@sema-agent/core 7.31.1 → 7.32.1

package/dist/core/runner/prepare-hands-readface.js

@@ -10,6 +10,8 @@ import { createShellReadStation } from "../../tools/fs/shell-read-check.js";
 import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
 import { deliverEngineNotice } from "../types.js";
+import { readRootGrantOver } from "./read-root-grant.js";
+import { sessionSeatAnchorHolds } from "./session-read-file-states.js";
 import { rebaseWorkspacePath } from "./workspace-path.js";
 import { RosterBuilder } from "../tool-roster.js";
 const faceClampAnnouncedSinks = { read: new WeakSet(), write: new WeakSet() };
@@ -31,49 +33,6 @@ export function __resetReadFaceClampAnnouncement() {
     faceClampConsoleAnnounced.read = false;
     faceClampConsoleAnnounced.write = false;
 }
-export class SessionReadFileStates {
-    seats = new Map();
-    static CAP = 1024;
-    get(sessionId) {
-        const seat = this.seats.get(sessionId);
-        if (seat !== undefined) {
-            this.seats.delete(sessionId);
-            this.seats.set(sessionId, seat);
-        }
-        return seat;
-    }
-    adopt(sessionId, state, anchorLeafId) {
-        this.seats.delete(sessionId);
-        this.seats.set(sessionId, { state, anchorLeafId });
-        while (this.seats.size > SessionReadFileStates.CAP) {
-            const oldest = this.seats.keys().next().value;
-            if (oldest === undefined)
-                break;
-            this.seats.delete(oldest);
-        }
-    }
-    reanchor(sessionId, state, anchorLeafId) {
-        const seat = this.seats.get(sessionId);
-        if (seat !== undefined && seat.state === state)
-            seat.anchorLeafId = anchorLeafId;
-    }
-}
-export async function sessionSeatAnchorHolds(getEntry, anchorLeafId, currentLeafId) {
-    if (anchorLeafId === null)
-        return false;
-    let id = currentLeafId;
-    for (let steps = 0; id !== null && steps < 100_000; steps++) {
-        if (id === anchorLeafId)
-            return true;
-        const entry = await getEntry(id);
-        if (entry === null || entry === undefined)
-            return false;
-        if (entry.type === "compaction")
-            return false;
-        id = entry.parentId;
-    }
-    return false;
-}
 function assertStringArraySeat(value, seat, entryLaw) {
     if (value === undefined)
         return;
@@ -149,6 +108,8 @@ export function resolveHandsLessReadFace(input) {
         handsLessResolvedWriteFace,
         additionalRootsCanonical: [],
         additionalReadRootsCanonical: [],
+        grantReadRoot: undefined,
+        artifactStoreRef: undefined,
         attachmentRootCanonical: undefined,
         readDenyMatcher: undefined,
         envHandToolNames: new Set(),
@@ -181,6 +142,8 @@ export async function prepareHandsMount(input) {
     const shellGatedTools = new Set();
     const additionalRootsCanonical = [];
     const additionalReadRootsCanonical = [];
+    let grantReadRoot;
+    const artifactStoreRef = { current: undefined };
     let attachmentRootCanonical;
     let readDenyMatcher;
     if (handsEnabled) {
@@ -220,6 +183,7 @@ export async function prepareHandsMount(input) {
         }
         for (const a of [additionalRootsCanonical, additionalReadRootsCanonical])
             a.splice(0, a.length, ...new Set(a));
+        grantReadRoot = readRootGrantOver({ env: executionEnv, writeRoots: additionalRootsCanonical, readRoots: additionalReadRootsCanonical, artifactStore: artifactStoreRef });
         const readFileState = new Map((resume?.seed.readFileState ?? []).map(([k, v]) => [rebaseRestoredPath(k), v]));
         readFileStateForCheckpoint = readFileState;
         seedContextFiles = async (files) => {
@@ -341,19 +305,18 @@ export async function prepareHandsMount(input) {
             ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
         });
         if (handsIncludeShell) {
-            const readonlyBoundary = handsReadOnly
-                ? { roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical], cwd: rootCanonical, ...denySeat, alsoInside: createShellOverflowSpoolFence(executionEnv) }
-                : undefined;
+            const spoolFence = handsReadOnly ? createShellOverflowSpoolFence(executionEnv) : undefined;
+            const readonlyBoundary = () => spoolFence !== undefined ? { roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical], cwd: rootCanonical, ...denySeat, alsoInside: spoolFence } : undefined;
             shellReadStation = createShellReadStation({
                 env: executionEnv,
                 tools: new Set(handsReadOnly ? ["Bash"] : backgroundTaskToolsActive ? ["Bash", "Monitor"] : ["Bash"]),
                 seatOf: () => (handsReadOnly ? "readonly" : effectiveShellGate === "classify" ? "bash_classify" : "bash_off"),
-                boundaryOf: () => readonlyBoundary ?? shellReadBoundary(),
+                boundaryOf: () => readonlyBoundary() ?? shellReadBoundary(), rootsCanonical: true,
             });
         }
         const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
             ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
-            ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
+            additionalReadRoots: additionalReadRootsCanonical,
             ...(readDenyAdditions.length > 0 ? { readDenyPatterns: readDenyAdditions } : {}),
             ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
             ...(readDenyBuiltinCfg.exclude !== undefined ? { readDenyBuiltinExclude: readDenyBuiltinCfg.exclude } : {}),
@@ -372,6 +335,7 @@ export async function prepareHandsMount(input) {
             taskScope,
             oneShot: spec.oneShot,
             ...(sessionId !== undefined ? { sessionId } : {}),
+            retainBackgroundProcesses: spec.retainBackgroundProcesses === true,
             ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
             ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
             onToolProgress: (body) => input.toolProgressRef.current?.emit(body),
@@ -449,6 +413,8 @@ export async function prepareHandsMount(input) {
         handsLessResolvedFace,
         additionalRootsCanonical,
         additionalReadRootsCanonical,
+        grantReadRoot,
+        artifactStoreRef,
         attachmentRootCanonical,
         readDenyMatcher,
         envHandToolNames,

package/dist/core/runner/prepare-inherited-gate.d.ts

@@ -44,7 +44,7 @@ import type { DelegationContentSafety } from "../memory-engine/delegation-proven
 import { type SessionPermissionRules } from "../session-policy-store.js";
 import type { SessionStore } from "../session.js";
 import { type OnAsk } from "../tool-policy.js";
-import type { ApproverPosture, RunnerDeps, RuntimeCaps, ShellGateDoctrine, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";
+import type { ApproverPosture, RunnerDeps, RuntimeCaps, ShellGateDoctrine, TaskEvent, TaskSpec, ToolExecuteContext, ToolSpec } from "../types.js";
 import type { ActiveSkillScope } from "./active-skill-scope.js";
 import type { InheritedGate, Prepared, PrepareResume, RunInternals, StopForDenialLimit, ToolFaceSnapshot } from "./contracts.js";
 export interface PrepareInheritedGateInput {
@@ -89,6 +89,8 @@ export interface PrepareInheritedGateInput {
     /** borrowed-readonly — the frozen tool-face snapshot (the ctx forwards exclude / defer / alwaysLoad / restoreGated; the
      *  full-shell predicate reads the exclusion of Bash). */
     toolFaceSnapshot: ToolFaceSnapshot;
+    /** borrowed-readonly — the ctx's `mountsCallerTool` seat: identity membership in the caller's `spec.tools`, pre-gate. */
+    mountsCallerTool: (tool: ToolSpec) => boolean;
     /** borrowed-readonly — the resolved prompt profile (ctx seat). */
     promptProfile: ToolExecuteContext["promptProfile"];
     /** borrowed-readonly — the resolved interaction posture (ctx seat; absent ⇒ no key). */

package/dist/core/runner/prepare-inherited-gate.js

@@ -8,7 +8,7 @@ import { askApproverIdentity, durableMandateSourceOf } from "../tool-policy.js";
 import { attachRebuiltDenialTrackers, createDenialLimitStop } from "./denial-limit-arms.js";
 import { asThrownError } from "../thrown-value.js";
 export function prepareInheritedGate(input) {
-    const { spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, autoModeSeat, approverPostureSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun } = input;
+    const { spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, toolFaceSnapshot, mountsCallerTool, promptProfile, resolvedInteractionPosture, autoModeSeat, approverPostureSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun } = input;
     const liveInheritedGate = internals?.inheritedGate;
     const seedInheritedGate = resume?.seed.inheritedGate;
     const inheritedAncestorRules = (() => {
@@ -205,6 +205,7 @@ export function prepareInheritedGate(input) {
             ...(readDenyAdditionsNormalized.length > 0 ? { readDenyPatterns: Object.freeze(readDenyAdditionsNormalized.map((e) => ({ ...e }))) } : {}),
             ...(spec.interactiveTools === false ? { interactiveTools: false } : {}),
             oneShot: spec.oneShot,
+            mountsCallerTool,
             parentSpecSeat,
             ...(internals?.questionFaceStripped === true ? { questionFaceStripped: true } : {}),
             excludeTools: toolFaceSnapshot.exclude,

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

@@ -1,7 +1,7 @@
 import { uuidv7 } from "../../engine/session/uuid.js";
 import { Value } from "typebox/value";
 import { ASK_USER_QUESTION_TOOL_NAME, classifyQuestionOutcome, validateAskQuestions } from "../ask-question.js";
-import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
+import { hasBackgroundShell, sweepBackgroundShells, sweepRunBoundaryBackgroundShells } from "../background-shell.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { buildRiskDescriptor, checkpointVersionFor, debitLedger, encodeAtFidelity, mintCheckpointId, mintCheckpointToken, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
 import { pauseOf } from "../pause-registry.js";
@@ -229,8 +229,8 @@ export function prepareParkAsk(input) {
                     }
                 }
                 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);
                 }
                 token = mintCheckpointToken();
@@ -277,8 +277,10 @@ export function prepareParkAsk(input) {
                 }
                 const approvalLedger = debitLedger(priorLedger, liveSpendRef.get?.() ?? { costMicroUsd: 0, tokens: 0, turns: 0, walltimeMs: 0 }, resourceTotal, { countSlice: false });
                 const rowMatchedAskRule = matchedAskRule ?? storedShapeFacts?.matchedAskRule;
+                const storedShapeMandated = askMandateMember(storedShapeFacts).mandated === true;
                 const clearanceFacts = {
-                    ...(carry?.mandated === true || askMandateMember(storedShapeFacts).mandated === true ? { mandated: true } : {}),
+                    ...(carry?.mandated === true || storedShapeMandated ? { mandated: true } : {}),
+                    ...(carry?.mandate !== undefined && !storedShapeMandated ? { mandate: carry.mandate } : {}),
                     ...(rowRealApproval !== undefined ? { requiresRealApproval: true } : {}),
                     ...(shadowedRule !== undefined ? { persistedRuleShadowed: shadowedRule } : {}),
                     ...(askDecisionReason !== undefined ? { decisionReason: askDecisionReason } : {}),

package/dist/core/runner/prepare-policy-chain.js

@@ -13,6 +13,7 @@ import { createActiveSkillScopePolicy } from "./active-skill-scope.js";
 import { askMandateMember, probeMandatedAsk } from "../ask-origin.js";
 const ancestorFacts = (ask) => ({ ...(ask ?? {}), ancestorResolved: true });
 import { headlessDenyAtFold, headlessDenyAtRecheck, inheritedAskCarry, judgeInheritedClassifier, lateAskSettlementObserver, settleDenialLimitFallback } from "./denial-limit-arms.js";
+import { settleReadRootGrant } from "./read-root-grant.js";
 import { askGrantShapeOf } from "./inherited-ask-grants.js";
 import { createPermissionRuleLanes, inheritedAskRuleEvidence, createRuleOffersOf } from "./permission-rule-lanes.js";
 import { createLiveSessionRules, createSessionRulePolicy } from "./session-rule-policy.js";
@@ -360,6 +361,7 @@ export async function preparePolicyChain(input) {
                 ...inheritedAskCarry(judged, isLiveApproverSeat(onAskOf), ancestorTracker),
                 ruleEvidence: inheritedAskEvidence,
             }, onAskOf, csignal ?? abortController.signal, lateAskSettlementObserver({ toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
+            void settleReadRootGrant(rr.readRootGrant, undefined, { toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice });
             settleDenialLimitFallback({ fallback: editFallback, mintedHere: editMintedHere, tracker: ancestorTracker, resolved: rr, headless: headlessDenyAtRecheck, stop: stopForDenialLimit, toolName: creq.toolName, toolCallId: creq.toolCallId });
             if (rr.action !== "allow")
                 return rr;
@@ -436,6 +438,7 @@ export async function preparePolicyChain(input) {
                         ...inheritedAskCarry(judged, isLiveApproverSeat(pc.onAsk), pc.autoMode?.denialTracking),
                         ruleEvidence: inheritedAskEvidence,
                     }, pc.onAsk, csignal ?? abortController.signal, lateAskSettlementObserver({ toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
+                    void settleReadRootGrant(resolved.readRootGrant, undefined, { toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice });
                     const askWaitMs = Math.max(0, now() - askT0);
                     if (resolved.action === "deny" && resolved.approverUnavailable === true) {
                         if (markInheritedUnavailable(creq.toolCallId))
@@ -506,6 +509,7 @@ export async function preparePolicyChain(input) {
                         ...inheritedAskCarry(judged, isLiveApproverSeat(pc.onAsk), pc.autoMode?.denialTracking),
                         ruleEvidence: inheritedAskEvidence,
                     }, pc.onAsk, csignal ?? abortController.signal, lateAskSettlementObserver({ toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
+                    void settleReadRootGrant(resolved.readRootGrant, undefined, { toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice });
                     const askWaitMs = Math.max(0, now() - askT0);
                     if (resolved.action === "deny" && resolved.approverUnavailable === true) {
                         if (markInheritedUnavailable(creq.toolCallId))

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

@@ -7,6 +7,7 @@ import { uuidv7 } from "../../engine/session/uuid.js";
 import { brainToRuntime } from "../runtime.js";
 import { hasSessionFork } from "../session.js";
 import { SEND_MESSAGE_TOOL_NAME } from "../../agents/send-message-tool.js";
+import { callerToolMembership } from "../../agents/inherited-tool-pool.js";
 import { loadAnnounceOnceLedger } from "./announce-once-ledger.js";
 import { isValidReminderMark, mintReminderMark } from "../reminder-mint.js";
 import { refuseInvalidApproverPosture } from "../auto-mode-directive.js";
@@ -271,6 +272,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const runId = uuidv7();
     if (runIdSink !== undefined)
         runIdSink.runId = runId;
+    const mountsCallerTool = callerToolMembership(spec.tools);
     const doors = prepareConfigDoors({ spec, deps, sessions, resume, internals });
     spec = doors.spec;
     const checkpointStore = resolveCheckpointStore(spec, deps), checkpointSeat = checkpointSeatOf(spec, checkpointStore);
@@ -390,7 +392,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         let readDenyAdditionsNormalized = [];
         let handsLessResolvedFace;
         let handsLessResolvedWriteFace;
-        const { liveInheritedGate, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, inheritedParentConstraints, autoModeIntent, approverPosture: approverPostureResolved, inheritedAdmittedOrgScopes, priorOwnOrgVerdict, orgGovernedProvenance, effectiveShellGate, ownSessionRulesRef, ancestorSessionRulesRef, ancestorRulesNow, memoryAdmittedOrgScopesRef, ownOrgVerdictRef, orgAdmissionCheckpointState, faceCheckpointSection, faceCheckpointState, writeFaceCheckpointSection, f012CheckpointState, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, frozenOnQuestion, parentSpecSeat, provenanceForChildrenRef, delegationSettlementRef, inheritedGateForChildren, carrierReadFace, carrierWriteFace, fullShellReachable, gateStopRef, stopForDenialLimit, enrichSpecToolCtx } = prepareInheritedGate({ spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, checkpointSeat, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, autoModeSeat, approverPostureSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun: () => { abortController.abort(); void harness.abort(); }, runtimeCaps: () => runtimeCaps, hooks: () => hooks, preToolUseObservational: () => preToolUseObservational, hookTimeoutMs: () => hookTimeoutMs, hookEnvFace: () => hookEnvFace, autoModeDecider: () => autoModeDecider, autoModeDenialTracking: () => autoModeDenialTracking, autoModeArming: () => autoModeArming, agentForkDenial: () => agentForkDenial, observersActive: () => observersActive, resolvedReadFace: () => resolvedReadFace, resolvedWriteFace: () => resolvedWriteFace, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized, handsLessResolvedFace: () => handsLessResolvedFace, handsLessResolvedWriteFace: () => handsLessResolvedWriteFace, centerAdoption: () => centerAdoptionRef.current, memoryEngineSession: () => memoryEngineSession });
+        const { liveInheritedGate, seedInheritedGate, inheritedAncestorRules, inheritedShellGate, inheritedParentConstraints, autoModeIntent, approverPosture: approverPostureResolved, inheritedAdmittedOrgScopes, priorOwnOrgVerdict, orgGovernedProvenance, effectiveShellGate, ownSessionRulesRef, ancestorSessionRulesRef, ancestorRulesNow, memoryAdmittedOrgScopesRef, ownOrgVerdictRef, orgAdmissionCheckpointState, faceCheckpointSection, faceCheckpointState, writeFaceCheckpointSection, f012CheckpointState, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, frozenOnQuestion, parentSpecSeat, provenanceForChildrenRef, delegationSettlementRef, inheritedGateForChildren, carrierReadFace, carrierWriteFace, fullShellReachable, gateStopRef, stopForDenialLimit, enrichSpecToolCtx } = prepareInheritedGate({ spec, deps, internals, resume, sessions, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, ownedEnv, lockedPreflight, checkpointSeat, toolFaceSnapshot, mountsCallerTool, promptProfile, resolvedInteractionPosture, autoModeSeat, approverPostureSeat, handsEnabled, reportUsage, harnessRef, skillScope, forwardEvent, subagentRetain, worktreeIsolation, requestReview, requestStopAfterTurn, enterPlanMode, reminderMark, reminderDisclosureCounts, fileHistoryEnabled, historyScope, historyRoot, historyFs, abortRun: () => { abortController.abort(); void harness.abort(); }, runtimeCaps: () => runtimeCaps, hooks: () => hooks, preToolUseObservational: () => preToolUseObservational, hookTimeoutMs: () => hookTimeoutMs, hookEnvFace: () => hookEnvFace, autoModeDecider: () => autoModeDecider, autoModeDenialTracking: () => autoModeDenialTracking, autoModeArming: () => autoModeArming, agentForkDenial: () => agentForkDenial, observersActive: () => observersActive, resolvedReadFace: () => resolvedReadFace, resolvedWriteFace: () => resolvedWriteFace, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized, handsLessResolvedFace: () => handsLessResolvedFace, handsLessResolvedWriteFace: () => handsLessResolvedWriteFace, centerAdoption: () => centerAdoptionRef.current, memoryEngineSession: () => memoryEngineSession });
         const { roster, blockedRef, runtimeCaps, runtimeCapsFaulted, complianceDenies, complianceDegraded, agentForkDenial, observersActive, autoModeArmReason, autoModeDecider, autoModeDenialTracking, autoModeArming, selfOrchestrationActive, workflowToolsActive, workflowSizeGuideline } = await prepareCapsAndWorkflow({ spec, deps, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, checkpointSeat, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, parentSpecSeat, carrierReadFace, carrierWriteFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf, memoryEngineSession: () => memoryEngineSession, centerAdoption: () => centerAdoptionRef.current, readDenyAdditionsNormalized: () => readDenyAdditionsNormalized });
         const tools = roster.tools;
         const pausedRef = {};
@@ -557,7 +559,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 `(per-principal entitlement governance, not a misconfiguration — Agent(subagent_type:"fork") will refuse honestly)`), { phase: "config", sessionId });
         }
         const { lspDiagnostics, nudgeLspOnEdit, lspRunIdent, managerWired: lspManagerWired } = prepareLsp({ spec, deps, executionEnv, taskRootFinal, handsEnabled, sessionId, handsCwdRef, roster, envHandToolNames });
-        prepareArtifact({ deps, runId, taskId: hostTaskId, sessionId, agentName: internals?.explicitAgentName, onAsk: frozenOnAsk, executionEnv, rootCanonical: attachmentRootCanonical, additionalRootsCanonical: [...additionalRootsCanonical, ...additionalReadRootsCanonical], readDenyMatcher, resolvedReadFace, handsCwdRef, roster, firstPartyOffload, envHandToolNames });
+        prepareArtifact({ deps, runId, taskId: hostTaskId, sessionId, agentName: internals?.explicitAgentName, onAsk: frozenOnAsk, executionEnv, rootCanonical: attachmentRootCanonical, additionalRootsCanonical: () => [...additionalRootsCanonical, ...additionalReadRootsCanonical], readDenyMatcher, resolvedReadFace, handsCwdRef, roster, firstPartyOffload, envHandToolNames, ...(handsReadFace.artifactStoreRef !== undefined ? { artifactStoreRef: handsReadFace.artifactStoreRef } : {}) });
         if (internals?.delegationProvenance !== undefined && resume !== undefined) {
             const live = internals.delegationProvenance.ref.current;
             const seed = resume.seed.delegationProvenance;
@@ -716,7 +718,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 return undefined;
             });
         }
-        const { askLane } = prepareAskLane({ gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, advertisedWritableDirs, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash });
+        const { askLane } = prepareAskLane({ gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, advertisedWritableDirs, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash, grantReadRoot: handsReadFace.grantReadRoot });
         const { saga } = prepareSuspendSaga({ gateMachineryActive, abortController, harness, checkpointStore, deps, sessionId, hostTaskId, taskScope, liveSpendRef, resume, nestedStats, internals, activeTools, outputRef, readFileStateForCheckpoint, faceCheckpointSection, writeFaceCheckpointSection, reminderMark, handsCwdRef, worktreeSessionRef, undeliveredContinuationRef, inheritedParentConstraints, seedInheritedGate, ancestorRulesNow, inheritedShellGate, autoModeIntent, approverPosture: approverPostureResolved, inheritedAdmittedOrgScopes, ownOrgVerdictRef, orgGovernedProvenance, announcedListingsRef, gitStatusRef, hookIdentity, placementRootResolved, externalContentTargetActive, remoteEnvFailures, memoryEngineSession, suspendLoopRef, ownedEnv, incompleteSuspendAdapter });
         const { suspendForResource, suspendForPlatformLimit, suspendForReview } = prepareBoundaryParks({ saga, spec, checkpointStore, abortController, harness, session, sessions, sessionId, deps, priorLedger, maxSlices, maxSuspends, resourceTotal, priorSuspendCount, suspendChainBase, humanReviewRef, liveSpendRef, now, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, pausedRef, remoteEnvFailures, resourceSuspendEligible, durableSuspendInfraReady, incompleteSuspendAdapter });
         const { parkAsk } = prepareParkAsk({ askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas: rosterSeat, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, advertisedWritableDirs, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedTools, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef });

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

@@ -0,0 +1,66 @@
+/** The run's IN-FLIGHT read-root grant: the one place a screened grant ({@link ReadRootGrantScreen}) widens this run's
+ *  read directories (through the hands phase's {@link GrantReadRoot}, built by {@link readRootGrantOver}), the one
+ *  composer of the two notices, and the home of the store-isolation rule both root admission points judge by (the
+ *  Artifact phase's mount and the grant) — machinery both phases reach down for. */
+import type { ExecutionEnv } from "../../internal/harness.js";
+import type { ReadRootGrantCandidate } from "../types.js";
+import type { ReadRootGrantScreen } from "../read-root-grant-screen.js";
+import { type RunnerDeps } from "../types.js";
+/**
+ * THE store-isolation rule, one judgment for every root admission point (the Artifact mount over the prepare-time
+ * roots, an in-flight read-root grant over the granted root): a root that CONTAINS the local artifact store, lies
+ * INSIDE it, or IS it hands the file tools the store's ledger and stored files. Returns the first such root, or
+ * undefined.
+ *
+ * `storePhysical` is the store's physical path on THIS process's filesystem (`physicalPathOfExisting`, resolved
+ * once per run by the Artifact phase); a root is the execution env's canonical key. The judgment touches no
+ * filesystem — the grant runs after the approver's wait under the call's cut, and a synchronous lookup on a stalled
+ * store mount would block the event loop past that cut. The two are compared as identities 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 claim is made against it.
+ */
+export declare function rootAdmittingArtifactStore(storePhysical: string, rootsCanonical: readonly string[]): string | undefined;
+/** The run's cell holding the local artifact store a granted root must never admit (its physical path, as the
+ *  Artifact phase resolved it): minted with the grant by the hands phase, written by the Artifact phase (the one
+ *  reader of the hosting seat) once the declaration validates. */
+export interface ArtifactStoreRef {
+    current: string | undefined;
+}
+/** Why the run's station applied no grant: the spelling did not resolve (or its lookup was cut), it no longer
+ *  resolves to itself (a directory swapped for a link while the card waited), or it would admit the local artifact
+ *  store (the store-isolation rule the Artifact phase judges its mount by). */
+type GrantRefusal = "unresolvable" | "resolves_elsewhere" | "admits_artifact_store";
+/** Widen THIS run's live read roots by one granted candidate: the offered spelling must still be its own canonical
+ *  form and must not admit the local artifact store, then one deduplicated push; `root` = the spelling held. Nothing
+ *  is pushed once `signal` has fired (a late lookup never widens). */
+export type GrantReadRoot = (candidate: ReadRootGrantCandidate, signal: AbortSignal) => Promise<{
+    ok: true;
+    root: string;
+} | {
+    ok: false;
+    reason: GrantRefusal;
+    cause: string;
+}>;
+/** The hands phase's {@link GrantReadRoot} over the run's live root arrays: the offered spelling must still be its own
+ *  canonical form, must not admit the store in `artifactStore` ({@link rootAdmittingArtifactStore}), then ONE
+ *  deduplicated push onto `readRoots` (the live read set every read face reads per call); the write roots are only
+ *  consulted for the dedup, never widened. */
+export declare function readRootGrantOver(seats: {
+    env: Pick<ExecutionEnv, "canonicalPath">;
+    writeRoots: readonly string[];
+    readRoots: string[];
+    artifactStore: ArtifactStoreRef;
+}): GrantReadRoot;
+/** Act on one screened grant: `granted` widens through `grant` (absent on a station that cannot widen — an inherited
+ *  ask, a hands-less leg) and is announced; every other outcome changes nothing and is announced too — never silent.
+ *  Returns a promise ONLY while a grant is applied, so an answer with no grant costs no extra event-loop turn. */
+export declare function settleReadRootGrant(screen: ReadRootGrantScreen | undefined, grant: GrantReadRoot | undefined, at: {
+    toolName: string;
+    toolCallId: string;
+    sessionId: string;
+    runId: string;
+    taskId?: string;
+    onNotice: RunnerDeps["onNotice"];
+    signal?: AbortSignal;
+}): Promise<void> | undefined;
+export {};

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

@@ -0,0 +1,77 @@
+import { deliverEngineNotice } from "../types.js";
+import { READ_ROOT_CANDIDATE_DIR_MAX } from "../read-root-candidate.js";
+import { DEFAULT_GATE_AWAIT_TIMEOUT_MS } from "../gate-bounded-await.js";
+import { thrownText } from "../thrown-value.js";
+import { pathFamilyOf, withinAnyRoot } from "../../tools/fs/safety.js";
+export function rootAdmittingArtifactStore(storePhysical, rootsCanonical) {
+    const storeFamily = pathFamilyOf({ root: storePhysical });
+    return rootsCanonical.find((root) => pathFamilyOf({ root }) === storeFamily && (withinAnyRoot([root], storePhysical) || withinAnyRoot([storePhysical], root)));
+}
+export function readRootGrantOver(seats) {
+    const { env, writeRoots, readRoots, artifactStore } = seats;
+    return async (candidate, signal) => {
+        const c = await env.canonicalPath(candidate.dir);
+        if (signal.aborted)
+            return { ok: false, reason: "unresolvable", cause: "the lookup was cut" };
+        if (!c.ok)
+            return { ok: false, reason: "unresolvable", cause: `${c.error.code}: ${c.error.message}` };
+        if (c.value !== candidate.dir)
+            return { ok: false, reason: "resolves_elsewhere", cause: `it resolves to ${c.value}` };
+        const store = artifactStore.current;
+        if (store !== undefined && rootAdmittingArtifactStore(store, [c.value]) !== undefined)
+            return { ok: false, reason: "admits_artifact_store", cause: "the Artifact tool's ledger and stored files stay outside every root the file tools reach" };
+        if (!writeRoots.includes(c.value) && !readRoots.includes(c.value))
+            readRoots.push(c.value);
+        return { ok: true, root: c.value };
+    };
+}
+export function settleReadRootGrant(screen, grant, at) {
+    if (screen === undefined)
+        return undefined;
+    const ids = { toolName: at.toolName, toolCallId: at.toolCallId, sessionId: at.sessionId, runId: at.runId, ...(at.taskId !== undefined ? { taskId: at.taskId } : {}) };
+    const reject = (reason, offered, requested, why) => deliverEngineNotice(at.onNotice, {
+        code: "approval.read_root_grant_rejected",
+        message: `the approval for "${at.toolName}" asked to add a read directory, and nothing was added: ${why}. The approval's own verdict is unchanged.`,
+        detail: { reason, ...(offered !== undefined ? { offered } : {}), ...(requested !== undefined ? { requested: requested.slice(0, READ_ROOT_CANDIDATE_DIR_MAX) } : {}), ...ids },
+    });
+    if (screen.verdict === "rejected") {
+        const why = {
+            on_refusal: "a directory grant rides an approval, and this answer refused the call",
+            not_a_string: "the grant is not a string",
+            no_candidate: "this approval card offered no directory",
+            mismatch: "the grant is not the directory the card offered (it must be sent back exactly as offered)",
+        }[screen.reason];
+        reject(screen.reason, screen.offered, screen.requested, why);
+        return undefined;
+    }
+    const { candidate } = screen;
+    if (grant === undefined) {
+        reject("no_read_roots", candidate.dir, candidate.dir, "this run has no read directories to widen");
+        return undefined;
+    }
+    const cut = AbortSignal.any([...(at.signal !== undefined ? [at.signal] : []), AbortSignal.timeout(DEFAULT_GATE_AWAIT_TIMEOUT_MS)]);
+    const cutShort = new Promise((resolve) => {
+        const onCut = () => resolve({ ok: false, reason: "unresolvable", cause: at.signal?.aborted === true ? "the call ended before it resolved" : `it did not resolve within ${DEFAULT_GATE_AWAIT_TIMEOUT_MS}ms` });
+        if (cut.aborted)
+            onCut();
+        else
+            cut.addEventListener("abort", onCut, { once: true });
+    });
+    const attempt = grant(candidate, cut).catch((err) => ({ ok: false, reason: "unresolvable", cause: thrownText(err) }));
+    return Promise.race([attempt, cutShort]).then((applied) => {
+        if (!applied.ok) {
+            const why = {
+                unresolvable: `the directory could not be resolved (${applied.cause})`,
+                resolves_elsewhere: `the offered path no longer resolves to itself (${applied.cause})`,
+                admits_artifact_store: `the directory would admit the artifact store (${applied.cause})`,
+            }[applied.reason];
+            reject(applied.reason, candidate.dir, candidate.dir, why);
+            return;
+        }
+        deliverEngineNotice(at.onNotice, {
+            code: "approval.read_root_granted",
+            message: `the approval for "${at.toolName}" added ${candidate.covers === "exact" ? "the path" : "the directory"} ${candidate.dir} to this run's read directories (reads only; for the rest of this run).`,
+            detail: { dir: candidate.dir, ...(candidate.covers !== undefined ? { covers: candidate.covers } : {}), root: applied.root, ...ids },
+        });
+    });
+}

package/dist/core/runner/run-notification-lane.d.ts

@@ -3,7 +3,7 @@ import type { PushQueue } from "../push-queue.js";
 import type { SessionStore } from "../session.js";
 import { type NotificationInjectionOutcome, type PendingSessionNotifications, type SystemInjectionPriority, type TaskNotificationPayload } from "../task-notification.js";
 import type { RunnerDeps, TaskEvent, TaskSpec } from "../types.js";
-import type { SessionReadFileStates } from "./prepare-hands-readface.js";
+import type { SessionReadFileStates } from "./session-read-file-states.js";
 import type { NotificationLaneBindings, Prepared, PrepareTaskFn, ResumeRun, RunInternals, RunnerDepsSeat, RunnerSelfSeat, TaskIdRef } from "./contracts.js";
 export interface RunNotificationLaneInput<R> {
     /** borrowed-readonly — the task spec: prepare's input, and the principal the peer scope is minted from. */

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

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

package/dist/core/runner/runtask.js

@@ -15,7 +15,7 @@ import { PushQueue } from "../push-queue.js";
 import { TtlSessionStore } from "../session-store.js";
 import { errorCodeOf } from "./assemble-result.js";
 import { effectiveDelegationFacts, prepareTask } from "./prepare-task.js";
-import { SessionReadFileStates } from "./prepare-hands-readface.js";
+import { SessionReadFileStates } from "./session-read-file-states.js";
 import { RunnerSharedToolResultStore } from "../tool-result-store.js";
 import { PAUSE_REGISTRY } from "../pause-registry.js";
 import { toolPolicyNameSets } from "../tool-policy.js";

package/dist/core/runner/send-message-continuation.d.ts

@@ -0,0 +1,45 @@
+import type { RunnerDeps, ToolSpec } from "../types.js";
+import type { RunnerSelfSeat } from "./contracts.js";
+import type { SubagentTranscriptTier } from "../wiring-manifest.js";
+/**
+ * The tier-3 revival spawner of the SendMessage mount: re-enters the
+ * MOUNTED delegation tool (identified by object, never by wire name) through the raw ToolSpec execute +
+ * the leg's ctx enricher, with a fresh toolCallId and the trusted `ctx.reviveClaim`, so a revival is the
+ * complete spawn chain. `undefined` when no delegation tool is mounted. Module-level: closes over
+ * nothing of the leg but the two values it is handed.
+ */
+declare function buildTier3ReviveSpawn(delegationForRevive: ToolSpec | undefined, enrichSpecToolCtx: (ctx: import("../types.js").ToolExecuteContext) => import("../types.js").ToolExecuteContext): ((req: {
+    row: import("../background-agent-store.js").BackgroundAgentRecord;
+    rev: number;
+    prompt: string;
+    peerSeed?: {
+        hopChain: string[];
+    };
+}) => Promise<{
+    isError?: boolean;
+    content: string;
+    details?: unknown;
+}>) | undefined;
+/**
+ * The tier-3 revival spawner: identify the mounted delegation
+ * tool by OBJECT via its `agentListing` marker (filled only by createSubagentTool; a caller's
+ * same-named shadow tool never carries it, so the trusted ctx.reviveClaim can never reach
+ * one). The call goes through the RAW ToolSpec execute + `enrichSpecToolCtx` (the same
+ * enrichment the injection map applies — the AgentTool adapter face forwards only
+ * {toolCallId, signal} and would strip the claim), so the revival is the complete spawn
+ * chain: notify lane, observer sink, roster, durable store. The request is built by
+ * SendMessage AT EXECUTE TIME (ctx-first identity); this closure holds only the tool object
+ * reference. Fresh toolCallId per revival (F-11③ — never SendMessage's own call id).
+ * `tier` is {@link sendMessageContinuationTier} over the same seats the mount receives.
+ */
+export declare function sendMessageContinuationSeats(seats: {
+    specTools: readonly ToolSpec[];
+    agentStore: RunnerDeps["backgroundAgentStore"];
+    mailbox: RunnerDeps["mailboxStore"];
+    runner: RunnerSelfSeat;
+    enrichSpecToolCtx: (ctx: import("../types.js").ToolExecuteContext) => import("../types.js").ToolExecuteContext;
+}): {
+    reviveSpawn: ReturnType<typeof buildTier3ReviveSpawn>;
+    tier: SubagentTranscriptTier;
+};
+export {};

package/dist/core/runner/send-message-continuation.js

@@ -0,0 +1,27 @@
+import { randomBytes } from "node:crypto";
+import { sendMessageContinuationTier } from "../../agents/send-message-tool.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 } : {}),
+        };
+    };
+}
+export function sendMessageContinuationSeats(seats) {
+    const delegationForRevive = seats.specTools.find((t) => t.agentListing !== undefined);
+    const reviveSpawn = seats.agentStore !== undefined && seats.mailbox !== undefined ? buildTier3ReviveSpawn(delegationForRevive, seats.enrichSpecToolCtx) : undefined;
+    return { reviveSpawn, tier: sendMessageContinuationTier({ agentStore: seats.agentStore, mailbox: seats.mailbox, reviveSpawn, runner: seats.runner }) };
+}