agentfootprint 9.18.0 → 9.19.0

package/dist/esm/core/agent/skillBrains.js

@@ -0,0 +1,209 @@
+/**
+ * skillBrains — per-skill model switching (9.19.0). ONE owner of the brains
+ * fold: the declared shapes (`ProviderChoice`, `EscalationPolicy`), the
+ * build-time fold + check-up over BOTH declaration homes, and the runtime
+ * `brainFor` consult callLLM makes.
+ *
+ * "THE CURSOR PICKS THE BRAIN." A skill graph already decides WHERE the run
+ * is (the one cursor); this feature lets that same position decide WHO
+ * answers — a cheap triage skill on a small model, the refund skill on the
+ * strong one — with zero new stages: `callLLM` consults `brainFor(cursor,
+ * escalated)` once at the top and resolves field by field down the stated
+ * precedence chain:
+ *
+ *   **escalation > per-skill brain > `.configure()` `resolvedModel` >
+ *   build-time default** — the more specific context wins (evidence > node
+ *   > run > build). Field-by-field at the call site: `provider =
+ *   brain?.provider ?? deps.provider`; `model = brain?.model ??
+ *   (runConfigured ? scope.resolvedModel : undefined) ?? deps.model`;
+ *   `cacheStrategy = brain?.cacheStrategy ?? deps.cacheStrategy`. A brain
+ *   naming only a MODEL inherits the agent's provider; a brain naming only a
+ *   foreign PROVIDER may not inherit the agent's model id (that id belongs
+ *   to another vendor's namespace and would fail mid-turn, on exactly the
+ *   iteration the cursor enters the skill) — refused at build instead.
+ *
+ * TWO declaration homes, one meaning: `defineSkill({ provider, model })`
+ * keeps the choice beside the skill it serves; `SkillGraphOptions.providers`
+ * keeps a fleet's choices in one place at the mount. The same id declared in
+ * both with different choices is refused naming both homes — configuration
+ * that disagrees with itself must not pick a silent winner.
+ *
+ * ESCALATE-ON-EVIDENCE. `escalation: { provider, model?, afterRefusals: N }`
+ * — when the gate refuses N routing picks in ONE turn (`skill.rejected`,
+ * reachability or posture — real recorded refusals, never vibes), the rest
+ * of the turn runs on the escalation brain, `skill.escalated` goes on the
+ * record once, and the next turn's seed de-escalates. The loop the model is
+ * flubbing gets the bigger brain until the turn resolves.
+ *
+ * Vendor-neutral by construction: a brain is an `LLMProvider` OBJECT (any
+ * port implementation), never a vendor name this library resolves.
+ */
+import { getDefaultCacheStrategy } from '../../cache/strategyRegistry.js';
+/** The per-skill brain declared on `defineSkill({ provider, model })`,
+ *  read off the metadata bag (the engine-ignores-unknown precedent —
+ *  `projectActiveInjection` never projects it, so the live provider object
+ *  stays on the closure-held list and never crosses a scope boundary). */
+export function skillBrainOf(injection) {
+    const meta = injection.metadata;
+    if (meta?.provider === undefined && meta?.model === undefined)
+        return undefined;
+    return {
+        // `model` alone is legal — the agent's own provider, another model.
+        ...(meta.provider !== undefined && { provider: meta.provider }),
+        ...(meta.model !== undefined && { model: meta.model }),
+    };
+}
+/**
+ * Fold both declaration homes into one frozen map, running every build-time
+ * refusal (the check-up). Returns `undefined` when nothing was declared —
+ * the zero-cost gate every caller branches on.
+ */
+export function foldSkillBrains(args) {
+    const fromOptions = new Map(Object.entries(args.providers ?? {}));
+    const fromSkills = new Map();
+    for (const inj of args.injections) {
+        if (inj.flavor !== 'skill')
+            continue;
+        const brain = skillBrainOf(inj);
+        if (brain)
+            fromSkills.set(inj.id, brain);
+    }
+    const declaredAnything = fromOptions.size > 0 ||
+        fromSkills.size > 0 ||
+        args.escalation !== undefined ||
+        args.decider !== undefined;
+    if (!declaredAnything)
+        return undefined;
+    // A brain with no cursor to pick it: "the cursor picks the brain", and an
+    // agent without a graph has no cursor. Refused rather than silently inert.
+    if (!args.graphMounted) {
+        const ids = [...new Set([...fromOptions.keys(), ...fromSkills.keys()])];
+        const what = ids.length > 0
+            ? `per-skill brains (${ids.map((id) => `'${id}'`).join(', ')})`
+            : args.escalation !== undefined
+                ? 'an escalation policy'
+                : 'a routing decider';
+        throw new Error(`Agent.build(): ${what} declared, but no skill graph is mounted — the cursor picks ` +
+            `the brain, and without .skillGraph() there is no cursor, so the declaration would ` +
+            `never serve a single call. Mount a graph, or drop the provider/model declarations.`);
+    }
+    if (args.nodeIds === undefined) {
+        throw new Error(`Agent.build(): per-skill brains / escalation / decider were declared, but the mounted ` +
+            `graph object carries no \`nodes\` — the brain check-up cannot tell a skill id from a ` +
+            `typo against it. Build the graph with this version's skillGraph() (every graph it ` +
+            `builds carries nodes), or drop the declarations.`);
+    }
+    // Foreign-provider-without-model: decidable at build, guaranteed wrong at
+    // run (the agent's model id belongs to another vendor's namespace).
+    const requireModelOnForeign = (choice, where) => {
+        if (choice.model !== undefined)
+            return;
+        if (choice.provider === undefined || choice.provider.name === args.agentProviderName)
+            return;
+        throw new Error(`Agent.build(): ${where} names provider '${choice.provider.name}' without a model. The ` +
+            `run's configured model belongs to '${args.agentProviderName}' and cannot be resolved ` +
+            `against a different provider — the call would fail mid-turn, on exactly the ` +
+            `iteration this brain first serves. Name the model for it (inheritance down the ` +
+            `chain stays legal when the provider matches the agent's).`);
+    };
+    // Merge the two homes. Same id + same choice = fine (one fact said twice);
+    // different choices = a disagreement no silent winner may resolve.
+    const bySkill = new Map();
+    for (const [skillId, choice] of fromSkills)
+        bySkill.set(skillId, choice);
+    for (const [skillId, choice] of fromOptions) {
+        const other = fromSkills.get(skillId);
+        if (other !== undefined) {
+            const sameProvider = other.provider === choice.provider;
+            const sameModel = other.model === choice.model;
+            if (!sameProvider || !sameModel) {
+                throw new Error(`Agent.build(): skill '${skillId}' declares a brain in BOTH homes with different ` +
+                    `choices — defineSkill({ provider: ${describeChoice(other)} }) and ` +
+                    `skillGraph options.providers['${skillId}'] = ${describeChoice(choice)}. Two ` +
+                    `homes may repeat one choice; they may not disagree. Keep one declaration, or ` +
+                    `make them identical.`);
+            }
+        }
+        bySkill.set(skillId, choice);
+    }
+    for (const [skillId, choice] of bySkill) {
+        if (!args.nodeIds.has(skillId)) {
+            throw new Error(`Agent.build(): a brain is declared for skill '${skillId}', but the mounted graph ` +
+                `has no node with that id — the cursor can never land there, so the brain would ` +
+                `never serve a call. Fix the id, wire the skill into the graph, or drop the ` +
+                `declaration.`);
+        }
+        // `model` alone (provider undefined in the defineSkill home) is the
+        // agent's own provider — nothing foreign to check.
+        if (choice.provider !== undefined) {
+            requireModelOnForeign(choice, `skill '${skillId}''s brain`);
+        }
+    }
+    if (args.escalation !== undefined) {
+        const n = args.escalation.afterRefusals;
+        if (!Number.isInteger(n) || n < 1) {
+            throw new Error(`Agent.build(): escalation.afterRefusals must be an integer ≥ 1 (got ${String(n)}). ` +
+                `It counts recorded gate refusals (skill.rejected) in one turn before the flip — ` +
+                `0 would mean "always escalated", which is not escalation but a different default ` +
+                `brain; declare that as the agent's provider/model instead.`);
+        }
+        requireModelOnForeign(args.escalation, 'the escalation brain');
+    }
+    if (args.decider !== undefined) {
+        requireModelOnForeign(args.decider, 'the routing decider');
+    }
+    return {
+        bySkill,
+        ...(args.escalation !== undefined && { escalation: args.escalation }),
+        ...(args.decider !== undefined && { decider: args.decider }),
+    };
+}
+function describeChoice(c) {
+    const provider = c.provider !== undefined ? `provider '${c.provider.name}'` : 'agent provider';
+    return c.model !== undefined ? `${provider}, model '${c.model}'` : provider;
+}
+/** Build the runtime consult. See {@link BrainFor}. */
+export function buildBrainFor(args) {
+    const strategyFor = (provider) => provider === undefined || provider.name === args.agentProviderName
+        ? args.agentCacheStrategy
+        : getDefaultCacheStrategy(provider.name);
+    const bySkill = new Map();
+    for (const [skillId, choice] of args.brains.bySkill) {
+        bySkill.set(skillId, {
+            provider: choice.provider,
+            ...(choice.model !== undefined && { model: choice.model }),
+            cacheStrategy: strategyFor(choice.provider),
+            via: 'skill',
+            skillId,
+        });
+    }
+    const escalation = args.brains.escalation
+        ? {
+            provider: args.brains.escalation.provider,
+            ...(args.brains.escalation.model !== undefined && {
+                model: args.brains.escalation.model,
+            }),
+            cacheStrategy: strategyFor(args.brains.escalation.provider),
+            via: 'escalation',
+        }
+        : undefined;
+    return (activeCursor, escalated) => {
+        // Evidence outranks the node: once the turn escalated, EVERY remaining
+        // call of the turn runs on the escalation brain, whatever the cursor.
+        if (escalated && escalation !== undefined)
+            return escalation;
+        if (activeCursor === undefined)
+            return undefined;
+        return bySkill.get(activeCursor);
+    };
+}
+/** Describe the brain that WOULD serve a cursor pre-escalation — the
+ *  `skill.escalated` event's honest `from` field, resolved by the same
+ *  precedence chain callLLM applies (skill brain > configured > default). */
+export function describeServingBrain(args) {
+    const brain = args.cursor !== undefined ? args.brains.bySkill.get(args.cursor) : undefined;
+    const provider = brain?.provider?.name ?? args.agentProviderName;
+    const model = brain?.model ?? args.resolvedModel ?? args.defaultModel;
+    return { provider, model };
+}
+//# sourceMappingURL=skillBrains.js.map

