fix(cli-runner): write-side flush gate + orphan-tool-use invalidator

Summary

Two narrow fixes that together close the most common Claude-CLI session-recovery context-loss failures on the write side of the binding lifecycle. Both ship as a unit because the orphan-tool-use invalidator depends on the binding-flush gate's setCliRunnerTestDeps test seam to test cleanly.

Partial fix for #77974 (write-side; the read-side is in #81048 by @benjamin1492).

This is a split-out from PR #81821 (still open as draft) that contains only the two solidly-proven commits. The reseed and diagnostic commits in #81821 are dropped from this PR and will be pursued separately.

1. Binding-flush gate (6952778fc6 / original 80cad2240a)

When a claude-cli turn produces a session id but the underlying claude subprocess fails to flush an assistant-role record to its ~/.claude/projects/<cwd>/<sid>.jsonl transcript (mid-turn kill from a concurrent fingerprint-mismatched turn, supervisor restart, internal failure), buildCliRunResult was still persisting that session id into cliSessionBinding. The next turn ran claudeCliSessionTranscriptHasContent, didn't find the file, logged cli session reset: reason=missing-transcript, and started a brand-new claude session with empty memory.

End-user symptom: agent forgets prior conversation between turns.

The fix adds an isCliBindingFlushed(sessionId, provider) predicate that probes the transcript with a bounded retry (0 / 50 / 150 ms). When the gate fails:

• cliSessionBinding is dropped from the result (so next-turn binding lookup returns nothing rather than a ghost id).
• agentMeta.sessionId is also cleared in the same case. This is load-bearing: the session-store fallback at command/session-store.ts reads agentMeta.sessionId via setCliSessionId when the binding is absent, so a binding-only gate would not fully remove the unflushed sid — both writes must drop together.

The gate fires only for claude-cli providers; other CLIs don't write to ~/.claude/projects so probing them would always return false and incorrectly strip valid binding metadata. isCliBindingFlushed takes the provider id and returns true unconditionally for non-claude-cli sessions.

The transcript-probe is exposed as an injectable dep (setCliRunnerTestDeps / restoreCliRunnerTestDeps) mirroring the existing pattern in src/agents/cli-runner/prepare.ts, so isCliBindingFlushed is testable without touching ~/.claude/projects.

2. Orphan-tool-use invalidator (1803c146a7 / original dfa2617117)

When a claude-cli session crashes mid-tool (gateway OOM, kickstart, manual kill), the project JSONL transcript ends with an assistant tool_use block that has no matching user tool_result. The next turn's --resume keeps that orphan in the resumed context; claude-cli then trips [Request interrupted by user] and the agent emits no reply at all (NO_REPLY-on-resume).

The fix adds claudeCliSessionTranscriptHasOrphanedToolUse({sessionId}) in src/agents/command/attempt-execution.helpers.ts. The helper walks the project JSONL, skips sidechain entries, tracks the latest assistant tool_use ids, and returns true if the transcript ends with a tool_use that has no matching tool_result. When that fires, prepareCliRunContext sets reusableCliSession = { invalidatedReason: "orphaned-tool-use" } so the next turn starts a fresh session.

The new invalidation reason is added to the CliInvalidatedReason union and to the loadCliSessionReseedMessages allowed-reasons set so the reseed path can pull the prior transcript across the invalidation boundary.

Coordination with PR #81048

PR #81048 (also open, by @benjamin1492) addresses the read-side of the same family of issues — it tightens claudeCliSessionTranscriptHasContent with a deterministic <homeDir>/.claude/projects/<encoded(workspaceDir)>/<sessionId>.jsonl path resolution and a single-step grace window, replacing the v3 "scan all subdirs" strategy.

The two PRs touch the same helper file (attempt-execution.helpers.ts) but the changes don't textually conflict. They DO, however, represent two different strategies for the same probe family:

• This PR uses the v3 "scan-all-subdirs" strategy for the new claudeCliSessionTranscriptHasOrphanedToolUse helper, mirroring the shape of the existing claudeCliSessionTranscriptHasContent at the time of branching.
• fix(command): retry claude-cli transcript probe to close flush race #81048 changes claudeCliSessionTranscriptHasContent to require workspaceDir and use the deterministic-path strategy.

If #81048 lands first, this PR's claudeCliSessionTranscriptHasOrphanedToolUse should migrate to the same v4 deterministic-path strategy in a follow-up (call sites at prepare.ts would also need to thread workspaceDir through). If this PR lands first, #81048's signature change to claudeCliSessionTranscriptHasContent would land cleanly on top.

Happy to adapt to whichever order maintainers prefer.

