@sema-agent/core 7.31.1 → 7.32.0

package/dist/core/runner/session-read-file-states.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The Runner's session-scoped read-file-state CACHE and the licence to inherit from it: session-scoped cache
+ * machinery, not a phase step — the Runner owns the instance for its lifetime, the run internals carry it to the
+ * hands phase, and the hands phase adopts, inherits and seals seats through it.
+ */
+import type { ReadFileState } from "../../tools/fs/safety.js";
+/**
+ * The Runner's per-session read-file-state seats (CC parity: readFileState is minted
+ * once per REPL session and mutated across turns; it has NO turn-boundary and NO abort clear site —
+ * its only clears are compaction/fork/subagent-cleanup/dispose). sema's map stays per-task (the §11
+ * ruling-A closure wiring), so the SESSION scope lives here instead: prepare adopts each task's live
+ * map under its sessionId, and the next same-session, same-Runner task INHERITS it (through the same
+ * containment judgment the transcript-replay seed applies — see `inheritSessionReadFileState`).
+ *
+ * This seat is a CACHE, never an authority:
+ *  - a durable resume's checkpoint seed stays the sole authority on that leg (the seed was cut
+ *    atomically with the leaf; this seat may be older OR newer than it);
+ *  - a cross-process continuation misses here and falls back to the transcript replay (rung-2);
+ *  - eviction (the LRU cap, a Runner restart) degrades to that same replay — never to wrong state.
+ *
+ * Bounded: an LRU over sessionIds (insertion-order refresh on read), because the SessionStore's own
+ * eviction is not observable from here — a dropped seat costs one transcript replay, nothing else.
+ * The stored value is the task's LIVE map (object identity), so in-turn mutations — tool write-backs,
+ * and above all the compaction clear — are the seat's truth by construction; a snapshot copy
+ * here would resurrect summarized-away reads on the next turn.
+ *
+ * BRANCH BINDING: a sessionId alone does not name a transcript — the same id
+ * can be rebranched (`resumeAt`), rewound out-of-band, or DELETED and re-created (`release()` + the
+ * default create-on-miss acquire), and the seat's map would then vouch for reads the CURRENT branch
+ * never saw. Each seat therefore records `anchorLeafId` — a leaf on the lineage its task produced —
+ * and inheritance must first prove the CURRENT branch still descends from that anchor
+ * (see {@link sessionSeatAnchorHolds}). The anchor is written twice: at ADOPT (the leaf at prepare;
+ * `null` when the branch was still empty) and SEALED at the task's settle to the task's own tail
+ * (`reanchor`). A `null` anchor is NEVER inheritable ("the branch is non-empty now" proves
+ * nothing about WHOSE messages those are — another Runner repopulating a released id, or a session
+ * import, makes a non-empty branch that never contained this seat's reads). An unprovable anchor
+ * falls back to the transcript replay, which reads the current branch by construction — cost, never
+ * wrongness.
+ */
+export declare class SessionReadFileStates {
+    private readonly seats;
+    private static readonly CAP;
+    /** The session's seat row, or undefined (cross-process / evicted / first turn) ⇒ caller replays.
+     *  The caller must verify the anchor against the session's CURRENT branch before using `state`. */
+    get(sessionId: string): {
+        state: ReadFileState;
+        anchorLeafId: string | null;
+    } | undefined;
+    /** Adopt THIS task's live map as the session's seat (every hands leg: fresh, continuation, resume).
+     *  `anchorLeafId` = the session's leaf as read at THIS prepare (null = the branch was empty; a
+     *  null-anchored seat is not inheritable until the settle-time {@link reanchor} names a real leaf). */
+    adopt(sessionId: string, state: ReadFileState, anchorLeafId: string | null): void;
+    /** The settle-time SEAL: re-anchor the seat to the finished task's own tail, so a
+     *  first-task (null-anchor) seat becomes inheritable only through a leaf its task provably wrote.
+     *  Identity-guarded: touches the row only while it still holds THIS task's map (a later prepare on
+     *  the same session has already replaced the seat and owns its own anchor). */
+    reanchor(sessionId: string, state: ReadFileState, anchorLeafId: string): void;
+}
+/**
+ * Does the session's CURRENT branch still descend from the seat's anchor?
+ * TRUE is the licence to inherit; anything unprovable answers FALSE (the caller then replays the
+ * transcript — the fail-closed direction costs a rebuild, never admits a wrong entry).
+ *
+ *  - anchor `null`: NEVER inheritable (r2). The seat was adopted on an empty branch and its task
+ *    never sealed (crashed pre-settle, or the leaf read failed) — "the branch is non-empty now"
+ *    would also be true of a released-and-repopulated id or an imported log, whose messages are not
+ *    this seat's lineage. The settle-time reanchor is what upgrades such a seat to a real leaf.
+ *  - anchor non-null: holds iff walking parentIds from the current leaf reaches the anchor within
+ *    a bounded number of steps (the walk length is one task's appends in the ordinary continuation).
+ *    A rebranch/rewind moved the leaf OFF the anchor's subtree ⇒ the walk misses ⇒ no inherit; a
+ *    recreated/foreign log does not contain the anchor ⇒ same answer; a re-IMPORT of the same log
+ *    keeps the anchor's lineage ⇒ inheritance stays correct there by the same test.
+ *  - a COMPACTION on the walked segment (A-082 idx2): refuses, even though the branch is perfectly
+ *    intact. The walked segment is exactly what landed AFTER this seat was anchored, and a
+ *    compaction there summarized older Read results OUT of the context the model will be shown —
+ *    the very state the compaction clear removes from the live map at the landing site. That clear reaches the seat
+ *    only when the SAME Runner did both (the seat IS that map, by object identity); a second Runner
+ *    on the shared durable session clears its own map and commits the compaction as an ORDINARY
+ *    LINEAR APPEND, which every other test here passes. Inheriting across it would let requireRead
+ *    and checkStale both pass on a read whose card the model no longer has — a blind edit from a
+ *    summarized-away recollection, the exact failure the compaction clear exists to prevent. Refusing
+ *    costs one transcript replay, and the replay reads the POST-compaction branch by construction,
+ *    so the fail-closed direction is also the CORRECT state. A compaction at or ABOVE the anchor is
+ *    not on the walked segment and does not refuse: the seat that observed it already carries its
+ *    clear (P-483-4), and an ordinary foreign turn with no compaction still inherits (G-483-5) —
+ *    dropping every seat a foreign Runner touched would restore the cross-turn read-state amnesia this seat-anchor check already ended.
+ */
+export declare function sessionSeatAnchorHolds(getEntry: (id: string) => Promise<{
+    parentId: string | null;
+    type?: string;
+} | null | undefined>, anchorLeafId: string | null, currentLeafId: string | null): Promise<boolean>;