package/dist/esm/core/agent/skillBrains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillBrains.js","sourceRoot":"","sources":["../../../../src/core/agent/skillBrains.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/stages/callLLM.d.ts

@@ -90,6 +90,30 @@ export interface CallLLMStageDeps {
      * product is the recording.
      */
     readonly runConfigured?: boolean;
+    /**
+     * "The cursor picks the brain" (9.19.0). Consulted ONCE at the top of the
+     * stage with the ADVANCED cursor — `scope.nextSkillCursor ??
+     * scope.currentSkillId`, correct in BOTH chart shapes: inside
+     * `sf-llm-call` the boundary's `currentSkillId` is a readonly input still
+     * holding the previous iteration's cursor and the advanced one lives
+     * under `nextSkillCursor`; in the flat chart the engine's outputMapper
+     * has already written `currentSkillId` to the advanced value — and with
+     * the run's escalation flag (`scope.skillEscalated`, threaded across the
+     * `sf-llm-call` boundary by the grouped chart's mappers). The result
+     * resolves field by field down the STATED precedence chain:
+     *
+     *   **escalation > per-skill brain > `.configure()` `resolvedModel` >
+     *   build-time default** — `provider = brain?.provider ?? deps.provider`;
+     *   `model = brain?.model ?? (runConfigured ? scope.resolvedModel :
+     *   undefined) ?? deps.model`; `cacheStrategy = brain?.cacheStrategy ??
+     *   deps.cacheStrategy`. A brain naming only a model inherits the agent's
+     *   provider; a foreign provider without a model was refused at build.
+     *
+     * Undefined — no brain declared anywhere — and this stage reads no new
+     * scope key, resolves exactly as before, and `llm_start` keeps its exact
+     * bytes (the additive `brain` field appears only when a rung won).
+     */
+    readonly brainFor?: import('../skillBrains.js').BrainFor;
 }
 /**
  * Build the callLLM stage function. Captures the LLM provider + model

package/dist/esm/core/agent/stages/callLLM.js

@@ -54,12 +54,24 @@ export function buildCallLLMStage(deps) {
         // `scope.messagesInjections` is read by ContextRecorder for
         // observability; the LLM-wire path now reads scope.history directly.
         const iteration = scope.iteration;
+        // "The cursor picks the brain" (9.19.0) — ONE consult, at the top, with
+        // the advanced cursor and the escalation flag. Gated on `deps.brainFor`
+        // so an agent without brains reads no new scope key and resolves on the
+        // exact line it always did.
+        const brain = deps.brainFor
+            ? deps.brainFor((scope.nextSkillCursor ?? scope.currentSkillId), scope.skillEscalated === true)
+            : undefined;
+        const provider = brain?.provider ?? deps.provider;
+        const cacheStrategy = brain?.cacheStrategy ?? deps.cacheStrategy;
         // The model for this run. `.configure()` resolved it at seed and
         // COMMITTED it to scope, so what gets called, what the `llm_start`
         // event reports and what cost is priced against are all one value —
         // the one the trace records. Without `.configure()` this is the
-        // build-time model and scope is never touched.
-        const model = (deps.runConfigured ? scope.resolvedModel : undefined) ?? deps.model;
+        // build-time model and scope is never touched. A winning brain rung
+        // (9.19.0) outranks both — the stated precedence chain.
+        const model = brain?.model ??
+            (deps.runConfigured ? scope.resolvedModel : undefined) ??
+            deps.model;
         // Per-iteration boundary marker (was a dedicated `IterationStart` stage —
         // folded here since emitting is passive observability, not work that needs
         // its own execution stage). Fires FIRST, before the LLM call, so recorders
@@ -102,11 +114,19 @@ export function buildCallLLMStage(deps) {
             : registeredToolSchemas;
         typedEmit(scope, 'agentfootprint.stream.llm_start', {
             iteration,
-            provider: deps.provider.name,
+            provider: provider.name,
             model,
             systemPromptChars: systemPrompt.length,
             messagesCount: messages.length,
             toolsCount: activeToolSchemas.length,
+            // WHICH BRAIN answered (9.19.0) — stamped ONLY when a brain rung won,
+            // so configured/default runs keep byte-identical events.
+            ...(brain !== undefined && {
+                brain: {
+                    via: brain.via,
+                    ...(brain.skillId !== undefined && { skillId: brain.skillId }),
+                },
+            }),
             ...(activeToolSchemas.length > 0 && {
                 tools: activeToolSchemas.map((t) => ({
                     name: t.name,
@@ -135,7 +155,7 @@ export function buildCallLLMStage(deps) {
         // and populated scope.cacheMarkers accordingly. Strategy.prepareRequest
         // is a pass-through for empty markers.
         const cacheMarkers = scope.cacheMarkers ?? [];
-        const cachePrepared = await deps.cacheStrategy.prepareRequest(baseRequest, cacheMarkers, {
+        const cachePrepared = await cacheStrategy.prepareRequest(baseRequest, cacheMarkers, {
             iteration,
             iterationsRemaining: Math.max(0, deps.maxIterations - iteration),
             recentHitRate: scope.recentHitRate,
@@ -167,8 +187,8 @@ export function buildCallLLMStage(deps) {
         const singleProviderCall = async (req, hooks) => {
             let resp;
             let firstChunkFired = false;
-            if (deps.provider.stream) {
-                for await (const chunk of deps.provider.stream(req, providerHooks)) {
+            if (provider.stream) {
+                for await (const chunk of provider.stream(req, providerHooks)) {
                     if (chunk.done) {
                         if (chunk.response)
                             resp = chunk.response;
@@ -182,7 +202,7 @@ export function buildCallLLMStage(deps) {
                     // with its own marker instead of `done: true`, which is why the
                     // refusal says what the terminal chunk looks like.
                     if (typeof chunk.content !== 'string') {
-                        throw new TypeError(`provider '${deps.provider.name}' yielded a stream chunk whose \`content\` is ` +
+                        throw new TypeError(`provider '${provider.name}' yielded a stream chunk whose \`content\` is ` +
                             `${chunk.content === undefined ? 'missing' : `a ${typeof chunk.content}`}. ` +
                             `Every chunk from LLMProvider.stream() is ` +
                             `{ tokenIndex: number, content: string, done: boolean }, and the LAST one is ` +
@@ -213,7 +233,7 @@ export function buildCallLLMStage(deps) {
                 // those are two genuinely billed calls and collapsing them would
                 // hide real double-billing. (That this branch can re-call at all
                 // after a stream is a pre-existing quirk; see MENTAL_MODEL §14.)
-                resp = await deps.provider.complete(req, providerHooks);
+                resp = await provider.complete(req, providerHooks);
             }
             // `'tool-forced'`: the answer arrived as the synthetic tool's ARGUMENTS,
             // so it is moved into `content` and the call is taken off the list here,
@@ -276,7 +296,7 @@ export function buildCallLLMStage(deps) {
         }
         let response;
         if (deps.reliability) {
-            response = await executeWithReliability(scope, llmRequest, deps.reliability, deps.provider, deps.provider.name, model, singleProviderCall, postValidate);
+            response = await executeWithReliability(scope, llmRequest, deps.reliability, provider, provider.name, model, singleProviderCall, postValidate);
             // `executeWithReliability` returns `undefined` when it took the
             // fail-fast path. It already wrote scope state and called
             // `$break(reason)` — `Agent.run()` translates the propagated

package/dist/esm/core/agent/stages/callLLM.js.map

@@ -1 +1 @@
-{"version":3,"file":"callLLM.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"callLLM.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/stages/routeTurn.d.ts

@@ -47,6 +47,7 @@
  * and the README names it.
  */
 import type { TypedScope } from 'footprintjs';
