Summary

• Problem: when the active session transcript file (<id>.jsonl) is missing, three async readers — readRecentSessionMessagesAsync (called by chat.history in src/gateway/server-methods/chat.ts:1684), readSessionMessagesAsync (called by sessions-history HTTP in src/gateway/sessions-history-http.ts:171), and readSessionTitleFieldsFromTranscriptAsync (called by session listing/title in src/gateway/session-utils.ts:1888) — return an empty result even when a <id>.jsonl.reset.<UTC timestamp> archive sibling exists from a prior reset rotation.
• Why it matters: reset rotates <id>.jsonl to <id>.jsonl.reset.<ts> via an atomic rename and only re-creates the active file at the next write, so a session reset before the next read leaves the production async API surfacing nothing without raw-file forensics. References the discoverability concerns in Bug: session reset archives are not discoverable via sessions_history, breaking context recovery after reset #56131 / [Feature]: Script to restore session history archived by new daily-reset mechanism (introduced v2026.2+) #45003 / [Feature]: logical chat history across rolled sessions #43929 and complements the in-flight fix(session): fall back to reset archive in chat.history when primary transcript is missing #60409 (sync) / feat(session): add includeArchived to chat.history and sessions_history #73883 (explicit opt-in) PRs.
• What changed: one new helper findLatestResetArchiveAsync(candidatePaths) in src/gateway/session-transcript-files.fs.ts, one new internal helper findActiveOrLatestResetArchiveAsync in src/gateway/session-utils.fs.ts, and three async readers re-routed through it. Existing helper parseSessionArchiveTimestamp(entry, "reset") is reused for archive validation.
• What did NOT change (scope boundary): no protocol schema, no includeArchived API, no sessions_history tool schema, no session-memory hook, no session-logs skill, no sync paths, no findExistingTranscriptPath, no UI sidebar listing, no compaction checkpoint chains, no active+archive merging, no archive chain aggregation, no previousFragments / chained logical-history.

Change Type (select all)

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

Scope (select all touched areas)

• 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 [Feature]: logical chat history across rolled sessions #43929 [Feature]: Script to restore session history archived by new daily-reset mechanism (introduced v2026.2+) #45003 fix(session): fall back to reset archive in chat.history when primary transcript is missing #60409 feat(session): add includeArchived to chat.history and sessions_history #73883
• This PR fixes a bug or regression

Why Refs and not Fixes:

• Bug: session reset archives are not discoverable via sessions_history, breaking context recovery after reset #56131's primary reproducer involves a fresh active session that does receive new messages (e.g. exec-completion notifications) after a reset; the active candidate then exists and this PR's fallback intentionally is not triggered. The narrow slice covered here (active fully missing → newest archive returned) is necessary but not sufficient for Bug: session reset archives are not discoverable via sessions_history, breaking context recovery after reset #56131's stated acceptance criteria, which call for chain pointers and archived-fragment metadata.
• [Feature]: logical chat history across rolled sessions #43929 explicitly requires previousFragments and chained logical history, both deliberately out of scope here.
• [Feature]: Script to restore session history archived by new daily-reset mechanism (introduced v2026.2+) #45003 is a feature request for a recovery script; this PR removes part of the need but does not deliver the script.
• fix(session): fall back to reset archive in chat.history when primary transcript is missing #60409 (sync) and feat(session): add includeArchived to chat.history and sessions_history #73883 (explicit opt-in) are complementary by layer and surface; hunks do not overlap with this PR.

Root Cause (if applicable)

• Root cause: the candidate-resolution path used by all three async readers (findExistingTranscriptPath plus the inline resolveSessionTranscriptCandidates + existsSync block in readSessionTitleFieldsFromTranscriptAsync) only considers active <id>.jsonl candidates, even though archiveFileOnDisk (session-transcript-files.fs.ts) atomically renames the active to <id>.jsonl.reset.<ts> on reset.
• Missing detection / guardrail: cleanupArchivedSessionTranscripts already enumerates archives via parseSessionArchiveTimestamp(entry, "reset"), so core was maintaining the on-disk archive while the read side had no async-path equivalent. The sync side is being addressed in fix(session): fall back to reset archive in chat.history when primary transcript is missing #60409; this PR brings the async side to behavioral parity for the missing-active case only.
• Contributing context: the rename and the next active-write are not atomic from a reader's point of view, so a reader arriving in that gap saw nothing.