package/dist/core/runner/session-read-file-states.js

@@ -0,0 +1,43 @@
+export class SessionReadFileStates {
+    seats = new Map();
+    static CAP = 1024;
+    get(sessionId) {
+        const seat = this.seats.get(sessionId);
+        if (seat !== undefined) {
+            this.seats.delete(sessionId);
+            this.seats.set(sessionId, seat);
+        }
+        return seat;
+    }
+    adopt(sessionId, state, anchorLeafId) {
+        this.seats.delete(sessionId);
+        this.seats.set(sessionId, { state, anchorLeafId });
+        while (this.seats.size > SessionReadFileStates.CAP) {
+            const oldest = this.seats.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.seats.delete(oldest);
+        }
+    }
+    reanchor(sessionId, state, anchorLeafId) {
+        const seat = this.seats.get(sessionId);
+        if (seat !== undefined && seat.state === state)
+            seat.anchorLeafId = anchorLeafId;
+    }
+}
+export async function sessionSeatAnchorHolds(getEntry, anchorLeafId, currentLeafId) {
+    if (anchorLeafId === null)
+        return false;
+    let id = currentLeafId;
+    for (let steps = 0; id !== null && steps < 100_000; steps++) {
+        if (id === anchorLeafId)
+            return true;
+        const entry = await getEntry(id);
+        if (entry === null || entry === undefined)
+            return false;
+        if (entry.type === "compaction")
+            return false;
+        id = entry.parentId;
+    }
+    return false;
+}

package/dist/core/store-contracts/checkpoint-store-contract.d.ts

@@ -51,6 +51,7 @@ export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
     toolName: string;
     toolInput: string;
     mandated: boolean;
+    mandate: string;
     origin: string;
     spentMicroUsd?: undefined;
 } | {
@@ -68,5 +69,6 @@ export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
     toolName?: undefined;
     toolInput?: undefined;
     mandated?: undefined;
+    mandate?: undefined;
     origin?: undefined;
 })[];

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -363,6 +363,23 @@ export async function checkpointStoreContract(make, runAssertion) {
         assert.equal("mandated" in byId.get("md-false"), false, "a written false is out-of-contract and must read as absent, never project");
         assert.equal("mandated" in byId.get("md-string"), false, "a non-boolean spelling must read as absent, never project verbatim");
     });