+import type { LLMProvider } from '../../../adapters/types.js';
 import type { AgentState } from '../types.js';
 import type { InjectionContext } from '../../../lib/injection-engine/types.js';
 import type { EntryScoring } from '../../../lib/injection-engine/skillGraph.js';
@@ -69,5 +70,27 @@ export interface RouteTurnDeps {
     /** Which skills the caller's role may not see (9.11.0) — excluded from
      *  candidates, scores, menus and the envelope. Fail-closed inside. */
     readonly hiddenSkillIds?: () => Promise<readonly string[]> | readonly string[];
+    /**
+     * The tier-3 DECIDER (9.19.0) — an out-of-band constrained pick over an
+     * outstanding menu ∪ {stay}, resolved HERE, before the loop, with the
+     * `constrainedEnumPick` machinery (the `llmClassifier` discipline: forced
+     * tool on providers that constrain, strict parse + one re-ask + `'none'`
+     * everywhere else — ids never fabricated). A decisive pick starts the
+     * turn (`turn_routed { by: 'decider' }`, additive); `'stay'` holds the
+     * incumbent (`by: 'continuity'`, decider recorded); `'none'` / parse
+     * failure / a throw leaves the in-band envelope standing, decider
+     * recorded with `picked` absent. Rails × decider is ADMITTED — the
+     * decider is constrained, off-loop and recorded (a scorer in posture
+     * terms), which makes it the sanctioned resolver for rails menus.
+     * Undefined → every menu keeps its exact 9.17 behavior.
+     */
+    readonly decider?: {
+        readonly provider: LLMProvider;
+        readonly model?: string;
+        /** The agent's build-time model — the chain's last rung. */
+        readonly defaultModel: string;
+        /** `.configure()` present — only then is `scope.resolvedModel` read. */
+        readonly runConfigured: boolean;
+    };
 }
 export declare function makeRouteTurnStage(deps: RouteTurnDeps): (scope: TypedScope<AgentState>) => Promise<void>;

