Add `pty run --permanent` (and `--cleanup-on-clean-exit`) so spawners stop reimplementing the supervisor contract

[schickling-assistant]

Problem

Today, every consumer that wants a pty session to survive a host/supervisor restart re-derives the same contract by hand:

1. Pass --tag strategy=permanent at spawn time, knowing the supervisor reads that tag (dist/supervisor.js — evaluateSession / loadState).
2. After the leaf process exits, run a post-spawn cleanup that conditionally calls pty rm <name> if the exit was clean — otherwise the supervisor's 1s-backoff restart loop fires (MAX_RESTARTS=5 in RESTART_WINDOW_MS=60_000) and the session lands at FAILED with stale metadata.

Both halves are load-bearing, but neither is discoverable from pty run --help. Spawners learn the contract by reading supervisor source, and each consumer ends up reimplementing the same shell snippet:

pty run -a --name "$name" --tag strategy=permanent -- <leaf>
rc=$?
if ! pty list --json | jq -e --arg n "$name" '.[] | select(.name==$n and .status=="running")' >/dev/null; then
  pty rm "$name" || true
fi
exit "$rc"

Concrete reimplementations I'm aware of:

• Shell wrappers (cl1/co1/oc/pi style agent launchers in schickling/dotfiles) — the snippet above, generated in nix.
• A web UI / pty manager that spawns sessions via the in-process client — needs the same strategy=permanent tag plus a post-exit pty.rm() in its session-exit watcher.

Each spawner racing the supervisor on cleanup is a known footgun: if the supervisor's fs-watcher fires scheduleRestart before the wrapper checks pty list --json, one spurious respawn happens, then the wrapper removes the metadata anyway. Bounded, but messy.

Proposed flags

Two small additions to pty run:

--permanent

Equivalent to --tag strategy=permanent today, but as a first-class flag so consumers stop string-matching the tag in their own code (forge has to read the tag back; wrappers emit it as bash). Promoting it to a flag lets pty own the contract — including the name. Future-proof: if the tag schema ever changes (strategy=permanent → strategy=managed), only pty changes.

--cleanup-on-clean-exit

When the leaf process exits with code 0, the supervisor itself removes the session's metadata (no client-side race). When the leaf exits non-zero, leaves the metadata alone — preserving the existing crash-→-restart-loop behavior.

Both flags can be used independently. The common case is both together: "I want this to come back on reboot, AND I want it to truly disappear when the user explicitly quits."

Why supervisor-side

Today the cleanup races the supervisor's scheduleRestart (1s backoff). Moving it into the supervisor itself — running atomically with the exit-detection path — removes the race window entirely.

It also lets pty centralize the "clean exit vs crash" distinction. Right now supervisor doesn't distinguish exit codes (supervisor.js:163-165); the semantic only lives in client code that races to remove metadata before backoff fires.

Implementation sketch

• New tags written alongside strategy=permanent: strategy.cleanup-on-clean-exit=true (or fold into one tag value: strategy=permanent-ephemeral-on-clean-exit).
• Supervisor's evaluateSession reads the new tag/value and, in the isExited branch, checks the recorded exit code:
  • exit 0 + cleanup-on-clean-exit → cleanupAll (skip scheduleRestart).
  • non-zero → existing scheduleRestart path.
• pty run --permanent and pty run --cleanup-on-clean-exit set the corresponding tags. Internal Daemon already records exitedAt and the exit code via session_exit events, so no new wire data is needed.

Backwards compatibility

• Existing --tag strategy=permanent users keep working (the flag is just sugar).
• Existing session metadata without the new tag retains today's "always restart on exit" semantic.
• No projection-layer change.

Net effect

Three independent reimplementations of "spawn permanent + clean up on clean exit" collapse to pty run --permanent --cleanup-on-clean-exit -- <leaf>. Supervisor owns the lifecycle instead of every spawner racing it.

Happy to send a PR if the design lands.

Posted on behalf of @schickling

field	value
agent_name	🌈 cl2-opal
agent_session_id	7df4e531-dcfd-4417-808c-06e7c504fe46
agent_tool	Claude Code
agent_tool_version	2.1.139
agent_runtime	Claude Code 2.1.139
agent_model	claude-opus-4-7
worktree	dotfiles/schickling-assistant/2026-05-22-ai-bundle-followup
machine	dev3
tooling_profile	dotfiles@unknown-dirty

[myobie]

Yes, send the PR — both flags as proposed.

The design is right: keep --tag strategy=permanent working for backwards compatibility, promote --permanent as the discoverable flag so pty owns the contract name, and move the clean-exit cleanup into the supervisor so it can't race the scheduleRestart backoff. Centralizing the "clean exit vs crash" distinction supervisor-side is the load-bearing semantic, not just an ergonomic flag — it eliminates a class of bug rather than papering over it.

Two notes for the PR:

• Independence: I want to be able to use --permanent without --cleanup-on-clean-exit (the current "outlives spawner forever" semantic) AND --cleanup-on-clean-exit without --permanent (one-shot script that should clean up its own metadata on exit 0 even though it wasn't pinned permanent). Your "both flags can be used independently" line already covers this; just confirming.
• Backwards compat: the existing pty.toml strategy = "permanent" use across my own agent stack must keep working unchanged. Sounds like that's already the plan.

Looking forward to the PR.

[myobie]

Direction is accepted; here's how it reconciles with where main landed since this was filed.

Big picture change. PR #44 replaced the long-running supervisor with a stateless pty gc reconciliation invoked from cron/launchd (default StartInterval=30). No more src/supervisor.ts, evaluateSession, scheduleRestart, or MAX_RESTARTS. Same contract from the outside — strategy=permanent sessions are restarted; the mechanism is now a periodic sweep instead of a fs-watcher + backoff loop.

Adapted semantics:

• pty run --permanent — still sugar for --tag strategy=permanent. Same rationale as your proposal (pty owns the contract, spawners stop string-matching the tag). Direct 1:1.
• pty run --cleanup-on-clean-exit — moves from "supervisor detects exit + inspects code" to "gc detects gone + inspects last exit code". Implementation:
  1. Daemon already records exitedAt and appends a session_exit event with the exit code (src/events.ts).
  2. New tag strategy.cleanup-on-clean-exit=true (or the folded form strategy=permanent-unless-clean — either works; the folded form is one fewer tag to reason about).
  3. gc step 2 (respawn permanent) reads the tag + the last session_exit event's exit code. If tag set AND exit code === 0 → cleanupAll (fall through to the step-3 sweep). If tag set AND non-zero → respawn as today.
  4. pty run --permanent and pty run --cleanup-on-clean-exit set the corresponding tags at spawn time.

Race gone by construction. The client-side race with scheduleRestart that motivated this proposal doesn't exist under gc — gc is single-invocation, single-threaded, and the tag semantic is the only source of truth. Wrappers can drop their post-exit pty rm calls entirely.

Backwards compat matches your proposal — existing --tag strategy=permanent users unaffected; existing metadata without the new tag keeps today's "always restart on exit" semantic.

Happy to accept a PR against post-#44 code. If you'd rather I ship it, I'll take it — the mechanics are small (2 flags in src/cli.ts's run subcommand, 1 tag check in src/sessions.ts's gc(), tests parallel to tests/gc-permanent.test.ts). Timeline: this week if you send a PR; next week if I take it. Ping either way.