@sema-agent/core 7.5.0 → 7.5.2

package/dist/core/runner/prepare-file-history.js

@@ -0,0 +1,383 @@
+import { NodeExecutionEnv } from "../../engine/execution-env/node-execution-env.js";
+import { isRemoteExecutionEnv } from "../remote-env.js";
+import { resolveTrackKey } from "../file-history-store.js";
+export async function prepareFileHistory(input) {
+    const { deps, spec, internals, executionEnv, taskRootFinal, handsEnabled, sessionId, session, resumeAtBeforeParentId, abortController } = input;
+    const rewindNotes = [];
+    const onTrackFailure = deps.onTrackFailure === undefined ? "refuse" : deps.onTrackFailure;
+    if (onTrackFailure !== "refuse" && onTrackFailure !== "proceed-unprotected") {
+        const e = new Error(`RunnerDeps.onTrackFailure must be "refuse" or "proceed-unprotected"; got ${JSON.stringify(deps.onTrackFailure)} — refusing prepare rather than silently defaulting a first-touch-failure policy.`);
+        e.code = "config.invalid_on_track_failure";
+        throw e;
+    }
+    const fileHistoryStore = resolveWiredFileHistoryStore(deps.fileHistoryStore);
+    const legacyRewindFiles = spec.rewindFiles;
+    if (legacyRewindFiles === true) {
+        if (spec.resumeAt !== undefined) {
+            const e = new Error(`rewind-files: TaskSpec.rewindFiles is retired (design/381 — rewind now converges the per-edited-file history, not a whole-tree snapshot). This request pairs it with resumeAt, i.e. the RESTORE sense: set restoreFiles: true instead. (The capture sense needs no request anymore — first-touch tracking is always on when a RunnerDeps.fileHistoryStore is wired.)`);
+            e.code = "rewind.rewind_files_retired";
+            throw e;
+        }
+        try {
+            deps.onError?.(new Error(`TaskSpec.rewindFiles (capture sense) is retired and was ignored: per-edited-file first-touch tracking is always on when RunnerDeps.fileHistoryStore is wired, so a per-turn capture request has nothing left to ask for. Drop the field; the restore sense moved to TaskSpec.restoreFiles.`), { phase: "config", sessionId });
+        }
+        catch {
+        }
+    }
+    if (spec.restoreFiles === true && spec.resumeAt === undefined) {
+        const e = new Error(`rewind-files: restoreFiles: true needs a resumeAt anchor — restoring files means converging them to a specific prior entry's boundary, and this spec names none. Use resumeAt + restoreFiles to move conversation and files together, or rewindFilesTo alone for a code-only restore.`);
+        e.code = "rewind.invalid_spec";
+        throw e;
+    }
+    if (spec.resumeAt !== undefined && spec.rewindFilesTo !== undefined) {
+        const e = new Error(`rewind-files: resumeAt ("${spec.resumeAt}") and rewindFilesTo ("${spec.rewindFilesTo}") were both set — resumeAt already anchors the file restore when restoreFiles is true, so a separate rewindFilesTo target is a conflicting request. Drop one of the two.`);
+        e.code = "rewind.conflicting_targets";
+        throw e;
+    }
+    let rewindTarget = spec.resumeAt !== undefined ? (spec.restoreFiles === true ? spec.resumeAt : undefined) : spec.rewindFilesTo;
+    const rewindBefore = rewindTarget !== undefined && spec.resumeAt !== undefined && spec.resumeAtMode === "before";
+    if (spec.resumeAt !== undefined && spec.restoreFiles !== true) {
+        rewindNotes.push({
+            code: "conversation_only",
+            message: `the conversation was branched at entry "${spec.resumeAt}" but the working tree was NOT rewound — this task set resumeAt without restoreFiles, so files remain at their current state`,
+        });
+    }
+    const fileHistoryEnabled = fileHistoryStore !== undefined && handsEnabled;
+    const { historyRoot, historyScope, historyFs } = await resolveFileHistoryCoordinates(fileHistoryEnabled, executionEnv, taskRootFinal, internals?.fileHistoryLineage, sessionId);
+    if (fileHistoryStore !== undefined && internals?.fileHistoryLineage === undefined)
+        await adoptForkedFileHistory(fileHistoryStore, session, sessionId, deps.onError);
+    if (rewindTarget !== undefined && historyScope !== sessionId)
+        throw childScopeRewindRefusal(historyScope, rewindTarget);
+    if (fileHistoryStore === undefined) {
+        if (rewindTarget !== undefined) {
+            const e = new Error(`rewind-files: restoring files to entry "${rewindTarget}" requires a history backend, but this deployment wired no RunnerDeps.fileHistoryStore — no file history was ever recorded, so the files were NOT rewound`);
+            e.code = "rewind.store_unconfigured";
+            throw e;
+        }
+    }
+    else if (!handsEnabled) {
+        if (rewindTarget !== undefined) {
+            rewindNotes.push({
+                code: "files_env_unsupported",
+                message: "the file side of rewind was inert: this deployment mounts no filesystem-capable ExecutionEnv, so no file history was recorded or restored",
+            });
+        }
+    }
+    const legacyEpochTail = (entryId, form = "at-or-above") => legacyRewindEpochTail(deps, sessionId, entryId, form);
+    let restoredFilePaths = [];
+    if (rewindTarget !== undefined && fileHistoryStore !== undefined && handsEnabled) {
+        const historyStore = fileHistoryStore;
+        if (rewindBefore) {
+            let anchor;
+            if (await historyStore.canRestore(sessionId, rewindTarget)) {
+                anchor = rewindTarget;
+            }
+            else {
+                const walked = new Set();
+                let cursor = resumeAtBeforeParentId;
+                while (cursor !== null && !walked.has(cursor)) {
+                    walked.add(cursor);
+                    if (await historyStore.canRestore(sessionId, cursor)) {
+                        anchor = cursor;
+                        break;
+                    }
+                    cursor = (await session.getEntry(cursor))?.parentId ?? null;
+                }
+            }
+            if (anchor === undefined) {
+                const e = new Error(`rewind-files: no file-history boundary exists at or above the "before" branch point on session "${sessionId}" — cannot restore files consistent with the rewound context. ${await legacyEpochTail(rewindTarget)}`);
+                e.code = "rewind_snapshot.unresolvable";
+                throw e;
+            }
+            rewindTarget = anchor;
+        }
+        const restoreRoot = historyRoot;
+        const restoreSignal = spec.signal ? AbortSignal.any([abortController.signal, spec.signal]) : abortController.signal;
+        const restored = await historyStore.restore(sessionId, rewindTarget, executionEnv, restoreRoot, restoreSignal);
+        const ledgerLine = (r) => `applied ${r.filesChanged.length}, identical ${r.identicalSkipped.length}, refused ${r.refused.length}${r.refused.length > 0 ? ` (${r.refused.map((f) => `${f.path}: ${f.reason}`).join("; ")})` : ""}, failed ${r.failed.length}${r.failed.length > 0 ? ` (${r.failed.map((f) => `${f.path}: ${f.reason}`).join("; ")})` : ""}`;
+        if (restored.outcome === "failed") {
+            if (restored.error?.code === "not_found") {
+                const e = new Error(rewindBefore
+                    ? `rewind-files: the resolved "before" history anchor "${rewindTarget}" disappeared before restore — files were NOT rewound`
+                    : `rewind-files: no file-history boundary exists for entry "${rewindTarget}" on session "${sessionId}" — the working tree was NOT rewound. ${await legacyEpochTail(rewindTarget, "keyed")}`);
+                e.code = "rewind_snapshot.unresolvable";
+                throw e;
+            }
+            const e = new Error(`rewind-files restore failed (${restored.error?.code ?? "restore_failed"}): ${restored.error?.message ?? "unknown"} — ledger: ${ledgerLine(restored)}`);
+            e.code = "rewind.restore_failed";
+            throw e;
+        }
+        if (restored.outcome === "partial") {
+            if (spec.acceptPartialRestore === true) {
+                rewindNotes.push({
+                    code: "restore_partial",
+                    message: `file restore to entry "${rewindTarget}" was PARTIAL and was tolerated by acceptPartialRestore — ledger: ${ledgerLine(restored)}. Re-running the same restore converges (per-file idempotent).`,
+                });
+            }
+            else {
+                const e = new Error(`rewind-files: restore to entry "${rewindTarget}" was PARTIAL — ledger: ${ledgerLine(restored)}. The task is refused rather than run on a mixed-state tree (set acceptPartialRestore: true to tolerate and disclose instead); re-running the same restore converges (per-file idempotent).`);
+                e.code = "rewind.restore_failed";
+                throw e;
+            }
+        }
+        restoredFilePaths = restoredAbsPathsOf(restored, restoreRoot);
+    }
+    const trackFileEdit = fileHistoryEnabled
+        ? async (req) => {
+            const r = await fileHistoryStore.trackEdit(historyScope, req.key, executionEnv, historyRoot, req.signal);
+            if (r.ok) {
+                if (!r.minted)
+                    return { ok: true };
+                return {
+                    ok: true,
+                    annul: async (proof) => {
+                        const a = await fileHistoryStore.annulTrack(historyScope, req.key, historyRoot, proof === "verify" ? { env: executionEnv, ...(req.signal !== undefined ? { signal: req.signal } : {}) } : undefined);
+                        if (a.ok)
+                            return;
+                        try {
+                            deps.onError?.(new Error(`file-history could not retract the first-touch record for "${req.key}" after its edit failed to land (${a.error.code}: ${a.error.message}) — the path stays tracked, so a rewind to a boundary below it may converge bytes this engine never wrote`), { phase: "rewind", sessionId });
+                        }
+                        catch {
+                        }
+                    },
+                };
+            }
+            if (onTrackFailure === "proceed-unprotected") {
+                try {
+                    deps.onError?.(new Error(`file-history first-touch backup for "${req.key}" failed (${r.error.code}: ${r.error.message}) — proceeding UNPROTECTED per RunnerDeps.onTrackFailure: the pristine promise for this path is void, and only in this process's memory (no durable trace exists, so after a process restart the next edit can still mint already-modified bytes as pristine v1)`), { phase: "rewind", sessionId });
+                }
+                catch {
+                }
+                return { ok: true };
+            }
+            return {
+                ok: false,
+                refusal: `Error (${req.tool}): the edit was refused because its first-touch file-history backup could not be persisted (${r.error.code}: ${r.error.message}). Proceeding would leave "${req.path}" with no durable pristine record — after the history store recovers, a retried edit would mint already-modified bytes as the pristine baseline. Retry when the file-history store is healthy.`,
+            };
+        }
+        : undefined;
+    const fileHistoryBoundary = fileHistoryEnabled && historyScope === sessionId
+        ? createFileHistoryBoundarySeat({ store: fileHistoryStore, sessionId, env: executionEnv, root: historyRoot, onError: deps.onError })
+        : undefined;
+    return { trackFileEdit, fileHistoryBoundary, restoredFilePaths, rewindNotes, fileHistoryEnabled, historyScope, historyRoot, historyFs };
+}
+function restoredAbsPathsOf(restored, root) {
+    const out = [];
+    for (const key of [...restored.filesChanged, ...restored.failed.map((f) => f.path)]) {
+        const abs = resolveTrackKey(root, key);
+        if (abs.ok)
+            out.push(abs.abs);
+    }
+    return out;
+}
+function resolveWiredFileHistoryStore(candidate) {
+    if (candidate === undefined)
+        return undefined;
+    const verbs = ["trackEdit", "annulTrack", "snapshot", "restore", "canRestore", "reap", "adoptScope"];
+    const verbOf = (v) => {
+        try {
+            return candidate[v];
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const probeable = (typeof candidate === "object" && candidate !== null) || typeof candidate === "function";
+    const missing = probeable ? verbs.filter((v) => typeof verbOf(v) !== "function") : [...verbs];
+    if (missing.length > 0) {
+        const shape = candidate === null ? "null" : probeable ? "a value that is not a FileHistoryStore" : `a ${typeof candidate}`;
+        const e = new Error(`RunnerDeps.fileHistoryStore was wired with ${shape} — missing contract verbs: ${missing.join(", ")}. Refusing prepare rather than half-wiring the rewind seat (a present-but-unusable store makes every Edit/Write/NotebookEdit fail its first-touch backup while restore requests report "no store wired"). Omit the key to run without file history.`);
+        e.code = "config.invalid_file_history_store";
+        throw e;
+    }
+    return candidate;
+}
+const LEGACY_PROBE_TIMEOUT_MS = 2_000;
+const LEGACY_PROBE_TIMED_OUT = Symbol("legacy-rewind-probe-timeout");
+async function legacyRewindEpochTail(deps, sessionId, entryId, form) {
+    const probe = deps.legacyRewindBoundaryProbe;
+    let verdict;
+    if (probe !== undefined) {
+        try {
+            let timer;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(() => resolve(LEGACY_PROBE_TIMED_OUT), LEGACY_PROBE_TIMEOUT_MS);
+            });
+            try {
+                verdict = await Promise.race([Promise.resolve(probe({ sessionId, entryId })), timeout]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (verdict === LEGACY_PROBE_TIMED_OUT) {
+                verdict = undefined;
+                try {
+                    deps.onError?.(new Error(`RunnerDeps.legacyRewindBoundaryProbe did not answer within ${LEGACY_PROBE_TIMEOUT_MS}ms while explaining a rewind refusal — the refusal stands and names both possibilities`), { phase: "rewind", sessionId });
+                }
+                catch {
+                }
+            }
+        }
+        catch (err) {
+            verdict = undefined;
+            try {
+                deps.onError?.(new Error(`RunnerDeps.legacyRewindBoundaryProbe threw while explaining a rewind refusal (${err.message}) — the refusal stands and names both possibilities`), { phase: "rewind", sessionId });
+            }
+            catch {
+            }
+        }
+        if (verdict !== undefined && typeof verdict !== "boolean") {
+            try {
+                deps.onError?.(new Error(`RunnerDeps.legacyRewindBoundaryProbe answered ${JSON.stringify(String(verdict))} for entry "${entryId}" — only true/false/undefined are meaningful, so the refusal names both possibilities instead of trusting it`), { phase: "rewind", sessionId });
+            }
+            catch {
+            }
+            verdict = undefined;
+        }
+    }
+    if (verdict === true) {
+        return `This deployment's legacy-epoch probe reports that entry "${entryId}" DOES carry a boundary from the retired whole-tree snapshot era, which this engine's per-edited-file seat does not restore — the two epochs are not interchangeable (a whole-tree manifest carries no tracked-set provenance, so replaying it here would converge files this session never edited). Restore it with the whole-tree-era tooling this deployment kept, or re-run the turns under the current engine.`;
+    }
+    if (verdict === false) {
+        return `This deployment's legacy-epoch probe reports no whole-tree-era boundary for entry "${entryId}" either, so the boundary simply does not exist: its turns ran without a RunnerDeps.fileHistoryStore wired, or it was reaped.`;
+    }
+    return form === "keyed"
+        ? `Boundaries are keyed by a turn's INITIAL entry and exist only for turns that ran with a RunnerDeps.fileHistoryStore wired; a boundary from the retired whole-tree snapshot era is not restorable by this seat, and reaped boundaries have none.`
+        : `Either the boundary does not exist (its turns ran without a RunnerDeps.fileHistoryStore, or it was reaped), or it was produced in the retired whole-tree snapshot era, which this engine's per-edited-file seat does not restore.`;
+}
+const FILE_HISTORY_BOUNDARY_TIMEOUT_MS = 30_000;
+const FILE_HISTORY_CARRY_MEMO = new WeakMap();
+async function adoptForkedFileHistory(store, session, sessionId, onError) {
+    const memo = FILE_HISTORY_CARRY_MEMO.get(store) ?? { settled: new Set(), disclosed: new Set(), inFlight: new Map() };
+    FILE_HISTORY_CARRY_MEMO.set(store, memo);
+    const discloseOnce = (err) => {
+        if (memo.disclosed.has(sessionId))
+            return;
+        memo.disclosed.add(sessionId);
+        onError?.(err, { phase: "rewind", sessionId });
+    };
+    try {
+        if (memo.settled.has(sessionId))
+            return;
+        const forkedFrom = (await session.getMetadata()).forkedFrom;
+        if (forkedFrom === undefined || forkedFrom === sessionId)
+            return;
+        const shared = memo.inFlight.get(sessionId);
+        if (shared !== undefined)
+            return await shared;
+        if (memo.settled.has(sessionId))
+            return;
+        const attempt = store.adoptScope(forkedFrom, sessionId).then((carried) => {
+            if (carried.ok || carried.error.code === "conflict") {
+                memo.settled.add(sessionId);
+                return;
+            }
+            discloseOnce(new Error(`file-history fork carry from session "${forkedFrom}" failed (${carried.error.code}): ${carried.error.message} — this forked session starts with an EMPTY rewind history, so boundaries recorded before the fork are not restorable from it (the run itself proceeds; the carry is retried on this session's next turn while its scope is still empty)`));
+        }, (err) => discloseOnce(err));
+        memo.inFlight.set(sessionId, attempt);
+        try {
+            await attempt;
+        }
+        finally {
+            memo.inFlight.delete(sessionId);
+        }
+    }
+    catch (err) {
+        try {
+            discloseOnce(err);
+        }
+        catch {
+        }
+    }
+}
+function createFileHistoryBoundarySeat(opts) {
+    let inFlight;
+    let begun = false;
+    return {
+        begin(entryId) {
+            if (begun)
+                return;
+            begun = true;
+            const ac = new AbortController();
+            let timer;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    ac.abort();
+                    resolve({ ok: false });
+                }, FILE_HISTORY_BOUNDARY_TIMEOUT_MS);
+            });
+            let work;
+            try {
+                work = opts.store.snapshot(opts.sessionId, entryId, opts.env, opts.root, ac.signal);
+            }
+            catch (err) {
+                work = Promise.resolve({ ok: false, error: { code: "snapshot_failed", message: `history store threw synchronously: ${err.message}` } });
+            }
+            work.catch(() => { });
+            inFlight = Promise.race([
+                work.then((r) => (r.ok ? undefined : `boundary capture failed (${r.error.code}): ${r.error.message}`)),
+                timeout.then(() => `boundary capture timed out after ${FILE_HISTORY_BOUNDARY_TIMEOUT_MS / 1000}s (fenced — the attempt can never publish)`),
+            ])
+                .then((failure) => {
+                if (failure !== undefined) {
+                    try {
+                        opts.onError?.(new Error(`file-history ${failure} — this turn has no boundary and cannot be rewound to (the turn itself proceeds)`), { phase: "rewind", sessionId: opts.sessionId });
+                    }
+                    catch {
+                    }
+                }
+            })
+                .catch((err) => {
+                try {
+                    opts.onError?.(err, { phase: "rewind", sessionId: opts.sessionId });
+                }
+                catch {
+                }
+            })
+                .finally(() => clearTimeout(timer));
+        },
+        async settle() {
+            if (inFlight !== undefined)
+                await inFlight;
+        },
+    };
+}
+async function resolveFileHistoryCoordinates(enabled, env, taskRoot, lineage, sessionId) {
+    if (!enabled)
+        return { historyRoot: taskRoot, historyScope: sessionId, historyFs: "" };
+    const canonRoot = await env.canonicalPath(taskRoot);
+    const historyRoot = canonRoot.ok ? canonRoot.value : taskRoot;
+    const historyFs = fileHistoryFilesystemIdentity(env);
+    return { historyRoot, historyScope: resolveFileHistoryScope(lineage, historyRoot, historyFs, sessionId), historyFs };
+}
+export function resolveFileHistoryScope(lineage, historyRoot, historyFs, sessionId) {
+    if (lineage === undefined || lineage.scope === "" || lineage.root !== historyRoot || lineage.fs !== historyFs)
+        return sessionId;
+    return lineage.scope;
+}
+const envFilesystemTokens = new WeakMap();
+let envFilesystemSeq = 0;
+export function fileHistoryFilesystemIdentity(env) {
+    if (isRemoteExecutionEnv(env)) {
+        try {
+            const h = env.workspaceHandle();
+            return JSON.stringify(["remote", h.provider, h.sandboxId, h.deviceId !== undefined && h.deviceId !== "" ? h.deviceId : null]);
+        }
+        catch {
+        }
+    }
+    else if (env.hostLocalPaths === true || (env.hostLocalPaths === undefined && env instanceof NodeExecutionEnv)) {
+        return "host";
+    }
+    let token = envFilesystemTokens.get(env);
+    if (token === undefined) {
+        token = `instance:${++envFilesystemSeq}`;
+        envFilesystemTokens.set(env, token);
+    }
+    return token;
+}
+function childScopeRewindRefusal(rootScope, target) {
+    const e = new Error(`rewind-files: this run is a delegated child recording its edits into the ROOT session "${rootScope}"'s file history, so restoring files to entry "${target}" is the root session's action (rewindFilesTo / resumeAt+restoreFiles on that session), not the child's — the files were NOT rewound`);
+    e.code = "rewind.child_scope_unsupported";
+    return e;
+}

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