package/dist/esm/core/agent/stages/routeTurn.js

@@ -49,7 +49,12 @@
 import { isDevMode } from 'footprintjs';
 import { validateIntentScores } from '../../../lib/injection-engine/intentScorer.js';
 import { decideTier2, } from '../../../lib/injection-engine/routingPolicy.js';
+import { constrainedEnumPick } from '../../../lib/injection-engine/constrainedEnumPick.js';
 import { typedEmit } from '../../../recorders/core/typedEmit.js';
+/** The decider's `'stay'` sentinel — first-class on mid-conversation menus. */
+const DECIDER_STAY = 'stay';
+/** The decider's decline sentinel (the enum machinery's fallback). */
+const DECIDER_NONE = 'none';
 export function makeRouteTurnStage(deps) {
     const plan = deps.turnRouting;
     return async (scope) => {
@@ -88,7 +93,7 @@ export function makeRouteTurnStage(deps) {
                 'Fix the resolver passed to hiddenSkillIds.');
         }
         const visibleEntryIds = plan.entryIds.filter((id) => !hidden.has(id));
-        const verdict = await runCascade(deps, plan, ctx, inherited, hidden, visibleEntryIds, env.signal);
+        let verdict = await runCascade(deps, plan, ctx, inherited, hidden, visibleEntryIds, env.signal);
         if (verdict === undefined && droppedResume === undefined) {
             // Cold start on a continuity graph with no tier 2 at all: the resolver's
             // cold walk decides exactly as it always has — no verdict, no event.
@@ -100,6 +105,59 @@ export function makeRouteTurnStage(deps) {
             scope.entryScores = verdict.scores;
             scope.entryScorer = verdict.scorer;
         }
+        // ── Tier-3 DECIDER (9.19.0) — the out-of-band menu resolver ────────
+        // Runs HERE, off the hot loop, only when a menu verdict is actually
+        // outstanding. A decisive pick starts the turn; 'stay' holds the
+        // incumbent; 'none'/parse-fail/throw leaves the in-band envelope
+        // standing. The consult is ALWAYS recorded on the event (`decider`),
+        // picked or not — a resolver that ran and said nothing is still a fact.
+        let deciderRecord;
+        /** Set when the decider RESOLVED the menu — the menu is then no longer
+         *  outstanding, so the scope POJO carries no `offered` (the rails
+         *  what-happened vs what-the-loop-may-act-on split, reused). */
+        let deciderResolved;
+        if (deps.decider !== undefined &&
+            verdict !== undefined &&
+            verdict.by === 'menu' &&
+            verdict.offered !== undefined &&
+            verdict.offered.length > 0) {
+            // The precedence chain's model rung, for the decider's own call:
+            // declared > `.configure()` resolvedModel > build-time default.
+            const deciderModel = deps.decider.model ??
+                (deps.decider.runConfigured ? scope.resolvedModel : undefined) ??
+                deps.decider.defaultModel;
+            const stayAllowed = verdict.stayOffered === true && inherited !== undefined;
+            const picked = await runDecider({
+                provider: deps.decider.provider,
+                model: deciderModel,
+                plan,
+                userMessage: ctx.userMessage,
+                offered: verdict.offered,
+                stayAllowed,
+                inherited,
+                signal: env.signal,
+            });
+            deciderRecord = {
+                provider: deps.decider.provider.name,
+                model: deciderModel,
+                ...(picked !== undefined && { picked }),
+            };
+            if (picked !== undefined && picked !== DECIDER_STAY) {
+                // Decisive pick: the turn starts there. `offered` stays on the
+                // VERDICT (the event keeps the full menu); the POJO below drops it.
+                verdict = { ...verdict, by: 'decider', to: picked };
+                deciderResolved = 'move';
+            }
+            else if (picked === DECIDER_STAY) {
+                // STAY is a resolution too: the incumbent holds AND the menu closes
+                // — the scope TurnRoute carries no `offered` while the event keeps
+                // the full offered set (nice-6; guard's `menuOutstanding` then
+                // refuses late picks against a menu the decider already answered).
+                verdict = { ...verdict, by: 'continuity', to: inherited };
+                deciderResolved = 'stay';
+            }
+            // picked === undefined → the in-band envelope stands, decider recorded.
+        }
         const policy = plan.policy;
         const effectiveFloor = policy.floor ?? plan.scorer?.floor;
         // Rails × menu: the model may not act on it — record the offer, act on none.
@@ -122,6 +180,7 @@ export function makeRouteTurnStage(deps) {
             },
             ...(verdict?.window !== undefined && { window: verdict.window }),
             ...(droppedResume !== undefined && { droppedResume }),
+            ...(deciderRecord !== undefined && { decider: { ...deciderRecord } }),
         });
         // The POJO the LOOP acts on — the resolver's iteration-1 input, the
         // envelope's source, the guard gate's window. Under rails a menu carries