+    run("mandate word: a row's closed-set word survives + projects; absent stays absent; a word outside the set reads as absent", async () => {
+        const store = make();
+        const worded = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "mw-word" });
+        Object.assign(worded.pendingAction, { mandated: true, mandate: "probe_mandate" });
+        const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "mw-absent" });
+        Object.assign(bare.pendingAction, { mandated: true });
+        const bogus = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "mw-bogus" });
+        Object.assign(bogus.pendingAction, { mandated: true, mandate: "bypass_ok" });
+        for (const cp of [worded, bare, bogus])
+            await store.put(cp.token, cp);
+        assert.equal((await store.get(worded.token)).pendingAction.mandate, "probe_mandate", "the row's mandate word must survive the round-trip verbatim");
+        assert.equal("mandate" in (await store.get(bare.token)).pendingAction, false, "an absent word must stay OMITTED on the row");
+        const byId = new Map((await store.listByScope("tenant-a")).map((s) => [s.sessionId, s]));
+        assert.equal(byId.get("mw-word")?.mandate, "probe_mandate");
+        assert.equal("mandate" in byId.get("mw-absent"), false, "absent must project the key OMITTED");
+        assert.equal("mandate" in byId.get("mw-bogus"), false, "a word outside the closed set must read as absent, never project verbatim");
+    });
     await settle();
 }
 const sortByToken = (a, b) => a.token.localeCompare(b.token);
