dsh-llm-fallbacks 0.6.13 → 0.7.0

package/dist/role-resolution.d.ts

@@ -2,7 +2,7 @@
  * Dispatch-time role resolution (plan fallbacks-role-automatch Task 2; the
  * dispatch-role stage added by plan dsh-148-agent-team-role-delivery Task 1).
  *
- * Precedence (first hit wins) across four ordered stages:
+ * Precedence (first hit wins) across three ordered stages:
  * 1. explicit — `session.header.agentPreset` trimmed matches a declared role
  *    id → that role's DECLARED RAW id (via the `roleIds` trimmed-id map, the
  *    same canonicalization the rules path uses); the reserved `'inherit'`
@@ -16,51 +16,30 @@
  *    not an error;
  * 3. rules — the existing `resolveRole` passthrough, unchanged (a declared
  *    role wins; no-rule-match / an explicit rule targeting `'inherit'`
- *    resolve to `'inherit'`);
- * 4. auto-match — only when stage 3 resolved to `'inherit'` AND
- *    `opts.automatchEnabled`: call `opts.automatch` with the agent. The hook
- *    (Task 3 supplies the bounded LLM caller) MUST return a declared raw id
- *    or `null`; the resolver defensively validates the return against
- *    `roleIds` — an unknown id warns and resolves to `'inherit'`, never an
- *    undeclared role. When `automatch` is undefined or `automatchEnabled`
- *    is false the hook is skipped.
+ *    resolve to `'inherit'`).
  *
  * `'inherit'` is the single "no specific role" outcome — reached by
- * no-rule-match OR an explicit rule targeting `'inherit'` — and both are
- * auto-match eligible when enabled. An operator who wants a class to never
- * auto-match sets `roleAutoMatch: false` (→ `automatchEnabled: false`).
+ * no-rule-match OR an explicit rule targeting `'inherit'`.
  *
- * Pure ordering logic: no config object and no LLM service inside this
- * module — the LLM is an injectable hook owned by Task 3/4.
+ * There is deliberately NO auto-match stage: the only host point it ever had
+ * was the deleted `agent/request` inject, and running an LLM call inside the
+ * walk's `stream()` would be a nested request per failure (design
+ * dsh-022-rc1-upgrade §2.2). Resolution is therefore pure and synchronous —
+ * the walk must throw its pre-attempt errors before the first chunk.
  *
  * @module dsh-llm-fallbacks/role-resolution
  */
 import { type FallbacksRoleRule } from './config.ts';
 import { type AgentLike } from './roles.ts';
-import type { Selector } from './selectors.ts';
 export type { FallbacksRoleRule } from './config.ts';
