[liuedcson]

Background

run_in_background documented that "the process is terminated when the session exits", but the implementation only called trackDetachedChildPid + unref(). No session_shutdown handler existed, so the promise was never kept. A dev server started by a test host outlived it by two days, kept firing a durable cron job every minute, and produced about 6500 billed model requests.

The detached-child registry was a global Set<number>. That single data structure caused three separate defects:

1. No owner. A session could not reclaim its own trees without risking another session's, so cleanup only ever ran at whole-process exit.
2. No kind. "The session is still working" (a subagent) and "a process is still running" (a dev server the user is inspecting) were indistinguishable. A session whose reply was finished but whose dev server was still up read as unfinished.
3. No default host. Five hand-written calls in the CLI modes were the only cleanup path. The Web/Desktop host never called it, so it leaked by construction, not by oversight.

实现

1. Kind- and owner-aware registry (packages/coding-agent/src/core/process-registry.ts)

A registration carries kind (bash | subagent | workflow), the owning session id, a label, the working directory, and the log path.

isUnfinishedWork(kind) answers the completion question and deliberately excludes bash: a background command is a side effect the user inspects, not work the session is still performing. subagent and workflow count.

修复前: a single Set<number> with no way to ask either question.

2. Graceful termination (packages/coding-agent/src/utils/process-tree.ts)

terminateProcessTreeGracefully() sends SIGTERM to the process group, then SIGKILL after PROCESS_TREE_TERM_GRACE_MS. Abort and timeout paths use it, so a shell's trap ... TERM cleanup runs.

修复前: killProcessTree() (immediate SIGKILL, uncatchable) on both paths, so cleanup handlers were silently skipped.

killProcessTree() remains for host exit, where waiting is not an option.

3. Four reclamation layers (was one)

Layer	Mechanism	Covers
1	releaseOwnerGracefully(ownerId) from session_shutdown	session deleted, replaced, resumed away
2	releaseAllProcessesSync() on process.exit, registered inside the registry	any host, including one that wrote no shutdown path
3	prependListener("exit"), same registration	crash, uncaught exception
4	Detached IPC supervisor (utils/parent-death-guard.ts)	SIGKILL, which no in-process handler survives

The guard's IPC channel doubles as a liveness lease: when the channel closes for any reason, the supervisor signals every armed group. Leases are keyed by a random id, so a stale disarm cannot cancel a live lease and a recycled pid is never signalled.

4. Model-facing controls

bash_list and bash_kill let the model enumerate and stop its own session's background commands. Previously it had to remember pids from earlier tool results, which a resumed or compacted session had lost. Both are scoped to the caller's session, so a subagent or fork cannot kill a dev server another conversation owns.

Semantics

Event	Background command
Switching which session is viewed	keeps running
Forking a session	keeps running; the new session starts with none
Reloading settings or extensions	keeps running
Session deleted, replaced, or resumed away	stopped
Host exits	stopped

docs/orchestration-lifecycle.md records this and the layer table.

验证

New tests:

• test/process-registry.test.ts (7) — kind separation, per-owner release, cross-session isolation, SIGTERM handler runs before escalation, synchronous release.
• test/parent-death-guard.test.ts (2) — the SIGKILL case uses a child that ignores SIGTERM, so the test can only pass on the supervisor's SIGKILL escalation (502 ms ≈ 300 ms grace); a second test proves a disarmed lease does not report a normal exit as a parent death.
• test/background-command-lifecycle.test.ts (6) — the tool result carries kind: "bash", a command dies with its session while another session's keeps running, bash_list/bash_kill are session-scoped, cross-session kill is refused, the log file records output.

Regression evidence:

• test/subagent-child-env.test.ts used to leave fake-child.mjs processes behind (6 orphans per run, still alive after 15 s). It now terminates them: 0 orphans after a run, verified with ps and a 6 s wait.
• pnpm run check passes, including all 16 repository guards and check:public-boundary.

Not verified: real Windows hosts. The supervisor's taskkill path is exercised by inference only.

边界

• Log files are retained after their command stops, matching the choice to keep a stopped dev server inspectable. The registry carries logPath; nothing deletes it.
• This does not add a session-scoped process tree API beyond bash; workflow kind is registered but has no producer yet.