Summary

Session archive rotation (reset / deleted / bak) renames the live .jsonl on disk but never emits a sessionTranscriptUpdate event, so the memory sync incremental path is left in the dark about the new archived path. The only way the index learns about the archive today is a full memory index --force reindex — which is what users actually have to do after a /reset to regain search over post-reset history.

• Problem: After a session reset, *.jsonl.reset.<iso> / *.jsonl.deleted.<iso> files land on disk but never enter chunks until a full reindex. memory_search returns empty for any query that would land on post-reset history for hours / days afterwards.
• Why it matters: Reset is a hot path (every /reset, every auto-reset, every gateway maintenance archive). Losing incremental index coverage on this path means memory_search quietly goes blind to user-visible session history, with no indication. Downstream work that depends on the archive showing up in the index (the archive content reader + visibility stem extractor landed in fix(memory): resolve archived transcript hits during session visibility filtering (follow-up to #76311, AI-assisted) #76452) is wasted until the file is actually pulled in.
• What changed: archiveFileOnDisk now emits a session transcript update after fs.renameSync, pointing at the new archived path. This is the exact same signal every other in-process session-file mutation already emits (appendMessage, compaction, tool-result rewrite, chat transcript inject, command execution, pi-embedded tool-result truncation, transcript append/truncate plumbing, session tool-result guard — eight existing emit points in src/ today). Archive was the sole mutation point that silently renamed without notifying subscribers.
• What did NOT change (scope boundary): Emission only. No change to indexing policy, the chokidar watch set, force-reindex behavior, visibility filtering, or any downstream subscriber. onSessionTranscriptUpdate listeners (memory sync, sessions-history HTTP, runtime subscriptions) already know how to route a plain { sessionFile } payload.

Change Type

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Refs Bug: session reset archives are not discoverable via sessions_history, breaking context recovery after reset #56131
• Follow-up to fix(memory): retry reindex on socket errors #76311 (socket retry, merged) and fix(memory): resolve archived transcript hits during session visibility filtering (follow-up to #76311, AI-assisted) #76452 (archive content + visibility stem extractor)
• This PR fixes a bug or regression

Root Cause

• Root cause: archiveFileOnDisk in src/gateway/session-transcript-files.fs.ts only calls fs.renameSync(filePath, archived) and returns. Memory-core's incremental session sync reacts to onSessionTranscriptUpdate events (see ensureSessionListener in extensions/memory-core/src/memory/manager-sync-ops.ts), and the chokidar file watcher set up there covers MEMORY.md + memory/ + extraPaths only — not the agent sessions directory. Without an event emit, the new archive path is invisible to both signalling channels, so sessionPendingFiles never sees it and shouldSyncSessionsForReindex only returns true if force=true (i.e. manual memory index --force).
• Missing detection / guardrail: There was no unit test asserting that archive rotation emits, so the asymmetry with the other eight emit sites was invisible at the contract layer.
• Contributing context: Archive is the newest of the session-file mutation points. The rest of the surface (append, compaction, etc.) grew up alongside the event bus and emits consistently; archive rotation was introduced separately and never got wired through.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/session-transcript-files.fs.archive-events.test.ts
• Scenario the test should lock in: For each archive reason (reset, deleted, bak), calling archiveFileOnDisk renames the file on disk and emits exactly one sessionTranscriptUpdate whose sessionFile matches the new archived path — and nothing else (no stale message / messageId payload).
• Why this is the smallest reliable guardrail: The contract is pure side-effect: a file rename + an event emit. A unit-level assertion is sufficient and cheap.
• Existing test that already covers this: None.
• If no new test is added, why not: N/A — 2 new cases added, exercising all three archive reasons.

User-visible / Behavior Changes

• After a session /reset, auto-reset, or maintenance archive, memory sync sees the new archive path on its next tick and indexes it incrementally — same timing as any other session mutation (appends already reach chunks in seconds). Users no longer need memory index --force to recover memory_search coverage of freshly archived transcripts.
• No config / env / defaults changed.

Diagram

Before (session reset):

  archiveFileOnDisk(filePath, "reset")
    └─ fs.renameSync(filePath, archived)
    └─ return archived                         ← NO event

  memory sync:
    ensureSessionListener → onSessionTranscriptUpdate  ← never fires for archived
    scheduleSessionDirty / sessionPendingFiles         ← never adds archived
    shouldSyncSessionsForReindex                       ← force=true only

  Result: archived file sits on disk, invisible to the incremental index
          until `memory index --force` runs.

After:

  archiveFileOnDisk(filePath, "reset")
    └─ fs.renameSync(filePath, archived)
    └─ emitSessionTranscriptUpdate({ sessionFile: archived })   ← NEW
    └─ return archived

  memory sync:
    onSessionTranscriptUpdate → scheduleSessionDirty(archived)
    → sessionPendingFiles.add(archived)
    → processSessionDeltaBatch → sessionsDirtyFiles.add(archived)
    → shouldSyncSessionsForReindex → true → targeted reindex

  Result: archive is indexed on the next memory sync tick,
          same signalling path as append / compaction / rewrite.

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No. The event carries only the new path. Listeners already gate their downstream actions against their own authorization model (the memory search visibility guard in filterMemorySearchHitsBySessionVisibility remains authoritative, as introduced by fix(memory): resolve archived transcript hits during session visibility filtering (follow-up to #76311, AI-assisted) #76452). Emitting for an archive path cannot leak information because the emit target is the same file that just landed on disk in its agent-owned session store.

Repro + Verification

Environment

• OS: Linux (container)
• Runtime: Node 24.14.0, pnpm 10.33.2
• Model/provider: any
• Config: default

Steps

1. Start a fresh session with memory source including sessions.
2. Append a few messages so the session file has real content indexed into chunks.
3. Trigger /reset (or any code path hitting archiveSessionTranscriptsForSession).
4. Inspect memory/ SQLite:
   • SELECT COUNT(*) FROM files WHERE path LIKE '%.jsonl.reset.%';
   • SELECT COUNT(*) FROM chunks WHERE path LIKE '%.jsonl.reset.%';

Before this PR: files/chunks never include the just-archived path (until memory index --force runs).

After this PR: next memory sync tick (within seconds) picks up the archive, files and chunks both reflect it, memory_search can surface post-reset history normally.

Evidence

Local validation on upstream main at this commit SHA (Linux, Node 24.14.0, pnpm 10.33.2):

• pnpm check — EXIT 0 (typecheck prod / oxlint / policy guards / import-cycle / temp-path guardrails all green)
• npx vitest run src/gateway/session-transcript-files.fs.archive-events.test.ts → 6 passed (2 cases × 3 gateway test environments: core / server / client)
• npx vitest run src/gateway/session-archive.imports.test.ts (existing) → 6 passed (no regression on the imports contract)
• Screenshot / recording — not applicable (no UI change)

Human Verification

• Verified scenarios:
  • reset archive emits exactly one update pointing at the new path; deleted and bak behave identically.
  • Payload contract matches the compaction-only emit pattern (sessionFile only, no stale message / messageId).
  • Imports graph under session-archive.imports.test.ts still holds (archive runtime not eagerly loaded by reply session module).
• Edge cases checked:
  • Rename failure from fs.renameSync throws before the emit, so no ghost event for a nonexistent path.
  • .bak reason participates in the emit identically (useful for the sessions.ts bak rotation flow at src/gateway/server-methods/sessions.ts:1952).
  • Listener set is process-local (src/sessions/transcript-events.ts), so the emit never escapes the process.
• What I did NOT verify: Full pnpm test sweep on upstream main at this exact SHA — only the targeted test files were exercised locally; CI will cover the rest on the PR.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes — strictly additive. Any listener that did not care about archive events simply receives an extra notification for a file path; listeners already handle any sessionFile payload.
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: A subscriber that explicitly wants to ignore archived paths (e.g., treats archive as opaque) now receives the emit.
  • Mitigation: Archived paths are already distinguishable by suffix (.jsonl.reset.<iso> / .jsonl.deleted.<iso> / .jsonl.bak.<iso>), and existing listeners treat sessionFile as an opaque string that downstream code classifies via the usage-counted helpers in src/config/sessions/artifacts.ts. The memory sync listener is the primary consumer and is the one that should receive this signal.
• Risk: A renameSync failure still fires the emit and points at a non-existent path.
  • Mitigation: fs.renameSync throws on failure, so execution never reaches the emit in that case. The test plan locks this in by asserting the file actually exists at the archived path when the emit fires.

AI-assisted PR: Prepared with Claude (Opus 4.7). Lightly tested — the underlying behavior is in active validation on a downstream fleet; upstream version is unit-test-validated locally in all three gateway test environments, and pnpm check is EXIT 0 on this SHA.