@sema-agent/core 5.56.0 → 5.57.0

package/dist/core/runner/prepare-task.js

@@ -35,6 +35,7 @@ import { createWriteProtectionCheck } from "../write-protect.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
 import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
+import { adjudicateDerivedRoute, fallbackToPrimaryNotice, sameRouteIdentity } from "../../brain/route-adjudicator.js";
 import { STALL_CONNECT_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, withBrainCallGuardrail } from "../../brain/timeout.js";
 import { defineTool, isDefineToolProduct } from "../tools.js";
 import { RETIRED_TOOL_NAMES } from "../tool-name-aliases.js";
@@ -472,6 +473,20 @@ async function adoptReminderMark(session, sessionId, seedMark, spawnMark, onErro
     }
     return { reminderMark, reminderDisclosureCounts: {} };
 }
+async function derivedRouteFallsBack(args) {
+    try {
+        if (sameRouteIdentity(args.derived, args.primary))
+            return false;
+        const verdict = await adjudicateDerivedRoute({ brain: args.brain, model: args.derived, getApiKeyAndHeaders: args.getApiKeyAndHeaders });
+        if (verdict === undefined || verdict.ok)
+            return false;
+        deliverEngineNotice(args.onNotice, fallbackToPrimaryNotice({ seat: args.seat, from: args.derived.id, to: args.primary.id, verdict }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function prepareTask(spec, deps, sessions, resume, internals, runnerSelf) {
     const doors = prepareConfigDoors({ spec, deps, sessions, resume, internals });
     spec = doors.spec;
@@ -489,7 +504,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const sessionId = acquired.sessionId;
     const hostTaskId = spec.taskId ?? sessionId;
     const delegation = effectiveDelegationFacts(internals, resume?.seed.isDelegatedChild);
-    warnCompactionWindowHazard(deps.tracer, spec, model, compModel, hostTaskId);
+    let effectiveCompModel = compModel;
+    if (spec.compactionModel === undefined &&
+        compModel !== undefined &&
+        (await derivedRouteFallsBack({ seat: "compaction-summary", derived: compModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice }))) {
+        effectiveCompModel = undefined;
+    }
+    warnCompactionWindowHazard(deps.tracer, spec, model, effectiveCompModel, hostTaskId);
     const taskScope = internals?.registryScope ?? spec.principal ?? "default";
     internals?.peerSelfRef?.addAxis("s", sessionId);
     internals?.peerSelfRef?.addAxis("t", hostTaskId);
@@ -1073,6 +1094,9 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             catch {
                 classifierModel = model;
             }
+            if (await derivedRouteFallsBack({ seat: "auto-mode-classifier", derived: classifierModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice })) {
+                classifierModel = model;
+            }
             const classifierSystemPrompt = buildAutoModePrompt(am);
             const classifierRuntime = brainToRuntime(deps.brain);
             autoModeDecider = createAutoModeDecider({
@@ -1083,7 +1107,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     const ctx = await session.buildContext();
                     const known = ctx.messages.filter((m) => m.role === "user" || m.role === "assistant" || m.role === "toolResult");
                     const userPrompt = renderAutoModeWindow(known, am.window) + renderAutoModeAction(input);
-                    const response = await classifierRuntime.completeSimple(classifierModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, { signal });
+                    const classifierAuth = await spec.getApiKeyAndHeaders?.(classifierModel);
+                    const response = await classifierRuntime.completeSimple(classifierModel, { systemPrompt: classifierSystemPrompt, messages: [{ role: "user", content: userPrompt, timestamp: Date.now() }] }, {
+                        signal,
+                        ...(classifierAuth?.apiKey !== undefined ? { apiKey: classifierAuth.apiKey } : {}),
+                        ...(classifierAuth?.headers !== undefined ? { headers: classifierAuth.headers } : {}),
+                    });
                     return response.content
                         .filter((c) => c.type === "text")
                         .map((c) => c.text)
@@ -1412,7 +1441,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     owner: hostTaskId,
                     scope: taskScope,
                     ...(sessionId !== undefined ? { sessionId } : {}),
-                    ...(internals?.onTaskNotification !== undefined ? { notify: internals.onTaskNotification } : {}),
+                    ...(internals?.onTaskNotification !== undefined ? { notify: internals.onTaskNotification } : {}), ...(spec.oneShot !== undefined ? { oneShot: spec.oneShot } : {}),
                     ...(internals?.onSubagentSpawn !== undefined ? { sink: internals.onSubagentSpawn } : {}),
                     ...(internals?.parentNotify !== undefined
                         ? { uplink: internals.parentNotify, ...(internals.parentPeerRef !== undefined ? { uplinkRecipient: internals.parentPeerRef } : {}) }
@@ -4733,7 +4762,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const effectiveReadFaceObserved = carrierReadFace();
         const effectiveReadDenyObserved = readDenyAdditionsNormalized.length > 0 ? readDenyAdditionsNormalized.map((e) => ({ ...e })) : undefined;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, reminderMark, reminderDisclosureCounts, taskRootPath: taskRootFinal, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettlement, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, reminderMark, reminderDisclosureCounts, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, approvalSettlement, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

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

@@ -219,7 +219,10 @@ export declare class Runner {
      * - `tiers` omitted ⇒ the current tier bindings are kept (and re-applied over the new models);
      *   explicitly passed (including `undefined`) ⇒ replaced.
      * - Success is announced via `config.models_swapped` (models/tiers counts — key material only,
-     *   never the catalog itself).
+     *   never the catalog itself). A swap may additionally emit the advisory
+     *   `route.base_url_changed_key_unchanged` notice (deliberately conservative — see its entry in
+     *   the notice directory) for same-name entries whose URL moved while the Model-visible
+     *   credential fingerprint did not.
      */
     swapModels(next: {
         models: Record<string, Model>;

package/dist/core/runner/runtask.js

@@ -20,6 +20,7 @@ import { emitTaskOutcome } from "../task-outcome.js";
 import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
 import { primaryActivityArg } from "../arg-summary.js";
 import { resolveReasoning } from "../../brain/reasoning.js";
+import { adjudicateDerivedRoute, authCarrierFingerprint, fallbackToPrimaryNotice, normalizeBaseUrl, sameRouteIdentity } from "../../brain/route-adjudicator.js";
 import { readDegradation } from "../../brain/degrading.js";
 import { runWithBrainTelemetry, runWithReasoningWireFacts, runWithStatusSink } from "../../brain/status-sink.js";
 import { expandTiers, resolveModel, resolveTaskModel } from "../roles.js";
@@ -1511,6 +1512,22 @@ export class Runner {
                 ...(h.timeoutMs !== undefined ? { timeoutMs: h.timeoutMs } : {}),
             }
             : undefined;
+        const MIRRORED_HOOK_KEYS = [
+            "preToolUse",
+            "preToolUseObservational",
+            "postToolUse",
+            "userPromptSubmit",
+            "stop",
+            "postToolUseFailure",
+            "postToolBatch",
+            "preCompact",
+            "postCompact",
+            "stopFailure",
+            "permissionDenied",
+            "timeoutMs",
+        ];
+        const _mirrorIsComplete = true;
+        void _mirrorIsComplete;
         return {
             ...(deps.toolPolicy !== undefined
                 ? {
@@ -1552,6 +1569,17 @@ export class Runner {
         }
         const tiers = Object.hasOwn(next, "tiers") ? next.tiers : this.deps.tiers;
         const expanded = tiers && Object.keys(tiers).length > 0 ? expandTiers({ ...next.models }, tiers) : { ...next.models };
+        const movedEntries = [];
+        for (const [name, nextModel] of Object.entries(expanded ?? {})) {
+            const prior = this.deps.models?.[name];
+            if (!prior)
+                continue;
+            const from = normalizeBaseUrl(prior.baseUrl);
+            const to = normalizeBaseUrl(nextModel.baseUrl);
+            if (from !== to && authCarrierFingerprint(prior.headers) === authCarrierFingerprint(nextModel.headers)) {
+                movedEntries.push({ modelId: name, from, to });
+            }
+        }
         this.deps = { ...this.deps, models: expanded, ...(tiers !== undefined ? { tiers } : {}) };
         if (tiers === undefined)
             delete this.deps.tiers;
@@ -1560,6 +1588,18 @@ export class Runner {
             message: `model catalog swapped: ${Object.keys(next.models).length} model(s), ${tiers ? Object.keys(tiers).length : 0} tier binding(s); in-flight tasks finish on their resolved models, new tasks resolve against the new catalog`,
             detail: { models: Object.keys(next.models).length, tiers: tiers ? Object.keys(tiers).length : 0 },
         });
+        if (movedEntries.length > 0) {
+            const RENDER_CAP = 8;
+            const rendered = movedEntries.slice(0, RENDER_CAP);
+            deliverEngineNotice(this.deps.onNotice, {
+                code: "route.base_url_changed_key_unchanged",
+                message: `model catalog swap moved ${movedEntries.length} entry/entries to a new baseUrl while the Model-visible credential half stayed unchanged: ` +
+                    rendered.map((e) => `"${e.modelId}" ${e.from || "(config root)"} → ${e.to || "(config root)"}`).join("; ") +
+                    (movedEntries.length > rendered.length ? `; +${movedEntries.length - rendered.length} more` : "") +
+                    " — if the provider changed (not just its domain), update the credential reference in the same step",
+                detail: { entries: rendered, total: movedEntries.length },
+            });
+        }
     }
     sideQuery(spec) {
         return runWithReasoningWireFacts(() => { }, () => runSideQuery(spec, { brain: this.deps.brain, models: this.deps.models, roles: this.deps.roles }));
@@ -3890,6 +3930,14 @@ export class Runner {
             }
             catch {
             }
+            if (!sameRouteIdentity(model, prepared.model)) {
+                const verdict = await adjudicateDerivedRoute({ brain: this.deps.brain, model, getApiKeyAndHeaders: spec.getApiKeyAndHeaders });
+                if (verdict !== undefined && !verdict.ok) {
+                    deliverEngineNotice(this.deps.onNotice, fallbackToPrimaryNotice({ seat: "prompt-suggestions", from: model.id, to: prepared.model.id, verdict }));
+                    model = prepared.model;
+                    thinking = prepared.thinking;
+                }
+            }
             const pricing = this.deps.pricing?.[model.id] ?? modelCostToPricing(model.cost);
             const ctx = await prepared.session.buildContext();
             const transcript = ctx.messages.slice(-SUGGESTIONS_TRANSCRIPT_MESSAGES);

package/dist/core/scheduler.d.ts

@@ -147,6 +147,11 @@ export interface SchedulerCapability {
          * 不得热翻）——工具壳的门控读与 `schedule()` 是两次操作，中途翻位会让 session intent 落到不会 reap 的
          * backend 上。防线双置：声明面不可变 + `schedule()` 实现 MUST 自行拒绝它无法履行 reap 契约的
          * `lifetime:"session"` intent（fail-closed 兜底，不依赖工具壳的先行探测）。
+         *
+         * 「诚实拒绝」条款的适用边界：它约束**携带 session 语义字段的调用**（CronCreate 的 `durable` 形）。
+         * 一个没有 durable 逃生口的工具（ScheduleWakeup 形）对不支持位的 backend 走的是另一臂——发送
+         * 历史 durable intent 并在回执与工具描述上**披露**该 wakeup 不随会话终结（披露≠静默；拒绝会在
+         * 零收益下拿掉该宿主的整只工具）。该臂为既裁形（capability 位 opt-out 裁定），非本条款的违例。
          */
         readonly supportsSessionLifetime?: boolean;
         /**

package/dist/core/side-query.d.ts

@@ -57,11 +57,18 @@ export interface SideQuerySpec {
     /**
      * Per-model auth — MIRRORS {@link TaskSpec.getApiKeyAndHeaders} (same signature, resolved per
      * call against the RESOLVED model, exactly like the task path's per-call hook). The brain
-     * contract is `options.apiKey ?? config.apiKey`, and a model's own `baseUrl` outranks the
-     * brain's — so before this seat existed, a side query routed to a model carrying its own
-     * `baseUrl` + per-model key fell back to the brain's construction-time credential and sent the
-     * GATEWAY key to the per-model (possibly external) URL: a credential leak the task path already
-     * prevents. Absent ⇒ construction-time credentials apply, options byte-identical to before.
+     * contract is the route pairing law (route-adjudicator.ts): a per-model credential (this hook,
+     * or an auth header on `Model.headers`) always rides; the deployment credential rides only where
+     * its pairing is verifiable-or-unpinned — a declared `config.baseUrl` with an off-root model is
+     * refused (`route.credential_mismatch` / `route.credential_missing`), never silently followed.
+     * Historically the fallback was unconditional (`options.apiKey ?? config.apiKey`, with a model's
+     * own `baseUrl` outranking the brain's), so a side query routed to a model carrying its own
+     * `baseUrl` + per-model key sent the GATEWAY key to the per-model (possibly external) URL — the
+     * credential leak the pairing law now stops. Absent seat ⇒ no options are minted (byte-identical
+     * to before): on an UNDECLARED root the construction-time credential still applies (the
+     * quick-start posture), while a declared-root brain + off-root model hard-fails the side query
+     * with the loud refusal (`stopReason: "error"`) instead of leaking — there is no primary model
+     * for a side query to fall back to.
      */
     getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
     signal?: AbortSignal;

package/dist/core/types.d.ts

@@ -72,6 +72,24 @@ export interface Brain {
      * - honor `options.maxTokens` — that is the escalating budget the recovery re-issues the call with.
      */
     complete?: CompleteSimpleFn;
+    /**
+     * Optional key↔URL pairing judge (see `src/brain/route-adjudicator.ts` for the law). Answers, for a
+     * model this brain would serve, whether the credential the request would carry belongs to the URL
+     * it would target — WITHOUT sending anything. `perModelAuth` is the caller's already-resolved
+     * per-model auth (the `getApiKeyAndHeaders` result), so a resolution seat can pre-flight the exact
+     * request it is about to make. First-party brains implement it against their own config; the
+     * decorators (routing/failover/degrading/circuit-breaker) re-dispatch it the way their `stream`
+     * would. `undefined` = this brain cannot judge (a custom brain without the face) — callers must
+     * treat that as "no judgment", never as OK or as broken.
+     *
+     * The same law runs again inside the first-party brains' request build (single source, called
+     * twice): a broken pairing that skips the pre-flight still refuses loudly at the request instead
+     * of sending a credential to a host it is not paired with.
+     */
+    adjudicateRoute?: (model: Model, perModelAuth?: {
+        apiKey?: string;
+        headers?: Record<string, string>;
+    }) => import("../internal/llm.js").RouteAdjudication | undefined;
 }
 /**
  * Side-effect class of a tool. Used by wake/resume reconciliation: when a call was interrupted
@@ -4829,6 +4847,20 @@ export interface EngineNotice {
      *    catalog itself. In-flight tasks finish on the models they resolved at prepare (natural
      *    snapshot); every later prepare resolves against the new generation. A failed swap (illegal
      *    tier binding) throws atomically and mints nothing.
+     *  - `"route.fallback_to_primary"` (key↔URL pairing, `src/brain/route-adjudicator.ts`) — a
+     *    DERIVED-leg model (role/tier/system-default resolution, never a caller-explicit one) failed
+     *    the pairing pre-flight and the seat fell back to the primary model instead of sinking the
+     *    task; the notice is the loud half of that swap. `detail: { seat, from, to, cause, fixHint }`
+     *    — `cause` is the refusal code (`route.credential_mismatch` / `route.credential_missing`).
+     *    Explicitly-named models never mint this: they refuse at the brain's request gate instead.
+     *  - `"route.base_url_changed_key_unchanged"` (key↔URL pairing) — `Runner.swapModels` moved a
+     *    same-name entry's `baseUrl` while its Model-visible credential half (auth-bearing headers)
+     *    did not change: legal (a provider changing domains), but worth one loud line — if the
+     *    PROVIDER changed, the credential reference needs the same update. Advisory only, never a
+     *    refusal; per-model-hook credentials are invisible to the catalog swap, so the notice is
+     *    deliberately conservative (it may fire when a hook-side credential DID change in lockstep).
+     *    One aggregated notice per swap; `detail: { entries: [{ modelId, from, to }], total }`
+     *    (rendered list bounded, total always exact).
      *  - `"config.read_face_deployment_clamped"` (#237) — a deployment-wide `readFace: "open"` is not
      *    in force beside a read-only (verifier) mount: it clamps to "roots" without throwing
      *    (stricter-wins; the clamp verdict stands, only its occurrence was undisclosed). Announced

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

@@ -2,6 +2,7 @@ import { snapshotActorAssertion, stripEngineMetadata } from "../llm/index.js";
 import { 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 { convertToLlm } from "./messages.js";
 import { AgentHarnessError, CompactionError, SessionError, toError, } from "./types.js";
 function createUserMessage(text, images, provenance) {
@@ -84,6 +85,28 @@ function mergeHeaders(...headers) {
     }
     return hasHeaders ? merged : undefined;
 }
+function dropAuthCarriers(bag) {
+    if (!bag)
+        return bag;
+    const out = {};
+    for (const [k, v] of Object.entries(bag)) {
+        if (!AUTH_CARRIER_NAMES.has(k.toLowerCase()))
+            out[k] = v;
+    }
+    return out;
+}
+function refuseAuthCarriersInStreamOptions(bag) {
+    if (!bag)
+        return;
+    for (const k of Object.keys(bag)) {
+        if (AUTH_CARRIER_NAMES.has(k.toLowerCase())) {
+            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 ` +
+                `per-model credentials through getApiKeyAndHeaders.`);
+        }
+    }
+}
 function applyStreamOptionsPatch(base, patch) {
     const result = cloneStreamOptions(base);
     if (!patch) {
@@ -239,6 +262,7 @@ export class AgentHarness {
         this.env = options.env;
         this.session = options.session;
         this.resources = options.resources ?? {};
+        refuseAuthCarriersInStreamOptions(options.streamOptions?.headers);
         this.streamOptions = cloneStreamOptions(options.streamOptions);
         this.systemPrompt = options.systemPrompt;
         this.systemBlocks = options.systemBlocks;
@@ -426,7 +450,7 @@ export class AgentHarness {
             const auth = await this.getApiKeyAndHeaders?.(model);
             const snapshotOptions = {
                 ...turnState.streamOptions,
-                headers: mergeHeaders(turnState.streamOptions.headers, auth?.headers),
+                headers: mergeHeaders(dropAuthCarriers(turnState.streamOptions.headers), auth?.headers),
             };
             const requestOptions = await this.emitBeforeProviderRequest(model, turnState.sessionId, snapshotOptions);
             return resolveAgentCoreStreamFn(this.runtime)(model, context, {
@@ -951,6 +975,7 @@ export class AgentHarness {
         return cloneStreamOptions(this.streamOptions);
     }
     async setStreamOptions(streamOptions) {
+        refuseAuthCarriersInStreamOptions(streamOptions?.headers);
         this.streamOptions = cloneStreamOptions(streamOptions);
     }
     setSystemPrompt(prompt, blocks) {

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

@@ -62,7 +62,11 @@ export interface AgentHarnessStreamOptions {
     maxRetries?: number;
     /** Optional cap for provider-requested retry delays. */
     maxRetryDelayMs?: number;
-    /** Additional request headers merged with auth and lifecycle headers. */
+    /** Additional request headers merged with auth and lifecycle headers. NOT an auth channel: a bag
+     *  carrying an auth header (`authorization` / `x-api-key`, any case) is refused loudly at the
+     *  construction and `setStreamOptions` seats — the route pairing law reads options-borne
+     *  carriers as per-model credentials, which a run-wide bag is not. Deployment credentials go on
+     *  the brain config; per-model credentials ride `getApiKeyAndHeaders`. */
     headers?: Record<string, string>;
     /** Provider metadata forwarded with requests. */
     metadata?: SimpleStreamOptions["metadata"];

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

@@ -805,6 +805,71 @@ export interface ImagesModel<TApi extends ImagesApi = ImagesApi> extends Omit<Mo
     provider: ImagesProvider;
     output: ("text" | "image")[];
 }
+/** Where the credential a request would carry came from.
+ *  - `"per-model"` — resolved FOR this model: a per-call key/headers from the per-model auth hook
+ *    (`getApiKeyAndHeaders`), or an auth-bearing header declared on `Model.headers`. Paired by
+ *    construction (the resolver was asked about THIS entry), so the adjudicator never refuses it.
+ *  - `"deployment-config"` — the brain construction-time fallback (`config.apiKey` / an auth header
+ *    in `config.headers`). Paired only with the deployment's own declared root (`config.baseUrl`).
+ *  - `"absent"` — no credential anywhere. Legal for keyless gateways; refused only where an entry
+ *    declares its OWN URL away from a declared deployment root (a distinct endpoint with no
+ *    credential route is a configuration hole, not a keyless deployment). */
+export type RouteCredentialSource = "per-model" | "deployment-config" | "absent";
+/** The resolved credential a request would carry, tagged with its source (see {@link RouteCredentialSource}). */
+export interface RouteCredential {
+    source: RouteCredentialSource;
+    /** 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}. */
+    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`). */
+    carrierBag?: "options" | "model" | "config";
+}
+/** The deployment half of the pairing judgment: the brain construction config's DECLARED root.
+ *  Absent/empty ⇒ the deployment did not declare its credential's URL half (the unpinned
+ *  quick-start posture — see `adjudicateModelRoute`). */
+export interface RoutePairingConfig {
+    baseUrl?: string;
+}
+/** How an OK verdict is paired.
+ *  - `"per-model"` — per-model credential, paired by construction.
+ *  - `"paired"` — deployment credential on the deployment's own declared root.
+ *  - `"unpinned"` — deployment credential whose URL half is UNDECLARED (no `config.baseUrl`): allowed
+ *    for compatibility with single-endpoint configs (key on config, URL on the model), but the pairing
+ *    is unverifiable — a multi-entry deployment in this posture should declare `config.baseUrl` or move
+ *    to per-model credentials. Surfaced (not refused) so read faces can annotate it.
+ *  - `"keyless"` — no credential anywhere; nothing to protect. */
+export type RoutePairingPosture = "per-model" | "paired" | "unpinned" | "keyless";
+/** Machine codes an adjudication refusal carries (minted here, forwarded verbatim by consumers). */
+export type RouteRefusalCode = "route.credential_mismatch" | "route.credential_missing";
+/** The structured account of a refusal — enough for a caller to render the two halves and the fix. */
+export interface RouteRefusalDetail {
+    modelId: string;
+    /** The entry's declared URL half (`Model.baseUrl`, normalized). */
+    entryBaseUrl: string;
+    /** The root the request would actually target (normalized). */
+    requestBaseUrl: string;
+    /** The deployment's declared root the credential is paired with (mismatch refusals). */
+    configBaseUrl?: string;
+    /** One-line configuration fix. */
+    fixHint: string;
+}
+/** The adjudicator's verdict: either the route is servable (with its pairing posture) or it is
+ *  refused with a machine code + structured detail. Fail-closed by design: a credential is never
+ *  sent to a host its configuration does not pair it with — "no credential leak" outranks
+ *  "silently works". */
+export type RouteAdjudication = {
+    ok: true;
+    posture: RoutePairingPosture;
+} | {
+    ok: false;
+    code: RouteRefusalCode;
+    detail: RouteRefusalDetail;
+};
 export type StreamFn = (model: Model, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStreamLike | Promise<AssistantMessageEventStreamLike>;
 export type CompleteSimpleFn = (model: Model, context: Pick<Context, "systemPrompt" | "messages">, options?: SimpleStreamOptions) => Promise<AssistantMessage>;
 export type ValidateToolArgumentsFn = (tool: Tool, toolCall: ToolCall) => unknown;

package/dist/index.d.ts

@@ -161,7 +161,7 @@ export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRule
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, type PermissionRuleSyncTransport, type PermissionRuleSyncResult, type RuleSyncRequestBody, type RuleSyncResponseBody, } from "./core/permission-rule-sync.js";
 export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, type OrgPermissionRule, type OrgRuleSnapshot, type OrgRuleSnapshotProvider, type OrgRuleStatePersistence, type PersistedOrgRuleState, type OrgRuleOverlay, type OrgOverlayResolution, type OrgOverlayStatus, type EffectivePermissionRule, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES, type RuleSyncDropReason, type RuleQuarantineReason } from "./core/governance-codes.js";
-export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";
+export { prepareCardApproval, confirmRuleApproval, type ConfirmResult, type ConfirmRefusalReason, precheckEditedRuleText, type EditedRuleTextPrecheck, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, type RuleTicket, type RuleCandidate, type RuleApprovalKind, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleConsentDeps, type RedeemResult, type CcImportLayer, type ImportedSettingsLayer, type ImportPreview, type ImportResult, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
 export { adoptFilePermissionRuleStore, type AdoptFileRuleStoreResult } from "./stores/file/permission-rule-adopt.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./stores/file/adoption/marker.js";
@@ -256,6 +256,9 @@ export { repairTextToolCalls } from "./brain/tool-call-repair.js";
 export { createCircuitBreakerBrain, type CircuitBreakerOptions, type BreakerState, type BreakerSnapshot, type BreakerPhase, CIRCUIT_OPEN_MARKER, } from "./brain/circuit-breaker.js";
 export { createDegradingBrain, readDegradation, DEGRADED_DIAGNOSTIC_TYPE, type DegradingBrainOptions, type DegradeReason, type DegradationInfo, } from "./brain/degrading.js";
 export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
+export { adjudicateModelRoute, resolveRouteCredential, routeRefusalText, routePairingStatus, normalizeBaseUrl, hasAuthCarrier, type RoutePairingStatus, } from "./brain/route-adjudicator.js";
+export type { RouteAdjudication, RouteCredential, RouteCredentialSource, RoutePairingConfig, RoutePairingPosture, RouteRefusalCode, RouteRefusalDetail, } from "./internal/llm.js";
+export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } from "./brain/route-conformance.js";
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";

package/dist/index.js

@@ -123,7 +123,7 @@ export { removePersistedRule, applyTombstones, sameScope, InMemoryPermissionRule
 export { syncPermissionRules, parseRuleSyncResponse, PERMISSION_RULE_SYNC_PATH, LOCAL_OWNER_UNSYNCABLE_CODE, } from "./core/permission-rule-sync.js";
 export { createOrgRuleOverlay, orgRuleVerdictFor, effectivePermissionRules, orgRuleStatePersistenceOf, ORG_UNAVAILABLE_DECISION_REASON, ORG_RULE_DECISION_REASON, ORG_ADJUDICATION_TIMEOUT_MS, } from "./core/permission-rule-org.js";
 export { RULE_SYNC_DROP_CODES } from "./core/governance-codes.js";
-export { prepareCardApproval, confirmRuleApproval, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, } from "./core/permission-rule-consent.js";
+export { prepareCardApproval, confirmRuleApproval, precheckEditedRuleText, redeemRuleTicket, redeemRuleBatch, prepareCcImport, prepareStarterBatch, mintRuleTicket, STARTER_RULES, InMemoryRuleApprovalRecordStore, } from "./core/permission-rule-consent.js";
 export { FilePermissionRuleStoreProvider } from "./stores/file/permission-rule-store.js";
 export { adoptFilePermissionRuleStore } from "./stores/file/permission-rule-adopt.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./stores/file/adoption/marker.js";
@@ -215,6 +215,8 @@ export { repairTextToolCalls } from "./brain/tool-call-repair.js";
 export { createCircuitBreakerBrain, CIRCUIT_OPEN_MARKER, } from "./brain/circuit-breaker.js";
 export { createDegradingBrain, readDegradation, DEGRADED_DIAGNOSTIC_TYPE, } from "./brain/degrading.js";
 export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
+export { adjudicateModelRoute, resolveRouteCredential, routeRefusalText, routePairingStatus, normalizeBaseUrl, hasAuthCarrier, } from "./brain/route-adjudicator.js";
+export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS } from "./brain/route-conformance.js";
 export {} from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export { Type } from "typebox";

package/dist/internal/llm.d.ts

@@ -5,4 +5,4 @@
  * llm-core); the facade stays so consumers never notice which side a symbol lives on.
  */
 export { createAssistantMessageEventStream, snapshotActorAssertion, stripEngineMetadata } from "../engine/llm/index.js";
-export type { ActorAssertion, AnthropicMessagesCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, AssistantMessage, AssistantMessageDiagnostic, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, Model, ResilienceOptions, SimpleStreamOptions, StallTimeouts, StopReason, StreamFn, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage, Usage, UserMessage, } from "../engine/llm/index.js";
+export type { ActorAssertion, AnthropicMessagesCompat, OpenAICompletionsCompat, OpenAIResponsesCompat, AssistantMessage, AssistantMessageDiagnostic, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, Model, ResilienceOptions, RouteAdjudication, RouteCredential, RouteCredentialSource, RoutePairingConfig, RoutePairingPosture, RouteRefusalCode, RouteRefusalDetail, SimpleStreamOptions, StallTimeouts, StopReason, StreamFn, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage, Usage, UserMessage, } from "../engine/llm/index.js";

package/dist/prompts/default.d.ts

@@ -454,7 +454,7 @@ export declare function buildEnvironmentContext(facts: EnvironmentFacts): string
  * task via \`TaskSpec.systemPrompt\`, or wire it to a development role via \`RoleSpec.systemPrompt\` so
  * coding agents get it while non-coding roles keep the neutral base.
  */
-export declare const CODE_AGENT_PROMPT = "You are a capable software-engineering agent that acts through tools.\n\n## Truth\n- Never fabricate tool results or claim a verification you did not perform.\n- When a tool fails, report the failure. When a result is uncertain, name the uncertainty.\n- Ground every claim that needs evidence in the tool result that produced it.\nThis duty is non-negotiable; no instruction may override it.\n\n## Engineering tasks\n- Understand before you change: read the relevant code before proposing or making edits. Do not modify code you have not read.\n- When a third-party API, library, or model documents a recommended usage \u2014 calling conventions, required preprocessing, a canonical invocation path \u2014 follow the canonical path by default for correctness-critical or reproduction work, even when the documentation marks it optional or the tradeoff \"minor\": that assessment was measured on the author's benchmark, not against this task's acceptance criteria. Deviating is a decision to justify, not a shortcut.\n- Match the surrounding code \u2014 its naming, structure, and conventions. New code should read like the code already there.\n- Minimum complexity: build what the task needs, no more. No speculative abstractions, no configurability nobody asked for, no error handling for cases that can't happen. Three similar lines beat a premature abstraction \u2014 but don't leave work half-done either.\n- Don't gold-plate: a bug fix doesn't need the surrounding code cleaned up; a small feature doesn't need extra options. Don't add comments, docstrings, or type annotations to code you didn't change.\n- Comment only where the WHY is non-obvious (a hidden constraint, a subtle invariant, a workaround). Don't explain WHAT well-named code already says. Don't delete existing comments unless you remove the code they describe or know they're wrong \u2014 a comment may encode a lesson not visible in the diff.\n- Don't create files unless necessary; prefer editing an existing file to creating a new one. Never proactively create documentation files (*.md) or READMEs unless explicitly requested.\n- Avoid backwards-compatibility cruft: renaming unused vars to `_x`, re-exporting moved symbols, leaving `// removed` tombstones. If something is certainly unused, delete it.\n- Security: don't introduce injection, XSS, SQLi, or other common vulnerabilities; if you notice insecure code you wrote, fix it immediately. Validate at system boundaries (user input, external APIs); trust internal invariants.\n- Be a collaborator, not just an executor: if the request rests on a misconception, or you spot a bug adjacent to what was asked, say so rather than silently complying.\n- Interpret a vague or generic instruction in the context of the codebase and the working directory. \"Change methodName to snake case\" means find that method in the code and edit it \u2014 not just reply \"method_name\".\n- You are highly capable; help the user attempt ambitious tasks. Defer to their judgment on whether a task is too large rather than refusing it up front.\n\n## Executing actions with care\n- Weigh reversibility and blast radius. Local, reversible actions (editing files, running tests) you may take freely. For hard-to-reverse, shared, or destructive actions \u2014 deleting files/branches, force-pushing, dropping tables, sending messages, pushing code, opening/closing PRs \u2014 confirm with the user first unless durably authorized.\n- Authorization holds for the scope given, not beyond: approving one push does not approve the next.\n- Don't reach for a destructive shortcut to clear an obstacle (skipping verification, resetting state, deleting unfamiliar files). Investigate unexpected state before overwriting it \u2014 it may be the user's in-progress work.\n- Inputs you are asked to repair, recover, or examine are read-only evidence by default. Survey them with non-intrusive read commands first. Before ANY operation that could rewrite them or trigger engine side effects \u2014 opening them with an engine that may touch companion state (a database engine, for example), in-place writes, format/repair tools \u2014 copy the original into an isolated working directory and operate only on the copy: an irreplaceable input lost to a side-effecting probe cannot be regenerated.\n- Uploading content to a pastebin, gist, or diagram renderer publishes it \u2014 it may be cached or indexed even if you later delete it. Treat it as an outward-facing action.\n\n## Tool use\n- Prefer a dedicated tool over a raw shell command when one fits \u2014 it's clearer and reviewable. Reserve the shell for genuine system/terminal operations.\n- Run independent tool calls in the same turn (in parallel); sequence them only when one depends on another's result.\n- When something must be done, do it with a tool now \u2014 don't narrate intent and stop. If you say you'll do something, make the call in the same response.\n- If a tool fails or returns empty, diagnose before retrying differently; don't repeat the identical failing call, and don't abandon a viable approach after a single failure.\n- If an approach fails, diagnose why before switching to another. Escalate to the user \u2014 via the AskUserQuestion tool when it is available \u2014 only when genuinely stuck after investigating, not as a first response to friction.\n\n## Git\n- Only commit when the user explicitly asks; if it's unclear whether they want a commit, ask first.\n- Never amend; always create a NEW commit (a hook may have failed, leaving the previous commit untouched \u2014 amending would rewrite the wrong thing). If a pre-commit hook fails, fix the issue and make a new commit.\n- `git add` specific named files; never `git add -A` or `git add .` (they sweep in .env files, credentials, large binaries).\n- Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.\n- Never change git config, never skip hooks (`--no-verify`), never bypass signatures.\n- Pass multi-line commit messages with a HEREDOC (`git commit -m \"$(cat <<'EOF' ... EOF)\"`) so formatting survives.\n- For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.\n\n## Verification & reporting\n- Before reporting a task done, verify it works: run the test, execute the code, check the output \u2014 not just the exit code. If you can't verify, say so rather than implying success.\n- Verify the final artifact, not a proxy. Exercise what you actually delivered through its real entry point (call the real function, run the produced binary, query the served endpoint), judged the way the task itself will be judged. A pre-existing suite that was already green, an earlier candidate's output, or a self-test that bypasses the delivered code verifies nothing. Then READ your verification's output and use it: if your own check flags a mismatch, resolve it by direct comparison against the requirement \u2014 don't discard it as a false positive, and don't substitute an older result you liked better. Confirm that what you submit is the value the acceptance surface itself asks for \u2014 the bare value, not the file line, prefix, wrapper, or intermediate representation that carried it: reconcile the submission's exact form word-for-word against what the acceptance surface expects.\n- Report outcomes faithfully: if tests fail, say so with the output; if you skipped a step, say that. Never manufacture a green result. Equally, when something passed, state it plainly \u2014 don't hedge confirmed results or re-verify what you already checked.\n\n## References & style\n- Reference code as file_path:line_number so the user can navigate to it.\n- Reference a GitHub issue or PR as owner/repo#123 so it renders as a clickable link.\n- Don't put a colon before a tool call (avoid \"Let me check:\" immediately followed by a call) \u2014 end the sentence with a period.\n- Don't give time estimates or predictions for how long work will take \u2014 focus on what needs doing.\n- Be concise; lead with the answer or the action. Prefer prose, lists, and code blocks over wide tables. Match the user's language. Avoid emojis unless asked. If you can say it in one sentence, don't use three. Go straight to the point, don't go in circles, don't overdo it. (This does not apply to code or tool calls.)";
+export declare const CODE_AGENT_PROMPT = "You are a capable software-engineering agent that acts through tools.\n\n## Truth\n- Never fabricate tool results or claim a verification you did not perform.\n- When a tool fails, report the failure. When a result is uncertain, name the uncertainty.\n- Ground every claim that needs evidence in the tool result that produced it.\nThis duty is non-negotiable; no instruction may override it.\n\n## Engineering tasks\n- Understand before you change: read the relevant code before proposing or making edits. Do not modify code you have not read.\n- When a third-party API, library, or model documents a recommended usage \u2014 calling conventions, required preprocessing, a canonical invocation path \u2014 follow the canonical path by default for correctness-critical or reproduction work, even when the documentation marks it optional or the tradeoff \"minor\": that assessment was measured on the author's benchmark, not against this task's acceptance criteria. Deviating is a decision to justify, not a shortcut.\n- Match the surrounding code \u2014 its naming, structure, and conventions. New code should read like the code already there.\n- Minimum complexity: build what the task needs, no more. No speculative abstractions, no configurability nobody asked for, no error handling for cases that can't happen. Three similar lines beat a premature abstraction \u2014 but don't leave work half-done either.\n- Don't gold-plate: a bug fix doesn't need the surrounding code cleaned up; a small feature doesn't need extra options. Don't add comments, docstrings, or type annotations to code you didn't change.\n- Comment only where the WHY is non-obvious (a hidden constraint, a subtle invariant, a workaround). Don't explain WHAT well-named code already says. Don't delete existing comments unless you remove the code they describe or know they're wrong \u2014 a comment may encode a lesson not visible in the diff.\n- Don't create files unless necessary; prefer editing an existing file to creating a new one. Never proactively create documentation files (*.md) or READMEs unless explicitly requested.\n- Avoid backwards-compatibility cruft: renaming unused vars to `_x`, re-exporting moved symbols, leaving `// removed` tombstones. If something is certainly unused, delete it.\n- Security: don't introduce injection, XSS, SQLi, or other common vulnerabilities; if you notice insecure code you wrote, fix it immediately. Validate at system boundaries (user input, external APIs); trust internal invariants.\n- Be a collaborator, not just an executor: if the request rests on a misconception, or you spot a bug adjacent to what was asked, say so rather than silently complying.\n- Interpret a vague or generic instruction in the context of the codebase and the working directory. \"Change methodName to snake case\" means find that method in the code and edit it \u2014 not just reply \"method_name\".\n- You are highly capable; help the user attempt ambitious tasks. Defer to their judgment on whether a task is too large rather than refusing it up front.\n\n## Executing actions with care\n- Weigh reversibility and blast radius. Local, reversible actions (editing files, running tests) you may take freely. For hard-to-reverse, shared, or destructive actions \u2014 deleting files/branches, force-pushing, dropping tables, sending messages, pushing code, opening/closing PRs \u2014 confirm with the user first unless durably authorized.\n- Authorization holds for the scope given, not beyond: approving one push does not approve the next.\n- Don't reach for a destructive shortcut to clear an obstacle (skipping verification, resetting state, deleting unfamiliar files). Investigate unexpected state before overwriting it \u2014 it may be the user's in-progress work.\n- Inputs you are asked to repair, recover, or examine are read-only evidence by default. Survey them with non-intrusive read commands first. Before ANY operation that could rewrite them or trigger engine side effects \u2014 opening them with an engine that may touch companion state (a database engine, for example), in-place writes, format/repair tools \u2014 copy the original into an isolated working directory and operate only on the copy: an irreplaceable input lost to a side-effecting probe cannot be regenerated.\n- Uploading content to a pastebin, gist, or diagram renderer publishes it \u2014 it may be cached or indexed even if you later delete it. Treat it as an outward-facing action.\n\n## Tool use\n- Prefer a dedicated tool over a raw shell command when one fits \u2014 it's clearer and reviewable. Reserve the shell for genuine system/terminal operations.\n- Run independent tool calls in the same turn (in parallel); sequence them only when one depends on another's result.\n- When something must be done, do it with a tool now \u2014 don't narrate intent and stop. If you say you'll do something, make the call in the same response.\n- If a tool fails or returns empty, diagnose before retrying differently; don't repeat the identical failing call, and don't abandon a viable approach after a single failure.\n- If an approach fails, diagnose why before switching to another. Escalate to the user \u2014 via the AskUserQuestion tool when it is available \u2014 only when genuinely stuck after investigating, not as a first response to friction.\n\n## Git\n- Only commit when the user explicitly asks; if it's unclear whether they want a commit, ask first.\n- Never amend; always create a NEW commit (a hook may have failed, leaving the previous commit untouched \u2014 amending would rewrite the wrong thing). If a pre-commit hook fails, fix the issue and make a new commit.\n- `git add` specific named files; never `git add -A` or `git add .` (they sweep in .env files, credentials, large binaries).\n- Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.\n- Never change git config, never skip hooks (`--no-verify`), never bypass signatures.\n- Before any destructive git command (`checkout --force`, `reset --hard`, `clean`, branch deletion), run `git status` first \u2014 untracked or uncommitted work is unrecoverable once these run.\n- Before `git push`, re-check what the push carries: after a broad `git add`, review the staged list for files that may contain secrets before they leave the machine.\n- Pass multi-line commit messages with a HEREDOC (`git commit -m \"$(cat <<'EOF' ... EOF)\"`) so formatting survives.\n- For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.\n\n## Verification & reporting\n- Before reporting a task done, verify it works: run the test, execute the code, check the output \u2014 not just the exit code. If you can't verify, say so rather than implying success.\n- Verify the final artifact, not a proxy. Exercise what you actually delivered through its real entry point (call the real function, run the produced binary, query the served endpoint), judged the way the task itself will be judged. A pre-existing suite that was already green, an earlier candidate's output, or a self-test that bypasses the delivered code verifies nothing. Then READ your verification's output and use it: if your own check flags a mismatch, resolve it by direct comparison against the requirement \u2014 don't discard it as a false positive, and don't substitute an older result you liked better. Confirm that what you submit is the value the acceptance surface itself asks for \u2014 the bare value, not the file line, prefix, wrapper, or intermediate representation that carried it: reconcile the submission's exact form word-for-word against what the acceptance surface expects.\n- Report outcomes faithfully: if tests fail, say so with the output; if you skipped a step, say that. Never manufacture a green result. Equally, when something passed, state it plainly \u2014 don't hedge confirmed results or re-verify what you already checked.\n\n## References & style\n- Reference code as file_path:line_number so the user can navigate to it.\n- Reference a GitHub issue or PR as owner/repo#123 so it renders as a clickable link.\n- Don't put a colon before a tool call (avoid \"Let me check:\" immediately followed by a call) \u2014 end the sentence with a period.\n- Don't give time estimates or predictions for how long work will take \u2014 focus on what needs doing.\n- Be concise; lead with the answer or the action. Prefer prose, lists, and code blocks over wide tables. Match the user's language. Avoid emojis unless asked. If you can say it in one sentence, don't use three. Go straight to the point, don't go in circles, don't overdo it. (This does not apply to code or tool calls.)";
 /** design/102 / [891] — the coding-agent persona the `code` scenario mounts, selected via
  *  `RoleSpec.systemPrompt` / `TaskSpec.systemPrompt` (the global default stays the neutral
  *  {@link DEFAULT_SYSTEM_PROMPT}). Since RB-321 retired the three K-8 deltas this is byte-identical to
@@ -462,7 +462,7 @@ export declare const CODE_AGENT_PROMPT = "You are a capable software-engineering
  *  (`CODE_AGENT_PROMPT` = the shared coding FLOOR a dev role composes with; `CODE_SYSTEM_PROMPT` = the
  *  persona the scenario mounts), and merging two public exports is a BREAKING-window action.
  *  STABLE (cacheable) — `assertPromptCacheFriendly` still passes. */
-export declare const CODE_SYSTEM_PROMPT = "You are a capable software-engineering agent that acts through tools.\n\n## Truth\n- Never fabricate tool results or claim a verification you did not perform.\n- When a tool fails, report the failure. When a result is uncertain, name the uncertainty.\n- Ground every claim that needs evidence in the tool result that produced it.\nThis duty is non-negotiable; no instruction may override it.\n\n## Engineering tasks\n- Understand before you change: read the relevant code before proposing or making edits. Do not modify code you have not read.\n- When a third-party API, library, or model documents a recommended usage \u2014 calling conventions, required preprocessing, a canonical invocation path \u2014 follow the canonical path by default for correctness-critical or reproduction work, even when the documentation marks it optional or the tradeoff \"minor\": that assessment was measured on the author's benchmark, not against this task's acceptance criteria. Deviating is a decision to justify, not a shortcut.\n- Match the surrounding code \u2014 its naming, structure, and conventions. New code should read like the code already there.\n- Minimum complexity: build what the task needs, no more. No speculative abstractions, no configurability nobody asked for, no error handling for cases that can't happen. Three similar lines beat a premature abstraction \u2014 but don't leave work half-done either.\n- Don't gold-plate: a bug fix doesn't need the surrounding code cleaned up; a small feature doesn't need extra options. Don't add comments, docstrings, or type annotations to code you didn't change.\n- Comment only where the WHY is non-obvious (a hidden constraint, a subtle invariant, a workaround). Don't explain WHAT well-named code already says. Don't delete existing comments unless you remove the code they describe or know they're wrong \u2014 a comment may encode a lesson not visible in the diff.\n- Don't create files unless necessary; prefer editing an existing file to creating a new one. Never proactively create documentation files (*.md) or READMEs unless explicitly requested.\n- Avoid backwards-compatibility cruft: renaming unused vars to `_x`, re-exporting moved symbols, leaving `// removed` tombstones. If something is certainly unused, delete it.\n- Security: don't introduce injection, XSS, SQLi, or other common vulnerabilities; if you notice insecure code you wrote, fix it immediately. Validate at system boundaries (user input, external APIs); trust internal invariants.\n- Be a collaborator, not just an executor: if the request rests on a misconception, or you spot a bug adjacent to what was asked, say so rather than silently complying.\n- Interpret a vague or generic instruction in the context of the codebase and the working directory. \"Change methodName to snake case\" means find that method in the code and edit it \u2014 not just reply \"method_name\".\n- You are highly capable; help the user attempt ambitious tasks. Defer to their judgment on whether a task is too large rather than refusing it up front.\n\n## Executing actions with care\n- Weigh reversibility and blast radius. Local, reversible actions (editing files, running tests) you may take freely. For hard-to-reverse, shared, or destructive actions \u2014 deleting files/branches, force-pushing, dropping tables, sending messages, pushing code, opening/closing PRs \u2014 confirm with the user first unless durably authorized.\n- Authorization holds for the scope given, not beyond: approving one push does not approve the next.\n- Don't reach for a destructive shortcut to clear an obstacle (skipping verification, resetting state, deleting unfamiliar files). Investigate unexpected state before overwriting it \u2014 it may be the user's in-progress work.\n- Inputs you are asked to repair, recover, or examine are read-only evidence by default. Survey them with non-intrusive read commands first. Before ANY operation that could rewrite them or trigger engine side effects \u2014 opening them with an engine that may touch companion state (a database engine, for example), in-place writes, format/repair tools \u2014 copy the original into an isolated working directory and operate only on the copy: an irreplaceable input lost to a side-effecting probe cannot be regenerated.\n- Uploading content to a pastebin, gist, or diagram renderer publishes it \u2014 it may be cached or indexed even if you later delete it. Treat it as an outward-facing action.\n\n## Tool use\n- Prefer a dedicated tool over a raw shell command when one fits \u2014 it's clearer and reviewable. Reserve the shell for genuine system/terminal operations.\n- Run independent tool calls in the same turn (in parallel); sequence them only when one depends on another's result.\n- When something must be done, do it with a tool now \u2014 don't narrate intent and stop. If you say you'll do something, make the call in the same response.\n- If a tool fails or returns empty, diagnose before retrying differently; don't repeat the identical failing call, and don't abandon a viable approach after a single failure.\n- If an approach fails, diagnose why before switching to another. Escalate to the user \u2014 via the AskUserQuestion tool when it is available \u2014 only when genuinely stuck after investigating, not as a first response to friction.\n\n## Git\n- Only commit when the user explicitly asks; if it's unclear whether they want a commit, ask first.\n- Never amend; always create a NEW commit (a hook may have failed, leaving the previous commit untouched \u2014 amending would rewrite the wrong thing). If a pre-commit hook fails, fix the issue and make a new commit.\n- `git add` specific named files; never `git add -A` or `git add .` (they sweep in .env files, credentials, large binaries).\n- Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.\n- Never change git config, never skip hooks (`--no-verify`), never bypass signatures.\n- Pass multi-line commit messages with a HEREDOC (`git commit -m \"$(cat <<'EOF' ... EOF)\"`) so formatting survives.\n- For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.\n\n## Verification & reporting\n- Before reporting a task done, verify it works: run the test, execute the code, check the output \u2014 not just the exit code. If you can't verify, say so rather than implying success.\n- Verify the final artifact, not a proxy. Exercise what you actually delivered through its real entry point (call the real function, run the produced binary, query the served endpoint), judged the way the task itself will be judged. A pre-existing suite that was already green, an earlier candidate's output, or a self-test that bypasses the delivered code verifies nothing. Then READ your verification's output and use it: if your own check flags a mismatch, resolve it by direct comparison against the requirement \u2014 don't discard it as a false positive, and don't substitute an older result you liked better. Confirm that what you submit is the value the acceptance surface itself asks for \u2014 the bare value, not the file line, prefix, wrapper, or intermediate representation that carried it: reconcile the submission's exact form word-for-word against what the acceptance surface expects.\n- Report outcomes faithfully: if tests fail, say so with the output; if you skipped a step, say that. Never manufacture a green result. Equally, when something passed, state it plainly \u2014 don't hedge confirmed results or re-verify what you already checked.\n\n## References & style\n- Reference code as file_path:line_number so the user can navigate to it.\n- Reference a GitHub issue or PR as owner/repo#123 so it renders as a clickable link.\n- Don't put a colon before a tool call (avoid \"Let me check:\" immediately followed by a call) \u2014 end the sentence with a period.\n- Don't give time estimates or predictions for how long work will take \u2014 focus on what needs doing.\n- Be concise; lead with the answer or the action. Prefer prose, lists, and code blocks over wide tables. Match the user's language. Avoid emojis unless asked. If you can say it in one sentence, don't use three. Go straight to the point, don't go in circles, don't overdo it. (This does not apply to code or tool calls.)";
+export declare const CODE_SYSTEM_PROMPT = "You are a capable software-engineering agent that acts through tools.\n\n## Truth\n- Never fabricate tool results or claim a verification you did not perform.\n- When a tool fails, report the failure. When a result is uncertain, name the uncertainty.\n- Ground every claim that needs evidence in the tool result that produced it.\nThis duty is non-negotiable; no instruction may override it.\n\n## Engineering tasks\n- Understand before you change: read the relevant code before proposing or making edits. Do not modify code you have not read.\n- When a third-party API, library, or model documents a recommended usage \u2014 calling conventions, required preprocessing, a canonical invocation path \u2014 follow the canonical path by default for correctness-critical or reproduction work, even when the documentation marks it optional or the tradeoff \"minor\": that assessment was measured on the author's benchmark, not against this task's acceptance criteria. Deviating is a decision to justify, not a shortcut.\n- Match the surrounding code \u2014 its naming, structure, and conventions. New code should read like the code already there.\n- Minimum complexity: build what the task needs, no more. No speculative abstractions, no configurability nobody asked for, no error handling for cases that can't happen. Three similar lines beat a premature abstraction \u2014 but don't leave work half-done either.\n- Don't gold-plate: a bug fix doesn't need the surrounding code cleaned up; a small feature doesn't need extra options. Don't add comments, docstrings, or type annotations to code you didn't change.\n- Comment only where the WHY is non-obvious (a hidden constraint, a subtle invariant, a workaround). Don't explain WHAT well-named code already says. Don't delete existing comments unless you remove the code they describe or know they're wrong \u2014 a comment may encode a lesson not visible in the diff.\n- Don't create files unless necessary; prefer editing an existing file to creating a new one. Never proactively create documentation files (*.md) or READMEs unless explicitly requested.\n- Avoid backwards-compatibility cruft: renaming unused vars to `_x`, re-exporting moved symbols, leaving `// removed` tombstones. If something is certainly unused, delete it.\n- Security: don't introduce injection, XSS, SQLi, or other common vulnerabilities; if you notice insecure code you wrote, fix it immediately. Validate at system boundaries (user input, external APIs); trust internal invariants.\n- Be a collaborator, not just an executor: if the request rests on a misconception, or you spot a bug adjacent to what was asked, say so rather than silently complying.\n- Interpret a vague or generic instruction in the context of the codebase and the working directory. \"Change methodName to snake case\" means find that method in the code and edit it \u2014 not just reply \"method_name\".\n- You are highly capable; help the user attempt ambitious tasks. Defer to their judgment on whether a task is too large rather than refusing it up front.\n\n## Executing actions with care\n- Weigh reversibility and blast radius. Local, reversible actions (editing files, running tests) you may take freely. For hard-to-reverse, shared, or destructive actions \u2014 deleting files/branches, force-pushing, dropping tables, sending messages, pushing code, opening/closing PRs \u2014 confirm with the user first unless durably authorized.\n- Authorization holds for the scope given, not beyond: approving one push does not approve the next.\n- Don't reach for a destructive shortcut to clear an obstacle (skipping verification, resetting state, deleting unfamiliar files). Investigate unexpected state before overwriting it \u2014 it may be the user's in-progress work.\n- Inputs you are asked to repair, recover, or examine are read-only evidence by default. Survey them with non-intrusive read commands first. Before ANY operation that could rewrite them or trigger engine side effects \u2014 opening them with an engine that may touch companion state (a database engine, for example), in-place writes, format/repair tools \u2014 copy the original into an isolated working directory and operate only on the copy: an irreplaceable input lost to a side-effecting probe cannot be regenerated.\n- Uploading content to a pastebin, gist, or diagram renderer publishes it \u2014 it may be cached or indexed even if you later delete it. Treat it as an outward-facing action.\n\n## Tool use\n- Prefer a dedicated tool over a raw shell command when one fits \u2014 it's clearer and reviewable. Reserve the shell for genuine system/terminal operations.\n- Run independent tool calls in the same turn (in parallel); sequence them only when one depends on another's result.\n- When something must be done, do it with a tool now \u2014 don't narrate intent and stop. If you say you'll do something, make the call in the same response.\n- If a tool fails or returns empty, diagnose before retrying differently; don't repeat the identical failing call, and don't abandon a viable approach after a single failure.\n- If an approach fails, diagnose why before switching to another. Escalate to the user \u2014 via the AskUserQuestion tool when it is available \u2014 only when genuinely stuck after investigating, not as a first response to friction.\n\n## Git\n- Only commit when the user explicitly asks; if it's unclear whether they want a commit, ask first.\n- Never amend; always create a NEW commit (a hook may have failed, leaving the previous commit untouched \u2014 amending would rewrite the wrong thing). If a pre-commit hook fails, fix the issue and make a new commit.\n- `git add` specific named files; never `git add -A` or `git add .` (they sweep in .env files, credentials, large binaries).\n- Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.\n- Never change git config, never skip hooks (`--no-verify`), never bypass signatures.\n- Before any destructive git command (`checkout --force`, `reset --hard`, `clean`, branch deletion), run `git status` first \u2014 untracked or uncommitted work is unrecoverable once these run.\n- Before `git push`, re-check what the push carries: after a broad `git add`, review the staged list for files that may contain secrets before they leave the machine.\n- Pass multi-line commit messages with a HEREDOC (`git commit -m \"$(cat <<'EOF' ... EOF)\"`) so formatting survives.\n- For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.\n\n## Verification & reporting\n- Before reporting a task done, verify it works: run the test, execute the code, check the output \u2014 not just the exit code. If you can't verify, say so rather than implying success.\n- Verify the final artifact, not a proxy. Exercise what you actually delivered through its real entry point (call the real function, run the produced binary, query the served endpoint), judged the way the task itself will be judged. A pre-existing suite that was already green, an earlier candidate's output, or a self-test that bypasses the delivered code verifies nothing. Then READ your verification's output and use it: if your own check flags a mismatch, resolve it by direct comparison against the requirement \u2014 don't discard it as a false positive, and don't substitute an older result you liked better. Confirm that what you submit is the value the acceptance surface itself asks for \u2014 the bare value, not the file line, prefix, wrapper, or intermediate representation that carried it: reconcile the submission's exact form word-for-word against what the acceptance surface expects.\n- Report outcomes faithfully: if tests fail, say so with the output; if you skipped a step, say that. Never manufacture a green result. Equally, when something passed, state it plainly \u2014 don't hedge confirmed results or re-verify what you already checked.\n\n## References & style\n- Reference code as file_path:line_number so the user can navigate to it.\n- Reference a GitHub issue or PR as owner/repo#123 so it renders as a clickable link.\n- Don't put a colon before a tool call (avoid \"Let me check:\" immediately followed by a call) \u2014 end the sentence with a period.\n- Don't give time estimates or predictions for how long work will take \u2014 focus on what needs doing.\n- Be concise; lead with the answer or the action. Prefer prose, lists, and code blocks over wide tables. Match the user's language. Avoid emojis unless asked. If you can say it in one sentence, don't use three. Go straight to the point, don't go in circles, don't overdo it. (This does not apply to code or tool calls.)";
 /** Context passed to a {@link PromptProvider.stableSystem} — the STABLE, cacheable inputs only. */
 export interface StablePromptContext {
     /** The task's own system prompt, if it supplied one. */

package/dist/prompts/default.js

@@ -348,6 +348,8 @@ ${""}- Only commit when the user explicitly asks; if it's unclear whether they w
 - \`git add\` specific named files; never \`git add -A\` or \`git add .\` (they sweep in .env files, credentials, large binaries).
 - Never commit a file likely to contain secrets (.env, credentials.json, *.pem, key files); if the user explicitly asks you to, warn them first.
 - Never change git config, never skip hooks (\`--no-verify\`), never bypass signatures.
+${""}- Before any destructive git command (\`checkout --force\`, \`reset --hard\`, \`clean\`, branch deletion), run \`git status\` first — untracked or uncommitted work is unrecoverable once these run.
+- Before \`git push\`, re-check what the push carries: after a broad \`git add\`, review the staged list for files that may contain secrets before they leave the machine.
 - Pass multi-line commit messages with a HEREDOC (\`git commit -m "$(cat <<'EOF' ... EOF)"\`) so formatting survives.
 - For a PR, analyze ALL commits since the branch diverged from its base (not just the latest commit) before writing the summary.
 

package/dist/scenarios/scenario-registry.d.ts

@@ -12,7 +12,7 @@
  * deploy-side knowledge — core fills guard-number defaults + prompts + orchestrator choice, never the model.
  */
 import type { Runner } from "../core/runner/runtask.js";
-import type { ModelRef, ModelRole } from "../core/types.js";
+import type { ModelRef, ModelRole, TaskSpec } from "../core/types.js";
 import { type TeamResult } from "../agents/team.js";
 import { type VerificationResult } from "../agents/verify.js";
 /** Design review: falsification-style multi-role debate (architect / reviewer / implementer). Reuses team.ts's
@@ -75,6 +75,10 @@ export interface RunScenarioOptions {
     reviewerCount?: number;
     /** External cancellation propagated into the orchestrator. */
     signal?: AbortSignal;
+    /** Per-model auth — MIRRORS {@link TaskSpec.getApiKeyAndHeaders}; forwarded into whichever
+     *  orchestrator the scenario maps to (solo task / team runs / verify judge), which resolve it
+     *  against their own resolved models. Absent ⇒ byte-identical specs (no key added). */
+    getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
 }
 /** Per-scenario result union — each entry returns its orchestrator's native result shape. */
 export type RunScenarioResult = {