@sema-agent/core 5.32.0 → 5.34.0

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

@@ -0,0 +1,102 @@
+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";
+/**
+ * codex 1360 r2-r4 — 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-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`
+ * refusal and the lane that reports a failed restore.
+ */
+export declare function remoteEnvFailureNote(op: RemoteEnvFailureNote["op"], error: RemoteExecutionError, attempts: number): RemoteEnvFailureNote;
+/**
+ * RB-439-a — `resumeVM` with a bounded retry on the TRANSIENT codes, plus the attempt count for the
+ * caller-facing note.
+ *
+ * Why this op and no other: `resumeVM` is the one lifecycle call the seam documents as "idempotent +
+ * re-entrant" (a replica that crashed mid-suspend can be superseded by another resuming the SAME
+ * snapshot), which is exactly `withRetry`'s red line — retry idempotent establishment, never a
+ * side-effecting op. `suspendVM` TAKES a snapshot and `postResumeInit` re-injects secrets under an
+ * ordering red line; neither is retried here, they are disclosed with `retryable` instead so the caller
+ * decides. A code outside the retryable family (`unsupported`, `auth_failed`) returns on the first
+ * attempt — `withRetry` will not spend a second call on a permanent refusal.
+ */
+export declare function restoreWorkspaceWithRetry(env: RemoteExecutionEnv, snapshotId: SnapshotId, options: VmLifecycleOptions): 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`,
+     *  `postResumeInit`, `canonicalPath`) but NEVER rebinds or destroys it — the detach guard and the
+     *  prepare-throw catch are the exception-path owners, both in the driver, and their reference
+     *  must stay authoritative (a phase-local rebind could never reach them). */
+    ownedEnv: ExecutionEnv | undefined;
+    /** borrowed-readonly — the two deployment seats this phase reads, as a Pick over the SAME `deps`
+     *  object (相 API 规则件 R-4: receiver preserved for `deps.onError?.()`; a new deps read must
+     *  widen this Pick). `executionEnv` feeds only the observation sink's remote predicate. */
+    deps: Pick<RunnerDeps, "onError" | "executionEnv">;
+    /** borrowed-readonly — `signal` only: the caller's cancel signal, composed into the restore's
+     *  abortSignal so a cancel DURING the restore short-circuits it (the live listener is attached
+     *  only after the harness exists). */
+    spec: Pick<TaskSpec, "signal">;
+    /** borrowed-readonly — the trusted spawn-side seats the observation sink reads: the sink itself
+     *  and the isolation REQUEST (by this point past the driver's fail-closed enforcement, so
+     *  `isolated: true` is a receipt, not a restatement). */
+    internals: Pick<RunInternals, "onWorkspaceResolved" | "isolation"> | undefined;
+    /** borrowed-readonly — the durable-resume seats this phase reads: the checkpointed
+     *  `workspaceHandle` (restore target) and `executesApprovedAction` (the divergence fail-closed
+     *  key — codex 1360 r6). Absent for a fresh/non-durable run: the phase is then root-passthrough. */
+    resume: Pick<PrepareResume, "workspaceHandle" | "executesApprovedAction"> | undefined;
+    /** owned (value) — the pre-restore task root (isolation-aware initial derivation, computed in the
+     *  driver). Dead after this call by design (R-5): later phases read the returned
+     *  `taskRootFinal`, never this spelling. */
+    taskRootInitial: string;
+    /** borrowed-readonly — prepare's abort seat; only `.signal` is read (kept as the object so the
+     *  moved body's `abortController.signal` spelling stays verbatim). */
+    abortController: {
+        readonly signal: AbortSignal;
+    };
+    /** borrowed-readonly — the acquired session's id, for the observation arms' error tags. */
+    sessionId: string;
+}
+/** The phase's outputs (相 API 规则件 four-class form). */
+export interface PrepareWorkspaceRestoreResult {
+    /** owned — the SETTLED task root (T6 FINAL semantics): the initial derivation, else the park-only
+     *  handle's mountPath, else resumeVM's restored mountPath — settled before the observation sink
+     *  fired. Bound to a NEW name by design (R-5): `taskRootPath` must not be re-spelled by later
+     *  phases, so a consumer moved ahead of this call is a lexical error. */
+    taskRootFinal: string;
+    /** owned (pure function; closes over the phase-armed rebase state) — migrates one checkpointed
+     *  absolute path from the OLD workspace root onto the restored one (RB-439-c: any accepted
+     *  spelling of the old root); the identity function when no divergence was armed. Consumers (T7):
+     *  the readFileState checkpoint seed, the handsCwd seed, the activeWorktree restore. */
+    rebaseRestoredPath: (p: string) => string;
+}
+/** The B-4 phase body — the workspace-restore slice, verbatim (see the module header for the contract). */
+export declare function prepareWorkspaceRestore(input: PrepareWorkspaceRestoreInput): Promise<PrepareWorkspaceRestoreResult>;

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

@@ -0,0 +1,144 @@
+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}`;
+}
+export function remoteEnvFailureNote(op, error, attempts) {
+    return { op, code: error.code, retryable: isRetryableRemoteErrorCode(error.code), attempts, message: error.message };
+}
+const REMOTE_RESTORE_MAX_ATTEMPTS = 2;
+const REMOTE_RESTORE_BACKOFF_MS = 200;
+export async function restoreWorkspaceWithRetry(env, snapshotId, options) {
+    let attempts = 0;
+    const outcome = await withRetry(async (attempt) => {
+        attempts = attempt;
+        return env.resumeVM(snapshotId, options);
+    }, { 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;
+    let restoredRootRebase;
+    const rebaseRestoredPath = (p) => restoredRootRebase === undefined ? p : rebaseWorkspacePathAcross(p, restoredRootRebase.from, restoredRootRebase.to);
+    if (resume?.workspaceHandle !== undefined) {
+        const failResume = (message, cause, note) => {
+            const e = new Error(message, cause ? { cause } : undefined);
+            e.code = "resume.env_failed";
+            if (note !== undefined)
+                e.remoteEnvFailure = note;
+            throw e;
+        };
+        const handle = resume.workspaceHandle;
+        if (ownedEnv === undefined || !isRemoteExecutionEnv(ownedEnv)) {
+            failResume("resume needs a RemoteExecutionEnv from executionEnvFactory to restore the workspace snapshot");
+        }
+        else if (handle.snapshotId === undefined) {
+            if (handle.restoreMode !== "park_only" && ownedEnv.capabilities.suspendable) {
+                failResume("checkpoint workspaceHandle has no snapshotId and is not a park_only handle, but the resumed env is suspendable — refusing to resume on a possibly-unrestored workspace (corrupt checkpoint?)");
+            }
+            if (handle.mountPath && handle.mountPath !== taskRootPath) {
+                taskRootPath = handle.mountPath;
+            }
+        }
+        else {
+            const restoreSignal = spec.signal
+                ? AbortSignal.any([abortController.signal, spec.signal])
+                : abortController.signal;
+            const missingHere = missingRestoreSurface(ownedEnv);
+            if (missingHere.length > 0) {
+                failResume(`the resumed execution env cannot restore a workspace snapshot: its adapter does not implement ${missingHere.join(" or ")}. The checkpoint holds snapshot "${handle.snapshotId}" — wire an adapter that implements the full RemoteExecutionEnv restore surface and re-resume.`);
+            }
+            const { outcome: restored, attempts: restoreAttempts } = await restoreWorkspaceWithRetry(ownedEnv, handle.snapshotId, {
+                abortSignal: restoreSignal,
+                priorHandle: handle,
+            });
+            if (!restored.ok) {
+                failResume(`resumeVM failed after ${restoreAttempts} attempt(s) (${restored.error.code}): ${restored.error.message}`, restored.error, remoteEnvFailureNote("resumeVM", restored.error, restoreAttempts));
+            }
+            else {
+                const restoredEnv = ownedEnv;
+                const canonicalInEnv = async (p) => {
+                    try {
+                        const r = await restoredEnv.canonicalPath(p, restoreSignal);
+                        return r.ok ? r.value : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                };
+                let checkpointedCanonical;
+                let sameRootUnderAlias = false;
+                if (restored.value.mountPath !== handle.mountPath) {
+                    checkpointedCanonical = await canonicalInEnv(handle.mountPath);
+                    const restoredCanonical = await canonicalInEnv(restored.value.mountPath);
+                    sameRootUnderAlias =
+                        checkpointedCanonical !== undefined && restoredCanonical !== undefined && checkpointedCanonical === restoredCanonical;
+                }
+                if (restored.value.mountPath !== handle.mountPath && !sameRootUnderAlias) {
+                    if (resume.executesApprovedAction === true) {
+                        failResume(`resumeVM workspace-root divergence with a pending approved action: checkpointed mountPath "${handle.mountPath}" but the restored handle reports "${restored.value.mountPath}" — the approved args are bound to the checkpointed root; refusing to execute them against a moved workspace (adapter should honor priorHandle)`);
+                    }
+                    try {
+                        deps.onError?.(new Error(`resumeVM workspace-root divergence: checkpointed mountPath "${handle.mountPath}" but the restored handle reports "${restored.value.mountPath}" — the resumed task follows the restored root`), { phase: "config", sessionId });
+                    }
+                    catch {
+                    }
+                }
+                if (restored.value.mountPath && restored.value.mountPath !== taskRootPath) {
+                    taskRootPath = restored.value.mountPath;
+                }
+                if (restored.value.mountPath && restored.value.mountPath !== handle.mountPath && !sameRootUnderAlias) {
+                    const from = checkpointedCanonical !== undefined && checkpointedCanonical !== handle.mountPath
+                        ? [handle.mountPath, checkpointedCanonical]
+                        : [handle.mountPath];
+                    restoredRootRebase = { from, to: restored.value.mountPath };
+                    try {
+                        deps.onError?.(new Error(from.length > 1
+                            ? `resumeVM workspace-root rebase accepts both spellings of the checkpointed root (${from.map((f) => `"${f}"`).join(" and ")}) when migrating persisted paths to "${restored.value.mountPath}"`
+                            : `resumeVM workspace-root rebase is spelling-exact: it matches the checkpointed root "${handle.mountPath}" only, so persisted paths recorded under an equivalent alias of it are NOT migrated to "${restored.value.mountPath}" and stay as written`), { phase: "config", sessionId });
+                    }
+                    catch {
+                    }
+                }
+            }
+            const init = await ownedEnv.postResumeInit();
+            if (!init.ok) {
+                failResume(`postResumeInit failed (${init.error.code}): ${init.error.message}`, init.error, remoteEnvFailureNote("postResumeInit", init.error, 1));
+            }
+        }
+    }
+    if (internals?.onWorkspaceResolved !== undefined) {
+        try {
+            const workspaceEnv = ownedEnv ?? deps.executionEnv;
+            internals.onWorkspaceResolved({
+                cwd: taskRootPath,
+                isolated: internals.isolation === "worktree",
+                remote: workspaceEnv !== undefined &&
+                    (isRemoteExecutionEnv(workspaceEnv) || workspaceEnv.hostLocalPaths === false),
+            });
+        }
+        catch {
+        }
+    }
+    return { taskRootFinal: taskRootPath, rebaseRestoredPath };
+}

package/dist/core/runner/runtask.js

@@ -1,4 +1,5 @@
 import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
+import { createSafeNotifier, observeThenableRejection } from "../safe-notify.js";
 import { AgentHarness, DEFAULT_COMPACTION_SETTINGS, uuidv7 } from "../../internal/harness.js";
 import { snapshotActorAssertion } from "../../internal/llm.js";
 import { CheckpointError, BINDING_CHECKPOINT_VERSION, checkpointVersionOf, F012_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, remainingBudgetMicroUsd, readPendingSteerQueue, remainingTokens, validatePendingSteer, winnerFromOutcome, } from "../checkpoint-store.js";
@@ -989,6 +990,9 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
 }
 function makeHarnessHandlers(prepared, stats, rs, deps) {
     const { spec, queue, internals, ident, parentToolCallId, subagentName, pushContent, emitCommitted, startedToolCallIds, toolStartAt, writeFamilyOf, toolLabels, postToolBatchHook, batchArgs } = deps;
+    const internalsNotifier = createSafeNotifier({
+        onError: (f) => console.warn(`[sema-core] ${f.site}: run-internals activity sink threw (contained; further failures counted, not re-disclosed): ${f.error.message}`),
+    });
     let lastWorkspaceCwd = prepared.cwdRef?.current;
     const announceWorkspaceMove = () => {
         const cwdNow = prepared.cwdRef?.current;
@@ -1150,7 +1154,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                 rs.counters.groundingSignalPostR9 = true;
         }
         const activityArg = primaryActivityArg(event.args);
-        internals?.onActivity?.({ phase: "start", toolCallId: event.toolCallId, toolName: event.toolName, at: startAt, ...(activityArg !== undefined ? { arg: activityArg } : {}) });
+        internalsNotifier.notify(() => observeThenableRejection(internals?.onActivity?.({ phase: "start", toolCallId: event.toolCallId, toolName: event.toolName, at: startAt, ...(activityArg !== undefined ? { arg: activityArg } : {}) }), internalsNotifier, "runtask.onActivity.start"), "runtask.onActivity.start");
         pushContent({
             type: "tool_start",
             toolCallId: event.toolCallId,
@@ -1199,7 +1203,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
             ok: !event.isError,
             ts: toolNow,
         }));
-        internals?.onActivity?.({ phase: "end", toolCallId: event.toolCallId, toolName: event.toolName, isError: event.isError, at: toolNow });
+        internalsNotifier.notify(() => observeThenableRejection(internals?.onActivity?.({ phase: "end", toolCallId: event.toolCallId, toolName: event.toolName, isError: event.isError, at: toolNow }), internalsNotifier, "runtask.onActivity.end"), "runtask.onActivity.end");
         if (prepared.lspDiagnostics && !event.isError) {
             const name = event.toolName;
             if (name === "Edit" || name === "Write" || name === "NotebookEdit") {
@@ -2325,8 +2329,11 @@ export class Runner {
             queue.push({ type: "message_committed", entryId, role, ...(toolCallId !== undefined ? { toolCallId } : {}), ...ident() });
         };
         const subagentName = parentToolCallId !== undefined && internals?.agentName !== undefined ? inlineUntrusted(internals.agentName.slice(0, 320), 80) : undefined;
+        const statusSinkNotifier = createSafeNotifier({
+            onError: (f) => console.warn(`[sema-core] ${f.site}: run-internals status sink threw (contained; further failures counted, not re-disclosed): ${f.error.message}`),
+        });
         const statusEmit = (s) => {
-            queue.push({
+            const frame = {
                 type: "status",
                 phase: s.phase,
                 ...(s.detail !== undefined ? { detail: s.detail } : {}),
@@ -2336,7 +2343,12 @@ export class Runner {
                 ...(s.maxRetries !== undefined ? { maxRetries: s.maxRetries } : {}),
                 ...(s.errClass !== undefined ? { errClass: s.errClass } : {}),
                 ...ident(),
-            });
+            };
+            Object.freeze(frame);
+            const accepted = queue.push(frame);
+            if (accepted && internals?.onStatusEvent !== undefined) {
+                statusSinkNotifier.notify(() => observeThenableRejection(internals.onStatusEvent?.(frame), statusSinkNotifier, "runtask.onStatusEvent"), "runtask.onStatusEvent");
+            }
         };
         const telemetryEmit = (t) => {
             emitTrace(rs.telemetry.tracer, () => t.kind === "failover"
@@ -3114,6 +3126,8 @@ export class Runner {
                 rewindNotes: prepared.rewindNotes,
                 strandedHumanAnswers,
                 remoteEnvFailures: prepared.remoteEnvFailures,
+                effectiveReadFace: prepared.effectiveReadFace,
+                effectiveReadDenyPatterns: prepared.effectiveReadDenyPatterns,
                 retryAfterMs: rs.limits.platformTerminal?.retryAfterMs,
                 abortedForTimeout: timeout.fired,
                 abortedForTurns: rs.limits.turnsExceeded,

package/dist/core/safe-notify.d.ts

@@ -79,3 +79,12 @@ export interface SafeNotifier {
  * notifier whose callbacks never throw costs one object and nothing per call beyond the `try`.
  */
 export declare function createSafeNotifier(opts?: SafeNotifierOptions): SafeNotifier;
+/**
+ * Observe a `=> void` host callback's RETURN value for the async dialect: TypeScript accepts an
+ * `async` function at a void seat, and a rejected one would escape {@link SafeNotifier.notify}
+ * (which deliberately ignores return values — see the scope note above) as an unhandled rejection.
+ * Call this with the callback's return value INSIDE the notify thunk: a thenable's rejection is
+ * routed back through the same notifier/site, so async and sync failures share one count and one
+ * bounded disclosure, and neither can fault the engine's control flow.
+ */
+export declare function observeThenableRejection(r: unknown, notifier: SafeNotifier, site: string): void;

package/dist/core/safe-notify.js

@@ -57,3 +57,12 @@ export function createSafeNotifier(opts) {
         },
     };
 }
+export function observeThenableRejection(r, notifier, site) {
+    if (typeof r?.then === "function") {
+        r.then(undefined, (err) => {
+            notifier.notify(() => {
+                throw err instanceof Error ? err : new Error(String(err));
+            }, site);
+        });
+    }
+}

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

@@ -175,6 +175,17 @@ export type PermissionResult = {
      *  consumer (approval card, wire frame) can tell the person their rule is alive, just outranked.
      *  Absent ⇒ no rule matched, or the ask was cleared normally. */
     persistedRuleShadowed?: string;
+    /** backlog #239 disclosure (additive): WHY the reversibility probe did not clear this call, in the
+     *  probe's own words. ENGINE-STAMPED at the irreversibility tighten (which constructs this decision
+     *  wholesale), already neutralized + capped there; a `"maybe"` tier whose probe supplied no cause,
+     *  and the `"always"` tier (which runs no probe), leave it absent. Same DISPLAY-ONLY posture as
+     *  {@link persistedRuleShadowed}: a policy that self-declares it can only put its own prose on its
+     *  own card — nothing reads this member to decide anything, so it is not an authority channel. */
+    probeReason?: string;
+    /** backlog #239 disclosure (additive): the STRUCTURED cause, for a probe whose verdict this engine
+     *  understands (see {@link import("./checkpoint-store.js").ProbeCause}). Engine-stamped and
+     *  validated at the irreversibility tighten; same display-only posture as the prose sibling. */
+    probeCause?: import("./checkpoint-store.js").ProbeCause;
     /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules`
      *  shape); carries the matched rule's text. Present ⇔ a rule someone WROTE says "ask about this",
      *  never for a `defaultAction:"ask"` fallback (an unmatched call is default-closed posture, not a
@@ -657,6 +668,20 @@ export interface AskRequest {
      *  {@link PermissionResult}'s ask arm). The matched rule text, so the approval card renders "your
      *  rule is alive, just outranked" instead of leaving the person to regex the message prose. */
     persistedRuleShadowed?: string;
+    /** backlog #239: WHY the reversibility probe did not clear this call — the account of the tighten the
+     *  card was showing WITHOUT until now (the gate knew the cause and dropped it at this seam, leaving the
+     *  approver the action but not the reason it is being asked about). Present only for a `"maybe"`-tier
+     *  tighten whose probe supplied a cause; the durable park route carries the same string as
+     *  `RiskDescriptor.probeReason`. Neutralized + length-capped by the gate. UNTRUSTED-for-display,
+     *  never adjudication input. */
+    readonly probeReason?: string;
+    /** backlog #239: the STRUCTURED cause behind the tighten — a machine-readable code plus the operand
+     *  families as arrays with honest totals, so this surface renders its OWN sentence rather than one the
+     *  engine had to write before the check's edge cases were known. See
+     *  {@link import("./checkpoint-store.js").ProbeCause}, whose contract is that the ARRAY is the
+     *  structure: render the entries as data, never re-derive structure by splitting or joining them.
+     *  The durable park route carries the same value as `RiskDescriptor.probeCause`. */
+    readonly probeCause?: import("./checkpoint-store.js").ProbeCause;
     toolCallId: string;
     /** The (post-rewrite) args the tool would run with. */
     args: unknown;

package/dist/core/types.d.ts

@@ -87,6 +87,25 @@ export type ToolEffect = "read" | "write" | "idempotent";
 /** design/178 §3 — the content-origin classes (see {@link ToolSpec.contentOrigin}). */
 export type ToolContentOrigin = "external" | "execution" | "local";
 /** A native tool the model can call. `parameters` is a typebox schema; `execute` does the work. */
+/**
+ * design/77 §4 — what a {@link ToolSpec.reversibilityProbe} returns for ONE call.
+ *
+ * `reversible` alone decides: the gate tightens a surviving `allow` to `ask` unless it is exactly `true`,
+ * and neither optional member can widen that. They exist so the resulting approval card can say WHY, a
+ * thing the probe knows at the moment it decides and nothing downstream can re-derive.
+ *
+ * Supply `cause` when the reason has parts a consumer should render itself; `reason` when it is prose
+ * this engine cannot interpret. Both are optional and independent, so a probe written against the
+ * original bare `{ reversible }` shape remains valid.
+ */
+export interface ReversibilityVerdict {
+    reversible: boolean;
+    /** Free-text account, neutralized and length-capped by the gate before it reaches any card. */
+    reason?: string;
+    /** Structured account — see {@link import("./checkpoint-store.js").ProbeCause}. Validated by the gate;
+     *  a malformed value costs the DISCLOSURE only, never the ask. */
+    cause?: import("./checkpoint-store.js").ProbeCause;
+}
 export interface ToolSpec<TParams extends TSchema = TSchema> {
     /**
      * Model-facing tool name. MUST NOT contain `__` — that separator is reserved by the PROTOCOL TABLE
@@ -254,12 +273,37 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * approval timeout) and **fail-closed**: a non-`reversible` verdict, a timeout, or a throw all tighten to
      * `ask`. Declaring this probe defaults `irreversibility` to `"maybe"`. It is read from the spec at
      * prepare-time and captured in a closure — NOT a tool argument — so the model cannot monkey-patch it.
+     *
+     * **`reason` (optional, additive both ways)** — WHY this call was not proven reversible, in the probe's
+     * own words, minted in the same pass that reached the verdict (so nothing downstream re-derives it).
+     * Read ONLY on a tightening verdict: a `reversible: true` return ends the gate, and a timeout/throw
+     * produces no verdict at all, so the cause travels exactly when there is an approval card to put it on.
+     * The gate neutralizes and length-caps it, then carries it to both approval routes — the synchronous
+     * `AskRequest.probeReason` and the durable park's `RiskDescriptor.probeReason`. Compatible in BOTH
+     * directions by construction: a probe written against the older bare `{ reversible }` shape stays
+     * type-correct and simply supplies no cause, and an engine that does not know the member ignores it.
+     *
+     * **`cause` (optional)** — the STRUCTURED alternative, for a probe whose verdict is machine-describable:
+     * a `code` plus operand families as arrays with honest totals ({@link ProbeCause}), carried to
+     * `AskRequest.probeCause` / `RiskDescriptor.probeCause`. Prefer it wherever the cause has parts. Prose
+     * has to be written before the edge cases are known — a sentence about what a command DOES is false
+     * wherever the check over-fires, and a multi-part disclosure flattened into one capped string loses
+     * whichever part sorts last — whereas a code cannot be false and an array cannot be truncated into a
+     * lie. `reason` remains for deployments whose cause is genuinely just prose this engine cannot read.
+     * Both may be supplied; each is validated and carried independently.
+     *
+     * TRUST: the text is DEPLOYMENT-authored (and, for the built-in shell probe, derived from the model's
+     * own command), so it is DISPLAY/TRIAGE metadata only — never adjudication input, and never a channel
+     * that can widen a verdict. A probe cannot use it to auto-allow: `reversible` alone decides.
+     *
+     * That property is STRUCTURAL, and keeping it so constrains where the cause may be written. It is
+     * carried as a member and deliberately NOT folded into the ask's `message`, because the message is
+     * what an auto-mode classifier is handed as its `askMessage` — and that classifier may answer an ask
+     * with `allow`. Text on the prose channel is therefore steering input to a decider that can clear the
+     * very ask the probe raised, which is exactly the authority a probe must not have. Anything added
+     * later that renders this cause must keep it on display surfaces only.
      */
-    reversibilityProbe?: (args: unknown) => {
-        reversible: boolean;
-    } | Promise<{
-        reversible: boolean;
-    }>;
+    reversibilityProbe?: (args: unknown) => ReversibilityVerdict | Promise<ReversibilityVerdict>;
     /**
      * design/178 §3 — CONTENT-ORIGIN class of what this tool can bring into the session, a fourth axis
      * orthogonal to {@link effect} (repeat-safety), {@link egress} (blast-radius) and
@@ -2128,10 +2172,13 @@ export interface TaskSpec {
      * design/199 件B — TASK-layer ADDITIONS to the built-in sensitive-path READ deny set
      * ({@link import("../tools/fs/read-deny.js").READ_FACE_DEFAULT_DENY_ENTRIES}). Judged by the
      * structured read faces (Read/Grep/Glob/RepoMap, their traversals, the classify shell gate's
-     * auto-allow probe and the compaction attachment reader) in BOTH containment modes. Add-only
-     * everywhere (D-4 zero-shrink ruling): entries here UNION with the built-ins and the deployment's
-     * {@link RunnerDeps.readDenyPatterns}; `[]` ≡ absent (union identity); nothing can remove a
-     * built-in. Bad entry shapes refuse loudly at prepare (#123). The write faces are untouched.
+     * auto-allow probe and the compaction attachment reader) in BOTH containment modes. Add-only at
+     * the task layer: entries here UNION with the active built-ins and the deployment's
+     * {@link RunnerDeps.readDenyPatterns}; `[]` ≡ absent (union identity); NOTHING at the task layer
+     * can remove a built-in — the one removal channel is the DEPLOYMENT's built-in configuration
+     * ({@link RunnerDeps.readDenyBuiltinTiers} / {@link RunnerDeps.readDenyBuiltinExclude}, #245
+     * revision of D-4), which no TaskSpec key reaches. Bad entry shapes refuse loudly at prepare
+     * (#123). The write faces are untouched.
      */
     readDenyPatterns?: readonly import("../tools/fs/read-deny.js").ReadDenyEntry[];
     /**
@@ -2877,6 +2924,54 @@ export interface TaskResult {
         deliveryId: string;
         toolCallId: string;
     }>;
+    /**
+     * #240 (design/199 v1.1) — the READ-face this leg's read surfaces actually judged under, as an
+     * engine-filled OBSERVATION (never a knob: writing it on a spec does nothing). It is the run's ONE
+     * resolved face — the same value the hands toolkit enforced and the delegation carriers rode — with
+     * the hands-less resume pin folded in (a row resumed on a hands-less worker still reports the
+     * checkpoint-frozen `"roots"`).
+     *
+     * **In-presence condition (#242 widened):** present on every leg that completes prepare — hands
+     * mounted (any run with the built-in fs band) AND every hands-less leg (resume legs fold the
+     * checkpoint seed stricter-wins; non-resume legs report the live resolution). Absent only on
+     * prepare-failure terminals (nothing ran). Consumers that keyed on absence = "no posture" must
+     * re-key: absence now means only "prepare never completed". Rides every OTHER terminal, not just
+     * `completed` — the posture is a fact about the leg that ran, whatever ended it.
+     *
+     * Purpose: a POST-COMPLETION follow-on leg spawned OUTSIDE the delegation tree (the verify gate's
+     * verifier and fix legs are the canonical case) cannot see the checkpoint fold the completed leg ran
+     * under — its spawner holds only the resume-side config, which never contained the frozen posture.
+     * Folding this seat into the follow-on spec (stricter-wins: only `"roots"` ever tightens; an
+     * `"open"` observation is never forwarded) closes that escape for ANY follow-on, not just the
+     * verifier. See {@link effectiveReadDenyPatterns} for the deny-set half.
+     */
+    effectiveReadFace?: import("../tools/fs/read-face.js").ReadFace;
+    /**
+     * #240 (design/199 v1.1) — the sensitive-path deny ADDITIONS in force on this leg beyond the
+     * built-in table, normalized (deployment ∪ task ∪ checkpoint-frozen seed), as an engine-filled
+     * OBSERVATION. "In force" = judged by this leg's own read surfaces where they mounted, and carried
+     * to its delegation subtree either way (a hands-less resume leg reports the entries its children
+     * judge under).
+     * This seat is the only place a checkpoint-FROZEN deny entry becomes visible after the resumed leg
+     * completes: the resume-side caller's own config never contained it. A follow-on leg's spawner
+     * unions these into the child's `readDenyPatterns` (add-only; the child's compile folds exact
+     * duplicates, so re-supplying deployment-shared entries is idempotent) — that is how the frozen
+     * posture rides every leg that continues this work, not just the delegation subtree.
+     *
+     * **In-presence condition:** present iff non-empty. Built-in entries are never listed (they are in
+     * force on every run and re-compile locally). Same terminal coverage as
+     * {@link effectiveReadFace}: rides any terminal of a leg that ran; absent on prepare failures.
+     *
+     * On a DURABLE-PAUSE hand-back these seats are additionally the RE-SUPPLY hint: a checkpoint
+     * minted by a leg with no face resolution (a hands-less non-resume continuation) carries no
+     * frozen face section of its own, so a caller resuming that token must fold these entries back
+     * into the resume-side config (`readDenyPatterns` / `readFace: "roots"`). The resumed leg unions
+     * them into its own judgment and delegation carriers; the union is NOT serialized into any
+     * further checkpoint that leg may mint (a hands-less RESUME mint re-freezes only its original seed; a non-resume hands-less pause mints its live-resolved posture, #242), so
+     * fold them on EVERY resume — the standing resume contract. The seats describe the posture
+     * governing the WORK, never the contents of any checkpoint row.
+     */
+    effectiveReadDenyPatterns?: readonly import("../tools/fs/read-deny.js").NormalizedReadDenyEntry[];
     /**
      * `turns`/`tokens`/`costMicroUsd` are this task's OWN model usage. `nested` is the summed usage of any
      * delegated sub-runs (sub-agents) it spawned — present only when it delegated. The true total
@@ -4239,7 +4334,13 @@ export interface EngineNotice {
      *    deps and `runTask` builds a Runner per call), unwired console arm once per process;
      *    a library-direct `createHandsToolkit` mount announces at toolkit creation (one per mount,
      *    through the band-local `HandsToolkitOptions.onNotice` seat, absent ⇒ `console.warn`);
-     *    `detail: { seat, declared, inForce, cause }`. */
+     *    `detail: { seat, declared, inForce, cause }`.
+     *
+     *  Deliberately NOT a notice family: brain retry/reconnect liveness (a rate limit, a 5xx, a
+     *  transient network failure being retried). Those are per-attempt liveness frames with their own
+     *  frequency semantics and ride the wire `status` channel ({@link BrainStatus}), whose sink the
+     *  Runner establishes unconditionally around every brain-driving call — no host seat to wire, no
+     *  console fallback to flood. A reader looking for retry disclosure should look there, not here. */
     code: string;
     /** The exact human-readable line the unwired build prints via `console.warn` — same words, one text. */
     message: string;
@@ -4320,11 +4421,37 @@ export interface RunnerDeps {
     /**
      * design/199 件B — DEPLOYMENT-layer ADDITIONS to the built-in sensitive-path READ deny set
      * ({@link import("../tools/fs/read-deny.js").READ_FACE_DEFAULT_DENY_ENTRIES}); see
-     * {@link TaskSpec.readDenyPatterns} for the judged surfaces. Add-only (D-4 zero-shrink ruling):
-     * unions with the built-ins and any task-layer additions; there is no whole-table replacement
-     * escape hatch, and `[]` ≡ absent. Bad entry shapes refuse loudly at prepare (#123).
+     * {@link TaskSpec.readDenyPatterns} for the judged surfaces. Add-only on THIS seat: unions with
+     * the active built-ins and any task-layer additions, and `[]` ≡ absent — narrowing the built-in
+     * set is the sibling knobs' job ({@link readDenyBuiltinTiers} / {@link readDenyBuiltinExclude},
+     * #245 revision of D-4), not a replacement escape hatch here. Bad entry shapes refuse loudly at
+     * prepare (#123).
      */
     readDenyPatterns?: readonly import("../tools/fs/read-deny.js").ReadDenyEntry[];
+    /**
+     * #245 (revises the D-4 zero-shrink ruling) — the deployment's built-in deny-table TIER selection:
+     * EXACTLY the listed tiers of
+     * {@link import("../tools/fs/read-deny.js").READ_FACE_BUILTIN_DENY_TABLE} are active (`[]` = none —
+     * explicit and legal); absent = the default selection
+     * ({@link import("../tools/fs/read-deny.js").READ_DENY_DEFAULT_TIERS}: every tier except
+     * `shell-history`, which is unrestricted by default). Composes with
+     * {@link readDenyBuiltinExclude} (tiers first, then row removal); never touches the additions
+     * seats or the write faces. Unknown tier names refuse loudly at prepare (#123). DEPLOYMENT seat
+     * ONLY: deliberately not a TaskSpec key and not in the governed workflow whitelist — a task or
+     * governed script can only ADD deny entries, never widen the built-in face below its deployment.
+     * Not frozen into checkpoints: the checkpoint face section persists ADDITIONS only, so a resumed
+     * row's built-in face follows the CURRENT deployment configuration (the operator's live
+     * authority), while frozen additions stay stricter-wins.
+     */
+    readDenyBuiltinTiers?: readonly string[];
+    /**
+     * #245 — per-row removal from the built-in deny table by STABLE NAME (= the row's canonical
+     * pattern text, e.g. `".ssh"`, `".config/gcloud"`; the admin delete channel), applied after
+     * {@link readDenyBuiltinTiers} selection. Naming a row of an inactive tier is a satisfied intent
+     * (no-op); a name matching NO table row refuses loudly at prepare (#123 — never silently
+     * ignored). Same deployment-only seat, clamp argument and checkpoint posture as the tiers key.
+     */
+    readDenyBuiltinExclude?: readonly string[];
     /**
      * design/199 件A — the DEPLOYMENT's read-face declaration
      * ({@link import("../tools/fs/read-face.js").ReadFace}; see {@link TaskSpec.readFace} for the

package/dist/index.d.ts

@@ -7,6 +7,7 @@
  */
 export { Runner, runTask } from "./core/runner/runtask.js";
 export { resolveTaskLimits } from "./core/runner/prepare-task.js";
+export type { RunInternals, ResolvedWorkspace } from "./core/runner/prepare-task.js";
 export type { BudgetAxis } from "./core/runner/assemble-result.js";
 export { SESSION_LOG_DIGEST_SCHEME, sessionEntryDigest, sessionLogDigest, sessionLogDigestsComparable, } from "./engine/session/log-digest.js";
 export type { ResumeTaskConfig } from "./core/runner/runtask.js";
@@ -87,10 +88,10 @@ export type { InvariantKind, FunctionContract, Invariant, InvariantViolation, Ch
 export { HAND_TOOL_EFFECTS, bashReversibilityProbe, BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName, classifyCompoundReadonly, MAX_EDIT_BYTES } from "./tools/fs/index.js";
 export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, type BashReadonlyRootBoundary, type CompoundReadonlyVerdict, } from "./tools/fs/index.js";
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
-export { READ_FACE_DEFAULT_DENY_ENTRIES, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, } from "./tools/fs/index.js";
+export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
 export { deploymentReadFaceClampNotice, resolveReadFace, type ReadFace, type ReadFaceInputs } from "./tools/fs/index.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
-export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
+export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type ProbeCause, type ProbeCauseOperands, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";
@@ -252,7 +253,7 @@ export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, EngineNotice, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, EngineNotice, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";