From d009fc00b75126ae2a4630eb8ff279f605006bc7 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Wed, 4 Nov 2026 17:08:32 -0800 Subject: [PATCH] docs(core): clarify subagent settlement lifecycle --- packages/core/src/session/background.ts | 4 ++-- packages/core/src/session/subagent-job.ts | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/core/src/session/background.ts b/packages/core/src/session/background.ts index 6a8520b9907..69a64729bf8 100644 --- a/packages/core/src/session/background.ts +++ b/packages/core/src/session/background.ts @@ -55,8 +55,8 @@ export const outstanding = Effect.fnUntraced(function* ( /** * Whether an idle Session will be woken again by its own work: a background job of its own or a - * descendant's still running, or admitted input not yet delivered, such as a finished shell's - * notice. A subagent's report waits for this so it carries the child's final state. + * descendant's still running, completion notices awaiting admission, or admitted input not yet + * delivered. A subagent's report waits for this so it carries the child's final state. */ export const unsettled = Effect.fnUntraced(function* ( jobs: Pick, diff --git a/packages/core/src/session/subagent-job.ts b/packages/core/src/session/subagent-job.ts index feef64dd98c..0be57297425 100644 --- a/packages/core/src/session/subagent-job.ts +++ b/packages/core/src/session/subagent-job.ts @@ -58,8 +58,8 @@ const make: Effect.Effect< }).pipe(Effect.catchTag("Session.NotFoundError", () => Effect.void)) }) - // Waits until the child stops for good: idle, with no background work or undelivered input left - // to wake it. It only waits and never resumes, since resuming an idle child runs a model step. + // Resume once for launch, then wait until the child is idle with no background work or input + // left. Never resume just to inspect settlement: resuming an idle child runs another model step. const settle = Effect.fnUntraced(function* (sessionID: SessionSchema.ID) { const outcomes = [ SessionEvent.Execution.Succeeded,