@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/user-attachment.js

@@ -3,10 +3,12 @@ import { READ_OUTCOMES } from "../tools/fs/fs-read.js";
 import { renderDirectoryListing } from "../tools/fs/dir-entries.js";
 import { MAX_READ_OUTPUT_CHARS } from "../tools/fs/fs-shared.js";
 import { normalizeFileText } from "../tools/fs/encoding.js";
-import { ADMITTED_IMAGE_MIME_TYPES, admitImageBytes } from "../tools/fs/image-admission.js";
+import { ADMITTED_IMAGE_MIME_TYPES, admitImageBytes } from "./image-admission.js";
 import { PDF_MAX_PAGES_PER_READ } from "../tools/fs/pdf.js";
 import { MARKED_BLOCK_AFTER_DATA, mintSystemReminder } from "./reminder-mint.js";
 import { commitReminderDisclosureEffects, planReminderDisclosure } from "./reminder-disclosure.js";
+import { DEFAULT_CHARS_PER_TOKEN, estimateTokens } from "../internal/harness.js";
+import { guardBudget } from "./context-guard.js";
 export const USER_ATTACHMENTS_MAX = 20;
 export const USER_ATTACHMENT_LABEL_MAX = 4096;
 export const USER_ATTACHMENT_KINDS = Object.freeze(["text", "notebook", "image", "pdf", "directory", "client_text", "client_image"]);
@@ -22,12 +24,16 @@ export const USER_ATTACHMENT_SEAT = Object.freeze({
     supplies: USER_ATTACHMENT_SUPPLIES,
     limits: Object.freeze({ maxEntries: USER_ATTACHMENTS_MAX, maxRenderedTextChars: MAX_READ_OUTPUT_CHARS }),
 });
