@sema-agent/core 7.5.0 → 7.5.2

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

@@ -0,0 +1,230 @@
+import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens } from "../../internal/harness.js";
+import { clearStaleToolResults, createClearedProjectionLedger, dropEmptyFailureAssistants, editBudget, replayClearedProjection, resolveTriggerWindow } from "../context-edit.js";
+import { dropOrphanToolResults, guardBudget, insertTrimNotice, trimToBudget } from "../context-guard.js";
+import { AGGREGATE_MEDIA_BUDGET_BYTES, capAggregateMediaBytes } from "../media-byte-cap.js";
+import { capAggregateToolResults } from "../tool-result-budget.js";
+import { createOffloadPersist } from "../tool-result-store.js";
+import { emitTrace } from "../trace.js";
+import { deliverEngineNotice } from "../types.js";
+import { applyGitFrameGuard } from "./git-status-frame.js";
+export function prepareContextLane(input) {
+    const { model, deps, sessionId, runId, hostTaskId, offloadStore, microCompactKnob, harness, batchHaltRef, gitStatusRef, requestLossyRef, trimPressureRef } = input;
+    const editAt = editBudget(model);
+    const guardAt = guardBudget(model);
+    const microCompact = buildMicroCompactState(deps, model, sessionId, runId, offloadStore, microCompactKnob);
+    const charsPerToken = model.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    harness.on("context", async ({ messages, recheck, signal }) => {
+        batchHaltRef.current = undefined;
+        const pendingProjectionObservations = [];
+        try {
+            const healed = dropEmptyFailureAssistants(messages);
+            const replay = replayClearedProjection(healed, microCompact.ledger);
+            const replayed = replay.messages;
+            const capped = await capAggregateToolResults(replayed, {
+                store: offloadStore,
+                sessionId,
+                onCapped: (info) => pendingProjectionObservations.push(() => emitTrace(deps.tracer, () => ({
+                    kind: "tool_result.capped",
+                    version: 1,
+                    taskId: hostTaskId,
+                    ...(info.tool !== undefined ? { tool: info.tool } : {}),
+                    sizeChars: info.sizeChars,
+                    storeFallback: info.storeFallback,
+                    ts: Date.now(),
+                }))),
+            });
+            const mediaCapped = capAggregateMediaBytes(capped, {
+                limitBytes: deps.mediaByteCapBytes ?? AGGREGATE_MEDIA_BUDGET_BYTES,
+                onStripped: (info) => {
+                    const onMediaStripped = deps.onMediaStripped;
+                    if (onMediaStripped !== undefined)
+                        pendingProjectionObservations.push(() => onMediaStripped(info));
+                },
+            });
+            let ccPass;
+            const edited = microCompact.machine === "off" ? mediaCapped : clearStaleToolResults(mediaCapped, {
+                budgetTokens: editAt,
+                machine: microCompact.machine,
+                ...(microCompact.machine === "cc" || microCompact.clearOnRejection ? { recognizeCcMarkers: true } : {}),
+                ...(microCompact.machine === "cc"
+                    ? {
+                        clearSource: replayed,
+                        onCleared: (pass) => { ccPass = pass; },
+                    }
+                    : {}),
+                anchoredTotalTokens: estimateContextTokens(mediaCapped, charsPerToken).tokens,
+                charsPerToken,
+                ...(offloadStore
+                    ? {
+                        offload: {
+                            persist: createOffloadPersist(offloadStore, sessionId, deps.onNotice),
+                        },
+                    }
+                    : {}),
+            });
+            if (ccPass !== undefined) {
+                recordFrontierClears({ pass: ccPass, index: replay.index, edited, ledger: microCompact.ledger, tracer: deps.tracer, taskId: hostTaskId, trigger: "frontier" });
+            }
+            const chain = await runGuardChain({
+                edited, replayed, index: replay.index, microCompact, guardAt, charsPerToken, offloadStore,
+                sessionId, taskId: hostTaskId, deps, trimPressureRef, recheck, signal,
+                pendingProjectionObservations,
+            });
+            if ("earlyReturn" in chain) {
+                return chain.earlyReturn;
+            }
+            const { working, trimDroppedMessages } = chain;
+            let trimmed = chain.trimmed;
+            trimmed = applyGitFrameGuard({
+                before: working,
+                trimmed,
+                budgetTokens: guardAt,
+                ref: gitStatusRef,
+                charsPerToken,
+                onDegrade: (message) => {
+                    try {
+                        deps.onError?.(new Error(message), { phase: "degraded", sessionId, classification: "env-git-snapshot" });
+                    }
+                    catch {
+                    }
+                },
+            });
+            const swept = dropOrphanToolResults(trimmed);
+            if (swept.dropped.length > 0) {
+                try {
+                    deps.onError?.(new Error(`context belt: dropped ${swept.dropped.length} orphan toolResult(s) whose tool-call assistant was not in the request view — ` +
+                        swept.dropped
+                            .map((d) => `toolCallId=${d.toolCallId} at index ${d.index} (prev=${d.prevRole}, next=${d.nextRole})`)
+                            .join("; ")), { phase: "hook", sessionId });
+                }
+                catch {
+                }
+            }
+            requestLossyRef.current =
+                replayed !== healed ||
+                    capped !== replayed ||
+                    mediaCapped !== capped ||
+                    edited !== mediaCapped ||
+                    working !== edited ||
+                    trimDroppedMessages ||
+                    swept.dropped.length > 0 ||
+                    gitStatusRef.overBudgetShrunk === true;
+            microCompact.projectionRef.current = { messages: swept.messages, keyOf: replay.index.keyOf };
+            return { messages: swept.messages };
+        }
+        finally {
+            flushProjectionObservations(pendingProjectionObservations);
+        }
+    });
+    return { microCompact, charsPerToken };
+}
+function buildMicroCompactState(deps, model, sessionId, runId, offloadStore, knob) {
+    const triggerWindow = resolveTriggerWindow(model);
+    if (triggerWindow.clamped) {
+        deliverEngineNotice(deps.onNotice, {
+            code: "config.autocompact_window_clamped",
+            message: `model "${model.id}" declares autoCompactTokens=${triggerWindow.declaredAutoCompactTokens} ABOVE its physical window ` +
+                `${triggerWindow.physicalWindow}; the autocompact window only ever LOWERS the trigger-side geometry, so the value was ` +
+                `clamped to the physical window — fix the model config (declare a value at or below the physical window, or omit it)`,
+            detail: {
+                modelId: model.id,
+                declaredAutoCompactTokens: triggerWindow.declaredAutoCompactTokens,
+                physicalWindow: triggerWindow.physicalWindow,
+                sessionId,
+                runId,
+            },
+        });
+    }
+    return {
+        machine: knob.machine,
+        clearOnRejection: knob.clearOnRejection,
+        ledger: createClearedProjectionLedger(),
+        projectionRef: {},
+        inTurnCompactionRef: {},
+        ...(offloadStore ? { offloadPersist: createOffloadPersist(offloadStore, sessionId, deps.onNotice) } : {}),
+    };
+}
+function recordFrontierClears(args) {
+    for (const { index } of args.pass.clears) {
+        const at = args.index.keyAt(index);
+        const clearedMsg = args.edited[index];
+        const markerText = clearedMsg.content?.[0]?.text;
+        if (at !== undefined && typeof markerText === "string") {
+            args.ledger.entries.set(at.key, { marker: markerText, groupCount: at.groupCount, fp: at.fp });
+        }
+    }
+    emitTrace(args.tracer, () => ({
+        kind: "context.mc_clear",
+        version: 1,
+        taskId: args.taskId,
+        clearedCount: args.pass.clears.length,
+        tokensSavedEstimate: args.pass.tokensSavedEstimate,
+        trigger: args.trigger,
+        ts: Date.now(),
+    }));
+}
+function flushProjectionObservations(pending) {
+    for (const fire of pending.splice(0)) {
+        try {
+            fire();
+        }
+        catch {
+        }
+    }
+}
+export async function runGuardChain(args) {
+    const { edited, microCompact, guardAt, charsPerToken, deps, taskId } = args;
+    const applyGuardTrim = (view, anchoredTotal) => {
+        let trimmed = trimToBudget(view, guardAt, anchoredTotal, charsPerToken);
+        const dropped = trimmed.length < view.length;
+        if (dropped) {
+            args.trimPressureRef.droppedMessages = true;
+            const droppedCount = view.length - trimmed.length;
+            trimmed = insertTrimNotice(trimmed);
+            emitTrace(deps.tracer, () => ({
+                kind: "context.trim",
+                version: 1,
+                taskId,
+                dropped: droppedCount,
+                ts: Date.now(),
+            }));
+        }
+        return { trimmed, dropped };
+    };
+    let working = edited;
+    let anchoredWorking = estimateContextTokens(working, charsPerToken).tokens;
+    if (microCompact.machine === "legacy") {
+        const t = applyGuardTrim(working, anchoredWorking);
+        return { working, trimmed: t.trimmed, trimDroppedMessages: t.dropped };
+    }
+    if (microCompact.machine === "off" && anchoredWorking > guardAt) {
+        let blockingPass;
+        const blockingEdited = clearStaleToolResults(working, {
+            budgetTokens: guardAt,
+            machine: "cc",
+            clearSource: args.replayed,
+            onCleared: (pass) => { blockingPass = pass; },
+            anchoredTotalTokens: anchoredWorking,
+            charsPerToken,
+            ...(args.offloadStore ? { offload: { persist: createOffloadPersist(args.offloadStore, args.sessionId, deps.onNotice) } } : {}),
+        });
+        if (blockingPass !== undefined) {
+            recordFrontierClears({ pass: blockingPass, index: args.index, edited: blockingEdited, ledger: microCompact.ledger, tracer: deps.tracer, taskId, trigger: "blocking" });
+            working = blockingEdited;
+            anchoredWorking = estimateContextTokens(working, charsPerToken).tokens;
+        }
+    }
+    if (anchoredWorking > guardAt && args.recheck !== true) {
+        const compacted = (await microCompact.inTurnCompactionRef.current?.(args.signal, anchoredWorking)) === true;
+        if (compacted) {
+            args.pendingProjectionObservations.length = 0;
+            return { earlyReturn: { messages: working, adoptSessionRebuild: true } };
+        }
+        if (args.signal?.aborted === true) {
+            args.pendingProjectionObservations.length = 0;
+            return { working, trimmed: working, trimDroppedMessages: false };
+        }
+    }
+    const t = applyGuardTrim(working, anchoredWorking);
+    return { working, trimmed: t.trimmed, trimDroppedMessages: t.dropped };
+}

