@try-works/dsh-recursive-mode 0.3.1 → 0.4.0

package/lib/recursive_delegate.tool.d.ts

@@ -0,0 +1,22 @@
+import type { RecursiveRuntime } from './runtime.ts';
+import type { SubagentsRuntimeLike } from './delegation.ts';
+/**
+ * ⚠ FU-17 — THE WORK TOOL FILTER, AND WHY IT IS A DENY LIST RATHER THAN AN ALLOW LIST.
+ *
+ * `delegateReview` applies `input.toolFilter ?? defaultReviewToolFilter()` and that default is
+ * `{ allow: ['fs_read', 'grep', 'glob'] }`. So a work delegation that passes nothing receives a child that
+ * cannot write — and nothing about the outcome would say so.
+ *
+ * The obvious fix is an allow list of the writing tools, and it is the wrong one: it has to name EVERY tool a
+ * worker might need (`bash`, `pwsh`, `str_replace_editor`, `session_search`, `session_event_read`, `skill`,
+ * `load_workspace_dependencies`, `present`, …) and it SILENTLY REMOVES capability for each name forgotten.
+ * That is the same defect class this project has already fixed ten times: a surface that cannot express what
+ * the system can do, failing quietly.
+ *
+ * `deny` states the actual posture instead: a delegated worker may use everything EXCEPT spawning its own
+ * children and driving the team board. That is what the workflow wants — no recursive fan-out from a worker and
+ * no contention over the audit board — and it cannot lose a tool by omission. The host accepts `allow` and/or
+ * `deny` (`subagent/src/descriptor.ts`), throwing only when neither is declared.
+ */
+export declare const WORK_TOOL_FILTER: unknown;
+export declare function createRecursiveDelegateTool(recursive: RecursiveRuntime, subagents?: SubagentsRuntimeLike): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/recursive_preview.tool.d.ts