@@ -388,6 +405,7 @@ export async function checkpointListByScopeSummaries(store) {
             kind: "tool_approval",
             origin: "policy",
             mandated: true,
+            mandate: "tool_marks",
             toolCallId: "call-pr",
             toolName: "open_pr",
             args: { repo: "x" },
@@ -428,6 +446,7 @@ export const EXPECTED_LISTBYSCOPE_SUMMARIES = [
         toolName: "open_pr",
         toolInput: '{"repo":"x"}',
         mandated: true,
+        mandate: "tool_marks",
         origin: "policy",
     },
     {

package/dist/core/task-registry-monitor.js

@@ -1,4 +1,5 @@
 import { delimitUntrusted } from "./untrusted-text.js";
+import { envDeclaresRetain, retainsBackgroundProcesses } from "./background-shell.js";
 import { assertOwnership, defaultMonitorTimers, MONITOR_MAX_TIMEOUT_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_BATCH_WINDOW_MS, MONITOR_MAX_BATCHES_PER_MINUTE, MONITOR_STORM_BURST, MONITOR_STORM_KILL_AFTER_MS, MONITOR_LINE_BUF_CAP, MONITOR_SPILL_CAP_CHARS, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, renderSpoolBody, SPOOL_REPLAY, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
 import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
 import { thrownText } from "./thrown-value.js";
@@ -41,6 +42,8 @@ export function registerMonitorLane(core, input) {
         ...(input.onEvent !== undefined ? { onEvent: input.onEvent } : {}),
         ...(input.toolResultStore !== undefined ? { toolResultStore: input.toolResultStore } : {}),
         ...(input.sessionId !== undefined ? { spillSessionId: input.sessionId } : {}),
+        ...(retainsBackgroundProcesses({ env: envDeclaresRetain(input.env), task: input.retainBackgroundProcesses === true }) ? { retained: true } : {}),
+        ...(input.retainBackgroundProcesses !== undefined ? { retainStatedAtLaunch: true } : {}),
     };
     core.handles.set(id, handle);
     try {

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

@@ -133,9 +133,11 @@ export interface BackgroundBashTaskHandle extends SemaTaskHandle {
      *  run-teardown settle/evict, kept alive through the dispose except-list, reaped by
      *  {@link TaskRegistry.reapSessionBackground}. Explicit flag only — never inferred from owner shape. */
     sessionScoped?: true;
-    /** Deliver-a-living-service ledger mark: the run-teardown settle sweep skipped this row under the
-     *  retain gate (spec-level `TaskSpec.retainBackgroundProcesses` OR the env-declared capability). The
-     *  row is the delivered daemon's ONLY management surface — while the process runs it survives the
+    /** Deliver-a-living-service ledger mark — the row's lane of THE retain predicate
+     *  (`retainsBackgroundProcesses`). Set at REGISTRATION when the launching task
+     *  (`TaskSpec.retainBackgroundProcesses`) or the env capability declares retain, and by a run teardown
+     *  whose own spec declares it. In-memory only (shell-lane rows are never persisted); a row without the
+     *  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
@@ -144,6 +146,11 @@ export interface BackgroundBashTaskHandle extends SemaTaskHandle {
      *  row is likewise exempt from the session-release reap ({@link TaskRegistry.reapSessionBackground}):
      *  the delivered daemon outlives its session, with the same three terminals. */
     retained?: true;
+    /** The launcher STATED the task lane at registration (`retainBackgroundProcesses` was passed, true or
+     *  false): the mark above already carries it, so a run teardown's own spec lane does not re-judge this row
+     *  (a later run's declaration must not re-label a process its launch receipt described). Absent ⇒ the
+     *  launcher did not know the lane (a host tool registering directly): the owning run's teardown supplies it. */
+    retainStatedAtLaunch?: true;
     /** design/116 §7 G2b: when a watcher is attached, the registry accumulates the FULL output here (rolling
      *  bound) — TaskOutput then serves a RE-READABLE snapshot (CC semantics) instead of a consume-once cursor.
      *  `timedOut`/`timeoutSec` record a SELF-INFLICTED background-timeout kill (the env's per-shell budget
@@ -449,6 +456,8 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
     sessionScoped?: true;
     /** Deliver-a-living-service ledger mark — same semantics as the bash handle's `retained` (see there). */
     retained?: true;
+    /** Same as the bash handle's `retainStatedAtLaunch` (see there). */
+    retainStatedAtLaunch?: true;
     /** Non-persistent only: watcher-enforced hard deadline (epoch ms on the injected clock).
      *  (CC parity): this deadline — not the parent run — is the watch's lifetime anchor.
      *  A monitor's life = min(timeout, process exit, TaskStop); a persistent one is SESSION-anchored.
@@ -523,6 +532,10 @@ export interface RegisterMonitorInput extends TaskAccess {
     timers?: MonitorTimers;
     /** Batch window (ms, default 200): lines arriving within one tick coalesce into one notification. */
     batchWindowMs?: number;
+    /** The LAUNCHING task's retain declaration (`TaskSpec.retainBackgroundProcesses`) — the task lane of
+     *  THE retain predicate; stamped onto the row's `retained` mark at registration, and passing it states the
+     *  lane, same as the bash lane (see `RegisterBackgroundBashInput.retainBackgroundProcesses`). */
+    retainBackgroundProcesses?: boolean;
     /** The SUSTAINED batch rate the storm bucket refills at (default 50/min). Exceeding it is
      *  suppression, not death — see `stormBurst` and MONITOR_STORM_KILL_AFTER_MS. */
     maxBatchesPerMinute?: number;

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

@@ -1,6 +1,6 @@
 import type { AgentTool, ExecutionEnv } from "../internal/harness.js";
 import type { ToolEffect } from "./types.js";
-import { type BackgroundShellCapability, type BackgroundShellId } from "./background-shell.js";
+import { type BackgroundHardKillOutcome, type BackgroundShellCapability, type BackgroundShellId } from "./background-shell.js";
 import type { WorkflowRunStore } from "./workflow-run-store.js";
 import { type BackgroundAgentStore } from "./background-agent-store.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
@@ -38,6 +38,22 @@ export interface RegisterBackgroundBashInput extends TaskAccess {
      *  append at TaskStop/run-teardown (the tail drain), so the file is written even without a watcher —
      *  there is just no live mirror. Callers create the file (empty) before registering. */
     outputFile?: string;
+    /** The LAUNCHING task's retain declaration (`TaskSpec.retainBackgroundProcesses`) — the task lane of
+     *  {@link retainsBackgroundProcesses}. Carried onto the row as its `retained` mark at registration
+     *  (together with the env lane), so faces that never see the spec — the session reap, the exit-boundary
+     *  hard face — answer the same retain question the launch receipt answered. Passing it (true or false)
+     *  STATES the lane: a later run teardown does not re-judge the row. Absent = the launcher does not know the
+     *  lane; the owning run's teardown supplies it. */
+    retainBackgroundProcesses?: boolean;
+}
+/** One row's receipt from {@link TaskRegistry.killAllBackgroundShellsNow} (closed `outcome` set; `retained`
+ *  present when the row was retained, whatever the outcome). */
+export interface BackgroundShellHardKillReceipt {
+    taskId: string;
+    type: "background_bash" | "monitor";
+    owner?: string;
+    retained?: true;
+    outcome: BackgroundHardKillOutcome | "retained_skipped";
 }
 export interface TaskPollOptions {
     workflowStore?: WorkflowRunStore;
@@ -371,7 +387,7 @@ export declare class TaskRegistry {
      *  file of a background bash row that (a) the caller can access (same owner/scope/session visibility as
      *  a TaskOutput poll — {@link canAccess}) and (b) was registered on the caller's OWN execution env —
      *  `env` identity is part of the match, same discipline as {@link retainedShellIds} /
-     *  {@link sessionResidentShellIds}. A canonical path only names a file within ONE env's filesystem
+     *  {@link runningShellIds}. A canonical path only names a file within ONE env's filesystem
      *  namespace: on a shared registry, a row minted on env A must never exempt a same-named outside-root
      *  file in env B's namespace (same session or not), so instance equality — never a string proxy — is
      *  required. The output file is minted by the ENGINE itself (createTempFile
@@ -501,10 +517,10 @@ export declare class TaskRegistry {
      *  Aborts every running session-scoped background child registered under `sessionId` and settles it
      *  `killed` (the child's own catch/then would also classify the abort as killed; this makes the registry
      *  state immediate rather than waiting on the child's promise). Idempotent.
-     *  RETAINED shell-lane rows are EXEMPT: under the deliver-a-living-service contract a retained daemon
-     *  outlives the session release — its only terminals are explicit TaskStop, its own process exit (the
-     *  watcher mints that receipt), and env destruction (the multi-tenant leak backstop). The engine-exit
-     *  reap ({@link reapAllSessionBackground}) delegates here, so it inherits the same exemption.
+     *  RETAINED shell-lane rows (THE retain predicate over the row's mark and the env's declaration) are left
+     *  whole — row, watcher and process (the deliver-a-living-service contract; their terminals: TaskStop, own
+     *  exit, env destruction, the hard face under `includeRetained: true`). Every other running shell-lane row
+     *  this session owns is killed and settled. {@link reapAllSessionBackground} delegates here.
      *  RB-375 A3 — RETURN-VALUE semantics: the count covers DIRECT hits of this sweep only (rows whose
      *  own arm above matched). Children the reaped agents themselves spawned (`sessionScoped:false`
      *  grandchildren) die COLLATERALLY, via each reaped agent's own teardown
@@ -522,11 +538,37 @@ export declare class TaskRegistry {
      *  pair — `owner` = the sessionId by design/129 discipline for background_bash/monitor/background_agent
      *  (RB-215 note: NOT for workflow, whose `owner` is the launching LEG's taskId; its session anchor is
      *  `originatingSessionId` — see {@link reapSessionBackground}'s own workflow arm for why) — and runs
-     *  the per-session reap on each pair; retain-declared envs keep their processes (rows settle only),
-     *  exactly like the per-session anchor. Timing discipline: call at the hardShutdown TERMINUS, never at
-     *  drain start — an in-flight turn may still be TaskOutput-following a bg process. Returns total rows
-     *  reaped. */
+     *  the per-session reap on each pair; retained rows are left alone (row and process), exactly like the
+     *  per-session anchor. Timing discipline: call at the hardShutdown TERMINUS, never at drain start — an
+     *  in-flight turn may still be TaskOutput-following a bg process. Returns total rows reaped.
+     *
+     *  Its kills go through each env's `killBackground` (possibly a TERM-then-timer ladder), and it reaches
+     *  session-resident rows only: every exit terminus calls {@link killAllBackgroundShellsNow} after it. */
     reapAllSessionBackground(): number;
+    /** The EXIT-BOUNDARY hard face over every shell-lane row (`background_bash` + `monitor`), session-resident or
+     *  not (docs/background-process-lifetime.md is the contract). SYNCHRONOUS (no await, no timer) and
+     *  IDEMPOTENT. Visits every row except `completed` (a `killed` row may sit inside a softer stop's grace
+     *  window; a `failed` one may have lost its watcher, not its process). A retained row (THE retain predicate)
+     *  is left alone under `includeRetained: false` — no default — unless an explicit stop already settled it
+     *  `killed`. Every other visited row goes through the seat {@link BackgroundShellCapability.killBackgroundNow}.
+     *  One receipt per visited row: `killed` (the seat delivered its kill now) / `already_gone` / `retained_skipped`
+     *  / `no_pgid` (no synchronous kill landed — no seat, the seat said so or threw; the env's ordinary
+     *  `killBackground` is then dispatched, nothing claimed). Only a running row the seat killed is settled
+     *  `killed` (stop source "system", no notification). `reason` is forensics only.
+     *  `sessionId` + `scope` narrow the visit to the rows {@link reapSessionBackground} (sessionId, scope) keys on
+     *  — the same access (`canAccess` with owner = session = sessionId, in that scope): every session-resident
+     *  row of the session, plus its run rows where the run's task id is the session id (the default); a run
+     *  named with its own task id is not reached. Absent ⇒ the whole registry. Same receipts either way. */
+    killAllBackgroundShellsNow(opts: {
+        includeRetained: boolean;
+        reason?: string;
+    } & ({
+        sessionId?: undefined;
+        scope?: undefined;
+    } | {
+        sessionId: string;
+        scope: string;
+    })): BackgroundShellHardKillReceipt[];
     /** subscribe to `reapSessionBackground` (the design/129 session terminal anchor).
      *  Returns an unsubscribe. Hooks are best-effort observers; a throwing hook is swallowed. */
     onSessionReap(hook: (sessionId: string, scope?: string) => void): () => void;
@@ -568,29 +610,19 @@ 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). */
+    retainedShellIds(env: unknown): BackgroundShellId[];
+    /** Every shell-lane row still RUNNING on this env, any owner — the run teardown's dispose except-list.
+     *  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
+     *  another run or session sharing the env. Unregistered env shells are still disposed. */
+    runningShellIds(env: unknown): BackgroundShellId[];
     /** design/135 G2: register a spawned background process as a MONITOR — the watcher polls at the batch
      *  window (200ms), turns each completed stdout line into an event, batches lines within one tick into
      *  ONE notification, enforces the non-persistent timeout, auto-stops an event storm, and fires exactly
      *  one terminal notification (exit code / timeout / auto-stop / env-side kill). */
-    /** The shells a run teardown must LEAVE ALIVE: running SESSION-scoped monitors of this
-     *  session on THIS env (their whole point is outliving the turn; the env-wide dispose would otherwise
-     *  orphan the watch — handle alive, process dead, watcher reporting a bogus env-death terminal). Env
-     *  identity is part of the match so a shared registry never exempts another env's ids. */
-    sessionResidentShellIds(sessionId: string, env: unknown): BackgroundShellId[];
-    /** The OTHER shells a run teardown must leave alive: NON-persistent monitors still inside
-     *  their timeout window, on THIS env. CC semantics: Monitor(persistent:false) lives to timeout_ms — the
-     *  parent run ending is not an exit (timeout / process exit / TaskStop are). Deliberately NO owner
-     *  filter: on a shared env an earlier run's (or another session's) in-window watch must survive this
-     *  run's env-wide dispose too. Env identity stays part of the match, same as
-     *  {@link sessionResidentShellIds} (a shared registry never exempts another env's ids). */
-    timeoutResidentShellIds(env: unknown): BackgroundShellId[];
-    /** The THIRD dispose except-list lane: RETAINED shells (the settle sweep's deliver-a-living-service
-     *  mark) still running on THIS env. Deliberately NO owner filter, same as
-     *  {@link timeoutResidentShellIds}: on a shared static env a LATER task's env-wide teardown dispose
-     *  must not reap an EARLIER task's delivered daemon (that task's own teardown skipped the dispose;
-     *  the next run's sweep was the remaining kill path). Env identity stays part of the match
-     *  (a shared registry never exempts another env's ids). */
-    retainedShellIds(env: unknown): BackgroundShellId[];
     registerMonitor(input: RegisterMonitorInput): string;
     registerWorkflow(input: RegisterWorkflowInput): string;
     pollTask(id: string, access: TaskAccess, opts?: TaskPollOptions): Promise<UnifiedTaskResult>;
@@ -616,6 +648,10 @@ export declare class TaskRegistry {
          *  explicit flag tells them apart. Bulk attribution should use {@link markStopSourceForOwner}, not a
          *  list()-driven loop (the 500-row cap). */
         sessionScoped: boolean;
+        /** Present on a shell-lane row (`background_bash` / `monitor`) that THE retain predicate keeps alive
+         *  past the automatic reaps — the "keeps running" half of an exit listing: the controlled-exit reap and
+         *  the hard face under `includeRetained: false` leave it running; every other running shell row stops. */
+        retained?: true;
         description?: string;
         toolUseId?: string;
         createdAt: number;

package/dist/core/task-registry.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { defineTool, errorResult } from "./tools.js";
-import { hasBackgroundShell } from "./background-shell.js";
+import { envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "./background-shell.js";
 import { shutdownDebug } from "./shutdown-debug.js";
 import { canAccessAgentRecord, } from "./background-agent-store.js";
 import { delimitUntrusted } from "./untrusted-text.js";
@@ -15,6 +15,9 @@ import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane,
 import { toolFace } from "./tool-catalog-entries.js";
 import { thrownText } from "./thrown-value.js";
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
+function shellRowRetained(h) {
+    return retainsBackgroundProcesses({ marked: h.retained === true, env: envDeclaresRetain(h.env) });
+}
 const BLOCK_DEFAULT_TIMEOUT_MS = 30_000;
 const BLOCK_MAX_TIMEOUT_MS = 600_000;
 function blockDeadline(timeoutMs, now) {
@@ -276,6 +279,8 @@ export class TaskRegistry {
             shellId: input.shellId,
             ...(input.onTerminal !== undefined ? { onTerminal: input.onTerminal } : {}),
             ...(input.outputFile !== undefined ? { outputFile: input.outputFile } : {}),
+            ...(retainsBackgroundProcesses({ env: envDeclaresRetain(input.env), task: input.retainBackgroundProcesses === true }) ? { retained: true } : {}),
+            ...(input.retainBackgroundProcesses !== undefined ? { retainStatedAtLaunch: true } : {}),
         });
         if (input.onTerminal)
             this.startBashWatcher(id, input.onTerminal);
@@ -396,7 +401,7 @@ export class TaskRegistry {
                 continue;
             if (handle.type === "monitor" && monitorInTimeoutWindow(handle))
                 continue;
-            if ((handle.type === "background_bash" || handle.type === "monitor") && handle.retained === true)
+            if ((handle.type === "background_bash" || handle.type === "monitor") && shellRowRetained(handle))
                 continue;
             const before = handle.stopSource;
             this.markStopSource(handle.id, source);
@@ -425,7 +430,7 @@ export class TaskRegistry {
                 continue;
             if (handle.status !== "running" || !canAccess(handle, access))
                 continue;
-            if ((handle.retained === true || handle.env.backgroundCapabilities.retainBackgroundProcesses === true || opts?.retainProcesses === true) && !opts?.envDying) {
+            if (retainsBackgroundProcesses({ marked: handle.retained === true, env: envDeclaresRetain(handle.env), task: opts?.retainProcesses === true && handle.retainStatedAtLaunch !== true, envDying: opts?.envDying === true })) {
                 handle.retained = true;
                 continue;
             }
@@ -506,18 +511,16 @@ export class TaskRegistry {
         const access = { owner: sessionId, sessionId, ...(scope !== undefined ? { scope } : {}) };
         let reaped = 0;
         for (const handle of this.handles.values()) {
-            if ((handle.type === "background_bash" || handle.type === "monitor") && handle.retained === true && handle.status === "running")
+            if ((handle.type === "background_bash" || handle.type === "monitor") && handle.status === "running" && shellRowRetained(handle))
                 continue;
             if (handle.type === "monitor" && handle.status === "running" && handle.sessionScoped && canAccess(handle, access)) {
-                shutdownDebug("session reap: monitor row", { id: handle.id, shellId: handle.shellId, retainEnv: handle.env.backgroundCapabilities.retainBackgroundProcesses === true });
+                shutdownDebug("session reap: monitor row", { id: handle.id, shellId: handle.shellId });
                 this.markStopSource(handle.id, "system");
                 if (handle.watcher !== undefined) {
                     handle.timers.clearInterval(handle.watcher);
                     handle.watcher = undefined;
                 }
-                if (handle.env.backgroundCapabilities.retainBackgroundProcesses !== true) {
-                    void this.reportSessionReapKillFailure("monitor", handle);
-                }
+                void this.reportSessionReapKillFailure("monitor", handle);
                 handle.status = "killed";
                 handle.stoppedBy = handle.stopSource ?? "system";
                 handle.updatedAt = Date.now();
@@ -526,15 +529,13 @@ export class TaskRegistry {
                 continue;
             }
             if (handle.type === "background_bash" && handle.status === "running" && handle.sessionScoped && canAccess(handle, access)) {
-                shutdownDebug("session reap: background_bash row", { id: handle.id, shellId: handle.shellId, retainEnv: handle.env.backgroundCapabilities.retainBackgroundProcesses === true });
+                shutdownDebug("session reap: background_bash row", { id: handle.id, shellId: handle.shellId });
                 this.markStopSource(handle.id, "system");
                 if (handle.watcher !== undefined) {
                     clearInterval(handle.watcher);
                     handle.watcher = undefined;
                 }
-                if (handle.env.backgroundCapabilities.retainBackgroundProcesses !== true) {
-                    void this.reportSessionReapKillFailure("background_bash", handle);
-                }
+                void this.reportSessionReapKillFailure("background_bash", handle);
                 handle.status = "killed";
                 handle.stoppedBy = handle.stopSource ?? "system";
                 handle.updatedAt = Date.now();
@@ -586,6 +587,63 @@ export class TaskRegistry {
             reaped += this.reapSessionBackground(p.owner, p.scope);
         return reaped;
     }
+    killAllBackgroundShellsNow(opts) {
+        const sessionAccess = opts.sessionId !== undefined ? { owner: opts.sessionId, sessionId: opts.sessionId, scope: opts.scope } : undefined;
+        const receipts = [];
+        const settledOwners = new Set();
+        for (const handle of this.handles.values()) {
+            if (handle.type !== "background_bash" && handle.type !== "monitor")
+                continue;
+            if (sessionAccess !== undefined && !canAccess(handle, sessionAccess))
+                continue;
+            if (handle.status === "completed")
+                continue;
+            const retained = shellRowRetained(handle);
+            const base = { taskId: handle.id, type: handle.type, ...(handle.owner !== undefined ? { owner: handle.owner } : {}), ...(retained ? { retained: true } : {}) };
+            if (retained && !opts.includeRetained && handle.status !== "killed") {
+                receipts.push({ ...base, outcome: "retained_skipped" });
+                continue;
+            }
+            let outcome;
+            try {
+                outcome = handle.env.killBackgroundNow !== undefined ? handle.env.killBackgroundNow(handle.shellId) : "no_pgid";
+            }
+            catch (err) {
+                shutdownDebug("hard kill: seat threw", { id: handle.id, shellId: handle.shellId, error: thrownText(err) });
+                outcome = "no_pgid";
+            }
+            if (outcome !== "killed" && outcome !== "already_gone" && outcome !== "no_pgid")
+                outcome = "no_pgid";
+            if (outcome === "no_pgid") {
+                try {
+                    void handle.env.killBackground(handle.shellId).catch(() => undefined);
+                }
+                catch {
+                }
+            }
+            shutdownDebug("hard kill: row", { id: handle.id, shellId: handle.shellId, outcome, reason: opts.reason ?? "" });
+            if (handle.status === "running" && outcome === "killed") {
+                this.markStopSource(handle.id, "system");
+                if (handle.watcher !== undefined) {
+                    if (handle.type === "monitor")
+                        handle.timers.clearInterval(handle.watcher);
+                    else
+                        clearInterval(handle.watcher);
+                    handle.watcher = undefined;
+                }
+                handle.status = "killed";
+                handle.stoppedBy = handle.stopSource ?? "system";
+                handle.updatedAt = Date.now();
+                mintCompletionId(handle);
+                if (handle.owner !== undefined)
+                    settledOwners.add(handle.owner);
+            }
+            receipts.push({ ...base, outcome });
+        }
+        for (const owner of settledOwners)
+            this.pokeBgQuiescence(owner);
+        return receipts;
+    }
     onSessionReap(hook) {
         this.sessionReapHooks.add(hook);
         return () => void this.sessionReapHooks.delete(hook);
@@ -595,7 +653,7 @@ export class TaskRegistry {
         for (const handle of this.handles.values()) {
             if (handle.type !== "background_bash" && handle.type !== "monitor" && handle.type !== "background_agent")
                 continue;
-            if (handle.type !== "background_agent" && handle.retained === true)
+            if (handle.type !== "background_agent" && shellRowRetained(handle))
                 continue;
             if (handle.status === "running" && handle.owner === owner)
                 n++;
@@ -777,28 +835,19 @@ export class TaskRegistry {
         handle.watcher = setInterval(() => void tick(), 1_000);
         handle.watcher.unref?.();
     }
-    sessionResidentShellIds(sessionId, env) {
-        const out = [];
-        for (const handle of this.handles.values()) {
-            if ((handle.type === "monitor" || handle.type === "background_bash") && handle.status === "running" && handle.sessionScoped === true && handle.owner === sessionId && handle.env === env) {
-                out.push(handle.shellId);
-            }
-        }
-        return out;
-    }
-    timeoutResidentShellIds(env) {
+    retainedShellIds(env) {
         const out = [];
         for (const handle of this.handles.values()) {
-            if (handle.type === "monitor" && handle.env === env && monitorInTimeoutWindow(handle)) {
+            if ((handle.type === "background_bash" || handle.type === "monitor") && handle.status === "running" && shellRowRetained(handle) && handle.env === env) {
                 out.push(handle.shellId);
             }
         }
         return out;
     }
-    retainedShellIds(env) {
+    runningShellIds(env) {
         const out = [];
         for (const handle of this.handles.values()) {
-            if ((handle.type === "background_bash" || handle.type === "monitor") && handle.status === "running" && handle.retained === true && handle.env === env) {
+            if ((handle.type === "background_bash" || handle.type === "monitor") && handle.status === "running" && handle.env === env) {
                 out.push(handle.shellId);
             }
         }
@@ -961,6 +1010,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                 type: h.type,
                 status: h.status,
                 sessionScoped: h.sessionScoped === true,
+                ...((h.type === "background_bash" || h.type === "monitor") && shellRowRetained(h) ? { retained: true } : {}),
                 ...(h.description !== undefined ? { description: h.description } : {}),
                 ...(h.toolUseId !== undefined ? { toolUseId: h.toolUseId } : {}),
                 createdAt: h.createdAt,
@@ -1003,7 +1053,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
             if (handle.type === "monitor" && !handle.sessionScoped && canAccess(handle, access)) {
                 if (monitorInTimeoutWindow(handle))
                     continue;
-                if (handle.retained === true && handle.status === "running")
+                if (shellRowRetained(handle) && handle.status === "running")
                     continue;
                 this.handles.delete(id);
                 if (handle.status === "running" && handle.owner !== undefined)
@@ -1019,7 +1069,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                 continue;
             if (handle.sessionScoped)
                 continue;
-            if (handle.retained === true && handle.status === "running")
+            if (shellRowRetained(handle) && handle.status === "running")
                 continue;
             this.handles.delete(id);
             if (handle.status === "running" && handle.owner !== undefined)

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

@@ -1138,9 +1138,11 @@ export interface TaskSpec {
      *   retention there would be illusory, so the teardown keeps its honest killed receipts instead.
      * - win32: best-effort "no active kill" only; without detached process groups, process-tree survival
      *   past the host is a platform boundary (some children may still exit with it).
-     * - Explicit stops are untouched: the TaskStop tool, per-shell background timeouts, and the
-     *   deployment's session-release reap still kill — this flag only exempts the automatic run-teardown
-     *   sweep (settle + dispose).
+     * - Automatic reaps leave a retained process alone: the run-teardown sweep (settle + dispose), the
+     *   session-release reap, and the exit-boundary hard face under `includeRetained: false`. What still ends
+     *   it: the TaskStop tool, its per-shell background timeout (while the host runs), env destruction, and the
+     *   hard face under `includeRetained: true`. The row carries the lane it was launched under (a later run's
+     *   declaration does not re-label a session-resident row) — see docs/background-process-lifetime.md.
      * - NOT inherited by delegated child tasks: each child's own spec decides for the child's own
      *   background processes.
      */