-export function userAttachmentRefusal(field, detail) {
-    const e = new Error(`${field}: ${detail}`);
+export function userAttachmentRefusal(at, problem) {
+    const e = new Error(`${at.path}: ${problem}`);
     e.code = "config.user_attachment_invalid";
+    e.detail = { path: at.path, ...(at.index !== undefined ? { index: at.index } : {}) };
     return e;
 }
 const SEAT_FIELD = "TaskSpec.userAttachments";
+const SEAT_REF = { path: SEAT_FIELD };
+const entryRef = (index) => ({ path: `${SEAT_FIELD}[${index}]`, index });
+const memberRef = (at, member) => ({ ...at, path: `${at.path}.${member}` });
 const isPlainObject = (v) => {
     if (v === null || typeof v !== "object" || Array.isArray(v))
         return false;
@@ -43,85 +49,87 @@ export function screenUserAttachments(seat, opts) {
     if (seat === undefined)
         return undefined;
     if (!Array.isArray(seat))
-        throw userAttachmentRefusal(SEAT_FIELD, "must be an array of attachments.");
+        throw userAttachmentRefusal(SEAT_REF, "must be an array of attachments.");
     const entries = [...seat];
     if (entries.length === 0)
         return undefined;
     if (entries.length > USER_ATTACHMENTS_MAX)
-        throw userAttachmentRefusal(SEAT_FIELD, `${entries.length} attachments, over the ${USER_ATTACHMENTS_MAX} one objective may carry.`);
+        throw userAttachmentRefusal(SEAT_REF, `${entries.length} attachments, over the ${USER_ATTACHMENTS_MAX} one objective may carry.`);
     if (opts.resumeLeg)
-        throw userAttachmentRefusal(SEAT_FIELD, "a durable resume continues the parked run and sends no new human message, so it cannot carry attachments — declare them on a new objective.");
-    return entries.map((raw, i) => screenEntry(raw, `${SEAT_FIELD}[${i}]`));
+        throw userAttachmentRefusal(SEAT_REF, "a durable resume continues the parked run and sends no new human message, so it cannot carry attachments — declare them on a new objective.");
+    return entries.map((raw, i) => screenEntry(raw, entryRef(i)));
 }
-function screenLabel(v, field) {
+function screenLabel(v, at) {
     if (typeof v !== "string" || v.length === 0)
-        throw userAttachmentRefusal(field, "must be a non-empty string.");
+        throw userAttachmentRefusal(at, "must be a non-empty string.");
     if (v.length > USER_ATTACHMENT_LABEL_MAX)
-        throw userAttachmentRefusal(field, `${v.length} characters, over the ${USER_ATTACHMENT_LABEL_MAX}-character limit.`);
+        throw userAttachmentRefusal(at, `${v.length} characters, over the ${USER_ATTACHMENT_LABEL_MAX}-character limit.`);
     return v;
 }
-function screenPositiveInt(v, field) {
+function screenPositiveInt(v, at) {
     if (typeof v !== "number" || !Number.isInteger(v) || v < 1)
-        throw userAttachmentRefusal(field, "must be an integer of at least 1.");
+        throw userAttachmentRefusal(at, "must be an integer of at least 1.");
     return v;
 }
-function onlyMembers(o, allowed, field) {
+function onlyMembers(o, allowed, at) {
     for (const k of Object.keys(o))
         if (!allowed.includes(k))
-            throw userAttachmentRefusal(`${field}.${k}`, `is not a member of this attachment (allowed: ${allowed.join(", ")}).`);
+            throw userAttachmentRefusal(memberRef(at, k), `is not a member of this attachment (allowed: ${allowed.join(", ")}).`);
 }
-function screenEntry(raw, field) {
+function screenEntry(raw, at) {
     if (!isPlainObject(raw))
-        throw userAttachmentRefusal(field, "must be a plain object: { path } (a workspace file), { name, text } (host text) or { name, image } (a host image).");
+        throw userAttachmentRefusal(at, "must be a plain object: { path } (a workspace file), { name, text } (host text) or { name, image } (a host image).");
     const arms = ["path", "text", "image"].filter((k) => Object.prototype.hasOwnProperty.call(raw, k));
     const arm = arms[0];
     if (arm === undefined || arms.length !== 1) {
-        throw userAttachmentRefusal(field, arm === undefined ? "names no attachment: give exactly one of `path`, `text` or `image`." : `mixes ${arms.map((a) => `\`${a}\``).join(" and ")}: give exactly one of \`path\`, \`text\` or \`image\`.`);
+        throw userAttachmentRefusal(at, arm === undefined ? "names no attachment: give exactly one of `path`, `text` or `image`." : `mixes ${arms.map((a) => `\`${a}\``).join(" and ")}: give exactly one of \`path\`, \`text\` or \`image\`.`);
     }
     switch (arm) {
         case "path": {
-            onlyMembers(raw, ["path", "lines"], field);
-            const path = screenLabel(raw.path, `${field}.path`);
+            onlyMembers(raw, ["path", "lines"], at);
+            const path = screenLabel(raw.path, memberRef(at, "path"));
             const linesRaw = raw.lines;
             if (linesRaw === undefined)
                 return { supply: "path", path };
+            const linesAt = memberRef(at, "lines");
             if (!isPlainObject(linesRaw))
-                throw userAttachmentRefusal(`${field}.lines`, "must be { start, end? }.");
-            onlyMembers(linesRaw, ["start", "end"], `${field}.lines`);
-            const start = screenPositiveInt(linesRaw.start, `${field}.lines.start`);
+                throw userAttachmentRefusal(linesAt, "must be { start, end? }.");
+            onlyMembers(linesRaw, ["start", "end"], linesAt);
+            const start = screenPositiveInt(linesRaw.start, memberRef(linesAt, "start"));
             const endRaw = linesRaw.end;
             if (endRaw === undefined)
                 return { supply: "path", path, lines: { start } };
-            const end = screenPositiveInt(endRaw, `${field}.lines.end`);
+            const end = screenPositiveInt(endRaw, memberRef(linesAt, "end"));
             if (end < start)
-                throw userAttachmentRefusal(`${field}.lines.end`, `${end} is before the start line ${start}.`);
+                throw userAttachmentRefusal(memberRef(linesAt, "end"), `${end} is before the start line ${start}.`);
             return { supply: "path", path, lines: { start, end } };
         }
         case "text": {
-            onlyMembers(raw, ["name", "text", "startLine"], field);
-            const name = screenLabel(raw.name, `${field}.name`);
+            onlyMembers(raw, ["name", "text", "startLine"], at);
+            const name = screenLabel(raw.name, memberRef(at, "name"));
             const text = raw.text;
             if (typeof text !== "string" || text.length === 0)
-                throw userAttachmentRefusal(`${field}.text`, "must be a non-empty string.");
-            const startLine = raw.startLine === undefined ? 1 : screenPositiveInt(raw.startLine, `${field}.startLine`);
+                throw userAttachmentRefusal(memberRef(at, "text"), "must be a non-empty string.");
+            const startLine = raw.startLine === undefined ? 1 : screenPositiveInt(raw.startLine, memberRef(at, "startLine"));
             const rendered = renderNumbered(text, startLine);
             if (rendered.length > MAX_READ_OUTPUT_CHARS)
-                throw userAttachmentRefusal(`${field}.text`, `renders to ${rendered.length} characters with line numbers, over the ${MAX_READ_OUTPUT_CHARS}-character limit a read may deliver — send a part of it.`);
+                throw userAttachmentRefusal(memberRef(at, "text"), `renders to ${rendered.length} characters with line numbers, over the ${MAX_READ_OUTPUT_CHARS}-character limit a read may deliver — send a part of it.`);
             return { supply: "content_text", name, text, startLine, rendered };
         }
         case "image": {
-            onlyMembers(raw, ["name", "image"], field);
-            const name = screenLabel(raw.name, `${field}.name`);
+            onlyMembers(raw, ["name", "image"], at);
+            const name = screenLabel(raw.name, memberRef(at, "name"));
             const img = raw.image;
+            const imageAt = memberRef(at, "image");
             if (!isPlainObject(img))
-                throw userAttachmentRefusal(`${field}.image`, "must be { data, mimeType } (base64 bytes and the image's type).");
-            onlyMembers(img, ["data", "mimeType"], `${field}.image`);
+                throw userAttachmentRefusal(imageAt, "must be { data, mimeType } (base64 bytes and the image's type).");
+            onlyMembers(img, ["data", "mimeType"], imageAt);
             const data = img.data;
             const mimeType = img.mimeType;
             if (typeof data !== "string" || data.length === 0)
-                throw userAttachmentRefusal(`${field}.image.data`, "must be a non-empty base64 string.");
+                throw userAttachmentRefusal(memberRef(imageAt, "data"), "must be a non-empty base64 string.");
             if (typeof mimeType !== "string" || !ADMITTED_IMAGE_MIME_TYPES.includes(mimeType)) {
-                throw userAttachmentRefusal(`${field}.image.mimeType`, `must be one of ${ADMITTED_IMAGE_MIME_TYPES.join(", ")}.`);
+                throw userAttachmentRefusal(memberRef(imageAt, "mimeType"), `must be one of ${ADMITTED_IMAGE_MIME_TYPES.join(", ")}.`);
             }
             return { supply: "content_image", name, data, mimeType };
         }
@@ -130,7 +138,7 @@ function screenEntry(raw, field) {
 export function refuseUserAttachmentPathsWithoutWorkspace(screened) {
     const i = screened?.findIndex((a) => a.supply === "path") ?? -1;
     if (i >= 0)
-        throw userAttachmentRefusal(`${SEAT_FIELD}[${i}].path`, "this run has no workspace (its hand tools are off), so the engine has no file to read — send the file's bytes as a `text` or `image` entry instead.");
+        throw userAttachmentRefusal(memberRef(entryRef(i), "path"), "this run has no workspace (its hand tools are off), so the engine has no file to read — send the file's bytes as a `text` or `image` entry instead.");
 }
 export function userAttachmentDeclarations(screened) {
     return screened.map((a, i) => a.supply === "path"
@@ -147,16 +155,16 @@ export async function admitUserAttachmentImages(screened) {
             out.set(i + 1, admitted.block);
             continue;
         }
-        const field = `${SEAT_FIELD}[${i}].image`;
+        const imageAt = memberRef(entryRef(i), "image");
         switch (admitted.reason) {
             case "mime_unsupported":
-                throw userAttachmentRefusal(`${field}.mimeType`, `must be one of ${ADMITTED_IMAGE_MIME_TYPES.join(", ")}.`);
+                throw userAttachmentRefusal(memberRef(imageAt, "mimeType"), `must be one of ${ADMITTED_IMAGE_MIME_TYPES.join(", ")}.`);
             case "magic_mismatch":
-                throw userAttachmentRefusal(`${field}.data`, `does not begin with a ${a.mimeType} signature (empty, mis-declared, or not base64) — refused rather than sent.`);
+                throw userAttachmentRefusal(memberRef(imageAt, "data"), `does not begin with a ${a.mimeType} signature (empty, mis-declared, or not base64) — refused rather than sent.`);
             case "raw_too_large":
-                throw userAttachmentRefusal(`${field}.data`, `${admitted.rawBytes} bytes, over the ${admitted.cap}-byte cap.`);
+                throw userAttachmentRefusal(memberRef(imageAt, "data"), `${admitted.rawBytes} bytes, over the ${admitted.cap}-byte cap.`);
             case "base64_too_large":
-                throw userAttachmentRefusal(`${field}.data`, `base64 of ${admitted.base64.length} characters, over the API's 5 MB image limit — shrink the image first.`);
+                throw userAttachmentRefusal(memberRef(imageAt, "data"), `base64 of ${admitted.base64.length} characters, over the API's 5 MB image limit — shrink the image first.`);
         }
     }
     return out;
@@ -383,7 +391,19 @@ function mintFrame(r, at, seat) {
     const commit = result !== undefined || extra.length > 0 ? () => seat.commit(result, extra) : undefined;
     return { seed: { content, attachment }, ...(commit !== undefined ? { commit } : {}) };
 }
-export async function readObjectiveAttachments(prepared, inputId, blocked) {
+function refuseFramesOverWindow(frames, model, window) {
+    const budget = guardBudget(model, window.overlay());
+    if (!Number.isFinite(budget))
+        return;
+    const cpt = model.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    const asMessage = (f) => ({ role: "user", content: [...f.seed.content], timestamp: 0 });
+    const tokens = frames.reduce((n, f) => n + estimateTokens(asMessage(f), cpt), 0) + Math.ceil(window.objectiveChars / cpt);
+    if (tokens <= budget)
+        return;
+    const n = frames.length;
+    throw userAttachmentRefusal(SEAT_REF, `the ${n} ${n === 1 ? "attachment" : "attachments"} and the objective come to about ${tokens} tokens, over the ${budget} tokens one request can hold on this model — to send it the engine would have to drop the objective or some of the attachments. Nothing was sent; attach fewer or smaller parts.`);
+}
+export async function readObjectiveAttachments(prepared, inputId, blocked, window) {
     if (blocked || prepared.userAttachments === undefined)
         return { frames: [], chars: 0 };
     const frames = await readUserAttachments({
@@ -397,6 +417,7 @@ export async function readObjectiveAttachments(prepared, inputId, blocked) {
         counts: prepared.reminderDisclosureCounts,
         signal: prepared.abortController.signal,
     });
+    refuseFramesOverWindow(frames, prepared.harness.getModel(), window);
     return { frames, chars: frames.reduce((n, f) => n + f.seed.content.reduce((m, b) => m + (b.type === "text" ? b.text.length : 0), 0), 0) };
 }
 export function lastAttachmentFrameOf(entries, id) {

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

@@ -23,7 +23,7 @@
 import { type PermissionMode } from "./ask-origin.js";
 import type { RunnerDeps, TaskSpec } from "./types.js";
 import { type StoreDurability } from "./checkpoint-store.js";
-import type { WiringManifestHookEntry } from "./hook-seats.js";
+import type { ModAdmissionRecord } from "./mods/kernel/index.js";
 import type { McpDelivered, McpFailureKind, McpServerLiveness } from "./mcp-failure.js";
 import type { WriteProtectionTargetView } from "./write-protect.js";
 import type { OnAsk } from "./tool-policy.js";
@@ -113,8 +113,7 @@ export interface AutoModeArmFact {
  * One declared MCP server's materialization result for THIS leg — the per-server connection-state
  * read face on {@link WiringManifest.mcp}. `status` is the connect-time verdict of this leg's
  * materialize (a snapshot, never a heartbeat — the same semantics as `MaterializedMcp.statuses`,
- * which it is projected from): `connected` (tools listed; `toolCount` = the mounted roster size after
- * intake), `failed` (the connect or the tool listing threw — `errorCode`/`delivered`/`httpStatus` are the
+ * which it is projected from): `connected` (tools listed; `toolCount` = see the field), `failed` (the connect or the tool listing threw — `errorCode`/`delivered`/`httpStatus` are the
  * failure record spread flat (see the MCP failure vocabulary's `McpFailure`), `error` the
  * neutralized, length-bounded remote text), `skipped` (declared on the spec but this leg produced no
  * status for it — the materialization did not reach it). `source` is the DECLARING side's own label
@@ -130,6 +129,9 @@ export interface WiringManifestMcpEntry {
     delivered?: McpDelivered;
     httpStatus?: number;
     error?: string;
+    /** How many of the server's tools the roster the row is read against holds: a run's roster (the valve and the deployment's
+     *  `toolFaces` overlay applied — a tool either one leaves off is not counted), or, for `probeMcpServers` (no run, so no lists),
+     *  what its own dial would mount. `0` on `failed` and on `skipped` (no connection, so nothing held). */
     toolCount: number;
     /**
      * The engine's last liveness OBSERVATION about this server as of this leg's materialize — a per-leg
@@ -180,7 +182,6 @@ export declare function deriveLspSeam(mounted: boolean, diagnosticsLive: boolean
  * (`schemaVersion` bumps only on a semantic break of an EXISTING field). The TaskEvent face is the
  * host/operator plane — the manifest never enters model context.
  */
-export type { WiringManifestHookEntry };
 export interface WiringManifest {
     schemaVersion: 1;
     /** Present on EFFECTIVE (per-leg) manifests only; the static half has no leg. */
@@ -356,14 +357,16 @@ export interface WiringManifest {
      */
     tools?: import("./tool-roster.js").ToolRoster;
     /**
-     * EFFECTIVE half only: the hook seats this leg wired, one entry per family, in {@link import("./hook-seats.js").HOOK_FAMILIES} order. PRESENT IFF at least one
-     * seat is wired — a deployment that wires none reports nothing here and its manifest (and {@link configFingerprint}) is byte-for-byte what it was; an empty
-     * array is never emitted, so absence reads as "this leg wired no hook RECORD of its own" — NOT as "no hook runs": a delegated child with no local record can
-     * still be screened (and refused) by an ancestor's `preToolUse` through the gate's constraint fold, which this face deliberately does not call a hook of
-     * this leg. Every entry is deployment code the engine awaits on the critical path, fail-closed on the two decision seats. EXCLUDED from
-     * {@link configFingerprint}: the record is a per-task seat, so one assembly's legs legitimately differ on it.
+     * EFFECTIVE half only: the leg's mods admission — one record per registration of the two seats, in run order: a
+     * mounted one with the patterns it actually hung (`events`), the ones it declared observe-only (`observe`) and the
+     * judges skipped while it was judged (`skipped`), or a refused one with who refused it and why (`refusedBy`,
+     * `reason`). PRESENT IFF the leg has a registration — a deployment that wires none reports nothing here and its
+     * manifest (and {@link configFingerprint}) is byte-for-byte what it was. Absence reads as "this leg carries no
+     * registration", NOT as "no extension judges this leg's calls": a delegated child can still be screened by an
+     * ancestor's chain through the gate's constraint fold. EXCLUDED from {@link configFingerprint}: the task seat is a
+     * per-task seat, so one assembly's legs legitimately differ on it.
      */
-    hooks?: readonly WiringManifestHookEntry[];
+    mods?: readonly ModAdmissionRecord[];
     /**
      * EFFECTIVE half only: the LSP code-intelligence seam. PRESENT IFF a manager seat resolved
      * (`spec.lspManager ?? deps.lspManager`); a deployment that wires none reports nothing (byte-for-byte
@@ -412,7 +415,7 @@ export interface WiringManifest {
      * the engine's seats — the same fact `config.write_protection_target_view_absent` announces once per run
      * when a covered write tool is mounted beside a `"spelling-only"` judge.
      *
-     * IN the fingerprint below (unlike `tools`/`lsp`/`hooks`): which view the judge got is an ASSEMBLY fact
+     * IN the fingerprint below (unlike `tools`/`lsp`/`mods`): which view the judge got is an ASSEMBLY fact
      * — it follows the table seat and whether the deployment wired hands at all — so legs of one assembly
      * agree on it, which is exactly the equality the fingerprint advertises.
      *
@@ -466,7 +469,7 @@ export interface WiringManifest {
      * `"on"` — it records (store wired, neither layer declared it off, a filesystem env mounted). `"disabled"` — it does
      * not, whichever layer or missing half made it so (`TaskSpec.fileHistory`, `RunnerDeps.fileHistoryStore: "disabled"`, `RunnerDeps.fileHistoryCapture: "off"`,
      * no store, no filesystem env); the host knows its own deployment seat. ABSENT = an older mint or an external
-     * derivation, never a state. Out of {@link configFingerprint}: the request word is a per-task seat (`hooks` reasoning).
+     * derivation, never a state. Out of {@link configFingerprint}: the request word is a per-task seat (`mods` reasoning).
      */
     fileHistory?: "on" | "disabled";
     /** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
@@ -544,8 +547,8 @@ export interface WiringFacts {
     mcp?: readonly WiringManifestMcpEntry[];
     /** Effective half only — the leg's minted tool roster (see {@link WiringManifest.tools}). */
     tools?: import("./tool-roster.js").ToolRoster;
-    /** Effective half only — the wired hook seats ({@link WiringManifest.hooks}); an empty array and an absent value derive the same thing (no section). */
-    hooks?: readonly WiringManifestHookEntry[];
+    /** Effective half only — the leg's mods admission records ({@link WiringManifest.mods}); an empty array and an absent value derive the same thing (no section). */
+    mods?: readonly ModAdmissionRecord[];
     /** Effective half only — the LSP seam ({@link WiringManifest.lsp}); absent ⇒ no manager wired. */
     lsp?: {
         mounted: boolean;

package/dist/core/wiring-manifest.js

@@ -210,7 +210,7 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.autoMode !== undefined ? { autoMode: readAutoModeFact(facts.autoMode) } : {}),
         ...(facts.half === "effective" && facts.mcp !== undefined ? { mcp: facts.mcp.map((e) => ({ ...e })) } : {}),
         ...(facts.half === "effective" && facts.tools !== undefined ? { tools: facts.tools } : {}),
-        ...(facts.half === "effective" && facts.hooks !== undefined && facts.hooks.length > 0 ? { hooks: facts.hooks.map((h) => ({ ...h })) } : {}),
+        ...(facts.half === "effective" && facts.mods !== undefined && facts.mods.length > 0 ? { mods: [...facts.mods] } : {}),
         ...(facts.half === "effective" && facts.lsp !== undefined ? { lsp: { ...facts.lsp } } : {}),
         ...(facts.half === "effective" && facts.hands !== undefined ? { hands: readHandsFact(facts.hands) } : {}),
         ...(facts.half === "effective" && facts.permissionMode !== undefined ? { permissionMode: readPermissionModeFact(facts.permissionMode) } : {}),
@@ -226,7 +226,7 @@ export function deriveWiringManifest(facts) {
             : {}),
     };
     if (facts.half === "effective") {
-        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, hooks: _hooks, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, permissionMode: _permissionMode, ...assembly } = manifest;
+        const { leg: _leg, mcp: _mcp, tools: _tools, lsp: _lsp, mods: _mods, teamRole: _teamRole, peerPresence: _peerPresence, fileHistory: _fileHistory, permissionMode: _permissionMode, ...assembly } = manifest;
         const { provenance: _askSeat, ...askForHash } = assembly.ask;
         const { provenance: _questionSeat, ...questionForHash } = assembly.question;
         manifest.configFingerprint = createHash("sha256")

package/dist/engine/compaction/utils.js

@@ -2,8 +2,7 @@ import { renderUserAttachmentView, userAttachmentOf } from "../llm/index.js";
 import { normalizeLlmMessageContent } from "../harness/messages.js";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 import { cutEnginePrefix, cutEngineSegments, flattenableUserText } from "../../core/untrusted-text.js";
-import { fileArgPath } from "../../tools/fs/safety.js";
-import { fileOpAccessOf } from "../../core/tool-registry.js";
+import { fileArgPath, fileOpAccessOf } from "../../core/tool-registry.js";
 export const DURABLE_HISTORY_NAMES = new Map([
     ["read", "read"],
     ["write", "create"],

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

@@ -112,9 +112,10 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
          *  fail-closed (drop secret-pattern keys, keep PATH/build/locale). `"all"` = full inherit (trusted env);
          *  `string[]` = strict allowlist. `shellEnv`/per-exec `env` always pass through. Any other value — an unknown
          *  word, a non-string, a list entry that is not a variable name — throws here (`inheritEnvPolicyProblem`'s
-         *  reason), the same judgment the oracle gate's `inheritEnv` meets. Whatever the policy, the deployment's declared
-         *  own credentials (`declareWithheldEnv`) are withheld from the inherited part; a list naming one throws here when
-         *  the declaration came first, and every spawn refuses it (`spawn_error` / `spawn_failed`) whenever it came. */
+         *  reason), the same judgment the oracle gate's `inheritEnv` meets. Whatever the policy, the deployment's own
+         *  credentials (`declareWithheldEnv`: by name, and by a value equal to a declared or engine-held credential value)
+         *  are withheld from the inherited part; a list naming a declared name throws here when the declaration came
+         *  first, and every spawn refuses it (`spawn_error` / `spawn_failed`) whenever it came. */
         inheritEnv?: "all" | "scrub" | string[];
         /** design/105: inject a resident scheduler daemon backend (the shell daemon). Absent ⇒ scheduling INERT. */
         scheduler?: SchedulerCapability;

package/dist/engine/execution-env/symlink-chain.js

@@ -1,5 +1,5 @@
 import { dirname, isAbsolute, sep } from "node:path";
-import { isUncSpelling } from "../../tools/fs/safety.js";
+import { isUncSpelling } from "../../core/unc-spelling.js";
 import { err, ok } from "../harness/types.js";
 export function anchorAtLinkDir(linkDir, target, separator) {
     const endsInSeparator = linkDir.endsWith(separator) || (separator === "\\" && linkDir.endsWith("/"));

package/dist/engine/harness/agent-harness.d.ts

@@ -363,7 +363,7 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     /**
      * roadmap #5 (CC Stop hook): wire (or clear) the stop gate — consulted ONLY when the run would
      * otherwise end (no tool calls, steer + followUp queues dry). Non-empty return = the run
-     * continues with those messages injected; empty = the run ends. Policy (the Hooks.stop call,
+     * continues with those messages injected; empty = the run ends. Policy (the `classic.Stop` dispatch,
      * consecutive-block cap, reason formatting) lives in the runner; the harness only supplies the
      * drain-point timing.
      */

package/dist/engine/harness/agent-harness.js

@@ -2,7 +2,7 @@ import { createAssistantMessageEventStream, ensureToolTurnInvariants, snapshotAc
 import { finalizeToolOutcome, runAgentLoop } from "../loop/agent-loop.js";
 import { resolveAgentCoreStreamFn } from "../loop/runtime-deps.js";
 import { normalizeEngineSegments } from "../../core/untrusted-text.js";
-import { AUTH_CARRIER_NAMES } from "../../brain/request-params.js";
+import { isCredentialHeaderName } from "../../core/secret-env.js";
 import { isProviderEchoShape } from "../../brain/errors.js";
 import { convertToLlm } from "./messages.js";
 import { readMember, thrownText } from "../../core/thrown-value.js";
@@ -99,7 +99,7 @@ function dropAuthCarriers(bag) {
         return bag;
     const out = {};
     for (const [k, v] of Object.entries(bag)) {
-        if (!AUTH_CARRIER_NAMES.has(k.toLowerCase()))
+        if (!isCredentialHeaderName(k))
             out[k] = v;
     }
     return out;
@@ -108,7 +108,7 @@ function refuseAuthCarriersInStreamOptions(bag) {
     if (!bag)
         return;
     for (const k of Object.keys(bag)) {
-        if (AUTH_CARRIER_NAMES.has(k.toLowerCase())) {
+        if (isCredentialHeaderName(k)) {
             throw new Error(`streamOptions.headers must not carry an auth header ("${k}") — the run-static bag is not an auth channel ` +
                 `(the route pairing law reads options-borne carriers as per-model credentials, which a run-wide bag is not). ` +
                 `Put a deployment credential on the brain config (apiKey / headers, where its URL half is judged), or serve ` +
@@ -670,13 +670,14 @@ export class AgentHarness {
                     },
                 };
             },
-            beforeToolCall: async ({ toolCall, args }, signal) => {
+            beforeToolCall: async ({ toolCall, args, readArguments }, signal) => {
                 const result = await this.emitHook({
                     type: "tool_call",
                     toolCallId: toolCall.id,
                     toolName: toolCall.name,
                     input: args,
                     ...(signal !== undefined ? { signal } : {}),
+                    ...(readArguments !== undefined ? { readArguments } : {}),
                 });
                 return result;
             },

package/dist/engine/harness/types.d.ts

@@ -142,6 +142,8 @@ export declare class FileError extends Error {
 }
 /** Stable, backend-independent execution error codes returned by {@link ExecutionEnv.exec}. */
 export type ExecutionErrorCode = "aborted" | "timeout"
+/** Ran-then-cut for SILENCE: no stdout/stderr byte for the env's liveness window ({@link ExecutionError.noOutputSec}) — a hang detector, not the wall-clock budget (`"timeout"`), so an env MUST answer this word for it: the two explain themselves with different numbers. Retryable per idempotency. */
+ | "liveness_no_output"
 /** The shell binary/config could not be resolved BEFORE spawning — the command never started. */
  | "shell_unavailable"
 /** CONTRACT (2026-07-13, TB cwd-contamination batch): spawn_error MUST mean the command NEVER STARTED (the
@@ -187,7 +189,7 @@ export declare class ExecutionError extends Error {
     code: ExecutionErrorCode;
     /**
      * TB triple-fake-green report (2026-07-13) — output produced BEFORE the failure, for the
-     * ran-then-cut codes (`timeout` / `aborted` / `callback_error`; the last is a command that
+     * ran-then-cut codes (`timeout` / `liveness_no_output` / `aborted` / `callback_error`; the last is a command that
      * started and was then killed because a host-side output callback failed — its completion was
      * never observed, but its captured output is real work). CC anchor (2.1.206 BashTask settle): a
      * timed-out command keeps ALL captured stdout/stderr and only APPENDS a "Command timed out after
@@ -197,11 +199,15 @@ export declare class ExecutionError extends Error {
      */
     partialStdout?: string;
     partialStderr?: string;
+    /** `liveness_no_output` only: the silence window (whole seconds) that cut the command — the env's bound, never the requested budget; absent = not stated. */
+    noOutputSec?: number;
     constructor(code: ExecutionErrorCode, message: string, cause?: Error, partial?: {
         stdout?: string;
         stderr?: string;
-    });
+    }, noOutputSec?: number);
 }
+/** A command that RAN and was cut by a time bound — the wall-clock budget (`"timeout"`) or the silence window (`"liveness_no_output"`): one reading for every consumer that recovers the partial output. */
+export declare function isTimeCutCode(code: ExecutionErrorCode): code is "timeout" | "liveness_no_output";
 /** Stable compaction error codes returned by compaction helpers. */
 export type CompactionErrorCode = "aborted" | "summarization_failed" | "invalid_session" | "unknown";
 /** Error returned by compaction helpers. */
@@ -610,8 +616,8 @@ export interface LeafEntry extends SessionTreeEntryBase {
 }
 /**
  * Prompt-epoch pin (stage S3, prompt-assembly protocol §9.2) — a FIRST-CLASS typed entry (not a
- * forgeable generic `custom` entry): which prompt-pack artifact this session is pinned to. Written
- * at session start (before the first conversation entry) and on legacy migration; every compaction
+ * forgeable generic `custom` entry): the session's prompt identity record and its pinned center layer. Written
+ * at session start (before the first conversation entry) and whenever a run's identity moves; every compaction
  * RESTATES the then-current descriptor inside its own `details.promptEpoch` (same-CAS atomicity,
  * bounded-tail recoverable). Fields mirror `PromptEpochDescriptor` (src/prompt-assembly/epoch.ts).
  */
@@ -934,10 +940,11 @@ export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetad
      * bounded-tail backends. A durable backend that loads only `firstKeptEntryId..leaf` cannot show
      * the branch walk an epoch carrier when a rewind cuts BEFORE the latest compaction's restatement
      * (window: firstKept ≤ cut < compactionEntry) — `Session.getPromptEpoch()` falls back to this
-     * method when the loaded branch has no carrier. Implementations return the descriptor from the
-     * nearest carrier BELOW the load floor (a `prompt_epoch` entry or a compaction restatement), or
-     * undefined when none exists (a genuinely pre-epoch session). File/in-memory backends need not
-     * implement it (their walks see the full tree).
+     * method when the loaded branch has no carrier. Implementations return the record of the
+     * nearest carrier BELOW the load floor (a `prompt_epoch` entry or a compaction's `details.promptEpoch`)
+     * AS STORED — the session reads it (a retired shape must reach it to be answered `legacy`; a backend that
+     * normalized it first would turn a pinned session into an unpinned one) — or undefined when none exists (a
+     * genuinely pre-epoch session). File/in-memory backends need not implement it (their walks see the full tree).
      */
     /** RB-104 (2026-07-25, defect probe): the bounded-window root this storage was woken with (F3), or
      *  null/absent for a full-tree load. Optional — a backend that never bounds its wake omits it. Callers
@@ -945,13 +952,7 @@ export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetad
      *  from a CORRUPT log (a head whose parent is simply missing); the two look identical byte-wise and
      *  must not be treated alike. `BaseSessionStorage` implements it for the bundled backends. */
     getFloorId?(): string | null;
-    getEpochAnchor?(): Promise<{
-        epoch: number;
-        artifactDigest: string;
-        packId: string;
-        assemblyApi: number;
-        activatedBy: "session_start" | "compaction" | "legacy_migration";
-    } | undefined>;
+    getEpochAnchor?(): Promise<unknown>;
 }
 /**
  * Options for `buildContext`/`buildSessionContext` — the read-side window awareness seam.
@@ -1018,7 +1019,7 @@ export interface Session<TMetadata extends SessionMetadata = SessionMetadata> {
      *  optionality keeps external `Session` implementers compatible. The consumer (`maybeCompact`'s
      *  epoch restatement) calls it with `?.()` — an implementer without it degrades to the pre-epoch
      *  path (no restatement), never a crash. */
-    getPromptEpoch?(): Promise<import("../../prompt-assembly/epoch.js").PromptEpochDescriptor | undefined>;
+    getPromptEpoch?(): Promise<import("../../prompt-assembly/epoch.js").StoredPromptEpoch | undefined>;
     /** Persist the git-status announced state as a first-class {@link GitAnnouncementEntry}
      *  (snapshot semantics; see `Session.appendGitAnnouncement`). OPTIONAL on the interface — same
      *  external-implementer posture as `getPromptEpoch`; consumers call it with `?.()` and an
@@ -1184,6 +1185,9 @@ export interface ToolCallEvent {
      *  emits that carry no per-call signal; a subscriber gating a wait on it must then fall back to
      *  whatever run-level signal it already holds (the historical shape, byte-identical). */
     signal?: AbortSignal;
+    /** The loop's reading of this call's arguments ({@link BeforeToolCallContext.readArguments}), handed on verbatim: a
+     *  subscriber that rewrites the call reads the rewrite through it before judging it. */
+    readArguments?: (args: unknown) => unknown;
 }
 export interface ToolResultEvent {
     type: "tool_result";

package/dist/engine/harness/types.js

@@ -33,7 +33,8 @@ export class ExecutionError extends Error {
     code;
     partialStdout;
     partialStderr;
-    constructor(code, message, cause, partial) {
+    noOutputSec;
+    constructor(code, message, cause, partial, noOutputSec) {
         super(message, cause === undefined ? undefined : { cause });
         this.name = "ExecutionError";
         this.code = code;
@@ -41,8 +42,13 @@ export class ExecutionError extends Error {
             this.partialStdout = partial.stdout;
         if (partial?.stderr !== undefined)
             this.partialStderr = partial.stderr;
+        if (noOutputSec !== undefined)
+            this.noOutputSec = noOutputSec;
     }
 }
+export function isTimeCutCode(code) {
+    return code === "timeout" || code === "liveness_no_output";
+}
 export class CompactionError extends Error {
     code;
     constructor(code, message, cause) {

package/dist/engine/llm/types.d.ts

@@ -1012,12 +1012,13 @@ export interface RouteCredential {
     /** The key itself, when the credential rides the apiKey knob. An EMPTY string is a present (per-call)
      *  credential that fails closed at emit time — presence, not truthiness (the degraded-secret contract). */
     apiKey?: string;
-    /** True when the credential rides as an auth-bearing HEADER (`authorization`/`x-api-key`, any case)
-     *  rather than the apiKey knob. The winning bag is named by {@link RouteCredential.carrierBag}. */
+    /** True when the credential rides (also) as credential HEADERS (`isCredentialHeaderName`: `authorization`,
+     *  `x-api-key`, `api-key`, a gateway's `Helicone-Auth`, …, any case) — alone, or beside the apiKey knob when one
+     *  source sets both. The winning bag is named by {@link RouteCredential.carrierBag}. */
     headersBorne?: boolean;
-    /** Which header bag carries a headers-borne credential (resolution precedence:
-     *  options > model > config; the apiKey knob outranks headers within options, while the config's
-     *  knob+header pair counts as ONE deployment credential — see `resolveRouteCredential`). */
+    /** Which header bag carries a headers-borne credential (resolution precedence: options > model > config, one rank
+     *  per source; within the hook's answer (`options`) and within the deployment config (`config`) the knob and the
+     *  bag's credential headers are ONE credential — see `resolveRouteCredential`). */
     carrierBag?: RouteCarrierBag;
 }
 /** The deployment half of the pairing judgment: the root the brain sends to when an entry names none —
@@ -1029,12 +1030,12 @@ export interface RoutePairingConfig {
     laneDefault?: string;
 }
 /** How an OK verdict is paired.
- *  - `"per-model"` — per-model credential, paired by construction.
+ *  - `"per-model"` — per-model credential, on the origin it is bound to (or not bound yet).
  *  - `"paired"` — deployment credential on the deployment's own root (declared, or the lane default).
  *  - `"keyless"` — no credential anywhere; nothing to protect. */
 export type RoutePairingPosture = "per-model" | "paired" | "keyless";
 /** Machine codes an adjudication refusal carries (minted here, forwarded verbatim by consumers). */
-export type RouteRefusalCode = "route.credential_mismatch" | "route.credential_missing";
+export type RouteRefusalCode = "route.credential_mismatch" | "route.credential_missing" | "route.credential_origin_mismatch" | "route.credential_answer_conflict";
 /** The structured account of a refusal — the two halves and the fix, every URL a DISPLAY spelling. */
 export interface RouteRefusalDetail {
     modelId: string;
@@ -1044,6 +1045,10 @@ export interface RouteRefusalDetail {
     requestBaseUrl: string;
     /** The declared root the credential is paired with (mismatch refusals), rendered. */
     configBaseUrl?: string;
+    /** The origin a per-model credential is bound to (`route.credential_origin_mismatch`), rendered. */
+    boundOrigin?: string;
+    /** The origin the refused request would have gone to (`route.credential_origin_mismatch`), rendered. */
+    requestOrigin?: string;
     /** One-line configuration fix. */
     fixHint: string;
 }

package/dist/engine/loop/agent-loop.d.ts

@@ -23,7 +23,7 @@
  */
 import type { AssistantMessage, ToolResultMessage } from "../llm/index.js";
 import { type AgentCoreStreamRuntimeDeps } from "./runtime-deps.js";
-import type { AfterToolCallResult, AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentToolResult, HaltRemainingDirective, StreamFn } from "./types.js";
+import type { AfterToolCallResult, AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, AgentToolCall, AgentToolResult, HaltRemainingDirective, StreamFn } from "./types.js";
 /** Callback used by synchronous loop runners to publish agent lifecycle events. */
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 /** Named reasons the loop goes around again. Assertable in tests via the trace sink. */
@@ -159,6 +159,17 @@ export type ExecutedToolCallOutcome = {
     result: AgentToolResult<unknown>;
     isError: boolean;
 };
+/**
+ * THE reading a value gets on its way to becoming a call's arguments: the tool's own preparation (`prepareArguments` —
+ * a default filled in, an alias folded), then the schema's coercions ({@link validateToolArguments}). The loop reads the
+ * model's call through it before the gate, hands the same reading to the gate (`BeforeToolCallContext.readArguments`)
+ * so every rewrite is judged as it will run, and reads the gate's output through the same two steps once more — refusing
+ * an output they would move. A preparation that throws throws here too (the value cannot be read: whoever adopts it
+ * refuses it, as the loop refuses a model call whose preparation throws). A value that does not VALIDATE is handed back as
+ * given: nothing invalid runs (the loop's own reading of the gate's output throws on it), and a judge of it judges bytes
+ * that never execute.
+ */
+export declare function readToolCallArguments(tool: AgentTool, toolCall: AgentToolCall, args: unknown): unknown;
 /**
  * How many tool names an unknown-tool miss spells out. A miss is a NAME problem: seeing a couple of dozen
  * real names is what lets a model spot the one it meant, while a full listing grows with the deployment