@sema-agent/core 7.39.1 → 7.40.0

package/dist/core/permission-rules.js

@@ -1,7 +1,7 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
-import { PATH_RULE_BASE_LABEL, READ_RULE_TOOL, isUsablePathBase, parseRuleText, pathRuleHeadOf, pathRuleReachOf, programRunReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
+import { PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, parseRuleText, pathRuleHeadOf, pathRuleReachOf, programRunReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
 import { pathFamilyOf, pathIdentityOf, spellingOfIdentity } from "../tools/fs/safety.js";
 import { effectivePathTargetOf } from "./effective-path-target.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
@@ -82,7 +82,6 @@ export const fileToolParamVocabulary = (canonicalTool) => {
     const face = catalogRuleFaceOf(canonicalTool);
     return face?.params === undefined || pathTargetOf(canonicalTool) === undefined ? undefined : new Set(face.params);
 };
-export const PATH_DENY_RULE_FACES = Object.freeze({ [READ_RULE_TOOL]: ["read", "write"], Edit: ["write"] });
 export function pathRuleDenyRowOf(rule, bases) {
     const family = pathFamilyOf(bases);
     const tree = bases.root ?? bases.cwd;
@@ -99,10 +98,6 @@ export function pathRuleDenyRowOf(rule, bases) {
         ...(head !== undefined ? { head: spellingOfIdentity(head, family) } : {}),
     };
 }
-function callPathFaceOf(req) {
-    const target = protectivePathTargetOf(req);
-    return target === undefined ? undefined : target.access === "read" ? "read" : "write";
-}
 function countStars(s) {
     let n = 0;
     for (const c of s)
@@ -218,7 +213,7 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
                 }
                 if (issues.length > 0 && issues[issues.length - 1].rule === text && issues[issues.length - 1].code === "unsupported.path_base")
                     continue;
-                const faces = r.behavior === "deny" ? PATH_DENY_RULE_FACES[toolName] : undefined;
+                const faces = PATH_RULE_FACES[toolName]?.[r.behavior];
                 entry.content[r.behavior].push({ parsed: parsedPath.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}), ...(faces !== undefined ? { faces } : {}) });
                 byTool.set(toolName, entry);
                 continue;
@@ -340,8 +335,15 @@ export function createPermissionRulePolicy(rules, opts) {
     }
     const coveringHit = (lane, toolName) => lane.length === 0 ? undefined : lane.find((r) => namespacedRuleNameCovers(r.ruleName, toolName));
     const hasCovering = namespacedCovering.deny.length > 0 || namespacedCovering.ask.length > 0 || namespacedCovering.allow.length > 0;
-    const faceDenyRules = [...byTool.values()].flatMap((e) => e.content.deny.filter((r) => r.faces !== undefined));
-    const pathDenyRules = faceDenyRules.map((r) => pathRuleDenyRowOf({ parsed: r.parsed, ruleText: r.ruleText, faces: r.faces }, pathBases));
+    const faceRules = {
+        deny: [...byTool.values()].flatMap((e) => e.content.deny.filter((r) => r.faces !== undefined)),
+        ask: [...byTool.values()].flatMap((e) => e.content.ask.filter((r) => r.faces !== undefined)),
+    };
+    const pathDenyRules = faceRules.deny.map((r) => pathRuleDenyRowOf({ parsed: r.parsed, ruleText: r.ruleText, faces: r.faces }, pathBases));
+    const contentLaneOf = (behavior, entry, callFace) => [
+        ...(entry?.content[behavior].filter((r) => r.faces === undefined) ?? []),
+        ...(callFace !== undefined ? faceRules[behavior].filter((r) => r.faces.includes(callFace)) : []),
+    ];
     const commandParam = catalogRuleFaceOf("Bash")?.primaryParams[0] ?? "command";
     const contentHit = (lane, req) => {
         if (lane.length === 0)
@@ -410,8 +412,8 @@ export function createPermissionRulePolicy(rules, opts) {
                 if (coveringDeny)
                     return { action: "deny", message: ruleDenial(req, coveringDeny.ruleText, coveringDeny.source) };
             }
-            const callFace = faceDenyRules.length > 0 ? callPathFaceOf(req) : undefined;
-            const denyLane = [...(entry?.content.deny.filter((r) => r.faces === undefined) ?? []), ...(callFace !== undefined ? faceDenyRules.filter((r) => r.faces.includes(callFace)) : [])];
+            const callFace = faceRules.deny.length > 0 || faceRules.ask.length > 0 ? callPathFaceOf(req) : undefined;
+            const denyLane = contentLaneOf("deny", entry, callFace);
             const contentDeny = denyLane.length > 0 ? contentHit(denyLane, req) : undefined;
             if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
                 return { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source) };
@@ -434,23 +436,24 @@ export function createPermissionRulePolicy(rules, opts) {
                 if (coveringAsk)
                     return { action: "ask", message: ruleAskMessage(coveringAsk.ruleText, coveringAsk.source), matchedAskRule: coveringAsk.ruleText };
             }
