@sema-agent/core 7.31.1 → 7.32.1

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

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

@@ -816,6 +816,9 @@ export type PendingAction = {
      *  when a person's rule also speaks — never a substitute for this one). Display metadata: no gate, CAS or
      *  resume path reads it. */
     mandated?: true;
+    /** The PARK twin of `AskRequest.mandate` (same derivation, same precedent): the table word the bit stands on,
+     *  present only when it is the whole reason. Written only as a member of the closed set. */
+    mandate?: import("./ask-origin.js").PersistedRuleMandate;
     /** The PARK twin of `AskRequest.denialLimitFallback`: present
      *  ⇔ this parked ask is the classifier DENIAL-LIMIT fallback, carrying the counts that tripped
      *  the bound. Its `autoDenyAfterMs` is ALWAYS `0` on a row: the window is a fact of the ask's
@@ -1947,6 +1950,8 @@ export interface CheckpointSummary {
      *  OMITTED (the {@link toolCallId} absence-shape contract), screened to the literal `true` — a pre-#1079 row
      *  reads absent (unreported). ECHO-ONLY; nothing gates on it. */
     mandated?: true;
+    /** The row's `PendingAction.tool_approval.mandate`, echoed ONLY as a member of the closed set. ECHO-ONLY. */
+    mandate?: import("./ask-origin.js").PersistedRuleMandate;
     /** The row's `PendingAction.tool_approval.denialLimitFallback`, projected BESIDE the preview
      *  for the same one-call reason: a card that shows the fallback's counts and limit must not re-open
      *  the row to learn them (`autoDenyAfterMs` is `0` on every row — see the row member). Pure echo;

package/dist/core/checkpoint-store.js

@@ -3,7 +3,7 @@ import { uuidv7 } from "../internal/harness.js";
 import { PROBE_CAUSE_PATH_MAX, PROBE_REASON_MAX, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { carriesBidiControls } from "./tool-policy.js";
 import { readDenialLimitFallback } from "./auto-mode.js";
-import { isAskOrigin, isRuleStoreUnreadable } from "./ask-origin.js";
+import { isAskOrigin, isPersistedRuleMandate, isRuleStoreUnreadable } from "./ask-origin.js";
 import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "./checkpoint-execution-record.js";
 import { renderUntrustedCommandText, stripFormatCharacters } from "./permission-rule-model.js";
 import { redactSecrets } from "./untrusted-egress.js";
@@ -305,7 +305,8 @@ export function summarizeCheckpoint(cp) {
         ...(() => {
             const origin = tool?.origin;
             const ruleStoreUnreadable = tool?.ruleStoreUnreadable;
-            return { ...(isAskOrigin(origin) ? { origin } : {}), ...(isRuleStoreUnreadable(ruleStoreUnreadable) ? { ruleStoreUnreadable } : {}) };
+            const mandate = tool?.mandate;
+            return { ...(isAskOrigin(origin) ? { origin } : {}), ...(isRuleStoreUnreadable(ruleStoreUnreadable) ? { ruleStoreUnreadable } : {}), ...(isPersistedRuleMandate(mandate) ? { mandate } : {}) };
         })(),
         ...(hasBidi ? { hasBidiControls: true } : {}),
     };

package/dist/core/engine-notice.d.ts

@@ -400,6 +400,15 @@ export interface EngineNotice {
      *    AFTER the loop's end is refused typed (`steering.not_running`, every verb alike) and mints
      *    nothing: the refusal itself is the loud answer.
      *
+     *  - `"approval.read_root_granted"` / `"approval.read_root_grant_rejected"` — an approver's `readRootGrant`
+     *    (`AskOutcome`). GRANTED: it equalled the card's `readRootCandidate.dir` beside `allow: true`; this run's READ
+     *    directories now include it (never the write roots; this run only); `detail: { dir, covers?, root, toolName,
+     *    toolCallId, sessionId, runId, taskId? }`, `root` = the canonical spelling held. REJECTED: nothing changed,
+     *    the verdict stands; `detail: { reason, offered?, requested?, …same ids }`, `reason` ∈ `on_refusal` |
+     *    `not_a_string` | `no_candidate` | `mismatch` | `unresolvable` | `resolves_elsewhere` | `admits_artifact_store`
+     *    (the directory contains the wired local artifact store, lies inside it or is it) | `no_read_roots`. Once per
+     *    answered ask. Audience `"user"`.
+     *
      *  - `"checkpoint.execution_outcome_unrecorded"` — the resumed leg's pending-call resolver disposed
      *    the decided action (executed it, delivered the refusal, or vetoed the person's yes) and filed
      *    the frame's record through `CheckpointStore.recordExecutionOutcome`, and the store answered

package/dist/core/gate-lanes.js

@@ -467,7 +467,7 @@ export async function runGateLanes(pass) {
             ...(d.action === "ask" && d.denialLimitFallback !== undefined ? { denialLimitFallback: unarmedWindow(d.denialLimitFallback) } : {}),
             ...(d.action === "ask" && d.origin !== undefined ? { origin: d.origin } : {}),
             ...(d.action === "ask" && d.ruleStoreUnreadable !== undefined ? { ruleStoreUnreadable: d.ruleStoreUnreadable } : {}),
-            ...(d.action === "ask" && d.mandated === true ? { mandated: true } : {}),
+            ...(d.action === "ask" && d.mandated === true ? { mandated: true, ...(d.mandate !== undefined ? { mandate: d.mandate } : {}) } : {}),
         });
         if (suspendAsk && pass.decision.action === "ask") {
             const parkArgs = [pass.req, pass.currentInput, safety, undefined, realApprovalOf(pass.decision), pass.decision.action === "ask" ? pass.decision.persistedRuleShadowed : undefined, pass.decision.action === "ask" ? pass.decision.decisionReason : undefined, pass.decision.action === "ask" ? pass.decision.probeReason : undefined, pass.decision.action === "ask" ? pass.decision.probeCause : undefined, pass.decision.action === "ask" ? pass.decision.segmentCoverage : undefined, pass.decision.action === "ask" ? pass.decision.matchedAskRule : undefined, pass.decision.action === "ask" ? pass.decision.probeMandated : undefined];

package/dist/core/governance-codes.d.ts

@@ -119,7 +119,7 @@ export type NoticeAudience = "user" | "operator";
  * the union's catalog ({@link EngineNotice.code}). The groups below say only which family a row joins,
  * so the catalog is not written a second time here and the two cannot drift.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed"];
 /** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */

package/dist/core/governance-codes.js

@@ -169,6 +169,8 @@ export const ENGINE_NOTICE_CODES = [
     "task.halt_unconsumed",
     "task.late_approval",
     "task.interrupt_unconsumed",
+    "approval.read_root_granted",
+    "approval.read_root_grant_rejected",
     "memory.capture_opted_out",
     "memory.capture_optout_unpersisted",
     "skills.listing_truncated",
@@ -193,6 +195,8 @@ const NOTICE_AUDIENCE_TABLE = {
     "task.halt_unconsumed": "user",
     "task.late_approval": "user",
     "task.interrupt_unconsumed": "user",
+    "approval.read_root_granted": "user",
+    "approval.read_root_grant_rejected": "user",
     "config.durable_gate_unavailable": "user",
     "memory.capture_opted_out": "user",
     "memory.capture_optout_unpersisted": "user",

package/dist/core/hooks.d.ts

@@ -1714,6 +1714,8 @@ export interface AskCarry {
     /** The stamped mandate ({@link import("./tool-policy.js").AskRequest.mandated}) — the park site's
      *  rule-offer facts read it, so a parked mandated ask offers no rule, like the live card. */
     readonly mandated?: true;
+    /** The table word stamped beside it ({@link import("./tool-policy.js").AskRequest.mandate}), for the row's twin. */
+    readonly mandate?: import("./ask-origin.js").PersistedRuleMandate;
 }
 /** What a durable row persists of an {@link AskCarry}: the fallback member COPIED (the row never aliases
  *  the gate's object; its window is already `0` — the gate's carry mint is the one writer of that

package/dist/core/read-root-grant-screen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The resolver's reading of an approver's `readRootGrant` (`AskOutcome`) against the card it answered. It only
+ * READS: widening a run's read roots is that run's own station's act, and the resolver holds no run.
+ */
+import type { ReadRootGrantCandidate } from "./types.js";
+/** `granted` ⇔ an `allow` whose grant is byte-equal to the request's `readRootCandidate.dir` (the candidate rides
+ *  back whole, `covers` included); otherwise `rejected` with ONE reason, the card's `offered` dir when it had one,
+ *  and the `requested` grant when it was a string (verbatim host text — a notice bounds it). */
+export type ReadRootGrantScreen = {
+    readonly verdict: "granted";
+    readonly candidate: ReadRootGrantCandidate;
+} | {
+    readonly verdict: "rejected";
+    readonly reason: "on_refusal" | "not_a_string" | "no_candidate" | "mismatch";
+    readonly offered?: string;
+    readonly requested?: string;
+};
+/** Screen one grant read; `{}` when the answer carried none. */
+export declare function readRootGrantSeat(grant: unknown, candidate: ReadRootGrantCandidate | undefined, allowed: boolean): {
+    readRootGrant?: ReadRootGrantScreen;
+};
+/** An engine-owned copy of a card's offer (one read per member), taken before an approver can touch the object. */
+export declare function ownReadRootCandidate(c: ReadRootGrantCandidate | undefined): ReadRootGrantCandidate | undefined;

package/dist/core/read-root-grant-screen.js

@@ -0,0 +1,17 @@
+export function readRootGrantSeat(grant, candidate, allowed) {
+    if (grant === undefined)
+        return {};
+    const offered = candidate !== undefined ? { offered: candidate.dir } : {};
+    const requested = typeof grant === "string" ? { requested: grant } : {};
+    const reason = !allowed ? "on_refusal" : typeof grant !== "string" ? "not_a_string" : candidate === undefined ? "no_candidate" : grant !== candidate.dir ? "mismatch" : undefined;
+    if (reason !== undefined)
+        return { readRootGrant: { verdict: "rejected", reason, ...offered, ...requested } };
+    return { readRootGrant: { verdict: "granted", candidate: candidate } };
+}
+export function ownReadRootCandidate(c) {
+    if (c === undefined)
+        return undefined;
+    const dir = c.dir;
+    const covers = c.covers;
+    return typeof dir === "string" ? { dir, clearsThisAsk: true, ...(covers === "exact" ? { covers } : {}) } : undefined;
+}

package/dist/core/runner/contracts.d.ts

@@ -52,7 +52,7 @@ import type { WiringManifest } from "../wiring-manifest.js";
 import type { ActiveSkillFrame } from "./active-skill-scope.js";
 import type { BudgetAxis } from "./assemble-result.js";
 import type { GitStatusLaneRef } from "./git-status-frame.js";
-import type { SessionReadFileStates } from "./prepare-hands-readface.js";
+import type { SessionReadFileStates } from "./session-read-file-states.js";
 import type { BlockedRef, OutputRef, SkillListingEntry } from "./synthetic-tools.js";
 import type { createAttachmentState, WriteFamily } from "./turn-attachments.js";
 import type { cacheFamilyOf } from "./usage-accounting.js";

package/dist/core/runner/prepare-artifact.d.ts

@@ -6,11 +6,10 @@
  * seat uses. The tool's local-file read goes through the run's fs fence (root containment, read-deny, read
  * face) exactly as `Read` does, then reads the bytes once from the execution env. A local stub's store
  * (`capabilities.storageDir`) must lie OUTSIDE every root the run may write or read — a ledger the model can
- * edit through the fs tools is not a trust boundary — and a store inside one refuses the mount, naming both.
- * The store is a path on THIS process's filesystem; a root is the execution env's canonical key. The two are
- * compared as identities under one spelling family only when both spell the same family (`within` reads both
- * under the root's family); a root of the other family names a filesystem the store cannot be on, and no
- * containment claim is made against it.
+ * edit or read through the fs tools is not a trust boundary — judged by {@link rootAdmittingArtifactStore} at
+ * every point a root is admitted: here over the prepare-time roots (a store that overlaps one refuses the mount,
+ * naming both), and at an in-flight read-root grant over the granted root (the grant is refused). The phase
+ * publishes the declared store into the run's {@link ArtifactStoreRef} for that second point.
  * Synchronous: the stretch has no await (the file read is a closure the tool calls later).
  */
 import type { ExecutionEnv } from "../../internal/harness.js";
@@ -19,6 +18,7 @@ import { type ArtifactPlane } from "../artifact-host.js";
 import { RosterBuilder } from "../tool-roster.js";
 import type { AgentTool, RunnerDeps } from "../types.js";
 import type { ReadDenyMatcher, ContainmentFace } from "../../tools/fs/index.js";
+import { type ArtifactStoreRef } from "./read-root-grant.js";
 import type { Prepared } from "./contracts.js";
 export interface PrepareArtifactInput {
     /** borrowed-readonly — the deployment's hosting seat and the notice sink the refusal arm announces on. */
@@ -38,8 +38,9 @@ export interface PrepareArtifactInput {
     executionEnv: ExecutionEnv;
     /** borrowed-readonly — the canonical task root the fs fence contains reads to; undefined ⇒ no local-file publish. */
     rootCanonical: string | undefined;
-    /** borrowed-readonly — the extra containment roots (write and read-only) the fence admits. */
-    additionalRootsCanonical: readonly string[];
+    /** borrowed-readonly — the extra containment roots (write and read-only) the fence admits, read per call (the run's
+     *  live set: an in-flight read-root grant widens it). */
+    additionalRootsCanonical: () => readonly string[];
     /** borrowed-readonly — the read-deny matcher in force for the run, when any. */
     readDenyMatcher: ReadDenyMatcher | undefined;
     /** borrowed-readonly — the resolved read face (`"open"` lifts root containment for reads). */
@@ -52,6 +53,10 @@ export interface PrepareArtifactInput {
     firstPartyOffload: (tool: AgentTool) => AgentTool;
     /** borrowed-mutable — the env-hand membership set the memory content-origin face reads (a tool that reads the execution env's files is a hand); writer here: `add("Artifact")` on the mount. */
     envHandToolNames: Set<string>;
+    /** borrowed-mutable — the run's store cell the in-flight read-root grant reads (minted by the hands phase; absent on
+     *  a hands-less leg, which has no grant); writer here: the declared `storageDir`'s physical path once the
+     *  declaration validates. */
+    artifactStoreRef?: ArtifactStoreRef;
 }
 export interface PrepareArtifactResult {
     /** owned — the mounted face's plane, or undefined when nothing mounted (absent seat, or an invalid one). */

package/dist/core/runner/prepare-artifact.js

@@ -5,11 +5,12 @@ import { RosterBuilder } from "../tool-roster.js";
 import { defineTool } from "../tools.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { physicalPathOfExisting } from "../physical-path.js";
-import { pathFamilyOf, resolveKey, violationDetails, violationText, withinAnyRoot } from "../../tools/fs/safety.js";
+import { resolveKey, violationDetails, violationText } from "../../tools/fs/safety.js";
+import { rootAdmittingArtifactStore } from "./read-root-grant.js";
 import { createArtifactTool } from "../../tools/artifact/artifact-tool.js";
 import { thrownText } from "../thrown-value.js";
 export function prepareArtifact(input) {
-    const { deps, runId, taskId, sessionId, agentName, onAsk, executionEnv, rootCanonical, additionalRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, roster, firstPartyOffload, envHandToolNames } = input;
+    const { deps, runId, taskId, sessionId, agentName, onAsk, executionEnv, rootCanonical, additionalRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, roster, firstPartyOffload, envHandToolNames, artifactStoreRef } = input;
     const host = deps.artifactHost;
     if (host === undefined)
         return { artifactPlane: undefined };
@@ -25,12 +26,13 @@ export function prepareArtifact(input) {
     if (!verdict.ok)
         return refuse(verdict.problem);
     const storageDir = verdict.capabilities.storageDir;
-    if (storageDir !== undefined && rootCanonical !== undefined) {
-        const real = physicalPathOfExisting(storageDir);
-        const storeFamily = pathFamilyOf({ root: real });
-        const inside = [rootCanonical, ...additionalRootsCanonical].find((root) => pathFamilyOf({ root }) === storeFamily && withinAnyRoot([root], real));
-        if (inside !== undefined)
-            return refuse(`the local artifact store ${storageDir} lies inside a root this run may reach through its file tools (${inside}); put the store outside every task root and additional directory`);
+    const storePhysical = storageDir !== undefined && rootCanonical !== undefined ? physicalPathOfExisting(storageDir) : undefined;
+    if (artifactStoreRef !== undefined)
+        artifactStoreRef.current = storePhysical;
+    if (storePhysical !== undefined && rootCanonical !== undefined) {
+        const overlapping = rootAdmittingArtifactStore(storePhysical, [rootCanonical, ...additionalRootsCanonical()]);
+        if (overlapping !== undefined)
+            return refuse(`the local artifact store ${storageDir} and a root this run may reach through its file tools (${overlapping}) overlap — the store lies inside a root, or the root inside the store; put the store outside every task root and additional directory`);
     }
     try {
         host.onMount?.(runId);

package/dist/core/runner/prepare-ask-lane.d.ts

@@ -26,6 +26,7 @@ import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { CwdRef } from "../../tools/fs/fs-shared.js";
 import type { AskLane, Prepared } from "./contracts.js";
 import { consumeInheritedAskGrant } from "./inherited-ask-grants.js";
+import { type GrantReadRoot } from "./read-root-grant.js";
 import type { createRuleOffersOf } from "./permission-rule-lanes.js";
 export interface PrepareAskLaneInput {
     /** borrowed-readonly — the wiring-manifest phase's ONE activation predicate; false ⇒ this phase builds nothing and
@@ -100,6 +101,8 @@ export interface PrepareAskLaneInput {
     hookTimeoutMs: number;
     /** borrowed-readonly — the own hook-crash reporter (the deny observer's swallow-guarded report sink). */
     notifyOwnHookCrash: (err: unknown) => void;
+    /** borrowed-readonly — the hands phase's in-flight read-root widening (an approver's accepted `readRootGrant`), or undefined (hands-less). */
+    grantReadRoot: GrantReadRoot | undefined;
 }
 export interface PrepareAskLaneResult {
     /** owned — the lane, or undefined exactly when `gateMachineryActive` is false (then the suspend saga, the boundary

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

@@ -5,6 +5,7 @@ import { composeCallSignal, raceAbort } from "./abort-race.js";
 import { askMandateMember } from "../ask-origin.js";
 import { gateAskCarry, lateAskSettlementObserver } from "./denial-limit-arms.js";
 import { consumeInheritedAskGrant } from "./inherited-ask-grants.js";
+import { settleReadRootGrant } from "./read-root-grant.js";
 import { asThrownError } from "../thrown-value.js";
 function createDenyObserverNotifier(hooks, hookTimeoutMs, signal, report) {
     if (hooks?.permissionDenied === undefined)
@@ -57,7 +58,7 @@ function resolveApprovalPreview(tools, toolName, args) {
     }
 }
 export function prepareAskLane(input) {
-    const { gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, advertisedWritableDirs, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash } = input;
+    const { gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, advertisedWritableDirs, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash, grantReadRoot } = input;
     if (!gateMachineryActive)
         return { askLane: undefined };
     const composedCallSignal = (callSignal) => composeCallSignal(abortController.signal, callSignal);
@@ -109,6 +110,9 @@ export function prepareAskLane(input) {
             ...(decision.action === "ask" && decision.ruleEvidence !== undefined ? { ruleEvidence: decision.ruleEvidence } : {}),
         }, onAsk, composedCallSignal(callSignal), lateAskSettlementObserver({ toolName: req.toolName, toolCallId: req.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
         const waitMs = Math.max(0, now() - t0);
+        const granting = settleReadRootGrant(resolved.readRootGrant, grantReadRoot, { toolName: req.toolName, toolCallId: req.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, signal: composedCallSignal(callSignal) });
+        if (granting !== undefined)
+            await granting;
         if (resolved.approverUnavailable !== true && resolved.settlement?.kind !== "task_aborted") {
             humanReviewRef.count += 1;
             humanReviewRef.totalWaitMs += waitMs;

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

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

package/dist/core/runner/prepare-delegation-surface.d.ts

@@ -1,3 +1,21 @@
+/**
+ * PrepareTask's DELEGATION-SURFACE phase, verbatim from the driver: the surface's two doors
+ * (the background/workflow door the read/kill faces keep; the delegated-child arm SendMessage additionally mounts
+ * on), the TaskOutput / TaskStop mounts, the SendMessage mount with its tier-3 revival spawner and peer seats, the
+ * AgentTranscript residual lane, the peer lane's ListAgents, the Monitor tool, the EnterWorktree / ExitWorktree pair
+ * with the worktree session seat it seeds from the checkpoint or the workspace snapshot, and the offload reader. The
+ * revival spawner and the continuation tier it yields are machinery below (send-message-continuation.ts). The
+ * interface is the dependency list the segment had implicitly.
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the hands
+ * mount before it and the question-face phase after it (a stretch with no await is extracted as
+ * a sync function). Read-stability of the host handles for the call: {@link RunInternals}
+ * (`@contract prepare.deps-read-stable`).
+ *
+ * The roster (`tools`) is borrowed-mutable here — the writer table lives on {@link Prepared.tools};
+ * this phase's rows are the eight mounts named above. `childPolicy` is NOT a seat yet: the
+ * delegation carriers still ride the enriched ctx's individual clamp fields, as they did in the driver.
+ */
 import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
 import { type PeerLaneRefs } from "../../agents/peer-session-drain.js";
 import type { SubagentRetainLedger } from "../../agents/retain-ledger.js";

package/dist/core/runner/prepare-delegation-surface.js

@@ -1,4 +1,3 @@
-import { randomBytes } from "node:crypto";
 import { createAgentTranscriptTool, AGENT_TRANSCRIPT_TOOL_NAME } from "../../agents/agent-transcript-tool.js";
 import { createSendMessageTool, SEND_MESSAGE_TOOL_NAME } from "../../agents/send-message-tool.js";
 import { listAgentsMountable, mountListAgents, peerLaneSendMessageSeats } from "../../agents/peer-session-drain.js";
@@ -11,30 +10,12 @@ import { createReadToolResultTool } from "../tool-result-store.js";
 import { emitTrace } from "../trace.js";
 import { deliverEngineNotice } from "../types.js";
 import { RosterBuilder } from "../tool-roster.js";
-function buildTier3ReviveSpawn(delegationForRevive, enrichSpecToolCtx) {
-    if (delegationForRevive === undefined)
-        return undefined;
-    return async (req) => {
-        const out = await delegationForRevive.execute({
-            description: req.row.description ?? "revived teammate",
-            prompt: req.prompt,
-            run_in_background: true,
-            ...(req.row.agentType !== undefined ? { subagent_type: req.row.agentType } : {}),
-            ...(req.row.name !== undefined ? { name: req.row.name } : {}),
-            ...(req.row.model !== undefined ? { model: req.row.model } : {}),
-        }, enrichSpecToolCtx({ toolCallId: `rv-${randomBytes(8).toString("hex")}`, reviveClaim: { row: req.row, rev: req.rev, ...(req.peerSeed !== undefined ? { peerSeed: req.peerSeed } : {}) } }));
-        const o = (typeof out === "string" ? { content: out } : out);
-        return {
-            content: typeof o.content === "string" ? o.content : JSON.stringify(o.content),
-            ...(o.isError === true ? { isError: true } : {}),
-            ...(o.details !== undefined ? { details: o.details } : {}),
-        };
-    };
-}
+import { sendMessageContinuationSeats } from "./send-message-continuation.js";
 export function prepareDelegationSurface(input) {
     const { spec, deps, internals, resume, sessionId, hostTaskId, taskScope, taskRootFinal, taskRootCanonical, executionEnv, runnerSelf, backgroundTaskToolsActive, workflowToolsActive, peerLaneActive, peerSendMessageBuiltIn, peerLaneRefs, sessionBox, roster, toolEffects, axisExplicitNegatives, envHandToolNames, toolFaceSnapshot, firstPartyOffload, offloadStore, subagentRetain, enrichSpecToolCtx, handsCwdRef, wsSnapshot, rebaseWsPath, rebaseRestoredPath, workspaceStateSettle } = input;
     let worktreeSessionRef;
     const delegationSurfaceActive = backgroundTaskToolsActive || workflowToolsActive;
+    let sendMessageTier;
     if (delegationSurfaceActive || internals?.parentNotify !== undefined || peerLaneActive) {
         if (delegationSurfaceActive) {
             roster.mountAll([
@@ -44,8 +25,8 @@ export function prepareDelegationSurface(input) {
         }
         if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
             axisExplicitNegatives.set(SEND_MESSAGE_TOOL_NAME, { ...axisExplicitNegatives.get(SEND_MESSAGE_TOOL_NAME), egress: false });
-            const delegationForRevive = (spec.tools ?? []).find((t) => t.agentListing !== undefined);
-            const reviveSpawn = deps.backgroundAgentStore !== undefined && deps.mailboxStore !== undefined ? buildTier3ReviveSpawn(delegationForRevive, enrichSpecToolCtx) : undefined;
+            const { reviveSpawn, tier } = sendMessageContinuationSeats({ specTools: spec.tools ?? [], agentStore: deps.backgroundAgentStore, mailbox: deps.mailboxStore, runner: runnerSelf, enrichSpecToolCtx });
+            sendMessageTier = tier;
             roster.mount(firstPartyOffload(createSendMessageTool({
                 runner: runnerSelf,
                 registry: defaultTaskRegistry,
@@ -103,7 +84,7 @@ export function prepareDelegationSurface(input) {
         toolEffects.set(READ_INBOX_TOOL_NAME, "read");
         roster.mount(firstPartyOffload(createReadInboxTool({ pull: () => peerLaneRefs.pull })), { source: "builtin", mountedBy: "peerLane" });
     }
-    const listAgents = (peerLaneActive || delegationSurfaceActive) && peerSendMessageBuiltIn && listAgentsMountable({ exclude: toolFaceSnapshot.exclude, specTools: spec.tools ?? [] }) ? mountListAgents({ ...(peerLaneActive ? { peerDirectory: deps.peerDirectory } : {}), freshWindowMs: resolvePeerLaneConfig(deps.peerLane, deps.onNotice).listingFreshWindowMs, sessionId, scope: taskScope, hostTaskId, ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}), ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}), registry: defaultTaskRegistry, ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}), specTools: spec.tools ?? [], toolEffects }) : undefined;
+    const listAgents = (peerLaneActive || delegationSurfaceActive) && peerSendMessageBuiltIn && listAgentsMountable({ exclude: toolFaceSnapshot.exclude, specTools: spec.tools ?? [] }) ? mountListAgents({ ...(peerLaneActive ? { peerDirectory: deps.peerDirectory } : {}), freshWindowMs: resolvePeerLaneConfig(deps.peerLane, deps.onNotice).listingFreshWindowMs, sessionId, scope: taskScope, hostTaskId, ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}), ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}), registry: defaultTaskRegistry, ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}), ...(sendMessageTier !== undefined ? { continuationTier: sendMessageTier } : {}), specTools: spec.tools ?? [], toolEffects }) : undefined;
     if (listAgents !== undefined)
         roster.mount(firstPartyOffload(listAgents), { source: "builtin", mountedBy: "peerLane" });
     if (backgroundTaskToolsActive) {
@@ -118,7 +99,7 @@ export function prepareDelegationSurface(input) {
             ...(handsCwdRef !== undefined ? { cwdRef: handsCwdRef } : {}),
             rootCanonical: taskRootCanonical,
             ...(offloadStore !== undefined ? { toolResultStore: offloadStore } : {}),
-            ...(spec.retainBackgroundProcesses === true ? { retainBackgroundProcesses: true } : {}),
+            retainBackgroundProcesses: spec.retainBackgroundProcesses === true,
         })), { source: "builtin", mountedBy: "backgroundTasks" });
     }
     if (handsCwdRef !== undefined) {

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -5,6 +5,7 @@ import type { RunnerDeps, ShellGateDoctrine, TaskSpec } from "../types.js";
 import type { Model } from "../../internal/llm.js";
 import type { AgentHarness, AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
 import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
+import { type ArtifactStoreRef, type GrantReadRoot } from "./read-root-grant.js";
 import type { StoredSession } from "../session.js";
 import type { IrreversibilityTier, PrepareResume, ReversibilityProbes, RunInternals, ToolFaceSnapshot, ToolProgressLane } from "./contracts.js";
 import { RosterBuilder } from "../tool-roster.js";
@@ -14,91 +15,6 @@ import { RosterBuilder } from "../tool-roster.js";
  *  the console arm's key is the process itself, which only this seam can refresh. Moved WITH the
  *  phase; prepare-task.ts keeps a re-export so the existing import sites stand. */
 export declare function __resetReadFaceClampAnnouncement(): void;
-/**
- * The Runner's per-session read-file-state seats (CC parity: readFileState is minted
- * once per REPL session and mutated across turns; it has NO turn-boundary and NO abort clear site —
- * its only clears are compaction/fork/subagent-cleanup/dispose). sema's map stays per-task (the §11
- * ruling-A closure wiring), so the SESSION scope lives here instead: prepare adopts each task's live
- * map under its sessionId, and the next same-session, same-Runner task INHERITS it (through the same
- * containment judgment the transcript-replay seed applies — see `inheritSessionReadFileState`).
- *
- * This seat is a CACHE, never an authority:
- *  - a durable resume's checkpoint seed stays the sole authority on that leg (the seed was cut
- *    atomically with the leaf; this seat may be older OR newer than it);
- *  - a cross-process continuation misses here and falls back to the transcript replay (rung-2);
- *  - eviction (the LRU cap, a Runner restart) degrades to that same replay — never to wrong state.
- *
- * Bounded: an LRU over sessionIds (insertion-order refresh on read), because the SessionStore's own
- * eviction is not observable from here — a dropped seat costs one transcript replay, nothing else.
- * The stored value is the task's LIVE map (object identity), so in-turn mutations — tool write-backs,
- * and above all the compaction clear — are the seat's truth by construction; a snapshot copy
- * here would resurrect summarized-away reads on the next turn.
- *
- * BRANCH BINDING: a sessionId alone does not name a transcript — the same id
- * can be rebranched (`resumeAt`), rewound out-of-band, or DELETED and re-created (`release()` + the
- * default create-on-miss acquire), and the seat's map would then vouch for reads the CURRENT branch
- * never saw. Each seat therefore records `anchorLeafId` — a leaf on the lineage its task produced —
- * and inheritance must first prove the CURRENT branch still descends from that anchor
- * (see {@link sessionSeatAnchorHolds}). The anchor is written twice: at ADOPT (the leaf at prepare;
- * `null` when the branch was still empty) and SEALED at the task's settle to the task's own tail
- * (`reanchor`). A `null` anchor is NEVER inheritable ("the branch is non-empty now" proves
- * nothing about WHOSE messages those are — another Runner repopulating a released id, or a session
- * import, makes a non-empty branch that never contained this seat's reads). An unprovable anchor
- * falls back to the transcript replay, which reads the current branch by construction — cost, never
- * wrongness.
- */
-export declare class SessionReadFileStates {
-    private readonly seats;
-    private static readonly CAP;
-    /** The session's seat row, or undefined (cross-process / evicted / first turn) ⇒ caller replays.
-     *  The caller must verify the anchor against the session's CURRENT branch before using `state`. */
-    get(sessionId: string): {
-        state: ReadFileState;
-        anchorLeafId: string | null;
-    } | undefined;
-    /** Adopt THIS task's live map as the session's seat (every hands leg: fresh, continuation, resume).
-     *  `anchorLeafId` = the session's leaf as read at THIS prepare (null = the branch was empty; a
-     *  null-anchored seat is not inheritable until the settle-time {@link reanchor} names a real leaf). */
-    adopt(sessionId: string, state: ReadFileState, anchorLeafId: string | null): void;
-    /** The settle-time SEAL: re-anchor the seat to the finished task's own tail, so a
-     *  first-task (null-anchor) seat becomes inheritable only through a leaf its task provably wrote.
-     *  Identity-guarded: touches the row only while it still holds THIS task's map (a later prepare on
-     *  the same session has already replaced the seat and owns its own anchor). */
-    reanchor(sessionId: string, state: ReadFileState, anchorLeafId: string): void;
-}
-/**
- * Does the session's CURRENT branch still descend from the seat's anchor?
- * TRUE is the licence to inherit; anything unprovable answers FALSE (the caller then replays the
- * transcript — the fail-closed direction costs a rebuild, never admits a wrong entry).
- *
- *  - anchor `null`: NEVER inheritable (r2). The seat was adopted on an empty branch and its task
- *    never sealed (crashed pre-settle, or the leaf read failed) — "the branch is non-empty now"
- *    would also be true of a released-and-repopulated id or an imported log, whose messages are not
- *    this seat's lineage. The settle-time reanchor is what upgrades such a seat to a real leaf.
- *  - anchor non-null: holds iff walking parentIds from the current leaf reaches the anchor within
- *    a bounded number of steps (the walk length is one task's appends in the ordinary continuation).
- *    A rebranch/rewind moved the leaf OFF the anchor's subtree ⇒ the walk misses ⇒ no inherit; a
- *    recreated/foreign log does not contain the anchor ⇒ same answer; a re-IMPORT of the same log
- *    keeps the anchor's lineage ⇒ inheritance stays correct there by the same test.
- *  - a COMPACTION on the walked segment (A-082 idx2): refuses, even though the branch is perfectly
- *    intact. The walked segment is exactly what landed AFTER this seat was anchored, and a
- *    compaction there summarized older Read results OUT of the context the model will be shown —
- *    the very state the compaction clear removes from the live map at the landing site. That clear reaches the seat
- *    only when the SAME Runner did both (the seat IS that map, by object identity); a second Runner
- *    on the shared durable session clears its own map and commits the compaction as an ORDINARY
- *    LINEAR APPEND, which every other test here passes. Inheriting across it would let requireRead
- *    and checkStale both pass on a read whose card the model no longer has — a blind edit from a
- *    summarized-away recollection, the exact failure the compaction clear exists to prevent. Refusing
- *    costs one transcript replay, and the replay reads the POST-compaction branch by construction,
- *    so the fail-closed direction is also the CORRECT state. A compaction at or ABOVE the anchor is
- *    not on the walked segment and does not refuse: the seat that observed it already carries its
- *    clear (P-483-4), and an ordinary foreign turn with no compaction still inherits (G-483-5) —
- *    dropping every seat a foreign Runner touched would restore the cross-turn read-state amnesia this seat-anchor check already ended.
- */
-export declare function sessionSeatAnchorHolds(getEntry: (id: string) => Promise<{
-    parentId: string | null;
-    type?: string;
-} | null | undefined>, anchorLeafId: string | null, currentLeafId: string | null): Promise<boolean>;
 export interface PrepareHandsReadFaceInput {
     /** owned (value) — `ownedEnv !== undefined || deps.executionEnv !== undefined`, computed in the
      *  driver: the phase's own branch condition (hands mount vs the hands-less resolver arm). */
@@ -149,8 +65,9 @@ export interface PrepareHandsReadFaceInput {
      *  (the Read tool's document-degradation fork). */
     model: Model;
     /** borrowed-readonly — the task-spec seats this phase reads, as a Pick over the SAME spec object
-     *  (R-4). `tools` feeds only the band shadow check; `envFacts` only the advertised scratchpad. */
-    spec: Pick<TaskSpec, "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "handsReadOnly" | "readDenyPatterns" | "readFace" | "writeFace" | "oneShot" | "resumeAt" | "sessionId" | "tools">;
+     *  (R-4). `tools` feeds only the band shadow check; `envFacts` only the advertised scratchpad;
+     *  `retainBackgroundProcesses` only the band's retain lane (Bash's lifetime sentence + row stamp). */
+    spec: Pick<TaskSpec, "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "handsReadOnly" | "readDenyPatterns" | "readFace" | "writeFace" | "oneShot" | "resumeAt" | "retainBackgroundProcesses" | "sessionId" | "tools">;
     /** borrowed-readonly — the deployment seats this phase reads, as a Pick over the SAME deps
      *  object (R-4: `deps.onError?.()` keeps its receiver; a new deps read must widen this Pick).
      *  `readDenyBuiltinTiers`/`readDenyBuiltinExclude` are SNAPSHOTTED before the first await that
@@ -302,8 +219,14 @@ export interface PrepareHandsReadFaceResult {
      *  ARRAY identity. Settled here (no mutation after return). */
     additionalRootsCanonical: string[];
     /** owned — the read-only arm of the fence widening (2026-08-05 both-arms ruling); same identity
-     *  contract as above. */
+     *  contract as above, and the run's LIVE read-root set: {@link grantReadRoot} is its one writer after prepare,
+     *  and every read face reads it per call (never a copy). */
     additionalReadRootsCanonical: string[];
+    /** owned — widen {@link additionalReadRootsCanonical} by one granted candidate (an approver's in-flight
+     *  `readRootGrant`); undefined ⇔ hands-less (no read face to widen). */
+    grantReadRoot: GrantReadRoot | undefined;
+    /** owned — the store cell {@link grantReadRoot} judges against; the driver threads it to its one writer, the Artifact phase. */
+    artifactStoreRef: ArtifactStoreRef | undefined;
     /** owned — the canonical containment root, published so the working-file ATTACHMENT
      *  reader applies the same containment the hands tools do. Undefined ⇔ hands-less. */
     attachmentRootCanonical: string | undefined;
@@ -326,7 +249,7 @@ export interface PrepareHandsReadFaceResult {
      *  a hands-less leg (nothing mounts on the env; the driver's env mounts are hands-gated too). */
     envHandToolNames: Set<string>;
     /** owned — the settle-time SEAT SEAL: re-anchors the session seat to the
-     *  task's OWN last-committed entry (see {@link SessionReadFileStates.reanchor}). The driver calls
+     *  task's OWN last-committed entry (see {@link import("./session-read-file-states.js").SessionReadFileStates.reanchor}). The driver calls
      *  it once at the run's settle (every terminal, suspend included), under the session lock, passing
      *  the last entryId ITS OWN run committed (the message_committed lane) — never a re-read of the
      *  shared session leaf, which a concurrent writer on another Runner could have moved onto a branch