fix(agent): keep finalized SWM retirement locally authoritative

[branarakic]

Stack

• Base: fix(cli): allow bounded graceful shutdown budget #2030
• This PR: locally authoritative SWM retirement and reorg recovery
• Target: codex/rfc64-m1-shutdown-budget (stacked; not testnet-canary directly)

User impact

Before this PR, a graph-scoped assertion that reached VM remained visible in both VM and the user-facing SWM view. The first implementation hid it with a marker in syncable SWM metadata, which meant a peer-imported marker could incorrectly hide data on a receiver that had not materialized VM.

After this PR:

• finalized SWM snapshots remain physically present for receipt/reorg recovery;
• only a node-local, assertion-version-bound marker can hide a snapshot from shared-working-memory;
• peer-imported or stale markers cannot change local visibility;
• a newer SWM assertion reuses the graph safely because its version does not match the older local marker;
• canonical receipts remain transaction/root provenance only and never inherit mutable SWM assertion metadata;
• permanently invalidating a receipt clears the exact local marker and immediately re-exposes the retained SWM assertion;
• standalone handlers without the agent's shared SWM write-lock map cannot create retirement markers.

Before

sequenceDiagram
    participant Peer
    participant Receiver
    participant Store
    participant User

    Peer->>Receiver: Sync SWM data plus sharedMemoryFinalized marker
    Receiver->>Store: Persist data and syncable marker
    User->>Store: Query shared-working-memory
    Store-->>User: Snapshot hidden although local VM is absent

Loading

After

sequenceDiagram
    participant Peer
    participant Receiver
    participant Finalizer
    participant LocalTrust
    participant User

    Peer->>Receiver: Sync SWM data and peer metadata
    Receiver->>Receiver: Peer marker has no local authority
    User->>Receiver: Query shared-working-memory
    Receiver-->>User: Synced snapshot remains visible
    Finalizer->>Finalizer: Verify exact current head and content under shared KA lock
    Finalizer->>LocalTrust: Write local graph plus assertion-version marker
    User->>Receiver: Query shared-working-memory
    Receiver->>LocalTrust: Join marker to current durable head version
    Receiver-->>User: Locally finalized snapshot hidden
    Finalizer->>LocalTrust: Clear exact version after receipt invalidation
    Receiver-->>User: Recovery snapshot visible again

Loading

Safety properties

• A canonical receipt alone cannot promote or repair graph-scoped assertion metadata.
• The retirement marker is stored in LOCAL_TRUSTED_KA_CONTROLS_GRAPH, outside every syncable CG namespace.
• Visibility requires the local marker's graph and assertion version to match the current durable SWM head.
• Marker writes are disabled unless the handler receives the same per-KA lock map used by production SWM writers.
• Physical SWM data is retained for bounded reorg/replay recovery.

Verification

• Agent build (tsc, type tests, package-root): passed
• Query build: passed
• Graph-scoped finalization: 48 passed
• Real requester insertion / peer-marker visibility: 12 passed
• Query visibility and version matching: 122 passed
• Broader focused Agent lane: 117 passed before the final visibility-only assertion adjustment
• git diff --check: passed

Canary plan

After the stack is review-clean, deploy the exact child-stack commit only to the isolated local Publisher/Edge and isolated remote Core. Re-run the externally anchored five-graph M1 corpus, then a bounded soak. Production Core processes remain out of scope.