@sema-agent/core 7.56.0 → 7.57.0

package/dist/brain/request-params.js

@@ -1,4 +1,4 @@
-import { isCredentialHeaderName } from "../core/secret-env.js";
+import { isCredentialHeaderName, namesASecret } from "../core/secret-env.js";
 import { isPlainRecord } from "../core/mods/kernel/receive.js";
 import { BrainError } from "./errors.js";
 export const OPENAI_RESERVED = new Set([
@@ -129,6 +129,19 @@ export function mergeHeaders(...bags) {
     }
     return out;
 }
+export function declaredRequestValues(bags, stated, key) {
+    const out = new Set();
+    for (const bag of bags)
+        for (const value of Object.values(bag ?? {}))
+            if (typeof value === "string" && value !== "")
+                out.add(value);
+    for (const value of stated)
+        if (value !== undefined && value !== "")
+            out.add(value);
+    if (key !== undefined && namesASecret(key))
+        out.add(key);
+    return [...out];
+}
 export const OUTPUT_CAP_KEYS = {
     openai: ["max_tokens", "max_completion_tokens"],
     anthropic: ["max_tokens"],

package/dist/brain/stream-engine.d.ts

@@ -109,6 +109,12 @@ export declare const WAITING_FIRST_TOKEN_EVERY_MS = 30000;
 export interface SSERequest {
     url: string;
     headers: Record<string, string>;
+    /**
+     * Every header value this request was DECLARED with — the model entry's, the deployment's and the call's header bags as the
+     * route kept them, and the key — as the adapter built them. An endpoint's words lose these before the engine carries them
+     * ({@link remoteWords}); the engine's own protocol words (`content-type`, the version and the beta list it chose) are not declared.
+     */
+    declared: readonly string[];
     body: string;
     /**
      * The per-request output cap this request ACTUALLY carries on the wire, when the adapter sets one
@@ -194,6 +200,9 @@ export interface StreamControls {
      *  raising the provider's own in-band failure from `finalize`: the terminal message the engine mints for that
      *  failure keeps it (the text the provider streamed, the usage it reported), rather than an empty shell. */
     keepOutput(output: KeptOutput): void;
+    /** The provider's own words in an in-band failure, as the engine carries them: this attempt's request ({@link SSERequest.declared}) taken
+     *  out, then the credential vocabulary. A judge that reads the frame (the condition, the input-too-long anchor) reads the raw words. */
+    providerWords(words: string): string;
 }
 /** The output a parser hands over with {@link StreamControls.keepOutput}. */
 export interface KeptOutput {

package/dist/brain/stream-engine.js

@@ -9,7 +9,7 @@ import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.j
 import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry, reportExtraBodyDropped } from "./status-sink.js";
 import { createAttemptController, firstByteWindow, refuseRetiredTimeoutKnobs, resolveFirstByteRetries, resolveWatchdogMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, } from "./timeout.js";
 import { readMember, thrownText } from "../core/thrown-value.js";
-import { egressText } from "../core/untrusted-egress.js";
+import { remoteWords } from "../core/protocol-http-auth.js";
 const DEFAULT_MAX_RETRIES = 10;
 const MAX_RETRIES_ENV_CEILING = 15;
 const MAX_RETRIES_ENV = "SEMA_MAX_RETRIES";
@@ -294,6 +294,13 @@ export function runStreamingBrain(args) {
     let attemptPartial;
     let attemptOutput;
     let routeSeen;
+    let declaredSeen = [];
+    const echoCarried = (value, field) => {
+        if (remoteWords(value, declaredSeen) === value)
+            return value;
+        emitBrainTelemetry({ kind: "echo_dropped", field });
+        return undefined;
+    };
     void run()
         .catch((err) => {
         const aborted = signal?.aborted === true || isAbortError(err);
@@ -313,7 +320,8 @@ export function runStreamingBrain(args) {
             errorMsg.usage = kept.usage;
         }
         errorMsg.stopReason = aborted ? "aborted" : "error";
-        errorMsg.errorMessage = thrownText(err);
+        const said = thrownText(err);
+        errorMsg.errorMessage = brainErrorCodeOf(err) !== undefined ? said : remoteWords(said, declaredSeen);
         const failure = aborted ? {} : thrownBrainFailure(err);
         if (failure.code !== undefined) {
             if (failure.errorKind !== undefined)
@@ -328,13 +336,17 @@ export function runStreamingBrain(args) {
                 const statusNum = typeof status === "number" ? status : undefined;
                 if (namesTheFailure(statusNum))
                     errorMsg.apiErrorStatus = statusNum;
-                if (requestIdSeen !== undefined)
-                    errorMsg.requestId = requestIdSeen;
+                const requestId = requestIdSeen === undefined ? undefined : echoCarried(requestIdSeen, "requestId");
+                if (requestId !== undefined)
+                    errorMsg.requestId = requestId;
                 if (routeSeen !== undefined)
                     errorMsg.apiErrorRoute = routeSeen;
                 const providerCode = readMember(err, "providerCode");
-                if ((statusNum === undefined || refusedTheRequest(statusNum)) && typeof providerCode === "string" && isProviderEchoShape(providerCode))
-                    errorMsg.apiErrorCode = providerCode;
+                if ((statusNum === undefined || refusedTheRequest(statusNum)) && typeof providerCode === "string" && isProviderEchoShape(providerCode)) {
+                    const apiErrorCode = echoCarried(providerCode, "apiErrorCode");
+                    if (apiErrorCode !== undefined)
+                        errorMsg.apiErrorCode = apiErrorCode;
+                }
                 const condition = readMember(err, "providerCondition");
                 const source = readMember(err, "providerConditionSource");
                 if (isProviderCondition(condition) && isProviderConditionSource(source)) {
@@ -370,6 +382,7 @@ export function runStreamingBrain(args) {
             r.onCommitted?.();
             reportRequestStrip(model, r);
             routeSeen = admittedRequestRoute(r.route);
+            declaredSeen = r.declared;
         };
         commit(req);
         const dialect = resolveProviderDialect(req.url, model.api);
@@ -475,7 +488,7 @@ export function runStreamingBrain(args) {
                     }
                     else if (classifyFetchThrow(e) === "request_unbuildable") {
                         cc.dispose();
-                        throw new BrainError("invalid_request", `${httpLabel} request could not be built: ${egressText("same-principal", stripUrlCredentials(thrownText(e)))}`);
+                        throw new BrainError("invalid_request", `${httpLabel} request could not be built: ${remoteWords(stripUrlCredentials(thrownText(e)), req.declared)}`);
                     }
                     else {
                         netErr = e;
@@ -634,14 +647,14 @@ export function runStreamingBrain(args) {
                         continue;
                     }
                     if (netErr) {
-                        const chain = describeNetworkError(netErr);
+                        const chain = remoteWords(describeNetworkError(netErr), req.declared);
                         const proxyRefusal = connectReading?.proxyRefusal;
                         throw new BrainError("network", proxyRefusal === undefined ? chain : `${proxyTunnelRefusedSentence(proxyRefusal.status)} — ${chain}`, undefined, { apiError: true });
                     }
                     if (r !== undefined && errorBody === undefined)
                         errorBody = await readErrorBody(r, signal);
                     const terminalVerdict = judge();
-                    const detail = errorBody?.text ?? "";
+                    const detail = errorBody === undefined ? "" : remoteWords(errorBody.endedNormally ? errorBody.text : errorBody.text.replace(/\S+$/u, ""), req.declared);
                     const status = r?.status ?? 0;
                     const itl = terminalVerdict?.inputTooLong ?? "no";
                     const providerCode = refusedTheRequest(status) ? readProviderErrorCode(errorBody) : undefined;
@@ -737,6 +750,7 @@ export function runStreamingBrain(args) {
                 keepOutput: (output) => {
                     attemptOutput = output;
                 },
+                providerWords: (words) => remoteWords(words, req.declared),
             });
             const INBAND_OVERLOAD_WARNING = "API overloaded mid-response. The response above may be incomplete.";
             const onLineOverloadTierA = (line) => {
@@ -761,7 +775,7 @@ export function runStreamingBrain(args) {
                         throw e;
                     failure = {
                         kind: "connection",
-                        err: new BrainError("network", `mid-stream read failed: ${describeNetworkError(e)}`, undefined, { apiError: true }),
+                        err: new BrainError("network", `mid-stream read failed: ${remoteWords(describeNetworkError(e), req.declared)}`, undefined, { apiError: true }),
                     };
                     break readLoop;
                 }

package/dist/brain/stream-shared.d.ts

@@ -17,9 +17,10 @@ import { type AssistantMessage, type ModelOutputInvalid, type StreamDropCause }
 /** The warning (the reference's former words; later replaced by a resume request) stamped beside `partialFinalized` when a stream ended before its close — by the
  *  mid-stream promotion (the body threw) and by the parsers' own finalize (content arrived, no finish frame). */
 export declare const STREAM_TORN_WARNING = "Connection closed mid-response. The response above may be incomplete.";
-/** A provider word as a stream-end seat carries it: the word in the provider echo shape, else `?` — the fact that a
- *  word arrived survives, bytes outside the shape do not (the echo discipline: dropped, never rewritten). */
-export declare function echoFoldedWord(raw: string): string;
+/** A provider word as a stream-end seat carries it: the word in the provider echo shape that the stream's mint
+ *  (`providerWords`) leaves as it is, else `?` — the fact that a word arrived survives, bytes outside the shape or holding
+ *  what the request was declared with do not (the echo discipline: dropped, never rewritten). */
+export declare function echoFoldedWord(raw: string, providerWords: (words: string) => string): string;
 /**
  * The record of what arrived after a stream's first terminal statement — the one ordering rule both wire parsers
  * apply: the first ending (a finish / stop reason, a message stop, an in-band error) decides the turn; after it the
@@ -27,7 +28,7 @@ export declare function echoFoldedWord(raw: string): string;
  * here. Rides `AssistantMessage.streamEndIgnored` (the first refused frame's kind and word, how many came); the
  * Runner announces it (`route.stream_end_ignored`).
  */
-export declare function createStreamEndLedger(): {
+export declare function createStreamEndLedger(providerWords: (words: string) => string): {
     note(statement: StreamEndStatement, word: string): void;
     readonly ignored: AssistantMessage["streamEndIgnored"];
 };

package/dist/brain/stream-shared.js

@@ -3,14 +3,14 @@ import { inspectDegenerate } from "./repetition.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { stampStreamDrops } from "../internal/llm.js";
 export const STREAM_TORN_WARNING = "Connection closed mid-response. The response above may be incomplete.";
-export function echoFoldedWord(raw) {
-    return isProviderEchoShape(raw) ? raw : "?";
+export function echoFoldedWord(raw, providerWords) {
+    return isProviderEchoShape(raw) && providerWords(raw) === raw ? raw : "?";
 }
-export function createStreamEndLedger() {
+export function createStreamEndLedger(providerWords) {
     let ignored;
     return {
         note(statement, word) {
-            ignored = ignored === undefined ? { statement, word: echoFoldedWord(word), frames: 1 } : { ...ignored, frames: ignored.frames + 1 };
+            ignored = ignored === undefined ? { statement, word: echoFoldedWord(word, providerWords), frames: 1 } : { ...ignored, frames: ignored.frames + 1 };
         },
         get ignored() {
             return ignored;

package/dist/core/allow-entry.d.ts

@@ -73,15 +73,6 @@ export type CompiledAllowEntry = {
     readonly kind: "domain";
     readonly rule: PersistedRule;
 };
-/**
- * THE near-miss reading of a tool name the judgment calls current: the spelling the run mounts when the run mounts no tool of this
- * exact name but one that differs from it only by case (`BASH` beside `Bash`), else `undefined`. Two kinds of name are never a near
- * miss, because the roster they would be read against is not the final one: an engine tool's (the engine mounts some of its tools
- * after a list is read) and a protocol tool's (a refresh mounts and unmounts them while the run goes on) — in both the exact
- * spelling can be the right one by the time it matters. Every station that asks "is this name a case twin of a mounted tool" reads
- * this answer: an entry list ({@link readRuleEntry}), a tool policy's name lists (the prepare-time policy-name audit).
- */
-export declare function nearMissSpellingOf(name: string, roster: ReadonlySet<string>): string | undefined;
 /**
  * THE universe a ROOT-facing tool-name list is read against: every name the engine's catalog carries, and the names the reader knows
  * are carried (`carried`). A list is root-facing when it bounds the tools of the run that holds it — the run's own `allowTools` /
@@ -135,7 +126,9 @@ export declare const AUTO_STRIPPED_PROGRAMS: readonly ["python", "python3", "pyt
  * disclosed.
  */
 export declare function autoStripped(compiled: CompiledAllowEntry, call: ToolCallRequest | undefined): boolean;
-/** {@link autoStripped} over a person's stored ALLOW row (a deny / ask row is never stripped; a path row never is). */
+/** {@link autoStripped} over a person's stored ALLOW row, read as its list twin ({@link entryOfRow}): a row is stripped exactly when
+ *  the entry spelling the same rule is (a deny / ask row never is; a row no grammar reads has no twin and is not stripped here — the
+ *  lane reads no allow it cannot parse). */
 export declare function autoStrippedRule(rule: PersistedRule, call: ToolCallRequest): boolean;
 /** One row a list matcher reads. */
 export interface AllowEntryRow {

package/dist/core/allow-entry.js

@@ -2,11 +2,11 @@ import { heldBy } from "./tool-name-readings.js";
 import { ruleIssue } from "./permission-rules.js";
 import { isCoveringRuleName, ruleNameCovers } from "./namespaced-rule-name.js";
 import { ruleSpellingOf } from "./permission-rule-syntax.js";
-import { judgeRuleToolName, splitNamespacedName } from "./tool-name-aliases.js";
+import { splitNamespacedName, toolNameFaultOf } from "./tool-name-aliases.js";
 import { catalogToolNames, isShellFaceToolName } from "./tool-registry.js";
 import { ALLOW_RULE_MEMBERS } from "./allow-rule-shadow.js";
 import { callHostTargetOf } from "./host-target.js";
-import { COMMAND_RULE_TOOL, adjudicatePersistedDomainRules, adjudicatePersistedNameRules, commandCoverageOf, laneToolNamesOf, ruleContentOf, noticeRuleText, parseRuleText, programRunReachOf, ruleToolGrammarOf, commandPatternMayRun } from "./permission-rule-model.js";
+import { adjudicatePersistedDomainRules, wholeToolRuleReaches, adjudicatePersistedNameRules, commandCoverageOf, laneToolNamesOf, ruleContentOf, noticeRuleText, parseRuleText, programRunReachOf, ruleToolGrammarOf, commandPatternMayRun } from "./permission-rule-model.js";
 import { pathRuleLaneAnswer } from "./runner/permission-rule-lanes.js";
 import { callTargetReadingOf } from "./effective-path-target.js";
 import { splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
@@ -25,30 +25,12 @@ export function nonListValueLabel(read) {
 function ruleRowOf(parsed) {
     return { ...parsed, scope: { kind: "global" }, adds: [{ dot: { actor: "list", counter: 1 }, origin: "user", createdAt: "" }] };
 }
-function mountedSpellingOf(name, roster) {
-    const folded = name.toLowerCase();
-    for (const mounted of roster)
-        if (mounted.toLowerCase() === folded)
-            return mounted;
-    return undefined;
-}
-export function nearMissSpellingOf(name, roster) {
-    if (roster.has(name) || catalogToolNames().has(name) || splitNamespacedName(name) !== undefined)
-        return undefined;
-    return mountedSpellingOf(name, roster);
-}
 export function rootFacingToolNames(carried) {
     return new Set([...catalogToolNames(), ...carried]);
 }
 function toolNameReading(name, roster, behavior) {
-    const verdict = judgeRuleToolName(name, roster, behavior);
-    if (verdict.kind === "unprefixed_namespace")
-        return { kind: "inert", reason: "tool_name", verdict: verdict.kind };
-    if (verdict.kind !== "current") {
-        return { kind: "inert", reason: "tool_name", verdict: verdict.kind, guidance: verdict.guidance, ...(verdict.currentName !== undefined ? { currentName: verdict.currentName } : {}) };
-    }
-    const mounted = nearMissSpellingOf(name, roster);
-    return mounted === undefined ? undefined : { kind: "inert", reason: "near_miss", currentName: mounted };
+    const fault = toolNameFaultOf(name, roster, behavior);
+    return fault === undefined ? undefined : { kind: "inert", ...fault };
 }
 export function readRuleEntry(raw, behavior, roster) {
     const inert = (reason) => ({ kind: "inert", reason });
@@ -165,12 +147,22 @@ export function autoStripped(compiled, call) {
     }
 }
 export function autoStrippedRule(rule, call) {
-    return rule.behavior === "allow" && rule.tool === COMMAND_RULE_TOOL && autoStripped({ kind: "command", rule }, call);
+    if (rule.behavior !== "allow")
+        return false;
+    const entry = entryOfRow(rule);
+    return entry !== undefined && autoStripped(entry, call);
+}
+function entryOfRow(rule) {
+    if (rule.match === "tool")
+        return isShellFaceToolName(rule.tool) ? { kind: "shell", name: rule.tool } : { kind: "tool", name: rule.tool };
+    const grammar = ruleToolGrammarOf(rule.tool);
+    return grammar === undefined ? undefined : { kind: grammar, rule };
 }
 const NO_LEADS = new Map();
 function nameRowReaches(compiled, req) {
-    const covers = compiled.kind === "covering" ? (n) => ruleNameCovers(compiled.pattern, n) : compiled.kind === "tool" || compiled.kind === "shell" ? (n) => n === compiled.name : undefined;
-    return covers !== undefined && answersTo(req, covers);
+    if (compiled.kind === "tool" || compiled.kind === "shell")
+        return wholeToolRuleReaches(compiled.name, req);
+    return compiled.kind === "covering" && answersTo(req, (n) => ruleNameCovers(compiled.pattern, n));
 }
 function commandOf(req) {
     const tool = laneToolNamesOf(req).find((n) => ruleToolGrammarOf(n) === "command");

package/dist/core/approval-object.d.ts

@@ -1,6 +1,7 @@
 import type { PendingAction } from "./checkpoint-store.js";
 import type { CallTargetReading } from "./effective-path-target.js";
 import { type SkillGrantSource } from "./skill-grant.js";
+import type { ReadLanding } from "../tools/fs/shell-read-identity.js";
 import type { ToolCallPathTarget, ToolFamily, ToolHostTarget } from "./tool-face.js";
 import { type ToolRosterEntry } from "./tool-roster.js";
 type ParkedApproval = Extract<PendingAction, {
@@ -16,6 +17,15 @@ export type ApprovalTargetRole = (typeof APPROVAL_TARGET_ROLES)[number];
 export type ApprovalTargets = {
     readonly [R in ApprovalTargetRole]?: string | null;
 };
+/** The row's `targetReads` member: per read candidate the shell read station judged for the parked bytes (its key's
+ *  digest), where it landed (its settled targets' digest — a pattern lands on a set). A sibling of `targets`, not a key
+ *  inside it: a reader that knows only the path roles reads an unknown key there as damage and spends the approval, where
+ *  a member of its own carries its own word and that reader refuses the row unread (`version_newer`). Present exactly when
+ *  the station judged the parked bytes — `{}` when it found no read candidate: a candidate appearing by the resume is a
+ *  read the card did not cover. */
+export type ApprovalTargetReads = {
+    readonly [candidate: string]: string;
+};
 /** The tool member as the row carries it: every member optional (a row is read, never trusted to be whole). */
 export interface ApprovalTool {
     readonly capabilityId?: string;
@@ -29,17 +39,21 @@ export interface ApprovalTool {
 export interface ApprovalObject {
     /** Absent on a row minted before the identity members (all four absent): such a row binds the tool's name alone. */
     readonly tool?: ApprovalTool;
-    /** The row's member as stored — read, validated, by the judge. */
+    /** The row's two target members as stored — read, validated, by the judge. */
     readonly targets?: unknown;
+    readonly targetReads?: unknown;
     readonly grants?: string;
 }
 /** The view of one parked approval's object. */
 export declare function approvalObjectOf(row: ParkedApproval): ApprovalObject;
-/** The `targets` member of a reading: per role, the canonical view, or `null` for a view the environment was asked for
- *  and did not answer; nothing when no role was read either way (or no reading was taken). The park mints it from the
- *  gate's reading of the parked bytes; the execution station reads the bytes that will run the same way. */
-export declare function approvalTargetsOf(reading: CallTargetReading | undefined): {
+/** The TARGETS of a reading — the one mint of both members, for the row and for the live call alike: `targets` per role,
+ *  the canonical view, or `null` for a view the environment was asked for and did not answer (nothing when no role was read
+ *  either way, or no reading was taken); `targetReads` per read candidate the shell read station judged, where it landed
+ *  (nothing when the station judged no candidate of these bytes). The park mints them from the gate's readings of the parked
+ *  bytes; the execution station reads the bytes that will run the same way. */
+export declare function approvalTargetsOf(reading: CallTargetReading | undefined, reads?: readonly ReadLanding[]): {
     targets?: ApprovalTargets;
+    targetReads?: ApprovalTargetReads;
 };
 /** Where a resume judges the object: before the claim (the decided bytes), before the session is touched (the live
  *  tool), right before the execution (the tool as mounted then — a host's re-dial can replace it between the two — and the
@@ -71,6 +85,8 @@ export interface LiveApprovalObject {
     readonly skillToolName?: string;
     /** execution: the reading of the bytes that will run, taken at this station (`undefined`: none could be taken). */
     readonly targetReading?: CallTargetReading | undefined;
+    /** execution: where this leg's shell read station found those bytes' reads land (`undefined`: it holds no judgment of them). */
+    readonly reads?: readonly ReadLanding[] | undefined;
     /** execution: the bytes the decision rewrote the call to, as the tool reads them; absent when it rewrote nothing. When
      *  the row's binding does not cover them ({@link licenseCovers}, the one judge of "are these the approved bytes") the
      *  person approved bytes whose target the row never recorded, and the targets member is not judged. */

package/dist/core/approval-object.js

@@ -5,22 +5,23 @@ import { toolIdentityOf } from "./tool-roster.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 export const APPROVAL_TARGET_ROLES = Object.freeze(["protective", "declared"]);
 export function approvalObjectOf(row) {
-    const { capabilityId, contractId, shapeDigest, implementationRevision, family, pathTarget, hostTarget, targets, boundGrantDigest } = row;
+    const { capabilityId, contractId, shapeDigest, implementationRevision, family, pathTarget, hostTarget, targets, targetReads, boundGrantDigest } = row;
     const carried = [capabilityId, contractId, shapeDigest, implementationRevision].some((m) => m !== undefined);
     return {
         ...(carried ? { tool: { capabilityId, contractId, shapeDigest, implementationRevision, family, pathTarget, hostTarget } } : {}),
         ...(targets !== undefined ? { targets } : {}),
+        ...(targetReads !== undefined ? { targetReads } : {}),
         ...(boundGrantDigest !== undefined ? { grants: boundGrantDigest } : {}),
     };
 }
-export function approvalTargetsOf(reading) {
+export function approvalTargetsOf(reading, reads) {
     const targets = {};
     for (const role of APPROVAL_TARGET_ROLES) {
         const view = reading?.[role];
         if (view?.kind === "path" && (view.canonical !== undefined || view.unread === true))
             targets[role] = view.canonical ?? null;
     }
-    return Object.keys(targets).length > 0 ? { targets } : {};
+    return { ...(Object.keys(targets).length > 0 ? { targets } : {}), ...(reads !== undefined ? { targetReads: Object.fromEntries(reads.map((r) => [r.key, r.landing])) } : {}) };
 }
 export const APPROVAL_STATION_MEMBERS = Object.freeze({
     claim: Object.freeze(["grants"]),
@@ -52,22 +53,48 @@ function judgeTool(row, live) {
     return { member: "tool", disposition: "veto", code: "resume.target_moved", message: vetoed(row.toolName, "the tool's face (its display family, or the path target or URL slot it declares) changed after the approval") };
 }
 function judgeTargets(row, live) {
-    const bound = row.targets;
-    if (bound === undefined || ("decided" in live && !licenseCovers(row.boundInputHash, live.decided)))
+    if ((row.targets === undefined && row.targetReads === undefined) || ("decided" in live && !licenseCovers(row.boundInputHash, live.decided)))
         return undefined;
-    const roles = typeof bound === "object" && bound !== null && !Array.isArray(bound) ? Object.entries(bound) : [];
-    const whole = roles.length > 0 && roles.every(([k, v]) => APPROVAL_TARGET_ROLES.includes(k) && (v === null || (typeof v === "string" && v.length > 0)));
-    if (!whole)
-        return { member: "targets", disposition: "veto", code: "resume.target_moved", message: vetoed(row.toolName, "the target member of the approval on its checkpoint row is damaged (not a reading → resolved location record)") };
-    const now = approvalTargetsOf(live.targetReading).targets ?? {};
-    const where = (p) => (p === null ? "did not resolve" : `resolved to ${shown(p)}`);
-    for (const [role, was] of roles) {
-        const is = now[role];
-        if (is === was)
-            continue;
-        return { member: "targets", disposition: "veto", code: "resume.target_moved", message: vetoed(row.toolName, is === undefined ? `where its target resolves (it ${where(was)} when the card was asked) could not be established on this leg` : `its target ${is === null ? "does not resolve" : `resolves to ${shown(is)}`} now and ${where(was)} when the card was asked`) };
+    const why = landedElsewhere(row.targets, row.targetReads, live);
+    return why === undefined ? undefined : { member: "targets", disposition: "veto", code: "resume.target_moved", message: vetoed(row.toolName, why) };
+}
+const DIGEST = /^[0-9a-f]{64}$/;
+function landedElsewhere(bound, boundReads, live) {
+    if (bound !== undefined) {
+        const roles = typeof bound === "object" && bound !== null && !Array.isArray(bound) ? Object.entries(bound) : [];
+        const whole = roles.length > 0 && roles.every(([k, v]) => APPROVAL_TARGET_ROLES.includes(k) && (v === null || (typeof v === "string" && v.length > 0)));
+        if (!whole)
+            return "the target member of the approval on its checkpoint row is damaged (not a reading → resolved location record)";
+        const now = approvalTargetsOf(live.targetReading).targets ?? {};
+        const where = (p) => (p === null ? "did not resolve" : `resolved to ${shown(p)}`);
+        for (const [role, was] of roles) {
+            const is = now[role];
+            if (is === was)
+                continue;
+            return is === undefined ? `where its target resolves (it ${where(was)} when the card was asked) could not be established on this leg` : `its target ${is === null ? "does not resolve" : `resolves to ${shown(is)}`} now and ${where(was)} when the card was asked`;
+        }
     }
-    return undefined;
+    if (boundReads === undefined)
+        return undefined;
+    const record = typeof boundReads === "object" && boundReads !== null && !Array.isArray(boundReads);
+    const reads = record ? Object.entries(boundReads) : [];
+    if (!record || !reads.every(([k, v]) => DIGEST.test(k) && typeof v === "string" && DIGEST.test(v)))
+        return "the read member of the approval on its checkpoint row is damaged (not a read → landing record)";
+    if (live.reads === undefined)
+        return `where its reads land (the read station judged ${reads.length} when the card was asked) could not be established on this leg`;
+    const was = new Map(reads);
+    const now = new Map(Object.entries(approvalTargetsOf(undefined, live.reads).targetReads ?? {}));
+    const named = (key) => live.reads?.find((r) => r.key === key);
+    const added = [...now.keys()].find((k) => !was.has(k));
+    if (added !== undefined || [...was.keys()].some((k) => !now.has(k)))
+        return `this leg reads the command differently than when the card was asked (${added !== undefined ? `${shown(named(added)?.raw ?? "?")} is read now at a place or in a form the card did not cover` : "a read the card covered is not read now"})`;
+    const movedKey = [...now.keys()].find((k) => now.get(k) !== was.get(k));
+    const moved = movedKey === undefined ? undefined : named(movedKey);
+    if (movedKey === undefined)
+        return undefined;
+    const targets = moved?.targets ?? [];
+    const at = targets.length === 0 ? "cannot be placed" : `lands on ${shown(targets[0])}${targets.length > 1 ? ` (and ${targets.length - 1} more)` : ""}`;
+    return `its read ${shown(moved?.raw ?? "?")} ${at} now, not where it landed when the card was asked`;
 }
 function judgeGrants(row, live, station) {
     const refusal = parkedSkillApprovalRefusal(row, live.args, live.skills ?? [], live.skillToolName ?? "", station);

package/dist/core/ask-origin.d.ts

@@ -203,8 +203,8 @@ export type RuleOffersAbsence = (typeof RULE_OFFERS_ABSENCES)[number];
  * class row's `ruleMayClear` ({@link classifyAsk} — every door below is a class there), read once by the gate's allow layer.
  *  · `word` — the DISCLOSED reason ({@link RuleOffersAbsence}), first door wins, in the display order the card has always
  *    used (governance, the outranked allow, the hook, the ask rule, the two ancestor doors, then the marks). Display
- *    only. A structural door the offer factory owns (no lane wired, a tool it does not speak for, a
- *    task that cannot hold a rule) is decided BEFORE this and is deliberately silent;
+ *    only. The structural door the offer factory owns (no rule speaks for the call: no lane wired, a
+ *    task that cannot hold a rule, a call the lane does not judge) is decided BEFORE this and is deliberately silent;
  *  · `mandated` — the FACT the ask carries as its own member. Read off the whole mandate set, so which
  *    door is DISPLAYED cannot change it: an ask that is both outranked and mandated is mandated;
  *  · `mandate` — WHICH table word the bit stands on, only when the MARKS family is its whole reason (no

package/dist/core/auto-compaction.d.ts

@@ -3,8 +3,8 @@ import { type Message, type Model, type Tool } from "../internal/llm.js";
 import type { ContextWindowOverlay } from "./context-settings.js";
 import type { PostCompactContext, PreCompactContext, PreCompactResult } from "./hooks.js";
 import type { TraceEvent } from "./trace.js";
-import type { Brain } from "./types.js";
-import type { TaskEvent, TaskEventIdentity } from "./task-event.js";
+import type { Brain, ModelRef, TaskSpec } from "./types.js";
+import type { CompactOutcome, TaskEvent, TaskEventIdentity } from "./task-event.js";
 import type { CompactionEffect } from "./frame-settlement.js";
 import type { MintedAttachmentFrame } from "./user-attachment.js";
 /**
@@ -39,13 +39,18 @@ export type CompactionPhaseDurations = Omit<Extract<TraceEvent, {
     kind: "compaction.phase_timings";
 }>, "kind" | "version" | "taskId" | "ts" | "durationMs">;
 /** True iff `err` is a compaction failure caused by a manual compact() caller WITHDRAWING its
- *  request — see {@link MaybeCompactOptions.manualCancelSignal}. Two mint sites since the
- *  design/374 slice-3 commit-boundary re-check (C16): the summary call's own abort outcome, and
- *  the pre-persist "cancelled before commit" throw (a brain that ignored the abort finished the
- *  summary, but the withdrawal still fired before anything landed). Absence of the marker means
+ *  request — see {@link MaybeCompactOptions.manualCancelSignal}. Minted at every cut point of the
+ *  pass: before the pass commits, while the summary provider or the credential callback is
+ *  answering ({@link untilPassCut}), the summary call's own abort outcome, and the pre-persist
+ *  "cancelled before commit" throw (design/374 slice-3, C16: a brain that ignored the abort finished
+ *  the summary, but the withdrawal still fired before anything landed). Absence of the marker means
  *  the failure was NOT the withdrawal: a real summarizer error racing a late cancel stays
  *  unmarked so the caller's breaker/onError accounting still sees it. */
 export declare function isCompactionManualCancel(err: unknown): boolean;
+/** The ONE reason a failed compaction pass reports, read by every lane that accounts for one (the turn boundary, the end-of-task pass,
+ *  the prompt-too-long recovery) for its trace frame and its `compaction_outcome{failed}` event: the thrown value's words through the
+ *  same-principal tier, THEN bounded — minted before the cut, so the cut can leave no part of a value. */
+export declare function compactionFailureReason(err: unknown): string;
 /**
  * design/145 §1/§3 — the window-safety decision surfaced to the caller BEFORE the summary call
  * (same pre-call posture as `onInputTruncated`: the disclosure must survive a later summary
@@ -734,6 +739,66 @@ export interface CompactedFrameSource {
 export declare function mintCompactedEvent(comp: CompactedFrameSource, trigger: "auto" | "manual" | "forced", identity: TaskEventIdentity): Extract<TaskEvent, {
     type: "compacted";
 }>;
+/** `Runner.compactSession`'s request — the out-of-run manual compaction of a session no leg of the Runner holds. A plain
+ *  data object; the keys are a closed set. */
+export interface CompactSessionRequest {
+    /** The session to compact. It must exist. */
+    sessionId: string;
+    /** The model the session's next turn runs on — its window bounds the pass (resolved like `TaskSpec.model`). */
+    model: ModelRef;
+    /** This pass's summarization instructions: they REPLACE `compaction.instructions` and the default for this pass (the
+     *  `TaskStream.compact` reading); sanitized and capped like every instructions channel. */
+    instructions?: string;
+    /** The members of `TaskSpec.compaction` a pass reads, as a run would carry them. */
+    compaction?: Pick<NonNullable<TaskSpec["compaction"]>, "enabled" | "reserveTokens" | "keepRecentTokens" | "instructions" | "clampTolerance">;
+    /** The independent summary model (`TaskSpec.compactionModel`); absent ⇒ the deployment's `summarize` role (or its tier
+     *  default), else the main model. A role-derived model whose key↔URL pairing is broken falls back to the main model,
+     *  announced, as on a run. */
+    compactionModel?: ModelRef;
+    /** Per-model credentials (`TaskSpec.getApiKeyAndHeaders`). */
+    getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
+    /** Withdraws the pass: aborted before the session's lock is taken, the answer is `"mooted"` with nothing done; while the pass
+     *  runs the summary call and the credential wait read it (store reads and appends, and the pre-flight's own 5 s timer, do not); a pass that already persisted is not undone. */
+    signal?: AbortSignal;
+}
+/** `Runner.compactSession`'s answer. */
+export interface CompactSessionResult {
+    /** What the pass did — the closed set `TaskStream.compact` resolves with. */
+    outcome: CompactOutcome;
+    /**
+     * The pass's frames, in order, each with its own `eventId` and no task attribution: `compaction_started` once the
+     * pass committed, then the frame that ends it — `compacted` (`trigger: "manual"`) on a landing, else
+     * `compaction_outcome` (`trigger: "manual"`). Empty when the pass never ran (a withdrawn request). Returned, not
+     * streamed: a `compaction_started` here is a record of the pass, not a live progress signal.
+     */
+    events: Array<Extract<TaskEvent, {
+        type: "compaction_started" | "compacted" | "compaction_outcome";
+    }>>;
+    /** The model calls the pass made (the summary, a hook's `$.model.complete`), priced as a run's side calls are; absent
+     *  when none was made. `usageMissing` ⇒ a reply reported no usage (a lower bound); `unpriced` ⇒ a call ran on a model
+     *  the deployment could not price. */
+    usage?: {
+        tokens: number;
+        totalInputTokens: number;
+        promptTokens: number;
+        cachedTokens: number;
+        cacheWriteTokens: number;
+        outputTokens: number;
+        costMicroUsd: number;
+        usageMissing?: true;
+        unpriced?: true;
+    };
+}
+/**
+ * The MANUAL outcome of a pass that returned (did not throw) — the one reading for every manual pass: the turn
+ * boundary serving a `TaskStream.compact` request and the out-of-run `Runner.compactSession`. A manual pass forces
+ * (`force` + `minTokens: 0`), so the floor's `suppressedByFloor` cannot occur and is not a case here.
+ */
+export declare function manualCompactOutcomeOf(comp: {
+    compacted: boolean;
+    blocked?: boolean;
+    disabled?: boolean;
+}): CompactOutcome;
 /**
  * THE mint of the `compaction_started` wire frame — the opening half of the pair whose closing half is the
  * `compacted` frame above (or a `compaction_outcome` that carries the same `pass`). One function, three