@sema-agent/core 7.32.0 → 7.32.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 7.32.1 — 2026-09-25
+
+### Fix — a park that does not pause the env no longer stops the session's background shells (#1120; behavior; +0 exports, +0 wire keys) (@cli @server)
+
+- **Before.** A durable park on a park-only target (a remote env with `capabilities.suspendable: false`, whose workspace persists on the target: a tool ask under `durableApproval`, a plan-review park, a resource-slice park) swept the env keeping only rows already retained. The run's teardown keeps every registered shell row still running on the env. One question, two rules: a session's `run_in_background` loop outlived every turn, yet was stopped the moment the run parked — for example while a plan-approval card was on screen — and its row read `running` until the next watcher poll, then `failed` (measured: the process was already gone at the checkpoint commit). A parked run also stopped the non-retained loops of other sessions sharing the same env.
+- **Now.** One function answers both boundaries: a declared retain lane (the env's or the task's) sweeps nothing; otherwise every registered shell row still running on the env is spared, any owner, and unregistered env shells are disposed. The run's teardown that follows the park still collects the run's own rows that end with it (a session-less direct mount's rows: stop source `parent` where the park's sweep used to mark `env_sweep`). A park that pauses the env (`suspendVM`) still disposes every background process first. The teardown's gate now reads the env's retain declaration too: for an env that honours its own declaration nothing changes (its dispose was already a no-op); an adapter that declares retain on its capability face but disposes anyway now keeps its unregistered shells at a run's end as well.
+- **Who needs it.** A host that declared `TaskSpec.retainBackgroundProcesses` on every turn only to keep a session's loop across an approval card, and any session waiting on a park-only approval.
+- **Who is hurt / compensation.** A deployment that relied on a park to stop a session's non-retained shells — none expected. The session terminal (`reapSessionBackground`) and the exit hard face (`killAllBackgroundShellsNow`) end them as before; a teardown on an isolated env destroyed with the run still spares nothing.
+- **Known limit.** A park-only park resumed in ANOTHER process: the session's loop still runs on the target, but the resuming process does not track it, and the resume's orphan notice lists it as stopped (KL-1120a, #1126; retained rows had this before).
+- Pins: `test/backlog1120-park-sweep-rule.test.ts` (three park lanes × task lane absent / declared on real processes, an unregistered shell as the negative control, a second session sharing the env, a failed park commit, a persistent Monitor, a same-process resume, the parking run's own run-scoped row, the env lane read by the engine's gate, five teardown controls). Contract: `docs/background-process-lifetime.md`. Wire sheet: `docs/wire-consumption/unreleased-1120.md`.
+
 ## 7.32.0 — 2026-09-25
 
 ### The ask names WHICH mandate it stands on — `AskRequest.mandate` + `PendingAction.tool_approval.mandate` + `CheckpointSummary.mandate` (#1092; additive; +3 exports `PERSISTED_RULE_MANDATES` / `PersistedRuleMandate` / `isPersistedRuleMandate`; +4 optional type keys (`AskRequest`, the `PermissionResult` ask arm, the park row, the summary); no checkpoint-version bump) (@cli @client-core @server)

package/dist/core/background-shell.d.ts

@@ -153,9 +153,10 @@ export interface BackgroundRetainLanes {
 }
 /**
  * THE retain predicate — "is this background process kept alive past the automatic reaps?" Every face that
- * answers it calls this function (Bash description + receipts, Monitor receipt, the row stamp, teardown settle
- * and dispose, park-only sweeps, session reap, the exit hard face, the listing). Any declared lane retains,
- * unless the owning isolated env is being destroyed. Contract: docs/background-process-lifetime.md.
+ * answers it calls this function (Bash description + receipts, Monitor receipt, the row stamp, teardown settle,
+ * the run-boundary dispose at teardown and park-only parks, session reap, the exit hard face, the listing).
+ * Any declared lane retains, unless the owning isolated env is being destroyed.
+ * Contract: docs/background-process-lifetime.md.
  */
 export declare function retainsBackgroundProcesses(lanes: BackgroundRetainLanes): boolean;
 /** The env lane of {@link BackgroundRetainLanes}, read off an env (false for an env without the capability). */
@@ -192,12 +193,27 @@ export declare function sweepBackgroundShells(env: ExecutionEnv & BackgroundShel
     except?: readonly string[];
 }): Promise<void>;
 /**
- * The park-only sweep (a durable park that does not pause the env), one entry point for every park lane:
- * nothing is swept when this run's task or the env declares retain; otherwise every row already retained on
- * this env (an earlier run's delivered service) is spared.
+ * THE env-wide dispose at a run boundary: the run's teardown (every exit path) and the park-only park (a
+ * durable park that does not pause the env — its workspace, and the processes on it, persist on the target).
+ * One rule for "which background shells does this boundary take":
+ *
+ * - nothing, when THE retain predicate holds for the lanes the boundary sees (the env's declaration, the
+ *   run's `TaskSpec` lane; `envDying` overrides both);
+ * - otherwise every registered shell row still running on the env is spared (`runningShellIds`, any owner):
+ *   what the run's own settle kept (session-resident rows, in-window Monitors, retained rows) and every other
+ *   run's or session's rows sharing the env. Unregistered env shells are disposed;
+ * - `envDying` (an isolated owned env destroyed with this run) spares nothing: its processes die with it.
+ *
+ * A park and a teardown ask the same question because a park-only park IS the run ending for now: the run's
+ * teardown follows every park, its settle collects the run's own rows that end with it, and its dispose
+ * spares the rest — a park that took more would take what the run's end keeps (a session's loop, killed
+ * while its approval card is on screen). The sweep before a snapshot pause is a different question (the VM
+ * pause must not capture detached jobs; resume would revive untracked zombies), which is why those sites
+ * call {@link sweepBackgroundShells} with no keep-list.
  */