package/dist/core/runner/prepare-defer-classify.d.ts

@@ -0,0 +1,86 @@
+/**
+ * design/390 M11 — prepareTask's TOOL-FACE FOLD + DEFERRED CLASSIFICATION phase: the exclusion valve's
+ * true unmount (in place, on the shared mount array), the full-shell anti-drift invariant, the classic-
+ * profile description swap, `classifyDeferredOverFace` (the one classifier both counterfactual passes
+ * run), the built-in memory pairs' support-name pre-check (sole-cause counterfactual, whole-group
+ * retraction, the engine pair's recall paragraph stripped back out of the memory block) and the final
+ * `deferred` set. The body is the driver's stretch moved verbatim (one exception, named below); the
+ * interface is the dependency list it had implicitly (design/238 R-1).
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between
+ * the git-status probe before it and the content-origin wrap after it (design/390 §1.5 S1: a stretch
+ * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
+ *
+ * The one non-move: the stretch used to write `sharedMemoryPairMounted = false` /
+ * `memoryEnginePairMounted = false` on the retraction arm. Nothing reads either flag after this stretch
+ * (the driver's next reader was this stretch's own pair derivation, which runs first), so the two dead
+ * writes are not carried into the Result — the flags arrive as borrowed-readonly inputs.
+ *
+ * Throws pass through unchanged: `internal.full_shell_reachable_mismatch` (an engine invariant, never a
+ * configuration error). The reserved-name refusal for a standing ToolSearch collision is NOT here — it
+ * belongs to the disclosure mount downstream, which reads the `deferred` set this phase returns.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { Model } from "../../internal/llm.js";
+import type { MaterializedA2a } from "../a2a.js";
+import type { MaterializedMcp } from "../mcp.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { AnnounceOnceSink, ToolFaceSnapshot } from "./contracts.js";
+export interface PrepareDeferClassifyInput {
+    /** borrowed-readonly — the REBOUND spec (`spec′`); only `tools` is read (the caller roster the
+     *  classifier judges: names for the full-schema filter, specs for the `defer` declarations). */
+    spec: Pick<TaskSpec, "tools">;
+    /** borrowed-readonly — deployment deps; only `deferMode` is read (the classifier's mode knob). */
+    deps: Pick<RunnerDeps, "deferMode">;
+    /** borrowed-mutable — the shared mount array (later refs alias it; in-place contract, never
+     *  re-created). Mutated here, in order: `splice` of every excluded name; element REPLACEMENT with a
+     *  shallow copy for the classic-profile description swap (the caller's ToolSpec object is never
+     *  mutated); `splice` of a retracted memory group. After this phase: the content-origin wrap
+     *  (element replacement with the wrapped object), the disclosure mount, the MCP refresh re-splice. */
+    tools: AgentTool[];
+    /** borrowed-readonly — the frozen task-start tool face: `exclude` (the valve), `defer` (operator
+     *  defers, exact wire names), `alwaysLoad` (the inline pins). */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude" | "defer" | "alwaysLoad">;
+    /** borrowed-readonly — whether a real execution env is mounted (the full-shell invariant runs only
+     *  where a shell could be on the roster). */
+    handsEnabled: boolean;
+    /** borrowed-readonly — the spec-time precomputation the invariant checks the post-exclusion roster
+     *  against (design/199 D-6): a mismatch is an engine bug, thrown. */
+    fullShellReachable: boolean;
+    /** borrowed-readonly — the resolved prompt profile (`classic` swaps in `descriptionClassic`). */
+    promptProfile: "simple" | "classic";
+    /** borrowed-readonly — the resolved model (the classifier's constant-defer arm reads its shape). */
+    model: Model;
+    /** borrowed-readonly — the materialized MCP roster; only `tools` is read (protocol names for the
+     *  remote-roster arm; `mcpAlwaysLoad` self-declarations, losing to an explicit operator defer). */
+    mcp: Pick<MaterializedMcp, "tools">;
+    /** borrowed-readonly — the materialized A2A roster; only `tools` is read (protocol names). */
+    a2a: Pick<MaterializedA2a, "tools">;
+    /** borrowed-readonly — whether the shared-memory pair mounted (project-context phase). */
+    sharedMemoryPairMounted: boolean;
+    /** borrowed-readonly — whether the engine-memory pair mounted (project-context phase). */
+    memoryEnginePairMounted: boolean;
+    /** borrowed-readonly — the memory block as the project-context phase left it. The engine pair's
+     *  retraction strips the recall paragraph from it and the stripped value returns as
+     *  {@link PrepareDeferClassifyResult.memoryBlock}; the input value itself is never mutated. */
+    memoryBlock: string | undefined;
+    /** borrowed-readonly — the exact recall-discipline segment the memory phase composed (the strip
+     *  removes THIS string, never a re-composition). */
+    memoryRecallSegment: string | undefined;
+    /** borrowed-readonly — the once-per-session ledger's deduplicated operator sink (a retraction is a
+     *  session-level fact, announced once). */
+    onceLedger: AnnounceOnceSink;
+    /** borrowed-readonly — the acquired session's id (operator-line context). */
+    sessionId: string;
+}
+export interface PrepareDeferClassifyResult {
+    /** owned — the FINAL deferred set over the post-exclusion, post-retraction roster: the disclosure
+     *  mount, the deferred registry and `Prepared.deferredToolNames` all read this one set (there is
+     *  deliberately no second classification). Empty ⇒ nothing is deferred. */
+    deferred: Set<string>;
+    /** owned — the memory block after the engine pair's retraction strip (unchanged when no retraction
+     *  ran). The driver binds it under the name the prompt assembly reads. */
+    memoryBlock: string | undefined;
+}
+/** The M11 phase body — prepareTask's tool-face fold + deferred classification, verbatim (module header). */
+export declare function prepareDeferClassify(input: PrepareDeferClassifyInput): PrepareDeferClassifyResult;

