@sema-agent/core 7.9.2 → 7.11.0

package/dist/core/shell-lexer.js

@@ -13,11 +13,13 @@ const ALL_OPS = [...CONNECTOR_OPS, ...REDIRECT_OPS];
 export const MAX_SHELL_READ_CHARS = 10_000;
 export function readShellCommand(source) {
     if (source.length > MAX_SHELL_READ_CHARS)
-        return { segments: [{ argv: [], peeled: [], unreadable: `the command is longer than ${MAX_SHELL_READ_CHARS} characters — not read` }], connectors: [], grouped: false };
+        return { segments: [{ argv: [], redirections: [], peeled: [], unreadable: `the command is longer than ${MAX_SHELL_READ_CHARS} characters — not read` }], connectors: [], grouped: false, backgrounded: false, strayRedirection: false };
     const segments = [];
     const connectors = [];
     let grouped = false;
-    let seg = { words: [] };
+    let backgrounded = false;
+    let strayRedirection = false;
+    let seg = { words: [], redirections: [] };
     let word = freshWord();
     let pendingRedirect;
     let heredocs = [];
@@ -40,6 +42,7 @@ export function readShellCommand(source) {
                     badDelimiter = true;
                 heredocs.push({ delimiter: word.text, quoted: word.raw !== word.text, dash: pendingRedirect === "<<-" });
             }
+            seg.redirections.push({ op: pendingRedirect, target: publicWord(word) });
             pendingRedirect = undefined;
         }
         else {
@@ -56,17 +59,19 @@ export function readShellCommand(source) {
         let built = buildSegment(seg);
         if (built === "keyworded")
             grouped = true;
+        if ((built === "empty" || built === "keyworded") && seg.redirections.length > 0)
+            strayRedirection = true;
         if (built === "empty" || built === "keyworded") {
             const continuation = connector === "\n" && lastConnector !== undefined && lastConnector !== ";" && lastConnector !== "&" && lastConnector !== "\n";
             const legal = built === "keyworded" || afterBoundary || connector === undefined || connector === "\n" || lastConnector === "\n";
             if (!legal)
-                built = { argv: [], peeled: [], unreadable: `an empty command before \`${connector}\` — a syntax error` };
+                built = { argv: [], redirections: seg.redirections, peeled: [], unreadable: `an empty command before \`${connector}\` — a syntax error` };
             else {
                 if (connector !== undefined && connector !== "\n" && segments.length > 0)
                     grouped = true;
                 if (connector !== undefined && !continuation)
                     lastConnector = connector;
-                seg = { words: [] };
+                seg = { words: [], redirections: [] };
                 afterBoundary = false;
                 return;
             }
@@ -76,7 +81,7 @@ export function readShellCommand(source) {
         segments.push(built);
         if (connector !== undefined)
             lastConnector = connector;
-        seg = { words: [] };
+        seg = { words: [], redirections: [] };
         afterBoundary = false;
     };
     const boundary = () => { finishSegment(undefined); grouped = true; afterBoundary = true; lastConnector = undefined; };
@@ -187,6 +192,8 @@ export function readShellCommand(source) {
                     i += op.length;
                     continue;
                 }
+                if (op === "&")
+                    backgrounded = true;
                 finishSegment(op);
                 i += op.length;
                 continue;
@@ -271,7 +278,7 @@ export function readShellCommand(source) {
             seg.unreadable ??= `the connector \`${lastConnector}\` has no command after it — a syntax error`;
         finishSegment(undefined);
     }
-    return { segments, connectors, grouped };
+    return { segments, connectors, grouped, backgrounded, strayRedirection };
 }
 const publicWord = ({ text, raw, expands }) => ({ text, raw, expands });
 const SUBSTITUTION_UNREAD = "a command substitution runs a program this reader does not read";
@@ -281,8 +288,8 @@ export function isFullyReadable(shape) {
 }
 function buildSegment(seg) {
     if (seg.unreadable !== undefined)
-        return { argv: seg.words.map(publicWord), peeled: [], unreadable: seg.unreadable };
-    const carried = () => (seg.substitution === true ? { argv: [], peeled: [], peelUnreadable: SUBSTITUTION_UNREAD } : keyworded ? "keyworded" : "empty");
+        return { argv: seg.words.map(publicWord), redirections: seg.redirections, peeled: [], unreadable: seg.unreadable };
+    const carried = () => (seg.substitution === true ? { argv: [], redirections: seg.redirections, peeled: [], peelUnreadable: SUBSTITUTION_UNREAD } : keyworded ? "keyworded" : "empty");
     let keyworded = false;
     let k0 = 0;
     while (k0 < seg.words.length && seg.words[k0].expands === false && (PREFIX_KEYWORDS.has(seg.words[k0].text) || CLOSING_KEYWORDS.has(seg.words[k0].text))) {
@@ -298,7 +305,7 @@ function buildSegment(seg) {
     if (head.expands === false && (head.text === "[[" || head.text === "["))
         return carried();
     if (head.expands === false && OPAQUE_KEYWORDS.has(head.text))
-        return { argv: words.map(publicWord), peeled: [], unreadable: `a \`${head.text}\` control structure — its commands need a syntax tree` };
+        return { argv: words.map(publicWord), redirections: seg.redirections, peeled: [], unreadable: `a \`${head.text}\` control structure — its commands need a syntax tree` };
     const argv = words.map(publicWord);
     const peeled = [];
     let peelUnreadable;
@@ -338,7 +345,7 @@ function buildSegment(seg) {
     }
     if (seg.substitution === true || [argv, ...peeled].some((c) => c[0]?.expands === false && evaluatesOperand(c)))
         peelUnreadable ??= SUBSTITUTION_UNREAD;
-    return { argv, peeled, ...(peelUnreadable !== undefined ? { peelUnreadable } : {}) };
+    return { argv, redirections: seg.redirections, peeled, ...(peelUnreadable !== undefined ? { peelUnreadable } : {}) };
 }
 function unwrap(words) {
     const head = words[0];

package/dist/core/shell-wrapper-table.js

@@ -50,9 +50,12 @@ export function evaluatesOperand(run) {
     return run.some((w) => namesArrayElement(w.text) || namesArrayElement(w.raw) || (integer && /^[A-Za-z_][A-Za-z0-9_]*\+?=.*[A-Za-z_$]/.test(w.text)));
 }
 function namesArrayElement(word) {
-    const open = word.indexOf("[");
-    if (open <= 0 || !/[A-Za-z0-9_]/.test(word[open - 1]))
-        return false;
-    const close = word.indexOf("]", open);
-    return close > 0 && /[A-Za-z_$]/.test(word.slice(open + 1, close));
+    for (let open = word.indexOf("["); open > 0; open = word.indexOf("[", open + 1)) {
+        if (!/[A-Za-z0-9_]/.test(word[open - 1]))
+            continue;
+        const close = word.indexOf("]", open);
+        if (close > 0 && /[A-Za-z_$]/.test(word.slice(open + 1, close)))
+            return true;
+    }
+    return false;
 }

package/dist/core/swappable-deps.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The deployment seats a Runner may HOT-SWAP after construction — the vocabulary behind the ONE door,
+ * `Runner.swapDeps` (runtask.ts).
+ *
+ * WHY ONE DOOR. Each hot-swappable seat used to be a verb of its own (`swapModels` was the first), and a
+ * verb per seat restates the same three laws every time — validate the candidate BEFORE anything is
+ * written, write the deps object ONCE (a swap is atomic: a refused candidate leaves the current deps
+ * byte-identical), announce the change under a notice code — while the question "which seats may be
+ * swapped at all" was answered by the list of verbs, i.e. by nothing a compiler could see. With one door
+ * the laws are stated once, the swappable set is THIS closed list, and every seat carries its rows in
+ * the tables beside it: the compiler refuses a member without its rows ({@link AssertAllKeysHandled}),
+ * the door refuses a key outside the set at run time (never a silent ignore — a hot-config driver
+ * handing `{ brain }` must learn that the brain is not a swappable seat, not watch nothing happen).
+ *
+ * WHAT A SWAP MEANS — the natural snapshot, one sentence for every seat: a running task reads the deps
+ * object it was handed at its prepare and holds that reference; a swap replaces the Runner's object, so
+ * every LATER prepare reads the new seat and every in-flight leg keeps the value it prepared under.
+ * Nothing is re-routed, re-priced or re-fenced mid-run; the divergence window is exactly the in-flight
+ * legs' lifetime, by design (the `swapModels` precedent, now the rule for the whole set).
+ *
+ * KEY PRESENCE IS THE INSTRUCTION: a key present on the candidate is REPLACED (an explicit `undefined`
+ * CLEARS an optional seat back to its engine default — `readFace: undefined` ⇒ the deployment declares
+ * no read face, `tiers: undefined` ⇒ no tier bindings); a key absent is KEPT. `Object.hasOwn`, never
+ * truthiness, so the two spellings cannot be confused. An EMPTY candidate is refused: a swap that names
+ * no seat is a caller defect, not a no-op.
+ */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { RunnerDeps } from "./runner-deps.js";
+/**
+ * The closed set of hot-swappable deployment seats.
+ *  - `models`   — the model catalog generation (the same-name redirect, re-pricing and retirement rules
+ *                 of the former `swapModels`: a string ref resolves against the new catalog at the next
+ *                 prepare; a `Model` object a leg already holds is untouched).
+ *  - `tiers`    — the tier bindings, a BINDING OVER a catalog: it may only be swapped together with
+ *                 `models` (the door refuses `tiers` alone — re-expanding bindings over an already
+ *                 expanded catalog would keep the retired tier words as ordinary keys, which is exactly
+ *                 the stale-generation shape the swap exists to end). Omitted beside `models` ⇒ the
+ *                 current bindings are re-applied over the new catalog; present (including `undefined`)
+ *                 ⇒ replaced.
+ *  - `readFace` — the deployment's read-face declaration ({@link RunnerDeps.readFace}); screened by the
+ *                 same value gate every prepare applies (`assertReadFaceValue`: `"open"` | `"roots"`
+ *                 | absent, anything else refused loudly). The RESOLVED face of a leg is still the
+ *                 resolver's business (task seat, governance, the read-only mount); the swap changes the
+ *                 deployment seat that resolution reads.
+ */
+export declare const SWAPPABLE_DEP_SEATS: readonly ["models", "tiers", "readFace"];
+export type SwappableDepSeat = (typeof SWAPPABLE_DEP_SEATS)[number];
+/** The candidate a swap takes: the swappable seats of {@link RunnerDeps}, each optional (presence = instruction). */
+export type SwappableDeps = Pick<RunnerDeps, SwappableDepSeat>;
+/** Whether a key names a swappable seat. */
+export declare function isSwappableDepSeat(k: unknown): k is SwappableDepSeat;
+/**
+ * Which notice a seat's successful swap is announced under — the disposition table over the set (a seat
+ * with no row does not compile: {@link SwapNoticeTableCoversEverySeat}). `models` and `tiers` share the
+ * catalog-generation line (one swap, one line, both counts); the read face has its own.
+ */
+export declare const SWAP_SEAT_NOTICE: {
+    readonly models: "config.models_swapped";
+    readonly tiers: "config.models_swapped";
+    readonly readFace: "config.read_face_swapped";
+};
+/** The fence over the notice table: `never` while every seat has a row. */
+export type SwapNoticeTableCoversEverySeat = AssertAllKeysHandled<Exclude<SwappableDepSeat, keyof typeof SWAP_SEAT_NOTICE>>;
+/** What the screen hands back: the seats present (set order) and the ONE read of each present seat's value,
+ *  copied at screen time — the door writes from THIS object and never re-reads the caller's. */
+export interface ScreenedSwappableDeps {
+    readonly seats: readonly SwappableDepSeat[];
+    /** A fresh plain object: the screened value of every present seat (`models`/`tiers` shallow-copied,
+     *  `readFace` the screened word; an explicit `undefined` is kept as a PRESENT own key so the door can
+     *  tell "clear this seat" from "not named"). */
+    readonly candidate: SwappableDeps;
+}
+/**
+ * Screen a swap candidate BEFORE anything is written: the object shape, the key set (every own key must
+ * be a member of {@link SWAPPABLE_DEP_SEATS}; at least one), the `tiers`-rides-with-`models` rule, and
+ * each present seat's own value gate. Returns the seats present (set order) and a SNAPSHOT of their values
+ * — the one read. Throws on the first defect; the caller has written nothing yet, so the current deps stay
+ * in force byte-identical.
+ *
+ * ONE READ, BY CONSTRUCTION: every seat value is read off the caller's object exactly once, here, and the
+ * screened copy is what the door writes and announces. A getter-backed or concurrently-mutated candidate
+ * therefore cannot present a legal value to the screen and a different one to the write (or to the
+ * announcement, which runs AFTER the write — a throw there would have left a half-announced swap in
+ * force). The prepare doors read their deps seats the same way.
+ *
+ * The per-seat gate is the SAME one the seat's prepare-time reader applies (`readFace` ⇒
+ * `assertReadFaceValue` with the deployment-seat name a prepare door uses — one value, one loudness, one
+ * seat name on every leg), so a value the door admits is a value every later prepare admits.
+ */
+export declare function screenSwappableDeps(next: unknown): ScreenedSwappableDeps;

package/dist/core/swappable-deps.js

@@ -0,0 +1,55 @@
+import { assertReadFaceValue } from "../tools/fs/read-face.js";
+export const SWAPPABLE_DEP_SEATS = ["models", "tiers", "readFace"];
+const SWAPPABLE_DEP_SEAT_SET = new Set(SWAPPABLE_DEP_SEATS);
+export function isSwappableDepSeat(k) {
+    return SWAPPABLE_DEP_SEAT_SET.has(k);
+}
+export const SWAP_SEAT_NOTICE = {
+    models: "config.models_swapped",
+    tiers: "config.models_swapped",
+    readFace: "config.read_face_swapped",
+};
+export function screenSwappableDeps(next) {
+    if (next === null || typeof next !== "object" || Array.isArray(next)) {
+        throw new Error(`swapDeps: the candidate must be a plain object naming the seats to swap (got ${next === null ? "null" : Array.isArray(next) ? "array" : typeof next}) — the current deps stay in force`);
+    }
+    const keys = Object.keys(next);
+    const unknown = keys.filter((k) => !isSwappableDepSeat(k));
+    if (unknown.length > 0) {
+        throw new Error(`swapDeps: ${unknown.map((k) => JSON.stringify(k)).join(", ")} is not a hot-swappable seat (the closed set is ${SWAPPABLE_DEP_SEATS.join(" | ")}) — the current deps stay in force`);
+    }
+    const present = SWAPPABLE_DEP_SEATS.filter((seat) => Object.hasOwn(next, seat));
+    if (present.length === 0) {
+        throw new Error(`swapDeps: the candidate names no seat (an empty swap is a caller defect, not a no-op) — the current deps stay in force`);
+    }
+    const raw = next;
+    const candidate = {};
+    for (const seat of present) {
+        const v = raw[seat];
+        switch (seat) {
+            case "models":
+                if (v === null || typeof v !== "object" || Array.isArray(v)) {
+                    throw new Error(`swapDeps: models must be a plain Record<string, Model> (got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}) — the current generation stays in force`);
+                }
+                candidate.models = { ...v };
+                break;
+            case "tiers":
+                if (!present.includes("models")) {
+                    throw new Error(`swapDeps: tiers is a binding over models — pass the catalog it binds in the same swap (\`{ models, tiers }\`); the current generation stays in force`);
+                }
+                if (v !== undefined && (v === null || typeof v !== "object" || Array.isArray(v))) {
+                    throw new Error(`swapDeps: tiers must be a plain Record<string, ModelRef> or undefined (got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v}) — the current generation stays in force`);
+                }
+                candidate.tiers = v === undefined ? undefined : { ...v };
+                break;
+            case "readFace":
+                candidate.readFace = assertReadFaceValue(v, "readFace (deployment seat)");
+                break;
+            default: {
+                const _exhaustive = seat;
+                throw new Error(`swapDeps: unhandled seat ${String(_exhaustive)}`);
+            }
+        }
+    }
+    return { seats: present, candidate: candidate };
+}

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

@@ -99,7 +99,10 @@ export interface ToolCallRequest {
  *   - `"org_unavailable"` — an org-governed deployment could not adjudicate against a snapshot, so the
  *     whole decision boundary failed closed (see `ORG_UNAVAILABLE_DECISION_REASON`, the single
  *     spelling this word is minted from). */
-declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
+/** `read_only` (#619): the shell tool's command was PROVABLY read-only by the engine's transcribed upstream
+ *  tables (`readOnlyShellVerdict`) and the allow layer let it run without a question — after every
+ *  deny/ask lane and the person's own allow rules, never over a mandated ask. */
+declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
 export type DecisionReason = (typeof DECISION_REASONS)[number];
 /** Read the engine-attested settlement off a funneled decision FOR the named call (the gate's exit is the
  *  one consumer): an attestation bound to a different call is a replayed object and answers absence.
@@ -204,6 +207,23 @@ export type PermissionResult = {
      *  same safe direction as `matchedAskRule`); it cannot state a window of its own, because the
      *  route it would be a window for has not been chosen yet. */
     denialLimitFallback?: import("./auto-mode.js").UnarmedDenialLimitFallback;
+    /** #616 (additive): the auto-mode classifier was CONSULTED on this ask and could not run — the ask
+     *  flows the original chain exactly as it would have (routing, origin, bit and members unchanged),
+     *  carrying the station FACT beside them so a card can say "asked because the classifier was
+     *  unavailable (timeout)" instead of reading as ordinary hesitation. `cause` is the verdict's own
+     *  word ({@link import("./auto-mode.js").AutoModeUnavailableCause}: `error` / `timeout` /
+     *  `breaker_open`). A FACT, not an origin: CC 2.1.250 marks the same condition as a denial KIND on
+     *  the outcome (`automode-unavailable`) beside the decision's provenance, never in place of it, and
+     *  this engine's divergence (the ask reaches a person instead of being denied) does not move the
+     *  fact onto the origin axis either. ENGINE-STAMPED at the classifier stations (the gate's own and
+     *  the inherited-lane arms) only when the verdict was `unavailable`; `parse_error` stamps nothing
+     *  (the classifier ran and answered outside its contract — a different sentence). Display metadata:
+     *  nothing reads it to decide anything, so a policy that self-declares it can only put its own
+     *  sentence on its own card. Carried onto the approval request and the durable row by the carry
+     *  stations. */
+    classifierUnavailable?: {
+        readonly cause: import("./auto-mode.js").AutoModeUnavailableCause;
+    };
     /** #144 disclosure (additive): a persisted allow rule MATCHED this call but could not clear the
      *  ask, because the ask is MANDATED (operator shellGate:"always", or the tool's own
      *  egress/irreversibility marks) rather than a classifier's hesitation — "allow rules silence
@@ -1191,6 +1211,15 @@ export interface AskRequest {
      *  that forwards a decision's member here does not compile, which is the point: the window is the
      *  route's fact, and forwarding it silently is how a configured window becomes a wait with none. */
     readonly denialLimitFallback?: import("./auto-mode.js").DenialLimitFallback;
+    /** #616 (additive) — present ⇔ the auto-mode classifier was consulted on this ask and could not run (see
+     *  the {@link PermissionResult} ask-arm member of the same name): the card's "asked because the
+     *  classifier was unavailable" fact, with the verdict's own cause word. Absent on every ask the classifier
+     *  answered, was not eligible for, or was not wired for — read presence, never absence. Filled by the
+     *  carry stations from the decision, never a caller/worker-settable field; the durable park row carries
+     *  the same member (`PendingAction.tool_approval.classifierUnavailable`). */
+    readonly classifierUnavailable?: {
+        readonly cause: import("./auto-mode.js").AutoModeUnavailableCause;
+    };
     /** (additive) WHICH AUTHORITY raised this ask — the wire twin of the {@link PermissionResult} ask-arm
      *  member of the same name, one word from the closed {@link import("./ask-origin.js").AskOrigin} set.
      *  The gate's own mint station copies the engine-stamped word; the three inherited-lane stations

package/dist/core/tool-policy.js

@@ -10,7 +10,7 @@ import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./unt
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
 import { protocolOf } from "./protocol-table.js";
 import { isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
-const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
+const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
 const DECISION_REASON_SET = new Set(DECISION_REASONS);
 function settledByNobody(kind) {
     return { kind, who: { party: "none" }, when: Date.now() };
@@ -410,6 +410,7 @@ export function combinePolicies(...policies) {
             let ruleAskText;
             let probeMandateSeen = false;
             let fallbackSeen;
+            let classifierUnavailableSeen;
             for (const p of policies) {
                 const d = refuseOutOfContractDecision(await p.check(current, signal));
                 if (d.action === "deny") {
@@ -440,13 +441,16 @@ export function combinePolicies(...policies) {
                     probeMandateSeen = true;
                 if (d.action === "ask" && d.denialLimitFallback !== undefined && fallbackSeen === undefined)
                     fallbackSeen = d.denialLimitFallback;
+                if (d.action === "ask" && d.classifierUnavailable !== undefined && classifierUnavailableSeen === undefined)
+                    classifierUnavailableSeen = d.classifierUnavailable;
             }
             if (asked) {
                 const merged = rewrite?.updatedInput;
                 const withRuleAsk = ruleAskText !== undefined && asked.matchedAskRule === undefined ? { ...asked, matchedAskRule: ruleAskText } : asked;
                 const withMark = probeMandateSeen && withRuleAsk.probeMandated !== true ? { ...withRuleAsk, probeMandated: true } : withRuleAsk;
                 const withFallback = fallbackSeen !== undefined && withMark.denialLimitFallback === undefined ? { ...withMark, denialLimitFallback: fallbackSeen, requiresRealApproval: true } : withMark;
-                return merged !== undefined ? { ...withFallback, updatedInput: merged } : withFallback;
+                const withFact = classifierUnavailableSeen !== undefined && withFallback.classifierUnavailable === undefined ? { ...withFallback, classifierUnavailable: { cause: classifierUnavailableSeen.cause } } : withFallback;
+                return merged !== undefined ? { ...withFact, updatedInput: merged } : withFact;
             }
             const allowed = rewrite ?? ALLOW;
             if (settledAllow === undefined)

package/dist/core/tools.d.ts

@@ -15,14 +15,34 @@ export declare function errorResult(text: string, details?: unknown): {
     isError: true;
     details?: unknown;
 };
-/** True iff `x` is an `AgentTool` this module's `defineTool` itself constructed — see {@link DEFINE_TOOL_BRAND}. */
+/** The seat's function: the mount's ctx builder and the very object being mounted (the seal compares it to the stamped one). */
+type DefineToolRebind = (enrich: ToolCtxEnricher, mounted: object) => AgentTool;
+/** True iff `x` is an `AgentTool` this module's `defineTool` itself constructed — see {@link DEFINE_TOOL_BRAND}.
+ *  An OWN property read: an object that merely INHERITS the brand (`Object.create(product)`, a Proxy over it)
+ *  is not the product — the rebind seat would rebuild the product and drop whatever the derived object
+ *  overrode, so such objects are not recognised here and fall to the spec arm's contract (which they do not
+ *  meet either; see {@link stampDefineToolBrand} for the one supported wrapper form). */
 export declare function isDefineToolProduct(x: unknown): x is AgentTool;
-/** RB-362 类修同源章点 — the ONE place the brand is stamped. `defineTool` uses it on its own product;
- *  the only OTHER legitimate caller is a wrapper that (a) starts from a branded product and (b)
- *  preserves the AgentTool `execute(toolCallId, rawParams, signal, onUpdate)` contract faithfully
- *  (e.g. teacher.ts's logging wrapper). A shallow copy that does NOT re-stamp deliberately loses the
- *  brand — that is the brand's documented survival contract, not an accident. Internal only. */
-export declare function stampDefineToolBrand<T extends object>(tool: T): T;
+/** RB-362 类修同源章点 — the ONE place the brand is stamped, and with it the rebind seat (a branded object
+ *  ALWAYS carries one; that invariant is what lets the caller mount rebind every product without a
+ *  "cannot enrich" arm). `defineTool` uses it on its own product; the only OTHER legitimate caller is a
+ *  wrapper that (a) starts from a branded product, (b) preserves the AgentTool
+ *  `execute(toolCallId, rawParams, signal, onUpdate)` contract faithfully and (c) hands over a `rebind`
+ *  that re-wraps the REBOUND inner product the same way (e.g. teacher.ts's logging wrapper) — so a mount
+ *  rebinding the wrapper gets a wrapper over an enriched product, not an enriched product without the
+ *  wrapper. A shallow copy that does NOT re-stamp deliberately loses the brand — that is the brand's
+ *  documented survival contract, not an accident. Internal only. */
+export declare function stampDefineToolBrand<T extends object>(tool: T, rebind: DefineToolRebind): T;
+/**
+ * A branded product REBOUND to a mount's ctx builder — the product's own `execute` rebuilt over its own
+ * spec with `enrich` applied per call (see {@link ToolCtxEnricher}; a builder the product was built with
+ * runs AFTER the mount's, refining the run's trusted seats, and the per-call identity is re-stamped after
+ * both). This is how a `defineTool()` product handed to `TaskSpec.tools` receives exactly the ctx a raw
+ * `ToolSpec` on the same mount receives: one mount law, whatever object shape the caller handed in.
+ * Throws on an unbranded object — the caller checks {@link isDefineToolProduct} first; a branded object
+ * without the seat cannot be constructed (both are written at the one stamp site).
+ */
+export declare function rebindDefineToolCtx(product: AgentTool, enrich: ToolCtxEnricher): AgentTool;
 /**
  * RB-409 — a per-call ctx builder a MOUNT hands to {@link defineTool}.
  *
@@ -58,3 +78,4 @@ export interface DefineToolOptions {
 }
 /** Adapt a friendly ToolSpec into the vendored AgentTool the agent loop expects. */
 export declare function defineTool<TParams extends TSchema = TSchema>(spec: ToolSpec<TParams>, options?: DefineToolOptions): AgentTool<TParams>;
+export {};

package/dist/core/tools.js

@@ -26,13 +26,46 @@ export function errorResult(text, details) {
     return details === undefined ? { content: text, isError: true } : { content: text, isError: true, details };
 }
 const DEFINE_TOOL_BRAND = Symbol("sema.core.defineTool.product");
+const DEFINE_TOOL_REBIND = Symbol("sema.core.defineTool.rebind");
 export function isDefineToolProduct(x) {
-    return typeof x === "object" && x !== null && x[DEFINE_TOOL_BRAND] === true;
+    return typeof x === "object" && x !== null && Object.getOwnPropertyDescriptor(x, DEFINE_TOOL_BRAND)?.value === true;
 }
-export function stampDefineToolBrand(tool) {
+export function stampDefineToolBrand(tool, rebind) {
     Object.defineProperty(tool, DEFINE_TOOL_BRAND, { value: true, enumerable: false });
+    Object.defineProperty(tool, DEFINE_TOOL_REBIND, { value: sealedRebind(tool, rebind), enumerable: false });
     return tool;
 }
+function sealedRebind(stamped, rebuild) {
+    const ownExecute = Object.getOwnPropertyDescriptor(stamped, "execute")?.value;
+    const stillSealed = () => {
+        const d = Object.getOwnPropertyDescriptor(stamped, "execute");
+        return d !== undefined && "value" in d && d.value === ownExecute;
+    };
+    return (enrich, mounted) => {
+        if (mounted !== stamped) {
+            throw new Error(`defineTool product ${JSON.stringify(stamped.name)}: the object being mounted is not the one this brand was stamped on (a derived object — prototype, proxy or descriptor copy — carrying a borrowed brand), so it cannot be rebound to the run's ctx without dropping its own overrides — wrap the product as a NEW object (stampDefineToolBrand with a rebind that re-wraps the rebound inner product), or author it as a raw ToolSpec`);
+        }
+        const refuse = () => {
+            throw new Error(`defineTool product ${JSON.stringify(stamped.name)}: its execute is not the own data property the factory wrote (replaced, or turned into an accessor, after the factory built it), so it cannot be rebound to the run's ctx without dropping the replacement — wrap the product as a NEW object (stampDefineToolBrand with a rebind that re-wraps the rebound inner product), or author it as a raw ToolSpec`);
+        };
+        if (!stillSealed())
+            refuse();
+        const rebound = rebuild(enrich, mounted);
+        if (!stillSealed())
+            refuse();
+        return rebound;
+    };
+}
+export function rebindDefineToolCtx(product, enrich) {
+    const rebind = Object.getOwnPropertyDescriptor(product, DEFINE_TOOL_REBIND)?.value;
+    if (typeof rebind !== "function")
+        throw new Error(`rebindDefineToolCtx: ${product.name} is not a defineTool product (no rebind seat)`);
+    return rebind(enrich, product);
+}
+function stampCallIdentity(enriched, toolCallId, signal) {
+    const own = (value) => ({ value, enumerable: true, configurable: true, writable: true });
+    return Object.create(Object.getPrototypeOf(enriched), { ...Object.getOwnPropertyDescriptors(enriched), toolCallId: own(toolCallId), signal: own(signal) });
+}
 export function defineTool(spec, options) {
     const executionMode = spec.executionMode ?? (spec.effect === "read" ? "parallel" : "sequential");
     const tool = {
@@ -77,7 +110,8 @@ export function defineTool(spec, options) {
             let ret;
             try {
                 const baseCtx = { toolCallId, signal };
-                ret = await spec.execute(params, options?.enrichCtx ? { ...options.enrichCtx(baseCtx), toolCallId, signal } : baseCtx);
+                const ctx = options?.enrichCtx ? stampCallIdentity(options.enrichCtx(baseCtx), toolCallId, signal) : baseCtx;
+                ret = await spec.execute(params, ctx);
             }
             catch (err) {
                 const wrapped = new Error(formatToolError(err));
@@ -105,6 +139,12 @@ export function defineTool(spec, options) {
             ...(spec.aliases && spec.aliases.length > 0 ? { aliases: spec.aliases } : {}),
         });
     }
-    stampDefineToolBrand(tool);
+    stampDefineToolBrand(tool, (enrich) => {
+        const composed = options?.enrichCtx === undefined ? enrich : (base) => options.enrichCtx(enrich(base));
+        const rebuilt = defineTool(spec, { ...options, enrichCtx: composed });
+        const { [DEFINE_TOOL_BRAND]: _brand, [DEFINE_TOOL_REBIND]: _seat, ...face } = Object.getOwnPropertyDescriptors(tool);
+        const copy = Object.create(Object.getPrototypeOf(tool), { ...face, execute: { value: rebuilt.execute, enumerable: true, configurable: true, writable: true } });
+        return stampDefineToolBrand(copy, (again) => rebindDefineToolCtx(rebuilt, again));
+    });
     return tool;
 }

package/dist/core/trace.d.ts

@@ -425,6 +425,21 @@ export type TraceEvent = {
     toolCallId: string;
     rules: readonly string[];
     ts: number;
+} | {
+    /**
+     * #619 — the READ-ONLY reader cleared a shell call, so no person and no classifier was asked: the
+     * allow layer's second attribution channel beside `permission.persisted_rule_allowed`. `command` is
+     * the FINAL command the gate judged (a policy rewrite included) — model-authored text, carried
+     * verbatim as the audit fact this frame exists for (a consumer rendering it applies its own
+     * display sanitizer, as it does for `tool_start` args).
+     */
+    kind: "permission.read_only_allowed";
+    version: 1;
+    taskId: string;
+    toolName: string;
+    toolCallId: string;
+    command: string;
+    ts: number;
 } | {
     /**
      * design/179 — the persisted allow-rule store could not be read, so this call was adjudicated with

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

@@ -244,10 +244,21 @@ export interface WiringManifest {
      * classifier decider was minted for this leg), and `reason` names the first arm that failed
      * otherwise — see {@link AUTO_MODE_ARM_REASONS}. A serving layer that used to infer the mode from
      * spec shape reads it here instead.
+     *
+     * `breaker` (#616) — the SESSION-level breaker read face: the most recent one-way breaker trip recorded
+     * for this session on this Runner (an EARLIER leg's decider — the latch is a per-run fact and a leg-start
+     * manifest's own decider is closed by construction, which is why there is no `open` boolean here: it
+     * would read `false` on every mint; the reason vocabulary reserves `latch_open` for a mid-leg re-read
+     * face nothing mints today). Present ⇔ a trip was recorded (never tripped, evicted or a standalone
+     * prepare ⇒ absent). `{ openedAtMs, lastCause, failures, runId }` — see
+     * {@link import("./auto-mode.js").AutoModeBreakerTrip}. A per-leg observation like `mcp`, so it is NOT
+     * part of {@link configFingerprint}: legs of one assembly must fingerprint alike whether or not a
+     * classifier was down.
      */
     autoMode?: {
         armed: boolean;
         reason: AutoModeArmReason;
+        breaker?: import("./auto-mode.js").AutoModeBreakerTrip;
     };
     /**
      * EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest (the `autoMode`
@@ -336,10 +347,13 @@ export interface WiringFacts {
         restore: string;
     };
     /** Effective half only — see {@link WiringManifest.autoMode}; the static half has no leg to arm.
-     *  `armed` must agree with `reason` (`armed ⇔ reason === "armed"`); a contradicting pair is refused. */
+     *  `armed` must agree with `reason` (`armed ⇔ reason === "armed"`); a contradicting pair is refused.
+     *  `breaker` (#616) is the session's most recent recorded trip, or absent; a trip whose cause is outside
+     *  the closed set or whose numbers are not finite is refused. */
     autoMode?: {
         armed: boolean;
         reason: AutoModeArmReason;
+        breaker?: import("./auto-mode.js").AutoModeBreakerTrip;
     };
     /** Effective half only — see {@link WiringManifest.mcp}; the static half materializes nothing.
      *  Copied entry-wise onto the manifest (the caller's array is never aliased). */

package/dist/core/wiring-manifest.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { AUTO_MODE_BREAKER_CAUSES, isAutoModeBreakerCause } from "./auto-mode.js";
 import { canonicalize } from "./canonical-json.js";
 import { resolveCheckpointStore } from "./checkpoint-store.js";
 import { isLiveQuestionFace } from "./ask-question.js";
@@ -71,7 +72,13 @@ function readAutoModeFact(fact) {
     if (!AUTO_MODE_ARM_REASONS.includes(fact.reason) || fact.armed !== (fact.reason === "armed")) {
         throw new Error(`the auto-mode wiring fact is inconsistent (armed=${String(fact.armed)}, reason=${JSON.stringify(fact.reason)}) — armed must hold exactly when reason is "armed", and reason must be one of ${AUTO_MODE_ARM_REASONS.join("|")}`);
     }
-    return { armed: fact.armed, reason: fact.reason };
+    const b = fact.breaker;
+    if (b === undefined)
+        return { armed: fact.armed, reason: fact.reason };
+    if (!isAutoModeBreakerCause(b.lastCause) || !Number.isFinite(b.openedAtMs) || !Number.isInteger(b.failures) || b.failures < 1 || typeof b.runId !== "string" || b.runId === "") {
+        throw new Error(`the auto-mode breaker fact is malformed (${JSON.stringify(b)}) — lastCause must be one of ${AUTO_MODE_BREAKER_CAUSES.join("|")}, openedAtMs finite, failures a positive integer, runId a non-empty string`);
+    }
+    return { armed: fact.armed, reason: fact.reason, breaker: { openedAtMs: b.openedAtMs, lastCause: b.lastCause, failures: b.failures, runId: b.runId } };
 }
 export function deriveWiringManifest(facts) {
     if (facts.half === "static" && facts.leg !== undefined) {
@@ -133,8 +140,9 @@ export function deriveWiringManifest(facts) {
         const { leg: _leg, mcp: _mcp, tools: _tools, ...assembly } = manifest;
         const { provenance: _askSeat, ...askForHash } = assembly.ask;
         const { provenance: _questionSeat, ...questionForHash } = assembly.question;
+        const { breaker: _breaker, ...autoModeForHash } = assembly.autoMode ?? {};
         manifest.configFingerprint = createHash("sha256")
-            .update(canonicalize({ ...assembly, ask: askForHash, question: questionForHash }))
+            .update(canonicalize({ ...assembly, ask: askForHash, question: questionForHash, ...(assembly.autoMode !== undefined ? { autoMode: autoModeForHash } : {}) }))
             .digest("hex")
             .slice(0, 16);
     }

package/dist/core/workflow-journal-store.d.ts

@@ -5,12 +5,31 @@ import type { TaskResult } from "./types.js";
  * longest unchanged PREFIX of these (keyed by the deterministic {@link workflowAgentCallKey}) and runs only the
  * first changed/new call + everything after it live. Same script + same args → 100% cache hit.
  */
-export interface WorkflowJournalEntry {
+export type WorkflowJournalEntry = {
     /** The agent's deterministic call key (`ordinal:specIdentityHash`) — the replay match key. */
     callKey: string;
     /** The agent's TaskResult, replayed verbatim when a resume's call key matches at the same ordinal. */
     result: TaskResult;
-}
+    parked?: never;
+} | {
+    callKey: string;
+    result?: never;
+    /**
+     * #642 — the ordinal's leg is PARKED at a durable approval gate: the child's own paused `TaskResult`
+     * (its `terminal` carries the checkpoint token + gate, its `sessionId` the pinned session). A resume
+     * reaching this ordinal with a matching call key does NOT run the call live (the parked child's
+     * session is pinned under a pending checkpoint; a fresh spawn would duplicate it) — it drives the
+     * parked child's resume when the caller hands it a decision for the token, else re-parks. Deliberately
+     * a DIFFERENT key from `result`: a journal reader from before this entry kind existed finds no
+     * `result.terminal` and refuses the whole resume (`WorkflowJournalIncompatibleError`) instead of
+     * admitting a paused cause it would re-run live — one-way, loud, like every journal schema step.
+     */
+    parked: TaskResult & {
+        terminal: Extract<TaskResult["terminal"], {
+            kind: "paused";
+        }>;
+    };
+};
 /** REF-D5: the resume-claim key triple — ONE shape for the interface pair and every implementation
  *  (it was re-inlined seven times; a key-field rename must red every leg at once). */
 export interface ResumeClaimArgs {

package/dist/core/workflow-journal-store.js

@@ -65,7 +65,7 @@ export class InMemoryWorkflowJournalStore {
         return [...rec.byOrdinal.entries()].sort((a, b) => a[0] - b[0]).map(([, e]) => snapshot(e));
     }
     async append(runId, scope, entry) {
-        if (oversizeJournalResult(JSON.stringify(entry.result)))
+        if (oversizeJournalResult(JSON.stringify(entry.parked !== undefined ? entry.parked : entry.result)))
             return;
         let rec = this.runs.get(runId);
         if (!rec) {

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -79,6 +79,8 @@ export declare function openSpoolPair(base: string): {
 };
 export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCapability, SchedulerCapability {
     cwd: string;
+    /** #644 — this adapter runs on the engine host, so the host's home IS the environment's (`ExecutionEnv.homeDir`). */
+    readonly homeDir: string;
     private shellPath?;
     private shellEnv?;
     private inheritEnv;