Regression Test Plan (if applicable)

• Coverage level: [x] Unit test
• Target file: src/gateway/session-utils.fs.test.ts — new describe("async archive fallback (missing-primary auto-fallback)") block.
• Invariants asserted (10 cases across the three async readers):
  • Active-wins: when active and archive both exist, the result is identical to today's output for the active file (no merging, archive ignored).
  • Missing-active fallback: when only an archive exists, the result is the archive's content (or its title fields).
  • Latest-only: when multiple .reset.<ts> archives exist, only the newest archive's content is returned (no chain aggregation).
  • Both-missing: when no candidate and no archive exist, the result is the existing default ([] or {firstUserMessage: null, lastMessagePreview: null}).
• Why this is the smallest reliable guardrail: each invariant maps directly to a public Acceptance Criterion in this PR and to a single branch in the new helper. The fixtures use formatSessionArchiveTimestamp(ms) for deterministic archive names, so the cases run in milliseconds and do not depend on Date.now() ordering.
• Existing coverage: none for the missing-primary async read path. archiveSessionTranscripts describe block elsewhere in the same file covers archive creation but not the read-side fallback.

User-visible / Behavior Changes

• When the active transcript is missing, async readers used by chat.history, sessions-history HTTP, and session listing/title now return the newest reset-archive content (or its title fields) instead of an empty result. Active-present behavior is intended to remain unchanged and is covered by the active-wins tests above. No new config knob, no schema change, no opt-in flag.

Diagram (if applicable)

N/A (single-step decision: "no active candidate exists → consult findLatestResetArchiveAsync → read that one path").

Security Impact (required)

• 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

Concrete invariant: the fallback uses the same candidate roots as resolveSessionTranscriptCandidates, only inspects sibling filenames in those candidate parent directories, and accepts only entries whose suffix passes the existing parseSessionArchiveTimestamp(entry, "reset") validation (already used by cleanupArchivedSessionTranscripts). No new directory roots, no caller-controlled path components.

Repro + Verification

Environment

• OS: Linux x86_64 (workspace dev environment)
• Runtime: Node 22, pnpm 10.33.2
• Model/provider: N/A (server-side fs path)
• Integration/channel (if any): N/A
• Relevant config: default ~/.openclaw layout / temp store under os.tmpdir() for tests

Steps

1. Start with no <id>.jsonl for sessionId in the sessions store; place a <id>.jsonl.reset.<UTC timestamp> sibling with content.
2. Call each of readRecentSessionMessagesAsync, readSessionMessagesAsync({mode:"full"}), and readSessionTitleFieldsFromTranscriptAsync.
3. Add an active <id>.jsonl with different content and repeat — assert active wins.
4. Add a second <id>.jsonl.reset.<later-ts> and re-remove the active file — assert only the newer archive is returned.

Expected

• Step 2: archive content / archive-derived title fields.
• Step 3: active content only (archive ignored).
• Step 4: newer archive content only (older archive bytes do not appear).

Actual

• Matches Expected. The 10 new cases in src/gateway/session-utils.fs.test.ts enforce all four invariants.

Evidence

• The new regression cases cover behavior that is absent from the PR base (current upstream/main HEAD bd6035d97707b7a62376a30de2eeae9579d56466): three of the new invariants (missing-active fallback, latest-archive-only, archive-derived title fields) exercise code paths that did not exist before this PR, so without these commits the asserted post-conditions could not be produced. I have not separately cherry-picked the new describe block onto the base commit to demonstrate a direct red run.
• Existing 71 cases in session-utils.fs.test.ts continue to pass alongside the 10 new cases (81 / 81 green locally on this branch). Adjacent regression: session-archive.imports.test.ts, session-transcript-key.test.ts, session-history-state.test.ts, sessions-history-http.revocation.test.ts, managed-image-attachments.test.ts, embedded-backend.test.ts all pass alongside.
• Real-behavior trace — see ## Real behavior proof section below.
• Screenshot/recording — N/A (server-side fs).
• Perf numbers — N/A (extra cost is one async readdir per deduped candidate parent dir, only on the missing-primary slow path; on the fast path the only added work is one extra await).

