Restore running commands: non-idempotent commands (e.g. claude --resume X --fork-session) mint new state on every restart

[artfaal]

Context. Heavy user of "Restore running commands on restart" with Claude Code sessions; I also maintain a tool that maps agterm sessions to Claude sessions via tree --json foreground argv.

Problem. Restore re-runs the captured foreground command verbatim. Perfect for idempotent commands (claude --resume <uuid> reattaches the same session every time), but it breaks down for:

1. Non-idempotent commands. claude --resume <uuid> --fork-session creates a new Claude session (new uuid) each run. Every agterm restart mints another fork: the session I was actually working in (yesterday's fork child) is not resumed, and transcripts accumulate near-identical copies. Real data point: after a couple of restarts I found 6 sessions with the same title, 3 of them created in the same second — the restart moment.
2. Commands with an interactive target. claude -r / bare claude --resume capture no session id; restore lands in the interactive picker, not in the session that was open.

Not agterm's fault — it can't know which commands are idempotent. But agterm is the only layer where the user (or tooling) could fix it.

Ideas (the first seems cleanest):

• Per-session restore-command override: agtermctl session restore-command set|clear <cmd> + read side in tree --json. On restart the override wins over the captured foreground. Agent tooling could then register the idempotent form — e.g. a Claude Code SessionStart hook knows the real current uuid, so the override would stay accurate even for forked or picker-resumed sessions.
• Restore rules in settings: pattern → skip / rewrite (e.g. "never re-run commands containing --fork-session").
• At minimum, a per-session opt-out of command restore (restore clear exists, but it's global and one-shot).

Happy to expand or test builds.

[umputun]

built and merged in #271, shipping in the next release.

the read was right on both counts: capture and restore live entirely inside the app, so no external process can rewrite the seam, and a static wrapper can't help either because with --fork-session the child uuid only exists after the fork runs. Idea 1 in the narrow form is what got built.

session.restore pins a shell line per session, per pane:

agtermctl session restore "claude --resume $sid" --target "$AGTERM_SESSION_ID" --pane-id "$AGTERM_PANE_ID"
agtermctl session restore --none     # this pane restores nothing
agtermctl session restore --clear    # back to auto-capture

it's a tri-state on one field: absent = today's auto-capture, "" = plain shell, "cmd" = run it. So idea 3, the per-session opt-out, falls out of --none as expected. Read back on tree as restoreCommand / splitRestoreCommand, so a script can record and restore what it set.

timing is as described: write-now, consume-next-launch. Setting it never touches the running session, and the pin is sticky, it fires again on every launch until cleared. A SessionStart hook rewrites it each start, so the next restart reattaches instead of forking. The bundled agent skill has the hook recipe, reading session_id from the hook's stdin with a guard against pinning an empty value.

two details that came out of building it and aren't obvious from the proposal:

the override obeys the restoreRunningCommand setting but bypasses restore-denylist.conf. The denylist is a basename heuristic for blind capture; an override names its command deliberately, so it should win. Setting a pin while the toggle is off returns ok with a note saying it won't run.

a split hidden at quit drops its pin rather than keeping it. A hidden split comes back with no right pane and is never rebuilt, so a kept pin would be a value tree reports that no write can clear, and it would later fire into an unrelated new split.

idea 2 stayed out for the reason given earlier, the skip half already exists as the denylist.

the offer to test builds is welcome, the edge worth hammering is a fork chain over several restarts.