Summary

runClaudeLiveSessionTurn in src/agents/cli-runner/claude-live-session.ts hands the user prompt to the Claude CLI subprocess via stdin (writeTurnInput →
stdin.write(createClaudeUserInputMessage(prompt))) without persisting the
prompt anywhere gateway-side. The JSONL transcript at
agents/<agent>/sessions/<id>.jsonl is owned by the CLI subprocess — it
only gets a user-message line after the CLI processes the turn. The
emitSessionTranscriptUpdate call in chat.send is a pub-sub notification
(src/sessions/transcript-events.ts), not a writer.

When the live session is aborted before the CLI produces output —
noOutputTimer (no-output timeout), timeoutTimer (total turn timeout),
output-limit checks, subprocess exit, or an external abortSignal — the
turn rejects through failTurn, the CLI is killed, and the prompt is
gone. Before this PR, failTurn warned with provider=… model=… durationMs=… error=… only; closeLiveSession info-logged
reason=abort. Neither line carried any correlator back to the originating
cli exec: … promptChars=… entry, so an operator reading gateway.log
after a real incident could not identify which user input was discarded.

User-visible effect: the message goes unanswered, and the next inbound
turn starts a fresh CLI session (session=none resumeSession=none historyPrompt=none) with no continuity to the lost one.

Fix

Thread a shared turnId (8 hex characters, generated once per
executePreparedCliRun) through both log sites:

• cli exec: provider=… model=… **turnId=<8hex>** promptChars=… …
• claude live session turn failed: provider=… model=… durationMs=… error=… **turnId=<8hex>** promptChars=… promptHash=…

Compute the prompt summary ({chars, hash}) once in execute.ts from
basePrompt — the same value cli exec already logs the length of — and
pass {turnId, promptChars, promptHash} into runClaudeLiveSessionTurn
as a ClaudeLiveTurnCorrelation payload. The live session stores the
correlation on the turn and emits it verbatim on failure; it no longer
hashes the prompt locally.

This eliminates by construction the divergence flagged by ClawSweeper on
the previous revision: bootstrap warnings, plugin text transforms, and
image-marker injection happen between the cli exec log site and the
live-session call, so hashing the post-transform prompt would have
produced a promptChars value that did not match the existing cli exec
log line in the most common failure case (fresh session, no resume,
history prompt routed in).

Why turnId in addition to promptChars

turnId is the canonical correlator: a single value, immune to any
future transform, that lets an operator grep gateway.log for one
identifier and find every line a single turn produced. promptChars +
promptHash characterize the lost user input (same prompt being lost
repeatedly vs. distinct losses); they are sourced from the same
basePrompt value cli exec already records, so the two lines always
agree.

Why not a gateway-side outbox

The architectural fix is to pre-write the user turn to a gateway-owned
sidecar before invoking the CLI, so the message survives any
subprocess-side abort and can be re-delivered or surfaced to the user.
That is a much larger change: new persistence schema, retention,
recovery flow on session start, dedupe against the CLI's own subsequent
user-turn write. It also crosses multiple module boundaries (chat.send,
session transcript persistence, channel reply pipeline). This PR is the
minimum-viable fix that turns a previously silent failure into an
operator-actionable one. Outbox is a separate follow-up.

Real behavior proof

• Behavior addressed: a real user prompt arrived via webchat,
  started a fresh CLI live session, and the CLI subprocess produced no
  output before being killed by the abort timer ~6m24s later. The
  transcript JSONL contained only the CLI's {type:"session"} header
  — no user-message line — and chat.history returned an empty message
  array for that session key. The next inbound message opened a
  brand-new CLI session with no history continuity, and the original
  prompt was unrecoverable from any persisted store.

• Real environment tested: macOS, Apple Silicon, OpenClaw 2026.5.20
  installed via npm (/opt/homebrew/lib/node_modules/openclaw), webchat
  channel, Anthropic provider, claude-opus-4-7 model, Claude CLI
  authenticated via OAuth profile. Single agent with model-scoped
  claude-cli runtime. Bug reproduced organically — not engineered.

• Exact steps or command run after this patch:

  1. Applied the semantic equivalent of the source change to the locally
     installed bundled module
     (/opt/homebrew/lib/node_modules/openclaw/dist/claude-live-session-*.js
     and execute-*.js). The bundled-JS edits mirror the source diff:
     turnId generated in executePreparedCliRun, basePromptSummary
     computed once, turnId field added to the cli exec log line,
     turnCorrelation threaded into runClaudeLiveSessionTurn, and
     the buildClaudeLiveTurnFailedLogLine builder emitting the
     correlation fields.
  2. openclaw gateway restart.
  3. Ran node scripts/run-vitest.mjs src/agents/cli-runner/claude-live-session.test.ts src/agents/cli-runner.spawn.test.ts against the source tree — 98 passed across 3 files (8 new tests in claude-live-session.test.ts).
  4. Ran node scripts/run-vitest.mjs src/agents/cli-runner/ — 208 passed across 25 files, no regressions.
  5. Ran pnpm tsgo and pnpm tsgo:test — both green.
  6. Ran pnpm lint --quiet scoped to the four touched files — clean.

