@sema-agent/core 7.4.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/runtask.d.ts

@@ -86,7 +86,9 @@ declare function toolEndBodyFrom(result: unknown, isError: boolean,
  *  live loop reads it off the gate's per-call sideband, the resumed leg off the decide. Deliberately
  *  a parameter and never derived from `result`: a tool's own `details` (which post-tool hooks may
  *  also replace) is writable by layers that adjudicate nothing, so reading provenance out of it would
- *  let a failing tool claim a person approved it. Omitted ⇒ this call settled no approval. */
+ *  let a failing tool claim a person approved it. Omitted ⇒ the caller supplied no source: the call
+ *  settled no approval, OR an approval settled whose decider named none (a caller predating the
+ *  field) — absence is not a fact about the call (see the `tool_end.settledBy` doc, the one home). */
 settledBy?: ApprovalSettledBy, 
 /** design/252 G-7 — WHOSE settlement, from the same caller and the same channel as `settledBy`, and
  *  for the same reason it is a parameter: an attribution read out of a tool's own result would let a
@@ -100,7 +102,13 @@ resolution?: import("../tool-policy.js").AskDenyResolution,
  *  sharpest version of that reason: this one is an assertion about a DIFFERENT call, so a tool able to
  *  author it could point an approval UI at a call nobody is waiting on. Omitted ⇒ no park is holding a
  *  call (nothing parked, or the park that did holds none), and the frame then carries no id at all. */