package/dist/core/runner/prepare-defer-classify.js

@@ -0,0 +1,107 @@
+import { getToolContract } from "../../prompt-assembly/tool-catalog.js";
+import { FULL_SHELL_CONTRACT_ID } from "../../tools/fs/index.js";
+import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
+import { MEMORY_ENGINE_TOOL_NAMES } from "../memory-engine/tools.js";
+import { SHARED_MEMORY_TOOL_NAMES } from "../shared-memory/types.js";
+import { TOOL_SEARCH_NAME, classifyDeferred } from "./tool-disclosure.js";
+function explicitlyDeferredMemoryTrio(mounted, roster, deferNames) {
+    return mounted ? MEMORY_ENGINE_TOOL_NAMES.filter((n) => roster.some((t) => t.name === n) && (deferNames ?? []).includes(n)) : [];
+}
+function memoryGroupRetractionSet(builtinDeferPairNames, engineTrioInPlay) {
+    return new Set([...builtinDeferPairNames, ...(engineTrioInPlay ? MEMORY_ENGINE_TOOL_NAMES : [])]);
+}
+export function prepareDeferClassify(input) {
+    const { spec, deps, tools, toolFaceSnapshot, handsEnabled, fullShellReachable, promptProfile, model, mcp, a2a, sharedMemoryPairMounted, memoryEnginePairMounted, memoryRecallSegment, onceLedger, sessionId } = input;
+    let memoryBlock = input.memoryBlock;
+    if (toolFaceSnapshot.exclude !== undefined && toolFaceSnapshot.exclude.length > 0) {
+        const excluded = new Set(toolFaceSnapshot.exclude);
+        for (let i = tools.length - 1; i >= 0; i--)
+            if (excluded.has(tools[i].name))
+                tools.splice(i, 1);
+    }
+    if (handsEnabled) {
+        const fullShellOnRoster = tools.some((t) => t.name === "Bash" && getToolContract(t, "core").contractId === FULL_SHELL_CONTRACT_ID);
+        if (fullShellOnRoster !== fullShellReachable) {
+            const e = new Error(`internal invariant: fullShellReachable=${String(fullShellReachable)} but the post-exclusion roster ` +
+                `${fullShellOnRoster ? "carries" : "does not carry"} the full shell (${FULL_SHELL_CONTRACT_ID}). ` +
+                `A new roster-affecting mechanism was added without updating the predicate.`);
+            e.code = "internal.full_shell_reachable_mismatch";
+            throw e;
+        }
+    }
+    if (promptProfile === "classic") {
+        for (let i = 0; i < tools.length; i++) {
+            const t = tools[i];
+            if (t.descriptionClassic !== undefined)
+                tools[i] = { ...t, description: t.descriptionClassic };
+        }
+    }
+    const userToolNames = (spec.tools ?? []).map((t) => t.name);
+    const protocolToolNames = [...mcp.tools.map((t) => t.name), ...a2a.tools.map((t) => t.name)];
+    const mcpAlwaysLoadNames = mcp.tools
+        .filter((t) => t.mcpAlwaysLoad === true && !(toolFaceSnapshot.defer ?? []).includes(t.name))
+        .map((t) => t.name);
+    const classifyDeferredOverFace = (face, builtinDeferNames) => {
+        const deferredSet = classifyDeferred({
+            specs: spec.tools ?? [],
+            protocolToolNames,
+            fullTools: face.filter((t) => userToolNames.includes(t.name) || protocolToolNames.includes(t.name)),
+            deferMode: deps.deferMode,
+            model,
+            deferNames: [...(toolFaceSnapshot.defer ?? []), ...builtinDeferNames].filter((n) => face.some((t) => t.name === n)),
+            alwaysLoadNames: [
+                ASK_USER_QUESTION_TOOL_NAME,
+                ...(toolFaceSnapshot.alwaysLoad ?? []),
+                ...mcpAlwaysLoadNames,
+            ],
+        });
+        for (const n of [...deferredSet]) {
+            if (!face.some((t) => t.name === n))
+                deferredSet.delete(n);
+        }
+        return deferredSet;
+    };
+    const sharedMemoryPair = sharedMemoryPairMounted ? SHARED_MEMORY_TOOL_NAMES.filter((n) => tools.some((t) => t.name === n)) : [];
+    const memoryEnginePair = explicitlyDeferredMemoryTrio(memoryEnginePairMounted, tools, toolFaceSnapshot.defer);
+    const builtinDeferPairNames = [...sharedMemoryPair, ...memoryEnginePair];
+    let deferred;
+    if (builtinDeferPairNames.length > 0) {
+        const withoutPairs = tools.filter((t) => !builtinDeferPairNames.some((n) => n === t.name));
+        const d1 = classifyDeferredOverFace(tools, builtinDeferPairNames);
+        const d0 = classifyDeferredOverFace(withoutPairs, []);
+        const soleCause = d0.size === 0 && d1.size > 0;
+        const supportNameTaken = tools.some((t) => t.name === TOOL_SEARCH_NAME || (t.aliases ?? []).includes(TOOL_SEARCH_NAME));
+        if (soleCause && supportNameTaken) {
+            const retractNames = memoryGroupRetractionSet(builtinDeferPairNames, memoryEnginePair.length > 0);
+            for (let i = tools.length - 1; i >= 0; i--) {
+                if (retractNames.has(tools[i].name))
+                    tools.splice(i, 1);
+            }
+            if (sharedMemoryPair.length > 0) {
+                onceLedger.onError(new Error(`Shared memory tools ${SHARED_MEMORY_TOOL_NAMES.join("/")} were NOT mounted: mounting them would inject ` +
+                    `the "${TOOL_SEARCH_NAME}" tool, whose name this task already declares — the pair mounts together or not at all.`), { phase: "config", sessionId, classification: "shared-memory-not-mounted" });
+            }
+            if (memoryEnginePair.length > 0) {
+                if (memoryBlock !== undefined && memoryRecallSegment !== undefined) {
+                    const segment = memoryRecallSegment;
+                    if (memoryBlock === segment)
+                        memoryBlock = undefined;
+                    else if (memoryBlock.includes(`\n\n${segment}`))
+                        memoryBlock = memoryBlock.replace(`\n\n${segment}`, "");
+                    else if (memoryBlock.startsWith(`${segment}\n\n`))
+                        memoryBlock = memoryBlock.slice(segment.length + 2);
+                }
+                onceLedger.onError(new Error(`Memory tools ${MEMORY_ENGINE_TOOL_NAMES.join("/")} were NOT mounted: mounting them would inject ` +
+                    `the "${TOOL_SEARCH_NAME}" tool, whose name this task already declares — these tools mount together or not at all.`), { phase: "config", sessionId, classification: "memory-tools-not-mounted" });
+            }
+            deferred = d0;
+        }
+        else {
+            deferred = d1;
+        }
+    }
+    else {
+        deferred = classifyDeferredOverFace(tools, []);
+    }
+    return { deferred, memoryBlock };
+}

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