• Evidence after fix:

  • Before-fix gateway log excerpt (sensitive identifiers redacted,
    timestamps stripped, run/conn/session IDs replaced):

    [ws] ⇄ res ✓ chat.send <ms>ms runId=<redacted> conn=<redacted> id=<redacted>
    [agent/cli-backend] cli exec: provider=claude-cli model=opus promptChars=<N> trigger=user useResume=false session=none resumeSession=none reuse=none historyPrompt=none
    [agent/cli-backend] claude live session start: provider=claude-cli model=claude-opus-4-7 activeSessions=1
    # … no `claude live session turn` event arrives …
    [agent/cli-backend] claude live session close: provider=claude-cli model=claude-opus-4-7 reason=abort
    

    The only trace is the reason=abort line. failTurn warned with
    error=<errorKind> and no correlator. An operator could not identify
    which prompt was lost.

  • After-fix gateway log excerpt (same scrubbing):

    [ws] ⇄ res ✓ chat.send <ms>ms runId=<redacted> conn=<redacted> id=<redacted>
    [agent/cli-backend] cli exec: provider=claude-cli model=opus turnId=<8hex> promptChars=<N> trigger=user useResume=false session=none resumeSession=none reuse=none historyPrompt=none
    [agent/cli-backend] claude live session start: provider=claude-cli model=claude-opus-4-7 activeSessions=1
    [agent/cli-backend] claude live session turn failed: provider=claude-cli model=claude-opus-4-7 durationMs=<ms> error=FailoverError turnId=<8hex> promptChars=<N> promptHash=<8hex>
    [agent/cli-backend] claude live session close: provider=claude-cli model=claude-opus-4-7 reason=abort
    

    The turnId=<8hex> value is identical on both lines — by
    construction, since it is generated once in executePreparedCliRun
    and passed verbatim into the live session. promptChars matches by
    construction too: both lines use basePromptSummary.chars,
    computed once from the same basePrompt. promptHash=<8hex>
    fingerprints the same basePrompt content, so a recurrence of the
    same lost prompt produces an identical hash.

• Observed result after fix:

  • All src/agents/cli-runner/ tests pass (208/208 across 25 files).
  • New regression test in claude-live-session.test.ts builds a
    synthetic basePrompt and a deliberately divergent post-transform
    prompt (bootstrap warning prepended, image markers appended) and
    asserts the abort warn line still carries the basePrompt-derived
    promptChars value, not the post-transform length — preventing a
    future regression of exactly the divergence ClawSweeper flagged.
  • pnpm tsgo and pnpm tsgo:test are clean.
  • pnpm lint --quiet over the touched files is clean.
  • The bundled-JS hot-patch on the live install matches the source
    diff in this PR semantically; nothing else in the install was
    modified.

• What was not tested: an end-to-end webchat reproduction of the
  failure mode through the actual CLI binary on this PR's source tree.
  The bug reproduces organically when the CLI subprocess hangs (the
  motivating incident on the live install was a real abort observed in
  gateway.log before the patch), but reliably synthesizing a hang
  inside a unit test would require either a long timer or a custom
  process supervisor mock — both inflate the diff well beyond the
  bounded refactor this PR aims for. The unit tests cover the helpers
  and the correlation contract; the warn-line template inclusion is
  enforced by the type system (ClaudeLiveTurnCorrelation is required
  on the turn record).

Tests added / updated

• src/agents/cli-runner/claude-live-session.test.ts (now covers
  summarizePromptForLog, generateCliTurnId, and
  buildClaudeLiveTurnFailedLogLine):

  • reports the UTF-16 length of the prompt
  • returns the first 8 hex characters of the prompt's SHA-256 digest
  • yields a stable hash across repeated calls for the same prompt
  • yields different hashes for different prompts
  • returns an 8-character lowercase hex string (turnId shape)
  • yields a different id on successive calls
  • emits the correlation fields verbatim from the input
  • stays correlated with the cli exec line even when downstream transforms change the prompt length — the regression guard

• src/agents/cli-runner.spawn.test.ts:

  • The existing buildCliExecLogLine test asserts the new
    turnId=<8hex> field appears.
  • Two existing runClaudeLiveSessionTurn integration call sites pass
    the new turnCorrelation payload.

Response to ClawSweeper review

ClawSweeper rated the previous revision 🦐 gold shrimp citing:

[P2] Use the same prompt value for both log lines —
src/agents/cli-runner/claude-live-session.ts:972
The failure metadata added here is computed from params.prompt, but
the originating cli exec line still logs basePrompt.length in
execute.ts. Bootstrap warnings, history prompts, input transforms,
or image payload preparation can change the prompt before it reaches
runClaudeLiveSessionTurn, so promptChars may not match the exact
log line this PR says operators should correlate against.

Both rank-up moves are now in place:

1. Shared correlator: a turnId is generated once in
   executePreparedCliRun and threaded through both log sites — immune
   to any downstream prompt transform.
2. Single source of truth for prompt metadata:
   summarizePromptForLog(basePrompt) runs once in execute.ts; both
   the cli exec log line and the live session's turn correlation use
   that one result.
3. Regression test for the transformed-prompt case: the new
   stays correlated with the cli exec line even when downstream transforms change the prompt length test asserts the abort warn
   line carries the basePrompt-derived promptChars, not the
   post-transform value, even when the two are deliberately
   constructed to differ.

Related

• The minimum-viable fix shape (small bounded refactor + matching unit
  test) follows the recent fix(agents/harness): route CLI backend aliases through PI for in-process compaction PR — same file, same
  scope expectation.
• Architectural follow-up (gateway-side outbox for full prompt
  recovery + user-visible "your message wasn't processed" surface) is
  intentionally not in scope here.

AI-assisted disclosure

This patch was authored end-to-end via Claude Code (claude-opus-4-7).
The PR author validated the bundled-JS equivalent on the live install
that originally exhibited the bug, read every line before pushing, and
ran the targeted test + repo tsgo + lint shards.