-gatedCallIdOfRun?: string): {
+gatedCallIdOfRun?: string, 
+/** #557 — the classifier denial-limit fallback's own auto-deny marker, from the same engine-owned
+ *  settlement sideband as `resolution` (same never-derived-from-`result` posture). Omitted ⇒ absent.
+ *  The pair `settledBy:"timeout"` + `resolution:"window_expired"` WITHOUT this bit is the approval
+ *  factory's own `approvalTimeoutMs` window; a durable park's expiry is neither — the decide lane's
+ *  emitter passes no `resolution` at all (see the `tool_end.autoDenied` doc on the event type). */
+autoDenied?: true): {
     output?: unknown;
     truncated?: boolean;
     totalChars?: number;
@@ -110,6 +118,7 @@ gatedCallIdOfRun?: string): {
     settledBy?: ApprovalSettledBy;
     approver?: string;
     resolution?: import("../tool-policy.js").AskDenyResolution;
+    autoDenied?: true;
 };
 /**
  * scan-1/A1 — the BODY of the synthetic `tool_end` that closes a reconcile-recovered orphan. ONE

package/dist/core/runner/runtask.js

@@ -47,6 +47,7 @@ import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.j
 import { cloneObserverInput, formatHookFeedback, hookSeatExpiredError, MAX_HOOK_TIMEOUT_MS, mintHookInvocationIdentity, resolveHookTimeoutMs, runHookSeat } from "../hooks.js";
 import { buildHumanInputEvent, frameMidTurnUserInput, projectHumanInput } from "../human-input-projection.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY, sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
+import { droppedToolDigest, withAnnounceDigests } from "./prepare-announce-once.js";
 import { appendInterruptionMarker, reconcileInterruptedSession } from "../session-reconcile.js";
 import { RunnerSharedToolResultStore } from "../tool-result-store.js";
 import { formatDiagnosticsBlock } from "../lsp-diagnostics.js";
@@ -146,7 +147,7 @@ function resumeDecisionWasNegative(resume) {
 }
 const DEFERRED_REISSUE = "[DEFERRED] This tool call shared a batch with a call that suspended for durable approval, so it was " +
     "NOT executed on resume. If you still need it, issue it again now.";
-function toolEndBodyFrom(result, isError, settledBy, approver, resolution, gatedCallIdOfRun) {
+function toolEndBodyFrom(result, isError, settledBy, approver, resolution, gatedCallIdOfRun, autoDenied) {
     const o = toolOutputFrom(result);
     const st = structuredFrom(result);
     const det = isError ? result?.details : undefined;
@@ -162,6 +163,7 @@ function toolEndBodyFrom(result, isError, settledBy, approver, resolution, gated
         ...(settledBy !== undefined ? { settledBy } : {}),
         ...(approver !== undefined ? { approver } : {}),
         ...(resolution !== undefined ? { resolution } : {}),
+        ...(autoDenied !== undefined ? { autoDenied } : {}),
     };
 }
 export function reconciledToolEndBody(orphan) {
@@ -381,6 +383,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
     let finalVerifySeenAtLastBoundary = 0;
     const onTurnBoundary = async (event) => {
         let boundarySteered = false;
+        const noNextRequest = () => prepared.stopRequestedRef.current || deps.loopLatch.userHalted;
         const walltimeHit = walltimeMonotonicDeadline !== undefined && performance.now() >= walltimeMonotonicDeadline;
         const preemptHit = spec.preemptSignal?.aborted === true;
         if (preemptHit && !prepared.suspendForResource && !rs.counters.preemptIgnoredReported) {
@@ -565,6 +568,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
             rs.attach.attachState !== undefined) &&
             !boundarySteered &&
             prepared.batchHaltRef.current === undefined &&
+            !noNextRequest() &&
             rs.counters.finalVerifyInjections === 0 &&
             !prepared.abortController.signal.aborted) {
             const due = [];
@@ -589,6 +593,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 const backgroundTasksOn = (rs.attach.attachmentsCfg?.backgroundTasks ?? eventDefaultOn("background_tasks")) === true;
                 const bgTasks = backgroundTasksOn && rs.attach.attachState.postCompactPending ? prepared.listBackgroundTasks() : undefined;
                 const toolsDeltaOn = rs.attach.attachmentsCfg?.toolsDelta === true;
+                let announcedOnceDirty = false;
                 const tdRef = toolsDeltaOn ? prepared.toolsDeltaRef : undefined;
                 const pendingTools = tdRef !== undefined && tdRef.pending.length > 0 ? [...tdRef.pending] : undefined;
                 const pendingRemovedTools = tdRef !== undefined && tdRef.pendingRemoved.length > 0 ? [...tdRef.pendingRemoved] : undefined;
@@ -694,8 +699,13 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                             ref.pendingRemoved.splice(0, pendingRemovedTools.length);
                         if (pendingReaddedTools !== undefined)
                             ref.pendingReadded.splice(0, pendingReaddedTools.length);
-                        if (pendingFailedMcp !== undefined)
+                        if (pendingFailedMcp !== undefined) {
                             ref.pendingFailed.splice(0, pendingFailedMcp.length);
+                            if (!noNextRequest()) {
+                                prepared.announcedListingsRef.mcpFailed = [...(prepared.announcedListingsRef.mcpFailed ?? []), ...pendingFailedMcp];
+                                announcedOnceDirty = true;
+                            }
+                        }
                     }
                 }
                 if ((mcpAdds !== undefined || mcpRemovals !== undefined) &&
@@ -708,6 +718,10 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 if (mcpDropped !== undefined &&
                     due.some((a) => a.source === "mcp_dropped_tools" && a.body === renderMcpDroppedTools(mcpDropped))) {
                     prepared.mcp.droppedTools.splice(0, mcpDropped.length);
+                    if (!noNextRequest()) {
+                        prepared.announcedListingsRef.advisories = withAnnounceDigests(prepared.announcedListingsRef.advisories, mcpDropped.map(droppedToolDigest));
+                        announcedOnceDirty = true;
+                    }
                 }
                 if (rs.attach.agentListingOn && prepared.agentListing !== undefined && due.some((a) => a.source === "agent_listing")) {
                     const listing = prepared.agentListing;
@@ -717,7 +731,8 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                         prepared.announcedListingsRef.agents = listing.entries.map((e) => e.name);
                         if (listing.models !== undefined)
                             prepared.announcedListingsRef.models = [...listing.models];
-                        await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+                        if (prepared.announcedSnapshotRecovered)
+                            await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
                     }
                 }
                 if (rs.attach.skillsListingOn && prepared.skillsListing !== undefined && due.some((a) => a.source === "skills_listing")) {
@@ -726,9 +741,12 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     if (intactBody !== undefined && due.some((a) => a.source === "skills_listing" && a.body === intactBody)) {
                         commitSkillsListing(rs.attach.attachState, listing.entries);
                         prepared.announcedListingsRef.skills = listing.entries.map((e) => e.name);
-                        await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+                        if (prepared.announcedSnapshotRecovered)
+                            await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
                     }
                 }
+                if (announcedOnceDirty && prepared.announcedSnapshotRecovered)
+                    await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
             }
             if (rs.attach.dateState !== undefined && rs.turn.lastTurnHadToolCalls) {
                 const today = prepared.dateChange.today();
@@ -1377,7 +1395,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
             toolName: event.toolName,
             ...(toolLabels.get(event.toolName) !== undefined ? { label: toolLabels.get(event.toolName) } : {}),
             isError: event.isError,
-            ...toolEndBodyFrom(event.result, event.isError, settlement?.settledBy, settlement?.approver, settlement?.resolution, prepared.abortController.signal.aborted ? gatedCallIdOf(prepared) : undefined),
+            ...toolEndBodyFrom(event.result, event.isError, settlement?.settledBy, settlement?.approver, settlement?.resolution, prepared.abortController.signal.aborted ? gatedCallIdOf(prepared) : undefined, settlement?.autoDenied),
             ...ident(),
         });
         announceWorkspaceMove();
@@ -3346,7 +3364,7 @@ export class Runner {
                 w.resolve(outcome);
         };
         const onTurnBoundary = makeTurnBoundary(prepared, stats, rs, {
-            spec, queue, manualCompactRef, todoToolMounted, taskToolsMounted,
+            spec, queue, loopLatch, manualCompactRef, todoToolMounted, taskToolsMounted,
             walltimeMonotonicDeadline,
             timeout, ident, postToolBatchHook, batchArgs, compactionBrain, withinTaskCompaction,
             compactionBreaker, windowSafetyOptions, rapidRefill, drainManualCompact,
@@ -3833,7 +3851,7 @@ export class Runner {
                         queue.push({ type: "steering_injected", source: f.source, preview: redactThenCut(f.body, 220), ...ident() });
                     }
                     rs.attach.attachmentsInjected += firstFrames.length;
-                    if (firstFrames.length > 0)
+                    if (firstFrames.length > 0 && prepared.announcedSnapshotRecovered)
                         await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
                     const enginePrefixChars = effectiveObjective.length - projectedObjective.length;
                     queue.push({
@@ -4719,8 +4737,8 @@ export class Runner {
             }
         }
         if ((preCasGateBit?.origin === "org_rule" || preCasGateBit?.origin === "org_unavailable") &&
-            this.deps.permissionRuleOrg === undefined) {
-            throw new CheckpointError("checkpoint.unsupported_version", `this checkpoint's approval was minted under organization governance (${preCasGateBit.origin}) and this worker has no org adjudication wiring (permissionRuleOrg) — a governed approval may only be redeemed where governance can be enforced; the checkpoint stays pending, resume it on an org-wired worker`, { reason: "governed_unwired" });
+            this.deps.permissionRuleStore?.partitions.org !== true) {
+            throw new CheckpointError("checkpoint.unsupported_version", `this checkpoint's approval was minted under organization governance (${preCasGateBit.origin}) and this worker has no org adjudication wiring (its permission-rule store carries no org partition) — a governed approval may only be redeemed where governance can be enforced; the checkpoint stays pending, resume it on an org-wired worker`, { reason: "governed_unwired" });
         }
         const retiredWalltimeTotal = cp.resourceLedger?.totalWalltimeSec;
         if (retiredWalltimeTotal !== undefined) {

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/sensitive-path-policy.d.ts

@@ -33,6 +33,22 @@ import type { ToolPolicy } from "./tool-policy.js";
  * hard refusal for every deployment that wires this list.
  */
 export declare const RECOMMENDED_SENSITIVE_PATTERNS: readonly string[];
