@sema-agent/core 7.31.0 → 7.32.0

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.
      */

package/dist/core/tool-policy.d.ts

@@ -1,4 +1,5 @@
 import type { AskOrigin } from "./ask-origin.js";
+import { type ReadRootGrantScreen } from "./read-root-grant-screen.js";
 import { type Settlement } from "./gate-outcome.js";
 /** A tool call presented to a policy before it executes. */
 /** design/388 B6 — the per-call face (see {@link ToolCallRequest.face}). */
@@ -332,6 +333,9 @@ export type PermissionResult = {
      *  set, and a policy self-declaring it only opts its own ask OUT of automatic answering. Carried
      *  onto the approval request as {@link AskRequest.mandated}. */
     mandated?: true;
+    /** The TABLE WORD the {@link mandated} bit stands on — see {@link AskRequest.mandate}. ENGINE-STAMPED at
+     *  the same origin stamp as the bit; a policy's self-declared value is dropped there. */
+    mandate?: import("./ask-origin.js").PersistedRuleMandate;
     /** The probe named a directory that would clear this ask
      *  ({@link import("./types.js").ReversibilityVerdict.readRootCandidate}). Display metadata like the two
      *  `probe*` above; ENGINE-STAMPED and VALIDATED at the tighten, and deliberately NOT merged onto an ask
@@ -790,6 +794,7 @@ export type ApprovalSeatOutcome = boolean | (Extract<AskOutcome, {
     allow: boolean;
 }> & {
     updatedInput?: never;
+    readRootGrant?: never;
 });
 /**
  * Human-in-the-loop approval for selected tools. Tools in `requireApproval` call `approve(req)` and
@@ -1294,6 +1299,12 @@ export interface AskRequest {
      * gate, never caller/worker-settable; tightening-only.
      */
     readonly mandated?: true;
+    /** WHICH word of the closed {@link import("./ask-origin.js").PERSISTED_RULE_MANDATES} set {@link mandated} stands
+     *  on — present ⇔ that table word is the bit's WHOLE reason (`probe_mandate` = a read outside the session's
+     *  directories). ABSENT beside `mandated: true` = another door holds too (governance, a hook, an ancestor's
+     *  approver, a policy's own claim) — absence never names a word. Stamped by the gate beside
+     *  the bit, copied by the four mint stations; the park row carries the same word. Never adjudication input. */
+    readonly mandate?: import("./ask-origin.js").PersistedRuleMandate;
     /** Present ⇔ this ask is the classifier DENIAL-LIMIT fallback (see the
      *  {@link PermissionResult} ask-arm member of the same name): the counts that tripped the bound and
      *  this ask's own auto-deny window. Two readers: a card renders it as a countdown; {@link resolveAsk}
@@ -1488,6 +1499,13 @@ export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal)
  * that were quietly dropped would leave a settlement looking unattributed rather than misreported. It is
  * carried on the arms where the CALLER settled something (its allow, its human/timeout deny) and never
  * on an end the engine produced (an abort, a throw, an unclonable edit): nobody approved those.
+ *
+ * `readRootGrant` — "yes, and add this directory": the card's {@link AskRequest.readRootCandidate} `dir`, sent back
+ * byte for byte (`shell.read_boundary.grant_candidate_is_the_grant`). Beside `allow: true` on an ask carrying that
+ * candidate, THIS run's read directories include it from then on (read faces only; `covers: "exact"` = that one
+ * path) — announced `approval.read_root_granted`. Anything else changes nothing and is announced
+ * `approval.read_root_grant_rejected`; the verdict it rode stands. A seat with no card (a policy's `approve`)
+ * refuses it. Keeping the directory beyond this run is the deployment's (`TaskSpec.additionalReadDirectories`).
  */
 export type AskOutcome = boolean | "unavailable" | {
     allow: boolean;
@@ -1495,6 +1513,7 @@ export type AskOutcome = boolean | "unavailable" | {
     settledBy?: "human" | "timeout" | "policy";
     reason?: string;
     approver?: string;
+    readRootGrant?: string;
 };
 /**
  * ruled 2026-08-04 — forward an approver into a delegated child, stamping every ask it raises with the
@@ -1649,6 +1668,8 @@ export type ResolvedAsk = (Extract<PermissionResult, {
      *  (string modes present nothing). */
     presentedInput?: unknown;
     approverUnavailable?: never;
+    /** The answer's `readRootGrant` ({@link AskOutcome}), screened against the request's candidate. */
+    readRootGrant?: ReadRootGrantScreen;
 }) | (Extract<PermissionResult, {
     action: "deny";
 }> & {
@@ -1657,6 +1678,8 @@ export type ResolvedAsk = (Extract<PermissionResult, {
     settlement: Settlement;
     presentedInput?: unknown;
     approverUnavailable?: true;
+    /** A grant riding a refusal: always `rejected` (`on_refusal`). */
+    readRootGrant?: ReadRootGrantScreen;
 });
 /**
  * Does any string reachable in `value` carry a {@link BIDI_CONTROL_RE} member? Bounded, cycle-safe,