@@ -0,0 +1,104 @@
+import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
+import { createSendMessageTool } from "../../agents/send-message-tool.js";
+import { type PeerLaneRefs } from "../../agents/peer-session-drain.js";
+import type { SubagentRetainLedger } from "../../agents/retain-ledger.js";
+import { type WorktreeSessionRef } from "../../tools/worktree.js";
+import type { CwdRef } from "../../tools/fs/index.js";
+import { type ToolResultStore } from "../tool-result-store.js";
+import type { RunnerDeps, TaskSpec, ToolEffect, ToolExecuteContext } from "../types.js";
+import type { PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+/** The runner the SendMessage / AgentTranscript mounts accept — spelled as the factory's own option type so this phase
+ *  names no runner module of its own (the narrow `RunnerSelfSeat` contract is a design decision still open). */
+type DelegationMountRunner = Parameters<typeof createSendMessageTool>[0]["runner"];
+export interface PrepareDelegationSurfaceInput {
+    /** borrowed-readonly — the REBOUND spec. Read: `tools` (the shadow checks and the revival spawner's delegation-tool
+     *  lookup), `oneShot` (the read/kill faces' completion promises), `retainBackgroundProcesses` (the Monitor receipt),
+     *  `handsReadOnly` is NOT read here (the hands mount decided the surface). Never mutated. */
+    spec: Pick<TaskSpec, "tools" | "oneShot" | "retainBackgroundProcesses">;
+    /** borrowed-readonly — the deployment seats the mounts read: `workflowRunStore` / `backgroundAgentStore` / `mailboxStore` (the
+     *  read/kill faces and the tier-3 revival seams), `rosterStore`, `peerAdmission`, `peerDirectory`, `onNotice`,
+     *  `onBackgroundChildEvent`, `tracer`. */
+    deps: Pick<RunnerDeps, "workflowRunStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "peerAdmission" | "peerDirectory" | "onNotice" | "onBackgroundChildEvent" | "tracer">;
+    /** borrowed-readonly — the trusted spawn-side channel: `parentNotify` (the delegated-child door), the uplink / sibling /
+     *  identity seats the SendMessage mount forwards, `onTaskNotification`, `onSubagentSpawn`. Never mutated. */
+    internals: Pick<RunInternals, "parentNotify" | "parentPeerRef" | "parentRetainLedger" | "explicitAgentName" | "parentTaskId" | "parentSessionId" | "peerSelfRef" | "peerInboundChainRef" | "onTaskNotification" | "onSubagentSpawn"> | undefined;
+    /** borrowed-readonly — the resume leg, or undefined: `seed.activeWorktree` seeds the worktree session (checkpoint first). */
+    resume: Pick<PrepareResume, "seed"> | undefined;
+    /** borrowed-readonly — the acquired session id (the mounts' session axis). */
+    sessionId: string;
+    /** borrowed-readonly — the per-task identity (the mounts' owner axis). */
+    hostTaskId: string;
+    /** borrowed-readonly — the registry scope the mounts register in. */
+    taskScope: string;
+    /** borrowed-readonly — the SETTLED task root (the worktree tools' repoRoot). */
+    taskRootFinal: string;
+    /** borrowed-readonly — the run's resolved env the Monitor and worktree tools operate. */
+    executionEnv: ExecutionEnv;
+    /** borrowed-readonly — the trusted Runner self-reference the SendMessage / AgentTranscript mounts execute through; undefined
+     *  when prepareTask runs standalone (then neither mounts). */
+    runnerSelf: DelegationMountRunner | undefined;
+    /** borrowed-readonly — the background/workflow door's first half: the hands mount decided a real shell with write hands. */
+    backgroundTaskToolsActive: boolean;
+    /** borrowed-readonly — the door's second half: the Workflow tool is on the roster. */
+    workflowToolsActive: boolean;
+    /** borrowed-readonly — the peer lane's mount verdict for this leg. */
+    peerLaneActive: boolean;
+    /** borrowed-readonly — whether the BUILT-IN SendMessage is on this face (the ListAgents mount's second term). */
+    peerSendMessageBuiltIn: boolean;
+    /** borrowed-mutable — the lane's late-bound facts; the SendMessage mount hands the SAME object to its peer seats (identity is
+     *  the contract: the wiring station fills `askEffective` later). Not written here. */
+    peerLaneRefs: PeerLaneRefs;
+    /** borrowed-mutable — the run's shared roster (`Prepared.tools`, whose JSDoc carries the writer table). Writers here: the
+     *  eight mounts (TaskOutput, TaskStop, SendMessage, AgentTranscript, ListAgents, Monitor, the worktree pair, the offload
+     *  reader), every one a push. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the effect collection (`Prepared.toolEffects`). Writers here: TaskOutput → read, TaskStop / SendMessage
+     *  (built-in mount only) / Monitor / EnterWorktree / ExitWorktree → write. */
+    toolEffects: Map<string, ToolEffect>;
+    /** borrowed-mutable — the explicit-negative axis declarations. Writer here: the built-in SendMessage mount's `egress: false`
+     *  (report-face only). */
+    axisExplicitNegatives: Map<string, {
+        irreversible?: false;
+        egress?: false;
+    }>;
+    /** borrowed-mutable — the env-hand tool-name set the read posture reads. Writers here: Monitor and the two worktree tools
+     *  (membership minted at the mount). */
+    envHandToolNames: Set<string>;
+    /** borrowed-readonly — the frozen tool-face snapshot (`exclude` feeds the ListAgents mount predicate). */
+    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude">;
+    /** borrowed-readonly — the large-result wrapper for first-party mounts. */
+    firstPartyOffload: (tool: AgentTool) => AgentTool;
+    /** borrowed-readonly — the run's offload store, or undefined when offload is disabled (then no reader mounts and the
+     *  read/kill faces spill nowhere). */
+    offloadStore: ToolResultStore | undefined;
+    /** borrowed-readonly — the retain ledger the SendMessage mount continues children through (absent ⇒ honest not-retained). */
+    subagentRetain: SubagentRetainLedger | undefined;
+    /** borrowed-readonly — the caller-tool ctx enrichment: the revival spawner re-enters the delegation tool through it, and
+     *  the SendMessage / AgentTranscript mounts activate their ctx-first arms with it. */
+    enrichSpecToolCtx: (ctx: ToolExecuteContext) => ToolExecuteContext;
+    /** borrowed-mutable — the hands mount's tracked-cwd seat: present ⇔ real shell + write hands; the worktree pair's mount
+     *  predicate. Not written by this phase, but the tools it mounts over it ARE its writers (design/238 R-3): EnterWorktree and
+     *  ExitWorktree assign `current` at run time (the hands band's shared cwd then points at the worktree, and back); the
+     *  Monitor only reads it. The cell must stay the hands mount's own object — a copy would strand those writes. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the workspace-state snapshot (the worktree seed's continuation rung), or undefined. */
+    wsSnapshot: Pick<WorkspaceState, "activeWorktree"> | undefined;
+    /** borrowed-readonly — the rebase of a snapshot path onto this leg's root. */
+    rebaseWsPath: (p: string) => string;
+    /** borrowed-readonly — the rebase of a checkpoint path onto this leg's root. */
+    rebaseRestoredPath: (p: string) => string;
+    /** borrowed-mutable — the workspace-state settle seat; the worktree mount stamps `restoredWorktreeDir` on it once. */
+    workspaceStateSettle: {
+        restoredWorktreeDir?: string;
+    } | undefined;
+}
+export interface PrepareDelegationSurfaceResult {
+    /** owned — whether the background/workflow door is open (TaskOutput / TaskStop / AgentTranscript ride it). */
+    delegationSurfaceActive: boolean;
+    /** borrowed-mutable — the EnterWorktree session's shared serializable state (`Prepared.worktreeSessionRef`), minted iff the
+     *  worktree pair mounted. Writers: the worktree tools at run time (Enter/Exit); the suspend serializer reads it. */
+    worktreeSessionRef: WorktreeSessionRef | undefined;
+}
+/** The M6 phase body — prepareTask's delegation-surface stretch, verbatim (see the module header). */
+export declare function prepareDelegationSurface(input: PrepareDelegationSurfaceInput): PrepareDelegationSurfaceResult;
+export {};