@sema-agent/core 7.5.0 → 7.5.2

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

@@ -0,0 +1,192 @@
+/**
+ * design/390 §1.2 M18 — prepareTask's WIRING-MANIFEST phase, verbatim from the driver: the run's own frozen approver
+ * seat, the loud ungated-write warning (hand band / destructive MCP / first-party write tools with no effect-aware gate,
+ * deduped per deployment and tool-set shape), the PreToolUse context stash and the blocked-call set, the settlement and
+ * bare-rejection sidebands, the turn halt fact, the suspend infrastructure predicates (restore surface gap, durable
+ * infra, the task-axis lane with its INACTIVE line), usage governance, the platform-suspend arming, the synthesized
+ * durableApproval, the effective wiring manifest, the peer lane's ask fold and drain binding, the park predicate as ONE
+ * named const, the durable-gate-unavailable notice, the hook identity mint and the hook env face. The four helpers only
+ * this segment called moved with it (usage governance, the per-deployment warn ledger, the MCP manifest projection, the
+ * durable-gate notice). The interface is the dependency list the segment had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between the policy-chain
+ * station before it and the gate registration after it (design/390 §1.5: a stretch with no await is extracted as a sync
+ * function). Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * One read changed spelling and nothing else: the manifest's MCP face read `mcp?.statuses ?? []` while `mcp` had long
+ * been the protocol-tools phase's non-null handle; the optional chain was dead and is now the plain member read.
+ */
+import type { AgentHarness, ExecutionEnv } from "../../internal/harness.js";
+import { type PeerLaneRefs } from "../../agents/peer-session-drain.js";
+import type { OnQuestion } from "../ask-question.js";
+import type { CheckpointStore } from "../checkpoint-store.js";
+import { type HookEnvCapabilities, type HookInvocationIdentity, type Hooks } from "../hooks.js";
+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, type ToolPolicy } from "../tool-policy.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";
+import type { AnnounceOnceSink, Prepared, PrepareResume, RunInternals, UsageGovernance } from "./contracts.js";
+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), `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`,
+     *  `memoryScopeAdmission`, `retentionPolicy`, `onElicit`), `onNotice`, and the usage-governance seats (`usageWindowStore`,
+     *  `now`, `onUsageGovernance`…) the helper reads through the whole record. */
+    deps: RunnerDeps;
+    /** borrowed-readonly — the trusted spawn-side channel: `questionFaceStripped`, `isDelegatedChild`, `onTaskNotification`,
+     *  `peerSelfRef`, `explicitAgentName` (the drain), `insideFork` / `agentName` / `parentToolCallId` (the identity). */
+    internals: Pick<RunInternals, "questionFaceStripped" | "isDelegatedChild" | "onTaskNotification" | "peerSelfRef" | "explicitAgentName" | "insideFork" | "agentName" | "parentToolCallId"> | undefined;
+    /** borrowed-readonly — the resume leg, or undefined (the manifest's leg derivation reads presence only). */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+    /** borrowed-readonly — the acquired session id. */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id. */
+    runId: string;
+    /** borrowed-readonly — the per-task identity (the hook identity's taskId). */
+    hostTaskId: string;
+    /** borrowed-readonly — the registry scope the peer drain binds under. */
+    taskScope: string;
+    /** borrowed-readonly — the resolved hook record (`spec.hooks ?? deps.hooks`): the effect-aware-gate term, the tracked flag
+     *  and the hook-env face's consumer test. */
+    hooks: Hooks | undefined;
+    /** borrowed-readonly — whether the deployment declared its screening face observational (then it is no gate). */
+    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). */
+    mcp: Pick<MaterializedMcp, "tools" | "statuses">;
+    /** borrowed-readonly — the assembled safety vocabulary (the ungated scans and the manifest's armed cell). Read only. */
+    irreversibleTools: ReadonlySet<string>;
+    /** borrowed-readonly — see `irreversibleTools`. */
+    egressTools: ReadonlySet<string>;
+    /** borrowed-readonly — the effect collection; read only here (the ungated scans). */
+    toolEffects: ReadonlyMap<string, ToolEffect>;
+    /** borrowed-readonly — the per-task owned env when a factory minted one (durable infra, the hook-env predicate). */
+    ownedEnv: ExecutionEnv | undefined;
+    /** borrowed-readonly — the run's resolved env (the hook env face is built over it). */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the run's offload store, or undefined (a volatile store disqualifies durable suspend). */
+    offloadStore: ToolResultStore | undefined;
+    /** borrowed-readonly — the once-per-session ledger's operator sink (the INACTIVE line, once per session). */
+    onceLedger: Pick<AnnounceOnceSink, "onError">;
+    /** borrowed-readonly — the resolved usage windows, or undefined. */
+    usageWindows: readonly UsageWindow[] | undefined;
+    /** borrowed-readonly — the env-lifetime suspend instant, or undefined (platform-suspend arming). */
+    envLifetimeSuspendAt: number | undefined;
+    /** borrowed-readonly — the resolved per-principal entitlements (forceDurableGate). */
+    runtimeCaps: RuntimeCaps | undefined;
+    /** borrowed-readonly — the resolved interaction posture (a manifest cell). */
+    resolvedInteractionPosture: ToolExecuteContext["interactionPosture"];
+    /** borrowed-readonly — the question-face phase's durable-face decision (the composition-lie detector reuses it). */
+    durableQuestionFace: boolean;
+    /** borrowed-readonly — the live question face, or undefined (the notice's effective fact). */
+    liveQuestionFace: OnQuestion | undefined;
+    /** borrowed-readonly — the leg's checkpoint store, resolved once by the question-face phase. */
+    checkpointStore: CheckpointStore | undefined;
+    /** borrowed-readonly — the session store (durability declaration and transcript tier). */
+    sessions: SessionStore;
+    /** borrowed-readonly — the model gate's per-leg read face, or undefined. */
+    modelGateManifest: WiringManifest["modelGate"];
+    /** borrowed-readonly — the arming outcome the caps phase minted (the manifest's auto-mode face). */
+    autoModeArmReason: AutoModeArmReason;
+    /** borrowed-readonly — the frozen preflight; only `mcp` (the declared servers the manifest face joins). */
+    lockedPreflight: Pick<LockedPreflight, "mcp">;
+    /** borrowed-mutable — the peer lane's late-bound facts. Writer here: `askEffective` ← the manifest's ask derivation (the
+     *  one fold of this session's permission-mode class). */
+    peerLaneRefs: PeerLaneRefs;
+    /** borrowed-readonly — the peer lane's mount verdict (the drain binds only while mounted). */
+    peerLaneActive: boolean;
+    /** 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"];
+    /** 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). */
+    liveInheritedGate: RunInternals["inheritedGate"];
+    /** borrowed-readonly — the effective delegation facts (the identity's isDelegatedChild). */
+    delegation: {
+        isDelegatedChild: boolean;
+    };
+}
+export interface PrepareWiringManifestResult {
+    /** owned — the run's own approver seat (spec over deps), read by the gate-fold station. */
+    onAsk: OnAsk | undefined;
+    /** borrowed-mutable — PreToolUse `additionalContext` per call id. Writers: the gate (phase 1 stash), the post-tool handler
+     *  (one-shot drain). */
+    preToolContexts: Map<string, string[]>;
+    /** 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
+     *  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>;
+    /** 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). */
+    blockedTracked: boolean;
+    /** owned — the restore-surface gap of a declared-suspendable adapter, or undefined for a complete / non-suspendable one. */
+    incompleteSuspendAdapter: readonly ("resumeVM" | "postResumeInit")[] | undefined;
+    /** owned — the infrastructure half of suspend eligibility (no task opt-in in it). */
+    durableSuspendInfraReady: boolean;
+    /** owned — the task-axis lane: the infrastructure plus the caller's opt-in. */
+    resourceSuspendEligible: boolean;
+    /** owned — the run's usage-governance handle, or undefined (`Prepared.usageGovernance`). */
+    usageGovernance: UsageGovernance | undefined;
+    /** owned — whether the suspend saga must be armed for a PLATFORM cause. */
+    platformSuspendArmed: boolean;
+    /** owned — the effective durable-approval opt-in: the caller's, or the scope synthesized for a forced durable gate. */
+    durableApproval: TaskSpec["durableApproval"];
+    /** owned — this leg's EFFECTIVE wiring manifest (`Prepared.wiringManifest`). */
+    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). */
+    hookEnvFace: HookEnvCapabilities | undefined;
+}
+/**
+ * The wiring manifest's per-server MCP read face for one leg ({@link WiringManifest.mcp}): every
+ * 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
+ *    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);
+ *  · no status at all ⇒ `skipped` (the declaration stands, this leg produced no attempt record for it).
+ * `source` is echoed from the declaration (single-line, bounded; core reads nothing off it). The
+ * entries are fresh objects so the manifest never aliases the status records the refresh face mutates.
+ */
+export declare function mcpManifestEntries(entries: ReadonlyArray<import("../types.js").McpServerSpec> | undefined, statuses: ReadonlyArray<import("../mcp.js").McpServerStatus>): WiringManifestMcpEntry[];
+/** The M18 phase body — prepareTask's wiring-manifest stretch, verbatim (see the module header). */
+export declare function prepareWiringManifest(input: PrepareWiringManifestInput): PrepareWiringManifestResult;

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