Real behavior proof

Captured 2026-05-17 against this branch rebased onto upstream/main 9616aa6e5a. Branch head SHA after rebase: 21bd4d3ed080c6cb75f725dbf14a527f22a6074b.

Behavior or issue addressed: when a session has been reset (<id>.jsonl atomically rotated to <id>.jsonl.reset.<UTC timestamp> with no active file recreated yet), the production async readers consumed by chat.history (readRecentSessionMessagesAsync), sessions-history HTTP (readSessionMessagesAsync + readSessionMessageCountAsync + readRecentSessionMessagesWithStatsAsync), and session listing/title (readSessionTitleFieldsFromTranscriptAsync) used to return an empty response. After this PR they auto-fall back to the newest reset-archive sibling.

Real environment tested: Linux x86_64 local dev workspace (Node v22, pnpm 11.1.0) running against this branch's actual source tree under src/gateway/. The fs state was constructed on the real local filesystem (/tmp/proof-archive-async-*), the readers were imported directly from src/gateway/session-utils.fs.ts via tsx (no mocks, no stubs, no vitest harness), and the sessions-history HTTP path was exercised with the real gateway HTTP server bound to a real loopback port.

Exact steps or command run after this patch:

1. Build the temp store: write a sessions.json and a sibling <id>.jsonl.reset.2026-05-01T00-00-00.000Z archive carrying two messages; do not create the active <id>.jsonl.
2. Import the production readers from src/gateway/session-utils.fs.ts directly and invoke each public async reader against that fs state.
3. Run the real gateway HTTP server in the regression test, archive the active via the production archiveSessionTranscripts helper (reset reason → atomic rename), and follow nextCursor pagination with real fetch calls.

Concrete commands run on the rebased branch:

$ node node_modules/.bin/tsx scripts/proof-archive-async-fallback.ts
$ CI=true pnpm test src/gateway/sessions-history-http.test.ts -- --reporter=verbose -t archive
$ CI=true pnpm test src/gateway/session-utils.fs.test.ts src/gateway/sessions-history-http.test.ts
$ CI=true pnpm check:changed

Evidence after fix:

Terminal transcript from the standalone fs probe (no test framework involved — actual production readers invoked against real disk state):

=== fs state (active missing, reset archive present) ===
tmpDir:           /tmp/proof-archive-async-kRSk7e
primary (active): sess-proof.jsonl
  exists?         false
archive (reset):  sess-proof.jsonl.reset.2026-05-01T00-00-00.000Z
  exists?         true
  size bytes:     197

=== ls of tmpDir ===
  sess-proof.jsonl.reset.2026-05-01T00-00-00.000Z
  sessions.json

