Summary

• Persist node agent.request offloaded image refs through the existing chat.send media helpers so session transcripts keep MediaPath / MediaPaths for iOS share and node gateway attachments.
• Thread the prepared user-turn transcript recorder through command ingress to both embedded and CLI runners, then add a block-aware fallback for early runtime failures.
• Keep before_agent_run hook blocks safe by marking the recorder blocked from the command result before fallback persistence runs.

Fixes #60339.

Verification

• node scripts/run-vitest.mjs src/gateway/server-node-events.test.ts
  • 82 passed
• OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/run-vitest.mjs src/agents/command/attempt-execution.cli.test.ts -t "forwards prepared user-turn transcript recorders"
  • 4 passed, 70 skipped
• OPENCLAW_VITEST_MAX_WORKERS=1 node scripts/run-vitest.mjs src/gateway/server-methods/chat.directive-tags.test.ts -t "preserves offloaded attachment media paths in transcript order"
  • 2 passed, 204 skipped
• node_modules\.bin\oxfmt.cmd --check src/agents/command/attempt-execution.cli.test.ts src/agents/command/attempt-execution.ts src/agents/command/types.ts src/gateway/server-methods/chat.ts src/gateway/server-node-events.runtime.ts src/gateway/server-node-events.test.ts src/gateway/server-node-events.ts
• git diff --check
• node scripts/run-oxlint.mjs src/agents/command/attempt-execution.cli.test.ts src/agents/command/attempt-execution.ts src/agents/command/types.ts src/gateway/server-methods/chat.ts src/gateway/server-node-events.runtime.ts src/gateway/server-node-events.test.ts src/gateway/server-node-events.ts
• node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-60339-core.tsbuildinfo
• node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-60339-core-test.tsbuildinfo
• python .agents\skills\autoreview\scripts\autoreview --mode branch --base origin/main --engine claude
  • clean, no accepted/actionable findings

Source / contract proof

• src/gateway/server-methods/chat.ts already owns the persistChatSendImages -> buildChatSendUserTurnMedia -> createUserTurnTranscriptRecorder flow for web/chat upload transcripts; this patch reuses that path instead of adding a node-only media persistence implementation.
• src/agents/embedded-agent-runner/run.ts propagates meta.error.kind: "hook_block" for before_agent_run blocks, and src/agents/command/delivery.ts preserves run meta in the command delivery result. The node fallback uses that established hook-block signal before calling persistFallback().
• src/sessions/user-turn-transcript.ts already skips fallback persistence when the recorder has been marked blocked, and short-circuits fallback after runtime persistence succeeds.

Real behavior proof

Behavior addressed: node/iOS share agent.request attachments that parse into offloadedRefs now persist transcript media metadata instead of leaving the media orphaned after the parser returns.

Real environment tested: Windows OpenClaw checkout, focused Vitest wrappers and static checks at head f026bae77d on fix/60339-node-offloaded-refs against origin/main 1a3ce7c2a8.

Exact steps or command run after this patch: commands listed in Verification were run after the final block-aware fallback change and before opening this PR.

Evidence after fix: server-node-events.test.ts covers parsed node offloaded refs being passed into persistChatSendImages, converted into recorder media, forwarded into agentCommandFromIngress, retried with a fresh per-request user idempotency key, and protected by fallback persistence. It also covers meta.error.kind: "hook_block" marking the recorder blocked before fallback runs. attempt-execution.cli.test.ts covers recorder forwarding to both embedded and CLI runners.

Observed result after fix: The prepared user-turn transcript recorder receives the raw user text plus persisted media paths, the agent still receives the parsed marker-bearing message, and fallback persistence cannot re-persist raw input for blocked runs.

What was not tested: No live iOS share extension or real node client attachment run was executed; this is source-level behavior proof with focused gateway and command-runner tests.