@sema-agent/core 5.40.0 → 5.42.0

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

@@ -0,0 +1,283 @@
+import { emitTrace } from "../trace.js";
+import { StubExecutionEnv } from "../stub-env.js";
+import { hasBackgroundShell } from "../background-shell.js";
+import { defaultTaskRegistry } from "../task-registry.js";
+import { bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { resolveKey } from "../../tools/fs/safety.js";
+import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
+import { deliverEngineNotice } from "../types.js";
+import { rebaseWorkspacePath } from "./prepare-workspace-restore.js";
+const readFaceClampAnnouncedSinks = new WeakSet();
+let readFaceClampConsoleAnnounced = false;
+export function __resetReadFaceClampAnnouncement() {
+    readFaceClampConsoleAnnounced = false;
+}
+export function resolveHandsLessReadFace(input) {
+    const { resume, fullShellReachable, spec, deps } = input;
+    let handsLessResolvedFace;
+    let readDenyAdditionsNormalized = [];
+    {
+        const liveFace = resolveReadFace({
+            specReadFace: spec.readFace,
+            depsReadFace: deps.readFace,
+            readOnlyMount: spec.handsReadOnly === true,
+            orgGoverned: deps.permissionRuleOrg !== undefined,
+            fullShellReachable,
+        });
+        const seed = resume?.seed.readFace;
+        handsLessResolvedFace = resume !== undefined && (seed === undefined || seed.face === "roots") ? "roots" : liveFace;
+        const denyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seed?.denyEntries ?? [])];
+        resolveReadDenyBuiltins({
+            ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: deps.readDenyBuiltinTiers } : {}),
+            ...(deps.readDenyBuiltinExclude !== undefined ? { exclude: deps.readDenyBuiltinExclude } : {}),
+        });
+        if (denyAdditions.length > 0) {
+            readDenyAdditionsNormalized = compileReadDeny(denyAdditions, "readDenyPatterns", { tiers: [] }).entries;
+        }
+    }
+    return {
+        readFileStateForCheckpoint: undefined,
+        seedContextFiles: undefined,
+        handsCwdRef: undefined,
+        workspaceStateSettle: undefined,
+        wsSnapshot: undefined,
+        rebaseWsPath: (p) => p,
+        backgroundTaskToolsActive: false,
+        resolvedReadFace: undefined,
+        readDenyAdditionsNormalized,
+        handsLessResolvedFace,
+        additionalRootsCanonical: [],
+        additionalReadRootsCanonical: [],
+        attachmentRootCanonical: undefined,
+        readDenyMatcher: undefined,
+        shellGatedBash: false,
+        shellGatedMonitor: false,
+    };
+}
+export async function prepareHandsMount(input) {
+    const { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, tools, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes } = input;
+    let readFileStateForCheckpoint;
+    let seedContextFiles;
+    let handsCwdRef;
+    let workspaceStateSettle;
+    let wsSnapshot;
+    let rebaseWsPath = (p) => p;
+    let backgroundTaskToolsActive = false;
+    let resolvedReadFace;
+    let readDenyAdditionsNormalized = [];
+    let handsLessResolvedFace;
+    let shellGatedBash = false;
+    let shellGatedMonitor = false;
+    const additionalRootsCanonical = [];
+    const additionalReadRootsCanonical = [];
+    let attachmentRootCanonical;
+    let readDenyMatcher;
+    if (handsEnabled) {
+        const rootRaw = taskRootFinal;
+        const canon = await executionEnv.canonicalPath(rootRaw);
+        const rootCanonical = canon.ok ? canon.value : rootRaw;
+        attachmentRootCanonical = rootCanonical;
+        const canonicalizeExtraDirs = async (dirs, field, sink) => {
+            for (const dir of dirs ?? []) {
+                if (!dir || !dir.trim())
+                    continue;
+                const c = await executionEnv.canonicalPath(dir);
+                if (c.ok) {
+                    sink.push(c.value);
+                }
+                else {
+                    deps.onError?.(new Error(`${field} entry skipped (cannot canonicalize): ${dir}`), {
+                        phase: "config",
+                        sessionId,
+                    });
+                    emitTrace(deps.tracer, () => ({
+                        kind: "config.additional_directory_skipped",
+                        version: 1,
+                        taskId: hostTaskId,
+                        entry: dir,
+                        ...(field !== "additionalDirectories" ? { field } : {}),
+                        reason: `${c.error.code}: ${c.error.message}`,
+                        ts: Date.now(),
+                    }));
+                }
+            }
+        };
+        await canonicalizeExtraDirs(spec.additionalDirectories, "additionalDirectories", additionalRootsCanonical);
+        await canonicalizeExtraDirs(spec.additionalReadDirectories, "additionalReadDirectories", additionalReadRootsCanonical);
+        if (spec.envFacts?.scratchpadDir) {
+            let c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
+            if (!c.ok && c.error.code === "not_found") {
+                const marker = await executionEnv.joinPath([spec.envFacts.scratchpadDir, ".sema-scratchpad"]);
+                const exclusiveCreate = executionEnv.writeFileExclusive?.bind(executionEnv);
+                if (marker.ok && exclusiveCreate) {
+                    const w = await exclusiveCreate(marker.value, "");
+                    if (w.ok || w.error.code === "already_exists")
+                        c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
+                }
+            }
+            if (c.ok)
+                additionalRootsCanonical.push(c.value);
+        }
+        for (const a of [additionalRootsCanonical, additionalReadRootsCanonical])
+            a.splice(0, a.length, ...new Set(a));
+        const readFileState = new Map((resume?.seed.readFileState ?? []).map(([k, v]) => [rebaseRestoredPath(k), v]));
+        readFileStateForCheckpoint = readFileState;
+        seedContextFiles = async (files) => {
+            for (const f of files) {
+                const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, resolvedReadFace);
+                if (rk.ok)
+                    seedReadFileStateFromContext(readFileState, rk.key, f.content);
+            }
+        };
+        const handsIncludeShell = !(executionEnv instanceof StubExecutionEnv);
+        const handsReadOnly = spec.handsReadOnly === true;
+        backgroundTaskToolsActive = handsIncludeShell && !handsReadOnly && hasBackgroundShell(executionEnv);
+        wsSnapshot = resume !== undefined || !(handsIncludeShell && !handsReadOnly) ? undefined : await session.getWorkspaceState().catch(() => undefined);
+        rebaseWsPath = (p) => (wsSnapshot === undefined || wsSnapshot.taskRoot === rootCanonical ? p : rebaseWorkspacePath(p, wsSnapshot.taskRoot, rootCanonical));
+        if (handsIncludeShell && !handsReadOnly) {
+            handsCwdRef = { current: rootCanonical };
+            if (resume?.seed.handsCwd !== undefined)
+                handsCwdRef.current = rebaseRestoredPath(resume.seed.handsCwd);
+            else if (wsSnapshot?.handsCwd !== undefined)
+                handsCwdRef.current = rebaseWsPath(wsSnapshot.handsCwd);
+            workspaceStateSettle = {
+                rootCanonical,
+                restoredHandsCwd: handsCwdRef.current !== rootCanonical ? handsCwdRef.current : undefined,
+                ...(resume !== undefined ? { baselineUnknown: true } : {}),
+            };
+        }
+        const seedReadFaceSection = resume?.seed.readFace;
+        const readDenyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seedReadFaceSection?.denyEntries ?? [])];
+        const readDenyBuiltinCfg = {
+            ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: [...deps.readDenyBuiltinTiers] } : {}),
+            ...(deps.readDenyBuiltinExclude !== undefined ? { exclude: [...deps.readDenyBuiltinExclude] } : {}),
+        };
+        readDenyMatcher = compileReadDeny(readDenyAdditions, "readDenyPatterns", readDenyBuiltinCfg);
+        readDenyAdditionsNormalized = compileReadDeny(readDenyAdditions, "readDenyPatterns", { tiers: [] }).entries;
+        let liveReadFace = resolveReadFace({
+            specReadFace: spec.readFace,
+            depsReadFace: deps.readFace,
+            readOnlyMount: handsReadOnly,
+            orgGoverned: deps.permissionRuleOrg !== undefined,
+            fullShellReachable,
+            onDeploymentClamp: () => {
+                const sink = deps.onNotice;
+                if (typeof sink === "function") {
+                    if (readFaceClampAnnouncedSinks.has(sink))
+                        return;
+                    readFaceClampAnnouncedSinks.add(sink);
+                }
+                else {
+                    if (readFaceClampConsoleAnnounced)
+                        return;
+                    readFaceClampConsoleAnnounced = true;
+                }
+                deliverEngineNotice(sink, deploymentReadFaceClampNotice());
+            },
+        });
+        if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
+            liveReadFace = "roots";
+        resolvedReadFace = liveReadFace;
+        if (resume === undefined && spec.sessionId !== undefined) {
+            const prior = await session.buildContext().catch(() => undefined);
+            for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
+                const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
+                if (rk.ok)
+                    seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
+            }
+        }
+        const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
+            ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
+            ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
+            ...(readDenyAdditions.length > 0 ? { readDenyPatterns: readDenyAdditions } : {}),
+            ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
+            ...(readDenyBuiltinCfg.exclude !== undefined ? { readDenyBuiltinExclude: readDenyBuiltinCfg.exclude } : {}),
+            readFace: liveReadFace,
+            includeShell: handsIncludeShell,
+            readOnly: handsReadOnly,
+            ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
+            taskRegistry: defaultTaskRegistry,
+            taskOwner: hostTaskId,
+            taskScope,
+            oneShot: spec.oneShot,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
+            ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
+            ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
+            pdfModelCapabilities: pdfModelCapabilitiesOf(model),
+            ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
+            ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
+            ...(deps.hands?.readImageDownsampler !== undefined ? { readImageDownsampler: deps.hands.readImageDownsampler } : {}),
+            ...(deps.hands?.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: deps.hands.autoBackgroundOnTimeout } : {}),
+            ...(deps.hands?.readCyberReminder !== undefined ? { readCyberReminder: deps.hands.readCyberReminder } : {}),
+            beforeWrite: async (w) => {
+                const deploymentGate = deps.hands?.beforeWrite;
+                if (deploymentGate) {
+                    const verdict = await deploymentGate(w);
+                    if (verdict !== undefined && verdict.ok === false)
+                        return verdict;
+                }
+                return memoryWriteGateRef.current?.(w);
+            },
+            mountBackgroundTaskTools: false,
+            monitorToolActive: backgroundTaskToolsActive && !(toolFaceSnapshot.exclude?.includes("Monitor") ?? false),
+        });
+        {
+            const bandNames = new Set(band.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+            const shadowed = (spec.tools ?? []).filter((t) => [t.name, ...(t.aliases ?? [])].some((n) => bandNames.has(n)));
+            if (shadowed.length > 0) {
+                const names = shadowed.map((t) => `"${t.name}"`).join(", ");
+                deps.onError?.(new Error(`spec.tools ${shadowed.length > 1 ? "entries" : "entry"} ${names} collide${shadowed.length > 1 ? "" : "s"} with the built-in hands tool band — the built-in wins (registered later; the harness tool Map is last-write-wins) and the caller tool never dispatches this task. Rename the caller tool, or don't inject executionEnv if you intend to replace the band.`), { phase: "config", sessionId });
+            }
+        }
+        tools.push(...band.map((t) => firstPartyOffload(t)));
+        const shellGate = effectiveShellGate;
+        if (shellGate === "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
+            deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — no shell safety-axis ` +
+                `fold applies to this run (commands are adjudicated by the ordinary policy/hook chain only). ` +
+                `Set spec.shellGate to "classify" or "always" if this deployment expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
+        }
+        if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
+            const bashTierBefore = irreversibilityTier.get("Bash");
+            shellGatedBash = !egressTools.has("Bash") && bashTierBefore !== "always" && bashTierBefore !== "maybe";
+            const bashEffectiveTier = shellGate === "always" || bashTierBefore === "always" ? "always" : "maybe";
+            irreversibilityTier.set("Bash", bashEffectiveTier);
+            irreversibleTools.add("Bash");
+            const shellReadBoundary = () => ({
+                roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
+                ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
+                denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
+                ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
+            });
+            if (shellGate === "classify" && shellGatedBash)
+                reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
+            if (backgroundTaskToolsActive) {
+                const monitorTierBefore = irreversibilityTier.get("Monitor");
+                shellGatedMonitor = !egressTools.has("Monitor") && monitorTierBefore !== "always" && monitorTierBefore !== "maybe";
+                const monitorEffectiveTier = shellGate === "always" || monitorTierBefore === "always" ? "always" : "maybe";
+                irreversibilityTier.set("Monitor", monitorEffectiveTier);
+                irreversibleTools.add("Monitor");
+                if (shellGate === "classify" && shellGatedMonitor)
+                    reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
+            }
+        }
+    }
+    return {
+        readFileStateForCheckpoint,
+        seedContextFiles,
+        handsCwdRef,
+        workspaceStateSettle,
+        wsSnapshot,
+        rebaseWsPath,
+        backgroundTaskToolsActive,
+        resolvedReadFace,
+        readDenyAdditionsNormalized,
+        handsLessResolvedFace,
+        additionalRootsCanonical,
+        additionalReadRootsCanonical,
+        attachmentRootCanonical,
+        readDenyMatcher,
+        shellGatedBash,
+        shellGatedMonitor,
+    };
+}

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