-export declare function sweepParkOnlyBackgroundShells(env: ExecutionEnv & BackgroundShellCapability, registry: EnvSweepAttribution & {
-    retainedShellIds(env: unknown): readonly string[];
+export declare function sweepRunBoundaryBackgroundShells(env: ExecutionEnv & BackgroundShellCapability, registry: EnvSweepAttribution & {
+    runningShellIds(env: unknown): readonly string[];
 }, lanes: {
     task: boolean;
+    envDying?: boolean;
 }): Promise<void>;

package/dist/core/background-shell.js

@@ -33,9 +33,10 @@ export async function sweepBackgroundShells(env, attribution, opts) {
     }
     await env.disposeBackgroundShells(opts?.except !== undefined ? { except: opts.except } : undefined);
 }
-export async function sweepParkOnlyBackgroundShells(env, registry, lanes) {
-    if (retainsBackgroundProcesses({ env: envDeclaresRetain(env), task: lanes.task }))
+export async function sweepRunBoundaryBackgroundShells(env, registry, lanes) {
+    const envDying = lanes.envDying === true;
+    if (retainsBackgroundProcesses({ env: envDeclaresRetain(env), task: lanes.task, envDying }))
         return;
-    const except = registry.retainedShellIds(env);
+    const except = envDying ? [] : registry.runningShellIds(env);
     await sweepBackgroundShells(env, registry, except.length > 0 ? { except } : undefined);
 }

package/dist/core/runner/prepare-boundary-parks.js

@@ -1,4 +1,4 @@
-import { hasBackgroundShell, sweepBackgroundShells, sweepParkOnlyBackgroundShells } from "../background-shell.js";
+import { hasBackgroundShell, sweepBackgroundShells, sweepRunBoundaryBackgroundShells } from "../background-shell.js";
 import { checkpointVersionFor, debitLedger, mintCheckpointId, mintCheckpointToken, } from "../checkpoint-store.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { checkpointScopeOf } from "./checkpoint-scope.js";
@@ -37,7 +37,7 @@ export function prepareBoundaryParks(input) {
         }
         else if (parkOnlyRemoteEnv !== undefined) {
             if (hasBackgroundShell(parkOnlyRemoteEnv))
-                await sweepParkOnlyBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
+                await sweepRunBoundaryBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
             remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
         }
         const token = mintCheckpointToken();
@@ -120,7 +120,7 @@ export function prepareBoundaryParks(input) {
             }
             else if (parkOnlyRemoteEnv !== undefined) {
                 if (hasBackgroundShell(parkOnlyRemoteEnv))
-                    await sweepParkOnlyBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
+                    await sweepRunBoundaryBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
                 remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
             }
             const token = mintCheckpointToken();

package/dist/core/runner/prepare-park-ask.js

@@ -1,7 +1,7 @@
 import { uuidv7 } from "../../engine/session/uuid.js";
 import { Value } from "typebox/value";
 import { ASK_USER_QUESTION_TOOL_NAME, classifyQuestionOutcome, validateAskQuestions } from "../ask-question.js";
-import { hasBackgroundShell, sweepBackgroundShells, sweepParkOnlyBackgroundShells } from "../background-shell.js";
+import { hasBackgroundShell, sweepBackgroundShells, sweepRunBoundaryBackgroundShells } from "../background-shell.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { buildRiskDescriptor, checkpointVersionFor, debitLedger, encodeAtFidelity, mintCheckpointId, mintCheckpointToken, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
 import { pauseOf } from "../pause-registry.js";
@@ -230,7 +230,7 @@ export function prepareParkAsk(input) {
                 }
                 else if (parkOnlyRemoteEnv !== undefined) {
                     if (hasBackgroundShell(parkOnlyRemoteEnv))
-                        await sweepParkOnlyBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
+                        await sweepRunBoundaryBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
                     remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
                 }
                 token = mintCheckpointToken();

package/dist/core/runner/run-settle-and-teardown.js

@@ -2,7 +2,7 @@ import { MAX_CONSECUTIVE_COMPACTION_FAILURES } from "./compaction-knobs.js";
 import { isSyntheticApiErrorMessage } from "../../internal/harness.js";
 import { adjudicateDerivedRoute, fallbackToPrimaryNotice, sameRouteIdentity } from "../../brain/route-adjudicator.js";
 import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
-import { hasBackgroundShell, retainsBackgroundProcesses, sweepBackgroundShells } from "../background-shell.js";
+import { hasBackgroundShell, sweepRunBoundaryBackgroundShells } from "../background-shell.js";
 import { resolveCheckpointStore } from "../checkpoint-store.js";
 import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
 import { modelCostToPricing } from "../pricing.js";
@@ -315,11 +315,9 @@ export async function runSettleAndTeardown(input) {
             retainProcesses: spec.retainBackgroundProcesses === true,
         }), "taskRegistry.settleKilledForOwner", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
         const bgEnv = prepared.ownedEnv ?? runner.deps.executionEnv;
-        const retainBgBySpec = retainsBackgroundProcesses({ task: spec.retainBackgroundProcesses === true, envDying: ownedEnvDying });
-        if (bgEnv && hasBackgroundShell(bgEnv) && !retainBgBySpec) {
+        if (bgEnv && hasBackgroundShell(bgEnv)) {
             try {
-                const keepAlive = ownedEnvDying && bgEnv === prepared.ownedEnv ? [] : defaultTaskRegistry.runningShellIds(bgEnv);
-                await settleTeardownLeg(() => sweepBackgroundShells(bgEnv, defaultTaskRegistry, keepAlive.length > 0 ? { except: keepAlive } : undefined), "sweepBackgroundShells", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+                await settleTeardownLeg(() => sweepRunBoundaryBackgroundShells(bgEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true, envDying: ownedEnvDying }), "sweepBackgroundShells", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
             }
             catch (e) {
                 runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId });

package/dist/core/task-registry-shared.d.ts

@@ -140,7 +140,7 @@ export interface BackgroundBashTaskHandle extends SemaTaskHandle {
      *  field reads as not marked. The row is the delivered daemon's ONLY management surface — while the process runs it survives the
      *  per-run evict (TaskOutput/TaskStop resolve through this map; the watcher must stay live to mint
      *  the natural-exit receipt) and rides every later run's dispose except-list on the same env
-     *  ({@link TaskRegistry.retainedShellIds}). A terminal row evicts normally. Terminals: explicit
+     *  ({@link TaskRegistry.runningShellIds}). A terminal row evicts normally. Terminals: explicit
      *  TaskStop, the process's own exit (watcher settle), or env destruction (watcher env-death settle)
      *  — deliberately NO timed reaper (the deliverable is the living process). A retained SESSION-resident
      *  row is likewise exempt from the session-release reap ({@link TaskRegistry.reapSessionBackground}):

package/dist/core/task-registry.d.ts

@@ -610,10 +610,13 @@ export declare class TaskRegistry {
      *  completion notification at the terminal state. `unref()`d — a watcher never keeps the process alive.
      *  Stops itself on terminal, on a vanished shell (env disposed), or when the handle is evicted. */
     private startBashWatcher;
-    /** RETAINED shells (THE retain predicate) still running on THIS env, any owner — the park-only sweep's
-     *  spare list. Env identity is part of the match (a shared registry never exempts another env's ids). */
+    /** RETAINED shells (THE retain predicate) still running on THIS env, any owner. Env identity is part of the
+     *  match (a shared registry never exempts another env's ids). No caller in src since the park-only parks
+     *  moved to the run-boundary dispose (which spares every running row: {@link runningShellIds}); removal
+     *  scheduled for the next minor. */
     retainedShellIds(env: unknown): BackgroundShellId[];
-    /** Every shell-lane row still RUNNING on this env, any owner — the run teardown's dispose except-list.
+    /** Every shell-lane row still RUNNING on this env, any owner — the run-boundary dispose's except-list (the
+     *  run teardown and the park-only parks: `sweepRunBoundaryBackgroundShells`).
      *  A run's teardown disposes only shells it can attribute to itself: its settle sweep has already killed
      *  and settled the rows of this run that end with it, so whatever registered row is still running here is
      *  either something that settle kept (session-resident, an in-window Monitor, retained) or belongs to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.32.0",
+  "version": "7.32.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",

package/wire-changes/core@7.32.1.json

@@ -0,0 +1,78 @@
+{
+  "repo": "core",
+  "version": "7.32.1",
+  "from": "5aeef6b3eb1ec7dfc7aef1dd0c9f6a7aebfe3cfd",
+  "to": "v7.32.1",
+  "added": [],
+  "removed": [],
+  "changed": [],
+  "narrowed": [],
+  "closedSetMembers": [],
+  "closedSetsUnreadable": [],
+  "typeKeys": [],
+  "typeKeysUnreadableArms": [],
+  "typeKeysFlattenedCount": 217,
+  "declarationMoves": [],
+  "mintMoves": [],
+  "criteriaObserves": [
+    {
+      "kind": "taskEventField",
+      "name": "tool_end.output",
+      "assertions": [
+        "G1.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "BackgroundPoll.status",
+      "assertions": [
+        "G1.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "BackgroundShellHardKillReceipt.outcome",
+      "assertions": [
+        "G1.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "TaskRegistry.list",
+      "assertions": [
+        "G1.a",
+        "G1.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "TaskRegistry.reapSessionBackground",
+      "assertions": [
+        "G1.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "TaskRegistry.runningShellIds",
+      "assertions": [
+        "G1.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "TaskSpec.retainBackgroundProcesses",
+      "assertions": [
+        "G1.a"
+      ]
+    }
+  ],
+  "consumersHint": {
+    "cli": [],
+    "server": [],
+    "sdk": [],
+    "note": "scanned cli@4e593722 server@582dee2f sdk@9b5e65b — a name listed is MENTIONED there today, which is evidence of consumption, not proof of it"
+  },
+  "breakingCount": 0,
+  "breakingItems": [],
+  "toResolvedAt": "b09a04bd1f9e09fd7e28914d488f12f517dc8d4c"
+}