-/** Options for {@link resolveRoleAtDispatch}. */
-export interface ResolveRoleAtDispatchOptions {
+/** Options for {@link resolveDeclaredRole}. */
+export interface DeclaredRoleOptions {
     /**
      * Dispatch-declared role: the DECLARED RAW id the seam resolved from the
      * Assignment/teammate prompt (`**Execute as**: <id>`). Validated against the
      * live `roleIds` map; absent, `inherit`, or no-longer-declared → skipped.
      */
     dispatchRole?: string;
-    /**
-     * Whether the auto-match stage may run (the `roleAutoMatch` config switch).
-     * When `false`, stage 4 never runs and the outcome is identical to the
-     * explicit/dispatch/rules stages alone.
-     */
-    automatchEnabled: boolean;
-    /**
-     * Auto-match hook — Task 3 supplies the bounded LLM caller; the resolver
-     * itself contains no LLM. Contract: given the agent being resolved, return
-     * a declared raw role id or `null`. The resolver defensively validates the
-     * return against `roleIds` — an unknown id warns and resolves to
-     * `'inherit'`, never an undeclared role. Skipped when undefined.
-     */
-    automatch?: (agent: AgentLike) => Promise<string | null>;
     /** Warning sink — the decision path injects the plugin logger. */
     warn: (message: string) => void;
     /**
@@ -76,11 +55,7 @@ export interface ResolveRoleAtDispatchOptions {
     };
 }
 /**
- * Resolve the dispatch-time role for an agent across four ordered stages
- * (explicit → dispatch → rules → auto-match hook). Never throws on its own
- * inputs; the hook's own rejection is deliberately NOT caught here (the
- * Task-3/4 wiring bounds the LLM call so it never throws out of the request
- * path).
+ * The dispatch role: explicit → dispatch-declared → rules.
  *
  * `roleIds` is the canonical trimmed-id map (`trimmed id → declared raw id`,
  * built in `src/index.ts` apply()): every stage canonicalizes its reference
@@ -88,18 +63,4 @@ export interface ResolveRoleAtDispatchOptions {
  * `chains.ts` / `commands.ts` find the stored `roles.list[]` entry exactly
  * (qc2 F-001 — no silent role inertness on padded YAML ids).
  */
-export declare function resolveRoleAtDispatch(agent: AgentLike, rules: FallbacksRoleRule[], roleIds: ReadonlyMap<string, string>, opts: ResolveRoleAtDispatchOptions): Promise<string>;
-/**
- * The dispatch-time chain head (plan fallbacks-role-automatch Task 4): the
- * FIRST candidate of a `resolveChainViews` pass whose `wildcard` flag is
- * false — an exact `provider/model` entry. `provider/*` entries are NOT
- * dispatch injection targets (no failing model to anchor them; a guessed
- * injection risks a hard failure whose code may sit outside `triggerCodes`),
- * so a wildcard-only chain yields `undefined` → no injection (today's
- * behavior). No cooldown/failed filtering and no existence probe run here —
- * a fresh subagent's first request has no failure-scoped state (see the Task
- * 4 decision) and exact heads are never probed. Pairs with
- * {@link resolveChainViews}'s parallel `wildcard` provenance (`src/chains.ts`);
- * the caller resolves the role's concatenated chain first.
- */
-export declare function firstExactCandidate(all: readonly Selector[], wildcard: readonly boolean[]): Selector | undefined;
+export declare function resolveDeclaredRole(agent: AgentLike, rules: FallbacksRoleRule[], roleIds: ReadonlyMap<string, string>, opts: DeclaredRoleOptions): string;

package/dist/roles.d.ts

@@ -4,11 +4,10 @@
  *
  * This module is the RULES stage. Dispatch-time role resolution
  * (plan fallbacks-role-automatch; plan dsh-148 added the dispatch stage) is
- * the four-stage resolver in `role-resolution.ts` — explicit
+ * the three-stage resolver in `role-resolution.ts` — explicit
  * (`session.header.agentPreset`) → dispatch-declared role (the seam record
- * resolved from `**Execute as**`) → this rules stage → an optional auto-match
- * hook; `AgentLike` carries the additive `session.header.agentPreset?`
- * carrier for that explicit stage.
+ * resolved from `**Execute as**`) → this rules stage; `AgentLike` carries the
+ * additive `session.header.agentPreset?` carrier for that explicit stage.
  *
  * Precedence (first hit wins):
  * 1. the first `rules` entry whose specified provider/model patterns match

package/dist/state.d.ts

@@ -1,69 +1,25 @@
 /**
- * Per-agent fallback state machine (spec §5.1; plan Task 3).
+ * Per-agent fallback state (direction C, plan dsh-022-rc1-upgrade).
  *
  * One `AgentFallbackState` per `agent.id`, held in a `FallbackStateStore`
- * created at plugin apply, removed on `agent/disposed`, defensively pruned on
- * `agent/status` idle, and cleared wholesale on plugin dispose (spec §6:
- * 无残留状态).
+ * created at plugin apply, removed on `agent/disposed`, and cleared wholesale
+ * on plugin dispose (spec §6: 无残留状态).
  *
- * **pendingSwitch lifecycle** (spec §5.1):
- * 1. **Produce** (decision point — request-error trigger-code or
- *    agent/request always-cap): `writePending` stores the decision and clears
- *    `appliedTurnStep`, so a *fresh* decision is always applicable at the
- *    current (turn, step) — required for chains (decision B→C must apply even
- *    though A→B was already applied at the same (turn, step)).
- * 2. **Apply** (`agent/request`): `applyPending` returns the pending switch
- *    when one exists and has not already been applied at the current
- *    (turn, step), records `appliedTurnStep`, and clears `pendingSwitch`
- *    (anti-replay guard).
- * 3. **Discard**: chain exhaustion / safety valve → the caller delegates
- *    (`next()`) and the pending state dies with the agent.
- *
- * **stepFailures** resets whenever (turn, step) advances (`syncStep`);
- * **cooldown** (`CooldownStore`) is a `provider/model → expiry epoch ms` map
- * with lazy expiry (`revertPolicy: 'never'` = `Infinity` TTL). The time-boxed
- * cooldown deliberately survives idle cleanup so `cooldown-expiry` revert
- * (US-4 / T4 integration) works across turns.
+ * The store is the CROSS-CALL memory the chain walk reads: **cooldown**
+ * (`CooldownStore` — a `provider/model → expiry epoch ms` map with lazy expiry;
+ * `revertPolicy: 'never'` = `Infinity` TTL) plus the **recovery** circuit
+ * (`RecoveryStore`). The time-boxed cooldown deliberately survives idle
+ * cleanup so `cooldown-expiry` revert (US-4 / T4 integration) works across
+ * turns. Per-request bookkeeping (the failed-candidate set, the switch cap) is
+ * walk-local: a walk lives inside one `stream()` call, so nothing durable is
+ * kept for it here.
  *
  * @module dsh-llm-fallbacks/state
  */
 import type { FallbackSwitchReason } from './events.ts';
-import { CooldownStore, StepFailureSet } from './cooldown.ts';
+import { CooldownStore } from './cooldown.ts';
 import { RecoveryStore } from './recovery.ts';
 import type { RecoveryPolicy } from './config.ts';
-/**
- * What a switch's failure was actually about.
- *
- * `'route'` (the default) is every failure the plugin has ever walked: the
- * provider/model itself is unhealthy (auth, quota, rate limit, ...), so the
- * from-route is cooled down and counted as a route failure.
- * `'request'` is a failure of the REQUEST on a healthy route — a
- * `CONTEXT_WINDOW_EXCEEDED` rejection is the request being too big, not the
- * model being down. `commit()` keeps the step-scoped bookkeeping for those
- * but writes no suppression and no recovery failure (see `src/index.ts`
- * `REQUEST_SCOPED_CODES`).
- */
-export type SwitchScope = 'route' | 'request';
-/** Decision awaiting application at the next `agent/request` boundary (spec §5.1). */
-export interface PendingSwitch {
-    from: {
-        provider: string;
-        model: string;
-    };
-    to: {
-        provider: string;
-        model: string;
-    };
-    role: string;
-    reason: FallbackSwitchReason;
-    /**
-     * What the failure was about — absent means `'route'`, the semantics every
-     * switch had before request-scoped codes existed (same optional-with-a-
-     * documented-default idiom as `FallbacksRole.fallback`). Only the
-     * `agent/request-error` listener ever sets `'request'`.
-     */
-    scope?: SwitchScope;
-}
 /**
  * One plugin-originated subagent switch the host allowlist blocked (plan
  * dsh-012-subagent-routing T3; spec D1). The intersection of the resolved
@@ -85,8 +41,9 @@ export interface BlockedSwitchAttempt {
 /**
  * How the effective subagent chain head was chosen (plan dsh-012-subagent-routing
  * T5 / T2 M3). Lives on a per-agent map (mirrors {@link BlockedSwitchAttempt}),
- * not on {@link AgentFallbackState} — recording a head is not a switch intent
- * (F-004: the fallback store grows only inside `commit()`).
+ * not on {@link AgentFallbackState}. The write point is the dispatch seam
+ * (direction C): `authorized` = the spawn request carried an explicit route,
+ * `injected` = the seam mounted the child on the virtual chain row.
  */
 export type ChainHeadSource = 'authorized' | 'injected';
 /**
@@ -104,34 +61,16 @@ export interface EffectiveChainHead {
     /** `authorized` = host spawn preserved; `injected` = plugin role-inject. */
     source: ChainHeadSource;
 }