=== production async readers (PR #76134 fallback path) ===
readRecentSessionMessagesAsync:
[
  { "role": "user",      "content": "archived: please summarize log A", "__openclaw": { "seq": 1 } },
  { "role": "assistant", "content": "archived: summary = A1, A2, A3",   "__openclaw": { "seq": 2 } }
]

readSessionMessagesAsync (mode=full):
[
  { "role": "user",      "content": "archived: please summarize log A", "__openclaw": { "seq": 1 } },
  { "role": "assistant", "content": "archived: summary = A1, A2, A3",   "__openclaw": { "seq": 2 } }
]

readSessionMessageCountAsync:
  2

readRecentSessionMessagesWithStatsAsync (totalMessages + seq):
{ "messages": [
    { "role": "user",      "content": "archived: please summarize log A", "__openclaw": { "seq": 1 } },
    { "role": "assistant", "content": "archived: summary = A1, A2, A3",   "__openclaw": { "seq": 2 } }
  ],
  "totalMessages": 2
}

readSessionTitleFieldsFromTranscriptAsync:
{ "firstUserMessage": "archived: please summarize log A",
  "lastMessagePreview": "archived: summary = A1, A2, A3" }

Live HTTP transcript from the regression scenario (real gateway HTTP server, archive-only state, real fetch cursor pagination):

GET /v1/sessions/agent:main:main/history?limit=2
  items     : ["second message","third message"]
  msg seqs  : [2, 3]
  hasMore   : true
  nextCursor: "2"

GET /v1/sessions/agent:main:main/history?limit=2&cursor=2
  items     : ["first message"]
  msg seqs  : [1]
  hasMore   : false
  nextCursor: undefined

The seq numbering 2,3 then 1 (rather than 1,2 then end) only holds if totalMessages is computed from the archived transcript (3 messages) rather than from the missing active file (0) — so the HTTP pagination path is observably routed through the new archive fallback in both the readers and the count helper.

Observed result after fix: every public async surface consumed by chat.history, sessions-history HTTP, and session listing/title returns the archived content against the archive-only fs state (recent.length=2, full.length=2, messageCount=2, stats.totalMessages=2, title.firstUserMsg="archived: please summarize log A"). Cursor pagination over the same archive-only state crosses both pages without skipping or duplicating, with stable __openclaw.seq numbering anchored to the archived totalMessages. Against the same fs state on the prior commit db66238880 the readers return [] / 0 / null title fields and the cursor pagination cannot reach the middle archive page.

What was not tested:

• Live chat.history round trip over the OpenClaw protocol seam against a real running OpenClaw gateway with a real client; the change sits below the protocol layer and the protocol shape is unchanged, so the public readers above are the contract surface.
• macOS / Windows filesystem semantics; the new code path only depends on fs.promises.readdir + fs.promises.stat, which are platform-stable.
• Active-file present case under live operator traffic; the active-wins boundary is covered by the regression suite (prefers active over archive when both exist cases) and the change deliberately does not touch the active path.

Human Verification (required)

• Verified scenarios:
  • pnpm test src/gateway/session-utils.fs.test.ts (rebased branch, locally) — 81 / 81 passed.
  • pnpm test for the consumer-side test files listed in Evidence — all passed.
  • pnpm check:changed — typecheck-all (tsgo), lint (oxlint), no-conflict-markers, no wildcard re-export drift, no runtime sidecar drift, no import cycles, all green locally.
• Edge cases checked:
  • Empty candidate list → findLatestResetArchiveAsync returns null.
  • readdir failure on a candidate directory → swallowed by .catch(() => []), fallback continues with other deduped candidate dirs.
  • Filename starts with <basename>. but is not a .reset.<ts> archive → rejected by parseSessionArchiveTimestamp returning null.
  • Distinct timestamps → strict > keeps the newer one; same-timestamp edge case is not relied on by any test.
• What I did not verify:
  • Live chat.history end-to-end (the change is below the protocol seam; the protocol is unchanged so the unit tests on the three readers are the contract).
  • macOS / Windows behavior; the change relies only on fs.promises.readdir + fs.promises.stat semantics that are stable across platforms.
• Note on local vs Testbox: I am an external contributor without Blacksmith/Testbox access, so the broad gates above ran locally rather than on Testbox. The full pnpm test:changed fan-out also surfaced 8 unrelated upstream-pre-existing failures in src/agents/pi-embedded-runner/compact.hooks.test.ts (its vi.doMock("../session-write-lock.js", ...) factory does not list resolveSessionWriteLockAcquireTimeoutMs, which was added by upstream commit f7ed29e118 "fix: thread session write-lock timeout config"). I confirmed those failures reproduce on bare bd6035d97707b7a62376a30de2eeae9579d56466 without this PR's commits.

Review Conversations

• I will reply to or resolve every bot review conversation I address in this PR.
• I will leave unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes — async readers return strictly more (a previously-empty result becomes the archive's content) only when no active exists; active-present behavior is intended to remain unchanged and is covered by the active-wins tests.
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: a reader that arrives during the rename window could see archive content one read and active content the next.
  • Mitigation: this PR does not change the rename ordering; it only adds a fallback for the missing-active case. If a writer transitions the active back into existence between two reads, the second read picks the active (existing behavior).
• Risk: a corrupt archive timestamp suffix could be selected as "newest".
  • Mitigation: parseSessionArchiveTimestamp validates the suffix against ARCHIVE_TIMESTAMP_RE and returns null for non-matching suffixes; rogue entries are skipped before sorting.
• Risk: extra readdir cost on the missing-primary path.
  • Mitigation: a seenDirs set deduplicates across overlapping candidate parent directories; readdir errors are swallowed and the fallback yields no archive (caller's existing default applies).