@sema-agent/core 7.31.1 → 7.32.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 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)
+
+- **Who needs it.** A surface that treats mandated cards differently by their reason: `mandated: true` alone could not tell a read outside the session's directories (`probe_mandate`) from an org demand, a hook's screen or a protected write.
+- **What it is.** One word of the closed six-word table (`probe_mandate` = a read outside the session's directories, `probe_unanswered`, `operator_always`, `tool_marks`, `write_protection`, `write_protection_unresolved`), present ⇔ that word is the `mandated` bit's WHOLE reason. Any other door — governance (`requiresRealApproval`), a hook's ask, an ancestor's approver, a policy's own `mandated` claim — leaves it ABSENT beside `mandated: true`, also when a table word holds too: absence names no word. One derivation (`ruleClearanceOf`'s fourth reading), stamped by the gate beside the bit (a policy's self-declared word is dropped), spread by the four mint stations through `askMandateMember`; the park row carries the same word (a stored-shape re-judgment that adds its own mandate drops it), the summary echoes it screened to the closed set.
+- **Who is hurt / compensation.** Nobody: `mandated` and `ruleOffersAbsence` read exactly as before (pinned card by card), the gate decides nothing on the word, and a consumer that ignores it renders what it rendered. A consumer that pins the card's exact key list sees one more key. **Read-deny note:** the built-in read-deny tiers default to NONE (`READ_DENY_DEFAULT_TIERS = []`), so on an unconfigured deployment a read of e.g. `~/.claude/settings.json` outside the roots is an ordinary out-of-root card carrying `mandate: "probe_mandate"`, not a refusal; the word does not distinguish a credential-looking path — the deny tiers do (`readDenyBuiltinTiers`).
+- Pins: `test/backlog1092-mandate-word.test.ts`. Wire sheet: `docs/wire-consumption/unreleased-1092.md`.
+
+### "Yes, and add this directory" takes effect in the SAME run — `AskOutcome.readRootGrant` (#1093; additive; +1 optional outcome member; +2 `ENGINE_NOTICE_CODES` members `approval.read_root_granted` / `approval.read_root_grant_rejected`; +1 export `ReadRootGrantScreen`; +1 optional `ResolvedAsk` member) (@cli @client-core @server)
+
+- **Who needs it.** The person on an out-of-root read card: it already named the one directory that would clear it (`readRootCandidate`), but acting on that meant declaring it for a LATER run; the run that asked kept asking about every read of that directory.
+- **What it does.** An approver answers `{ allow: true, readRootGrant: <the card's readRootCandidate.dir, byte for byte> }`: this run's READ directories include it from then on — the shell read boundary (the read-only shell face too) and Read / Grep / Glob / RepoMap read one live set (never a copy); `covers: "exact"` adds that one path. The write tools' roots are never touched. Announced once, `approval.read_root_granted` (`detail: { dir, covers?, root, toolName, toolCallId, sessionId, runId, taskId? }`, audience user).
+- **Bad values are loud.** No candidate on the card, another string, a non-string, a grant riding a refusal, a directory the environment can no longer resolve (or whose lookup outlives the call — bounded like the gate's other awaits and cut with it), an offered path that no longer resolves to itself (swapped for a link while the card waited), or a leg with no read face: nothing changes, the verdict the grant rode stands, and `approval.read_root_grant_rejected` says why (`reason` ∈ `on_refusal` | `not_a_string` | `no_candidate` | `mismatch` | `unresolvable` | `resolves_elsewhere` | `admits_artifact_store` | `no_read_roots`, with `offered` / bounded `requested`). The grant is screened against the engine's own copy of the card's offer, so an approver rewriting the object it was shown moves nothing.
+- **Roots are identities.** The Runner's shell read station no longer re-resolves its roots when it builds an establisher for a root set: a root swapped for a link after it was declared or granted brings in nothing (this closes the same hole for a DECLARED `additionalReadDirectories` / `additionalDirectories` root swapped before the run's first shell judgment). The Artifact tool's local-file reader reads the live set too (a granted directory's file publishes in the same run). A policy's `createApprovalPolicy` `approve` seat has no card and refuses the member (fail-closed deny naming it).
+- **The grant never admits the artifact store.** A granted directory that contains the wired local artifact store (`capabilities.storageDir`), lies inside it or is it widens nothing: `approval.read_root_grant_rejected` with `reason: "admits_artifact_store"` — otherwise Read reached the stub's `ledger.json` and every stored file, including what earlier runs published into a reused store. It is the judgment the Artifact mount already made (`rootAdmittingArtifactStore`, one rule at both admission points), now two-way at both — behaviour tightening: a declared root INSIDE the store (e.g. `additionalReadDirectories: [<store>/sub]`) now refuses the Artifact mount (`config.artifact_host_invalid`), where before only a store inside a root did (KL-1093e closed).
+- **Who is hurt / compensation.** Nobody without the member (pinned: two reads, two cards, zero notices, as before). The grant lasts for THIS run: the next run, a durable resume and children spawned afterwards start from the declared `additionalReadDirectories` (KL-1093a–c) — keeping the directory is the host's write of that seat. The gate's judgment of the asking call is unchanged.
+- Pins: `test/backlog1093-read-root-grant.test.ts`, `test/backlog1093-grant-store-exclusion.test.ts`. Wire sheet: `docs/wire-consumption/unreleased-1093.md`.
+
+### Fix — one retain predicate for background processes; a synchronous exit-boundary hard face (#1107; behavior: the session reap no longer settles a retain-declared row without killing it; +2 type exports; +1 optional env seat; @cli @server)
+
+- **Before.** Three places answered "is this background process kept alive" three ways. The Bash tool's description and launch receipt read only the env capability, so a task-level `TaskSpec.retainBackgroundProcesses` process was told "background processes do NOT survive the session" and then outlived it. The run teardown read spec OR env. The session reap read the row's mark, then the env capability again; for a retain-declared env row that no teardown had marked yet, it settled the row `killed` but left the process running. The only exit face was `reapAllSessionBackground()`, whose kills go through the env's `killBackground`. When that is a ladder (TERM now, KILL after a timer), a host exiting in the same tick never runs the KILL, and a shell that ignores SIGTERM survives with ppid 1.
+- **One predicate.** `retainsBackgroundProcesses(lanes)` (`env` / `task` / row `marked`; `envDying` overrides): any declared lane retains. A shell-lane row (`background_bash`, `monitor`) is stamped `retained` at registration from the env lane and the launching task's lane (new optional `retainBackgroundProcesses` on `RegisterBackgroundBashInput` / `RegisterMonitorInput`). Passing the lane at registration (true or false) states it, and the Runner's Bash and Monitor always do. A teardown's own spec lane re-judges only rows whose launcher did not state one, such as a host tool registering directly. Every face calls it: Bash description and receipts, the Monitor receipt, teardown settle and dispose, the park-only sweeps (now one helper that also spares rows already retained on the env), the session reap, the hard face, and `list()`. The Runner builds the hands band per run, so the spec lane is known when Bash is mounted: new `HandsToolkitOptions.retainBackgroundProcesses`, which the Runner fills from the spec. A retained process is never described as not surviving.
+- **Session reap.** A retained row is left alone (row, watcher, process). Every other session shell row is killed and settled. The settle-without-kill outcome is gone.
+- **Hard face.** `TaskRegistry.killAllBackgroundShellsNow({ includeRetained, reason? })`: synchronous, idempotent, no default for `includeRetained`.
+  - **Rows.** It visits every shell row except `completed` — running rows, rows a softer stop settled `killed`, and `failed` rows — session-resident or not. A retained row is `retained_skipped` under `includeRetained: false` unless an explicit stop already settled it `killed`.
+  - **Escaped descendants.** A descendant that left the shell's group (its own session) is outside the seat. The session reap's ordinary kill walks the tree, so a session-resident row keeps that coverage. A row only the hard face reaches does not: a non-persistent Monitor, or a session-less direct mount. This is a residual, recorded, of never signalling an unproven pid.
+  - **Kill.** Each goes through the new optional seat `BackgroundShellCapability.killBackgroundNow(shellId)`: a group SIGKILL with no TERM and no timer. The seat's outcomes are `killed` / `already_gone` / `no_pgid`.
+  - **Receipts.** One `BackgroundShellHardKillReceipt` per row: `killed` / `already_gone` / `retained_skipped` / `no_pgid`. Only a `killed` running row is settled `killed`.
+  - **`NodeExecutionEnv` seat.** Judged from the child handle, never the entry status: one `kill(-pid, SIGKILL)` while the leader is unreaped, with no descendant-pid snapshot. Its own landed kill, or an observed exit, answers `already_gone`. A refused signal (EPERM) answers `no_pgid` and a later call retries. win32 has no synchronous hard kill: the seat answers `no_pgid` and the hard face dispatches the ordinary kill, the ladder with its MSYS group discovery. A same-tick exit on win32 can leave a job running.
+  - **No seat.** An env without the seat reads `no_pgid`, and its `killBackground` is dispatched best-effort.
+  - **Session-level.** An optional `sessionId` + `scope` pair narrows the visit to the rows `reapSessionBackground(sid, scope)` keys on, for a session that ends while the engine stays up: a session kill on a shared engine, or a failed worker. The host calls `reapSessionBackground(sid, scope)` first, then `killAllBackgroundShellsNow({ sessionId: sid, scope, includeRetained: false })`. A run named with its own task id is not reached. Omitted means the whole registry, as before.
+- **Listing.** `list()` rows gain `retained?: true` on retained shell rows. This is the "keeps running" half of an exit listing.
+- **Run teardown dispose (F10).** A run's teardown disposes only shells it can attribute to itself. The env-wide dispose used to spare three kinds: this session's resident rows, in-window Monitors, and retained rows. It now spares every registered shell row still running on the env (`TaskRegistry.runningShellIds`), any owner. The settle sweep has already killed this run's rows that end with it. Unregistered env processes are still disposed. So a synchronous delegated child that shares its parent's env no longer disposes the parent session's background shells.
+- **Removed (type surface).** `TaskRegistry.sessionResidentShellIds(sessionId, env)` and `TaskRegistry.timeoutResidentShellIds(env)` are gone. They were the teardown's except-list lanes, and after F10 nothing in `src` calls them. No caller was found in the server / cli / client-core trees. Read `runningShellIds(env)` (every running shell row on the env) or `list(access)` instead.
+- **Contract.** `docs/background-process-lifetime.md` covers the three lifetimes, which exit face to call when, the retain contract (rows are in-memory and gone with the engine; task-level retain on a piped env may die of a broken pipe after the host exits), and the seat contract.
+- **Who is hurt.**
+  - **Unmarked retain-env row.** One reaped before any teardown marked it now stays running with its watch. It used to be settled `killed`, falsely, since its process stayed alive.
+  - **Mixed-lane session.** A row launched by the Runner's Bash or Monitor under a non-retaining run is no longer marked retained by a later retaining run's teardown, whether or not it is session-resident. It is reaped as its receipt said.
+  - **Task-retain wording.** A task-level retain run's Bash card and receipts drop the "do NOT survive" sentence. A task-retained daemon on an isolated env reads "Background processes are retained here" instead of "This environment declares retention".
+  - **Stop attribution.** `markStopSourceForOwner` skips a task-retained row from registration on. If `envDying` then kills it, the stop source is the teardown's own ("user" / "parent"), not a host's earlier mark.
+  - **Controlled exit mid-run.** A controlled exit in the middle of a retaining run now leaves that run's in-flight rows running. This covers rows whose launcher stated the task lane, which the Runner's Bash and Monitor always do.
+  - **Park sweeps.** A park-only sweep no longer reaps an earlier run's retained row on the same env.
+  - **Helper shells on a shared env (F10).** A synchronous helper's `run_in_background` shell is registered under the helper's own session. On 7.31.1 the parent run's teardown took it down as a side effect of the env-wide dispose. Now it outlives the parent run. The root session's end (`reapSessionBackground(root)` plus the session-level hard face) does not reach it; only the whole-registry hard face at host exit does. This applies to the SDK's static-env teardown lane and to server's session-level lane (KL-1107a; #1109 ties helper shells to the root session).
+- **Pickup.** @server: implement `killBackgroundNow` on the host background driver (unimplemented ⇒ `no_pgid` for every row). Call `killAllBackgroundShellsNow` after `reapAllSessionBackground()` on the exits with no later tick. @cli: `list()`'s `retained` splits "will stop" from "keeps running".
+- Pins: `test/backlog1107-retain-predicate.test.ts`, `test/backlog1107-exit-same-tick.test.ts`, `test/backlog1107-adoption-and-seat.test.ts`, `test/backlog1107-child-teardown.test.ts`; #1109 baseline (current behavior) `test/backlog1109-helper-shell-lifetime.test.ts`.
+
+### Fix — SendMessage / ListAgents promise continuation by the subagent transcript tier (#1108; model-facing text; +0 exports; @server)
+
+- **Before.** With the durable revival lane wired, SendMessage said a finished agent was continuable "even across restarts", and ListAgents labelled recorded agents "agent (durable record)". With a process-local transcript store (tier `rows`), the record survived a restart but the conversation did not, and the revival answered "no transcript found".
+- **Now.** Both faces read one helper, `sendMessageContinuationTier`, which is `resolveSubagentTranscriptTier` over the runner's session store, gated on all three revival seats: row store, mailbox, reviver. `full` keeps the old wording. `rows` says the record outlives a restart and the conversation does not. `none` means session retention only. `createListAgentsTool` / `mountListAgents` take `continuationTier`, which the Runner fills from the same seats as its SendMessage. A direct mount without it gets the `none` wording. `createSendMessageTool` now reads the session store's subagent placement declaration at construction, and a junk declaration throws `config.store_durability_invalid`.
+- Pins: `test/backlog1108-continuation-tier.test.ts`, `test/backlog1108-listagents-tier-mount.test.ts`.
+
+### Fix — an Agent child inherits the leader's scenario-layer tools: the task-list family on the leader's one list, WebFetch, WebSearch, TodoWrite (#1110; behavior: widening for children, narrowed to what they inherit — a teammate's allowlist is widened for the inherited task-list family only, never for a host-composed pool; `SubagentToolOptions` +1 optional `inheritedTools`, `ToolExecuteContext` +1 optional Runner-filled `mountsCallerTool`; +0 exports; @server @cli @test)
+
+- **Before.** `assembleCodeTools` put the task-list family (and WebFetch / WebSearch / TodoWrite) in the leader's list only, and handed its Agent tool nothing (`childPool = opts.tools ?? []`). A host that does not pass `subagent.tools` — the server's default and code scenarios — gave every child an empty pool: a teammate's `TaskList` / `TaskCreate` answered "Tool TaskList not found", so a team could not share its task list, and no child could fetch a URL.
+- **One default, two spawn-time laws.** With no explicit `subagent.tools`, the Agent tool's pool is the bundle's surface as the SAME instances the leader mounts (`SubagentToolOptions.inheritedTools`, filled by `assembleCodeTools`): the task-list family on the bundle's one `TaskListStore`, so a teammate's task shows in the leader's `TaskList` and the other way round. (1) ⊆ parent: an entry reaches a child only when the spawning run mounts THAT instance — `ToolExecuteContext.mountsCallerTool`, identity membership in the run's `spec.tools` as the caller handed them, before the model gate. A host that removes a tool from the leader's `spec.tools` (the server drops WebFetch on a multi-tenant deployment) removes it from every child; a same-named replacement (a host's own tool, a restricted tool injected per spawn through `extraTools`) never re-admits the bundle's original, at any depth. A delegation tool driven outside a Runner (no seat) inherits nothing. (2) Spawn tier (upstream 2.1.280): a synchronous child and a named teammate get the whole surface; an anonymous background child gets WebFetch / WebSearch / TodoWrite but not the task-list family. Model-gate stamps travel with the instances, so each child's own prepare trims the family for a gate-table child model and keeps it for any other, whatever the leader's model.
+- **Teammate definitions.** A named child whose agent definition (or the tool-level) `allowTools` is a real allowlist also keeps the task-list family it INHERITED (upstream teammate shape: the root's own first-party tools). A pool the host composed — an explicit `subagent.tools`, an `extraTools` product — is judged by the allowlist as written, named child or not: a model-chosen name never lifts a host's restriction (upstream widens only for an in-process teammate under the agent-teams switch, over the root's own tools; sema has no such switch and reads any spawn `name` as a teammate — an accepted divergence (design/969) — so the widening is confined to the inherited surface, where it keeps the upstream shape). A `denyTools` entry still removes it.
+- **TodoWrite** (the `taskList: false` arm) keeps one list per calling session instead of one per instance, so a child's write never replaces the leader's plan. A call outside a Runner keeps one list, as before.
+- **Precedence and what stays as it was.** An explicit `subagent.tools` is used verbatim, with no intersection and no tier trim: the one channel through which a host hands a child a tool its parent does not mount (`[]` = children inherit nothing). A per-spawn `extraTools` product still loses to an explicit `tools` entry of the same name, and now REPLACES a same-named inherited entry (explicit > injected > inherited); when the factory does not evaluate (it throws, or the spawn tree is over its call budget) the spawn inherits nothing, since the missing product may have been an override, and the existing note says so. A fork gets the inherited surface untrimmed (upstream runs a fork on the parent's exact tools); it had an empty pool before. The allow/deny subset law and the nested delegation tool (depth) are unchanged. A host's copy of a bundle tool (`{ ...tool, … }`) is another instance: the child does not inherit it. Host tools composed beside the bundle are not inherited: inheriting a host's whole `spec.tools` would carry host tools past the host's own per-spawn gates (a file-send tool gated per spawn, an environment selector).
+- **Who is affected.** Children of `assembleCodeTools` hosts get more tools: they can call WebFetch / WebSearch, and a teammate or synchronous child can read and write the leader's task list. A child's delegation result can now carry fetched web content into the session: the memory content-origin face reads the whole inherited surface (a superset of what a given spawn is handed, so it can mark a delegation external when the leader does not mount WebFetch). A child that parks on an inherited tool's durable approval cannot be redeemed with `allow` through a host leg that drives the Agent tool without the seat: the drive refuses before it consumes anything (the approval stays pending, the refusal names the missing seat, and `deny` still resolves it); an unreadable checkpoint at that check refuses the same way. See the pickup note. `tool_end` shapes and card vocabulary are unchanged.
+- **Pickup.** @server: nothing to change for the inherited family, WebFetch and WebSearch on the run lanes. The host's `Now` tool is not in the bundle: add `nowTool()` to the `subagentExtraTools` factory to hand it to children. The parked-revive leg (`/decide` → the Agent tool's execute) drives the tool directly with no Runner seat, so a teammate revived there inherits nothing, and an `allow` on an inherited tool is refused as above. Do NOT fill the seat from the boot-time bundle the revive tool comes from: that bundle is built with no session, so its task-list store is one private list, and filling the seat from it would make every revived teammate, across sessions and tenants, share that one list. The per-row fix (resolve the scenario for the row's root session, then pass `mountsCallerTool` over that list) is the ticket filed with this change. @cli: nothing to change. @test: A-arm shape (server-shaped assembly) for a teammate's `TaskList` vs the leader's, per tier.
+- Pins: `test/backlog1110-agent-child-inherits-scenario-surface.test.ts`.
+
 ## 7.31.1 — 2026-09-25
 
 ### Fix — a credential slot in the host shell's `SEMA_` namespace is withheld from spawned children (#1099; security; `SecretEnvFindingKind` +1 member `namespace-rule`; +0 exports; @cli @server)

package/dist/agents/inherited-tool-pool.d.ts

@@ -0,0 +1,28 @@
+import type { ToolSpec } from "../core/types.js";
+/**
+ * What a delegated child inherits when its delegation tool has no explicit pool (`SubagentToolOptions.inheritedTools`):
+ * the parent surface, narrowed at spawn by two laws. The mint of the parent bound ({@link callerToolMembership}) and both
+ * reads live here, so the law has one home.
+ */
+/** The team task-list family: the pool-borne members of the upstream teammate exception set (the rest of that set,
+ *  SendMessage and the Cron trio, is mounted by a child's own prepare and never rides a delegation pool). */
+export declare const TEAM_TASK_LIST_TOOL_NAMES: readonly string[];
+/** The run's `mountsCallerTool` seat: membership BY IDENTITY in `spec.tools` as the caller handed it (a copy of the
+ *  array taken now; nothing is read off the entries, so no entry can make the mint throw). */
+export declare function callerToolMembership(tools: readonly ToolSpec[] | undefined): (tool: ToolSpec) => boolean;
+/**
+ * The inherited pool for one spawn.
+ *  · ⊆ parent: an entry survives only when the spawning run mounts THAT instance — a same-named replacement (a host's
+ *    own tool, a per-spawn injection) never re-admits the surface's original. No seat (the tool is driven outside a
+ *    Runner) = no parent bound is known = nothing is inherited; a host driving the tool directly passes the seat itself.
+ *  · tier (upstream `filterToolsForAgent`): an anonymous background child gets the async allowlist there — WebFetch /
+ *    WebSearch / TodoWrite, not the task-list family. A synchronous child, a named teammate and a fork keep it.
+ */
+export declare function inheritedChildPool(surface: readonly ToolSpec[], mountsCallerTool: ((tool: ToolSpec) => boolean) | undefined, anonymousBackground: boolean): ToolSpec[];
+/**
+ * The task-list members of a named child's INHERITED pool that stand past its allowlist (upstream: a teammate built from a
+ * custom agent type gets `[...type.tools, SendMessage, ...the four when the root has them]` — the root's own first-party
+ * tools). Only what the child inherited is widened: a pool the host composed (`tools`, `extraTools`) is judged by the
+ * allowlist as written, since a model-chosen name must not lift a host's restriction. A deny still wins.
+ */
+export declare function teammateInheritedFamily(inherited: readonly ToolSpec[], denyTools: ReadonlyArray<string> | undefined): ToolSpec[];

package/dist/agents/inherited-tool-pool.js

@@ -0,0 +1,15 @@
+import { resolveToolSubset } from "./tool-filter.js";
+import { TASK_CREATE_TOOL_NAME, TASK_GET_TOOL_NAME, TASK_LIST_TOOL_NAME, TASK_UPDATE_TOOL_NAME } from "../core/tool-catalog-entries.js";
+export const TEAM_TASK_LIST_TOOL_NAMES = Object.freeze([TASK_CREATE_TOOL_NAME, TASK_GET_TOOL_NAME, TASK_LIST_TOOL_NAME, TASK_UPDATE_TOOL_NAME]);
+export function callerToolMembership(tools) {
+    const mounted = new Set(Array.isArray(tools) ? tools : []);
+    return (tool) => mounted.has(tool);
+}
+export function inheritedChildPool(surface, mountsCallerTool, anonymousBackground) {
+    if (mountsCallerTool === undefined)
+        return [];
+    return surface.filter((t) => mountsCallerTool(t) && !(anonymousBackground && TEAM_TASK_LIST_TOOL_NAMES.includes(t.name)));
+}
+export function teammateInheritedFamily(inherited, denyTools) {
+    return resolveToolSubset(inherited.filter((t) => TEAM_TASK_LIST_TOOL_NAMES.includes(t.name)), undefined, denyTools);
+}

package/dist/agents/list-agents-tool.d.ts

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import type { TaskAccess } from "../core/task-registry.js";
 import { type RosterEntry } from "./roster-store.js";
 import { type PeerDirectory, type PeerPresence, type PeerSessionRecord } from "./peer-directory.js";
+import type { SubagentTranscriptTier } from "../core/wiring-manifest.js";
 export declare const LIST_AGENTS_TOOL_NAME = "ListAgents";
 export declare const LIST_AGENTS_TOOL_ALIAS = "ListPeers";
 /** CC `maxResultSizeChars` for this tool. */
@@ -55,6 +56,12 @@ export interface ListAgentsToolOptions {
     };
     /** The resolved freshness window ({@link isFreshPeerRow}); absent ⇒ {@link PEER_LISTING_FRESH_WINDOW_MS}. */
     freshWindowMs?: number;
+    /** The continuation reach of the SendMessage mounted beside this tool (`sendMessageContinuationTier` —
+     *  the same answer from the same seats, so the two faces cannot disagree): what a recorded agent's label
+     *  may promise. `full` = the record and the conversation survive a restart; `rows` = the record survives,
+     *  the conversation does not; `none` = only the recorded name. Absent (a direct mount that did not say) ⇒
+     *  the `none` wording — a label never promises more than the mount can show. */
+    continuationTier?: SubagentTranscriptTier;
     /** The clock (tests). */
     now?: () => number;
 }

package/dist/agents/list-agents-tool.js

@@ -149,15 +149,22 @@ export function createListAgentsTool(opts) {
                 catch {
                 }
             }
+            const tier = opts.continuationTier ?? "none";
+            const rosterLabel = tier === "full" ? "agent (durable record)" : tier === "rows" ? "agent (record kept; conversation not kept across restarts)" : "agent (recorded name)";
+            const finishedReach = tier === "full"
+                ? "while its session is retained or a durable record exists"
+                : tier === "rows"
+                    ? "while its session is retained or this engine process still holds its conversation"
+                    : "while its session is retained";
             const lines = rows.map((r) => {
                 const label = r.kind === "peer_session" ? formatPeerNameRef(inlineUntrusted(r.name, 64), r.ref) : inlineUntrusted(r.name, 64);
                 const age = r.kind !== "peer_session" ? undefined : r.lastActiveAt !== undefined ? `active ${formatAgo(now - r.lastActiveAt)} ago` : r.offlineAt !== undefined ? `offline ${formatAgo(now - r.offlineAt)} ago` : "offline";
-                const cols = [label, r.state, age, r.cwd !== undefined ? inlineUntrusted(r.cwd, 64) : undefined, r.presence !== undefined ? renderPresence(r.presence) : undefined, r.kind === "peer_session" ? "peer session" : r.kind === "roster" ? "agent (durable record)" : "agent", r.address];
+                const cols = [label, r.state, age, r.cwd !== undefined ? inlineUntrusted(r.cwd, 64) : undefined, r.presence !== undefined ? renderPresence(r.presence) : undefined, r.kind === "peer_session" ? "peer session" : r.kind === "roster" ? rosterLabel : "agent", r.address];
                 return cols.filter((c) => c !== undefined).join("  ·  ");
             });
             const finishedCount = rows.filter((r) => r.state === "finished").length;
             const header = rows.length === 0 ? "No agents or peer sessions are listed right now." : `${rows.length} listed:`;
-            const finishedNote = finishedCount > 0 ? `\n(${finishedCount} finished agent(s): continuable by SendMessage only while its session is retained or a durable record exists — otherwise SendMessage answers with an honest refusal)` : "";
+            const finishedNote = finishedCount > 0 ? `\n(${finishedCount} finished agent(s): continuable by SendMessage only ${finishedReach} — otherwise SendMessage answers with an honest refusal)` : "";
             const fault = (directoryFault !== undefined ? `\n(peer-session directory unreadable: ${inlineUntrusted(directoryFault, 200)} — peer rows may be missing)` : "") +
                 (registryCapped ? "\n(the live task list is at its 500-row window: older background agents may be missing from this listing — address them by task_id)" : "");
             let content = `${header}${lines.length > 0 ? `\n${lines.join("\n")}` : ""}${finishedNote}${fault}`;

package/dist/agents/peer-session-drain.d.ts

@@ -237,6 +237,8 @@ export declare function mountListAgents(args: {
     parentSessionId?: string;
     registry: ListAgentsToolRegistry;
     roster?: NonNullable<Parameters<typeof createListAgentsTool>[0]["roster"]>;
+    /** The continuation reach of the SendMessage beside it — what a recorded agent's label may promise (see the tool option). */
+    continuationTier?: NonNullable<Parameters<typeof createListAgentsTool>[0]["continuationTier"]>;
     specTools: ReadonlyArray<{
         name: string;
         aliases?: readonly string[];

package/dist/agents/peer-session-drain.js

@@ -698,6 +698,7 @@ export function mountListAgents(args) {
         access: { owner: args.hostTaskId, scope: args.scope, sessionId: args.sessionId },
         ...(args.parentTaskId !== undefined ? { parentAccess: { owner: args.parentTaskId, scope: args.scope, ...(args.parentSessionId !== undefined ? { sessionId: args.parentSessionId } : {}) } } : {}),
         ...(args.roster !== undefined ? { roster: args.roster } : {}),
+        ...(args.continuationTier !== undefined ? { continuationTier: args.continuationTier } : {}),
     });
 }
 export function bindPeerSessionDrain(harness, opts) {

package/dist/agents/send-message-tool.d.ts

@@ -8,6 +8,7 @@ import { type PeerDirectory } from "./peer-directory.js";
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type SubagentSteerHandle } from "./subagent.js";
 import { type PeerLaneConfig, type PeerInboundChainRef, type PeerSelfRef } from "./peer-admission.js";
+import { type SubagentTranscriptTier } from "../core/wiring-manifest.js";
 /** Model-facing name of the background-agent continuation tool (CC 2.1.2xx `SendMessage`). */
 export declare const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 export interface SendMessageToolOptions {
@@ -237,6 +238,22 @@ export declare function clipSendMessageSummary(raw: string): string;
  * second revive). The auto-mode peer-referral tighten keys on the WIRE NAME and applies to a direct
  * mount all the same.
  */
+/**
+ * The continuation promise's REACH — how far "continue a finished agent" goes on a SendMessage mount — by the
+ * deployment's subagent transcript tier: the ONE derivation (`resolveSubagentTranscriptTier`, the wiring
+ * manifest's `subagentTranscripts` cell) over the mount's own seats. Without all three tier-3 seats (row
+ * store, mailbox, reviver) there is no durable revival at all — session retention is the only lane (`none`).
+ * With them, the session store the revival runs through (`runner.sessions`) decides: `full` keeps the
+ * conversation across a restart, `rows` keeps the record but not the conversation (a process-local
+ * transcript store), so only `full` may say "across restarts". Exported so every face that describes the
+ * same reach (the ListAgents mount beside this tool) reads the same answer from the same seats.
+ */
+export declare function sendMessageContinuationTier(seats: {
+    agentStore?: unknown;
+    mailbox?: unknown;
+    reviveSpawn?: unknown;
+    runner: Pick<RunnerSelfSeat, "sessions">;
+}): SubagentTranscriptTier;
 export declare function createSendMessageTool(opts: SendMessageToolOptions): import("../internal/harness.js").AgentTool<Type.TObject<{
     to: Type.TString;
     message: Type.TString;

package/dist/agents/send-message-tool.js

@@ -18,6 +18,7 @@ import { appendHopToken, judgePeerAdmission, peerAxisToken, resolvePeerLaneConfi
 import { toolFace } from "../core/tool-catalog-entries.js";
 import { thrownText } from "../core/thrown-value.js";
 import { assertNoRetiredKeys } from "../core/retired-keys.js";
+import { resolveSubagentTranscriptTier } from "../core/wiring-manifest.js";
 export const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 let uplinkSeqGlobal = Date.now();
 const UPLINK_RESULT_MAX = 8000;
@@ -60,9 +61,13 @@ function targetLaneKey(scope, targetId) {
     return JSON.stringify([scope ?? "", targetId]);
 }
 const OPERATOR_CONTINUATION_CTX = Symbol("sema.operator_continuation");
+export function sendMessageContinuationTier(seats) {
+    const tier3Capable = seats.agentStore !== undefined && seats.mailbox !== undefined && seats.reviveSpawn !== undefined;
+    return tier3Capable ? resolveSubagentTranscriptTier(true, seats.runner.sessions) : "none";
+}
 export function createSendMessageTool(opts) {
     assertNoRetiredSendMessageOptions(opts);
-    const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
+    const continuationTier = sendMessageContinuationTier(opts);
     const notifyWhenIdleParameter = {
         notify_when_idle: Type.Optional(Type.Boolean({
             description: "Ask a peer SESSION of this engine to send you ONE notice when it next goes idle (finishes its turn with nothing queued) or exits — opt-in, one-shot, no polling. With a message: deliver it now AND subscribe. Without a message (omit it): a pure subscription that costs the other session nothing. Peer sessions only (not agents or teammates), and only from the main conversation.",
@@ -166,10 +171,12 @@ export function createSendMessageTool(opts) {
                     : `A finished agent is NOT announced on this mount${retrievalMounted === false
                         ? ", and its result cannot be collected by this run (no TaskOutput is mounted beside this tool) — do not end your turn to wait for a notification that never comes"
                         : " — check on it with TaskOutput(task_id) where mounted rather than ending your turn to wait for a notification that never comes"}. `) +
-            (tier3Capable
+            (continuationTier === "full"
                 ? `Continuing a finished agent works for agents with a durable record — by name or task_id, even across restarts — and for runs that retain sub-agent sessions; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
-                : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
-                    `retained (or is no longer held) you get an honest error and should launch a new agent with the needed context instead.`) +
+                : continuationTier === "rows"
+                    ? `Continuing a finished agent works by name or task_id while this engine process still holds its conversation, and for runs that retain sub-agent sessions — its record outlives a restart but its conversation does not, so after a restart it cannot be continued; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
+                    : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
+                        `retained (or is no longer held) you get an honest error and should launch a new agent with the needed context instead.`) +
             (peerLane.active
                 ? ` Peer SESSIONS — other sessions of this engine for the same user${opts.peerListingMounted === false ? "" : opts.peerListingMounted === true ? " (list them with ListAgents)" : " (list them with ListAgents where that tool is mounted)"} — are addressed by name, by \`name [ref]\` when a name is ambiguous, or by their \`session.<id>\` address. A message to a peer is parked durably in its session box and read at its next turn boundary (an offline peer reads it when it next runs); the receipt confirms the box accepted it, not that the peer acted on it.`
                 : ""),

package/dist/agents/subagent.d.ts

@@ -702,8 +702,17 @@ export interface SubagentToolOptions {
      * assembly time but still resolves at the child's own prepare through the runner's live table.
      */
     models?: Record<string, Model>;
-    /** Tools available to the child (a deliberately narrowed subset). */
+    /** Tools available to the child: the deployment's EXPLICIT pool, used verbatim — it replaces {@link inheritedTools}
+     *  and is the one channel that hands a child a tool its parent does not mount. `[]` = the child inherits nothing. */
     tools?: ToolSpec[];
+    /**
+     * The parent surface a child inherits when {@link tools} is absent (`assembleCodeTools` passes its bundle's own
+     * instances, so the task-list family shares the leader's store). Narrowed per spawn by `inheritedChildPool`: only
+     * the instances the spawning run mounts (`ToolExecuteContext.mountsCallerTool`; a host's copy of an entry is another
+     * instance and is not inherited), no task-list family for an anonymous background child, and a same-named `extraTools`
+     * product replaces the entry. Model-gate stamps travel with the entries; each child's prepare re-judges them.
+     */
+    inheritedTools?: ToolSpec[];
     /**
      * Tool-level allowlist (design/38 1A), used when NO `agent` is selected (a selected agent definition's
      * own `allowTools`/`denyTools` REPLACE these). When set, the child sees only these tools from `tools`

package/dist/agents/subagent.js

@@ -68,6 +68,7 @@ import { LAUNCH_RECEIPT_OWN_WORDS_CLAUSE, launchReceiptNoQuoteClause } from "./l
 import { ObserverDigestTap, ObserverPairing, createObserverReportToolSpec, markObserverTaskId, unmarkObserverTaskId, isObserverTaskId, ObserverResumeStateError, ObserverStoppedByUserError, observerFramingPrompt, observerSlug, resolveObserverDeclaration, } from "./observer.js";
 import { SubagentStepRecorder } from "./subagent-steps.js";
 import { toolFace } from "../core/tool-catalog-entries.js";
+import { inheritedChildPool, teammateInheritedFamily } from "./inherited-tool-pool.js";
 import { readMember, thrownText } from "../core/thrown-value.js";
 const BG_AGENT_RESULT_MAX = 4_000;
 const BG_AGENT_RESULT_FULL_MAX = 200_000;
@@ -1390,7 +1391,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
     ];
     const agentToolPool = opts.extraTools !== undefined
         ? undefined
-        : (opts.tools ?? []).map((t) => ({
+        : (opts.tools ?? opts.inheritedTools ?? []).map((t) => ({
             name: t.name,
             ...(t.aliases !== undefined ? { aliases: t.aliases } : {}),
             ...(t.contentOrigin !== undefined
@@ -1807,7 +1808,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     };
                 }
             }
-            let childPool = opts.tools ?? [];
+            const inherited = opts.tools === undefined && extraToolsNote === undefined ? inheritedChildPool(opts.inheritedTools ?? [], ctx.mountsCallerTool, wantsBackground && agentName === undefined && !wantsFork) : [];
+            if (extraToolsNote !== undefined && opts.tools === undefined && (opts.inheritedTools?.length ?? 0) > 0)
+                extraToolsNote += " The inherited tools were withheld for this spawn as well.";
+            let childPool = opts.tools ?? inherited;
             if (injectedTools.length > 0) {
                 const taken = new Set();
                 const reserve = (t) => {
@@ -1818,20 +1822,19 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 for (const t of opts.tools ?? [])
                     reserve(t);
                 taken.add(toolName);
-                const merged = [...(opts.tools ?? [])];
+                const accepted = [];
                 for (const t of injectedTools) {
                     const names = [t.name, ...(t.aliases ?? [])];
                     if (names.some((n) => taken.has(n)))
                         continue;
                     for (const n of names)
                         taken.add(n);
-                    merged.push(t);
+                    accepted.push(t);
                 }
-                childPool = merged;
+                childPool = [...(opts.tools ?? inherited.filter((t) => ![t.name, ...(t.aliases ?? [])].some((n) => taken.has(n)))), ...accepted];
             }
-            const childTools = def
-                ? resolveToolSubset(childPool, def.allowTools, def.denyTools)
-                : resolveToolSubset(childPool, opts.allowTools, opts.denyTools);
+            const allowed = new Set([...resolveToolSubset(childPool, def ? def.allowTools : opts.allowTools, def ? def.denyTools : opts.denyTools), ...(agentName !== undefined ? teammateInheritedFamily(childPool.filter((t) => inherited.includes(t)), def ? def.denyTools : opts.denyTools) : [])]);
+            const childTools = childPool.filter((t) => allowed.has(t));
             const childSystemPrompt = def?.systemPrompt ?? opts.systemPrompt;
             const childDefaultPersona = childSystemPrompt === undefined && !wantsFork ? SUBAGENT_PROMPT : undefined;
             const defMaxTurns = typeof def?.maxTurns === "number" && Number.isFinite(def.maxTurns) && def.maxTurns > 0 ? def.maxTurns : undefined;
@@ -3330,6 +3333,19 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }
                         return rollbackAndThrow(e);
                     }
+                    if (opts.tools === undefined && (opts.inheritedTools?.length ?? 0) > 0 && ctx.mountsCallerTool === undefined && pr.outcome.gate === "policy_ask" && pr.outcome.decision === "allow") {
+                        let pending;
+                        try {
+                            pending = (await childParkStore.get(pr.ticket.token))?.pendingAction;
+                        }
+                        catch (e) {
+                            return rollbackAndThrow(e);
+                        }
+                        const name = pending?.kind === "tool_approval" ? pending.toolName : undefined;
+                        if (name !== undefined && (opts.inheritedTools ?? []).some((t) => t.name === name) && !(bgSpec.tools ?? []).some((t) => t.name === name)) {
+                            return rollbackAndThrow(new Error(`the approved tool "${name}" is one the agent inherits from its spawning run, and this resume was driven without the \`mountsCallerTool\` seat, so the resumed agent would not have it. The host must pass the seat built from the row's own session (never a boot-time bundle: its task list has no session and would be shared by every revived agent). Deny still resolves this approval.`));
+                        }
+                    }
                     {
                         let seat;
                         try {

package/dist/core/ask-origin.d.ts

@@ -183,7 +183,7 @@ export declare function stampAskOrigin<T extends Extract<PermissionResult, {
  * the reason is that a RULE is already speaking, not that the question is beyond rules, and a surface
  * that auto-answers by posture is not crossing a mandate when it answers one.
  *
- * THREE named readings of the one pass, because three callers need three different things and taking
+ * FOUR named readings of the one pass, because four callers need four different things and taking
  * the wrong one is how this boundary drifts:
  *  · `word` — the DISCLOSED reason, first door wins, in the display order the card has always used
  *    (governance, the shadow, the hook, the ask rule, the two ancestor doors, then the marks). Display
@@ -195,12 +195,16 @@ export declare function stampAskOrigin<T extends Extract<PermissionResult, {
  *    person's explicit `ask` rule, and deliberately NOT `word !== undefined`: `persistedRuleShadowed`
  *    is an ACCOUNT of a refusal that already happened, display-only by contract, and reading it as a
  *    blocker would let a policy forwarding that metadata refuse a call nothing is blocking. A
- *    display word is never an authority.
+ *    display word is never an authority;
+ *  · `mandate` — WHICH table word the bit stands on, only when the MARKS family is its whole reason (no
+ *    governance, hook or ancestor door, and no bit stamped without a word); absent, the bit's reason is
+ *    not one word.
  */
 export declare function ruleClearanceOf(ask: RuleClearanceFacts | undefined, marks: Omit<MandateMarks, "probeMandated">): {
     word?: "mandated" | "shadowed";
     mandated: boolean;
     ruleMayClear: boolean;
+    mandate?: PersistedRuleMandate;
 };
 /** The facts one ask carries about whether a rule could clear it — the members {@link ruleClearanceOf}
  *  reads beside the tool seat's marks. Every one is either engine-stamped or, where a caller can
@@ -209,6 +213,8 @@ export declare function ruleClearanceOf(ask: RuleClearanceFacts | undefined, mar
 export interface RuleClearanceFacts {
     /** The bit a gate already stamped (see {@link import("./tool-policy.js").AskRequest.mandated}). */
     mandated?: true;
+    /** The table word a gate stamped beside that bit (see {@link import("./tool-policy.js").AskRequest.mandate}). */
+    mandate?: PersistedRuleMandate;
     requiresRealApproval?: boolean;
     /** A matching persisted allow rule was found and did not clear the ask — carries its text. */
     persistedRuleShadowed?: string;
@@ -225,13 +231,14 @@ export interface RuleClearanceFacts {
      *  pass it literally) — this task's rule lane never adjudicates it. */
     ancestorResolved?: boolean;
 }
-/** The ask FACE's mandate member — what an approval request carries, spread at the four mint stations.
- *  The stations hand it the SAME facts object they hand the rule-offer factory, so the card's word and
- *  this bit are two readings of one derivation and cannot drift. The tool SEAT is not re-judged here:
- *  its marks were folded into the stamped bit at the gate, and a station minting a request from an
+/** The ask FACE's mandate members — the bit and its table word, spread at the four mint stations and the
+ *  park row. The stations hand it the SAME facts object they hand the rule-offer factory, so the card's word
+ *  and these members are readings of one derivation and cannot drift. The tool SEAT is not re-judged here:
+ *  its marks were folded into the stamped bit and word at the gate, and a station minting a request from an
  *  ANCESTOR's decision holds no seat of this task's to judge. */
 export declare function askMandateMember(ask: RuleClearanceFacts | undefined): {
     mandated?: true;
+    mandate?: PersistedRuleMandate;
 };
 /** The clearance facts of an ask the engine did not construct (a policy's verdict), each member read ONCE into
  *  an engine-owned value — for a station that keeps the answer past its own side effects, where the verdict's
@@ -341,6 +348,8 @@ export declare function classifierMayAnswer(origin: AskOrigin): boolean;
  */
 export declare const PERSISTED_RULE_MANDATES: readonly ["operator_always", "tool_marks", "probe_mandate", "probe_unanswered", "write_protection", "write_protection_unresolved"];
 export type PersistedRuleMandate = (typeof PERSISTED_RULE_MANDATES)[number];
+/** Membership test for {@link PersistedRuleMandate} — the screen a row reader applies to a stored word. */
+export declare function isPersistedRuleMandate(v: unknown): v is PersistedRuleMandate;
 /**
  * May a LIVE automatic lane answer an ask carrying this word? (The persisted-rule lane is not among
  * them — every word binds it.) TWO COLUMNS, because the two lanes are not asking one question: the

package/dist/core/ask-origin.js

@@ -18,19 +18,20 @@ export function askOriginOf(decision, facts) {
 const TIGHTEN_ONLY_ORIGINS = new Set(["shell_gate_tighten", "safety_tighten"]);
 export function stampAskOrigin(decision, facts) {
     const origin = askOriginOf(decision, facts);
-    const mandated = ruleClearanceOf(decision, facts.mandateMarks).mandated && decision.mandated !== true ? { ...decision, mandated: true } : decision;
+    const { mandate: _selfDeclared, ...unstamped } = decision;
+    const clearance = ruleClearanceOf(unstamped, facts.mandateMarks);
+    const mandated = { ...unstamped, ...(clearance.mandated ? { mandated: true } : {}), ...(clearance.mandate !== undefined ? { mandate: clearance.mandate } : {}) };
     if (mandated.probeReadRootCandidate === undefined || TIGHTEN_ONLY_ORIGINS.has(origin))
         return { ...mandated, origin };
     const { probeReadRootCandidate: _withdrawn, ...kept } = mandated;
     return { ...kept, origin };
 }
 export function ruleClearanceOf(ask, marks) {
-    const mandated = ask?.mandated === true ||
-        ask?.requiresRealApproval === true ||
-        ask?.decisionReason === "hook" ||
-        ask?.inheritedUnresolved === true ||
-        ask?.ancestorResolved === true ||
-        persistedRuleMandateOf({ ...marks, probeMandated: ask?.probeMandated === true }) !== undefined;
+    const marksWord = persistedRuleMandateOf({ ...marks, probeMandated: ask?.probeMandated === true });
+    const doorOutsideTable = ask?.requiresRealApproval === true || ask?.decisionReason === "hook" || ask?.inheritedUnresolved === true || ask?.ancestorResolved === true;
+    const mandated = ask?.mandated === true || doorOutsideTable || marksWord !== undefined;
+    const stampedWord = ask?.mandated === true && isPersistedRuleMandate(ask.mandate) ? ask.mandate : undefined;
+    const mandate = doorOutsideTable || (ask?.mandated === true && stampedWord === undefined) ? undefined : (stampedWord ?? marksWord);
     const word = (() => {
         if (ask?.requiresRealApproval === true)
             return "mandated";
@@ -46,10 +47,11 @@ export function ruleClearanceOf(ask, marks) {
             return "mandated";
         return mandated ? "mandated" : undefined;
     })();
-    return { ...(word !== undefined ? { word } : {}), mandated, ruleMayClear: !mandated && ask?.matchedAskRule === undefined };
+    return { ...(word !== undefined ? { word } : {}), mandated, ruleMayClear: !mandated && ask?.matchedAskRule === undefined, ...(mandate !== undefined ? { mandate } : {}) };
 }
 export function askMandateMember(ask) {
-    return ruleClearanceOf(ask, {}).mandated ? { mandated: true } : {};
+    const { mandated, mandate } = ruleClearanceOf(ask, {});
+    return mandated ? { mandated: true, ...(mandate !== undefined ? { mandate } : {}) } : {};
 }
 export function ownedClearanceFacts(d) {
     const { mandated, requiresRealApproval, decisionReason, matchedAskRule, probeMandated } = d;
@@ -114,6 +116,10 @@ export function classifierMayAnswer(origin) {
     return CLASSIFIER_MAY_ANSWER[origin];
 }
 export const PERSISTED_RULE_MANDATES = ["operator_always", "tool_marks", "probe_mandate", "probe_unanswered", "write_protection", "write_protection_unresolved"];
+const PERSISTED_RULE_MANDATE_SET = new Set(PERSISTED_RULE_MANDATES);
+export function isPersistedRuleMandate(v) {
+    return PERSISTED_RULE_MANDATE_SET.has(v);
+}
 const MANDATE_LANE_ANSWERS = {
     operator_always: { classifier: true, sandboxAdmission: true },
     tool_marks: { classifier: true, sandboxAdmission: true },

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

@@ -111,6 +111,19 @@ export interface BackgroundShellCapability {
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     /** 杀一个后台进程(幂等:杀已死的是 no-op,返回 ok)。`shellId` 同 {@link pollBackground} 的越界校验。 */
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
+    /**
+     * OPTIONAL — the SYNCHRONOUS hard kill for an exit boundary with no later tick, where a ladder-style
+     * {@link killBackground} (TERM, then a timer-driven KILL) never finishes a shell that ignores SIGTERM.
+     * Contract (docs/background-process-lifetime.md): complete the kill before returning — POSIX one
+     * `kill(-pgid, SIGKILL)` over the shell's process group (an env with no synchronous hard kill, e.g. win32,
+     * answers `no_pgid` and the registry falls back to the ordinary kill); no TERM, no timer,
+     * no await; never signal a pid the env cannot prove is still its own; never throw; idempotent; the pid never
+     * leaves the env. Outcomes: `killed` (delivered now), `already_gone` (exited, or this seat already delivered
+     * its kill, or the id is not its shell any more), `no_pgid` (no synchronous kill landed — nothing host-local
+     * to signal, or the signal was refused; nothing claimed, retryable). Without this seat the registry's hard
+     * face reads `no_pgid` for every shell.
+     */
+    killBackgroundNow?(shellId: BackgroundShellId): BackgroundHardKillOutcome;
     /**
      * 杀掉并清理**本 env 的所有**后台进程。Runner 在每条退出路径调:finish/abort/throw 在 run-loop tail finally,**suspend/
      * review 必须在 `suspendVM` 之前**(design/103 §3.7;detached job 不在 suspendVM in-flight 契约内,不能指望 adapter 隐式处理)。
@@ -125,6 +138,28 @@ export interface BackgroundShellCapability {
         except?: readonly BackgroundShellId[];
     }): Promise<void>;
 }
+/** The closed outcome set of {@link BackgroundShellCapability.killBackgroundNow}. */
+export type BackgroundHardKillOutcome = "killed" | "already_gone" | "no_pgid";
+/** The retain lanes a face can see (absent = not declared). */
+export interface BackgroundRetainLanes {
+    /** The env's own declaration: `backgroundCapabilities.retainBackgroundProcesses`. */
+    readonly env?: boolean;
+    /** The task's declaration: `TaskSpec.retainBackgroundProcesses` of the run whose face is asking. */
+    readonly task?: boolean;
+    /** The row's `retained` mark (stamped at registration; see the registry row). */
+    readonly marked?: boolean;
+    /** The owning ISOLATED env is destroyed with this run: retention there is illusory; overrides every lane. */
+    readonly envDying?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function retainsBackgroundProcesses(lanes: BackgroundRetainLanes): boolean;
+/** The env lane of {@link BackgroundRetainLanes}, read off an env (false for an env without the capability). */
+export declare function envDeclaresRetain(env: ExecutionEnv): boolean;
 /**
  * 结构 + 语义检测:`env` 是否暴露后台 shell 能力且声明 `supported:true`。挂载门控用此(对齐 `hasDestroy`)。
  *
@@ -156,3 +191,13 @@ export interface EnvSweepAttribution {
 export declare function sweepBackgroundShells(env: ExecutionEnv & BackgroundShellCapability, attribution: EnvSweepAttribution | undefined, opts?: {
     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.
+ */
+export declare function sweepParkOnlyBackgroundShells(env: ExecutionEnv & BackgroundShellCapability, registry: EnvSweepAttribution & {
+    retainedShellIds(env: unknown): readonly string[];
+}, lanes: {
+    task: boolean;
+}): Promise<void>;

package/dist/core/background-shell.js

@@ -8,6 +8,13 @@ export class BackgroundShellError extends Error {
         this.name = "BackgroundShellError";
     }
 }
+export function retainsBackgroundProcesses(lanes) {
+    return (lanes.env === true || lanes.task === true || lanes.marked === true) && lanes.envDying !== true;
+}
+export function envDeclaresRetain(env) {
+    const caps = env.backgroundCapabilities;
+    return typeof caps === "object" && caps !== null && caps.retainBackgroundProcesses === true;
+}
 export function hasBackgroundShell(env) {
     const e = env;
     return (typeof e.spawnBackground === "function" &&
@@ -26,3 +33,9 @@ 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 }))
+        return;
+    const except = registry.retainedShellIds(env);
+    await sweepBackgroundShells(env, registry, except.length > 0 ? { except } : undefined);
+}