@@ -133,13 +192,23 @@ export function makeRouteTurnStage(deps) {
         // untouched, or the drop would silently strand the turn on no entry.
         if (verdict === undefined)
             return;
+        // A decider-RESOLVED menu (move OR stay) is no longer outstanding: the
+        // POJO carries no `offered`, so the envelope composes none and `guard`'s
+        // `menuOutstanding` goes false — while the event above kept the full
+        // offered set. Same split rails ships; one more case earns it.
+        const menuStillOutstanding = deciderResolved === undefined;
         const turnRoute = {
             by: eventBy,
             ...(inherited !== undefined && { from: inherited }),
             ...(verdict.to !== undefined && { to: verdict.to }),
-            ...(!rails && verdict.offered !== undefined && { offered: [...verdict.offered] }),
-            ...(!rails && verdict.stayOffered !== undefined && { stayOffered: verdict.stayOffered }),
             ...(!rails &&
+                menuStillOutstanding &&
+                verdict.offered !== undefined && { offered: [...verdict.offered] }),
+            ...(!rails &&
+                menuStillOutstanding &&
+                verdict.stayOffered !== undefined && { stayOffered: verdict.stayOffered }),
+            ...(!rails &&
+                menuStillOutstanding &&
                 verdict.offered !== undefined &&
                 verdict.scores !== undefined && {
                 relevance: verdict.scores.map((s) => ({ id: s.id, relevance: s.relevance })),
@@ -292,6 +361,57 @@ function menuVerdict(offered, stayOffered, scorerName, window) {
         ...(window !== undefined && { window }),
     };
 }
+/**
+ * The tier-3 decider's one constrained call (9.19.0). Candidates project
+ * from the offered entries' declared intents, else their descriptions —
+ * `plan.incumbentCandidate` is the one projection that already does exactly
+ * that, so ids are never fabricated. `'stay'` joins the enum only on a
+ * mid-conversation menu. Returns the picked id / `'stay'`, or `undefined`
+ * when the decider declined (`'none'`, a parse failure after the one
+ * re-ask, or a throw — dev-warned): a decider is a tier, never a
+ * correctness dependency, so the in-band envelope stands.
+ */
+async function runDecider(args) {
+    const lines = args.offered.map((id) => {
+        const candidate = args.plan.incumbentCandidate(id);
+        return `- ${candidate.id}: ${candidate.intent}`;
+    });
+    if (args.stayAllowed) {
+        lines.push(`- ${DECIDER_STAY}: continue the current skill '${args.inherited}'`);
+    }
+    const allowed = [...args.offered, ...(args.stayAllowed ? [DECIDER_STAY] : []), DECIDER_NONE];
+    const systemPrompt = `You route ONE user message to a skill from a fixed menu.\n` +
+        `Menu:\n${lines.join('\n')}\n\n` +
+        `Pick the single id that should handle the message. If genuinely none fits, pick ` +
+        `'${DECIDER_NONE}'. Never invent an id.`;
+    try {
+        const picked = await constrainedEnumPick({
+            provider: args.provider,
+            model: args.model,
+            systemPrompt,
+            messages: [{ role: 'user', content: args.userMessage }],
+            allowed,
+            fallback: DECIDER_NONE,
+            pickTool: {
+                name: 'pick_skill',
+                description: `Report which menu skill should handle the user's message ('${DECIDER_NONE}' if none).`,
+                argName: 'skill',
+                argDescription: 'The picked skill id.',
+            },
+            ...(args.signal !== undefined && { signal: args.signal }),
+        });
+        return picked === DECIDER_NONE ? undefined : picked;
+    }
+    catch (err) {
+        if (isDevMode()) {
+            // eslint-disable-next-line no-console
+            console.warn(`agentfootprint RouteTurn: the routing decider threw — the menu stands and the ` +
+                `in-band envelope resolves it (recorded: turn_routed.decider with no pick). ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+        return undefined;
+    }
+}
 /** The prior conversational turns a windowed scorer sees — user/assistant
  *  roles only, the CURRENT user message excluded, newest last. */
 function recentTurnsOf(history, window) {