@sema-agent/core 5.0.1 → 5.2.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 5.2.0 (2026-08-03)
+
+_The v5.0.1..v5.1.0 full-window dual-lens review's repair batch (67 findings, all dispositioned; see docs/REVIEW-BACKLOG.md). Theme: the 5.1.0 retirements now refuse loudly EVERYWHERE they promised to, and the new disclosure seats reach the deployments they were built for._
+
+### Behavior / BREAKING-leaning (all loud-by-design)
+
+- **memory**: a `TaskSpec.memory` still carrying the retired singular `scope` throws `config.memory_scope_spelling` at task start (it silently normalized to memory-OFF for the whole task).
+- **tool policy**: a caller policy decision carrying the retired `reason` field is refused fail-closed at the policy fold — `deny` keeps denying with a migration text, `allow`/`ask` are NOT honored. (The 5.1.0 claim that `{reason}` "compiles red" was false in method-position shapes; this is the runtime signal that was missing.)
+- **hooks / resume**: the same tripwire reaches the two decision faces that do not cross the fold — a PreToolUse hook result carrying `reason` is refused fail-closed at both hook entry points (its `additionalContext`/`updatedInput` do not take effect either; `allow{reason}` used to run the tool), and the durable-resume re-checks (edited-args policy re-judgment, session-rule narrowing layer) refuse the retired dialect on the same helper.
+- **openai brain**: an out-of-contract `reasoning` value is treated as absent on every wire format (it used to pass through verbatim as `reasoning_effort`, so the two brains disagreed on the same input).
+- **ToolSearch**: a `select` argument key in any shape (the retired array form included) is a loud invalid-arguments naming `query:"select:A,B"` (it used to parse as an empty query and answer "No deferred tools matched"); stored activations replay tolerantly.
+- **Grep**: the retired `regex`/`max_results` keys refuse with their living replacements (pattern IS a regex; `head_limit`) — `max_results` was silently accepted and ignored.
+- **TodoWrite**: the public raw-spec execute lane refuses a missing/empty `activeForm` (it used to synthesize the label and accept what the schema refuses); the simple-arm card teaches the required form.
+- **protocol table**: `MCP_NAMESPACE.parse` rejects an empty tool segment; `makeName` throws on empty/separator-carrying segments (round-trip symmetry); both survive destructuring (`this`-free).
+- **workflow store**: a `resolveName` implementation still returning the retired bare-string resolution gets a structured migration error naming the `{script}` form (was a TypeError quoting the whole script source).
+- **Read/Edit/Write**: `file_path` is schema-REQUIRED, so a call carrying only the retired `path` alias is loud invalid-arguments naming `file_path` — on the live lane and on durable replay alike. 5.1.0 retired the alias from the schema's declared properties but left `file_path` optional; TypeBox's object check is non-strict, so `{path}` still validated with no `file_path` present and the tool body read the target back out through the gate reader's over-read arm. The alias therefore kept working end-to-end and no caller ever learned it had to migrate — the 5.1.0 note's "re-validates loudly on resume" was not true until now. The security-gate readers keep their `path` arm unchanged: that side is fail-closed coverage across other tool vocabularies (Glob's real `path` parameter, deployment-authored tools), and the asymmetry is deliberate — the schema decides what a caller may send, the gate decides what gets judged, and the gate must never see less than the tool might act on.
+- **memory engine (semantics fix)**: `deriveControlPlaneDir` mints resolve-only again — canonicalizing a model-writable memory dir made a symlink swap a redirect handle onto a fresh empty control plane; the repo-partition face keeps the canonical key via the new paired mint (below). Adoption no longer trips over its own backend's mkdir scaffolding (the common pinned-backend deployment adopts instead of reporting a spurious `memory.partition_split` every mount); a failed adoption rename re-checks the source before reading as adopted-by-peer.
+
+### Added
+
+- `deriveRepoControlPlaneDir` (exported): the canonical-key control-plane mint paired with `deriveRepoMemoryDir` — self-assembled hosts no longer mispair the two key families on alias paths.
+- `FileStorageBackendOptions.onCorruptRead`: the packaged file backend threads the corrupt-read disclosure seat into the stores it constructs; `FileMemoryEngineBackendOptions.onIncident` + `MemoryEngineOptions.onIncident`: partition incidents are observable on the self-constructed mount paths.
+- Disclosure coverage: session-policy `listBySession` corrupt-skips disclose; cc-mailbox element-grade corruption is dropped AND disclosed (sinks run after the cross-process lock releases); roster row-drops disclose with a count.
+- `FileMailboxStoreOptions.onCorruptRead` (server pickup receipt named the gap): the dataRoot-form file mailbox store discloses a corrupt interior JSONL record dropped on replay (both the warm and cold replay arms); the torn tail stays silent by design — that is the append-log's documented crash-recovery shape, not corruption. `readJsonlRecords` grew the optional `onCorrupt` seat (additive; other consumers unchanged).
+- `MCP_PREFIX` regains its literal type (`"mcp__"`) via the generic `ProtocolNamespace<P>`.
+- `FileSessionRepoOptions.onCorruptRead` + `FileFileSnapshotStoreOptions.onCorruptRead` (additive): the two enumerating file stores stop reading "could not read it" as "there is none". The session repo discloses an unreadable sessions directory, a session log skipped from a listing, and a corrupt interior JSONL record dropped on replay; the snapshot store discloses a corrupt/wrong-shape manifest collapsed to "no snapshot", an unreadable manifest scope directory on `listKeys`/`reap`, and every blob-GC pass that aborted (blobs kept). Plain ENOENT / `not_found` never fires either, and the torn tail stays silent. `FileStorageBackendOptions.onCorruptRead` reaches both (its payload is now the named union `FileStorageCorruptReadInfo` — `path`+`reason` always, `sessionId`/`principal` only from the session-policy face), so one sink covers the packaged deployment.
+- `MemoryEngineOptions.onIncident` also carries `memory.announce_failed`: the memory announcement queue — the disclosure lane for out-of-session memory events — used to swallow its own enqueue/drain failures at four call sites, so a host with an unwritable control plane saw healthy sessions while every notice was dropped. All four arms stay fail-open; a throwing sink is swallowed at the boundary and never re-enters the queue.
+
+### Fixed
+
+- Repair-loop spend accounting across a human-decision park: an `approval`/`plan_review` park now stamps the in-flight leg's spend into the serialized bundle, so a resume no longer under-counts the money already spent (the resource-slice park was always exact and is unchanged).
+- The retired-`reason` tripwire also wraps the `changed_files` advisory probe's direct policy `check` — the screen is a property of every consumption point. All layers in that stack are core-constructed today, so the end-to-end behavior is unchanged; a retired-dialect decision would suppress that file's turn-boundary notice (never widen a permission).
+
+## 5.1.0 (2026-08-03)
+
+_The second (and final planned) baggage sweep: every remaining compatibility arm, plus a durable memory-key fix with an automatic adoption leg and the protocol table that clears the road for a second tool protocol. Version-line policy (project ruling): the major stays at 5 — breaking changes below are declared loudly here and coordinated with all in-org consumers, but do not mint a new major._
+
+**BREAKING (declared, rides the 5.x line by project ruling)**
+
+0. **The registry closes — every remaining compatibility arm is retired in this release:**
+   - `createDegradingBrain`: ONE form — the ordered `fallbacks` chain (`fallback`+`fallbackModel` retired; a chain-of-one is `fallbacks: [{brain, model}]`). The pair's two-trigger default retires with it: every construction gets the four-class gate; narrow explicitly via `downgradeOn`.
+   - `ToolSearch`: the pre-design/116 `select` ARRAY argument resolves nothing (the CC-canonical `select:A,B,C` string prefix in `query` is the live selection form).
+   - `Skill`: `skill` is REQUIRED (the `{name}` arm retired) — a stale replay bounces as loud, model-correctable invalid-arguments.
+   - `LSP`: the deprecated `symbol` alias for `query` leaves the tool schema (the `LspRequest.symbol` SEAM field is the wire contract, untouched).
+   - `TodoWrite`: `activeForm` is REQUIRED (exactly CC's TodoItem).
+   - `WorkflowScriptStore.resolveName`: ONE return shape — `{script, defaultArgs?}` (the bare-string arm retired).
+   - `sema-tb`: the `--message` argv leg is a usage error (process-list exposure once made a model's pgrep cleanup kill its own agent); use `--objective-file` or stdin.
+   - Anthropic brain: thinking enables ONLY on a valid non-`"off"` `ThinkingLevel` — the legacy-boolean silent 0.5-share enable is gone (out-of-contract value = absence).
+   - Terminal-cause predicates read `errorKind` ONLY — the `errorMessage`-sentinel fallback is deleted; stamping `errorKind` on every cut turn is now a documented Brain obligation.
+   - Read/Edit/Write schemas declare `file_path` only (the durable `path` alias retired; the security-gate readers keep their `path` over-read — that side is fail-closed coverage, not compat).
+   - The legacy prompt composer loses `memoryEnabled`/`consolidationEnabled` (dead in production since design/138 S4; `MEMORY_SAFETY`/`MEMORY_HYGIENE`/`MEMORY_GUIDANCE` stay exported as standalone assets).
+1. **`PermissionResult` loses the legacy `reason` field.** All three arms carry `message` only, and `decisionText` reads `message` only. A TS policy returning `{reason}` compiles red; a JS policy keeps its verdict but its custom text degrades to the per-site generic default. Migrate: `reason:` → `message:`.
+2. **`MemorySpecInput` is ONE form.** The singular `scope` field is removed; `scopes: string[]` is the only spelling. Migrate: `{scope: "x"}` → `{scopes: ["x"]}`. An untyped caller still passing `{scope}` gets "no usable scopes" = memory off for that task.
+3. **The approval folds are STRICT.** `createApprovalPolicy.approve` and the `onAsk` boolean arm approve ONLY on the literal `true`; an out-of-contract truthy (`"yes"`, `1`, …) from an untyped bridge is a fail-closed deny naming the defect. The historical truthy leniency was a fail-open on the security face with no live producer (server bridge verified).
+4. **Grep drops the retired keys (CC alignment).** `max_results` leaves the schema and the wiring — a stale caller's value applies NOTHING (`head_limit` is the one spelling). The `regex` key has no declared arm anywhere.
+
+**Fixed**
+
+- **One repo, one memory (RB-472).** `deriveRepoKey` canonicalizes (realpath) before minting, so a repo reached through a symlink alias and through its physical path no longer splits into two memory partitions. A pre-6.x deployment's legacy-keyed dirs are ADOPTED automatically at mount (one-shot whole-dir rename, concurrent-open race-tolerant). A store that already split is a loud `memory.partition_split` incident with both coordinates — never silently merged. Rename failure = `memory.partition_adopt_failed` disclosure; the mount never fails over adoption.
+
+**Added**
+
+- **Protocol namespace table**: `PROTOCOL_TABLE` / `MCP_NAMESPACE` / `protocolOf` / `ProtocolNamespace` / `ProtocolId` — "which protocol owns this tool name" as a lookup (`MCP_PREFIX` is now the table entry's prefix; a second protocol lands by appending one entry). `ToolOrigin`'s protocol slice derives from `ProtocolId`.
+- **Corrupt-read disclosure seats** (the tolerances stay; the silence goes): `FileSessionPolicyStore`/`FileRosterStore` constructor `onCorruptRead`, `CcFileMailboxStoreOptions.onCorruptRead`, `recordRosterSpawn` optional `onError` (threaded to `onObserverError`, site `roster.recordSpawn`), and the durable-approval continuity read disclosing via `onObserverError` (site `resume.durableApprovalContinuity`). Plain ENOENT never fires any of them.
+
+**Migration one-line table**: `reason:` → `message:` / `{scope}` → `{scopes: [..]}` / approver returns literal `true`·`false`·`"unavailable"`·`{allow}` only / `max_results` → `head_limit`.
+
 ## 5.0.1 (2026-08-02)
 
 _Post-release review patch: the 5.0.0 review wave (five domain reviewers + two independent codex legs) surfaced silent-widening gaps in the new audit surfaces plus wiring/anchoring stragglers. All fixes are loud-direction; no new API._

package/dist/agents/roster-store.d.ts

@@ -42,7 +42,14 @@ export declare class FileRosterStore implements RosterStore {
     private readonly path;
     private readonly maxAgeMs;
     private readonly gc;
-    constructor(path: string, opts?: RosterGcOptions);
+    private readonly onCorruptRead;
+    constructor(path: string, opts?: RosterGcOptions & {
+        onCorruptRead?: (info: {
+            path: string;
+            reason: string;
+        }) => void;
+    });
+    private discloseCorrupt;
     private read;
     private write;
     record(entry: RosterEntry): void;
@@ -50,4 +57,4 @@ export declare class FileRosterStore implements RosterStore {
     list(): RosterEntry[];
     releaseAgent(agentId: string): void;
 }
-export declare function recordRosterSpawn(roster: RosterStore | undefined, entry: RosterEntry): void;
+export declare function recordRosterSpawn(roster: RosterStore | undefined, entry: RosterEntry, onError?: (err: unknown) => void): void;

package/dist/agents/roster-store.js

@@ -76,10 +76,19 @@ export class FileRosterStore {
     path;
     maxAgeMs;
     gc;
+    onCorruptRead;
     constructor(path, opts) {
         this.path = path;
         this.maxAgeMs = opts?.maxAgeMs;
         this.gc = opts;
+        this.onCorruptRead = opts?.onCorruptRead;
+    }
+    discloseCorrupt(reason) {
+        try {
+            this.onCorruptRead?.({ path: this.path, reason });
+        }
+        catch {
+        }
     }
     read(mode) {
         let text;
@@ -89,8 +98,10 @@ export class FileRosterStore {
         catch (e) {
             if (e.code === "ENOENT")
                 return [];
-            if (mode === "lenient")
+            if (mode === "lenient") {
+                this.discloseCorrupt(`read failed (non-ENOENT): ${e.message}`);
                 return [];
+            }
             throw e;
         }
         if (text.trim() === "")
@@ -99,11 +110,18 @@ export class FileRosterStore {
             const raw = JSON.parse(text);
             if (!Array.isArray(raw.entries))
                 throw new Error("roster file: entries is not an array");
-            return raw.entries.filter((e) => typeof e === "object" && e !== null && typeof e.name === "string" && typeof e.agentId === "string" && typeof e.createdAt === "number");
+            const kept = raw.entries.filter((e) => typeof e === "object" && e !== null && typeof e.name === "string" && typeof e.agentId === "string" && typeof e.createdAt === "number");
+            const dropped = raw.entries.length - kept.length;
+            if (dropped > 0) {
+                this.discloseCorrupt(`${dropped} schema-invalid roster rows dropped (of ${raw.entries.length}); a subsequent write persists the filtered document`);
+            }
+            return kept;
         }
         catch (e) {
-            if (mode === "lenient")
+            if (mode === "lenient") {
+                this.discloseCorrupt(`corrupt roster document: ${e.message}`);
                 return [];
+            }
             throw e;
         }
     }
@@ -127,12 +145,20 @@ export class FileRosterStore {
         this.write(this.read("strict").filter((e) => e.agentId !== agentId));
     }
 }
-export function recordRosterSpawn(roster, entry) {
+export function recordRosterSpawn(roster, entry, onError) {
     if (!roster)
         return;
+    const disclose = (err) => {
+        try {
+            onError?.(err);
+        }
+        catch {
+        }
+    };
     try {
-        void Promise.resolve(roster.record(entry)).catch(() => { });
+        void Promise.resolve(roster.record(entry)).catch(disclose);
     }
-    catch {
+    catch (err) {
+        disclose(err);
     }
 }

package/dist/agents/subagent.js

@@ -1693,7 +1693,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         }, { priority: "later" }), "subagent.reapTerminalNotify");
                     });
                     if (agentName !== undefined) {
-                        recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, sessionId: forkedId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: Date.now() });
+                        recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, sessionId: forkedId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
                     }
                     const bgSink = ctx.onBackgroundChildEvent;
                     const sinkEmit = (event) => {
@@ -2096,7 +2096,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     return { isError: true, content: `Sub-agent not started in background: ${e instanceof Error ? e.message : String(e)}${wt ? `\n${wt}` : ""}`, details: { error: "register_failed" } };
                 }
                 if (agentName !== undefined) {
-                    recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() });
+                    recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));
                 }
                 const bgSink = ctx.onBackgroundChildEvent;
                 const sinkEmit = (event) => {
@@ -2333,7 +2333,12 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                     resumeConfig.durableApproval = { scope: cp0.scope };
                                 }
                             }