+/**
+ * HRD-PRM-10 — the engine data root, read from the same knob its two consumers read
+ * (`$AGENT_DATA_DIR ?? ~/.ai-agent`, off the HOST at wiring time, NFC-normalized) and returned in
+ * EVERY spelling those consumers resolve it to. There are two, and they disagree for exactly two
+ * inputs (a leading `~`, and a relative value) — the transcript gate expands the tilde and leaves a
+ * relative value to the environment, the memory engine does neither and resolves against
+ * `process.cwd()`. Accepting only one caliber would exempt a directory nobody uses while the other
+ * consumer's real directory stayed guarded, which is the refusal this whole passthrough exists to
+ * remove. Every returned spelling is ANCHORED (see the loop) — that is not a detail.
+ *
+ * Exported as an ENGINE-INTERNAL seam (deliberately not re-exported from `src/index.ts`): the ask-side
+ * write-protection table carries the same passthrough law for the same reason, and a second reading of
+ * "where is the data root" is exactly how the two guards would come to disagree about which directory
+ * the engine owns. One resolver, two judges.
+ */
+export declare function dataRootSpellings(explicit: string | undefined): string[];
 /**
  * Build a composable policy that DENIES writes (via the guarded fs tools) whose canonical target
  * lands on a sensitive path. `patterns` are deployment-supplied (no default list is shipped — the