From 98061f7f13e2adff6fd57fbe4929917a81d2673d Mon Sep 17 00:00:00 2001 From: liuedcson <332840681+liuedcson@users.noreply.github.com> Date: Sat, 7 Nov 2026 20:47:24 +0800 Subject: [PATCH] docs: state that only quit releases a session's background commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new "When a command is released" section says the release is gated on `reason === "quit"`, but the ownership table right above it still listed "deleted, replaced, or resumed away" as stopping the tree. Those are exactly the reasons that do not end a session, so the two statements contradict each other and the table is the one a reader trusts. The table now separates them: `new` and `resume` keep running like a fork and a reload, and only a deleted session or a host exit stops the tree. The docblock on `releaseSessionProcesses` had the same stale claim — it described `session_shutdown` as firing only when the session is really going away, and "a session switch or a fork never reaches this handler". The handler does receive `new`, `resume` and `fork`; the gate is what keeps the trees alive. Both statements were left over from the ungated version and are now gone. --- docs/orchestration-lifecycle.md | 3 ++- packages/coding-agent/src/features/step.ts | 8 ++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/orchestration-lifecycle.md b/docs/orchestration-lifecycle.md index 3733790d..702865eb 100644 --- a/docs/orchestration-lifecycle.md +++ b/docs/orchestration-lifecycle.md @@ -292,8 +292,9 @@ Ownership decides when the tree stops: | --- | --- | | Switching which session is viewed | keeps running | | Forking a session | keeps running; the new session starts with none of them | +| Starting a new session, or resuming another one | keeps running | | Reloading settings or extensions | keeps running | -| The owning session is deleted, replaced, or resumed away | stopped | +| The owning session is deleted | stopped | | The host exits | stopped | Stopping goes through three layers, from narrowest to widest: diff --git a/packages/coding-agent/src/features/step.ts b/packages/coding-agent/src/features/step.ts index 3fc0efb1..adf520ad 100644 --- a/packages/coding-agent/src/features/step.ts +++ b/packages/coding-agent/src/features/step.ts @@ -590,10 +590,10 @@ function publishBackgroundCommandStatus(ctx: ExtensionContext): () => void { /** * Release the background process trees one session owns. * - * Called from `session_shutdown`, which fires only when the session is really going away: `/new`, - * resume, a deleted session, and quit. A session switch or a fork reuses the same session object - * and never reaches this handler, so a dev server the user is watching keeps running while they - * look at another conversation. That is the intended difference between "not visible" and "closed". + * Called from `session_shutdown` when `reason === "quit"`. That handler also fires for `new`, + * `resume`, `fork` and `reload`, and those keep the trees running: the conversation that owns them + * is still on disk — and, in a multi-session host, still on screen — so stopping its dev server + * would look like a bug. Only a host that is exiting, or a session being deleted, ends the work. * * Failure is reported, not thrown: a session that cannot stop one tree must still finish shutting * down, and the host-exit sweep is the backstop.