@@ -37,11 +37,7 @@ export declare function __resetMaterializeEnvAnnouncements(): void;
  *  seam below (console latch only): tests here legitimately reuse ONE sink across prepares to pin
  *  the per-sink dedup itself, so the seam must be able to re-arm a still-referenced sink. */
 export declare function __resetToolModelGateAnnouncements(): void;
-/** Test seam (mirrors `__resetMalformedNoticeSeatAnnouncement`): never called by production code.
- *  Deliberately asymmetric — it resets only the console latch: the WeakSet arm needs no seam
- *  because a test resets it by minting a fresh sink function (identity IS the ledger key), while
- *  the console arm's key is the process itself, which only this seam can refresh. */
-export declare function __resetReadFaceClampAnnouncement(): void;
+export { __resetReadFaceClampAnnouncement } from "./prepare-hands-readface.js";
 /**
  * design/164 件四 — how long before an execution environment's declared `lifetimeMs` expires the engine
  * stops the run and checkpoints it. The margin has to cover ONE suspend: pausing/snapshotting the

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

@@ -56,7 +56,8 @@ import { prepareMemory } from "./prepare-memory.js";
 import { limitConfigError, prepareConfigDoors } from "./prepare-config-doors.js";
 import { NAMESPACED_NAME_SHAPES, prepareSafetyScan } from "./prepare-safety-scan.js";
 import { prepareAcquireReconcile } from "./prepare-acquire-reconcile.js";
-import { prepareWorkspaceRestore, rebaseWorkspacePath, remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./prepare-workspace-restore.js";
+import { prepareHandsMount, resolveHandsLessReadFace } from "./prepare-hands-readface.js";
+import { prepareWorkspaceRestore, remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./prepare-workspace-restore.js";
 import { defaultPromptProvider, buildEnvironmentContext, formatLocalDate, isValidTimeZone, PROJECT_CONTEXT_FRAMING } from "../../prompts/default.js";
 import { applyGitFrameGuard, probeGitStatusLane } from "./git-status-frame.js";
 import { assemblePrompt } from "../../prompt-assembly/assemble.js";
@@ -76,7 +77,7 @@ import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.j
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
 import { createMonitorTool } from "../../tools/monitor.js";
 import { createWorktreeTools } from "../../tools/worktree.js";
-import { applyCompactionToReadFileState, bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, isReadDedupStubResult, resolveReadDenyBuiltins, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS, pdfModelCapabilitiesOf } from "../../tools/fs/index.js";
+import { applyCompactionToReadFileState, isReadDedupStubResult, FULL_SHELL_CONTRACT_ID, HAND_TOOL_EFFECTS } from "../../tools/fs/index.js";
 import { decodeTextBytes } from "../../tools/fs/encoding.js";
 import { ASK_USER_QUESTION_TOOL_NAME, createAskUserQuestionTool, classifyQuestionOutcome, isLiveQuestionFace, validateAskQuestions, } from "../ask-question.js";
 import { createSchedulerTools } from "../../tools/scheduler-tools.js";
@@ -86,8 +87,7 @@ import { createRunWorkflowTool, RUN_WORKFLOW_TOOL_NAME } from "../../orchestrati
 import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
 import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
 import { resolveKey } from "../../tools/fs/safety.js";
-import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
-import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
+import { BINDING_CHECKPOINT_VERSION, mintCheckpointId, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, encodeAtFidelity, remainingBudgetMicroUsd, resolveCheckpointStore, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { countElicitOptIns, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam } from "../wiring-manifest.js";
 import { durableParkGapFor } from "../park-selfcheck.js";
@@ -191,11 +191,7 @@ function announceToolModelGate(onNotice, modelId, gate) {
         }
     }
 }
-const readFaceClampAnnouncedSinks = new WeakSet();
-let readFaceClampConsoleAnnounced = false;
-export function __resetReadFaceClampAnnouncement() {
-    readFaceClampConsoleAnnounced = false;
-}
+export { __resetReadFaceClampAnnouncement } from "./prepare-hands-readface.js";
 const DEFAULT_MAX_SUSPENDS = 5;
 const ULTRA_REASONING_TIERS = new Set(["xhigh", "max"]);
 const DEFAULT_RESOURCE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
@@ -1036,14 +1032,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             resourceSpentMicroUsd: priorLedger?.spentMicroUsd ?? 0,
             suspendCount: priorSuspendCount,
         };
-        let readFileStateForCheckpoint;
-        let seedContextFiles;
-        let handsCwdRef;
-        let workspaceStateSettle;
-        let wsSnapshot;
-        let rebaseWsPath = (p) => p;
         let worktreeSessionRef;
-        let backgroundTaskToolsActive = false;
         let suspendForResource;
         let suspendForPlatformLimit;
         let suspendForReview;
@@ -1209,219 +1198,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         foldProtocolAxes(a2a.toolAxes, "A2A");
         const callIssuedAtRef = {};
         const memoryWriteGateRef = {};
-        const additionalRootsCanonical = [];
-        const additionalReadRootsCanonical = [];
-        let attachmentRootCanonical;
-        let readDenyMatcher;
-        if (handsEnabled) {
-            const rootRaw = taskRootFinal;
-            const canon = await executionEnv.canonicalPath(rootRaw);
-            const rootCanonical = canon.ok ? canon.value : rootRaw;
-            attachmentRootCanonical = rootCanonical;
-            const canonicalizeExtraDirs = async (dirs, field, sink) => {
-                for (const dir of dirs ?? []) {
-                    if (!dir || !dir.trim())
-                        continue;
-                    const c = await executionEnv.canonicalPath(dir);
-                    if (c.ok) {
-                        sink.push(c.value);
-                    }
-                    else {
-                        deps.onError?.(new Error(`${field} entry skipped (cannot canonicalize): ${dir}`), {
-                            phase: "config",
-                            sessionId,
-                        });
-                        emitTrace(deps.tracer, () => ({
-                            kind: "config.additional_directory_skipped",
-                            version: 1,
-                            taskId: hostTaskId,
-                            entry: dir,
-                            ...(field !== "additionalDirectories" ? { field } : {}),
-                            reason: `${c.error.code}: ${c.error.message}`,
-                            ts: Date.now(),
-                        }));
-                    }
-                }
-            };
-            await canonicalizeExtraDirs(spec.additionalDirectories, "additionalDirectories", additionalRootsCanonical);
-            await canonicalizeExtraDirs(spec.additionalReadDirectories, "additionalReadDirectories", additionalReadRootsCanonical);
-            if (spec.envFacts?.scratchpadDir) {
-                let c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
-                if (!c.ok && c.error.code === "not_found") {
-                    const marker = await executionEnv.joinPath([spec.envFacts.scratchpadDir, ".sema-scratchpad"]);
-                    const exclusiveCreate = executionEnv.writeFileExclusive?.bind(executionEnv);
-                    if (marker.ok && exclusiveCreate) {
-                        const w = await exclusiveCreate(marker.value, "");
-                        if (w.ok || w.error.code === "already_exists")
-                            c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
-                    }
-                }
-                if (c.ok)
-                    additionalRootsCanonical.push(c.value);
-            }
-            for (const a of [additionalRootsCanonical, additionalReadRootsCanonical])
-                a.splice(0, a.length, ...new Set(a));
-            const readFileState = new Map((resume?.seed.readFileState ?? []).map(([k, v]) => [rebaseRestoredPath(k), v]));
-            readFileStateForCheckpoint = readFileState;
-            seedContextFiles = async (files) => {
-                for (const f of files) {
-                    const rk = await resolveKey(executionEnv, rootCanonical, f.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, resolvedReadFace);
-                    if (rk.ok)
-                        seedReadFileStateFromContext(readFileState, rk.key, f.content);
-                }
-            };
-            const handsIncludeShell = !(executionEnv instanceof StubExecutionEnv);
-            const handsReadOnly = spec.handsReadOnly === true;
-            backgroundTaskToolsActive = handsIncludeShell && !handsReadOnly && hasBackgroundShell(executionEnv);
-            wsSnapshot = resume !== undefined || !(handsIncludeShell && !handsReadOnly) ? undefined : await session.getWorkspaceState().catch(() => undefined);
-            rebaseWsPath = (p) => (wsSnapshot === undefined || wsSnapshot.taskRoot === rootCanonical ? p : rebaseWorkspacePath(p, wsSnapshot.taskRoot, rootCanonical));
-            if (handsIncludeShell && !handsReadOnly) {
-                handsCwdRef = { current: rootCanonical };
-                if (resume?.seed.handsCwd !== undefined)
-                    handsCwdRef.current = rebaseRestoredPath(resume.seed.handsCwd);
-                else if (wsSnapshot?.handsCwd !== undefined)
-                    handsCwdRef.current = rebaseWsPath(wsSnapshot.handsCwd);
-                workspaceStateSettle = {
-                    rootCanonical,
-                    restoredHandsCwd: handsCwdRef.current !== rootCanonical ? handsCwdRef.current : undefined,
-                    ...(resume !== undefined ? { baselineUnknown: true } : {}),
-                };
-            }
-            const seedReadFaceSection = resume?.seed.readFace;
-            const readDenyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seedReadFaceSection?.denyEntries ?? [])];
-            const readDenyBuiltinCfg = {
-                ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: [...deps.readDenyBuiltinTiers] } : {}),
-                ...(deps.readDenyBuiltinExclude !== undefined ? { exclude: [...deps.readDenyBuiltinExclude] } : {}),
-            };
-            readDenyMatcher = compileReadDeny(readDenyAdditions, "readDenyPatterns", readDenyBuiltinCfg);
-            readDenyAdditionsNormalized = compileReadDeny(readDenyAdditions, "readDenyPatterns", { tiers: [] }).entries;
-            let liveReadFace = resolveReadFace({
-                specReadFace: spec.readFace,
-                depsReadFace: deps.readFace,
-                readOnlyMount: handsReadOnly,
-                orgGoverned: deps.permissionRuleOrg !== undefined,
-                fullShellReachable,
-                onDeploymentClamp: () => {
-                    const sink = deps.onNotice;
-                    if (typeof sink === "function") {
-                        if (readFaceClampAnnouncedSinks.has(sink))
-                            return;
-                        readFaceClampAnnouncedSinks.add(sink);
-                    }
-                    else {
-                        if (readFaceClampConsoleAnnounced)
-                            return;
-                        readFaceClampConsoleAnnounced = true;
-                    }
-                    deliverEngineNotice(sink, deploymentReadFaceClampNotice());
-                },
-            });
-            if (resume !== undefined && (seedReadFaceSection === undefined || seedReadFaceSection.face === "roots"))
-                liveReadFace = "roots";
-            resolvedReadFace = liveReadFace;
-            if (resume === undefined && spec.sessionId !== undefined) {
-                const prior = await session.buildContext().catch(() => undefined);
-                for (const rec of wholeFileRecordsFromTranscript(prior?.messages ?? [])) {
-                    const rk = await resolveKey(executionEnv, rootCanonical, rec.path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, liveReadFace);
-                    if (rk.ok)
-                        seedReadFileStateFromTranscript(readFileState, rk.key, rec.content, rec.at);
-                }
-            }
-            const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
-                ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
-                ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
-                ...(readDenyAdditions.length > 0 ? { readDenyPatterns: readDenyAdditions } : {}),
-                ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
-                ...(readDenyBuiltinCfg.exclude !== undefined ? { readDenyBuiltinExclude: readDenyBuiltinCfg.exclude } : {}),
-                readFace: liveReadFace,
-                includeShell: handsIncludeShell,
-                readOnly: handsReadOnly,
-                ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
-                taskRegistry: defaultTaskRegistry,
-                taskOwner: hostTaskId,
-                taskScope,
-                oneShot: spec.oneShot,
-                ...(sessionId !== undefined ? { sessionId } : {}),
-                ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
-                ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
-                ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
-                pdfModelCapabilities: pdfModelCapabilitiesOf(model),
-                ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
-                ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
-                ...(deps.hands?.readImageDownsampler !== undefined ? { readImageDownsampler: deps.hands.readImageDownsampler } : {}),
-                ...(deps.hands?.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: deps.hands.autoBackgroundOnTimeout } : {}),
-                ...(deps.hands?.readCyberReminder !== undefined ? { readCyberReminder: deps.hands.readCyberReminder } : {}),
-                beforeWrite: async (w) => {
-                    const deploymentGate = deps.hands?.beforeWrite;
-                    if (deploymentGate) {
-                        const verdict = await deploymentGate(w);
-                        if (verdict !== undefined && verdict.ok === false)
-                            return verdict;
-                    }
-                    return memoryWriteGateRef.current?.(w);
-                },
-                mountBackgroundTaskTools: false,
-                monitorToolActive: backgroundTaskToolsActive && !(toolFaceSnapshot.exclude?.includes("Monitor") ?? false),
-            });
-            {
-                const bandNames = new Set(band.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
-                const shadowed = (spec.tools ?? []).filter((t) => [t.name, ...(t.aliases ?? [])].some((n) => bandNames.has(n)));
-                if (shadowed.length > 0) {
-                    const names = shadowed.map((t) => `"${t.name}"`).join(", ");
-                    deps.onError?.(new Error(`spec.tools ${shadowed.length > 1 ? "entries" : "entry"} ${names} collide${shadowed.length > 1 ? "" : "s"} with the built-in hands tool band — the built-in wins (registered later; the harness tool Map is last-write-wins) and the caller tool never dispatches this task. Rename the caller tool, or don't inject executionEnv if you intend to replace the band.`), { phase: "config", sessionId });
-                }
-            }
-            tools.push(...band.map((t) => firstPartyOffload(t)));
-            const shellGate = effectiveShellGate;
-            if (shellGate === "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-                deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — no shell safety-axis ` +
-                    `fold applies to this run (commands are adjudicated by the ordinary policy/hook chain only). ` +
-                    `Set spec.shellGate to "classify" or "always" if this deployment expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
-            }
-            if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-                const bashTierBefore = irreversibilityTier.get("Bash");
-                shellGatedBash = !egressTools.has("Bash") && bashTierBefore !== "always" && bashTierBefore !== "maybe";
-                const bashEffectiveTier = shellGate === "always" || bashTierBefore === "always" ? "always" : "maybe";
-                irreversibilityTier.set("Bash", bashEffectiveTier);
-                irreversibleTools.add("Bash");
-                const shellReadBoundary = () => ({
-                    roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
-                    ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
-                    denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
-                    ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
-                });
-                if (shellGate === "classify" && shellGatedBash)
-                    reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
-                if (backgroundTaskToolsActive) {
-                    const monitorTierBefore = irreversibilityTier.get("Monitor");
-                    shellGatedMonitor = !egressTools.has("Monitor") && monitorTierBefore !== "always" && monitorTierBefore !== "maybe";
-                    const monitorEffectiveTier = shellGate === "always" || monitorTierBefore === "always" ? "always" : "maybe";
-                    irreversibilityTier.set("Monitor", monitorEffectiveTier);
-                    irreversibleTools.add("Monitor");
-                    if (shellGate === "classify" && shellGatedMonitor)
-                        reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
-                }
-            }
-        }
-        else {
-            const liveFace = resolveReadFace({
-                specReadFace: spec.readFace,
-                depsReadFace: deps.readFace,
-                readOnlyMount: spec.handsReadOnly === true,
-                orgGoverned: deps.permissionRuleOrg !== undefined,
-                fullShellReachable,
-            });
-            const seed = resume?.seed.readFace;
-            handsLessResolvedFace = resume !== undefined && (seed === undefined || seed.face === "roots") ? "roots" : liveFace;
-            const denyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seed?.denyEntries ?? [])];
-            resolveReadDenyBuiltins({
-                ...(deps.readDenyBuiltinTiers !== undefined ? { tiers: deps.readDenyBuiltinTiers } : {}),
-                ...(deps.readDenyBuiltinExclude !== undefined ? { exclude: deps.readDenyBuiltinExclude } : {}),
-            });
-            if (denyAdditions.length > 0) {
-                readDenyAdditionsNormalized = compileReadDeny(denyAdditions, "readDenyPatterns", { tiers: [] }).entries;
-            }
-        }
+        const handsReadFaceInput = { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, tools, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes };
+        const handsReadFace = handsEnabled ? await prepareHandsMount(handsReadFaceInput) : resolveHandsLessReadFace(handsReadFaceInput);
+        const { readFileStateForCheckpoint, seedContextFiles, handsCwdRef, workspaceStateSettle, wsSnapshot, rebaseWsPath, backgroundTaskToolsActive, additionalRootsCanonical, additionalReadRootsCanonical, attachmentRootCanonical, readDenyMatcher } = handsReadFace;
+        resolvedReadFace = handsReadFace.resolvedReadFace;
+        readDenyAdditionsNormalized = handsReadFace.readDenyAdditionsNormalized;
+        handsLessResolvedFace = handsReadFace.handsLessResolvedFace;
+        shellGatedBash = handsReadFace.shellGatedBash;
+        shellGatedMonitor = handsReadFace.shellGatedMonitor;
         if (backgroundTaskToolsActive || workflowToolsActive) {
             toolEffects.set("TaskOutput", "read");
             toolEffects.set("TaskStop", "write");
@@ -3821,6 +3605,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const mintedAt = Date.now();
                 const cp = {
                     token,
+                    checkpointId: mintCheckpointId(),
                     version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : resourceLedgerOut.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : RESOURCE_CHECKPOINT_VERSION,
                     scope,
                     sessionId,
@@ -3903,6 +3688,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     const mintedAt = Date.now();
                     const cp = {
                         token,
+                        checkpointId: mintCheckpointId(),
                         version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : reviewLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                         scope,
                         sessionId,
@@ -4164,6 +3950,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const mintedAt = Date.now();
                         cp = {
                             token,
+                            checkpointId: mintCheckpointId(),
                             version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : realApproval !== undefined ? REAL_APPROVAL_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : approvalLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                             scope,
                             sessionId,

package/dist/core/runner/runtask.js

@@ -1,6 +1,6 @@
 import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
 import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
-import { deliverDelegationLifecycle } from "../types.js";
+import { deliverDelegationLifecycle, deliverEngineNotice, undrainedUserInputNotices } from "../types.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
 import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, LEGACY_PENDING_STEER_INPUT_ID, MAX_STEER_INPUT_ID_CHARS, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
@@ -2068,6 +2068,11 @@ export class Runner {
             for (const p of payloads)
                 this.pendingSessionNotifications.pend(notificationSessionId, p);
         };
+        prepared.harness.onUndrainedUserInputs = (counts) => {
+            for (const notice of undrainedUserInputNotices(counts, spec.taskId)) {
+                deliverEngineNotice(this.deps.onNotice, notice);
+            }
+        };
         prepared.harness.onEngineNoteConsumed = (p) => {
             const peer = p?.peer;
             if (peer !== undefined && Array.isArray(peer.hopChain))