+            const askLane = contentLaneOf("ask", entry, callFace);
+            const contentAsk = askLane.length > 0 ? contentHit(askLane, req) : undefined;
+            if (contentAsk !== undefined) {
+                if (contentAsk.unreadable !== undefined)
+                    return unreadableAsk({ rule: contentAsk.rule, unreadable: contentAsk.unreadable }, "content_ask", req);
+                return { action: "ask", message: ruleAskMessage(contentAsk.rule.ruleText, contentAsk.rule.source), matchedAskRule: contentAsk.rule.ruleText };
+            }
             if (entry) {
-                const contentAsk = contentHit(entry.content.ask, req);
-                if (contentAsk !== undefined) {
-                    if (contentAsk.unreadable !== undefined)
-                        return unreadableAsk({ rule: contentAsk.rule, unreadable: contentAsk.unreadable }, "content_ask", req);
-                    return { action: "ask", message: ruleAskMessage(contentAsk.rule.ruleText, contentAsk.rule.source), matchedAskRule: contentAsk.rule.ruleText };
-                }
                 const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);
                 if (paramAsk) {
                     return { action: "ask", message: ruleAskMessage(paramAsk.ruleText, paramAsk.source), matchedAskRule: paramAsk.ruleText };
                 }
                 if (entry.bare.allow) {
-                    return { action: "allow" };
+                    return { action: "allow", decisionReason: "rule" };
                 }
             }
             if (covering && coveringHit(namespacedCovering.allow, req.toolName)) {
-                return { action: "allow" };
+                return { action: "allow", decisionReason: "rule" };
             }
             if (defaultAction === "allow")
                 return { action: "allow" };

package/dist/core/runner/branch-writeback.d.ts

@@ -0,0 +1,38 @@
+import type { SessionStorage } from "../session.js";
+/** The entries this prepare appended through the watched storage — recorded once a branch is armed (`ids` set). */
+export interface OwnAppends {
+    ids: Set<string> | undefined;
+}
+/** The branch a `resumeAt` acquire wrote: the watched storage, the leaf the request found, the leaf it set, and the own appends since. */
+export interface ResumeAtBranch {
+    storage: SessionStorage;
+    leafBefore: string | null;
+    leafSet: string | null;
+    own: OwnAppends;
+}
+/**
+ * Wrap a storage so a `SessionError("conflict")` from any append/leaf write flips `ref.hit`, and every append
+ * that lands is recorded on `own` while a branch is armed. The harness flattens a mid-run storage failure into
+ * a generic error (and, since a lost CAS makes every subsequent append fail, even its failure-reporting append
+ * fails) — so the conflict code is gone by the time the task result is assembled. Catching it here, at the
+ * storage boundary, keeps it recoverable as `TaskResult.errorCode = "conflict"`. Per-task and non-mutating (a
+ * Proxy over the shared storage), so it never stacks across tasks on a cached session.
+ */
+export declare function detectConflicts(storage: SessionStorage, ref: {
+    hit: boolean;
+}, own: OwnAppends): SessionStorage;
+/**
+ * Put a refused prepare's `resumeAt` branch back: the leaf returns to `leafBefore` when it still sits on the
+ * branch leaf or on this prepare's own appends above it, and the write is conditional on the leaf just
+ * verified. A no-op when the leaf is already there. Throws a sentence naming both leaves when the leaf is
+ * not this request's to take back or the write cannot land. `signal` aborted before the write starts ⇒ no
+ * write (the caller's bound expired and the view is being dropped); a storage write already in flight cannot
+ * be called back — the storage contract carries no cancellation.
+ */
+export declare function writeBranchBack(branch: ResumeAtBranch, sessionId: string, signal?: AbortSignal): Promise<void>;
+/**
+ * The session cleanup's write-back leg: {@link writeBranchBack} bounded like every other cleanup leg (a throw or
+ * a timeout goes to `report`, never to the caller). A write-back still pending when the bound expires does not
+ * START its write afterwards — the view it would write through is being dropped.
+ */
+export declare function settleBranchWriteBack(branch: ResumeAtBranch, sessionId: string, label: string, report: (err: Error) => void): Promise<void>;

package/dist/core/runner/branch-writeback.js