-/** The current (turn, step)'s failed-model set and switch budget (spec §5.1). */
-export interface StepFailures {
-    turn: number;
-    step: number;
-    /** `${provider}/${model}` keys failed in this step (double suppression with cooldown). */
-    failed: StepFailureSet;
-    /** Switches committed in this step; the caller judges it against `maxSwitchesPerStep`. */
-    switchCount: number;
-}
-/** One agent's whole fallback runtime state (spec §5.1). */
+/** One agent's fallback runtime state. */
 export interface AgentFallbackState {
-    /** Decision produced but not yet applied at an `agent/request` boundary. */
-    pendingSwitch?: PendingSwitch;
-    /** The (turn, step) the last pending switch was applied to — anti-replay. */
-    appliedTurnStep?: {
-        turn: number;
-        step: number;
-    };
-    /** Current (turn, step)'s failure bookkeeping. */
-    stepFailures: StepFailures;
     /** `provider/model → expiry epoch ms`; lazily expired on read. */
     cooldown: CooldownStore;
     /** Half-open recovery bookkeeping (plan fallbacks-half-open-recovery P2). */
     recovery: RecoveryStore;
 }
 /**
- * The `Map<agent.id, AgentFallbackState>` store plus the state-machine
- * operations (spec §5.1).
+ * The `Map<agent.id, AgentFallbackState>` store plus the state operations the
+ * walk and the diagnostics surfaces read.
  */
 export declare class FallbackStateStore {
     private readonly states;
@@ -146,29 +85,6 @@ export declare class FallbackStateStore {
     delete(agentId: string): void;
     /** Remove every agent's state (plugin dispose — no residual state). */
     clear(): void;
-    /** Reset step-scoped bookkeeping when (turn, step) advances (spec §5.1). */
-    syncStep(state: AgentFallbackState, turn: number, step: number): void;
-    /** Record the current model as failed in this step (spec §5.1). */
-    recordFailure(state: AgentFallbackState, key: string): void;
-    /** Bump the step's switch budget (spec §5.1). */
-    recordSwitch(state: AgentFallbackState): void;
-    /**
-     * Produce a pending switch. A fresh decision always supersedes a previous
-     * one and must be applicable at the current (turn, step), so the applied
-     * marker is cleared here (see module doc — chains).
-     */
-    writePending(state: AgentFallbackState, pending: PendingSwitch): void;
-    /**
-     * Apply the pending switch at (turn, step) when one exists and has not
-     * already been applied there; records the applied marker and clears the
-     * pending switch (spec §5.1 lifecycle step 2).
-     */
-    applyPending(state: AgentFallbackState, turn: number, step: number): PendingSwitch | undefined;
-    /**
-     * Defensive `agent/status` idle cleanup: drop per-step state. The time-boxed
-     * cooldown survives so `cooldown-expiry` revert works across turns (US-4).
-     */
-    clearStepState(state: AgentFallbackState): void;
     /** Suppress `key` until `untilEpochMs` (`Infinity` for `revertPolicy: 'never'`). */
     suppress(state: AgentFallbackState, key: string, untilEpochMs: number): void;
     /**

package/dist/subagent-policy.d.ts

@@ -9,8 +9,11 @@
  *    STRUCTURALLY — the upstream reader is not published from
  *    `@deepseek-ai/dsh-tool-subagent` and throws on malformed payloads,
  *    which is incompatible with the fail-closed no-throw requirement;
- * 2. the host settings service snapshot (`SubagentModelSelectionConfig`
- *    `.current()`), typed via a type-only peer import that is erased at emit.
+ * 2. the host's live subagent model-selection settings value (the
+ *    `subagent-model-selection-settings` settings namespace), typed via a
+ *    type-only peer import that is erased at emit. rc.1 made the settings
+ *    service's own snapshot reader private, so the wiring reads the settings
+ *    form value and narrows it structurally here.
  *
  * The session event wins over settings (ADR read order). Anything present but
  * unreadable yields `'unprovable'` (fail-closed): callers must not emit a
@@ -80,12 +83,22 @@ export type PolicySettings = {
 /** Assignability guard: fails typecheck if the peer's settings shape drifts from the reader's snapshot contract. */
 type AssertSettingsShape<T extends PolicySettings> = T;
 /**
- * The host settings service snapshot type, re-exported from the published
- * peer subpath (type-only). Wiring reads the service's `current()` and passes
- * the result in as plain data; if upstream drifts, this alias fails typecheck
- * instead of drifting silently at runtime (plan ADR).
+ * The host settings value's shape, re-exported from the published peer
+ * subpath (type-only). Wiring passes the settings form's namespace value in as
+ * plain data; if upstream drifts, this alias fails typecheck instead of
+ * drifting silently at runtime (plan ADR).
  */
 export type PeerSettingsSnapshot = AssertSettingsShape<SubagentModelSelectionSettings>;
+/**
+ * Narrow a host settings value into the reader's snapshot contract.
+ * Reads STRUCTURALLY like {@link readSessionPolicyEvent} — rc.1 publishes no
+ * settings value reader — so a malformed value is reported, never raised; the
+ * wiring decides its failure face (warn + fail-closed).
+ *
+ * @param value - untrusted settings-form value for the policy namespace.
+ * @returns a detached snapshot, or undefined when the value is not one.
+ */
+export declare function policySettingsFrom(value: unknown): PolicySettings | undefined;
 /**
  * Structurally read the session's `subagent/model-selection-policy` event.
  * Never throws: a present-but-malformed payload is reported, not raised.
@@ -116,8 +129,9 @@ export declare function readSessionPolicyEvent(events: readonly {
  * malformed route list, yields `'unprovable'`. Never throws.
  *
  * @param event - result of {@link readSessionPolicyEvent}.
- * @param settings - settings service snapshot, or undefined when the host
- *   does not compose the service.
+ * @param settings - host settings value narrowed by
+ *   {@link policySettingsFrom}, or undefined when the host composes no such
+ *   settings entry.
  */
 export declare function effectivePolicy(event: SessionPolicyEventRead, settings: PolicySettings | undefined): EffectivePolicy;
 export {};

package/dist/subagents-seam.d.ts

@@ -58,8 +58,25 @@
  * (the runtime mints its own child id and `agent/created` has already run), in
  * which case this module resolves the same question against the live roles
  * source and carries the verdict onto the record keyed off the RESOLVED id,
- * before the child's first pre-step. This module writes no request field,
- * reads no provider persona capability, and injects no agent preset.
+ * before the child's first pre-step. This module reads no provider persona
+ * capability and injects no agent preset.
+ *
+ * Virtual chain mount (plan dsh-022-rc1-upgrade §1.3; direction C): the SAME
+ * resolution point is where a dispatch child is mounted on the virtual
+ * `FallbacksChain/Auto` row — `request.agentOptions` is stamped (rc.1 merges
+ * it over the parent's route when `manager.startLocal` creates the child) when
+ * all five conditions hold: a resolved role, no explicit `agentOptions` route
+ * (explicit = authorized, untouched), a LOCAL backend, an active config whose
+ * resolved role chain has a dispatchable exact head ON the host allowlist when
+ * the subagent policy is `enabled`, and a policy that is not `unprovable`. The
+ * record carries `virtualRouteInjected` (sticky) and the effective chain head
+ * is labelled in `chainHeads` (`injected` / `authorized`). Injection is
+ * creation-time only BY CONSTRUCTION: rc.1's `startActivation` rejects any
+ * child id that already exists (`DUPLICATE_CHILD`), so this path never attaches
+ * to an existing child and cannot overwrite its durable selection — a
+ * caller-reserved `childId` is a pre-chosen identity for a NEW child. A
+ * non-injectable dispatch forwards the caller's spec untouched (external
+ * backends keep pure inheritance).
  *
  * In-session notice row (plan Task 3): the SAME install point registers the
  * `agent/pre-step` emitter (`./role-notice.ts`) over the record map it owns, so
@@ -89,7 +106,9 @@
  * @module dsh-llm-fallbacks/subagents-seam
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { type FallbacksRole } from './config.ts';
+import { type FallbacksConfig, type FallbacksRole } from './config.ts';
+import type { EffectiveChainHead } from './state.ts';
+import type { EffectivePolicy } from './subagent-policy.ts';
 /**
  * The cordis service-read waterfall event the seam registers on. Referenced
  * ONCE (registration) so a future cordis rename is a one-line change here.
@@ -149,6 +168,18 @@ export interface SubagentSeamRecord {
      * `true` survives.
      */
     personaNotApplied?: boolean;
+    /**
+     * `true` when this dispatch MOUNTED the child on the virtual
+     * `FallbacksChain/Auto` row (design §1.3): the plugin stamped the creation
+     * options, so the child's chain is plugin-originated and its switches are
+     * allowlist-filtered. Read by the chain walk (`ChainWalkDeps.seamRecord`)
+     * and never by a host surface.
+     *
+     * STICKY, like `personaNotApplied`: the mount happened at spawn and a record
+     * rewrite (a resume reusing the `childId`) carries no verdict of its own, so
+     * the first `true` survives.
+     */
+    virtualRouteInjected?: true;
 }
 /** One consumed prompt content block (`@deepseek-ai/dsh-llm` `ContentBlock` text members). */
 export interface SubagentPromptBlockView {
@@ -169,14 +200,25 @@ export interface SubagentStartRequestView {
             readonly id?: string;
         };
     };
+    /**
+     * rc.1 `SubagentStartRequest.agentOptions` (design §1.1) — the route the
+     * caller (or the model, on the tool path) asked the child to run on. Read
+     * only: an explicit pair here is the AUTHORIZED route and is never touched.
+     */
+    readonly agentOptions?: {
+        readonly provider?: string;
+        readonly model?: string;
+    };
 }
 /**
  * Structural view of the activation spec (rc.1 `SubagentActivationSpec`,
- * consumed fields only): `childId` is the caller-reserved identity a resume
- * already carries — also the record fallback when the request carries no
- * Assignment header — and `label` is the catalog join's other half (the
- * cataloged child membership carries this exact string). `signal`, `delivery`
- * and every future field travel with the caller's spec object.
+ * consumed fields only): `childId` is the caller-RESERVED identity of a NEW
+ * local child (rc.1 `startLocal` rejects an id that already exists with
+ * `DUPLICATE_CHILD`, so `startActivation` never attaches to a child that
+ * outlived an earlier activation) — also the record fallback when the request
+ * carries no Assignment header — and `label` is the catalog join's other half
+ * (the cataloged child membership carries this exact string). `signal`,
+ * `delivery` and every future field travel with the caller's spec object.
  */
 export interface SubagentActivationSpecView {
     readonly provider: string;
@@ -199,6 +241,23 @@ export interface SubagentSeamOptions {
      * wired) ⇒ no verdict, exactly like a listener that never saw the child.
      */
     roles?: () => readonly FallbacksRole[];
+    /**
+     * Live config reader — the SAME `source()` the runtime and the adapter walk
+     * read. Absent ⇒ the seam never mounts a child on the virtual route (a
+     * partial wiring keeps the native dispatch unchanged).
+     */
+    source?: () => FallbacksConfig;
+    /**
+     * The host subagent model-selection policy for one agent (guarded read,
+     * fail-closed). Absent ⇒ treated as `'disabled'` (no policy to fail closed
+     * on); an `'unprovable'` answer skips the mount.
+     */
+    policyFor?: (agentId: string) => EffectivePolicy;
+    /**
+     * Per-agent effective chain head, keyed by child session id (the Subagents
+     * card's read). Absent ⇒ the seam records no head label.
+     */
+    chainHeads?: Map<string, EffectiveChainHead>;
     /** Contained debug sink (at most one line per contained degrade). */
     debug?: (message: string) => void;
 }
