Design: freeze a session's program group atomically (cgroup freezer) #337

Design: freeze a session's program group atomically (cgroup freezer), so destroy and gc cannot miss a fork chain.

Problem

destroy and gc end a session's program group by reading /proc, proving that the group is the session's, and killing it. A fork chain (processes that each fork a successor and exit within a few ms) can end between two reads. Since #326, #333 and #334, agent-tty sends such a group SIGSTOP, so its processes stay in view, and judges it again. SIGSTOP and the reads are separate system calls, so this remains a heuristic. Two gaps are left, and docs/USAGE.md documents both (Limits 3 and 5, and the fork-chain paragraph under destroy):

1. A missed chain under a PID 1 that never reaps. When another process sends the group SIGCONT before each of the 5 freeze checks, the freeze misses the chain. Normally the wait then still finds the group id, and destroy fails with HOST_TIMEOUT. Under a PID 1 that never reaps, the scans show only zombies, the group reads ended, and destroy reports success while the chain still runs. gc has the same limit after its 20 frozen checks.
2. A false HOST_TIMEOUT (since fix(destroy): probe a group that no scan shows before the wait reads it ended #334). The CLI's /proc belongs to another pid namespace, the session has no autogroup record (or uses an old childPid record), and a PID 1 that never reaps keeps the zombies. Then destroy fails with HOST_TIMEOUT although the program has ended. Before fix(destroy): probe a group that no scan shows before the wait reads it ended #334, destroy recorded destroyed there. I reproduced both sides with a real CLI under sudo unshare --pid --fork without --mount-proc (see test(model): check the freeze of a fork chain behind its zombies #335).

A comment on 2026-11-03 in this work already concluded that a freeze without these gaps "needs the cgroup freezer or ptrace".

Direction to evaluate

• Put each session's program in its own cgroup v2 leaf (for example under the user's delegated systemd scope) when the host spawns it. cgroup.freeze then freezes every member at once, cgroup.procs lists the members without a /proc scan, and cgroup.kill (Linux 5.14+) kills them all in one call. Membership is inherited on fork, so a chain cannot escape it.
• Keep the current autogroup and SIGSTOP path as the fallback where no writable delegated cgroup exists (containers without delegation, older kernels, macOS, Windows).
• Questions to answer first: does a delegated cgroup exist in the environments agent-tty targets (CI runners, Coder workspaces, Docker with and without --cgroupns)? How does the host record the cgroup path so that destroy from another process can prove it is the session's (a host.json/program.json field, and model checks for it)? What happens to a session that a version without this feature started?
• The TLA+ lifecycle model (.agents/skills/verify-session-lifecycle) needs an action for the cgroup path, and the rules DestroyedProgramStopped and the gc rules must hold with it.

Done when

• A design note (ADR under docs/adr/) chooses the mechanism and the fallback, with measurements from the target environments.
• Both gaps above are closed where the mechanism is available, and the model check covers them.
• docs/USAGE.md states where the old limits still apply.

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high