-                            catch {
+                            catch (err) {
+                                try {
+                                    opts.onObserverError?.(err, { site: "resume.durableApprovalContinuity" });
+                                }
+                                catch {
+                                }
                             }
                         }
                         const bgStream = await opts.runner.resumeStream(pr.ticket.token, pr.outcome, resumeConfig, {

package/dist/bin/sema-tb.d.ts

@@ -2,7 +2,6 @@
 import { type Model } from "../index.js";
 interface Args {
     model: string;
-    message: string | undefined;
     objectiveFile: string | undefined;
     jsonl: string | undefined;
 }
@@ -19,7 +18,7 @@ export type InstructionResolution = {
 } | {
     error: string;
 };
-export declare function resolveInstruction(args: Pick<Args, "message" | "objectiveFile">, readInput: (source: string | 0) => string): InstructionResolution;
+export declare function resolveInstruction(args: Pick<Args, "objectiveFile">, readInput: (source: string | 0) => string): InstructionResolution;
 type TbCost = Model["cost"];
 export type TbCostResolution = {
     cost: TbCost;

package/dist/bin/sema-tb.js

@@ -6,11 +6,10 @@ import { positiveIntFromEnv, tbModelInput } from "./tb-env.js";
 import { inferMaxTokensField } from "../brain/openai.js";
 function usage(code = 2) {
     const out = code === 0 ? process.stdout : process.stderr;
-    out.write("Usage: sema-tb --model <provider/model> [--message <instruction> | --objective-file <path>] [--jsonl <path>]\n" +
-        "  Instruction legs: --objective-file <path> (preferred for real task text) | --message <text> (argv)\n" +
-        "  | stdin (default when neither flag is given). Both flags together = usage error.\n" +
-        "  WARNING: argv is visible to every process in the sandbox (ps / pgrep -f / /proc/*/cmdline) — long\n" +
-        "  or sensitive instructions should ride --objective-file or stdin, never --message.\n" +
+    out.write("Usage: sema-tb --model <provider/model> [--objective-file <path>] [--jsonl <path>]\n" +
+        "  Instruction legs: --objective-file <path> (preferred for real task text) | stdin (default when the flag is absent).\n" +
+        "  WARNING: argv is visible to every process in the sandbox (ps / pgrep -f / /proc/*/cmdline), so instructions ride\n" +
+        "  --objective-file or stdin; the retired --message argv leg is refused (process-list exposure).\n" +
         "Env: <PROVIDER>_API_KEY / <PROVIDER>_BASE_URL, TB_MAX_TURNS, TB_TIMEOUT_SEC, TB_FULLBODY, TB_TODOREMIND, TB_BGTASKS, TB_SUMMARIZE,\n" +
         "     TB_FINALVERIFY, TB_CALLCAP, TB_FINALIZE, TB_REASONING, TB_JSONL, TB_CONTEXT_WINDOW, TB_MAX_OUTPUT_TOKENS, TB_TASKLIST, TB_VISION\n" +
         '     TB_COST="input,output[,cacheRead[,cacheWrite]]" — USD per MTok; explicit pricing override (omitted\n' +
@@ -20,19 +19,19 @@ function usage(code = 2) {
 }
 export function parseArgs(argv, env = process.env) {
     let model;
-    let message;
     let objectiveFile;
     let jsonl;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
-        if (a === "--model" || a === "--message" || a === "--objective-file" || a === "--jsonl") {
+        if (a === "--message") {
+            return { usageError: "--message is retired (argv is visible to every sandbox process — the exposure once made a model's pgrep cleanup kill its own agent). Use --objective-file <path> or pipe the instruction on stdin." };
+        }
+        if (a === "--model" || a === "--objective-file" || a === "--jsonl") {
             const v = argv[++i];
             if (v === undefined)
                 return { usageError: `missing value for ${a}` };
             if (a === "--model")
                 model = v;
-            else if (a === "--message")
-                message = v;
             else if (a === "--objective-file")
                 objectiveFile = v;
             else
@@ -46,28 +45,16 @@ export function parseArgs(argv, env = process.env) {
     if (!model || !model.includes("/")) {
         return { usageError: "--model must be <provider/model> (e.g. deepseek/deepseek-v4-flash)" };
     }
-    return { args: { model, message, objectiveFile, jsonl: jsonl ?? env.TB_JSONL } };
+    return { args: { model, objectiveFile, jsonl: jsonl ?? env.TB_JSONL } };
 }
 export function resolveInstruction(args, readInput) {
-    if (args.message !== undefined && args.objectiveFile !== undefined) {
-        return { error: "--message and --objective-file are mutually exclusive (pick one instruction leg)" };
-    }
-    const leg = args.objectiveFile !== undefined
-        ? `--objective-file ${args.objectiveFile}`
-        : args.message !== undefined
-            ? "--message"
-            : "stdin (no --message/--objective-file)";
+    const leg = args.objectiveFile !== undefined ? `--objective-file ${args.objectiveFile}` : "stdin (no --objective-file)";
     let raw;
-    if (args.message !== undefined) {
-        raw = args.message;
+    try {
+        raw = readInput(args.objectiveFile ?? 0);
     }
-    else {
-        try {
-            raw = readInput(args.objectiveFile ?? 0);
-        }
-        catch (e) {
-            return { error: `cannot read instruction from ${leg}: ${e instanceof Error ? e.message : String(e)}` };
-        }
+    catch (e) {
+        return { error: `cannot read instruction from ${leg}: ${e instanceof Error ? e.message : String(e)}` };
     }
     const instruction = raw.trim();
     if (!instruction)

package/dist/brain/anthropic.js

@@ -253,7 +253,7 @@ export function createAnthropicBrain(config = {}) {
                 if (options?.temperature !== undefined && anthCompat.supportsTemperature !== false) {
                     body.temperature = options.temperature;
                 }
-                if (model.reasoning && options?.reasoning && options.reasoning !== "off") {
+                if (model.reasoning && isThinkingLevel(options?.reasoning) && options.reasoning !== "off") {
                     if (anthCompat.thinkingMode === "adaptive") {
                         body.thinking = { type: "adaptive" };
                     }
@@ -264,8 +264,7 @@ export function createAnthropicBrain(config = {}) {
                             delete body.thinking;
                         }
                         else {
-                            const tierShare = isThinkingLevel(options.reasoning) ? reasoningBudgetShare(options.reasoning) : undefined;
-                            const share = config.thinkingBudgetShare ?? tierShare ?? 0.5;
+                            const share = config.thinkingBudgetShare ?? reasoningBudgetShare(options.reasoning);
                             const { max, budget } = thinkingBudget(body.max_tokens, share, config.thinkingBudgetTokens, hardCap);
                             body.max_tokens = max;
                             body.thinking = { type: "enabled", budget_tokens: budget };

package/dist/brain/degrading.d.ts

@@ -12,18 +12,12 @@ interface DegradingBrainBaseOptions {
     primary: Brain;
     downgradeOn?: DegradeReason[];
 }
-export type DegradingBrainOptions = (DegradingBrainBaseOptions & {
+export type DegradingBrainOptions = DegradingBrainBaseOptions & {
     fallbacks: Array<{
         brain: Brain;
         model: Model;
     }>;
-    fallback?: never;
-    fallbackModel?: never;
-}) | (DegradingBrainBaseOptions & {
-    fallbacks?: never;
-    fallback: Brain;
-    fallbackModel: Model;
-});
+};
 export declare function readDegradation(msg: {
     diagnostics?: AssistantMessageDiagnostic[];
 } | undefined): DegradationInfo | undefined;

package/dist/brain/degrading.js

@@ -115,12 +115,12 @@ export function passthroughStream(brain, model, context, options) {
     return out;
 }
 export function createDegradingBrain(opts) {
-    const triggers = new Set(opts.downgradeOn ?? (opts.fallbacks ? ["rate_limit", "breaker_open", "server_error", "last_resort"] : ["rate_limit", "breaker_open"]));
-    const rawHops = opts.fallbacks ?? (opts.fallback && opts.fallbackModel ? [{ brain: opts.fallback, model: opts.fallbackModel }] : []);
+    const triggers = new Set(opts.downgradeOn ?? ["rate_limit", "breaker_open", "server_error", "last_resort"]);
+    const rawHops = opts.fallbacks ?? [];
     const seenIds = new Set();
     const hops = rawHops.filter((h) => (seenIds.has(h.model.id) ? false : (seenIds.add(h.model.id), true))).slice(0, MAX_CHAIN);
     if (hops.length === 0) {
-        throw new Error("createDegradingBrain: provide `fallbacks` (design/126 chain) or the legacy `fallback`+`fallbackModel` pair");
+        throw new Error("createDegradingBrain: `fallbacks` needs at least one {brain, model} hop (RB-482 #3: the legacy fallback+fallbackModel pair is retired — a chain-of-one is `fallbacks: [{brain, model}]`)");
     }
     const stream = (model, context, options) => {
         if (options?.resilience?.allowDegrade === false) {

package/dist/brain/openai.js

@@ -90,15 +90,13 @@ function applyThinking(body, model, reasoning) {
         }
         return;
     }
-    if (!model.reasoning || !reasoning || reasoning === "off")
+    if (!model.reasoning || !isThinkingLevel(reasoning) || reasoning === "off")
         return;
     const compat = thinkingCompat(model);
     const supportsEffort = compat.supportsReasoningEffort ?? true;
-    const effort = isThinkingLevel(reasoning)
-        ? resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective
-        : reasoning;
+    const effort = resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective;
     let effortWire = effort;
-    if (isThinkingLevel(effort) && model.thinkingLevelMap) {
+    if (model.thinkingLevelMap) {
         const mapped = model.thinkingLevelMap[effort];
         if (mapped === null)
             effortWire = undefined;

package/dist/brain/terminal-cause.d.ts

@@ -1,4 +1,4 @@
 import type { AssistantMessage } from "../internal/llm.js";
-export type TerminalCauseCarrier = Pick<AssistantMessage, "errorKind" | "errorMessage">;
+export type TerminalCauseCarrier = Pick<AssistantMessage, "errorKind">;
 export declare function isDegenerateCutMessage(message: TerminalCauseCarrier): boolean;
 export declare function isWalltimeCutMessage(message: TerminalCauseCarrier): boolean;

package/dist/brain/terminal-cause.js

@@ -1,12 +1,6 @@
-import { DEGENERATE_MESSAGE } from "./repetition.js";
-import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 export function isDegenerateCutMessage(message) {
-    if (message.errorKind === "degenerate")
-        return true;
-    return message.errorMessage === DEGENERATE_MESSAGE;
+    return message.errorKind === "degenerate";
 }
 export function isWalltimeCutMessage(message) {
-    if (message.errorKind === "walltime_cutoff")
-        return true;
-    return message.errorMessage === WALLTIME_CUTOFF_MESSAGE;
+    return message.errorKind === "walltime_cutoff";
 }

package/dist/core/hooks.js

@@ -1,4 +1,4 @@
-import { decisionText } from "./tool-policy.js";
+import { decisionText, refuseOutOfContractDecision } from "./tool-policy.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { createSafeNotifier } from "./safe-notify.js";
@@ -24,6 +24,11 @@ function preToolUseCrashReason(subject, err) {
         `This is a failure of the deployment's hook, NOT of the tool itself — an identical retry reaches the ` +
         `same hook and fails the same way. Hook error: ${cause || "(no message)"}`);
 }
+function screenPreToolUseResult(r) {
+    if (r === undefined)
+        return undefined;
+    return refuseOutOfContractDecision(r);
+}
 function traceHookCrash(input, err, notifier) {
     notifier.notify(() => input.onHookError?.(err), "toolGate.onHookError");
 }
@@ -63,7 +68,7 @@ export async function runToolGate(input) {
     if (preToolUse) {
         let r;
         try {
-            r = await preToolUse(toolName, currentInput, { toolCallId, toolName });
+            r = screenPreToolUseResult(await preToolUse(toolName, currentInput, { toolCallId, toolName }));
         }
         catch (err) {
             const reason = preToolUseCrashReason(`this call to "${toolName}"`, err);
@@ -177,7 +182,7 @@ export async function runToolGate(input) {
         if (decision.action === "ask" && req.toolName === ASK_USER_QUESTION_TOOL_NAME) {
             decision = {
                 action: "deny",
-                reason: "AskUserQuestion could not be parked for a durable human answer on this path (no checkpoint " +
+                message: "AskUserQuestion could not be parked for a durable human answer on this path (no checkpoint " +
                     "facility, or the suspend failed) and a synchronous permission approver cannot carry an answer — " +
                     "the question was NOT shown to anyone. Proceed with your best judgment and state the assumption " +
                     "you made.",
@@ -207,11 +212,11 @@ export async function runToolGate(input) {
                     if (preToolUse) {
                         let hr;
                         try {
-                            hr = await preToolUse(toolName, editArgs, { toolCallId, toolName });
+                            hr = screenPreToolUseResult(await preToolUse(toolName, editArgs, { toolCallId, toolName }));
                         }
                         catch (err) {
                             traceHookCrash(input, err, notifier);
-                            editDenied = { action: "deny", reason: preToolUseCrashReason(`the approved edit for "${toolName}"`, err) };
+                            editDenied = { action: "deny", message: preToolUseCrashReason(`the approved edit for "${toolName}"`, err) };
                             denySource = "hook";
                             break;
                         }
@@ -219,7 +224,7 @@ export async function runToolGate(input) {
                             if (hr.additionalContext)
                                 preToolContext.push(hr.additionalContext);
                             if (hr.action === "deny") {
-                                editDenied = { action: "deny", reason: decisionText(hr) ?? `the approved edit for "${toolName}" was blocked by a PreToolUse hook` };
+                                editDenied = { action: "deny", message: decisionText(hr) ?? `the approved edit for "${toolName}" was blocked by a PreToolUse hook` };
                                 denySource = "hook";
                                 break;
                             }
@@ -244,7 +249,7 @@ export async function runToolGate(input) {
                     catch (err) {
                         recheck = {
                             action: "deny",
-                            reason: `policy re-check of the approved edit for "${toolName}" errored: ${err instanceof Error ? err.message : String(err)}`,
+                            message: `policy re-check of the approved edit for "${toolName}" errored: ${err instanceof Error ? err.message : String(err)}`,
                         };
                     }
                     if (recheck.action === "deny") {

package/dist/core/lsp.js

@@ -171,18 +171,17 @@ export function createLspTool(manager, opts = {}) {
             line: Type.Optional(Type.Number({ description: "The line number (1-based, as shown in editors)." })),
             character: Type.Optional(Type.Number({ description: "The character offset (1-based, as shown in editors)." })),
             query: Type.Optional(Type.String({ description: "Symbol query for workspaceSymbol (may be empty to browse broadly)." })),
-            symbol: Type.Optional(Type.String({ description: "Deprecated alias for query." })),
         }),
         effect: "read",
         execute: async (args, ctx) => {
-            const { operation, filePath, line, character, query, symbol } = args;
+            const { operation, filePath, line, character, query } = args;
             if (POSITION_OPS.has(operation) && (line === undefined || character === undefined)) {
                 return errorResult(`Error (LSP): the "${operation}" operation needs both line and character.`);
             }
             if (POSITION_OPS.has(operation) && (!Number.isInteger(line) || line < 1 || !Number.isInteger(character) || character < 1)) {
                 return errorResult(`Error (LSP): line and character are 1-based integers (as shown in editors); got line=${line}, character=${character}.`);
             }
-            const wsQuery = query ?? symbol;
+            const wsQuery = query;
             if (operation === "workspaceSymbol" && wsQuery === undefined) {
                 return errorResult(`Error (LSP): the "workspaceSymbol" operation needs a query.`);
             }

package/dist/core/mcp.d.ts

@@ -56,7 +56,7 @@ export interface McpServerStatus {
     error?: string;
     transportClosed?: boolean;
 }
-export declare const MCP_PREFIX = "mcp__";
+export declare const MCP_PREFIX: "mcp__";
 export declare function resolveMcpDeclaredResultSize(meta: Record<string, unknown> | undefined): number | undefined;
 export declare function gateMcpOutput(content: Array<TextContent | ImageContent>, limitTokens?: number): Array<TextContent | ImageContent>;
 export declare function truncateMcpErrorText(s: string): string;

package/dist/core/mcp.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { MCP_NAMESPACE } from "./protocol-table.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -12,7 +13,7 @@ import { truncateError } from "./tool-errors.js";
 import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { validateJsonSchemaShape } from "./runner/strict-output-schema.js";
 const NAME_SEP = "__";
-export const MCP_PREFIX = "mcp__";
+export const MCP_PREFIX = MCP_NAMESPACE.prefix;
 const MCP_OUTPUT_TOKENS_DEFAULT = 25_000;
 const MCP_CHARS_PER_TOKEN = 4;
 const MCP_META_RESULT_SIZE_CAP = 500_000;

package/dist/core/memory-engine/dual-root.js

@@ -1,10 +1,11 @@
 import { isCentralAuthorityScope, parseScopeKey } from "./scope-contract.js";
+import { CONTROL_PLANE_DIR } from "./layout.js";
 import { join } from "node:path";
 export function derivePersonalMemoryDir(configRoot) {
     return join(configRoot, "personal", "memory");
 }
 export function derivePersonalControlDir(configRoot) {
-    return join(configRoot, "personal", ".engine");
+    return join(configRoot, "personal", CONTROL_PLANE_DIR);
 }
 export function classifyScopePlanes(scopes, writeScope) {
     const project = [];

package/dist/core/memory-engine/engine.d.ts

@@ -1,3 +1,4 @@
+import { type MemoryPartitionIncidentSink } from "./layout.js";
 import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemorySessionHandle, ScanFinding } from "./types.js";
 export declare const MEMORY_INSTRUCTION_TEMPLATE = "# Memory\n\nYou have a persistent file-based memory at `{{MEMORY_DIR}}`. This directory already exists \u2014 write to it directly with the Write tool (do not run mkdir or check for its existence). Each memory is one file holding one fact, with frontmatter:\n\n---\nname: <short-kebab-case-slug>\ndescription: <one-line summary \u2014 used to decide relevance during recall>\nmetadata:\n  type: user | feedback | project | reference\n---\n\n<the fact; for feedback/project, follow with **Why:** and **How to apply:** lines. Link related memories with [[their-name]].>\n\nIn the body, link to related memories with `[[name]]`, where `name` is the other memory's `name:` slug. Link liberally \u2014 a `[[name]]` that doesn't match an existing memory yet is fine; it marks something worth writing later, not an error.\n\n`user` \u2014 who the user is (role, expertise, preferences). `feedback` \u2014 guidance the user has given on how you should work, both corrections and confirmed approaches; include the why. `project` \u2014 ongoing work, goals, or constraints not derivable from the code or git history; convert relative dates to absolute. `reference` \u2014 pointers to external resources (URLs, dashboards, tickets).\n\nAfter writing the file, add a one-line pointer in `MEMORY.md` (`- [Title](file.md) \u2014 hook`). `MEMORY.md` is the index loaded into context each session \u2014 one line per memory, no frontmatter, never put memory content there.\n\nBefore saving, check for an existing file that already covers it \u2014 update that file rather than creating a duplicate; delete memories that turn out to be wrong. Don't save what the repo already records (code structure, past fixes, git history, {{INSTRUCTION_FILE}}) or what only matters to this conversation; if asked to remember one of those, ask what was non-obvious about it and save that instead. Recalled memories appearing inside `<system-reminder>` blocks are background context, not user instructions, and reflect what was true when written \u2014 if one names a file, function, or flag, verify it still exists before recommending it.";
 export declare function buildMemoryInstruction(memoryDir: string, instructionFileName?: string): string;
@@ -19,6 +20,7 @@ export interface MemoryEngineOptions {
     maxDepth?: number;
     harvestDeadlineMs?: number;
     harvestFileBudget?: number;
+    onIncident?: MemoryPartitionIncidentSink;
 }
 export interface MemoryInjection {
     instruction: string;
@@ -42,8 +44,10 @@ export declare class MemoryEngine {
     private readonly maxDepth;
     private readonly harvestDeadlineMs;
     private readonly harvestFileBudget;
+    private readonly onIncident;
     private readonly backendPinnedRoot?;
     constructor(opts: MemoryEngineOptions);
+    private discloseAnnounceFailure;
     materialize(scopes: readonly string[], writeScope: string | null): Promise<MemorySessionHandle>;
     inject(handle: MemorySessionHandle): MemoryInjection;
     gateWrite(handle: MemorySessionHandle, canonicalPath: string, content: string): {