@@ -0,0 +1,177 @@
+/**
+ * design/390 §1.2 M20 — prepareTask's two GATE STATIONS, verbatim from the driver: the `tool_call` station (the final-roster
+ * effect sync, the write-protection judge compiled once per task, the arming predicate, the compliance and plan-mode
+ * short-circuits, the `runToolGate` call with every seat it is handed, the lifecycle sweep, the deferred sandbox-admission
+ * disclosure, the PreToolUse context stash, the settlement sideband write and the bare-human-rejection boundary) and the
+ * `tool_result` station (the PostToolUse / PostToolUseFailure seats and the PreToolUse context drain). The two module-scope
+ * helpers only these stations called moved with them (the settlement screen, the rejection-boundary judgment). The
+ * interface is the dependency list the stations had implicitly (design/238 R-1).
+ *
+ * The stations REGISTER handlers on the harness (the side effect this phase exists for) and report only two observation
+ * seats back; the order they register in — after the file-history boundary lease the driver registers, and in this order
+ * (call before result) — is the order handlers run in.
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the handlers run per tool call / per tool
+ * result), so the phase adds no yield between the park closure before it and the context lane after it (design/390 §1.5).
+ * Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * The `tool_call` station is built exactly when the ask lane and the park closure are (the same predicate as the whole
+ * gate-machinery block, kept as the block's one guard here); the `tool_result` station keys off the hook record alone, as
+ * it always did.
+ *
+ * Every station this file holds is a `denySource` / settlement WRITE site the decomposition's next slice maps onto one
+ * gate outcome; nothing here changes a word, a source or an order — the stations are moved, not re-adjudicated.
+ */
+import type { AgentHarness, AgentTool } from "../../internal/harness.js";
+import type { AskClass } from "../ask-class.js";
+import type { AutoModeDecider, AutoModeDenialTracker } from "../auto-mode.js";
+import { type ComplianceCapability } from "../compliance.js";
+import { type HookEnvCapabilities, type HookInvocationIdentity, type Hooks } from "../hooks.js";
+import { type ToolPolicy } from "../tool-policy.js";
+import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import type { AskLane, IrreversibilityTier, ParkAsk, Prepared, ReversibilityProbes } from "./contracts.js";
+import type { StopForDenialLimit } from "./denial-limit-arms.js";
+import type { PermissionRuleLanes } from "./permission-rule-lanes.js";
+export interface PrepareGateStationsInput {
+    /** borrowed-readonly — the in-stream ask lane, or undefined when the gate machinery is inactive (then no `tool_call`
+     *  station is built). Read: `adjudicate`, `resolveAskBound`, `notifyPermissionDenied`, `notifyHookError`. */
+    askLane: AskLane | undefined;
+    /** borrowed-readonly — the park closure and the content-ask routing closure, or undefined (same law). Handed to the gate. */
+    parkAsk: ParkAsk | undefined;
+    /** borrowed-readonly — the FINAL mount roster: iterated once for the effect sync and the write-protection arming. Never
+     *  mutated here. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the effect collection. Writer here: the final-roster sync fills MISSING entries from each
+     *  first-party tool's declared effect (never overrides a scanned one); the plan-mode deny reads it per call. */
+    toolEffects: Map<string, ToolEffect>;
+    /** borrowed-readonly — the deployment seats these stations read, as a Pick over the SAME `deps` object (receiver
+     *  preserved for `deps.onError?.()`): the write-protection table and its data root, the tracer, the error face. */
+    deps: Pick<RunnerDeps, "writeProtectedPaths" | "memoryEngineDir" | "tracer" | "onError">;
+    /** borrowed-mutable — the protocol-tools phase's arming belt. Writer here: `armed` ← the registration predicate, the
+     *  one write; the refresh seam reads it. */
+    toolCallGateArmedRef: {
+        armed: boolean;
+    };
+    /** borrowed-readonly — the policy chain's effective policy, or undefined; presence only (the arming predicate). */
+    effectivePolicy: ToolPolicy | undefined;
+    /** borrowed-readonly — the resolved hook record: `preToolUse` presence (arming), the two post seats and the failure seat
+     *  (the `tool_result` station), called through the record so a class-instance keeps its receiver. */
+    hooks: Hooks | undefined;
+    /** borrowed-readonly — the egress vocabulary: arming, and the per-call `egress` flag handed to the gate. */
+    egressTools: ReadonlySet<string>;
+    /** borrowed-readonly — the irreversible vocabulary: arming only. */
+    irreversibleTools: ReadonlySet<string>;
+    /** borrowed-readonly — the REBOUND spec: `enablePlanMode` (arming) and `signal` (the failure seat's interrupt fact). */
+    spec: Pick<TaskSpec, "enablePlanMode" | "signal">;
+    /** borrowed-readonly — the compliance denials (the web_fetch veto's call-time lock, and its arming term). */
+    complianceDenies: ReadonlySet<ComplianceCapability>;
+    /** borrowed-mutable — the built harness. Writer here: `on("tool_call")` / `on("tool_result")` — the registrations this
+     *  phase exists for, in this order, after the driver's boundary-lease handler. */
+    harness: Pick<AgentHarness, "on">;
+    /** borrowed-mutable — the blocked/suspended call ids (`Prepared.blockedToolCalls`). Writers here: the head-of-evaluation
+     *  hygiene `delete`, the two short-circuits' and the gate outcome's `add`, the `tool_result` station's one-shot `delete`. */
+    blockedToolCalls: Set<string>;
+    /** borrowed-mutable — the duplicate-frame ask-grant record. Writer here: the head-of-evaluation and lifecycle-end `delete`. */
+    inheritedAskGrants: Map<string, unknown>;
+    /** borrowed-mutable — the bare-human-rejection sideband. Writer here: the head-of-evaluation `delete` and the lifecycle
+     *  sweep whose `delete` IS the read the boundary judgment consumes. */
+    humanBareRejections: Set<string>;
+    /** borrowed-mutable — the inherited-unavailable marker set. Writer here: the lifecycle-end `delete`; `has` is handed to
+     *  the gate as the read-only `isMarkedUnresolvable`. */
+    inheritedUnavailableAsks: Set<string>;
+    /** borrowed-mutable — the per-call ask-class record the sandbox admission reads. Writer here: the lifecycle-end `delete`. */
+    foldAskClasses: Map<string, Array<{
+        cls: AskClass;
+        layer: string;
+    }>>;
+    /** borrowed-mutable — the deferred ancestor sandbox admissions. Writer here: the unconditional read-and-`delete` after the
+     *  fold settles. */
+    ancestorSandboxAdmissions: Map<string, Array<{
+        cls: AskClass;
+        layer: string;
+    }>>;
+    /** borrowed-mutable — PreToolUse `additionalContext` per call id. Writers here: the `tool_call` station's stash (`set`, only
+     *  for calls that will execute) and the `tool_result` station's one-shot drain (`delete`). */
+    preToolContexts: Map<string, string[]>;
+    /** borrowed-mutable — the settlement sideband (`Prepared.approvalSettlement`). Writer here: the ONE screened `set` per
+     *  gate outcome; the frame mint reads and deletes. */
+    approvalSettlement: Prepared["approvalSettlement"];
+    /** borrowed-mutable — the turn halt fact (`Prepared.batchHaltRef`). Writer here: the bare-rejection boundary (`current`). */
+    batchHaltRef: Prepared["batchHaltRef"];
+    /** borrowed-readonly — whether blocked/suspended ids are tracked at all (the post-tool callbacks exist). */
+    blockedTracked: boolean;
+    /** borrowed-readonly — the leg's identity envelope every HookToolContext and PermissionDeniedPayload carries. */
+    hookIdentity: HookInvocationIdentity;
+    /** borrowed-readonly — the leg's reminder provenance mark (every model-facing deny reason and hook context carries it). */
+    reminderMark: string;
+    /** borrowed-readonly — the plan-mode latch (`Prepared.planModeRef`); `active` is read per call. Not written here. */
+    planModeRef: Prepared["planModeRef"];
+    /** borrowed-readonly — the per-task identity (the trace rows' taskId). */
+    hostTaskId: string;
+    /** borrowed-readonly — the acquired session id (the settlement defects' error tag). */
+    sessionId: string;
+    /** borrowed-readonly — the screening face as the gate must see it (the observational wrapper or the face itself). */
+    ownGatePreToolUse: Hooks["preToolUse"] | undefined;
+    /** borrowed-readonly — the validated per-prepare hook seat bound. */
+    hookTimeoutMs: number;
+    /** borrowed-readonly — the hand's live tracked cwd, or undefined; `current` is read per screening / per post seat. Not
+     *  written here. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the read-only env capability face every hook context carries, or undefined. */
+    hookEnvFace: HookEnvCapabilities | undefined;
+    /** borrowed-readonly — the per-tool irreversibility tier handed to the gate per call. */
+    irreversibilityTier: IrreversibilityTier;
+    /** borrowed-readonly — the per-tool reversibility probes handed to the gate per call. */
+    reversibilityProbes: ReversibilityProbes;
+    /** borrowed-readonly — prepare's abort seat; only `.signal` is read (the gate's probe bound, the post seats' bound, the
+     *  failure seat's interrupt fact). */
+    abortController: {
+        readonly signal: AbortSignal;
+    };
+    /** borrowed-readonly — whether Bash is coarsely shell-gated (the gate's `shellGated` attribution). */
+    shellGatedBash: boolean;
+    /** borrowed-readonly — whether Monitor is coarsely shell-gated (same). */
+    shellGatedMonitor: boolean;
+    /** borrowed-readonly — the auto-mode decider, or undefined (the classifier lane the gate routes a surviving ask through). */
+    autoModeDecider: AutoModeDecider | undefined;
+    /** borrowed-readonly — the auto-mode denial tracker, or undefined (handed to the gate beside the decider). */
+    autoModeDenialTracking: AutoModeDenialTracker | undefined;
+    /** borrowed-readonly — the headless denial-limit stop seat (wired unconditionally). */
+    stopForDenialLimit: StopForDenialLimit;
+    /** borrowed-readonly — the persisted allow-rule lane, or undefined (absent entirely with no store). */
+    permissionRuleLane: PermissionRuleLanes["personal"];
+    /** borrowed-readonly — the org rule lane, or undefined (absent on an ungoverned deployment). */
+    permissionRuleOrgLane: PermissionRuleLanes["org"];
+    /** borrowed-readonly — whether the ENGINE's question tool is what is mounted under the reserved name (the org lane's
+     *  content-ask exemption predicate). */
+    questionToolMounted: boolean;
+    /** borrowed-readonly — whether sandbox admission is armed (isolated env + park prerequisites). */
+    sandboxAdmissionArmed: boolean;
+    /** borrowed-readonly — the per-tool boundary-capability fact the sandbox admission reads. */
+    sandboxBoundaryCapable: (toolName: string) => boolean;
+    /** borrowed-readonly — the sandbox-admission trace sink (the deferred ancestor disclosure and the gate's own). */
+    emitSandboxAdmitted: (info: {
+        toolCallId: string;
+        toolName: string;
+        askClasses: ReadonlyArray<{
+            cls: AskClass;
+            layer: string;
+        }>;
+        boundary: "sandbox_internal";
+    }) => void;
+    /** borrowed-readonly — the effective delegation facts (the rejection boundary's isDelegatedChild). */
+    delegation: {
+        isDelegatedChild: boolean;
+    };
+    /** borrowed-readonly — the own hook-crash reporter (an expired post seat is reported through it). */
+    notifyOwnHookCrash: (err: unknown) => void;
+}
+export interface PrepareGateStationsResult {
+    /** owned — whether the `tool_call` station registered (the arming predicate's value; observation seat only). */
+    toolCallStationArmed: boolean;
+    /** owned — whether the `tool_result` station registered (a post or screening hook is wired; observation seat only). */
+    toolResultStationArmed: boolean;
+}
+/** The M20 phase body — prepareTask's two gate stations, verbatim (see the module header). */
+export declare function prepareGateStations(input: PrepareGateStationsInput): PrepareGateStationsResult;