@@ -0,0 +1,58 @@
+import { isSessionConflict } from "../session.js";
+import { thrownText } from "../thrown-value.js";
+import { settleTeardownLeg } from "./teardown-bounded.js";
+export function detectConflicts(storage, ref, own) {
+    const guard = (fn, landed) => async (...args) => {
+        try {
+            const out = await fn(...args);
+            landed(args);
+            return out;
+        }
+        catch (err) {
+            if (isSessionConflict(err)) {
+                ref.hit = true;
+            }
+            throw err;
+        }
+    };
+    return new Proxy(storage, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function") {
+                return value;
+            }
+            const bound = value.bind(target);
+            if (prop === "appendEntry")
+                return guard(bound, (args) => own.ids?.add(args[0].id));
+            if (prop === "setLeafId")
+                return guard(bound, () => undefined);
+            return bound;
+        },
+    });
+}
+export async function writeBranchBack(branch, sessionId, signal) {
+    let now;
+    try {
+        now = await branch.storage.getLeafId();
+        if (now === branch.leafBefore)
+            return;
+        const ids = branch.own.ids ?? new Set();
+        for (let at = now, steps = 0; at !== branch.leafSet; steps++) {
+            if (at === null || steps > ids.size || !ids.has(at))
+                throw new Error("another writer moved the leaf past the entries this request wrote");
+            at = (await branch.storage.getEntry(at))?.parentId ?? null;
+        }
+        if (signal?.aborted === true)
+            return;
+        await branch.storage.setLeafId(branch.leafBefore, { expectedLeafId: now });
+    }
+    catch (err) {
+        const shown = (id) => (id === undefined ? "(unreadable)" : id === null ? "(empty)" : `"${id}"`);
+        throw new Error(`resumeAt: prepare refused this request but could not put session "${sessionId}" back — its leaf stays at ${shown(now)} (the request found it at ${shown(branch.leafBefore)}), so the next turn continues from there: ${thrownText(err)}`);
+    }
+}
+export async function settleBranchWriteBack(branch, sessionId, label, report) {
+    const ac = new AbortController();
+    await settleTeardownLeg(() => writeBranchBack(branch, sessionId, ac.signal), label, report);
+    ac.abort();
+}

package/dist/core/runner/denial-limit-arms.js

