@sema-agent/core 7.5.1 → 7.6.0

package/dist/core/runner/prepare-turn-wiring.d.ts

@@ -0,0 +1,154 @@
+import type { AgentHarness, AgentTool, ExecutionEnv, ThinkingLevel } from "../../internal/harness.js";
+import type { Model } from "../../internal/llm.js";
+import { type AssembledPrompt, type AssembleInputs } from "../../prompt-assembly/assemble.js";
+import { type PromptEpochArtifact } from "../../prompt-assembly/artifact.js";
+import type { EpochDeclaredSections } from "../../prompt-assembly/epoch.js";
+import { type TurnPromptSnapshot } from "../../prompt-assembly/turn-snapshot.js";
+import type { PromptTextDeclaration } from "../../prompts/default.js";
+import { CacheBreakDetector, type ToolFingerprintInput } from "../cache-break-detector.js";
+import { type ToolPolicy } from "../tool-policy.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import { type ReadFace } from "../../tools/fs/index.js";
+import type { ReadDenyMatcher } from "../../tools/fs/read-deny.js";
+import { type ReadFileState } from "../../tools/fs/safety.js";
+import type { Prepared } from "./contracts.js";
+export interface PrepareTurnWiringInput {
+    /** borrowed-readonly — the deployment seats: `cacheBreakDetection` (the detector knob), `onError` (the attachment-skip
+     *  degraded line), `promptSource` (the center candidate's state and current artifact). Receiver preserved. */
+    deps: Pick<RunnerDeps, "cacheBreakDetection" | "onError" | "promptSource">;
+    /** borrowed-mutable — the LIVE system prompt (the prompt-assembly phase's accessor cell). Read: the fingerprint, the
+     *  snapshot's stable text, the overhead term. Writer here: the center candidate's `apply` (the boundary swap). */
+    systemPromptSeat: {
+        current: string;
+    };
+    /** borrowed-readonly — the FINAL wire tool list (the fingerprint's and the snapshot's tool wire, the overhead sum). */
+    harnessTools: ReadonlyArray<AgentTool>;
+    /** borrowed-mutable — the fingerprint ref the tool-disclosure phase minted. Writers: THIS phase seeds `current`; the
+     *  candidate's `apply` rewrites `current.systemPrompt`; the disclosure phase's rebuild seam refreshes `current.tools`. */
+    fpRef: {
+        current?: {
+            systemPrompt: string;
+            tools: ToolFingerprintInput[];
+        };
+    };
+    /** borrowed-readonly — the task model: `provider` / `id` / `maxTokens` / `api` (the snapshot's identity elements). */
+    model: Pick<Model, "provider" | "id" | "maxTokens" | "api">;
+    /** borrowed-readonly — the resolved epoch's artifact digest (the snapshot's identity element). */
+    epochArtifactDigestForSnapshot: string;
+    /** borrowed-readonly — the resolved prompt profile (a snapshot element). */
+    promptProfile: "simple" | "classic";
+    /** borrowed-readonly — the fable mitigations switch (a snapshot element). */
+    fableMitigations: boolean;
+    /** borrowed-readonly — the assembled prompt's physical block face, or undefined (the snapshot's layout groups). */
+    systemBlocks: AssembledPrompt["systemBlocks"];
+    /** borrowed-readonly — the resolved thinking level, or undefined (a snapshot element). */
+    thinking: ThinkingLevel | undefined;
+    /** borrowed-readonly — the REBOUND spec; only `outputSchema` (presence) and `taskId` (the snapshot's identity). */
+    spec: Pick<TaskSpec, "outputSchema" | "taskId">;
+    /** borrowed-readonly — the acquired session id (the snapshot; the attachment-skip attribution). */
+    sessionId: string;
+    /** borrowed-mutable — the snapshot ref the tool-disclosure phase minted. Writers: THIS phase seeds `current`; the candidate's
+     *  `apply` calls `refreshStableSystem`; the disclosure phase's rebuild seam calls `refreshTools`; the run loop assigns
+     *  `current.onChange` (the snapshot-changed trace emitter) once Prepared is built. */
+    turnSnapshotRef: {
+        current?: TurnPromptSnapshot;
+    };
+    /** borrowed-mutable — the composition manifest (`Prepared.promptManifest`). Writer here: the identity/lowering BACKFILL
+     *  (the snapshot needs the final wire list, which exists only now). */
+    promptManifest: Prepared["promptManifest"];
+    /** borrowed-readonly — the model's structural coefficient (the context lane's), the overhead term's coordinate. */
+    charsPerToken: number;
+    /** borrowed-readonly — whether an execution env is wired (every reader exists only then). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the run's resolved env (the readers read and stat through it). */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the canonical attachment root, or undefined (the readers' containment fence). */
+    attachmentRootCanonical: string | undefined;
+    /** borrowed-readonly — the canonical extra write roots (the fence's root set). */
+    additionalRootsCanonical: ReadonlyArray<string>;
+    /** borrowed-readonly — the canonical extra read roots (the fence's root set). */
+    additionalReadRootsCanonical: ReadonlyArray<string>;
+    /** borrowed-readonly — the compiled read-deny judge, or undefined (the reader's withheld arm). */
+    readDenyMatcher: ReadDenyMatcher | undefined;
+    /** borrowed-readonly — the resolved read face, or undefined (the fence's ninth argument). */
+    resolvedReadFace: ReadFace | undefined;
+    /** borrowed-readonly — the tracked-cwd seat, read per call by the kept-tail normalizer (never written here). */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-mutable — the live read-file state, or undefined. Writers here, at RUN time: `detectExternalChanges` evicts a
+     *  not-found entry; `onCompactionApplied` applies a landed compaction to it. The hands phase mints it. */
+    readFileStateForCheckpoint: ReadFileState | undefined;
+    /** borrowed-readonly — the deny-narrowing fold, or undefined (the changed-files deny door's authority). */
+    denyNarrowingPolicy: ToolPolicy | undefined;
+    /** borrowed-readonly — the run's abort controller; only `signal` (the deny door's and the stat's signal). */
+    abortController: Pick<AbortController, "signal">;
+    /** borrowed-readonly — the per-task identity (the background listing's owner). */
+    hostTaskId: string;
+    /** borrowed-readonly — the registry scope the background listing reads under. */
+    taskScope: string;
+    /** borrowed-readonly — the prompt-assembly phase's re-invokable assemble-inputs builder (the candidate re-assembles). */
+    buildAssembleInputs: (centerDecls?: PromptTextDeclaration[]) => AssembleInputs;
+    /** borrowed-mutable — the LIVE center adoption (the prompt-assembly phase's accessor cell). Read: the candidate's arming and
+     *  same-artifact test. Writer here: the candidate's `apply` (the boundary swap / the explicit-disable rollback). */
+    centerAdoptionRef: {
+        current: {
+            artifact: PromptEpochArtifact;
+            sourceRevision?: string;
+        } | undefined;
+    };
+    /** borrowed-readonly — the harness ref (the candidate's `apply` calls `setSystemPrompt` on the current harness). */
+    harnessRef: {
+        current?: AgentHarness;
+    };
+    /** borrowed-readonly — the provider-declared sections in the epoch shape (the candidate's declared-sections TYPE). */
+    epochDeclaredSections: EpochDeclaredSections;
+    /** borrowed-readonly — the ONE carrier-face expression both delegation mounts consume (the observation seat). */
+    carrierReadFace: () => ReadFace | undefined;
+    /** borrowed-readonly — the normalized deny additions (the observation seat copies them). */
+    readDenyAdditionsNormalized: ReadonlyArray<{
+        pattern: string;
+        caseSensitive: boolean;
+    }>;
+    /** borrowed-mutable — the holder of the built Prepared. Writer: the DRIVER fills `current` right after `buildPrepared()`;
+     *  the candidate's `apply` then writes `current.epochDeclaredSections` and `current.promptOverheadTokens` at a boundary. */
+    preparedHolder: {
+        current?: Prepared;
+    };
+}
+export interface PrepareTurnWiringResult {
+    /** owned — the two-phase cache-break detector (`Prepared.cacheBreakDetector`), or undefined when the knob is off. */
+    cacheBreakDetector: CacheBreakDetector | undefined;
+    /** borrowed-mutable — the prefix fingerprint (`Prepared.cacheFingerprint`; the same object `fpRef.current` holds), or
+     *  undefined. Writers after this phase: the candidate's `apply` (systemPrompt), the disclosure rebuild seam (tools). */
+    cacheFingerprint: {
+        systemPrompt: string;
+        tools: ToolFingerprintInput[];
+    } | undefined;
+    /** owned — the fixed prompt-overhead term in the compaction trigger's coordinate (`Prepared.promptOverheadTokens`). */
+    promptOverheadTokens: number;
+    /** owned — the fenced working-file reader, or undefined without hands (`Prepared.readTaskFile`). */
+    readTaskFile: Prepared["readTaskFile"];
+    /** owned — the kept-tail path normalizer, or undefined without hands. */
+    normalizeAttachmentPath: Prepared["normalizeAttachmentPath"];
+    /** owned — the Read tool's dedup-stub predicate, or undefined without hands. */
+    isDedupStubResult: Prepared["isDedupStubResult"];
+    /** owned — the most-recently-read files projection, or undefined without read state. */
+    recentlyReadFiles: Prepared["recentlyReadFiles"];
+    /** owned — the landed-compaction read-state hook, or undefined without read state. */
+    onCompactionApplied: Prepared["onCompactionApplied"];
+    /** owned — the boundary-time changed-files scan, or undefined without read state. */
+    detectExternalChanges: Prepared["detectExternalChanges"];
+    /** owned — the post-compact background-task listing (`Prepared.listBackgroundTasks`). */
+    listBackgroundTasks: Prepared["listBackgroundTasks"];
+    /** owned — the compaction-boundary center adoption candidate, or undefined (no source, or no adoption). */
+    centerCompactionCandidate: Prepared["centerCompactionCandidate"];
+    /** owned — the effective read face observed for the result seats (`Prepared.effectiveReadFace`), or undefined. */
+    effectiveReadFaceObserved: ReadFace | undefined;
+    /** owned — the effective read-deny patterns observed (fresh copies), or undefined when none. */
+    effectiveReadDenyObserved: Array<{
+        pattern: string;
+        caseSensitive: boolean;
+    }> | undefined;
+}
+/** The M22 phase body — prepareTask's turn-wiring stretch, verbatim (see the module header). */
+export declare function prepareTurnWiring(input: PrepareTurnWiringInput): PrepareTurnWiringResult;

package/dist/core/runner/prepare-turn-wiring.js

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import { assemblePrompt } from "../../prompt-assembly/assemble.js";
+import { artifactDeclarations } from "../../prompt-assembly/artifact.js";
+import { buildTurnPromptSnapshot } from "../../prompt-assembly/turn-snapshot.js";
+import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
+import { defaultTaskRegistry } from "../task-registry.js";
+import { refuseOutOfContractDecision } from "../tool-policy.js";
+import { decodeTextBytes } from "../../tools/fs/encoding.js";
+import { applyCompactionToReadFileState, isReadDedupStubResult } from "../../tools/fs/index.js";
+import { resolveKey } from "../../tools/fs/safety.js";
+import { PROMPT_HASH_SALT } from "./prompt-hash-salt.js";
+import { CHANGED_FILES_MTIME_EPS_MS } from "./turn-attachments.js";
+export function prepareTurnWiring(input) {
+    const { deps, systemPromptSeat, harnessTools, fpRef, model, epochArtifactDigestForSnapshot, promptProfile, fableMitigations, systemBlocks, thinking, spec, sessionId, turnSnapshotRef, promptManifest, charsPerToken, handsEnabled, executionEnv, attachmentRootCanonical, additionalRootsCanonical, additionalReadRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, readFileStateForCheckpoint, denyNarrowingPolicy, abortController, hostTaskId, taskScope, buildAssembleInputs, centerAdoptionRef, harnessRef, epochDeclaredSections, carrierReadFace, readDenyAdditionsNormalized, preparedHolder } = input;
+    const cacheBreakDetector = deps.cacheBreakDetection === false ? undefined : new CacheBreakDetector();
+    const cacheFingerprint = cacheBreakDetector
+        ? { systemPrompt: systemPromptSeat.current, tools: toolsToFingerprintInputs(harnessTools) }
+        : undefined;
+    fpRef.current = cacheFingerprint;
+    const turnSnapshot = buildTurnPromptSnapshot({
+        provider: model.provider,
+        modelId: model.id,
+        artifactDigest: epochArtifactDigestForSnapshot,
+        promptProfile,
+        fableMitigations,
+        layoutGroups: (systemBlocks ?? [{ groupId: "body", cacheControlBoundary: true }]).map((b) => ({ groupId: b.groupId, cacheControlBoundary: b.cacheControlBoundary })),
+        stableSystemText: systemPromptSeat.current,
+        toolWire: toolsToFingerprintInputs(harnessTools),
+        thinkingLevel: (thinking ?? "off"),
+        maxTokens: model.maxTokens,
+        hasOutputSchema: spec.outputSchema !== undefined,
+        sessionId,
+        taskId: spec.taskId,
+    }, model.api, (text) => `salted:${createHash("sha256").update(PROMPT_HASH_SALT).update(text).digest("hex")}`);
+    turnSnapshotRef.current = turnSnapshot;
+    promptManifest.snapshot = { cacheIdentity: turnSnapshot.cacheIdentity, elements: { ...turnSnapshot.elements } };
+    promptManifest.lowering = turnSnapshot.lowering;
+    const promptOverheadTokens = Math.ceil((systemPromptSeat.current.length +
+        harnessTools.reduce((a, t) => a + t.name.length + (t.description?.length ?? 0) + JSON.stringify(t.parameters ?? {}).length, 0)) / charsPerToken);
+    const announceAttachmentSkip = (path, reason) => {
+        deps.onError?.(new Error(`working-file attachment skipped — ${path}: ${reason}`), {
+            phase: "degraded",
+            sessionId,
+            classification: "attachment-read",
+        });
+    };
+    const readTaskFile = handsEnabled
+        ? async (path) => {
+            try {
+                let key = path;
+                if (attachmentRootCanonical !== undefined) {
+                    const rk = await resolveKey(executionEnv, attachmentRootCanonical, path, undefined, undefined, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, readDenyMatcher, resolvedReadFace);
+                    if (!rk.ok) {
+                        announceAttachmentSkip(path, rk.violation.message);
+                        if (rk.violation.code === "read_path_denied" && rk.violation.pattern !== undefined) {
+                            return { withheld: { pattern: rk.violation.pattern } };
+                        }
+                        return null;
+                    }
+                    key = rk.key;
+                }
+                const r = await executionEnv.readBinaryFile(key);
+                if (!r.ok) {
+                    announceAttachmentSkip(path, r.error.message);
+                    return null;
+                }
+                const d = decodeTextBytes(r.value);
+                if (d.malformed) {
+                    announceAttachmentSkip(path, "malformed text encoding (truncated UTF-16 body)");
+                    return null;
+                }
+                return d.text;
+            }
+            catch (err) {
+                announceAttachmentSkip(path, err instanceof Error ? err.message : String(err));
+                return null;
+            }
+        }
+        : undefined;
+    const normalizeAttachmentPath = handsEnabled
+        ? async (path) => {
+            if (attachmentRootCanonical === undefined)
+                return path;
+            try {
+                const rk = await resolveKey(executionEnv, attachmentRootCanonical, path, undefined, handsCwdRef?.current, [...additionalRootsCanonical, ...additionalReadRootsCanonical], undefined, undefined, resolvedReadFace);
+                return rk.ok ? rk.key : path;
+            }
+            catch {
+                return path;
+            }
+        }
+        : undefined;
+    const isDedupStubResult = handsEnabled ? isReadDedupStubResult : undefined;
+    const recentlyReadFiles = handsEnabled && readFileStateForCheckpoint
+        ? () => [...readFileStateForCheckpoint.entries()]
+            .filter(([, v]) => v.seededFromContext !== true)
+            .sort((a, b) => (b[1].lastReadAt ?? 0) - (a[1].lastReadAt ?? 0))
+            .map(([path]) => path)
+        : undefined;
+    const onCompactionApplied = handsEnabled && readFileStateForCheckpoint
+        ? (attachedComplete, preserveReadState) => applyCompactionToReadFileState(readFileStateForCheckpoint, attachedComplete, preserveReadState)
+        : undefined;
+    const changedFilesReadDenied = denyNarrowingPolicy === undefined
+        ? undefined
+        : async (path) => {
+            try {
+                const d = refuseOutOfContractDecision(await denyNarrowingPolicy.check({ toolName: "Read", args: { file_path: path }, toolCallId: "changed-files-visibility-probe" }, abortController.signal));
+                return d.action === "deny";
+            }
+            catch {
+                return false;
+            }
+        };
+    const detectExternalChanges = handsEnabled && readFileStateForCheckpoint
+        ? async (maxFiles) => {
+            const candidates = [...readFileStateForCheckpoint.entries()]
+                .filter(([, e]) => e.lastReadAt !== undefined)
+                .filter(([, e]) => e.truncated !== true)
+                .sort((a, b) => (b[1].lastReadAt ?? 0) - (a[1].lastReadAt ?? 0))
+                .slice(0, Math.max(0, maxFiles));
+            const changed = [];
+            const evicted = [];
+            for (const [path, entry] of candidates) {
+                if (changedFilesReadDenied !== undefined && (await changedFilesReadDenied(path)))
+                    continue;
+                try {
+                    const info = await executionEnv.fileInfo(path, abortController.signal);
+                    if (!info.ok) {
+                        if (info.error.code === "not_found") {
+                            readFileStateForCheckpoint.delete(path);
+                            evicted.push(path);
+                        }
+                        continue;
+                    }
+                    if (info.value.mtimeMs > (entry.lastReadAt ?? 0) + CHANGED_FILES_MTIME_EPS_MS) {
+                        changed.push({ path, mtimeMs: info.value.mtimeMs });
+                    }
+                }
+                catch {
+                }
+            }
+            return { changed, evicted };
+        }
+        : undefined;
+    const listBackgroundTasks = () => defaultTaskRegistry
+        .list({ owner: hostTaskId, scope: taskScope, sessionId })
+        .filter((t) => t.status === "pending" || t.status === "running" || t.status === "parked")
+        .map((t) => ({ id: t.task_id, ...(t.description !== undefined ? { description: t.description } : {}), status: t.status }));
+    const overheadState = { promptChars: 0 };
+    const centerCompactionCandidate = deps.promptSource !== undefined && centerAdoptionRef.current !== undefined
+        ? () => {
+            const state = deps.promptSource.sourceState?.() ?? "unavailable";
+            const cand = deps.promptSource.current();
+            const toBundled = state === "disabled";
+            if (!toBundled && (cand === undefined || cand.artifact.artifactDigest === centerAdoptionRef.current.artifact.artifactDigest))
+                return undefined;
+            let a2;
+            try {
+                a2 = assemblePrompt(buildAssembleInputs(toBundled ? undefined : artifactDeclarations(cand.artifact)));
+            }
+            catch {
+                return undefined;
+            }
+            if (!toBundled && a2.centerMounted !== true)
+                return undefined;
+            const declared2 = (a2.sections ?? [])
+                .filter((sec) => sec.origin === "provider")
+                .map((sec) => ({ id: sec.id, slot: sec.slot, chars: sec.text.length, ...(sec.declaredContentHash !== undefined ? { contentHash: sec.declaredContentHash } : {}) }));
+            const overheadTokensAfter = preparedHolder.current.promptOverheadTokens -
+                Math.ceil(overheadState.promptChars / charsPerToken) +
+                Math.ceil(a2.systemPrompt.length / charsPerToken);
+            return {
+                ...(toBundled
+                    ? { clear: true }
+                    : {
+                        centerArtifactDigest: cand.artifact.artifactDigest,
+                        ...(cand.sourceRevision !== undefined ? { sourceRevision: cand.sourceRevision } : {}),
+                    }),
+                declaredSections: declared2,
+                overheadTokensAfter,
+                apply: (committedArtifactDigest) => {
+                    systemPromptSeat.current = a2.systemPrompt;
+                    harnessRef.current?.setSystemPrompt(a2.systemPrompt, a2.systemBlocks);
+                    if (fpRef.current)
+                        fpRef.current.systemPrompt = a2.systemPrompt;
+                    turnSnapshotRef.current?.refreshStableSystem(a2.systemPrompt, committedArtifactDigest);
+                    preparedHolder.current.epochDeclaredSections = declared2;
+                    preparedHolder.current.promptOverheadTokens = overheadTokensAfter;
+                    overheadState.promptChars = a2.systemPrompt.length;
+                    centerAdoptionRef.current = toBundled
+                        ? undefined
+                        : { artifact: cand.artifact, ...(cand.sourceRevision !== undefined ? { sourceRevision: cand.sourceRevision } : {}) };
+                },
+            };
+        }
+        : undefined;
+    overheadState.promptChars = systemPromptSeat.current.length;
+    const effectiveReadFaceObserved = carrierReadFace();
+    const effectiveReadDenyObserved = readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized.map((e) => ({ ...e })) : undefined;
+    return { cacheBreakDetector, cacheFingerprint, promptOverheadTokens, readTaskFile, normalizeAttachmentPath, isDedupStubResult, recentlyReadFiles, onCompactionApplied, detectExternalChanges, listBackgroundTasks, centerCompactionCandidate, effectiveReadFaceObserved, effectiveReadDenyObserved };
+}

package/dist/core/runner/prepare-wiring-manifest.d.ts

@@ -25,7 +25,8 @@ import type { LockedPreflight } from "../locked-config.js";
 import type { MaterializedMcp } from "../mcp.js";
 import type { SessionStore } from "../session.js";
 import { type ToolResultStore } from "../tool-result-store.js";
-import { type ApprovalSettledBy, type OnAsk } from "../tool-policy.js";
+import { type OnAsk, type ToolPolicy } from "../tool-policy.js";
+import type { GateOutcome } from "../gate-outcome.js";
 import type { RunnerDeps, RuntimeCaps, TaskSpec, ToolEffect, ToolExecuteContext } from "../types.js";
 import { type UsageWindow } from "../usage-window-store.js";
 import { type AutoModeArmReason, type WiringManifest, type WiringManifestMcpEntry } from "../wiring-manifest.js";
@@ -33,8 +34,9 @@ import type { AnnounceOnceSink, Prepared, PrepareResume, RunInternals, UsageGove
 export interface PrepareWiringManifestInput {
     /** borrowed-readonly — the REBOUND spec. Read: `onAsk` (the own seat), `onQuestion` (the question seam), `handsReadOnly` / `tools` (the ungated scan),
      *  `resourceSuspend` (the task-axis lane), `durableApproval` / `principal` (the synthesis and the notice), `interactiveTools` /
-     *  `mcp` / `checkpointStore` (manifest cells and the notice's cause). Never mutated. */
-    spec: Pick<TaskSpec, "onAsk" | "onQuestion" | "handsReadOnly" | "tools" | "resourceSuspend" | "durableApproval" | "principal" | "interactiveTools" | "mcp" | "checkpointStore">;
+     *  `mcp` / `checkpointStore` (manifest cells and the notice's cause), `enablePlanMode` (the gate-machinery predicate's
+     *  plan-mode term). Never mutated. */
+    spec: Pick<TaskSpec, "onAsk" | "onQuestion" | "handsReadOnly" | "tools" | "resourceSuspend" | "durableApproval" | "principal" | "interactiveTools" | "mcp" | "checkpointStore" | "enablePlanMode">;
     /** borrowed-readonly — the deployment seats, whole: `onAsk` (the seat's deps half), `onError` (the warning), `executionEnv`
      *  (the hook-env predicate), `checkpointStore` (durable infra), the manifest's dozen wiring facts (`backgroundAgentStore`,
      *  `permissionRuleStore`, `permissionRuleSyncWired`, `onBackgroundChildEvent`, `lockedConfig`, `compliancePostureResolver`,
@@ -61,6 +63,9 @@ export interface PrepareWiringManifestInput {
     preToolUseObservational: boolean;
     /** borrowed-readonly — the caller-facing policy layers; only their COUNT is read (an effect-aware gate exists). */
     policyLayers: ReadonlyArray<unknown>;
+    /** borrowed-readonly — the policy chain's effective policy, or undefined; only its PRESENCE is read (the first term of the
+     *  gate-machinery predicate below). Never called here. */
+    effectivePolicy: ToolPolicy | undefined;
     /** borrowed-readonly — whether an execution env is wired (the hand band exists at all). */
     handsEnabled: boolean;
     /** borrowed-readonly — the materialized MCP handle: `tools` (the destructive-ungated scan) and `statuses` (the manifest face). */
@@ -109,9 +114,7 @@ export interface PrepareWiringManifestInput {
     /** borrowed-readonly — the built harness the peer drain binds to. */
     harness: AgentHarness;
     /** borrowed-readonly — the durable-suspend holder; the drain's parked predicate reads `token` at run time. Not written here. */
-    suspendRef: Prepared["suspendRef"];
-    /** borrowed-readonly — the review holder; same read. Not written here. */
-    reviewRef: Prepared["reviewRef"];
+    pausedRef: Prepared["pausedRef"];
     /** borrowed-readonly — the FROZEN approver seat (the notice's liveApprover fact). */
     frozenOnAsk: OnAsk | undefined;
     /** borrowed-readonly — the LIVE half of the inherited chain (the notice reads its content mandates). */
@@ -130,16 +133,9 @@ export interface PrepareWiringManifestResult {
     /** borrowed-mutable — the call ids the gate blocked or suspended (`Prepared.blockedToolCalls`). Writers: the gate; readers
      *  delete one-shot. */
     blockedToolCalls: Set<string>;
-    /** borrowed-mutable — the settlement sideband (`Prepared.approvalSettlement`). Writer: the gate; the frame mint reads and
+    /** borrowed-mutable — the gate-outcome sideband (`Prepared.gateOutcomes`). Writer: the gate station; the frame mint reads and
      *  deletes. Nothing else may write it. */
-    approvalSettlement: Map<string, {
-        settledBy?: ApprovalSettledBy;
-        approver?: string;
-        resolution?: import("../tool-policy.js").AskDenyResolution;
-        autoDenied?: true;
-    }>;
-    /** borrowed-mutable — the bare-human-rejection sideband. Writer: resolveAskBound; the gate handler consumes one-shot. */
-    humanBareRejections: Set<string>;
+    gateOutcomes: Map<string, GateOutcome>;
     /** borrowed-mutable — the turn's halt fact (`Prepared.batchHaltRef`). Writer: the judgment site; cleared at the next request. */
     batchHaltRef: Prepared["batchHaltRef"];
     /** owned — whether any consumer of the blocked set is wired (populate only then). */
@@ -160,6 +156,10 @@ export interface PrepareWiringManifestResult {
     wiringManifest: WiringManifest;
     /** owned — THE park predicate as one named const (`parkLane.effective === true`). */
     parkLaneArmed: boolean;
+    /** owned — THE gate-machinery activation predicate as one named const: a policy, a screening hook, an egress or
+     *  irreversible tool, an eligible resource lane, an armed platform lane, or plan mode. The ask lane, the suspend saga,
+     *  the boundary parks, the park closure and the gate station are built exactly when it holds. */
+    gateMachineryActive: boolean;
     /** owned — THE identity mint of this leg (`Prepared.hookIdentity`), one frozen envelope every hook station reuses. */
     hookIdentity: HookInvocationIdentity;
     /** owned — the read-only env capability face every hook context carries, or undefined (no hook consumer, or no env wired). */
@@ -170,8 +170,8 @@ export interface PrepareWiringManifestResult {
  * server the leg's FROZEN entry snapshot declared, in declaration order, joined by name to this leg's
  * materialization statuses. Pure projection — no connection logic, no second look at any transport:
  *  · a status `connected` ⇒ `connected` with the mounted roster size (the intake's post-filter count);
- *  · a status `failed` ⇒ `failed` with the class the materialization stamped ({@link McpFailureCode})
- *    and the remote text SECRET-REDACTED (an HTTP endpoint's error body rides the SDK's message
+ *  · a status `failed` ⇒ `failed` with the failure record the materialization stamped (`errorCode`/`delivered`/
+ *    `httpStatus` = the MCP vocabulary's `McpFailure` spread flat) and the remote text SECRET-REDACTED (an HTTP endpoint's error body rides the SDK's message
  *    verbatim, and a body that echoes the bearer it rejected must not reach a stream consumer),
  *    then neutralized + bounded to the reminder's own 240 (the same bound the once-per-session
  *    ledger applies to that text — one face, one width);

package/dist/core/runner/prepare-wiring-manifest.js

@@ -22,7 +22,7 @@ export function mcpManifestEntries(entries, statuses) {
             name: entry.name,
             ...source,
             status: "failed",
-            ...(status.errorCode !== undefined ? { errorCode: status.errorCode } : {}),
+            ...(status.errorCode !== undefined ? { errorCode: status.errorCode, delivered: status.delivered, ...(status.httpStatus !== undefined ? { httpStatus: status.httpStatus } : {}) } : {}),
             ...(status.error !== undefined ? { error: inlineUntrusted(status.error, 240) } : {}),
             toolCount: 0,
         };
@@ -87,17 +87,17 @@ const ungatedWarnedShapes = new WeakMap();
 function announceDurableGateUnavailable(args) {
     if (!args.forceDurableGate || args.storeWired)
         return;
-    const cause = args.taskStoreNull ? "task_store_null" : "no_deployment_store";
+    const cause = args.taskStoreDisabled ? "task_store_disabled" : "no_deployment_store";
     const inheritedContentMandate = (args.parentConstraints ?? []).some((pc) => pc.contentMandate === true);
     const liveQuestionFace = args.liveQuestionFace && !inheritedContentMandate;
     deliverEngineNotice(args.onNotice, {
         code: "config.durable_gate_unavailable",
         message: `Durable approval gate mandated but unavailable: the runtime entitlement forceDurableGate is in force for this ` +
-            `principal, but ${cause === "task_store_null" ? "this task disabled the checkpoint store (checkpointStore: null)" : "this deployment wired no checkpoint store"}, ` +
+            `principal, but ${cause === "task_store_disabled" ? 'this task disabled the checkpoint store (checkpointStore: "disabled")' : "this deployment wired no checkpoint store"}, ` +
             `so no interactive ask of this task can be parked for a durable answer. Asks resolve on the live chain instead ` +
             `(${args.liveApprover ? "a live approver answers permission asks in-stream" : "permission asks are denied fail-closed — no live approver is wired"}; ` +
             `${liveQuestionFace ? "a live question face answers AskUserQuestion in-stream" : args.liveQuestionFace ? "AskUserQuestion is withheld from the live face by an inherited durable mandate and refused" : "AskUserQuestion has no live face and is refused"}) ` +
-            `and NO durable approval record is written. ${cause === "task_store_null" ? "Run this task with its store, or withdraw the entitlement for principals whose runs are machine-started." : "Wire a checkpoint store on this deployment, or withdraw the entitlement for principals served here."}`,
+            `and NO durable approval record is written. ${cause === "task_store_disabled" ? "Run this task with its store, or withdraw the entitlement for principals whose runs are machine-started." : "Wire a checkpoint store on this deployment, or withdraw the entitlement for principals served here."}`,
         detail: {
             sessionId: args.sessionId,
             runId: args.runId,
@@ -109,7 +109,7 @@ function announceDurableGateUnavailable(args) {
     });
 }
 export function prepareWiringManifest(input) {
-    const { spec, deps, internals, resume, sessionId, runId, hostTaskId, taskScope, hooks, preToolUseObservational, policyLayers, handsEnabled, mcp, irreversibleTools, egressTools, toolEffects, ownedEnv, executionEnv, offloadStore, onceLedger, usageWindows, envLifetimeSuspendAt, runtimeCaps, resolvedInteractionPosture, durableQuestionFace, liveQuestionFace, checkpointStore, sessions, modelGateManifest, autoModeArmReason, lockedPreflight, peerLaneRefs, peerLaneActive, harness, suspendRef, reviewRef, frozenOnAsk, liveInheritedGate, delegation } = input;
+    const { spec, deps, internals, resume, sessionId, runId, hostTaskId, taskScope, hooks, preToolUseObservational, policyLayers, effectivePolicy, handsEnabled, mcp, irreversibleTools, egressTools, toolEffects, ownedEnv, executionEnv, offloadStore, onceLedger, usageWindows, envLifetimeSuspendAt, runtimeCaps, resolvedInteractionPosture, durableQuestionFace, liveQuestionFace, checkpointStore, sessions, modelGateManifest, autoModeArmReason, lockedPreflight, peerLaneRefs, peerLaneActive, harness, pausedRef, frozenOnAsk, liveInheritedGate, delegation } = input;
     const onAsk = spec.onAsk ?? deps.onAsk;
     const handWriteTools = handsEnabled && spec.handsReadOnly !== true
         ? Object.keys(HAND_TOOL_EFFECTS).filter((name) => {
@@ -144,8 +144,7 @@ export function prepareWiringManifest(input) {
     }
     const preToolContexts = new Map();
     const blockedToolCalls = new Set();
-    const approvalSettlement = new Map();
-    const humanBareRejections = new Set();
+    const gateOutcomes = new Map();
     const batchHaltRef = {};
     const blockedTracked = Boolean(hooks?.postToolUse || hooks?.preToolUse || hooks?.postToolUseFailure || hooks?.postToolBatch);
     const restoreSurfaceGap = ownedEnv !== undefined && isRemoteExecutionEnv(ownedEnv) && ownedEnv.capabilities.suspendable ? missingRestoreSurface(ownedEnv) : [];
@@ -220,11 +219,18 @@ export function prepareWiringManifest(input) {
             ownTokens: () => internals?.peerSelfRef?.current.ownTokens ?? [],
             refs: peerLaneRefs,
             selfName: () => internals?.explicitAgentName,
-            parked: () => suspendRef.token !== undefined || reviewRef.token !== undefined,
+            parked: () => pausedRef.current !== undefined,
         });
     }
     const parkLaneArmed = wiringManifest.parkLane.effective === true;
-    announceDurableGateUnavailable({ onNotice: deps.onNotice, forceDurableGate: runtimeCaps?.forceDurableGate === true, storeWired: checkpointStore !== undefined, taskStoreNull: spec.checkpointStore === null, liveApprover: isLiveApproverSeat(frozenOnAsk), liveQuestionFace: liveQuestionFace !== undefined, parentConstraints: liveInheritedGate?.parentConstraints, sessionId, runId, principal: spec.principal });
+    const gateMachineryActive = effectivePolicy !== undefined ||
+        hooks?.preToolUse !== undefined ||
+        egressTools.size > 0 ||
+        irreversibleTools.size > 0 ||
+        resourceSuspendEligible ||
+        platformSuspendArmed ||
+        spec.enablePlanMode === true;
+    announceDurableGateUnavailable({ onNotice: deps.onNotice, forceDurableGate: runtimeCaps?.forceDurableGate === true, storeWired: checkpointStore !== undefined, taskStoreDisabled: spec.checkpointStore === "disabled", liveApprover: isLiveApproverSeat(frozenOnAsk), liveQuestionFace: liveQuestionFace !== undefined, parentConstraints: liveInheritedGate?.parentConstraints, sessionId, runId, principal: spec.principal });
     const hookIdentity = mintHookInvocationIdentity({
         sessionId,
         taskId: hostTaskId,
@@ -236,5 +242,5 @@ export function prepareWiringManifest(input) {
     });
     const hookContextConsumerWired = hooks?.preToolUse !== undefined || hooks?.postToolUse !== undefined || hooks?.postToolUseFailure !== undefined;
     const hookEnvFace = hookContextConsumerWired && (ownedEnv ?? deps.executionEnv) != null ? createHookEnvCapabilities(executionEnv) : undefined;
-    return { onAsk, preToolContexts, blockedToolCalls, approvalSettlement, humanBareRejections, batchHaltRef, blockedTracked, incompleteSuspendAdapter, durableSuspendInfraReady, resourceSuspendEligible, usageGovernance, platformSuspendArmed, durableApproval, wiringManifest, parkLaneArmed, hookIdentity, hookEnvFace };
+    return { onAsk, preToolContexts, blockedToolCalls, gateOutcomes, batchHaltRef, blockedTracked, incompleteSuspendAdapter, durableSuspendInfraReady, resourceSuspendEligible, usageGovernance, platformSuspendArmed, durableApproval, wiringManifest, parkLaneArmed, gateMachineryActive, hookIdentity, hookEnvFace };
 }

package/dist/core/runner/prepare-workspace-restore.d.ts

@@ -1,34 +1,7 @@
-import type { RemoteExecutionEnv, RemoteExecutionError, SnapshotId, VmLifecycleOptions } from "../remote-env.js";
 import type { ExecutionEnv } from "../../internal/harness.js";
-import type { RemoteEnvFailureNote, RunnerDeps, TaskSpec } from "../types.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { PrepareResume, RunInternals } from "./contracts.js";
-/**
- * RB-439-a — project one failed remote lifecycle call onto the caller-facing note. ONE builder for all
- * three ops so the `retryable` classification can never drift between the lane that reports a `suspendVM`
- * refusal and the lane that reports a failed restore.
- */
-export declare function remoteEnvFailureNote(op: RemoteEnvFailureNote["op"], error: RemoteExecutionError, attempts: number): RemoteEnvFailureNote;
-/**
- * RB-439-a — `resumeVM` with a bounded retry on the TRANSIENT codes, plus the attempt count for the
- * caller-facing note.
- *
- * Why this op and no other: `resumeVM` is the one lifecycle call the seam documents as "idempotent +
- * re-entrant" (a replica that crashed mid-suspend can be superseded by another resuming the SAME
- * snapshot), which is exactly `withRetry`'s red line — retry idempotent establishment, never a
- * side-effecting op. `suspendVM` TAKES a snapshot and `postResumeInit` re-injects secrets under an
- * ordering red line; neither is retried here, they are disclosed with `retryable` instead so the caller
- * decides. A code outside the retryable family (`unsupported`, `auth_failed`) returns on the first
- * attempt — `withRetry` will not spend a second call on a permanent refusal.
- */
-export declare function restoreWorkspaceWithRetry(env: RemoteExecutionEnv, snapshotId: SnapshotId, options: VmLifecycleOptions, 
-/** design/384 slice 2 (additive): observe each attempt AS IT STARTS. The returned `attempts` is
- *  only readable after settlement, and a caller whose wait on this promise is BOUNDED (the park
- *  compensation) must report the live attempt count when its bound fires mid-call — without this
- *  seat a deaf second attempt was reported as `attempts: 1`. */
-onAttempt?: (attempt: number) => void): Promise<{
-    outcome: Awaited<ReturnType<RemoteExecutionEnv["resumeVM"]>>;
-    attempts: number;
-}>;
+export { remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./remote-env-retry.js";
 export interface PrepareWorkspaceRestoreInput {
     /** borrowed-readonly (the ownership-ref PROTOCOL stays with the driver — D-8 案①): the env this
      *  task owns, when the factory minted one. This phase reads and drives it (`resumeVM`,

package/dist/core/runner/prepare-workspace-restore.js

@@ -1,20 +1,7 @@
-import { isRemoteExecutionEnv, isRetryableRemoteErrorCode, missingRestoreSurface, RETRYABLE_REMOTE_ERROR_CODES } from "../remote-env.js";
-import { withRetry } from "../with-retry.js";
+import { isRemoteExecutionEnv, missingRestoreSurface } from "../remote-env.js";
+import { remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./remote-env-retry.js";
 import { rebaseWorkspacePathAcross } from "./workspace-path.js";
-export function remoteEnvFailureNote(op, error, attempts) {
-    return { op, code: error.code, retryable: isRetryableRemoteErrorCode(error.code), attempts, message: error.message };
-}
-const REMOTE_RESTORE_MAX_ATTEMPTS = 2;
-const REMOTE_RESTORE_BACKOFF_MS = 200;
-export async function restoreWorkspaceWithRetry(env, snapshotId, options, onAttempt) {
-    let attempts = 0;
-    const outcome = await withRetry(async (attempt) => {
-        attempts = attempt;
-        onAttempt?.(attempt);
-        return env.resumeVM(snapshotId, options);
-    }, { retryableCodes: RETRYABLE_REMOTE_ERROR_CODES, maxAttempts: REMOTE_RESTORE_MAX_ATTEMPTS, backoffMs: () => REMOTE_RESTORE_BACKOFF_MS }, { ...(options.abortSignal !== undefined ? { signal: options.abortSignal } : {}) });
-    return { outcome, attempts };
-}
+export { remoteEnvFailureNote, restoreWorkspaceWithRetry } from "./remote-env-retry.js";
 export async function prepareWorkspaceRestore(input) {
     const { ownedEnv, deps, spec, internals, resume, abortController, sessionId } = input;
     let taskRootPath = input.taskRootInitial;

package/dist/core/runner/prompt-hash-salt.d.ts

@@ -0,0 +1 @@
+export declare const PROMPT_HASH_SALT: Buffer<ArrayBufferLike>;

package/dist/core/runner/prompt-hash-salt.js

@@ -0,0 +1,2 @@
+import { randomBytes } from "node:crypto";
+export const PROMPT_HASH_SALT = randomBytes(16);

package/dist/core/runner/remote-env-retry.d.ts

@@ -0,0 +1,29 @@
+import type { RemoteExecutionEnv, RemoteExecutionError, SnapshotId, VmLifecycleOptions } from "../remote-env.js";
+import type { RemoteEnvFailureNote } from "../types.js";
+/**
+ * RB-439-a — project one failed remote lifecycle call onto the caller-facing note. ONE builder for all
+ * three ops so the `retryable` classification can never drift between the lane that reports a `suspendVM`
+ * refusal and the lane that reports a failed restore.
+ */
+export declare function remoteEnvFailureNote(op: RemoteEnvFailureNote["op"], error: RemoteExecutionError, attempts: number): RemoteEnvFailureNote;
+/**
+ * RB-439-a — `resumeVM` with a bounded retry on the TRANSIENT codes, plus the attempt count for the
+ * caller-facing note.
+ *
+ * Why this op and no other: `resumeVM` is the one lifecycle call the seam documents as "idempotent +
+ * re-entrant" (a replica that crashed mid-suspend can be superseded by another resuming the SAME
+ * snapshot), which is exactly `withRetry`'s red line — retry idempotent establishment, never a
+ * side-effecting op. `suspendVM` TAKES a snapshot and `postResumeInit` re-injects secrets under an
+ * ordering red line; neither is retried here, they are disclosed with `retryable` instead so the caller
+ * decides. A code outside the retryable family (`unsupported`, `auth_failed`) returns on the first
+ * attempt — `withRetry` will not spend a second call on a permanent refusal.
+ */
+export declare function restoreWorkspaceWithRetry(env: RemoteExecutionEnv, snapshotId: SnapshotId, options: VmLifecycleOptions, 
+/** design/384 slice 2 (additive): observe each attempt AS IT STARTS. The returned `attempts` is
+ *  only readable after settlement, and a caller whose wait on this promise is BOUNDED (the park
+ *  compensation) must report the live attempt count when its bound fires mid-call — without this
+ *  seat a deaf second attempt was reported as `attempts: 1`. */
+onAttempt?: (attempt: number) => void): Promise<{
+    outcome: Awaited<ReturnType<RemoteExecutionEnv["resumeVM"]>>;
+    attempts: number;
+}>;