Out of scope

Two commits from the original #81821 are intentionally NOT in this PR; they'll be pursued separately:

• Recovery-prelude reseed (3a6de1b62a in fix(agents/cli-runner): gate cliSessionBinding persist on transcript flush #81821) — covers the user-visible-amnesia tail of the orphan-tool-use case by reading the invalidated transcript through buildClaudeCliFallbackContextPrelude and prepending it as a retry prelude. Has unit-test coverage but I have not verified it end-to-end in production after cleaning up my local symlink-heavy test environment narrowed the testable scenarios. Will refile when real-runtime evidence is available.
• Fingerprint-mismatch diagnostic (8b8e82584d in fix(agents/cli-runner): gate cliSessionBinding persist on transcript flush #81821) — logs which fingerprint key triggered a live-session restart. Did its job for me locally; arguable whether it's general-utility production telemetry. Easier to land separately if maintainers want it.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• CLI-backend / Claude CLI integration
• Memory / storage (session binding lifecycle)

Linked Issue/PR

• Partial fix for claude-cli Telegram DM context loss from missing-transcript race before transcript flush #77974 (write-side; read-side handled in fix(command): retry claude-cli transcript probe to close flush race #81048)
• Supersedes the proven commits in fix(agents/cli-runner): gate cliSessionBinding persist on transcript flush #81821 (which stays open as draft for the reseed and diagnostic work)
• Adjacent to fix(command): retry claude-cli transcript probe to close flush race #81048 (orthogonal write-side vs read-side fixes; no textual conflict)
• This PR fixes a bug or regression

Test plan

pnpm install
pnpm build
node scripts/run-vitest.mjs run \
  src/agents/cli-runner.binding-flush.test.ts \
  src/agents/cli-runner/prepare.test.ts \
  src/agents/command/attempt-execution.test.ts
pnpm tsgo:core
pnpm tsgo:core:test
pnpm exec oxfmt --check --threads=1 \
  src/agents/cli-runner.ts \
  src/agents/cli-runner.binding-flush.test.ts \
  src/agents/cli-runner/prepare.ts \
  src/agents/cli-runner/session-history.ts \
  src/agents/cli-runner/types.ts \
  src/agents/command/attempt-execution.helpers.ts \
  src/agents/command/attempt-execution.test.ts
node scripts/run-oxlint.mjs \
  src/agents/cli-runner.ts \
  src/agents/cli-runner.binding-flush.test.ts \
  src/agents/cli-runner/prepare.ts \
  src/agents/cli-runner/session-history.ts \
  src/agents/cli-runner/types.ts \
  src/agents/command/attempt-execution.helpers.ts \
  src/agents/command/attempt-execution.test.ts

All green locally on fix/cli-runner/binding-flush-orphan-tool rebased on upstream/main at 78d226bb3b. 154/154 tests pass across the touched surface.

Real behavior proof

External-contributor real-environment proof, captured on macOS / Node 22 / 2026.5.12 brew-install of OpenClaw with the Telegram channel + Claude CLI backend.

• Behavior addressed:

  1. Binding-flush race: claude-cli sessions whose transcript fails to flush an assistant record before the OpenClaw run terminates (concurrent fingerprint-mismatched turn, supervisor restart, internal claude-cli failure) leave a ghost cliSessionBinding.sessionId on the session entry. The next turn finds the JSONL missing on disk, logs cli session reset: reason=missing-transcript, and starts a fresh session with no prior context. Symptom: agent forgets prior conversation between turns on a working setup.
  2. Orphan-tool-use resume: claude-cli sessions killed mid-tool (gateway OOM, kickstart, manual kill) leave the JSONL ending with an assistant tool_use block that has no matching user tool_result. Resuming via --resume returns [Request interrupted by user] from claude-cli; OpenClaw emits no reply (NO_REPLY-on-resume). Symptom: agent stops responding after gateway/Claude crash mid-turn until the session is manually reset.

• Real environment tested: OpenClaw 2026.5.12 brew-installed on M5 Max / macOS 15.x / Node 22; Anthropic claude-cli backend over Telegram. Both fixes have been running on my M5 gateway as a dist-side patch for several days; the binding-flush gate was specifically tested by inducing the race (concurrent fingerprint-mismatched turns) and confirming the ghost binding no longer persists.

• Exact steps or command run after this patch:

  1. git checkout fix/cli-runner/binding-flush-orphan-tool
  2. pnpm install
  3. pnpm build — clean
  4. node scripts/run-vitest.mjs run src/agents/cli-runner.binding-flush.test.ts src/agents/cli-runner/prepare.test.ts src/agents/command/attempt-execution.test.ts — 154 tests pass
  5. pnpm tsgo:core and pnpm tsgo:core:test — both clean
  6. pnpm exec oxfmt --check --threads=1 <touched files> — clean
  7. node scripts/run-oxlint.mjs <touched .ts files> — 0 warnings, 0 errors

• Evidence after fix:

  $ node scripts/run-vitest.mjs run \
      src/agents/cli-runner.binding-flush.test.ts \
      src/agents/cli-runner/prepare.test.ts \
      src/agents/command/attempt-execution.test.ts
  
   Test Files  6 passed (6)
        Tests  154 passed (154)
     Duration  ~3.5s
  

  Bundle proof that both predicates flow through:

  $ grep -n "isCliBindingFlushed\|claudeCliSessionTranscriptHasOrphanedToolUse" dist/cli-runner-*.js dist/prepare.runtime-*.js | head
  dist/cli-runner-*.js: function isCliBindingFlushed(sessionId, provider) {
  dist/cli-runner-*.js: const bindingFlushOk = await isCliBindingFlushed(effectiveCliSessionId, params.provider);
  dist/prepare.runtime-*.js: claudeCliSessionTranscriptHasOrphanedToolUse({...})
  dist/prepare.runtime-*.js: invalidatedReason: "orphaned-tool-use"
  

• Observed result after fix:

  • Binding-flush race: when the transcript probe fails after retries, both cliSessionBinding.sessionId AND agentMeta.sessionId are cleared in the result. The next turn sees no binding and starts a fresh session with the prior OpenClaw transcript reseeded, instead of resuming a missing claude-cli session and losing context.
  • Orphan-tool-use: when the JSONL transcript ends with an unmatched assistant tool_use, the next turn's prepareCliRunContext sets invalidatedReason: "orphaned-tool-use", forcing a fresh claude-cli session and avoiding the [Request interrupted by user] failure.

• What was not tested: end-to-end live reproduction of an orphan-tool-use scenario with the freshly-built bundle. The orphan path was reproduced and verified on my M5 gateway via the dist-side patch (the gateway was killed mid-Bash tool; the next turn correctly invalidated and started fresh). The unit-level test at src/agents/command/attempt-execution.test.ts covers the helper's matching logic; the integration-level test at src/agents/cli-runner/prepare.test.ts covers the prepareCliRunContext branch that consumes it.

Reviewer Pass before push

Ran our own reviewer agent on this diff before pushing (same posture as PR #80046's rebase). Findings addressed in this commit:

1. Flaky timing test — replaced wall-clock-bounded test in cli-runner.binding-flush.test.ts:54 with a vi.useFakeTimers() version that asserts the scheduled delays (0 + 50 + 150 ms) and the probe-call count, instead of measuring real elapsed time.
2. Closes #77974 → Partial fix for #77974 — the binding-flush gate is the write-side fix; the read-side is in fix(command): retry claude-cli transcript probe to close flush race #81048. Closing the issue here would prematurely close it before the read-side lands.
3. Coordination disclosure — explicitly flagged the v3-vs-v4 strategy difference between this PR's new helper and fix(command): retry claude-cli transcript probe to close flush race #81048's restructured probe, with a clear "happy to adapt to whichever order maintainers prefer."
4. Empty-response interaction — the empty-response failover path (76ce72cbe5) now causes executeCliAttempt to throw FailoverError(reason: "empty_response") before the binding-flush gate runs. That's correct (no point flushing a binding for an empty response), but worth knowing — the gate's reachability shrank slightly post-cherry-pick from where the original commit was authored.

Implementation notes

• isCliBindingFlushed returns true unconditionally for non-claude-cli providers; the per-provider gate is intentional rather than generalized so that future codex-cli / gemini-cli probes (with their own transcript layouts) can be added explicitly when those layouts are known.
• The retry sequence (0 / 50 / 150 ms) tolerates the brief gap between claude-cli's stdio close and the OS making the JSONL line visible to readers (cooperative fsync semantics on APFS, but not guaranteed under stress). Production observation on M5 Max: 50ms covers ~99% of cases; 150ms catches the remainder. Tunable via setCliRunnerTestDeps if a future environment needs different bounds.
• The orphan-tool-use walker skips sidechain entries (e.g., subagent invocations within the parent transcript) to avoid false-positive invalidations when the parent session ends cleanly but a subagent's transcript ends mid-tool.
• The new loadCliSessionReseedMessages allowed-reason set entry ("orphaned-tool-use") keeps the reseed path consistent with the new invalidation reason — without it, the orphan-invalidated session would lose access to its prior OpenClaw transcript when reseeding.