Headless resume: is it planned, would you take a PR, and is a mid-turn jsonl.zstd log a legal restore target?

[lmcmz]

TL;DR — dsh --profile headless cannot name or resume its session, so an unattended run that gets terminated is unrecoverable. I wrote a plugin that fixes it using only published API, and measured the crash behaviour. Three questions at the bottom, plus one thing that looks like a bug.

The gap

agents.create({ sessionId: SessionId(`session-${randomUUID()}`), … })

The id is minted inside run(), and headless takes no flag but --help — so the transcript lands on disk under an id nobody wrote down. Our runs are hours long on a host that SIGTERMs on every deploy.

Everything needed is already there: ctx.agents.resume() is published API and the JSONL persistence backend is already mounted in the headless bundle. Only the runner couldn't reach them. So — a --patch overlay that disables the headless-runner row and inserts a replacement:

https://github.com/Outblock/dsh-headless-resumable — MIT, tagged dsh-plugin, no fork, no vendoring.

(CONTRIBUTING says you can't take external PRs at the moment. I asked before reading it — sorry. A plugin it is.)

It works, including the case I expected to be hard

0.1.0-rc.6, real runs killed at randomised points and relaunched through ctx.agents.resume():

• SIGKILL mid-tool-call: 3/3 resumed and completed, with no work redone. Last stored seq → resumed pick-up was 322→327, 285→289, 336→340; the gaps are your synthetic tool/step/turn closers over the torn tail.
• Once on a real 38-minute agent build: one session directory throughout, deliverable produced, and pre-kill work not repeated — the input documents were read 5 times before the kill and 0 times after.

Thank you for that. The persistence README's "Durability and crash semantics" section is why we knew where to look, and it held up.

One thing looks like a bug, not a missing feature

In runProfile:

process.on("SIGTERM", () => { interrupt(0)   })
process.on("SIGINT",  () => { interrupt(130) })

SIGINT correctly yields 130. SIGTERM yields 0 — so under Kubernetes, systemd, ECS, Fly or plain docker stop, a headless run that was killed reports success, and a caller checking the exit code cannot tell it from a completed one.

A plugin can only work around this by removing your listener at mount time (Node dispatches signal listeners in registration order and yours is registered first), which is a hack worth reporting rather than living with. Happy to split it into its own thread if that is easier to triage.

Questions

1. Is headless resume planned? I would rather use yours than maintain a replacement row. (dsh --help shows --profile tui --resume <session> in its examples but no tui bundle ships in rc.6, so I could not tell whether that is a plan or just an argument-passthrough example.)
2. May we depend on the persistence README's crash contract — fsync per durable append, incomplete trailing frame truncated and re-encoded with synthetic closers, a defect at or before the last committed turn/end rejecting as corruption?
3. Is a log that ends mid-turn a legal restore target, or is that recovery best-effort? My measurements say it restores; I would like to know whether I am allowed to rely on it.

[sylvesterkaczmarek]

Current main still doesn't expose headless resume. The tui --resume line is explicitly just an argument-passthrough example, so your plugin is filling a real gap rather than duplicating a hidden CLI feature.

[weijiafu14]

Two independent data points for your "is the machinery actually reachable" question — from the other side of the plugin fence (we maintain pi2dsh, a Pi ABI compatibility engine; different problem, same seams):

1. The resume family works cross-process through published API — we've verified an adjacent path end-to-end. In our subagents acceptance run, a second OS process reopens a session created by the first one (by its archive identity, through the public sessions API our bridge projects) and continues it: same session log, grown from one turn to two, asserted from the persisted jsonl. Different entry point than your agents.resume() overlay, same underlying property: nothing below the runner refuses a resume from a fresh process. Your finding that only the headless runner couldn't reach it matches what we mapped.

2. We'd been telling people headless resume flatly doesn't exist (e.g. in 你应该知道 dsh 和 claude/codex/cursor 当前有哪些会影响生产的小区别 #1076: no headless --resume, plan around it) — your overlay changes that landscape, and it's the honest kind of fix: published API, no fork, patch row swap. We'll point people at it as "community overlay exists" rather than "can't be done" from now on. One caveat we'll keep attached, and you'd probably co-sign: a --patch that replaces a first-party runner row rides on an unversioned seam — worth pinning the DSH version range you've tested in the README, since runner internals moved between recent lines (we've had to capability-probe rather than version-probe for similar reasons).

On your mid-turn question I have no evidence either way — the crash-point behavior you measured is more than anyone else has published, so I'll defer to your data. Haven't run your plugin myself; the above is corroboration of the seams, not a review.

[PerryLink]

注：本条评论原文因编码问题曾显示为乱码，已重建为可读版（2026-09-07）。

这个场景我做过大量实测，headless resume 在恢复面上的答案（来自 dsh-checkpoint-rewind 与 dsh-claude-move 的实践）：

• dsh-checkpoint-rewind 就是「快照 + 回退 + 恢复」的组合：git 快照 + fork/seed 子会话，支持 headless 触发/回退，回退后验证「中途断点」可续，且不会丢失 crash 前的状态
• dsh-claude-move 做跨生态迁移（Claude Code/Codex/OpenCode/Hermes → DSH），恢复时带来源会话的上下文

关于「mid-turn jsonl.zstd 恢复合法性」：日志是按帧写入的，torn frame 会被恢复层拒绝（即 fail-closed），mid-turn 中断建议走 fork/seed 子会话续接——这点与 sylvesterkaczmarek 的结论一致。

[sylvesterkaczmarek]

Small update after checking current master (0a53fb55, released as dsh@0.1.2-alpha.2):

• headless still creates a fresh random session with agents.create(), so there is still no first-party headless resume path;
• SIGTERM -> 0 is still present, but the adjacent source comment now explicitly documents that as intentional supervisor-stop semantics applied across surfaces.

So I would no longer treat the SIGTERM exit code as an accidental implementation bug. Changing it would be a deliberate CLI/process-exit semantics change.

CONTRIBUTING.md also still says external PRs are not currently accepted, so for contributors the plugin/Discussion route remains the practical path.