@@ -0,0 +1,247 @@
+import { bindPeerLaneDrain } from "../../agents/peer-session-drain.js";
+import { HAND_TOOL_EFFECTS } from "../../tools/fs/index.js";
+import { resolveCheckpointStore } from "../checkpoint-store.js";
+import { createHookEnvCapabilities, mintHookInvocationIdentity } from "../hooks.js";
+import { isRemoteExecutionEnv, missingRestoreSurface } from "../remote-env.js";
+import { isVolatileOffloadStore } from "../tool-result-store.js";
+import { isLiveApproverSeat } from "../tool-policy.js";
+import { deliverEngineNotice } from "../types.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+import { GLOBAL_USAGE_KEY, usageRetryAfterMs, windowsGovernCost } from "../usage-window-store.js";
+import { countElicitOptIns, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam, resolveSubagentTranscriptTier } from "../wiring-manifest.js";
+import { DEFAULT_IRREVERSIBLE_SCOPE } from "./checkpoint-scope.js";
+export function mcpManifestEntries(entries, statuses) {
+    return (entries ?? []).map((entry) => {
+        const status = statuses.find((s) => s.name === entry.name);
+        const source = typeof entry.source === "string" && entry.source.length > 0 ? { source: inlineUntrusted(entry.source, 80) } : {};
+        if (status === undefined)
+            return { name: entry.name, ...source, status: "skipped", toolCount: 0 };
+        if (status.status === "connected")
+            return { name: entry.name, ...source, status: "connected", toolCount: status.toolNames?.length ?? 0 };
+        return {
+            name: entry.name,
+            ...source,
+            status: "failed",
+            ...(status.errorCode !== undefined ? { errorCode: status.errorCode } : {}),
+            ...(status.error !== undefined ? { error: inlineUntrusted(status.error, 240) } : {}),
+            toolCount: 0,
+        };
+    });
+}
+function buildUsageGovernance(windows, deps, principal, sessionId) {
+    if (windows === undefined || windows.length === 0)
+        return undefined;
+    const store = deps.usageWindowStore;
+    if (store === undefined) {
+        deps.onError?.(new Error("RunnerDeps.usageWindows is set but INACTIVE: no `usageWindowStore` is wired, so cross-task usage cannot be counted and no window can be enforced. Wire InMemoryUsageWindowStore (process-local) or FileUsageWindowStore (restart-surviving)."), { phase: "config", sessionId });
+        return undefined;
+    }
+    const key = principal || GLOBAL_USAGE_KEY;
+    const governsCost = windowsGovernCost(windows);
+    let chargedTokens = 0;
+    let chargedCostMicroUsd = 0;
+    let announcedCostGap = false;
+    let recordedUnpricedGap = false;
+    return {
+        key,
+        governsCost,
+        async check(now) {
+            const readings = await store.read(key, windows, now);
+            if (!announcedCostGap && readings.some((r) => r.costUnknown === true)) {
+                announcedCostGap = true;
+                deps.onError?.(new Error(`the usage window for ledger key ${JSON.stringify(key)} holds spend that nothing could price, so its maxCostUsd ceiling is being evaluated against a LOWER BOUND until that charge ages out of the window. Price every model this deployment can reach (including degrade targets and the compaction model).`), { phase: "config", sessionId });
+            }
+            return usageRetryAfterMs(readings, windows);
+        },
+        async commit(cumulativeTokens, cumulativeCostMicroUsd, now) {
+            if (!governsCost) {
+                const delta = cumulativeTokens - chargedTokens;
+                if (delta <= 0)
+                    return;
+                await store.charge(key, delta, now, windows);
+                chargedTokens = cumulativeTokens;
+                return;
+            }
+            if (cumulativeCostMicroUsd === undefined) {
+                const tokenDelta = cumulativeTokens - chargedTokens;
+                if (tokenDelta > 0 || !recordedUnpricedGap) {
+                    await store.charge(key, Math.max(0, tokenDelta), now, windows, null);
+                    chargedTokens = Math.max(chargedTokens, cumulativeTokens);
+                    recordedUnpricedGap = true;
+                }
+                const e = new Error("a deployment usage window declares maxCostUsd, but this run's spend has NO cost figure (RB-368 unpriced: a model served without a RunnerDeps.pricing entry or a Model.cost declaration). Refused rather than charged a fabricated 0 — the money ceiling would have silently stopped applying. Price every model this run can reach, or drop maxCostUsd from the window.");
+                e.code = "config.usage_window_unpriced";
+                throw e;
+            }
+            const tokenDelta = cumulativeTokens - chargedTokens;
+            const costDelta = cumulativeCostMicroUsd - chargedCostMicroUsd;
+            if (tokenDelta <= 0 && costDelta <= 0)
+                return;
+            await store.charge(key, Math.max(0, tokenDelta), now, windows, Math.max(0, costDelta));
+            chargedTokens = cumulativeTokens;
+            chargedCostMicroUsd = cumulativeCostMicroUsd;
+        },
+    };
+}
+const ungatedWarnedShapes = new WeakMap();
+function announceDurableGateUnavailable(args) {
+    if (!args.forceDurableGate || args.storeWired)
+        return;
+    const cause = args.taskStoreNull ? "task_store_null" : "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"}, ` +
+            `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."}`,
+        detail: {
+            sessionId: args.sessionId,
+            runId: args.runId,
+            ...(args.principal ? { principal: args.principal } : {}),
+            cause,
+            liveApprover: args.liveApprover,
+            liveQuestionFace,
+        },
+    });
+}
+export function prepareWiringManifest(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, suspendRef, reviewRef, frozenOnAsk, liveInheritedGate, delegation } = input;
+    const onAsk = spec.onAsk ?? deps.onAsk;
+    const handWriteTools = handsEnabled && spec.handsReadOnly !== true
+        ? Object.keys(HAND_TOOL_EFFECTS).filter((name) => {
+            const eff = HAND_TOOL_EFFECTS[name];
+            return eff === "write" || eff === "idempotent";
+        })
+        : [];
+    const hasEffectAwareGate = Boolean(policyLayers.length > 0 || (hooks?.preToolUse !== undefined && !preToolUseObservational));
+    const destructiveMcpUngated = mcp.tools.some((t) => !irreversibleTools.has(t.name) && !egressTools.has(t.name) && (toolEffects.get(t.name) ?? "write") !== "read");
+    const firstPartyWriteUngated = (spec.tools ?? [])
+        .map((t) => t.name)
+        .filter((name) => !irreversibleTools.has(name) && !egressTools.has(name) && toolEffects.get(name) === "write");
+    if (!hasEffectAwareGate && (handWriteTools.length > 0 || destructiveMcpUngated || firstPartyWriteUngated.length > 0)) {
+        const what = [
+            handWriteTools.length > 0 ? `hand tools [${handWriteTools.join(", ")}]` : undefined,
+            destructiveMcpUngated ? "MCP write tools" : undefined,
+            firstPartyWriteUngated.length > 0 ? `write tools [${firstPartyWriteUngated.join(", ")}]` : undefined,
+        ]
+            .filter(Boolean)
+            .join(" + ");
+        if (!ungatedWarnedShapes.get(deps)?.has(what)) {
+            let shapes = ungatedWarnedShapes.get(deps);
+            if (!shapes) {
+                shapes = new Set();
+                ungatedWarnedShapes.set(deps, shapes);
+            }
+            shapes.add(what);
+            deps.onError?.(new Error(`write-capable ${what} are present but UNGATED — wire an effect-aware tool policy (or a PreToolUse hook). ` +
+                `bash/MCP irreversible actions are otherwise unadjudicated; the deployment sandbox/egress boundary is the only protection (design/77 §4, design/53 §2.H). ` +
+                `(This warning fires once per deployment per tool-set shape.)`), { phase: "config", sessionId });
+        }
+    }
+    const preToolContexts = new Map();
+    const blockedToolCalls = new Set();
+    const approvalSettlement = new Map();
+    const humanBareRejections = new Set();
+    const batchHaltRef = {};
+    const blockedTracked = Boolean(hooks?.postToolUse || hooks?.preToolUse || hooks?.postToolUseFailure || hooks?.postToolBatch);
+    const restoreSurfaceGap = ownedEnv !== undefined && isRemoteExecutionEnv(ownedEnv) && ownedEnv.capabilities.suspendable ? missingRestoreSurface(ownedEnv) : [];
+    const incompleteSuspendAdapter = restoreSurfaceGap.length > 0 ? restoreSurfaceGap : undefined;
+    const durableSuspendInfraReady = resolveCheckpointStore(spec, deps) !== undefined &&
+        !(offloadStore !== undefined && isVolatileOffloadStore(offloadStore)) &&
+        (ownedEnv === undefined || isRemoteExecutionEnv(ownedEnv)) &&
+        incompleteSuspendAdapter === undefined;
+    const resourceSuspendEligible = spec.resourceSuspend !== undefined && durableSuspendInfraReady;
+    if (spec.resourceSuspend !== undefined && !resourceSuspendEligible) {
+        const why = resolveCheckpointStore(spec, deps) === undefined
+            ? "no CheckpointStore is wired"
+            : offloadStore !== undefined && isVolatileOffloadStore(offloadStore)
+                ? "tool-result offload uses the in-memory store (a resume needs durable results)"
+                : incompleteSuspendAdapter !== undefined
+                    ? `the per-task execution env declares capabilities.suspendable but its adapter does not implement ${incompleteSuspendAdapter.join(" or ")} (a snapshot nothing can restore is worse than no snapshot)`
+                    : "the per-task execution env is not a RemoteExecutionEnv (it would be destroyed on suspend)";
+        onceLedger.onError(new Error(`resourceSuspend is set but INACTIVE: ${why}; resource limits will hard-fail, not suspend`), {
+            phase: "config",
+            sessionId,
+        });
+    }
+    const usageGovernance = buildUsageGovernance(usageWindows, deps, spec.principal, sessionId);
+    const platformSuspendArmed = durableSuspendInfraReady && (envLifetimeSuspendAt !== undefined || usageGovernance !== undefined);
+    const durableApproval = spec.durableApproval ??
+        (runtimeCaps?.forceDurableGate ? { scope: spec.principal || DEFAULT_IRREVERSIBLE_SCOPE } : undefined);
+    const wiringQuestionSeam = resolveQuestionSeam(spec, deps);
+    const wiringQuestionStripped = internals?.questionFaceStripped === true;
+    const wiringAskSeam = resolveAskSeamForm(spec, deps);
+    const wiringManifest = deriveWiringManifest({
+        half: "effective",
+        leg: resume !== undefined ? "resume" : internals?.isDelegatedChild === true ? "child" : "root",
+        askForm: wiringAskSeam.form,
+        ...(wiringAskSeam.provenance !== undefined ? { askProvenance: wiringAskSeam.provenance } : {}),
+        questionWired: wiringQuestionSeam.wired,
+        ...(wiringQuestionSeam.provenance !== undefined ? { questionProvenance: wiringQuestionSeam.provenance } : {}),
+        ...(wiringQuestionStripped ? { questionStrippedByEngine: true } : {}),
+        ...(resolvedInteractionPosture !== undefined ? { interactionPosture: resolvedInteractionPosture } : {}),
+        ...(spec.interactiveTools === true && !wiringQuestionSeam.wired && !durableQuestionFace && !wiringQuestionStripped
+            ? { interactiveToolsWithoutDeliveryFace: true }
+            : {}),
+        elicitSeamWired: resolveElicitSeam(deps),
+        elicitServersOptedIn: countElicitOptIns(spec),
+        parkCapable: checkpointStore !== undefined,
+        parkDurableApprovalOptIn: spec.durableApproval !== undefined,
+        parkForceDurableGate: runtimeCaps?.forceDurableGate === true,
+        parkSafetyVocabularyArmed: irreversibleTools.size > 0 || egressTools.size > 0,
+        ...(checkpointStore !== undefined ? { checkpointDurability: resolveDeclaredDurability(checkpointStore, "checkpointStore") } : {}),
+        sessionDurability: resolveDeclaredDurability(sessions, "sessionStore"),
+        backgroundAgentStoreWired: deps.backgroundAgentStore !== undefined,
+        subagentTranscriptTier: resolveSubagentTranscriptTier(deps.backgroundAgentStore !== undefined, sessions),
+        permissionRuleStoreWired: deps.permissionRuleStore?.partitions.durable === true,
+        permissionRuleSyncWired: deps.permissionRuleSyncWired === true,
+        permissionRuleOrgGoverned: deps.permissionRuleStore?.partitions.org === true,
+        hostChildEventSinkWired: deps.onBackgroundChildEvent !== undefined,
+        lockedConfigWired: deps.lockedConfig !== undefined,
+        complianceWired: deps.compliancePostureResolver !== undefined,
+        memoryAdmissionWired: deps.memoryScopeAdmission !== undefined,
+        retentionPolicyWired: deps.retentionPolicy !== undefined,
+        ...(modelGateManifest !== undefined ? { modelGate: modelGateManifest } : {}),
+        autoMode: { armed: autoModeArmReason === "armed", reason: autoModeArmReason },
+        mcp: mcpManifestEntries(lockedPreflight.mcp, mcp.statuses),
+    });
+    peerLaneRefs.askEffective = wiringManifest.ask.effective;
+    if (peerLaneActive && internals?.onTaskNotification !== undefined) {
+        bindPeerLaneDrain(harness, {
+            deps,
+            sessionId,
+            runId,
+            scope: taskScope,
+            inject: internals.onTaskNotification,
+            ownTokens: () => internals?.peerSelfRef?.current.ownTokens ?? [],
+            refs: peerLaneRefs,
+            selfName: () => internals?.explicitAgentName,
+            parked: () => suspendRef.token !== undefined || reviewRef.token !== undefined,
+        });
+    }
+    const parkLaneArmed = wiringManifest.parkLane.effective === true;
+    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, taskStoreNull: spec.checkpointStore === null, liveApprover: isLiveApproverSeat(frozenOnAsk), liveQuestionFace: liveQuestionFace !== undefined, parentConstraints: liveInheritedGate?.parentConstraints, sessionId, runId, principal: spec.principal });
+    const hookIdentity = mintHookInvocationIdentity({
+        sessionId,
+        taskId: hostTaskId,
+        legKind: wiringManifest.leg.kind,
+        isDelegatedChild: delegation.isDelegatedChild,
+        ...(internals?.insideFork === true ? { insideFork: true } : {}),
+        ...(internals?.agentName !== undefined ? { agentName: internals.agentName } : {}),
+        ...(internals?.parentToolCallId !== undefined ? { parentToolCallId: internals.parentToolCallId } : {}),
+    });
+    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, gateMachineryActive, hookIdentity, hookEnvFace };
+}