@sema-agent/core 7.55.0 → 7.57.0

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

@@ -1,13 +1,6 @@
 export function resolveFileHistoryRequest(spec, deps) {
-    const onTrackFailure = deps.onTrackFailure === undefined ? "refuse" : deps.onTrackFailure;
-    if (onTrackFailure !== "refuse" && onTrackFailure !== "proceed-unprotected") {
-        const e = new Error(`RunnerDeps.onTrackFailure must be "refuse" or "proceed-unprotected"; got ${JSON.stringify(deps.onTrackFailure)} — refusing prepare rather than silently defaulting a first-touch-failure policy.`);
-        e.code = "config.invalid_on_track_failure";
-        throw e;
-    }
-    const wiredSeat = resolveWiredFileHistoryStore(deps.fileHistoryStore);
+    const { onTrackFailure, wiredSeat, captureOff } = resolveDeploymentFileHistory(deps);
     const runDeclaredOff = resolveRunFileHistoryWord(spec.fileHistory);
-    const captureOff = resolveFileHistoryCaptureWord(deps.fileHistoryCapture, wiredSeat);
     const declaredOff = wiredSeat === "disabled" || runDeclaredOff;
     const fileHistoryStore = declaredOff ? undefined : wiredSeat;
     const captureStore = captureOff ? undefined : fileHistoryStore;
@@ -34,14 +27,29 @@ export function resolveFileHistoryRequest(spec, deps) {
     if (rewindTarget !== undefined && fileHistoryStore === undefined) {
         if (runDeclaredOff)
             throw captureDisabledRefusal(rewindTarget);
-        const e = new Error(wiredSeat === "disabled"
-            ? `rewind-files: restoring files to entry "${rewindTarget}" requires a history backend, but this deployment declared file history disabled (RunnerDeps.fileHistoryStore: "disabled"), so there is no history to restore — the files were NOT rewound`
-            : `rewind-files: restoring files to entry "${rewindTarget}" requires a history backend, but this deployment wired no RunnerDeps.fileHistoryStore — no file history was ever recorded, so the files were NOT rewound`);
-        e.code = "rewind.store_unconfigured";
-        throw e;
+        throw storeUnconfiguredRefusal(wiredSeat, rewindTarget);
     }
     return { onTrackFailure, wiredSeat, runDeclaredOff, captureOff, declaredOff, fileHistoryStore, captureStore, rewindTarget, rewindBefore };
 }
+export function resolveDeploymentFileHistory(deps) {
+    const onTrackFailure = deps.onTrackFailure === undefined ? "refuse" : deps.onTrackFailure;
+    if (onTrackFailure !== "refuse" && onTrackFailure !== "proceed-unprotected") {
+        const e = new Error(`RunnerDeps.onTrackFailure must be "refuse" or "proceed-unprotected"; got ${JSON.stringify(deps.onTrackFailure)} — refusing prepare rather than silently defaulting a first-touch-failure policy.`);
+        e.code = "config.invalid_on_track_failure";
+        throw e;
+    }
+    const wiredSeat = resolveWiredFileHistoryStore(deps.fileHistoryStore);
+    const captureOff = resolveFileHistoryCaptureWord(deps.fileHistoryCapture, wiredSeat);
+    const fileHistoryStore = wiredSeat === "disabled" ? undefined : wiredSeat;
+    return { onTrackFailure, wiredSeat, captureOff, fileHistoryStore, captureStore: captureOff ? undefined : fileHistoryStore };
+}
+export function storeUnconfiguredRefusal(wiredSeat, target) {
+    const e = new Error(wiredSeat === "disabled"
+        ? `rewind-files: restoring files to entry "${target}" requires a history backend, but this deployment declared file history disabled (RunnerDeps.fileHistoryStore: "disabled"), so there is no history to restore — the files were NOT rewound`
+        : `rewind-files: restoring files to entry "${target}" requires a history backend, but this deployment wired no RunnerDeps.fileHistoryStore — no file history was ever recorded, so the files were NOT rewound`);
+    e.code = "rewind.store_unconfigured";
+    return e;
+}
 function resolveWiredFileHistoryStore(candidate) {
     if (candidate === undefined || candidate === "disabled")
         return candidate;

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

@@ -0,0 +1,45 @@
+/**
+ * The ONE restore of a session's tracked set and the ONE reading of its answer, reached DOWN for by the two seats that
+ * restore: the file-history phase's restore seat (`prepare-file-history.ts`, a `restoreFiles` / `rewindFilesTo` run)
+ * and the out-of-run rewind (`rewind-files.ts`, `Runner.rewindFiles`). A rewind outside a run is therefore the same
+ * history operation as the one a run performs, refused with the same codes and sentences, and handing the paths it
+ * moved to the same read-state channel.
+ */
+import type { ExecutionEnv } from "../../internal/harness.js";
+import type { FileHistoryRestoreResult, FileHistoryStore, RewindFilesResult } from "../file-history-store.js";
+import type { SessionReadFileStates } from "./session-read-file-states.js";
+/** A restore outcome a seat may accept: the ledger, with `failed` (the operation could not run) already refused —
+ *  the out-of-run rewind's answer carries exactly this. */
+export type AcceptedFileHistoryRestore = Extract<RewindFilesResult, {
+    dryRun: false;
+}>["restore"];
+/**
+ * The ONE restore of a session's tracked set and the ONE reading of its answer — the run's restore seat and the
+ * out-of-run `Runner.rewindFiles` both call it, so the two cannot disagree about what a restore means:
+ *  · every path the attempt may have moved (`filesChanged` ∪ `failed[].path`, whatever the outcome) goes to the
+ *    session's read-state channel (`noteRestored`), because a read record of the old bytes must stop vouching
+ *    for them on the session's next leg;
+ *  · `not_found` is "no boundary for that entry" — `rewind_snapshot.unresolvable` (in a "before" restore, the
+ *    before-specific sentence);
+ *  · any other `failed` outcome is `rewind.restore_failed` carrying the ledger and the store's own judgment on
+ *    the coded `detail` channel (a host reads it, never the prose).
+ * A `complete` or `partial` answer is returned for the caller to accept: only a run goes on to work on the tree,
+ * so only the run seat has a partial-restore policy.
+ */
+export declare function settleFileHistoryRestore(input: {
+    store: FileHistoryStore;
+    sessionId: string;
+    target: string;
+    before: boolean;
+    env: ExecutionEnv;
+    root: string;
+    signal: AbortSignal | undefined;
+    readStates: Pick<SessionReadFileStates, "noteRestored"> | undefined;
+}): Promise<AcceptedFileHistoryRestore>;
+/** The per-file ledger as one sentence (counts, then each refused / failed path with its reason). */
+export declare function fileHistoryRestoreLedgerLine(r: FileHistoryRestoreResult): string;
+/** A restore whose entry has no boundary on the session; a PREVIEW's form says "usable" — its probe
+ *  (`canRestore`) cannot tell a boundary never made from one that is there and unreadable, a real restore can. */
+export declare function noBoundaryRefusal(target: string, sessionId: string, preview?: boolean): Error & {
+    code?: string;
+};

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

@@ -0,0 +1,46 @@
+import { resolveTrackKey } from "../file-history-store.js";
+import { isGovernanceRetryClass } from "../governance-codes.js";
+export async function settleFileHistoryRestore(input) {
+    const { store, sessionId, target, env, root } = input;
+    const restored = await store.restore(sessionId, target, env, root, input.signal);
+    input.readStates?.noteRestored(sessionId, restoredAbsPathsOf(restored, root));
+    if (restored.outcome !== "failed")
+        return restored;
+    if (restored.error?.code === "not_found") {
+        if (input.before)
+            throw beforeWithoutBoundaryRefusal(target, sessionId);
+        throw noBoundaryRefusal(target, sessionId);
+    }
+    const e = new Error(`rewind-files restore failed (${restored.error?.code ?? "restore_failed"}): ${restored.error?.message ?? "unknown"} — ledger: ${fileHistoryRestoreLedgerLine(restored)}`);
+    e.code = "rewind.restore_failed";
+    if (restored.error !== undefined)
+        e.detail = { code: restored.error.code, ...(isGovernanceRetryClass(restored.error.permanence) ? { permanence: restored.error.permanence } : {}) };
+    throw e;
+}
+export function fileHistoryRestoreLedgerLine(r) {
+    return `applied ${r.filesChanged.length}, identical ${r.identicalSkipped.length}, refused ${r.refused.length}${r.refused.length > 0 ? ` (${r.refused.map((f) => `${f.path}: ${f.reason}`).join("; ")})` : ""}, failed ${r.failed.length}${r.failed.length > 0 ? ` (${r.failed.map((f) => `${f.path}: ${f.reason}`).join("; ")})` : ""}`;
+}
+export function noBoundaryRefusal(target, sessionId, preview = false) {
+    const e = new Error(preview
+        ? `rewind-files: no usable file-history boundary exists for entry "${target}" on session "${sessionId}" (never made, reaped, or there but unreadable — a real rewind names which), so there is nothing to preview. ${rewindRefusalTail()}`
+        : `rewind-files: no file-history boundary exists for entry "${target}" on session "${sessionId}" — the working tree was NOT rewound. ${rewindRefusalTail()}`);
+    e.code = "rewind_snapshot.unresolvable";
+    return e;
+}
+function restoredAbsPathsOf(restored, root) {
+    const out = [];
+    for (const key of [...restored.filesChanged, ...restored.failed.map((f) => f.path)]) {
+        const abs = resolveTrackKey(root, key);
+        if (abs.ok)
+            out.push(abs.abs);
+    }
+    return out;
+}
+function rewindRefusalTail() {
+    return `Boundaries are keyed by a turn's INITIAL entry and exist only for turns that recorded history (a RunnerDeps.fileHistoryStore wired, capture on, and the run's file history not disabled); a boundary from the retired whole-tree snapshot era is not restorable by this seat, and reaped boundaries have none.`;
+}
+function beforeWithoutBoundaryRefusal(target, sessionId) {
+    const e = new Error(`rewind-files: entry "${target}" has no file-history boundary on session "${sessionId}" — a before-restore needs the target's own boundary and never crosses into an earlier turn, so the working tree was NOT rewound. ${rewindRefusalTail()}`);
+    e.code = "rewind_snapshot.unresolvable";
+    return e;
+}

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

@@ -238,9 +238,9 @@ export interface GatePass {
     hookAsk: Extract<PermissionResult, {
         action: "ask";
     }> | undefined;
-    /** borrowed-mutable — the phase-1 screen answered its own `allow` (the exact word), naming the registration that answered
-     *  it: the allow layer's hook member (its `entries`), which speaks only while no policy rewrote the arguments after the
-     *  screen saw them. Writer: the dispatch (phase 1). Reader: the lanes' allow layer (its one reader). */
+    /** borrowed-mutable — the screen answered its own `allow` (the exact word) for the bytes that run, naming the registration
+     *  that answered it: the allow layer's hook member (its `entries`). Writers: the dispatch (phase 1) and the fold's second
+     *  look after a policy rewrite (rewrite-rejudge.ts), whose answer replaces the first. Reader: the lanes' allow layer. */
     hookAllowedBy?: readonly string[];
     /** borrowed-mutable — `tool.check` was raised in this pass's first adjudication, which raises it once: set by the
      *  raise in front of the ask branch, read by the raise behind the read-only arm (it then raises nothing). Writer and

package/dist/core/runner/gate-exit.js

@@ -244,7 +244,7 @@ export function hookDenyExit(pass, deniedReason) {
         preToolContext: pass.preToolContext,
     };
 }
-const ANCESTOR_UNRESOLVED_CLASSIFICATION = classifyAsk({ action: "ask", message: "" }, { contentQuestion: false, markedUnresolvable: true, org: undefined, tightened: undefined, mandateMarks: {} });
+const ancestorUnresolvedClassification = (call) => classifyAsk({ action: "ask", message: "" }, { call, contentQuestion: false, markedUnresolvable: true, org: undefined, tightened: undefined, mandateMarks: {} });
 function unresolvableCauseOfSettlement(gate) {
     if (gate.disposition.kind !== "denied" || gate.disposition.deniedBy !== "ask_resolution" || gate.settlement === undefined)
         return undefined;
@@ -274,12 +274,13 @@ export async function exitGate(pass) {
         const tableSeat = unresolvable !== undefined ? askUnresolvableRemedySeat(unresolvable) : undefined;
         const remedySeat = tableSeat === "absent" && input.askSeatForm === "declared_none" && pass.askClassification?.classes.has("content_question") !== true ? "declared_none" : tableSeat;
         const bindingRefusal = attestationOf(pass.decision, { toolCallId, toolName })?.bindingRefusal;
-        const remedy = bindingRefusal !== undefined ? undefined : remedySeat !== undefined ? headlessApprovalRemedy({ mode: input.permissionMode?.(), classification: foldCause !== undefined ? ANCESTOR_UNRESOLVED_CLASSIFICATION : pass.askClassification, approverSeat: remedySeat, coveredWrite: isProtectedWrite(pass.req), ...(pass.shellUnplacedOptions !== undefined ? { unplacedOptions: pass.shellUnplacedOptions } : {}) }) : undefined;
+        const headless = bindingRefusal !== undefined ? undefined : remedySeat !== undefined ? headlessApprovalRemedy({ mode: input.permissionMode?.(), classification: foldCause !== undefined ? ancestorUnresolvedClassification(pass.req) : pass.askClassification, approverSeat: remedySeat, coveredWrite: isProtectedWrite(pass.req), ...(pass.shellUnplacedOptions !== undefined ? { unplacedOptions: pass.shellUnplacedOptions } : {}) }) : undefined;
+        const remedy = headless?.sentence;
         const denyReason = withParkFailureCause(`${decisionText(pass.decision) ?? `tool "${toolName}" denied by policy`}${remedy !== undefined ? ` — ${remedy}` : ""}`, pass.parkFailed, unresolvable !== undefined);
         if (unresolvable !== undefined) {
             const cause = unresolvable;
             const noticeRemedy = bindingRefusal ?? remedy;
-            pass.notifier.notify(() => input.onAskUnresolvable?.({ toolName, toolCallId, cause, parkLaneExisted: pass.suspendAsk !== undefined, ...(noticeRemedy !== undefined ? { remedy: noticeRemedy } : {}) }), "toolGate.onAskUnresolvable");
+            pass.notifier.notify(() => input.onAskUnresolvable?.({ toolName, toolCallId, cause, parkLaneExisted: pass.suspendAsk !== undefined, ...(noticeRemedy !== undefined ? { remedy: noticeRemedy } : {}), ...(headless !== undefined ? { remedies: headless.remedies } : {}) }), "toolGate.onAskUnresolvable");
         }
         const finalInput = frozenInputSnapshot(pass.currentInput);
         await notifyPermissionDenied({

package/dist/core/runner/image.d.ts

@@ -1,22 +1,12 @@
 import type { ImageContent } from "../../internal/llm.js";
+import { type HostFloor } from "../host-floor.js";
 import type { ImageInput } from "../types.js";
 /**
- * Block obviously-internal hosts (loopback / private ranges / link-local incl. cloud metadata / CGNAT / IPv6
- * ULA, site-local, unspecified, IPv4-mapped, NAT64). Classifies with `net.isIP` rather than a string-prefix
- * regex — the old regex both UNDER-matched (IPv4-mapped `::ffff:`, NAT64, CGNAT 100.64/10, `::`) and
- * OVER-matched (any DNS name starting `fc`/`fd`, e.g. `fdpartners.com`). Numeric IPv4 forms (decimal/octal/hex)
- * are normalized to dotted-decimal by `URL` before this is called, so they're already covered.
- * Note: this checks the LITERAL host; it does NOT resolve DNS, so a hostname resolving to a private IP is not
- * caught here (documented limitation — a deployment needing that supplies its own resolve-and-pin guard).
+ * The guard of a remote image URL: https only, then the one egress hop judge with the private-network floor (`hopRefusal`,
+ * host-floor.ts) — the deployment's host floor (`RunnerDeps.hostFloor`, `floor`) must admit the host, and a private host is
+ * reachable only when the floor's `only` list names it — so an end-user-supplied `images[].url` can't make the server fetch
+ * `169.254.169.254` or a private box. The host is read literally (no DNS resolution). Throws on a refused URL.
  */
-export declare function isPrivateHost(host: string): boolean;
-/**
- * Default SSRF guard for a remote image URL: https only, and no internal/reserved hosts (so an
- * end-user-supplied `images[].url` can't make the server fetch `169.254.169.254` or a private box).
- * Note: this checks the URL host literally — it does not resolve DNS, so a hostname that resolves to
- * a private IP is not caught here; a deployment needing that should supply `RunnerDeps.allowImageUrl`
- * (e.g. a CDN allowlist or a resolve-and-pin check). Throws on a disallowed URL.
- */
-export declare function defaultImageUrlGuard(raw: string): void;
+export declare function defaultImageUrlGuard(raw: string, floor?: HostFloor): void;
 /** Resolve an {@link ImageInput} (inline base64 or a URL to fetch) into a vendored `ImageContent` block. */
-export declare function toImageContent(img: ImageInput, allowUrl?: (url: string) => boolean): Promise<ImageContent>;
+export declare function toImageContent(img: ImageInput, floor: HostFloor | undefined): Promise<ImageContent>;

package/dist/core/runner/image.js

@@ -1,55 +1,10 @@
-import { isIP } from "node:net";
+import { hopRefusal } from "../host-floor.js";
 import { ADMITTED_IMAGE_MIME_TYPES, imageMagicMatches } from "../image-admission.js";
 import { admitInlineImage } from "./inline-image.js";
 function sniffImageMime(bytes) {
     return ADMITTED_IMAGE_MIME_TYPES.find((mime) => imageMagicMatches(bytes, mime));
 }
-function isPrivateV4(ip) {
-    const o = ip.split(".").map(Number);
-    if (o.length !== 4 || o.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
-        return true;
-    const [a, b] = o;
-    return (a === 127 ||
-        a === 10 ||
-        a === 0 ||
-        (a === 172 && b >= 16 && b <= 31) ||
-        (a === 192 && b === 168) ||
-        (a === 169 && b === 254) ||
-        (a === 100 && b >= 64 && b <= 127));
-}
-function embeddedV4(h) {
-    const fromHex = (hi, lo) => {
-        const a = parseInt(hi, 16), c = parseInt(lo, 16);
-        return `${(a >> 8) & 255}.${a & 255}.${(c >> 8) & 255}.${c & 255}`;
-    };
-    let m = /^(?:::ffff:|64:ff9b::)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(h);
-    if (m)
-        return m[1];
-    m = /^(?:::ffff:|64:ff9b::)([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(h);
-    if (m)
-        return fromHex(m[1], m[2]);
-    return undefined;
-}
-export function isPrivateHost(host) {
-    const h = host
-        .replace(/^\[|\]$/g, "")
-        .replace(/\.+$/, "")
-        .toLowerCase();
-    if (h === "localhost")
-        return true;
-    const fam = isIP(h);
-    if (fam === 0)
-        return false;
-    if (fam === 4)
-        return isPrivateV4(h);
-    const v4 = embeddedV4(h);
-    if (v4)
-        return isPrivateV4(v4);
-    if (h === "::1" || h === "::")
-        return true;
-    return /^fe[89ab]/.test(h) || /^f[cd]/.test(h) || /^fe[c-f]/.test(h);
-}
-export function defaultImageUrlGuard(raw) {
+export function defaultImageUrlGuard(raw, floor) {
     let u;
     try {
         u = new URL(raw);
@@ -60,9 +15,9 @@ export function defaultImageUrlGuard(raw) {
     if (u.protocol !== "https:") {
         throw new Error(`image url must be https (got "${u.protocol}")`);
     }
-    if (isPrivateHost(u.hostname)) {
-        throw new Error(`image url host not allowed (private/reserved): ${u.hostname}`);
-    }
+    const refused = hopRefusal(u, floor, true);
+    if (refused !== undefined)
+        throw new Error(`image url not fetched — ${refused}`);
 }
 const IMAGE_FETCH_TIMEOUT_MS = 30_000;
 const IMAGE_MAX_BYTES = 20 * 1024 * 1024;
@@ -112,17 +67,11 @@ async function fetchImageCapped(url) {
     }
     return { buf, mimeType: sniffed };
 }
-export async function toImageContent(img, allowUrl) {
+export async function toImageContent(img, floor) {
     if ("url" in img) {
-        if (allowUrl) {
-            if (!allowUrl(img.url)) {
-                throw new Error(`image url rejected by policy: ${img.url}`);
-            }
-        }
-        else {
-            defaultImageUrlGuard(img.url);
-        }
-        const { buf, mimeType } = await fetchImageCapped(img.url);
+        const url = img.url;
+        defaultImageUrlGuard(url, floor);
+        const { buf, mimeType } = await fetchImageCapped(url);
         return { type: "image", data: buf.toString("base64"), mimeType };
     }
     return admitInlineImage(img);

package/dist/core/runner/permission-rule-lanes.d.ts

@@ -29,11 +29,8 @@ import { type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit, t
 import type { PersistedRule, PersistedRuleVerdict, RuleOffer, ScopeRootIdentity, SegmentCoverage } from "../permission-rule-model.js";
 import { type PathRuleBases } from "../permission-rule-model.js";
 import { type HeadLeads } from "../path-rule-binding.js";
-import type { ToolCallLike } from "../tool-registry.js";
 import { type OrgRuleResolution } from "../permission-rule-org.js";
 import { type EffectivePermissionRules, type PermissionRuleStoreProvider, type PersonRowsRead } from "../permission-rule-provider.js";
-/** The one SHELL tool the persisted-rule lane's COMMAND grammar speaks for (the rule-offer face mints for it, the name tools and the host tools); the other grammars' tools are derived (`ruleToolGrammarOf`). */
-export declare const PERSISTED_RULE_TOOL = "Bash";
 /**
  * The evidence an INHERITED-lane ask carries.
  *
@@ -121,7 +118,7 @@ export interface PermissionRuleLanes {
  *  `onDegraded` receives the snapshot's degraded line ({@link describeUnreadableOrgRows}) on every adjudication over a
  *  snapshot carrying a row this layer cannot read. */
 export declare function orgRuleLane(cfg: {
-    read: (toolCallId: string) => Promise<Pick<EffectivePermissionRules, "org">>;
+    read: (toolCallId: string, judged: unknown) => Promise<Pick<EffectivePermissionRules, "org">>;
     questionToolMounted: boolean;
     questionToolName: string;
     onRevisionDefect: (message: string) => void;
@@ -177,10 +174,10 @@ export declare function createPermissionRuleLanes(cfg: {
     onRevisionDefect: (message: string) => void;
     /** Sink for a judgment against the rows that threw, and for the org lane's degraded-snapshot line. */
     onDisclosure: (message: string) => void;
-    /** The run's one reader of the person's rules: the call's ONE read, pinned, that the read station, the org lane and the
-     *  personal lane all take (the lanes consume a reader; they do not make one). */
+    /** The run's one reader of the person's rules: the call's ONE read of the bytes judged, pinned, that the read station, the
+     *  org lane and the personal lane all take (the lanes consume a reader; they do not make one). */
     rows: {
-        pin(toolCallId: string): Promise<PersonRowsRead>;
+        pin(toolCallId: string, judged?: unknown): Promise<PersonRowsRead>;
     };
     /** The allow layer's auto strip over a stored ALLOW row (true ⇒ out of this call's table BEFORE the coverage is chosen). */
     stripsAllow?: (rule: PersistedRule, req: ToolCallRequest) => boolean;
@@ -203,9 +200,12 @@ interface RuleOffersAskFacts extends RuleClearanceFacts {
  * approval-preview field is a standing example of what happens otherwise: it reached two of the
  * five, so a delegated child's card was silently poorer than the top-level one).
  *
- * Empty unless a rule lane is armed — offering an option that redemption would refuse is worse than
- * offering none — and empty for any call the lane cannot speak for (a compound, a redirection, a
- * substitution, or a tool that is not the shell tool).
+ * Silent (no offer and no reason) only where no rule speaks for the call: no lane armed, the anonymous floor,
+ * a call the lane never judges — offering an option that redemption would refuse is worse than offering none.
+ * Every other card offers the one rule its call's form mints ({@link cardRuleFormOf}: the shell card's
+ * command rules, a name or host tool's exact value rule, the whole-tool rule of a call no rule word speaks
+ * for) or names why it offers none (`lane_cannot_speak`: a compound, a redirection, a substitution, a path
+ * tool, a shell-face sibling, a tool answering to one of those under an alias).
  *
  * Empty, too, on any ask a persisted rule could never CLEAR — "allow rules silence the classifier's
  * questions, never a mandated one". Two doors, matching the two halves of that boundary:
@@ -270,7 +270,7 @@ export declare function createRuleOffersOf(cfg: {
         current: string;
     } | undefined;
     deniesDirectoryRead: ((directory: string) => boolean) | undefined;
-}): (call: Pick<ToolCallLike, "toolName" | "face">, args: unknown, ask: RuleOffersAskFacts | undefined) => {
+}): (call: Pick<ToolCallRequest, "toolName" | "face">, args: unknown, ask: RuleOffersAskFacts | undefined) => {
     ruleOffers?: readonly RuleOffer[];
     ruleOffersAbsence?: RuleOffersAbsence;
     execCwd?: string;

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

@@ -1,17 +1,18 @@
 import { persistedRuleMandateOf, ruleClearanceOf } from "../ask-origin.js";
 import {} from "../hooks.js";
-import { adjudicatePersistedDomainRules, adjudicatePersistedNameRules, adjudicatePersistedPathRules, adjudicatePersistedRules, callPathFaceOf, escapeForDisclosure, faceRowsSpeakFor, laneToolNamesOf, nameRuleSubjectOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForHost, suggestRuleForName, suggestRulesForCommand } from "../permission-rule-model.js";
+import { adjudicatePersistedDomainRules, adjudicatePersistedNameRules, adjudicatePersistedPathRules, adjudicatePersistedRules, adjudicatePersistedToolRules, callPathFaceOf, cardRuleFormOf, eligiblePersisted, escapeForDisclosure, faceRowsSpeakFor, parseRuleText, laneToolNamesOf, nameRuleSubjectOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForHost, suggestRuleForName, suggestRuleForTool, suggestRulesForCommand, wholeToolRuleReaches } from "../permission-rule-model.js";
 import { callHostTargetOf } from "../host-target.js";
 import { callTargetViewsOf, validatePath } from "../effective-path-target.js";
 import { bindPathRules, persistedRowAnchors, projectScopeIdentity } from "../path-rule-binding.js";
 import { heldBy, seatOf, wireOf } from "../tool-name-readings.js";
 import { describeUnreadableOrgRows, readOrgRules, settleOrgVerdictWithin } from "../permission-rule-org.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
+import { routesContent } from "../tool-catalog-entries.js";
 import { ownerStoreOf } from "../permission-rule-provider.js";
+import { readPrincipal } from "../principal-name.js";
 import { thrownText } from "../thrown-value.js";
 import { strongestAnswer } from "../persisted-rule-arms.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS } from "../permission-rule-org.js";
-export const PERSISTED_RULE_TOOL = "Bash";
 const NO_LEADS = new Map();
 export function inheritedAskRuleEvidence(provider) {
     const org = provider?.partitions.org === true ? "not_adjudicated" : "not_wired";
@@ -59,7 +60,7 @@ export function orgRuleLane(cfg) {
                 return { status: "available" };
             let resolution;
             try {
-                resolution = (await cfg.read(req.toolCallId)).org;
+                resolution = (await cfg.read(req.toolCallId, req.args)).org;
             }
             catch (err) {
                 return { status: "unavailable", disclosures: [`the permission-rule store threw while resolving the org partition: ${thrownText(err)}`] };
@@ -106,10 +107,10 @@ export function createPermissionRuleLanes(cfg) {
     }
     if (provider === undefined)
         return { personal: undefined, org: undefined };
-    const anonymous = cfg.principal === undefined || cfg.principal === "";
+    const anonymous = readPrincipal(cfg.principal).kind === "absent";
     const reader = cfg.rows;
-    const orgViewOf = async (toolCallId) => {
-        const read = await reader.pin(toolCallId);
+    const orgViewOf = async (toolCallId, judged) => {
+        const read = await reader.pin(toolCallId, judged);
         if (read.org === undefined)
             throw new Error(read.unreadable ?? "the store did not answer");
         return { org: read.org };
@@ -121,14 +122,26 @@ export function createPermissionRuleLanes(cfg) {
         const judged = laneToolNamesOf(req).map((n) => [n, ruleToolGrammarOf(n)]);
         if (!judged.some(([, g]) => g === "path") && faceRowsSpeakFor(callPathFaceOf(req)))
             judged.push([req.toolName, "path"]);
-        const view = await reader.pin(req.toolCallId);
-        if (judged.length === 0)
+        const view = await reader.pin(req.toolCallId, req.args);
+        const ownRow = (r) => judged.some(([n]) => n === r.tool) || wholeToolRuleReaches(r.tool, req);
+        if (judged.length === 0 && !view.rules.some(ownRow))
             return view.unreadable !== undefined ? { unreadable: true } : undefined;
         try {
-            const table = view.rules.filter((r) => r.behavior !== "allow" || cfg.stripsAllow?.(r, req) !== true);
-            const leads = judged.some(([, g]) => g === "path") ? await cfg.leads.resolve(bindPathRules(table.filter((r) => r.match === "path" || r.match === "subpath").map((r) => ({ parsed: r, ruleText: r.rule, rule: r })), (spec) => anchorsOf(spec.rule))) : NO_LEADS;
+            const stripped = view.rules.filter((r) => r.behavior !== "allow" || cfg.stripsAllow?.(r, req) !== true);
+            const judgesPath = judged.some(([, g]) => g === "path");
+            const noRule = [];
+            const table = stripped.filter((r) => {
+                const read = ownRow(r) || (judgesPath && (r.match === "path" || r.match === "subpath")) ? parseRuleText(r.rule, r.behavior) : undefined;
+                if (read !== undefined && "reject" in read)
+                    noRule.push({ row: r, why: read.reject.message });
+                return read === undefined || !("reject" in read) || r.behavior !== "allow";
+            });
+            const leads = judgesPath ? await cfg.leads.resolve(bindPathRules(table.filter((r) => r.match === "path" || r.match === "subpath").map((r) => ({ parsed: r, ruleText: r.rule, rule: r })), (spec) => anchorsOf(spec.rule))) : NO_LEADS;
             const scopeIdentity = await projectScopeIdentity(table, cfg.rootCanonical, cfg.leads);
-            const answer = strongestAnswer(judged.map(([n, grammar]) => judgeAgainst(table, { ...req, toolName: n }, grammar, leads, scopeIdentity)));
+            const wholeTool = persistedRuleAnswerOf(adjudicatePersistedToolRules(table, { request: req, cwd: cfg.root, sessionId: cfg.sessionId, ...(scopeIdentity !== undefined ? { scopeIdentity } : {}) }));
+            const judgedAnswer = strongestAnswer([...judged.map(([n, grammar]) => judgeAgainst(table, { ...req, toolName: n }, grammar, leads, scopeIdentity)), wholeTool]);
+            const unjudged = noRule.find(({ row }) => (row.behavior === "deny" || row.behavior === "ask") && eligiblePersisted(row, { tool: row.tool, cwd: cfg.root, sessionId: cfg.sessionId, ...(scopeIdentity !== undefined ? { scopeIdentity } : {}) }, row.behavior));
+            const answer = unjudged !== undefined && !(judgedAnswer !== undefined && "behavior" in judgedAnswer && judgedAnswer.behavior === "deny") ? unjudgedRowAnswer(unjudged.row, unjudged.why, req.toolName) : judgedAnswer;
             const stands = answer !== undefined && (("behavior" in answer && answer.behavior === "deny") || "unreadable" in answer);
             return view.unreadable !== undefined && !stands ? { unreadable: true } : answer;
         }
@@ -138,6 +151,11 @@ export function createPermissionRuleLanes(cfg) {
             return { unreadable: true, reason: why };
         }
     };
+    const unjudgedRowAnswer = (row, refusal, tool) => {
+        const why = `the stored ${row.behavior} rule ${escapeForDisclosure(row.rule)} is no rule this engine reads (${refusal})`;
+        cfg.onDisclosure(`the persisted rule lane could not judge a ${tool} call against the rows it read — ${why}`);
+        return { unreadable: true, reason: why };
+    };
     const anchorsOf = (rule) => persistedRowAnchors(rule.scope, cfg.chainTop);
     const judgeAgainst = (table, req, grammar, leads, scopeIdentity) => {
         const liveCwd = cfg.liveCwd();
@@ -164,11 +182,9 @@ export function createPermissionRuleLanes(cfg) {
 export function createRuleOffersOf(cfg) {
     return (call, args, ask) => {
         const toolName = wireOf("offer.laneTool", call);
-        const grammar = ruleToolGrammarOf(toolName);
-        if (!cfg.laneArmed || (toolName !== PERSISTED_RULE_TOOL && grammar !== "name" && grammar !== "domain"))
-            return {};
-        if ((cfg.principal === undefined || cfg.principal === "") && !cfg.localOwnerDeclared)
+        if (!cfg.laneArmed || (readPrincipal(cfg.principal).kind === "absent" && !cfg.localOwnerDeclared) || routesContent(call.face))
             return {};
+        const form = cardRuleFormOf(toolName, call);
         const tierSeat = seatOf("offer.marks", cfg.irreversibilityTier, call);
         const closedDoor = ruleClearanceOf(ask, {
             egress: heldBy("offer.marks.egress", cfg.egressTools, call),
@@ -177,11 +193,17 @@ export function createRuleOffersOf(cfg) {
         }).word;
         if (closedDoor !== undefined)
             return { ruleOffersAbsence: closedDoor };
-        if (grammar === "name") {
+        if (form === "tool") {
+            const offer = suggestRuleForTool(toolName);
+            return offer !== undefined ? { ruleOffers: [offer] } : { ruleOffersAbsence: "lane_cannot_speak" };
+        }
+        if (form === undefined)
+            return { ruleOffersAbsence: "lane_cannot_speak" };
+        if (form === "name") {
             const offer = suggestRuleForName(toolName, nameRuleSubjectOf(toolName, args) ?? "");
             return offer !== undefined ? { ruleOffers: [offer] } : { ruleOffersAbsence: "lane_cannot_speak" };
         }
-        if (grammar === "domain") {
+        if (form === "domain") {
             const host = callHostTargetOf({ toolName: call.toolName, args, face: call.face }, "grant");
             const offer = host !== undefined && "host" in host ? suggestRuleForHost(toolName, host.host) : undefined;
             return offer !== undefined ? { ruleOffers: [offer] } : { ruleOffersAbsence: "lane_cannot_speak" };

package/dist/core/runner/person-path-rows.d.ts

@@ -1,12 +1,13 @@
 /**
  * The person's persisted rules as ONE run reads them.
  *
- * ## One read per adjudicated call
+ * ## One read per judgment of a call's bytes
  *
- * A call is judged against ONE read of the store, pinned to its `toolCallId` ({@link PersonPathRows.pin}): whichever of the
- * call's consumers asks first — the read station's judgment, the org layer, the personal rule lane — takes the read, the
- * others are handed the same answer, and the tables the call's tool judges with when it executes are compiled from it
- * ({@link PathTablesFacade.forCall}). A call is an attempt the leg's occurrence table holds; the pin is released when the
+ * A call's bytes are judged against ONE read of the store, pinned to its `toolCallId` ({@link PersonPathRows.pin}): whichever
+ * of the consumers judging those bytes asks first — the read station's judgment, the org layer, the personal rule lane —
+ * takes the read, the others are handed the same answer, and the tables the call's tool judges with when it executes are
+ * compiled from it ({@link PathTablesFacade.forCall}). Judging other bytes of the same call (an approved edit) is another
+ * judgment: it takes a new read, which the call then holds — a rule written while a person decided binds their edit. A call is an attempt the leg's occurrence table holds; the pin is released when the
  * table no longer holds that attempt. A judgment that is no call of the leg (a visibility probe's fixed id, a gate with no
  * leg) keeps nothing: its rule lanes take a read of their own, its read station the run's latest tables.
  *
@@ -106,10 +107,12 @@ export interface PersonPathRows {
     readonly holdsPersonRows: boolean;
     /** The prepare read — the unit's first write. `undefined`, synchronously, when there is no person's rows to read. */
     prime(): Promise<void> | undefined;
-    /** The rows of a call's one read — a call the leg's occurrence table holds: taken by its first consumer, handed to every
-     *  other until the table no longer holds that attempt; any other judgment (no leg, or an id the table does not hold — a
-     *  visibility probe) takes a read of its own, kept by nobody. Bounded ({@link PERSON_READ_BOUND_MS}); never rejects. */
-    pin(toolCallId: string): Promise<PersonRowsRead>;
+    /** The rows of a call's one read of the bytes it judges (`judged`) — a call the leg's occurrence table holds: taken by its
+     *  first consumer, handed to every other that judges the same bytes (or names none) until the table no longer holds that
+     *  attempt; a judgment of OTHER bytes of the call (an approved edit, its outlet form) takes a new read, which the call then
+     *  holds — a judgment reads the store, as the session rules' does. Any other judgment (no leg, or an id the table does not
+     *  hold — a visibility probe) takes a read of its own, kept by nobody. Bounded ({@link PERSON_READ_BOUND_MS}); never rejects. */
+    pin(toolCallId: string, judged?: unknown): Promise<PersonRowsRead>;
     /** Settles once the tables a reader takes are compiled: a pinned call's own; any other reader's (no id, or a call holding
      *  no pin), the unit's newest — through every change that lands meanwhile, within {@link PATH_TABLES_READY_BOUND_MS} —
      *  or at `signal` or the run's cut ({@link PersonPathRowsConfig.signal}). Never rejects: a reader whose wait was cut

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

@@ -1,5 +1,7 @@
 import { ownerStoreOf } from "../permission-rule-provider.js";
+import { readPrincipal } from "../principal-name.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS } from "../permission-rule-org.js";
+import { canonicalize } from "../canonical-json.js";
 import { PATH_RULE_FACES, READ_RULE_TOOL, eligiblePersisted, noticeRuleText } from "../permission-rule-model.js";
 import { bindPathRules, persistedRowAnchors, projectScopeIdentity } from "../path-rule-binding.js";
 import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, gateWaitFailureOf, withGateTimeout } from "../gate-bounded-await.js";
@@ -21,7 +23,7 @@ const COMPILED_TABLES_KEPT = 8;
 export const EMPTY_READ_ROOTS = Object.assign(() => [], { forCall: () => () => [], ready: () => Promise.resolve() });
 export function createPersonPathRows(cfg) {
     const provider = cfg.provider;
-    const anonymous = cfg.principal === undefined || cfg.principal === "";
+    const anonymous = readPrincipal(cfg.principal).kind === "absent";
     const holdsPersonRows = provider !== undefined && provider.partitions.durable && (!anonymous || cfg.localOwnerDeclared);
     const partitions = PARTITIONS.filter((p) => (p === "durable" ? provider?.partitions.durable === true : provider?.partitions.session === true));
     const unit = { durable: { failedSeq: 0 }, session: { failedSeq: 0 } };
@@ -186,20 +188,29 @@ export function createPersonPathRows(cfg) {
         pins.delete(toolCallId);
         return undefined;
     };
-    const enter = (toolCallId, attempt) => {
+    const enter = (toolCallId, attempt, judged) => {
         const rows = readOnce("call").then((read) => (entry.read = read));
-        const entry = { attempt, rows, tables: holdsPersonRows ? rows.then((read) => settleTables(entry, read)) : Promise.resolve(), ...(holdsPersonRows ? {} : { settled: {} }) };
+        const entry = { attempt, rows, tables: holdsPersonRows ? rows.then((read) => settleTables(entry, read)) : Promise.resolve(), ...(holdsPersonRows ? {} : { settled: {} }), ...(judged !== undefined ? { judged: { value: judged } } : {}) };
         pins.set(toolCallId, entry);
         return entry;
     };
-    const pin = (toolCallId) => {
+    const serves = (p, judged) => {
+        if (judged === undefined || p.judged === undefined || p.judged.value === judged)
+            return true;
+        p.judged.canonical ??= canonicalize(p.judged.value);
+        return p.judged.canonical === canonicalize(judged);
+    };
+    const pin = (toolCallId, judged) => {
         for (const id of [...pins.keys()])
             pinOf(id);
         const known = pinOf(toolCallId);
-        if (known !== undefined)
+        if (known !== undefined && serves(known, judged)) {
+            if (judged !== undefined)
+                known.judged ??= { value: judged };
             return known.rows;
+        }
         const attempt = cfg.occurrences?.get(toolCallId);
-        return attempt === undefined ? readOnce("call") : enter(toolCallId, attempt).rows;
+        return attempt === undefined ? readOnce("call") : enter(toolCallId, attempt, judged).rows;
     };
     const settleTables = async (entry, read) => {
         try {
@@ -317,7 +328,7 @@ export function onPinnedRead(rows, stations) {
             const id = callOpts.toolCallId;
             if (readStationMemberOf(call, members) === undefined)
                 return check.judge(call, args, cwd, signal, callOpts);
-            const ready = id !== undefined && rows.holds(id) ? rows.pin(id).then(() => rows.tablesReady(id)) : rows.tablesReady(undefined, signal);
+            const ready = id !== undefined && rows.holds(id) ? rows.pin(id, args).then(() => rows.tablesReady(id)) : rows.tablesReady(undefined, signal);
             return ready.then(() => check.judge(call, args, cwd, signal, callOpts) ?? VOUCHED);
         },
         unanswered: (call, cause) => check.unanswered(call, cause),

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

@@ -24,6 +24,7 @@ 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";
+import { type LegWrites } from "./session-write-ledger.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
@@ -54,6 +55,8 @@ export interface PrepareAcquireReconcileInput {
     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;
+    /** borrowed-mutable (the Runner's) — this leg's view of the session write ledger, every storage write issued through it ({@link writesThroughLeg}); absent for a standalone prepare. */
+    legWrites?: LegWrites;
 }
 /** 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