@@ -103,7 +103,7 @@ export async function judgeInheritedClassifier(opts) {
     const attributed = (d) => (verdict.classifier !== undefined ? attestClassifierRound(d, verdict.classifier, req) : d);
     if (verdict.kind === "allow") {
         autoMode.denialTracking?.recordAllow();
-        return { kind: "allow", result: attributed({ action: "allow", ...(opts.allowRewrite !== undefined ? { updatedInput: opts.allowRewrite } : {}) }) };
+        return { kind: "allow", result: attributed({ action: "allow", decisionReason: "classifier", ...(opts.allowRewrite !== undefined ? { updatedInput: opts.allowRewrite } : {}) }) };
     }
     if (verdict.kind === "unavailable") {
         const arm = classifierUnavailableArm({ ask, req, cause: verdict.cause, seat: opts.unavailableSeat, aborted: opts.signal.aborted });

package/dist/core/runner/gate-exit.d.ts

@@ -214,6 +214,10 @@ export interface GatePass {
     hookAsk: Extract<PermissionResult, {
         action: "ask";
     }> | undefined;
+    /** borrowed-mutable — the phase-1 hook answered its own `allow` (the exact word): a statement about this call, read by
+     *  the fold's last station only while the policy left the arguments as the hook saw them. Writer: the dispatch (phase 1).
+     *  Reader: the fold's unstated station. */
+    hookAllowed?: true;
     /** borrowed-mutable — set by a park attempt that FAILED (see `ParkAttemptFailed`). Read at the single deny
      *  exit — whatever the fallback chain then decides to say, it says it knowing the park was tried first.
      *  Writers: the three park sites. */
@@ -256,7 +260,7 @@ export interface GatePass {
      *  policy's answer; then rewritten by every station that changes the verdict (fold, tightens, org, rule
      *  lane, stamp, classifier, sandbox, content lane, resolution, edit chain). */
     decision: PermissionResult;
-    /** borrowed-mutable — which of the gate's OWN post-fold tightens minted the standing ask, if one did — an
+    /** borrowed-mutable — which of the gate's OWN post-fold stations (the tightens and the unstated station) minted the standing ask, if one did — an
      *  input of the ask-origin derivation (`AskOriginFacts.tightened`). Written at most once per pass: every
      *  tighten fires only over a surviving `allow`, and the first one to fire leaves an `ask` the others do not
      *  touch. Recorded by the gate rather than read off `decisionReason` because that member is a policy's to

package/dist/core/runner/permission-rule-lanes.js

@@ -1,6 +1,6 @@
 import { persistedRuleMandateOf, ruleClearanceOf } from "../ask-origin.js";
 import {} from "../hooks.js";
-import { adjudicatePersistedPathRules, adjudicatePersistedRules, laneToolNamesOf, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { adjudicatePersistedPathRules, adjudicatePersistedRules, callPathFaceOf, faceAskSpeaksFor, laneToolNamesOf, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
 import { isAbsolutePathForm } from "../../tools/fs/safety.js";
 import { effectivePathTargetOf } from "../effective-path-target.js";
 import { declaredPathTargetOf, protectivePathTargetOf } from "../tool-registry.js";
@@ -45,7 +45,7 @@ export function pathRuleLaneAnswer(table, req, ctx) {
     const allow = effectivePathTargetOf(req, declaredPathTargetOf(req), bases);
     if (tighten === undefined && allow === undefined)
         return undefined;
-    return persistedRuleAnswerOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, bases));
+    return persistedRuleAnswerOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId, face: callPathFaceOf(req) }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, bases));
 }
 export function orgRuleLane(cfg) {
     return {
@@ -127,8 +127,10 @@ export function createPermissionRuleLanes(cfg) {
     const personalAdjudicate = async (req) => {
         if (anonymous && !cfg.localOwnerDeclared)
             return undefined;
-        const laneNames = laneToolNamesOf(req);
-        if (laneNames.length === 0)
+        const judged = laneToolNamesOf(req).map((n) => [n, ruleToolGrammarOf(n)]);
+        if (!judged.some(([, g]) => g === "path") && faceAskSpeaksFor(callPathFaceOf(req)))
+            judged.push([req.toolName, "path"]);
+        if (judged.length === 0)
             return undefined;
         let view;
         try {
@@ -140,7 +142,7 @@ export function createPermissionRuleLanes(cfg) {
         if (view.unreadable !== undefined)
             skipped(view.unreadable, view.unreadableSources);
         try {
-            const answer = strongestAnswer(laneNames.map((n) => judgeAgainst(view.rules, { ...req, toolName: n }, ruleToolGrammarOf(n))));
+            const answer = strongestAnswer(judged.map(([n, grammar]) => judgeAgainst(view.rules, { ...req, toolName: n }, grammar)));
             return view.unreadable !== undefined && (answer === undefined || "segmentCoverage" in answer) ? { unreadable: true } : answer;
         }
         catch (err) {

package/dist/core/runner/persisted-path-rows.js

@@ -1,7 +1,7 @@
 import { ownerStoreOf } from "../permission-rule-provider.js";
-import { READ_RULE_TOOL, eligiblePersisted, isUsablePathBase, ruleBasesNeeded } from "../permission-rule-model.js";
+import { PATH_RULE_FACES, READ_RULE_TOOL, eligiblePersisted, isUsablePathBase, ruleBasesNeeded } from "../permission-rule-model.js";
 import { isAbsolutePathForm, pathFamilyOf } from "../../tools/fs/safety.js";
-import { PATH_DENY_RULE_FACES, pathRuleDenyRowOf } from "../permission-rules.js";
+import { pathRuleDenyRowOf } from "../permission-rules.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, gateWaitFailureOf, withGateTimeout } from "../gate-bounded-await.js";
 import { thrownText } from "../thrown-value.js";
@@ -34,7 +34,7 @@ export async function persistedPathRowsOf(cfg) {
                 readDirectories.push(rule.command);
             continue;
         }
-        const faces = PATH_DENY_RULE_FACES[rule.tool];
+        const faces = PATH_RULE_FACES[rule.tool]?.deny;
         if (rule.behavior !== "deny" || faces === undefined || (rule.match !== "path" && rule.match !== "subpath") || !eligiblePersisted(rule, { ...call, tool: rule.tool }, "deny"))
             continue;
         const missing = ruleBasesNeeded(rule).filter((b) => !isUsablePathBase(b === "cwd" ? bases.root : bases[b], family));

package/dist/core/runner/prepare-acquire-reconcile.d.ts

@@ -16,13 +16,15 @@
  *
  * Throws pass through unchanged: `resume.session_not_found` (requireExisting fail-loud mapping),
  * the `resume_at.*` target-validation refusals, and — after the bounded re-wake budget — the
- * session conflict itself.
+ * session conflict itself. A throw after a `resumeAt` branch landed first writes that branch back
+ * (`settleBranchWriteBack`); on success the branch is handed over with the session.
  */
 import { StoredSession } from "../session.js";
 import type { AcquiredSession, SessionStore } from "../session.js";
 import { type RecoveredOrphan } from "../session-reconcile.js";
 import type { TaskSpec, ToolEffect } from "../types.js";
 import type { PrepareResume } from "./contracts.js";
+import { type ResumeAtBranch } from "./branch-writeback.js";
 export interface PrepareAcquireReconcileInput {
     /** borrowed-mutable (service port) — the deployment's session store. This phase's verbs on it are
      *  the acquire/forget half of the session resource protocol: `acquire` per attempt, `forget` to
@@ -52,8 +54,10 @@ export interface PrepareAcquireReconcileInput {
      *  absent seat; nothing in the phase's control flow depends on it. Computed by the driver (which
      *  holds `deps`) rather than here, keeping this slice's input the narrow Pick its contract says. */
     durableParkGap?: string;
+    /** borrowed-readonly — the incident channel for this phase's own cleanup legs: a `resumeAt` branch it could not write back, a forget that did not settle. */
+    report?: (err: Error, sessionId: string) => void;
 }
-/** The phase's outputs (four-class form). All five are fresh bindings —
+/** The phase's outputs (four-class form). All six are fresh bindings —
  *  the driver destructures them into consts, so a consumer moved ahead of this call is a lexical
  *  error, which is the static guarantee the extraction keeps. */
 export interface PrepareAcquireReconcileResult {
@@ -75,6 +79,9 @@ export interface PrepareAcquireReconcileResult {
      *  SUCCEEDS (a conflict-losing attempt re-wakes and re-derives the whole set from the fresh
      *  branch), and stays empty for a fresh session / a clean one with nothing to reconcile. */
     wakeRecovered: RecoveredOrphan[];
+    /** owned (handed over with the session) — the `resumeAt` branch this phase wrote, absent when it wrote
+     *  none; the driver's throw cleanup writes it back on any later prepare refusal. */
+    branch: ResumeAtBranch | undefined;
 }
 /** The B-3 phase body — the acquire+reconcile slice, verbatim (see the module header for the contract). */
 export declare function prepareAcquireReconcile(input: PrepareAcquireReconcileInput): Promise<PrepareAcquireReconcileResult>;

package/dist/core/runner/prepare-acquire-reconcile.js

@@ -1,37 +1,15 @@
 import { StoredSession, isSessionConflict } from "../session.js";
 import { reconcileInterruptedSession } from "../session-reconcile.js";
+import { detectConflicts, settleBranchWriteBack } from "./branch-writeback.js";
+import { settleTeardownLeg } from "./teardown-bounded.js";
 const RECONCILE_MAX_RETRIES = 3;
-function detectConflicts(storage, ref) {
-    const guard = (fn) => async (...args) => {
-        try {
-            return await fn(...args);
-        }
-        catch (err) {
-            if (isSessionConflict(err)) {
-                ref.hit = true;
-            }
-            throw err;
-        }
-    };
-    return new Proxy(storage, {
-        get(target, prop, receiver) {
-            const value = Reflect.get(target, prop, receiver);
-            if (typeof value !== "function") {
-                return value;
-            }
-            const bound = value.bind(target);
-            return prop === "appendEntry" || prop === "setLeafId"
-                ? guard(bound)
-                : bound;
-        },
-    });
-}
 export async function prepareAcquireReconcile(input) {
     const { sessions, spec, resume, toolEffects } = input;
     let acquired;
     let session;
     let conflictRef;
     let wakeRecovered = [];
+    let branch;
     for (let attempt = 0;; attempt++) {
         try {
             acquired = await sessions.acquire(spec.sessionId, spec.requireExistingSession ? { requireExisting: true } : input.placement !== undefined ? { placement: input.placement } : undefined);
@@ -46,7 +24,8 @@ export async function prepareAcquireReconcile(input) {
             throw err;
         }
         conflictRef = { hit: false };
-        session = new StoredSession(detectConflicts(acquired.session.getStorage(), conflictRef));
+        const own = { ids: undefined };
+        session = new StoredSession(detectConflicts(acquired.session.getStorage(), conflictRef, own));
         if (!spec.sessionId) {
             break;
         }
@@ -105,7 +84,10 @@ export async function prepareAcquireReconcile(input) {
                         throw e;
                     }
                 }
-                await session.getStorage().setLeafId(spec.resumeAtMode === "before" ? entry.parentId : spec.resumeAt);
+                const storage = session.getStorage(), leafBefore = await storage.getLeafId(), leafSet = spec.resumeAtMode === "before" ? entry.parentId : spec.resumeAt;
+                await storage.setLeafId(leafSet);
+                own.ids = new Set();
+                branch = { storage, leafBefore, leafSet, own };
             }
             wakeRecovered = (await reconcileInterruptedSession(session, toolEffects, resume?.suspendedBatch)).recovered;
             break;
@@ -113,13 +95,17 @@ export async function prepareAcquireReconcile(input) {
         catch (err) {
             if (isSessionConflict(err) && attempt < RECONCILE_MAX_RETRIES) {
                 if (sessions.forget) {
-                    await Promise.resolve(sessions.forget(spec.sessionId)).catch(() => undefined);
+                    const forget = sessions.forget.bind(sessions), id = spec.sessionId;
+                    await settleTeardownLeg(() => Promise.resolve(forget(id)).catch(() => undefined), "forget (acquire-reconcile re-wake leg)", (e) => input.report?.(e, id));
                 }
+                branch = undefined;
                 continue;
             }
-            await Promise.resolve(sessions.forget ? sessions.forget(acquired.sessionId) : undefined).catch(() => undefined);
+            if (branch !== undefined)
+                await settleBranchWriteBack(branch, acquired.sessionId, "resumeAt branch write-back (acquire-reconcile failure leg)", (e) => input.report?.(e, acquired.sessionId));
+            await settleTeardownLeg(() => Promise.resolve(sessions.forget ? sessions.forget(acquired.sessionId) : undefined).catch(() => undefined), "forget (acquire-reconcile failure leg)", (e) => input.report?.(e, acquired.sessionId));
             throw err;
         }
     }
-    return { acquired, session, conflictRef, wakeRecovered };
+    return { acquired, session, conflictRef, wakeRecovered, branch };
 }

package/dist/core/runner/prepare-file-history.d.ts

@@ -8,8 +8,8 @@
  * boundary seat runtask drives.
  *
  * Runs INSIDE the driver's prepare try-block, after the workspace root is FINAL (`taskRootFinal`) and the
- * env is resolved: every refusal here throws through to the driver's prepare-throw catch exactly as
- * before the move (a minted ownedEnv is destroyed there, the session view forgotten). The phase acquires
+ * env is resolved: every refusal here throws through to the driver's prepare-throw catch (a minted
+ * ownedEnv is destroyed there, a resumeAt branch written back, the session view forgotten). The phase acquires
  * no resource of its own — the two seats it returns are closures over the store the deployment owns.
  *
  * The request door (the bad-value doors and every refusal the request decides alone) lives in

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

@@ -25,7 +25,7 @@
 import type { AgentHarness, AgentTool } from "../../internal/harness.js";
 import type { AskClass } from "../ask-class.js";
 import type { Arbitration, ToolMarkSource } from "../ask-origin.js";
-import type { PermissionModeController } from "../mode-policy.js";
+import { type PermissionModeController } from "../mode-policy.js";
 import type { AutoModeDecider, AutoModeDenialTracker } from "../auto-mode.js";
 import { type ComplianceCapability } from "../compliance.js";
 import { type HookEnvCapabilities, type HookInvocationIdentity, type Hooks } from "../hooks.js";

package/dist/core/runner/prepare-gate-stations.js

@@ -1,4 +1,5 @@
 import { SEND_MESSAGE_TOOL_NAME } from "../../agents/send-message-tool.js";
+import { mountedToolPermissionSeat } from "../mode-policy.js";
 import { complianceCallDenial } from "../compliance.js";
 import { cloneObserverInput, formatHookFeedback, hookSeatExpiredError, runHookSeat, runToolGate } from "../hooks.js";
 import { screenGateOutcome } from "../gate-outcome.js";
@@ -137,6 +138,7 @@ export function prepareGateStations(input) {
                         ...(autoModeDecider.current !== undefined ? { autoMode: { decider: autoModeDecider.current, ...(autoModeDenialTracking.current !== undefined ? { denialTracking: autoModeDenialTracking.current } : {}), unavailable: classifierUnavailableSeat({ station: "leg", ...(autoModeDecider.current.timeoutMs !== undefined ? { budgetMs: autoModeDecider.current.timeoutMs } : {}), approvalSeat: askReachesPerson(askRoute), onNotice: deps.onNotice, sessionId, runId }) } } : {}),
                         permissionMode: () => permissionMode.current,
                         ...(markSources.size > 0 ? { toolMarkSources: markSources } : {}),
+                        ...(mountedToolPermissionSeat(tools, e.toolName) === "passthrough" ? { permissionSeat: "passthrough" } : {}),
                         ...(a2aIsolatePeers === true ? { a2aIsolatePeers: true } : {}),
                         onModeReleased,
                         ancestorArbitrationOf: (toolCallId) => ancestorArbitrations.get(toolCallId),

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -149,7 +149,7 @@ export interface PrepareHandsReadFaceInput {
     reversibilityProbes: ReversibilityProbes;
     /** borrowed-readonly — the run's reminder provenance mark (minted/adopted
      *  by the driver's adoption ladder); threaded into the hands band so the fs-side engine mints
-     *  (the Read cyber/dedup/offset/empty reminders, the gh rate-limit hint) stamp the same mark the
+     *  (the Read dedup/offset/empty reminders, the gh rate-limit hint) stamp the same mark the
      *  system-prompt declaration names. */
     reminderMark: string;
     /** borrowed-mutable — the leg's disclosure trigger counters; the hands

package/dist/core/runner/prepare-hands-readface.js

@@ -366,7 +366,6 @@ export async function prepareHandsMount(input) {
             ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
             ...(deps.hands?.readImageDownsampler !== undefined ? { readImageDownsampler: deps.hands.readImageDownsampler } : {}),
             ...(deps.hands?.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: deps.hands.autoBackgroundOnTimeout } : {}),
-            ...(deps.hands?.readCyberReminder !== undefined ? { readCyberReminder: deps.hands.readCyberReminder } : {}),
             beforeWrite: async (w) => {
                 const deploymentGate = deps.hands?.beforeWrite;
                 if (deploymentGate) {

package/dist/core/runner/prepare-policy-chain.js

@@ -364,7 +364,8 @@ export async function preparePolicyChain(input) {
             if (re.action === "deny")
                 return vetoed(re);
             if (re.action === "allow") {
-                const out = { action: "allow", updatedInput: re.updatedInput !== undefined ? re.updatedInput : editArgs };
+                const stated = re.updatedInput === undefined ? "mode" : re.decisionReason;
+                const out = { action: "allow", updatedInput: re.updatedInput !== undefined ? re.updatedInput : editArgs, ...(stated !== undefined ? { decisionReason: stated } : {}) };
                 carryEngineAttestations(re, out);
                 carryPrecedingSettlement(settledBy, out);
                 return out;
@@ -384,7 +385,7 @@ export async function preparePolicyChain(input) {
             re = editAsk;
             const editArbitrated = arbitrateInherited(re, creq.toolCallId, judged);
             if (editArbitrated !== undefined) {
-                const out = editArbitrated.action === "allow" ? { action: "allow", updatedInput: editArgs } : editArbitrated;
+                const out = editArbitrated.action === "allow" ? { action: "allow", updatedInput: editArgs, decisionReason: "mode" } : editArbitrated;
                 carryPrecedingSettlement(settledBy, out);
                 return out;
             }
@@ -408,7 +409,7 @@ export async function preparePolicyChain(input) {
                 return rr;
             settledBy = rr;
             if (rr.updatedInput === undefined) {
-                const out = { action: "allow", updatedInput: editArgs };
+                const out = { action: "allow", updatedInput: editArgs, decisionReason: "mode" };
                 carryPrecedingSettlement(rr, out);
                 return out;
             }
@@ -461,7 +462,7 @@ export async function preparePolicyChain(input) {
                     const { ask: inheritedAsk, fallback, mintedHere } = judged;
                     if (fallback === undefined && sandboxAdmissionArmed && policyAskClassOf(pc.policy) === "sandbox_local" && !sandboxBoundaryCapable(creq) && judged.classification.row.sandboxAdmission) {
                         recordAncestorSandboxAdmission(creq.toolCallId, creq.toolName);
-                        return { action: "allow" };
+                        return { action: "allow", decisionReason: "sandbox" };
                     }
                     const arbitrated = arbitrateInherited(inheritedAsk, creq.toolCallId, judged);
                     if (arbitrated !== undefined)
@@ -496,7 +497,7 @@ export async function preparePolicyChain(input) {
                         return recheckApprovedEdit(pc.policy, pc.onAsk, creq, resolved.updatedInput, resolved, csignal, pc.autoMode);
                     }
                     recordInheritedAskGrant(creq.toolCallId, pc.onAsk, resolved.presentedInput, askWaitMs, resolved, askClassMembersOf(judged.classification).classes);
-                    return { action: "allow" };
+                    return { action: "allow", decisionReason: "mode" };
                 },
             }
             : wrapToolPolicy(pc.policy, async (creq, csignal) => {
@@ -535,7 +536,7 @@ export async function preparePolicyChain(input) {
                 const { ask: inheritedAsk, fallback, mintedHere } = judged;
                 if (fallback === undefined && sandboxAdmissionArmed && policyAskClassOf(pc.policy) === "sandbox_local" && !sandboxBoundaryCapable(creq) && judged.classification.row.sandboxAdmission) {
                     recordAncestorSandboxAdmission(creq.toolCallId, creq.toolName);
-                    return decision.updatedInput !== undefined ? { action: "allow", updatedInput: decision.updatedInput } : { action: "allow" };
+                    return decision.updatedInput !== undefined ? { action: "allow", updatedInput: decision.updatedInput, decisionReason: "sandbox" } : { action: "allow", decisionReason: "sandbox" };
                 }
                 const arbitrated = arbitrateInherited(inheritedAsk.action === "ask" ? { ...inheritedAsk, ...(decision.updatedInput !== undefined ? { updatedInput: decision.updatedInput } : {}) } : inheritedAsk, creq.toolCallId, judged);
                 if (arbitrated !== undefined)
@@ -635,6 +636,7 @@ export async function preparePolicyChain(input) {
             const finalReq = { ...req, args: decision.updatedInput };
             let asked;
             const revalidated = {};
+            let restated;
             try {
                 for (const layer of recheckLayers) {
                     const d = refuseOutOfContractDecision(await layer.check(finalReq, signal));
@@ -653,6 +655,8 @@ export async function preparePolicyChain(input) {
                     }
                     if (d.action === "ask" && asked === undefined)
                         asked = d;
+                    if (d.action === "allow" && restated === undefined && d.decisionReason !== undefined)
+                        restated = d.decisionReason;
                     carryEngineAttestations(d, revalidated);
                 }
             }
@@ -665,7 +669,7 @@ export async function preparePolicyChain(input) {
                 return surfaced;
             }
             if (decision.action === "allow") {
-                const owned = { ...decision };
+                const owned = { ...decision, ...(decision.decisionReason === undefined && restated !== undefined ? { decisionReason: restated } : {}) };
                 carryEngineAttestations(decision, owned);
                 carryEngineAttestations(revalidated, owned);
                 return owned;

package/dist/core/runner/prepare-task.js

@@ -38,6 +38,7 @@ import { preparePromptAssembly } from "./prepare-prompt-assembly.js";
 import { limitConfigError, prepareConfigDoors } from "./prepare-config-doors.js";
 import { prepareSafetyScan } from "./prepare-safety-scan.js";
 import { prepareAcquireReconcile } from "./prepare-acquire-reconcile.js";
+import { settleBranchWriteBack } from "./branch-writeback.js";
 import { prepareHandsMount, resolveHandsLessReadFace } from "./prepare-hands-readface.js";
 import { prepareWorkspaceRestore } from "./prepare-workspace-restore.js";
 import { parkContaminationMarker } from "./park-commit.js";
@@ -291,8 +292,15 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     let shellGatedTools = new Set();
     refuseRequireExistingWithoutSession(spec);
     refuseRegistryScopeMismatch(spec, internals);
+    if (model.extraBody !== undefined && Object.prototype.hasOwnProperty.call(model.extraBody, "max_completion_tokens")) {
+        const e = new Error(`model.extraBody supplies "max_completion_tokens" — this spelling is engine-owned (the overflow retry ` +
+            `adjusts the per-request output cap, and a constant extraBody value would override that adjustment on ` +
+            `every retry). Set the cap via limits.maxOutputTokens (per request) or model.maxTokens instead.`);
+        e.code = "config.extra_body_output_cap";
+        throw e;
+    }
     const fileHistoryRequest = resolveFileHistoryRequest(spec, deps);
-    const { acquired, session, conflictRef, wakeRecovered } = await prepareAcquireReconcile({ sessions, spec, resume, toolEffects, ...(internals?.sessionPlacement !== undefined ? { placement: internals.sessionPlacement } : {}), ...(() => { const g = durableParkGapFor(deps, spec); return g !== undefined ? { durableParkGap: g } : {}; })() });
+    const { acquired, session, conflictRef, wakeRecovered, branch } = await prepareAcquireReconcile({ sessions, spec, resume, toolEffects, report: (e, id) => deps.onError?.(e, { phase: "config", sessionId: id }), ...(internals?.sessionPlacement !== undefined ? { placement: internals.sessionPlacement } : {}), ...(() => { const g = durableParkGapFor(deps, spec); return g !== undefined ? { durableParkGap: g } : {}; })() });
     const sessionId = acquired.sessionId;
     await holdSessionLock?.(sessionId);
     const onceLedger = await loadAnnounceOnceLedger(session, resume?.seed.announcedListings, deps.onError);
@@ -320,18 +328,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         deps.onError?.(new Error(`offload/tool-result namespace note: this run mounts in registry domain "${internals.registryScope}" but its offloaded tool results live under the TRUST identity "${offloadScope}" (principal${spec.principal === undefined ? " absent → default" : ""}). Before 2.13.0 the registry domain named this namespace too; if a deployment used registryScope as its ref-tenancy boundary, that boundary is now the principal — pass one, or read refs under "${offloadScope}".`), { phase: "config", sessionId });
     }
     defaultTaskRegistry.maybeGc();
-    const forgetOnThrow = () => forgetQuietly(sessions, sessionId);
+    const forgetOnThrow = () => branch === undefined
+        ? forgetQuietly(sessions, sessionId)
+        : settleBranchWriteBack(branch, sessionId, "resumeAt branch write-back (prepare refusal)", (e) => deps.onError?.(e, { phase: "config", sessionId })).then(() => forgetQuietly(sessions, sessionId));
     const extraBodyCollisions = reservedCollisions(model.extraBody, reservedFor(model.api));
     if (extraBodyCollisions.length > 0) {
         deps.onError?.(new Error(`model.extraBody contains reserved key(s) [${extraBodyCollisions.join(", ")}] that core owns and sets itself — they are ignored. Remove them from extraBody.`), { phase: "config", sessionId });
     }
-    if (model.extraBody !== undefined && Object.prototype.hasOwnProperty.call(model.extraBody, "max_completion_tokens")) {
-        const e = new Error(`model.extraBody supplies "max_completion_tokens" — this spelling is engine-owned (the overflow retry ` +
-            `adjusts the per-request output cap, and a constant extraBody value would override that adjustment on ` +
-            `every retry). Set the cap via limits.maxOutputTokens (per request) or model.maxTokens instead.`);
-        e.code = "config.extra_body_output_cap";
-        throw e;
-    }
     const { nestedStats, reportUsage, offloadStore, offloadReachableToolsRef, maybeOffload, firstPartyOffload, remoteToolOffload } = prepareOffloadWrappers({ spec, deps, resume, offloadScope, sessionId });
     if (offloadStore && (spec.tools ?? []).some((t) => t.name === OFFLOAD_TOOL_NAME)) {
         const e = new Error(`Tool name "${OFFLOAD_TOOL_NAME}" is reserved when large-result offload is enabled.`);

package/dist/core/runner/prepare-wiring-manifest.d.ts

@@ -33,7 +33,7 @@ import { type LegWriteProtection } from "./write-protection-station.js";
 import { type UsageWindow } from "../usage-window-store.js";
 import type { ToolRoster } from "../tool-roster.js";
 import { type AutoModeArmFact, type WiringManifest, type WiringManifestMcpEntry } from "../wiring-manifest.js";
-import type { PermissionModeController } from "../mode-policy.js";
+import { type PermissionModeController } from "../mode-policy.js";
 import type { AnnounceOnceSink, Prepared, PrepareResume, RunInternals, UsageGovernance } from "./contracts.js";
 export interface PrepareWiringManifestInput {
     /** borrowed-readonly — the REBOUND spec. Read: `onAsk` (the own seat), `onQuestion` (the question seam), `handsReadOnly` / `tools` (the ungated scan),