@sema-agent/core 7.5.0 → 7.5.1

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

@@ -0,0 +1,240 @@
+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, 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;
+    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, hookIdentity, hookEnvFace };
+}

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

@@ -1,19 +1,7 @@
 import type { RemoteExecutionEnv, RemoteExecutionError, SnapshotId, VmLifecycleOptions } from "../remote-env.js";
 import type { ExecutionEnv } from "../../internal/harness.js";
 import type { RemoteEnvFailureNote, RunnerDeps, TaskSpec } from "../types.js";
-import type { PrepareResume, RunInternals } from "./prepare-task.js";
-/**
- * rebase one checkpointed absolute path from the OLD workspace root onto the RESTORED
- * one (divergent `resumeVM`). POSIX-ONLY by contract: every remote lane's `mountPath` is a container
- * path (e2b/k8s/ssh/adb/local-docker are all Linux targets), so a backslash ANYWHERE in the inputs marks
- * the value outside this function's domain and it returns `p` UNCHANGED — an un-rebased path is honestly
- * observable (the divergence observation already fired) while a WRONGLY-rebased one silently corrupts
- * cwd/read-state (r4: drive-root and cross-family recomposition are not implementable without a Windows
- * path model no lane needs). Trailing slashes are tolerated (from="/app/" must not weld the suffix);
- * bare "/" keeps filesystem-root semantics; a path outside `from` (incl. the prefix-sibling
- * "/application" vs "/app") returns unchanged. Exported for direct unit pinning.
- */
-export declare function rebaseWorkspacePath(p: string, fromRaw: string, toRaw: string): string;
+import type { PrepareResume, RunInternals } from "./contracts.js";
 /**
  * RB-439-a — project one failed remote lifecycle call onto the caller-facing note. ONE builder for all
  * three ops so the `retryable` classification can never drift between the lane that reports a `suspendVM`
@@ -41,20 +29,6 @@ onAttempt?: (attempt: number) => void): Promise<{
     outcome: Awaited<ReturnType<RemoteExecutionEnv["resumeVM"]>>;
     attempts: number;
 }>;
-/**
- * RB-439-c — {@link rebaseWorkspacePath} over a SET of accepted spellings of the old root: the first
- * prefix that actually matches wins, and a path under none of them is returned unchanged.
- *
- * The set exists because "the old root" has no single spelling. `WorkspaceHandle.mountPath` is whatever the
- * adapter called the mount, while the persisted paths being migrated were spelled by whoever produced them
- * (a `cd` the env canonicalized, a Read key resolved through realpath). On a target where the root has an
- * equivalent alias (`/var` ↔ `/private/var`) those disagree while naming the same directory, and a
- * single-prefix rebase then matched nothing and silently left the resumed shell in the pre-suspend tree —
- * under a disclosure that said the task follows the restored root. Order is caller-chosen (the checkpointed
- * spelling first, its canonical form second) and only matters if one prefix is a prefix of another, in
- * which case the earlier — more specific — spelling is the intended one. Exported for direct unit pinning.
- */
-export declare function rebaseWorkspacePathAcross(p: string, froms: readonly string[], to: string): string;
 export interface PrepareWorkspaceRestoreInput {
     /** borrowed-readonly (the ownership-ref PROTOCOL stays with the driver — D-8 案①): the env this
      *  task owns, when the factory minted one. This phase reads and drives it (`resumeVM`,

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

@@ -1,19 +1,6 @@
 import { isRemoteExecutionEnv, isRetryableRemoteErrorCode, missingRestoreSurface, RETRYABLE_REMOTE_ERROR_CODES } from "../remote-env.js";
 import { withRetry } from "../with-retry.js";
-export function rebaseWorkspacePath(p, fromRaw, toRaw) {
-    if (p.includes("\\") || fromRaw.includes("\\") || toRaw.includes("\\"))
-        return p;
-    const stripTrail = (s) => (s.length > 1 && s.endsWith("/") ? stripTrail(s.slice(0, -1)) : s);
-    const from = stripTrail(fromRaw);
-    const to = stripTrail(toRaw);
-    if (p === from || stripTrail(p) === from)
-        return to;
-    const fromPrefix = from === "/" ? from : `${from}/`;
-    if (!p.startsWith(fromPrefix))
-        return p;
-    const suffix = p.slice(fromPrefix.length).replace(/^\/+/, "");
-    return to === "/" ? `${to}${suffix}` : `${to}/${suffix}`;
-}
+import { rebaseWorkspacePathAcross } from "./workspace-path.js";
 export function remoteEnvFailureNote(op, error, attempts) {
     return { op, code: error.code, retryable: isRetryableRemoteErrorCode(error.code), attempts, message: error.message };
 }
@@ -28,14 +15,6 @@ export async function restoreWorkspaceWithRetry(env, snapshotId, options, onAtte
     }, { retryableCodes: RETRYABLE_REMOTE_ERROR_CODES, maxAttempts: REMOTE_RESTORE_MAX_ATTEMPTS, backoffMs: () => REMOTE_RESTORE_BACKOFF_MS }, { ...(options.abortSignal !== undefined ? { signal: options.abortSignal } : {}) });
     return { outcome, attempts };
 }
-export function rebaseWorkspacePathAcross(p, froms, to) {
-    for (const from of froms) {
-        const out = rebaseWorkspacePath(p, from, to);
-        if (out !== p)
-            return out;
-    }
-    return p;
-}
 export async function prepareWorkspaceRestore(input) {
     const { ownedEnv, deps, spec, internals, resume, abortController, sessionId } = input;
     let taskRootPath = input.taskRootInitial;

package/dist/core/runner/rollback-stack.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The prepare-FAILURE rollback stack — the implementation of {@link RollbackStack} (declared beside the
+ * other prepare contracts in ./contracts.ts, whose JSDoc carries the contract this file keeps).
+ *
+ * Why a stack and not a `finally`: prepare acquires resources in sequence (an execution env, MCP
+ * clients, A2A peers) and every one of them belongs to the RUN once prepare succeeds — the Runner's
+ * finish/teardown releases them. Only a prepare that THROWS must release what it already took, in
+ * reverse acquisition order. Today the orchestrator sees those handles because they are hoisted
+ * `let`s at function scope; a phase module that acquires a handle inside its own body has no such
+ * hoist, so it registers the cleanup HERE, immediately after the acquisition, and the driver unwinds
+ * the whole stack from its one catch.
+ *
+ * Posture (identical to the teardown leg the catch already uses — {@link settleTeardownLeg}):
+ *   · reverse order, each cleanup exactly once — the entry is removed before it runs, so a second
+ *     `unwindAll` (or a re-entrant one) finds nothing;
+ *   · no cleanup can stop another — a throw is routed to `report`, a hang is BOUNDED and reported as a
+ *     `TeardownLegTimeoutError` naming the leg; the unwind proceeds either way;
+ *   · `unwindAll` NEVER throws — it runs inside the driver's catch, where a throw would replace the
+ *     prepare error the caller is owed.
+ *
+ * States: `armed` (accepting pushes) → `committed` (prepare succeeded; the stack is emptied and
+ * ownership has passed to `Prepared`) or → `unwinding`/`unwound` (the failure path ran). A `push`
+ * outside `armed` is a PROGRAMMING error and is refused loudly: a resource acquired after commit
+ * would have no owner on the failure path, and one pushed during an unwind would never run.
+ */
+import type { RollbackStack } from "./contracts.js";
+/**
+ * Mint one stack per prepare. `report` is the incident channel for a cleanup that throws or times out
+ * (wire it to `deps.onError`); with none, failures of the failure path are dropped — the same
+ * contract `settleTeardownLeg` states for its own `report`.
+ */
+export declare function createRollbackStack(report?: (err: Error) => void): RollbackStack;

package/dist/core/runner/rollback-stack.js

@@ -0,0 +1,30 @@
+import { settleTeardownLeg } from "./teardown-bounded.js";
+export function createRollbackStack(report) {
+    const cleanups = [];
+    let state = "armed";
+    return {
+        push(cleanup) {
+            if (state !== "armed") {
+                throw new Error(`RollbackStack.push after ${state}: a cleanup registered once prepare has ${state === "committed" ? "succeeded" : "started unwinding"} would ${state === "committed" ? "never be owned by the failure path" : "never run"} — acquire resources only while the stack is armed.`);
+            }
+            cleanups.push(cleanup);
+        },
+        commit() {
+            if (state !== "armed")
+                throw new Error(`RollbackStack.commit after ${state}: commit is the success path's one disarm and cannot follow an unwind or a second commit.`);
+            state = "committed";
+            cleanups.length = 0;
+        },
+        async unwindAll() {
+            if (state !== "armed")
+                return;
+            state = "unwinding";
+            const total = cleanups.length;
+            let leg = total;
+            for (let cleanup = cleanups.pop(); cleanup !== undefined; cleanup = cleanups.pop(), leg--) {
+                await settleTeardownLeg(cleanup, `${cleanup.name !== "" ? cleanup.name : "anonymous cleanup"} (rollback leg ${leg} of ${total}, prepare-throw)`, report);
+            }
+            state = "unwound";
+        },
+    };
+}

package/dist/core/runner/workspace-path.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure path arithmetic for a workspace whose ROOT moved: rebase an absolute path from the old root
+ * onto the new one. No I/O, no state, no dependency on anything — which is why it lives here rather
+ * than inside the restore phase that used to own it. The read-face phase needs the same arithmetic,
+ * and a phase reaching sideways into a sibling phase for a helper is the shape the dependency
+ * gate exists to stop; the answer is to put the helper where both can reach DOWN to it.
+ */
+/**
+ * rebase one checkpointed absolute path from the OLD workspace root onto the RESTORED
+ * one (divergent `resumeVM`). POSIX-ONLY by contract: every remote lane's `mountPath` is a container
+ * path (e2b/k8s/ssh/adb/local-docker are all Linux targets), so a backslash ANYWHERE in the inputs marks
+ * the value outside this function's domain and it returns `p` UNCHANGED — an un-rebased path is honestly
+ * observable (the divergence observation already fired) while a WRONGLY-rebased one silently corrupts
+ * cwd/read-state (r4: drive-root and cross-family recomposition are not implementable without a Windows
+ * path model no lane needs). Trailing slashes are tolerated (from="/app/" must not weld the suffix);
+ * bare "/" keeps filesystem-root semantics; a path outside `from` (incl. the prefix-sibling
+ * "/application" vs "/app") returns unchanged. Exported for direct unit pinning.
+ */
+export declare function rebaseWorkspacePath(p: string, fromRaw: string, toRaw: string): string;
+/**
+ * RB-439-c — {@link rebaseWorkspacePath} over a SET of accepted spellings of the old root: the first
+ * prefix that actually matches wins, and a path under none of them is returned unchanged.
+ *
+ * The set exists because "the old root" has no single spelling. `WorkspaceHandle.mountPath` is whatever the
+ * adapter called the mount, while the persisted paths being migrated were spelled by whoever produced them
+ * (a `cd` the env canonicalized, a Read key resolved through realpath). On a target where the root has an
+ * equivalent alias (`/var` ↔ `/private/var`) those disagree while naming the same directory, and a
+ * single-prefix rebase then matched nothing and silently left the resumed shell in the pre-suspend tree —
+ * under a disclosure that said the task follows the restored root. Order is caller-chosen (the checkpointed
+ * spelling first, its canonical form second) and only matters if one prefix is a prefix of another, in
+ * which case the earlier — more specific — spelling is the intended one. Exported for direct unit pinning.
+ */
+export declare function rebaseWorkspacePathAcross(p: string, froms: readonly string[], to: string): string;

package/dist/core/runner/workspace-path.js

@@ -0,0 +1,22 @@
+export function rebaseWorkspacePath(p, fromRaw, toRaw) {
+    if (p.includes("\\") || fromRaw.includes("\\") || toRaw.includes("\\"))
+        return p;
+    const stripTrail = (s) => (s.length > 1 && s.endsWith("/") ? stripTrail(s.slice(0, -1)) : s);
+    const from = stripTrail(fromRaw);
+    const to = stripTrail(toRaw);
+    if (p === from || stripTrail(p) === from)
+        return to;
+    const fromPrefix = from === "/" ? from : `${from}/`;
+    if (!p.startsWith(fromPrefix))
+        return p;
+    const suffix = p.slice(fromPrefix.length).replace(/^\/+/, "");
+    return to === "/" ? `${to}${suffix}` : `${to}/${suffix}`;
+}
+export function rebaseWorkspacePathAcross(p, froms, to) {
+    for (const from of froms) {
+        const out = rebaseWorkspacePath(p, from, to);
+        if (out !== p)
+            return out;
+    }
+    return p;
+}

package/dist/core/tool-policy.d.ts

@@ -1415,6 +1415,22 @@ export declare function withDelegationProvenance(onAsk: OnAsk, delegation: AskDe
  * consultation". A non-wrapper value (including `"allow"`/`"deny"`/undefined) is its own identity.
  */
 export declare function askApproverIdentity(onAsk: unknown): unknown;
+/**
+ * Is this `onAsk` seat a LIVE APPROVER — a person the run can actually reach?
+ *
+ * Only a function is. A blanket `"allow"`/`"deny"` string is a policy setting (the same reading the
+ * interaction-posture door gives it), and an absent seat is nobody at all; neither can answer an ask, so
+ * neither may outrank a durable park.
+ *
+ * ONE definition on purpose. Two sites must agree on this — the run's own sync-first decline, and the
+ * mandate frozen into the chain its children inherit — and when they were two hand-written booleans they
+ * drifted: the decline narrowed to the function test while the freeze kept testing mere presence, and
+ * each still read correctly on its own, so nothing pointed at the pair. A blanket seat was therefore not
+ * an approver for the parent's asks and an approver for its children's. Declared here, in the vocabulary
+ * beside {@link askApproverIdentity}, because the two sites are now two prepare phases (the inherited-gate
+ * fold and the wiring station) plus the orchestrator, and each reaches DOWN for the one definition.
+ */
+export declare function isLiveApproverSeat(onAsk: OnAsk | undefined): boolean;
 /** EXACT structural clone for the approval boundary (alias isolation) — fail-closed, never lossy,
  *  never identity: a JSON round-trip would silently DROP unclonable members (presented ≠ executing =
  *  consent misrepresentation) and an identity fallback would hand the approver the live executing

package/dist/core/tool-policy.js

@@ -847,6 +847,9 @@ export function withDelegationProvenance(onAsk, delegation) {
 export function askApproverIdentity(onAsk) {
     return typeof onAsk === "function" ? (delegatedApproverRoot.get(onAsk) ?? onAsk) : onAsk;
 }
+export function isLiveApproverSeat(onAsk) {
+    return typeof onAsk === "function";
+}
 export function tryCloneArgs(v) {
     try {
         const value = structuredClone(v);

package/dist/core/types.d.ts

@@ -662,7 +662,7 @@ export interface ToolExecuteContext {
              * at all; a park under a screening entry announces the requirement on `onError`
              * (classification `screening-constraint-in-durable-chain`) at park time.
              */
-            inheritedGate?: import("./runner/prepare-task.js").InheritedGate;
+            inheritedGate?: import("./runner/contracts.js").InheritedGate;
         };
         /**
          * design/176 — the peer-chain SEED for a message-driven (tier-3) revival: the hop chain of the
@@ -1046,7 +1046,7 @@ export interface ToolExecuteContext {
      * read-only, NEVER a model/tool argument (same posture as {@link activeSkillScope}). Undefined when the
      * tool runs outside a Runner task.
      */
-    inheritedGateForChildren?: () => import("./runner/prepare-task.js").InheritedGate;
+    inheritedGateForChildren?: () => import("./runner/contracts.js").InheritedGate;
     /**
      * design/180 half A — the delegation runtime-provenance ARMING face. Runner-filled; a delegation
      * tool calls it at spawn time: a non-undefined return means this (parent) run is armed (it mounts

package/dist/core/write-protect.js

@@ -1,4 +1,4 @@
-import { isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
+import { isWinFormPath, writeTargetPath, isUncPath } from "../tools/fs/safety.js";
 import { PATH_CONFINABLE_WRITE_TOOLS } from "./runner/session-rule-policy.js";
 import { dataRootSpellings } from "./sensitive-path-policy.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
@@ -137,7 +137,8 @@ function pathViewSegments(path, win32, seps = BOTH_SEPARATOR_FAMILIES, anchorFlo
 const BOTH_SEPARATOR_FAMILIES = /[\\/]/;
 const POSIX_SEPARATOR_FAMILY = /\//;
 function uncAnchorSegments(path) {
-    return /^[\\/]{2}[^\\/]/.test(path) ? 2 : 0;
+    const third = path[2];
+    return isUncPath(path) && third !== undefined && third !== "\\" && third !== "/" ? 2 : 0;
 }
 function relativeUnderDataRoot(path, roots) {
     for (const root of roots) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.5.0",
+  "version": "7.5.1",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -73,7 +73,11 @@
     "gate:error-surface": "node scripts/verify-error-surface.mjs",
     "gate:criteria": "node scripts/criteria-lint.mjs",
     "gate:reminder-literal": "node scripts/verify-reminder-literal.mjs",
-    "gate:wire": "node scripts/wire-changes.mjs"
+    "gate:wire": "node scripts/wire-changes.mjs",
+    "gate:layering": "node scripts/verify-layering.mjs",
+    "gate:phase-api": "node scripts/verify-phase-api.mjs",
+    "gate:agent-returns": "node scripts/verify-agent-returns.mjs",
+    "gate:all": "node scripts/gate-all.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",