@@ -220,8 +279,8 @@ export interface SubagentSeam {
      * deliberately NOT cleared on `agent/disposed` — a continuable child's durable
      * session survives the activation, so clearing the marker would let a
      * re-activation resume append a second notice row to the same log. It is
-     * bounded (`NOTICE_EMITTED_LIMIT`) and cleared only in the plugin dispose
-     * effect.
+     * bounded (`NOTICE_EMITTED_LIMIT`) and cleared only when the LAST applied
+     * fiber of its root disposes (a surviving fiber's children still need it).
      */
     readonly noticeEmitted: Set<string>;
     /**
@@ -233,7 +292,7 @@ export interface SubagentSeam {
      * message.
      */
     readonly ownsWrapper: boolean;
-    /** Stop intercepting service reads (the owning fiber's teardown also does). */
+    /** Withdraw this fiber's registrations (its own lifecycle effect does this on teardown). */
     dispose(): void;
 }
 /**

package/dist/tui-settings.d.ts

@@ -114,12 +114,14 @@ export declare const FALLBACKS_TUI_SECTION_NS = "fallbacks";
  */
 export declare const JSON_FIELD_MAX_DRAFT_BYTES: number;
 /**
- * The `fallbacks` /settings section: 12 fields covering all 14 web-card
+ * The `fallbacks` /settings section: 10 fields covering the web-card
  * capabilities (the default-model choice rides `rootChain`'s last entry and
  * the per-role fallback strategy rides `roles.list` JSON; the config-level
  * `enabled` switch is REMOVED — plan fallbacks-web-ux-alignment T2, the
  * Plugins-page row toggle is the master switch and the runtime gates read
- * content presence). Scalar
+ * content presence; the always-mode retry cap and the dispatch role
+ * auto-match switch are REMOVED with their mechanisms — direction C, only a
+ * `FallbacksChain/Auto` session walks a chain). Scalar
  * capabilities use native kinds (boolean/number/select); complex structures
  * use `text` fields with custom `format`/`parse` that mirror the gateway's
  * validation. Built fresh per call — the host deep-freezes whatever it

package/dist/virtual-adapter.d.ts

@@ -24,22 +24,22 @@
  * re-narrow the condition to ignore `timeSlots`. Conformance-only chain
  * edits still never churn (conformance gates the delegate, not the row).
  *
- * Adapter behavior (P1/P3): `listModels` advertises exactly the one virtual
- * row; `stream()` is a THIN single-hop delegate to the effective chain head
- * through the host LLM runtime — no chain walk, no cooldown/caps/revert
- * bookkeeping, no state writes (a failure inside the delegate surfaces at
- * `agent/request-error`, where the existing engine walks from there).
- * `resolveModel` proxies the current effective head's metadata when
- * resolvable (modalities/context-window/reasoning follow the head) with a
- * permissive default otherwise — never throws. `providerRetryPolicy` and
- * `imageRequestPricing` mirror the same head for the host-captured retry
- * policy and the token meter — also never throwing.
+ * Adapter behavior (P1/P3, direction C): `listModels` advertises exactly the
+ * one virtual row; `stream()` WALKS the session's chain (cooldown / failed-set
+ * / switch cap / recovery bookkeeping) in `src/chain-walk.ts` — the walk is
+ * injected at install and owns the pre-attempt guards, so this module stays
+ * the catalog + metadata surface. `resolveModel` proxies the current effective
+ * head's metadata when resolvable (modalities/context-window/reasoning follow
+ * the head) with a permissive default otherwise — never throws.
+ * `providerRetryPolicy` and `imageRequestPricing` mirror the same head for the
+ * host-captured retry policy and the token meter — also never throwing.
  *
  * @module dsh-llm-fallbacks/virtual-adapter
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { LlmAdapter, type GenerateOptions, type LlmImageRequestPricing, type LlmModelInfo, type LlmResolvedModelInfo, type LlmRuntime, type ResolvedRetryPolicy, type StreamChunk } from '@deepseek-ai/dsh-llm';
 import { type FallbacksConfig } from './config.ts';
+import type { PolicyRoute } from './subagent-policy.ts';
 /** Provider route of the virtual adapter (exact string, spec lock). */
 export declare const FALLBACKS_PROVIDER = "FallbacksChain";
 /**
@@ -49,19 +49,6 @@ export declare const FALLBACKS_PROVIDER = "FallbacksChain";
  * {@link pickerDisplayName} (`Auto: <model>[<slot>]`).
  */
 export declare const FALLBACKS_CHAIN_MODEL = "Auto";
-/**
- * `LlmError` code: the effective chain is empty — the virtual route has no
- * head to delegate to (P1 guard).
- */
-export declare const EMPTY_EFFECTIVE_CHAIN_CODE = "EMPTY_EFFECTIVE_CHAIN";
-/**
- * `LlmError` code: the effective chain head is not a dispatchable real pair
- * (non-conforming all-day, wildcard selector, malformed selector, or a
- * self-route back to `FallbacksChain/*` — the P1 recursion guard).
- */
-export declare const UNDISPATCHABLE_HEAD_CODE = "UNDISPATCHABLE_EFFECTIVE_HEAD";
-/** `LlmError` code (defensive): the `llm` runtime disappeared mid-flight. */
-export declare const LLM_UNAVAILABLE_CODE = "LLM_UNAVAILABLE";
 /** One dispatchable exact head: `provider/model`. Wildcards are never seeds (P3). */
 export interface EffectiveHead {
     provider: string;
@@ -69,16 +56,25 @@ export interface EffectiveHead {
 }
 /**
  * The FIRST DISPATCHABLE exact head of a chain — the single definition of
- * "effective head" (F-001) shared by the virtual adapter's delegate paths and
- * the routing engine's served-route anchor (`anchorServedRoute` in
- * `src/index.ts`). Walks the SAME chain `resolveEffectiveChain` produces,
- * skipping entries that can never
+ * "effective head" (F-001) shared by this module's metadata paths
+ * (`pickerDisplayName` / `resolveModel` / `providerRetryPolicy` /
+ * `imageRequestPricing`), the walk's head and served-route resolution
+ * (`servedRouteOf` in `src/chain-walk.ts`), and the seam's mount gate
+ * (`injectRoute` in `src/subagents-seam.ts`). Walks the SAME chain
+ * `resolveEffectiveChain` produces, skipping entries that can never
  * be dispatched: malformed selectors (config-warning path), `provider/*`
  * `provider/*` wildcards (no real pair), and self-routes back to
  * `FallbacksChain/*` (the P1 recursion guard). `undefined` when the chain
  * is empty or no entry is dispatchable.
+ *
+ * `allowedModels` (spec D1) additionally restricts the result to the host
+ * subagent allowlist: a PLUGIN-originated route is only ever attempted on a
+ * route the host authorizes, so the seam's mount gate and a plugin-originated
+ * walk's start pass the enabled policy's list and an entry it excludes is
+ * skipped like any other non-dispatchable entry. An empty intersection is
+ * `undefined` — the caller declines the mount / refuses the walk.
  */
-export declare function firstDispatchableExactHead(chain: readonly string[]): EffectiveHead | undefined;
+export declare function firstDispatchableExactHead(chain: readonly string[], allowedModels?: readonly PolicyRoute[]): EffectiveHead | undefined;
 /**
  * The effective chain head at `now` (P1): the first DISPATCHABLE exact head
  * of the SAME `resolveEffectiveChain` the routing engine uses — thin
@@ -92,8 +88,9 @@ export declare function firstDispatchableExactHead(chain: readonly string[]): Ef
  * for a successful delegate —
  * a legacy multi-model (or empty) all-day chain earns no primary
  * semantics even though the picker row is visible. `resolveModel` then
- * falls back to the permissive default and `stream()` throws
- * {@link UNDISPATCHABLE_HEAD_CODE}.
+ * falls back to the permissive default. The delegate side of that gate is the
+ * chain walk's ROOT-origin rule (`UNDISPATCHABLE_EFFECTIVE_HEAD`); a subagent
+ * walks its role chain instead, so the all-day shape never gates a child.
  */
 export declare function effectiveHeadOf(config: FallbacksConfig, now: Date): EffectiveHead | undefined;
 /**
@@ -105,17 +102,14 @@ export declare function effectiveHeadOf(config: FallbacksConfig, now: Date): Eff
  */
 export declare function pickerDisplayName(config: FallbacksConfig, now?: Date, modelDisplayName?: string): string;
 /**
- * The virtual adapter (P1/P3). `stream()` is a thin head-delegate, never a
- * second routing engine: no chain walk, cooldown, caps, revert bookkeeping,
- * or state writes live here — those stay in the `agent/request` /
- * `agent/request-error` listeners. Exported so the defensive guard paths
- * the registration lifecycle cannot reach (a registered route whose `llm`
- * vanished mid-teardown) stay unit-testable by direct construction.
+ * The virtual adapter (P1/P3). `stream()` hands the call to the injected walk
+ * (see `src/chain-walk.ts`) — registration metadata stays here.
  */
 export declare class FallbacksChainAdapter extends LlmAdapter {
     private readonly readConfig;
     private readonly getLlm;
-    constructor(readConfig: () => FallbacksConfig, getLlm: () => LlmRuntime | undefined);
+    private readonly walk;
+    constructor(readConfig: () => FallbacksConfig, getLlm: () => LlmRuntime | undefined, walk: (options: GenerateOptions) => AsyncIterable<StreamChunk>);
     /** Minimal honest descriptor (P3) — the provider route IS the display name. */
     providerInfo(provider: string): {
         id: string;
@@ -157,14 +151,14 @@ export declare class FallbacksChainAdapter extends LlmAdapter {
      */
     imageRequestPricing(_provider: string, _model: string): LlmImageRequestPricing | undefined;
     /**
-     * Thin head-delegate (P1): resolve the effective chain head and dispatch
-     * that REAL pair through the host LLM runtime. Throws an explicit
-     * `LlmError` only when there is no real pair to delegate to: an empty
-     * effective chain, an undispatchable head (wildcard / malformed /
-     * self-route — the recursion guard), or a vanished `llm` runtime. The
-     * runtime normalizes the throw into a terminal error finish chunk, so the
-     * documented listener-order degradation stays graceful instead of a hard
-     * outage.
+     * The virtual route's entry point (P1, direction C): the session's chain is
+     * WALKED (`src/chain-walk.ts`) — the walk owns the pre-attempt guards
+     * (`EMPTY_EFFECTIVE_CHAIN` / `UNDISPATCHABLE_EFFECTIVE_HEAD` /
+     * `LLM_UNAVAILABLE`, thrown synchronously before any chunk, so the runtime
+     * normalizes them exactly like an adapter throw) because only it can resolve
+     * WHICH chain the calling session walks: a subagent's role chain is not the
+     * root's all-day chain, so a root-only gate here would refuse a child that
+     * has a perfectly walkable role chain.
      */
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }
@@ -174,7 +168,9 @@ export declare class FallbacksChainAdapter extends LlmAdapter {
  * @param ctx - the plugin context.
  * @param readConfig - live config reader (the same `source()` the runtime
  *   reads, so reconcile always sees COMMITTED composed snapshots).
+ * @param walk - the chain walk the adapter's `stream()` runs for one virtual
+ *   call (built by `apply()` over its live state — see `src/chain-walk.ts`).
  * @returns the reconcile thunk — call it from the settings `onChange` hook
  *   (child activation runs one reconcile on its own).
  */
-export declare function installFallbacksAdapter(ctx: Context, readConfig: () => FallbacksConfig): () => void;
+export declare function installFallbacksAdapter(ctx: Context, readConfig: () => FallbacksConfig, walk: (options: GenerateOptions) => AsyncIterable<StreamChunk>): () => void;

package/docs/DETAIL.md

@@ -0,0 +1 @@
+![A request failing on an auth code in the FallbacksChain walk, the next provider/model serving it, the switch log line, and the FallbacksChain / Auto row in the model picker](preview.svg)