@@ -0,0 +1,48 @@
+import type { EnforcementConfig } from './enforcement.ts';
+import type { RecursiveRuntime } from './runtime.ts';
+/** A tool call the caller wants to preview the guard's decision for. */
+export interface PreviewProbe {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+export interface PreviewResult {
+    /** T22: the byte-identical prefix, the per-phase tail, and the local identifier. */
+    policy: {
+        stable: string;
+        tail: string;
+        digest: string;
+    };
+    /** What the phase being worked on requires, from the same rules the linter enforces. */
+    phase: {
+        file: string;
+        requiredSections: string[];
+        audited: boolean;
+        tdd: boolean;
+        qa: boolean;
+    } | null;
+    /** The next legal transition, or null when nothing is pending. */
+    next: {
+        phase: string;
+        requiredSections: string[];
+    } | null;
+    /** What the guard WOULD decide for a probe call — the rule that would fire, by name. */
+    probe: {
+        kind: string;
+        rule: string;
+        reason?: string;
+    } | null;
+}
+/**
+ * Build the preview. Pure apart from the run-directory reads it is given.
+ *
+ * `next` is `null` for a completed run rather than a fabricated phase: "nothing is pending" is a fact
+ * a reader needs, and inventing the last phase as "next" would be the opposite of a preview.
+ */
+export declare function buildPreview(input: {
+    root: string;
+    runId: string;
+    config: EnforcementConfig;
+    probe?: PreviewProbe;
+}): PreviewResult;
+/** `recursive_preview` — the read-only view, registered as a tool so it is one call away. */
+export declare function createRecursivePreviewTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/recursive_review.tool.d.ts

@@ -0,0 +1,28 @@
+import type { RecursiveRuntime } from './runtime.ts';
+import type { ContinuableDelegationLike, SubagentsRuntimeLike } from './delegation.ts';
+export declare function createRecursiveReviewTool(recursive: RecursiveRuntime, subagents?: SubagentsRuntimeLike): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The child's reply file, or '' when it has not written one (an empty reply is not an approval). */
+export declare function readReplyText(root: string, runId: string, delegationId: string, childId: string): string;
+/**
+ * Project `delegateReview`'s result onto the loop shape the driver reads.
+ *
+ * The mapping is where the honest failure modes live: no continuable result at all
+ * (self-audit, or the delegation never ran) becomes `fellBackToOneShot`, which the
+ * driver reports as `unavailable` — the review happened without the repair path, and
+ * saying so beats reporting a success that cannot be acted on.
+ */
+export declare function toContinuable(review: {
+    continuable: {
+        rounds: unknown[];
+        childId?: string;
+        fellBackToOneShot?: boolean;
+        parked?: boolean;
+        ok?: boolean;
+        reason?: string;
+    } | null;
+    evaluation?: {
+        accepted?: boolean;
+    };
+    error?: string | null;
+    parked?: boolean;
+}): ContinuableDelegationLike;

package/lib/result-cap.d.ts

@@ -0,0 +1,70 @@
+/**
+ * T24 — bounded tool results.
+ *
+ * A linter over a 126 KB port can emit hundreds of findings, and `recursive_lint`
+ * returned `errors[]`/`warnings[]` unbounded, so a single tool result could grow
+ * without limit. Every result this plugin returns must be BOUNDED, and when a
+ * bound bites it must say so in a way the reader can act on:
+ *
+ *   - WHAT was removed (which list, how many),
+ *   - what is SHOWN, and
+ *   - HOW to see the rest.
+ *
+ * A silent truncation is worse than no cap at all: the reader cannot tell a
+ * complete result from a clipped one. Hence {@link ElisionMeta} accompanies every
+ * truncation, and the caller surfaces it next to the findings.
+ *
+ * The "how to see the rest" route is deliberately ITERATIVE rather than a
+ * bypass argument: the cap is a hard bound, so telling the caller to pass
+ * `mode: 'full'` when `mode: 'full'` is already the capped mode would be a lie.
+ * Fixing the shown findings and re-running genuinely reveals the next batch,
+ * which is also the order the workflow wants them fixed in.
+ */
+/** Findings kept by `mode: 'full'`. */
+export declare const MAX_FINDINGS_FULL = 200;
+/** Findings kept by `mode: 'summary'` — enough to orient, not enough to drown a turn. */
+export declare const MAX_FINDINGS_SUMMARY = 10;
+export interface ElisionMeta {
+    /** Which list was clipped. */
+    kind: 'errors' | 'warnings';
+    /** Findings the source produced. */
+    total: number;
+    /** Findings actually returned. */
+    shown: number;
+    /** `total - shown`; stated so a consumer need not compute it. */
+    omitted: number;
+    /** One self-sufficient sentence: what was removed and how to see it. */
+    hint: string;
+}
+export interface ElideResult {
+    kept: string[];
+    /** Present only when the list was clipped. */
+    meta: ElisionMeta | null;
+}
+/** The payload shape the byte budget knows how to trim. */
+export interface CappedPayload {
+    errors: string[];
+    warnings: string[];
+    elided: ElisionMeta[];
+}
+/** Serialized size of a payload, measured the way the byte budget is enforced. */
+export declare function payloadBytes(value: unknown): number;
+/**
+ * T28 — cap a payload by BYTES, which T24's count cap cannot do.
+ *
+ * `MAX_FINDINGS_FULL` bounds HOW MANY findings come back; it cannot see SIZE, so a
+ * handful of enormous findings still passes. This trims the longer list repeatedly
+ * until the payload fits, and reports every trim through the same `ElisionMeta` T24
+ * established — a silent truncation is worse than no cap, because the reader cannot
+ * tell a complete result from a clipped one.
+ *
+ * Terminates: each pass at least halves the longer list, and an empty pair of lists
+ * ends the loop. A payload that still exceeds the budget once both lists are empty is
+ * returned as-is — the alternative would be deleting fields the caller needs.
+ */
+export declare function capPayloadBytes<T extends CappedPayload>(payload: T, maxBytes: number): T;
+/**
+ * Keep at most `max` findings. Clipping is reported, never silent.
+ * A `max` of 0 or less is treated as "keep nothing" but still reports honestly.
+ */
+export declare function elideFindings(kind: 'errors' | 'warnings', findings: readonly string[], max: number): ElideResult;

package/lib/review-round.d.ts

@@ -0,0 +1,82 @@
+import { type ContinuableDelegationLike, type DelegationVerdict } from './delegation.ts';
+/** The durable record of an in-flight review, so the next turn can resume it. */
+export interface ReviewState {
+    delegationId: string;
+    /** The durable child carrying this review, stable across turns. */
+    childId: string;
+    phase: string;
+    role: string;
+    /** How many rounds the loop has observed so far. */
+    rounds: number;
+    startedAt: string;
+    lastVerdict?: DelegationVerdict;
+    /**
+     * ⚠ FU-17 — whether this round carries a VERDICT (`review`) or a DELIVERABLE (`work`). Optional and defaulted
+     * on read, so a state file written before this field existed still means what it always meant.
+     */
+    kind?: 'review' | 'work';
+}
+export interface AdvanceReviewOutcome {
+    status: 'reviewing' | 'revised' | 'approved' | 'rejected' | 'unavailable' | 'submitted';
+    childId?: string;
+    verdict?: DelegationVerdict;
+    rounds: number;
+    /** One sentence for the agent, saying what to do next. */
+    message: string;
+}
+/** Where one delegation's review state lives (beside its handoff and replies). */
+export declare function reviewStatePath(runDir: string, delegationId: string): string;
+/** Read an in-flight review, or null when there is none (or it is unreadable). */
+export declare function readReviewState(runDir: string, delegationId: string): ReviewState | null;
+export declare function writeReviewState(runDir: string, state: ReviewState): string;
+/** Forget a finished review. A finished review must not be resumable by accident. */
+export declare function clearReviewState(runDir: string, delegationId: string): void;
+/**
+ * Advance one review by exactly one turn.
+ *
+ * `delegate` is injected rather than called directly so this driver can be tested
+ * against a scripted loop, and so the caller owns how the review is dispatched
+ * (which provider, which bundle, which parent). It receives `resumeChild` when a
+ * child is already carrying the review — a resumed round must NEVER re-establish
+ * the child, which would orphan the one already doing the work.
+ */
+export declare function advanceReview(input: {
+    runDir: string;
+    delegationId: string;
+    phase: string;
+    role: string;
+    /** Dispatch one turn of the continuable loop, resuming `resumeChild` when given. */
+    delegate: (args: {
+        resumeChild?: string;
+    }) => Promise<ContinuableDelegationLike>;
+    /** The child's reply text for the settled round, or '' when it has not written one. */
+    readReply: (childId: string) => string;
+    /**
+     * Deliver a repair instruction to the child.
+     *
+     * NEEDED BECAUSE THE LOOP CAN STOP EARLY ON A MISREAD. The loop's own verdict
+     * reader falls back to APPROVE when a result carries no structured verdict, so a
+     * child that answered in prose can make the loop believe it was approved and
+     * END — leaving no repair sent and the child idle. This driver re-reads the reply
+     * fail-closed and disagrees, so it must be able to send the repair itself;
+     * otherwise the round would sit in `revised` forever with nothing ever asking the
+     * child to fix anything.
+     */
+    sendRepair?: (childId: string, instruction: string) => Promise<void>;
+    now?: () => string;
+    /**
+     * ⚠ FU-17 — WHICH KIND OF ROUND THIS IS, and it defaults to `'review'`.
+     *
+     * The kind is a PARAMETER rather than a forked code path, so every existing caller and spec keeps the exact
+     * behaviour it had — that is what makes "review is unchanged" a proof instead of a hope. A `'work'` round is
+     * the same round: same child, same state file, same park-and-resume mechanics, same repair delivery. The one
+     * difference is what a settlement MEANS: a work round's settlement is a DELIVERABLE, so the driver must not
+     * read an APPROVE out of prose that was never a verdict.
+     */
+    kind?: 'review' | 'work';
+    /**
+     * The main agent's feedback for a `'work'` round — delivered to the SAME child, which then repairs with its
+     * working set intact. Ignored for reviews, whose repair text is read from the reviewer's own reply.
+     */
+    instruction?: string;
+}): Promise<AdvanceReviewOutcome>;

package/lib/review.d.ts

@@ -19,6 +19,15 @@ export interface ReviewBundleInput {
     addenda?: string[];
     priorEvidence?: string[];
     memoryRefs?: string[];
+    /**
+     * T14 — the RETRIEVED prior-run memory, rendered, written into the bundle body.
+     *
+     * ⚠ `memoryRefs` above is the slot the bundle already had, and nothing ever filled it — so the
+     * memory section a reviewer was supposed to see did not exist. The two are complementary, not
+     * duplicates: `memoryRefs` is WHERE the memory lives (traceability), and this is the CONTENT,
+     * because a reviewer cannot cite a path whose contents it was never given.
+     */
+    memory?: string;
     changedFiles?: string[];
 }
 export interface ReviewBundleResult {

package/lib/role-route.d.ts

@@ -0,0 +1,122 @@
+/**
+ * T9 → FU-19 — per-role model routing, and now a full provider/model ladder.
+ *
+ * WHY. A delegation would otherwise run on whatever model the child inherits: the reviewer that must be rigorous
+ * and the repairer that will iterate many times become the same choice by accident. The item asks for them to
+ * differ — and FU-19 extends that to a general default, per-phase overrides, and a per-call choice.
+ *
+ * ⚠ THE PARAGRAPH THAT USED TO BE HERE WAS TRUE WHEN WRITTEN AND IS NOW FALSE, so it is replaced rather than
+ * left to mislead. It said the plugin "cannot by itself force a child onto a model", because
+ * `SubagentStartRequestLike` had no model field and model selection was the host's concern. Both halves changed:
+ * the harness accepts `agentOptions` on a start, and `delegateReview` now sets `request.agentOptions = { model }`
+ * — but ONLY for a provider that declares the `agentOptions` capability, because the harness REJECTS such a start
+ * otherwise.
+ *
+ * SO WHAT THIS MODULE PROMISES TODAY, precisely:
+ *   - it resolves WHICH provider and model a child should get, from the ladder in `resolveSubagentTarget`, and it
+ *     reports which level chose each value;
+ *   - the caller (not this module) applies them, because applying is a decision with consequences — a model on a
+ *     provider that cannot take overrides is NOT applied and is REPORTED rather than silently dropped;
+ *   - and the model is checked against what DSH actually has (`model-inventory.ts`), with an `unverified` verdict
+ *     when there is no inventory to ask, so a choice is never silently approved OR silently replaced.
+ *
+ * A module that claimed more than that would be lying about where the choice is made. The comment above is the
+ * second half of that lesson: a stale rationale is how a working feature gets deleted by accident.
+ */
+import type { RouterPolicy } from './router.ts';
+/** What kind of work a role does — the distinction the item is about. */
+export type RoleKind = 'review' | 'repair' | 'unknown';
+export declare function roleKindOf(role: string): RoleKind;
+/** One role's resolved route: what kind of work it is, and which model the policy names. */
+export interface RoleRoute {
+    role: string;
+    kind: RoleKind;
+    /** The policy's model for this role, or null when it names none. */
+    model: string | null;
+    /** Where the model came from — `unset` is a fact worth carrying, not an absence. */
+    source: 'policy' | 'unset';
+    /** One self-sufficient sentence, including the unknown-role case. */
+    reason: string;
+}
+/**
+ * Resolve a role's route from the policy.
+ *
+ * Never throws and never invents a model: an unknown role, an unconfigured role and a role whose
+ * policy entry names no model each produce a route with a reason that says which it is. A caller
+ * that wants to refuse an unknown role can; a caller that wants to proceed knows exactly what it
+ * is proceeding with.
+ */
+export declare function routeForRole(role: string, policy: RouterPolicy): RoleRoute;
+/**
+ * The model the caller should use for a role, or null to inherit.
+ *
+ * A one-line convenience for a caller that only needs the value; {@link routeForRole} is what a
+ * caller should use when it wants to SAY why.
+ */
+export declare function modelForRole(role: string, policy: RouterPolicy): string | null;
+/**
+ * ⚠ FU-19 — WHICH PROVIDER AND MODEL A DELEGATED CHILD WOULD ACTUALLY GET, AND WHO CHOSE EACH.
+ *
+ * ## The words, because they were doing too much work
+ *
+ * "Provider" is the thing that CREATES a child. In this harness it is resolved by a tier ladder, and the tiers
+ * have names that are not self-explanatory:
+ *
+ *   - **native** — a provider the harness runs ITSELF, in-process. It is what `ctx.subagents` serves; in the
+ *     session I measured it advertised exactly two: `spawn` and `fork`. "Native" means "the harness's own",
+ *     as opposed to something it shells out to.
+ *   - **external-cli** — a registered provider that drives a SEPARATE installed program (Codex, Claude Code and
+ *     friends). A child still exists, but the work happens in another process the user installed.
+ *   - **self-audit** — no child is created at all: the main agent reviews its own work. This is the honest
+ *     fallback, and it is NAMED rather than hidden.
+ *   - **local-controller** — the host's own controller. I have not measured this tier's behaviour in a live
+ *     session, so I will not describe it further here.
+ *
+ * ## Why "a provider but no model" — the part my earlier wording got wrong
+ *
+ * A MODEL CAN BE LEFT UNSET ON PURPOSE, AND THAT IS NOT THE SAME AS "NO MODEL". Absent means **inherited**: the
+ * plugin sends no `agentOptions.model` at all, and the child runs on whatever the session/provider default is.
+ * That is the measured behaviour — `delegation.ts` forwards `agentOptions` only when the caller supplies them,
+ * and `modelForRole` returns null precisely to mean "inherit".
+ *
+ * So the floor of the ladder is not a gap. A child cannot exist without a provider, so a provider is always
+ * resolved (by the ladder, or by the user); a model is only sent when someone actually chose one, because
+ * inventing one would silently override the session's own setting — and overriding a user's session default
+ * without being asked is worse than inheriting it.
+ *
+ * ## The precedence, and the labels it reports
+ *
+ *   per-call override  →  phase route  →  role route  →  general default  →  inherit
+ *
+ * Every value carries the label of the level that produced it, so "why did this child run on that model?" is
+ * answerable from the decision alone rather than by reading this function.
+ */
+export interface SubagentTarget {
+    role: string;
+    /** The provider that would create the child, or null when nothing resolved one. */
+    provider: string | null;
+    /** The model to ask for, or null meaning INHERIT — do not send `agentOptions.model` at all. */
+    model: string | null;
+    /** Plain-language provenance for each value: which level chose it. */
+    chosen: {
+        provider: string;
+        model: string;
+    };
+    /** One sentence a reader can act on. */
+    reason: string;
+}
+/** Which level produced a value. `inherit` is a decision, not an absence. */
+export type ChoiceSource = 'per-call' | 'phase' | 'role' | 'general' | 'ladder' | 'inherit';
+export declare function resolveSubagentTarget(input: {
+    role: string;
+    /** The phase the delegation is for, when it is known — the narrowest configured level. */
+    phase?: string;
+    policy: RouterPolicy;
+    /** A per-call override from the tool: wins over every configured level. */
+    override?: {
+        provider?: string | null;
+        model?: string | null;
+    };
+    /** What the tier ladder resolved. Used when no level named a provider, and labelled as the ladder's. */
+    ladderProvider?: string | null;
+}): SubagentTarget;

package/lib/router.d.ts

@@ -1,3 +1,33 @@
+/**
+ * ⚠ FU-19 — WHAT A CHILD RUNS ON, WHEN THE USER SAYS SO AND NOTHING MORE SPECIFIC DOES.
+ *
+ * Optional on purpose, and the reason is the same one the override layer gives below: an absent field must mean
+ * "defer to the next level in the precedence", never "reset to nothing". A default here would make every field
+ * present and silently shadow the role routes and phase routes forever.
+ */
+export interface SubagentDefault {
+    /** The SUBAGENT provider — who creates the child (`spawn`, `fork`). NOT the LLM provider; see below. */
+    provider?: string | null;
+    /** The model id to ask for. */
+    model?: string | null;
+    /**
+     * ⚠ THE LLM PROVIDER — WHO SERVES THE MODEL (`deepseek-official`), which is a DIFFERENT thing from the
+     * `provider` field above. Conflating the two was a real defect in this feature's first schema: a plain
+     * `provider` could mean either, and a user setting it had no way to know which.
+     *
+     * Optional: when only a model is named, the plugin looks its provider up from the inventory DSH exposes.
+     */
+    modelProvider?: string | null;
+}
+/** Per-phase overrides — the narrowest level, and the one that answers "this phase needs a stronger model". */
+export interface PhaseRoute {
+    role?: string;
+    /** The subagent provider, as above. */
+    provider?: string | null;
+    model?: string | null;
+    /** The LLM provider serving `model`, as above. */
+    modelProvider?: string | null;
+}
 export interface RouterDefaults {
     when_role_unconfigured: string;
     when_cli_unavailable: string;
@@ -5,18 +35,32 @@ export interface RouterDefaults {
     allow_auto_assign_if_single_cli: boolean;
     probe_timeout_ms: number;
     invoke_timeout_ms: number;
+    /** FU-19: the general provider/model for delegated subagents, absent when the user has not chosen one. */
+    subagent?: SubagentDefault;
 }
 export interface RoleRoute {
     enabled: boolean;
     mode: string;
     cli: string | null;
     model: string | null;
+    /**
+     * FU-19: the provider this role should be served by, when the user has chosen one. Absent means "let the tier
+     * ladder decide", which is what every policy scaffolded before this field did.
+     *
+     * This is the SUBAGENT provider — who creates the child. The LLM provider that serves the model is its own
+     * field below, because one name for two ideas is how a configuration becomes a guess.
+     */
+    provider?: string | null;
+    /** FU-19: the LLM provider serving this role's `model`. Optional; looked up from the inventory when omitted. */
+    modelProvider?: string | null;
     fallback: string;
 }
 export interface RouterPolicy {
     version: number;
     defaults: RouterDefaults;
     role_routes: Record<string, RoleRoute>;
+    /** FU-19: phase-keyed overrides, e.g. `{ '08': { role: 'memory-auditor' } }`. Absent means none. */
+    phase_routes?: Record<string, PhaseRoute>;
     cli_overrides: Record<string, unknown>;
     custom_clis: unknown[];
 }
@@ -25,6 +69,25 @@ export interface RouteDecision {
     tier: RouteTier;
     provider?: string;
     reason: string;
+    /**
+     * T9: the model the policy names for this role, or null when it names none.
+     *
+     * Present on EVERY decision because it is attached by the wrapper, never per-return-site.
+     *
+     * ⚠ THIS COMMENT USED TO SAY THE PLUGIN DOES NOT APPLY IT. That was true when it was written and is false now:
+     * `delegateReview` sets `request.agentOptions = { model }` when the provider declares the `agentOptions`
+     * capability, and reports a routing note when it does not. So this is still a value a caller can HONOUR, but
+     * the plugin now does the honouring — and says so when it cannot.
+     */
+    model?: string | null;
+    /**
+     * FU-19: where the provider and model came from, one short label per value, so "why did this child run on
+     * that model" is answerable without reading the resolution code.
+     */
+    chosen?: {
+        provider?: string;
+        model?: string;
+    };
 }
 export interface SubagentProviderLike {
     name: string;
@@ -33,6 +96,12 @@ export interface SubagentProviderLike {
         depthLimit?: boolean;
         toolFilter?: boolean;
         persona?: boolean;
+        /**
+         * T9: whether this provider accepts `agentOptions` (provider/model/reasoning-effort
+         * overrides). The harness REJECTS a start that sends them to a provider without this
+         * capability, so the caller must ASK rather than assume — see `delegateReview`.
+         */
+        agentOptions?: boolean;
     };
 }
 export interface CapabilityProbe {
@@ -46,15 +115,31 @@ export interface CapabilityProbe {
     };
     reason: string;
 }
+/**
+ * T7 — the settings OVERRIDE layer over the declarative file.
+ *
+ * ONE PATH, NOT TWO (the item's own interaction note): `recursive-router.json` remains the
+ * declarative source, and the settings namespace can OVERRIDE individual fields without
+ * restating the file. That is why every field here is optional and why the schema declares
+ * NO defaults for them: an absent field means "defer to the file", and a default would make
+ * every field present and silently shadow the file forever.
+ */
+export interface RouterPolicyOverrides {
+    defaults?: Partial<RouterPolicy['defaults']>;
+}
 /** Parse recursive-router.json. A missing/invalid file yields a default self-audit policy (never throws). */
-export declare function loadRouterPolicy(path?: string): RouterPolicy;
+export declare function loadRouterPolicy(path?: string, overrides?: RouterPolicyOverrides): RouterPolicy;
 /** Default router policy path inside a workspace root. */
 export declare function routerPolicyPath(root: string): string;
 /**
- * Resolve a role to a tier, preferring a native provider whose name maps to
- * the role (e.g. role 'code-reviewer' -> provider 'code-reviewer' or the
- * generic spawn/fork provider). External CLIs ride their provider rows; else
- * the policy fallback.
+ * T9 — attach the role's model to the decision.
+ *
+ * ⚠ WHY A WRAPPER AND NOT SIX EDITS. `resolveRoleInner` has six return sites, and adding the
+ * model to each would leave a decision shape that carries it on some paths and not others — a
+ * trap for the next reader, and exactly the kind of quiet inconsistency this plan keeps
+ * refusing to ship. Attaching it ONCE, at the seam where the decision leaves, makes the field
+ * present on EVERY path by construction. The policy lookup itself lives in `role-route.ts`
+ * (`routeForRole`), so there is one definition of "which model does this role use", not two.
  */
 export declare function resolveRole(role: string, policy: RouterPolicy, providers: Record<string, SubagentProviderLike>): RouteDecision;
 /** Probe a single provider and return its advertised capabilities. */