dsh-advisor 0.4.0 → 0.5.0

package/lib/index.js

@@ -31,11 +31,11 @@
  * (`ctx.get('tuiSettingsSections') !== undefined`), so the hint names the TUI
  * `/settings` Advisor section as a write path exactly while the seam is
  * mounted; the readback itself stays session-less and read-only.
- * Settings (plan dsh-advisor-settings-n2): the plugin-row config is the
- * composition base of the `advisor` settings namespace (`src/settings.ts`),
- * read live through the bridge source; committed settings edits re-apply
- * derived state (immuneTurns / maxDeltaMessages / per-session runtimes)
- * without a restart.
+ * Settings (plan dsh-advisor-settings-n2): the plugin-row entry config's six
+ * live fields are schema-volatile (`src/config.ts`), read live through the
+ * bridge source (`src/settings.ts`); committed volatile edits (Loader
+ * `loader/volatile-update`) re-apply derived state (immuneTurns /
+ * maxDeltaMessages / per-session runtimes) without a restart.
  * Config gateway (plan dsh-advisor-settings-gateway-n5): `apply` also
  * registers the host-side `AdvisorConfigGateway` (`src/gateway.ts`) — the
  * `/api/advisor/get` + `/api/advisor/set` endpoints (explicit
@@ -45,14 +45,67 @@
  *
  * @module dsh-advisor
  */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { resolveAdvisorConfig } from './config.js';
 import { installAdvisorSettings } from './settings.js';
-import { AdvisorConfigGateway, advisorTypertContribution } from './gateway.js';
+import { AdvisorConfigGateway, advisorSessionError, advisorTypertContribution } from './gateway.js';
 import { SessionTranscriptObserver } from './transcript.js';
 import { AdvisorRuntime } from './advisor-runtime.js';
 import { AdvisorDelivery } from './delivery.js';
 import { DEFAULT_ADVISOR_SYSTEM_PROMPT } from './prompts.js';
-import { AdvisorSessionOverrides, registerAdvisorCommands, summarizeSystemPrompt } from './commands.js';
+import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout';
+import { AdvisorSessionOverrides, registerAdvisorCommands, summarizeSystemPrompt, ADVISOR_MODEL_VALIDATION_TIMEOUT_MS } from './commands.js';
 import { installTuiClient } from './tui.js';
 import { TUI_SETTINGS_SECTIONS, installTuiSettingsSection } from './tui-settings.js';
 export const name = 'dsh-advisor';
@@ -64,15 +117,13 @@ export { Config } from './config.js';
  * fibers (observed: 3 active); with the global session/event subscription every
  * instance would observe every session and N×-review/N×-call per round. The
  * FIRST apply to claim the reviewer role wires the observer/runtime/delivery
- * and the /advisor commands; later instances attempt the settings registration
- * only (qc1 W-5: it is NOT idempotent — dsh-settings register throws on a
- * duplicate; installAdvisorSettings dedupes it and falls back to the entry
- * source, so the first registration owns the live namespace) and stay inert
- * otherwise. The claim is taken only AFTER the construction-time config gate
- * (qc1 W-4: a rejected first row never leaves the flag claimed) and is
- * released when the claiming fiber is disposed, so a later re-apply/re-mount
- * can take over. The flag rides globalThis so it survives even module-copy
- * divergence. */
+ * and the /advisor commands; later instances keep only their settings bridge
+ * (each fiber's bridge listens on its own fiber's `loader/volatile-update` —
+ * the owning-filter keeps them independent) and stay inert otherwise. The
+ * claim is taken only AFTER the construction-time config gate (qc1 W-4: a
+ * rejected first row never leaves the flag claimed) and is released when the
+ * claiming fiber is disposed, so a later re-apply/re-mount can take over. The
+ * flag rides globalThis so it survives even module-copy divergence. */
 const REVIEWER_KEY = '__dshAdvisorReviewer__';
 function claimReviewer() {
     const g = globalThis;
@@ -81,16 +132,72 @@ function claimReviewer() {
     g[REVIEWER_KEY] = true;
     return true;
 }
+/** Capability-owned code stamped onto the model-validation deadline's TimeoutReason. */
+const ADVISOR_MODEL_VALIDATION_TIMEOUT = 'ADVISOR_MODEL_VALIDATION_TIMEOUT';
+/**
+ * Fuse several upstream signals into one (spec §5.3 validation): the fused
+ * signal aborts when ANY upstream aborts. Used to combine the invoking
+ * command's cancellation signal with the owner-teardown signal — a hung
+ * `resolveModelInfo` lookup that honors cancellation aborts with whichever
+ * lands first, and the `dsh-timeout` deadline adds the 60 s bound on top.
+ * `cleanup` removes the listeners (the teardown signal outlives every
+ * short-lived validation).
+ */
+function fuseSignals(...upstreams) {
+    const controller = new AbortController();
+    const onAbort = (event) => {
+        controller.abort(event.target.reason);
+    };
+    for (const upstream of upstreams) {
+        if (upstream === undefined)
+            continue;
+        if (upstream.aborted)
+            controller.abort(upstream.reason);
+        else
+            upstream.addEventListener('abort', onAbort);
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            for (const upstream of upstreams)
+                upstream?.removeEventListener('abort', onAbort);
+        },
+    };
+}
+/**
+ * Race one promise against a signal (same shape as the runtime's per-chunk
+ * `raceIteratorNext`): settle with the promise's result, or `'aborted'` when
+ * the signal aborts first. Needed because `LlmRuntime.resolveModelInfo` only
+ * THREADS the signal into the adapter — an adapter whose lookup ignores
+ * cancellation would otherwise wedge the validation past the deadline; the
+ * race makes the 60 s bound (and the owner-teardown/command aborts) real for
+ * the caller regardless of adapter behavior.
+ */
+function raceSignal(promise, signal) {
+    if (signal.aborted)
+        return Promise.resolve('aborted');
+    return new Promise((resolve, reject) => {
+        const onAbort = () => resolve('aborted');
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
 export function apply(ctx, config) {
     // T2: the explicit provider/model gate — no model call without both
     // (spec §5.2). Unknown keys / malformed config throw here, rejecting the
     // plugin row at load; the gate resolves to disabled-with-reason instead.
     //
-    // T1-settings (plan dsh-advisor-settings-n2): the plugin-row config is the
-    // composition BASE of the `advisor` settings namespace. The runtime reads
-    // the LIVE composed value through the bridge source (schema defaults →
-    // base → settings user layer); with no settings service the source is
-    // exactly `config` — behavior identical to today. The hard gate is applied
+    // T1-settings (plan dsh-advisor-settings-n2): the plugin-row entry config's
+    // six live fields are schema-volatile (0.1.7-rc.1). The runtime reads the
+    // LIVE values through the bridge source (per-field volatile reference
+    // unwrap); the Loader commits edits into those references without a remount
+    // and announces them via `loader/volatile-update`. The hard gate is applied
     // to every read: `resolveAdvisorConfig` stays the SSOT for the
     // disabled-with-reason resolution.
     const bridge = installAdvisorSettings(ctx, config);
@@ -112,8 +219,16 @@ export function apply(ctx, config) {
     // registrations are fiber effects (unregistered when this fiber disposes),
     // so a re-apply/re-mount can take over. The instance needs no handle here:
     // the typertGateway dispatches through `ctx.get('advisor')`.
+    //
+    // B2 (issue #88 web session control): the session endpoints route through
+    // the SAME controller the `/advisor model` commands drive — the face below
+    // is assigned by the elected (reviewer-claiming) fiber AFTER its controller
+    // exists; the gateway resolves it lazily per request, so a gateway on a
+    // fiber that lost the service-key race (or that never claimed the reviewer
+    // role) answers `advisor/unavailable` in data and stays inert.
+    let sessionControl;
     try {
-        new AdvisorConfigGateway(ctx, bridge);
+        new AdvisorConfigGateway(ctx, bridge, () => sessionControl);
     }
     catch (error) {
         if (!(error instanceof Error) || !error.message.includes('has been registered'))
@@ -139,18 +254,18 @@ export function apply(ctx, config) {
     });
     const sourceConfig = () => bridge.source();
     const resolved = () => resolveAdvisorConfig(sourceConfig());
-    // qc2 W-1 containment: a settings user layer the resolver rejects (e.g. an
-    // unknown key survives the non-strict settings schema) must never wedge the
-    // live hot path — every read that can run inside an event handler goes
-    // through the safe wrappers, which catch resolver throws and return
-    // disabled-with-reason carrying the message, so gate semantics hold (no
-    // model call can start) and handlers stay functional. The LOAD-TIME
+    // qc2 W-1 containment: an entry config the resolver rejects (e.g. an
+    // unknown key that survived the non-strict schemastery object merge) must
+    // never wedge the live hot path — every read that can run inside an event
+    // handler goes through the safe wrappers, which catch resolver throws and
+    // return disabled-with-reason carrying the message, so gate semantics hold
+    // (no model call can start) and handlers stay functional. The LOAD-TIME
     // plugin-row throw contract is unchanged: construction-time reads below
     // (delivery/observer latches) still use the throwing `resolved()`, so a bad
     // entry rejects the plugin row at load (config.test.ts ⑤).
     const safeFallback = (reason) => {
         // S1 (gateway readConfig parity): when the raw source is still readable,
-        // seed the scalar latches from it — an invalid user layer only drops the
+        // seed the scalar latches from it — an invalid config only drops the
         // offending keys, so /advisor config (and /advisor status) never
         // misreport immuneTurns / maxDeltaMessages / systemPrompt vs the web
         // card's /api/advisor/get readback.
@@ -177,9 +292,23 @@ export function apply(ctx, config) {
             return safeFallback(error instanceof Error ? error.message : String(error));
         }
     };
+    // Spec §5.3 — the ONE effective resolver: (1) the global shape is validated
+    // first (a malformed entry still throws → safeFallback: fail closed for
+    // every session); (2) enable = session enable override ?? global; (3) route
+    // = the session's COMPLETE modelOverride pair ?? the composed global pair —
+    // the pair is atomic, so the levels are never merged; (4) the explicit pair
+    // gate (§5.2) applies AFTER this resolution on the effective values: a
+    // complete session pair satisfies a pairless global default, while an
+    // invalid global schema can never be bypassed.
     const safeEffective = (sessionId) => {
         try {
-            return resolveAdvisorConfig({ ...sourceConfig(), enabled: effectiveEnabled(sessionId) });
+            const source = sourceConfig();
+            const pair = overrides.model(sessionId);
+            return resolveAdvisorConfig({
+                ...source,
+                enabled: effectiveEnabled(sessionId),
+                ...(pair === undefined ? {} : { provider: pair.provider, model: pair.model }),
+            });
         }
         catch (error) {
             return safeFallback(error instanceof Error ? error.message : String(error));
@@ -194,17 +323,30 @@ export function apply(ctx, config) {
     // commands start/stop per-session runtimes WITHOUT touching the persisted
     // config (spec §4 mapping — omp `/advisor` semantics). Ephemeral: entries
     // are cleared on `agent/disposed` / `session/disposed` below. Seeded with
-    // the RAW config switch (not the post-gate `resolved.enabled`): a config-
-    // enabled-but-gate-blocked session (enabled without provider/model) then
-    // re-derives the disabled-with-reason through the resolver, so `/advisor
-    // status` shows the reason (spec §5.2; qc3 I-1) — the gate itself still
-    // blocks every runtime (the resolver is the SSOT for the gate).
-    const overrides = new AdvisorSessionOverrides(config.enabled);
+    // the LIVE config switch read through the bridge (the raw `config` fields
+    // are volatile references on a Loader composition — an unwrapped snapshot
+    // shares the source with `safeResolved`): a config-enabled-but-gate-blocked
+    // session (enabled without provider/model) then re-derives the
+    // disabled-with-reason through the resolver, so `/advisor status` shows the
+    // reason (spec §5.2; qc3 I-1) — the gate itself still blocks every runtime
+    // (the resolver is the SSOT for the gate).
+    const overrides = new AdvisorSessionOverrides(bridge.source().enabled);
     const effectiveEnabled = (sessionId) => overrides.effective(sessionId);
     // Live-path alias: every consumer reads the effective config through the
     // safe wrapper (qc2 W-1 — a throwing resolver must not break the
     // session/event handler or `/advisor status`).
     const effectiveConfig = (sessionId) => safeEffective(sessionId);
+    // n4 root-cause (host-observed NO_ADAPTER): this plugin's ctx may live in an
+    // isolated scope whose local llm service lacks the provider adapters (adapter
+    // registrations live on the application root's LlmRuntime). The APPLICATION
+    // ROOT's llm serves BOTH the advisor model calls (ensureRuntime) and the
+    // `/advisor model set` validation lookups (spec §5.3).
+    const appRootLlm = () => ctx.root?.get?.('llm') ?? ctx.llm;
+    // Spec §5.3 — model-validation teardown signal: fused into every in-flight
+    // `/advisor model set` lookup, so owner teardown aborts them promptly; the
+    // generation wipe (disposeAll, below) makes any completion that still
+    // settles unable to commit.
+    const validationTeardown = new AbortController();
     // T3+T4: per-session transcript observation wired into one advisor runtime
     // per session. On each stepped reviewable turn/end a bounded markdown delta
     // is rendered and queued on the session's runtime; the runtime drains it
@@ -232,7 +374,9 @@ export function apply(ctx, config) {
      * creation and compared on every settings change (qc3 W-1 / qc1 W-2): only
      * a signature change tears the runtime down — an immuneTurns/
      * maxDeltaMessages-only edit updates the latches in place and keeps every
-     * in-flight call and backlog.
+     * in-flight call and backlog. The triple reads the EFFECTIVE config
+     * (spec §5.3), so a session-pinned pair freezes the signature against later
+     * global pair edits — global edits reach inheritors, never pinned sessions.
      */
     const runtimeSignatures = new Map();
     const runtimeSignature = (sessionId) => {
@@ -267,12 +411,7 @@ export function apply(ctx, config) {
             provider: effective.provider,
             model: effective.model,
             systemPrompt: safeResolved().systemPrompt || DEFAULT_ADVISOR_SYSTEM_PROMPT,
-            // n4 root-cause (host-observed NO_ADAPTER): this plugin's ctx may live in
-            // an isolated scope whose local llm service lacks the provider adapters
-            // (adapter registrations live on the application root's LlmRuntime). Resolve
-            // the llm service from the APPLICATION ROOT so the advisor's model calls
-            // reach the registered deepseek-official adapter.
-            llm: ctx.root?.get?.('llm') ?? ctx.llm,
+            llm: appRootLlm(),
             onNote: (note) => {
                 // Accepted notes only — the runtime's emission guard (T5) already
                 // filtered suppressed ones. T6 routes the accepted note to the primary
@@ -298,14 +437,36 @@ export function apply(ctx, config) {
         runtimeSignatures.delete(sessionId);
         runtime.dispose();
     };
+    /**
+     * Apply a committed effective-route change (spec §5.3): abort the session's
+     * old advisor call + drop its backlog (disposeRuntime), re-seed the observer
+     * cursor to the current transcript length, and recreate the runtime — the
+     * change takes effect at the next new reviewable delta (no replay of the
+     * current window). A disabled session keeps its (new) pin for a later
+     * `/advisor on`; an unchanged effective route restarts nothing.
+     * @param before - the effective config captured BEFORE the override state
+     *   changed (the caller mutates `overrides` between the capture and here).
+     */
+    const applyRouteChange = (sessionId, before, sessionLength) => {
+        if (!effectiveEnabled(sessionId))
+            return;
+        const after = effectiveConfig(sessionId);
+        if (after.provider === before.provider && after.model === before.model)
+            return;
+        if (sessionLength !== undefined)
+            observer.seedTo(sessionId, sessionLength);
+        disposeRuntime(sessionId);
+        ensureRuntime(sessionId);
+    };
     // n4 QC F-6: claim the single-reviewer role HERE — after every
     // construction-time throwing read (the delivery latch above resolves the
     // config and can throw on a rejected row), so a first fiber whose config
     // fails the gate never leaves the flag claimed (qc1 W-4). Non-reviewer
     // instances stop here — observer/runtime/delivery and the /advisor commands
-    // are wired only by the single claimed reviewer. The settings registration
-    // (installAdvisorSettings above) already ran deduped (qc1 W-5): the first
-    // registration owns the live namespace on every composition.
+    // are wired only by the single claimed reviewer. Their own settings bridge
+    // (installAdvisorSettings above) stays live: it is per-fiber by
+    // construction, nothing to dedupe (qc1 W-5's registration is gone with the
+    // 0.1.7-rc.1 namespace model).
     const reviewer = claimReviewer();
     if (!reviewer) {
         ctx.logger('advisor').debug('non-reviewer instance — observer/runtime/commands skipped (single-reviewer guard)');
@@ -314,9 +475,14 @@ export function apply(ctx, config) {
     // qc1 W-4: release the claim when THIS (reviewer) fiber is disposed, so a
     // later re-apply/re-mount (plugin-row removal, composition reload, host hot
     // reload) can take over instead of leaving the advisor silently inert for
-    // the process lifetime. Registered only on the claiming fiber.
+    // the process lifetime. Registered only on the claiming fiber. The teardown
+    // also owns the override state (spec §5.3): abort in-flight model
+    // validations and wipe every per-session override entry/generation — a
+    // delayed validation completion can never commit after the owner is gone.
     ctx.effect(() => () => {
         delete globalThis[REVIEWER_KEY];
+        validationTeardown.abort('advisor owner disposed');
+        overrides.disposeAll();
     }, 'advisor: release reviewer claim');
     const observer = new SessionTranscriptObserver({
         maxDeltaMessages: resolved().maxDeltaMessages,
@@ -372,9 +538,26 @@ export function apply(ctx, config) {
     // creates the runtime eagerly (plan T4) when the session is enabled and
     // registers the agent in the KD-4 delivery map (T6); the observer fallback
     // covers pre-existing agents (KD-4-style robustness).
+    //
+    // 0.1.6-alpha.2 seam: `agent/created` became a SERIAL event — its listeners
+    // run in order and are AWAITED before creation resolves, and a throw or
+    // rejection FAILS creation and skips later listeners (0.1.5-rc.2 dispatched
+    // it fire-and-forget). Two obligations follow for this handler:
+    //   - return `undefined`: the listener contract is
+    //     `undefined | Promise<undefined>`, so a bare `void` body no longer
+    //     typechecks against the host Events table;
+    //   - never throw: an advisory-only plugin must not be able to fail the
+    //     primary agent's creation, so setup failures are contained and logged
+    //     here rather than crossing the event boundary.
     ctx.on('agent/created', ({ agent }) => {
-        ensureRuntime(agent.id);
-        delivery.registerAgent(agent);
+        try {
+            ensureRuntime(agent.id);
+            delivery.registerAgent(agent);
+        }
+        catch (error) {
+            ctx.logger('advisor').warn('advisor: agent/created setup failed — contained', { error, sessionId: agent.id });
+        }
+        return undefined;
     }, { global: true });
     ctx.on('agent/disposed', ({ agent }) => {
         observer.disposeSession(agent.id);
@@ -391,17 +574,18 @@ export function apply(ctx, config) {
     // T1-settings live re-apply: construction-time latches (immuneTurns on the
     // delivery, maxDeltaMessages on the observer, systemPrompt + provider/model
     // on each per-session runtime) are re-derived from the NEW source on every
-    // committed settings change and re-applied — delivery/observer update in
-    // place, per-session runtimes rebuild only when their runtime-affecting
-    // signature actually changed (qc3 W-1 / qc1 W-2: an immuneTurns/
-    // maxDeltaMessages-only edit must not abort in-flight advisor calls or drop
-    // backlogs). The S4 gate is re-applied by the resolver on every read, so a
-    // settings edit can never start a gated model call (SSOT unchanged); the
-    // config-level fallback switch follows the live source so new sessions pick
-    // up a Settings-page `enabled` edit immediately. A settings user layer the
-    // resolver rejects (qc2 W-1 — unknown key) stops the advisor without
-    // wedging the re-apply path, and the last-good latches stay until the
-    // config is repaired.
+    // committed volatile edit — the Loader's `loader/volatile-update` event,
+    // dispatched to this fiber only after the committed values are readable —
+    // and re-applied: delivery/observer update in place, per-session runtimes
+    // rebuild only when their runtime-affecting signature actually changed
+    // (qc3 W-1 / qc1 W-2: an immuneTurns/maxDeltaMessages-only edit must not
+    // abort in-flight advisor calls or drop backlogs). The S4 gate is
+    // re-applied by the resolver on every read, so a config edit can never
+    // start a gated model call (SSOT unchanged); the config-level fallback
+    // switch follows the live source so new sessions pick up an enabled edit
+    // immediately. An entry config the resolver rejects (qc2 W-1 — unknown
+    // key) stops the advisor without wedging the re-apply path, and the
+    // last-good latches stay until the config is repaired.
     bridge.onChange(() => {
         let next;
         try {
@@ -427,8 +611,16 @@ export function apply(ctx, config) {
         delivery.setImmuneTurns(next.immuneTurns);
         observer.setMaxDeltaMessages(next.maxDeltaMessages);
         overrides.setConfigEnabled(sourceConfig().enabled);
+        // Candidates = live runtimes ∪ sessions holding an override. The second
+        // set covers an `/advisor on`-enabled session whose runtime is ABSENT
+        // because it was gate-blocked: when the defaults become usable (a global
+        // pair is committed) it must gain its runtime here, not wait for its next
+        // delta (plan: include enabled-gate-blocked sessions with no runtime when
+        // defaults become usable). The signature compare still gates actual
+        // rebuilds; ensureRuntime re-applies the post-gate gate on every call.
+        const candidates = new Set([...runtimes.keys(), ...overrides.overrideSessionIds()]);
         let rebuilt = 0;
-        for (const sessionId of [...runtimes.keys()]) {
+        for (const sessionId of candidates) {
             if (runtimeSignatures.get(sessionId) === runtimeSignature(sessionId))
                 continue;
             disposeRuntime(sessionId);
@@ -449,7 +641,34 @@ export function apply(ctx, config) {
     // no full-history replay) and creates/resumes/recoveries the session runtime;
     // `/advisor off` disposes it (abort in-flight, drop backlog). The S4 gate
     // reason is re-derived through the config resolver, the SSOT for the
-    // disabled-with-reason text (spec §5.2).
+    // disabled-with-reason text (spec §5.2). `/advisor model set|reset` mutate
+    // the runtime-only session pair (spec §5.3) through the generation-fenced
+    // validation + applyRouteChange seams below.
+    const sessionStatus = (sessionId) => {
+        const runtime = runtimes.get(sessionId);
+        const effective = effectiveConfig(sessionId);
+        const pair = overrides.model(sessionId);
+        // Spec §5.3: the status reports the EFFECTIVE route, labeled by source.
+        // The label is `session` only when the effective pair IS the session's
+        // pin (a malformed global fails closed through safeFallback — provider/
+        // model undefined — and a pinned session under it reports no pair, with
+        // the reason carried by disabledReason).
+        const source = effective.provider === undefined || effective.model === undefined
+            ? undefined
+            : pair !== undefined && pair.provider === effective.provider && pair.model === effective.model
+                ? 'session'
+                : 'global';
+        return {
+            enabled: effective.enabled,
+            ...(effective.disabledReason === undefined ? {} : { disabledReason: effective.disabledReason }),
+            provider: effective.provider,
+            model: effective.model,
+            ...(source === undefined ? {} : { modelSource: source }),
+            runtimeStatus: runtime?.status() ?? 'disabled',
+            pendingCount: runtime?.pendingCount ?? 0,
+            lastActivityAt: runtime?.lastActivity,
+        };
+    };
     const controller = {
         setEnabled(sessionId, enabled, sessionLength) {
             // Recovery, not just a switch flip: `/advisor on` (and toggle-to-on)
@@ -486,29 +705,121 @@ export function apply(ctx, config) {
             }
         },
         getStatus(sessionId) {
-            const runtime = runtimes.get(sessionId);
+            return sessionStatus(sessionId);
+        },
+        // Spec §5.3: the effective route for `/advisor model` — the resolver SSOT
+        // (effectiveConfig) supplies the pair, the session pin supplies the label.
+        getModelRoute(sessionId) {
             const effective = effectiveConfig(sessionId);
-            return {
-                enabled: effective.enabled,
-                ...(effective.disabledReason === undefined ? {} : { disabledReason: effective.disabledReason }),
-                provider: safeResolved().provider,
-                model: safeResolved().model,
-                runtimeStatus: runtime?.status() ?? 'disabled',
-                pendingCount: runtime?.pendingCount ?? 0,
-                lastActivityAt: runtime?.lastActivity,
-            };
+            const pair = overrides.model(sessionId);
+            const source = pair !== undefined && pair.provider === effective.provider && pair.model === effective.model
+                ? 'session'
+                : 'global';
+            return { provider: effective.provider, model: effective.model, source };
+        },
+        // Spec §5.3 — validate, then commit, an atomic session pair. Fence FIRST
+        // (bump the generation), so a newer set/reset — or any state wipe — makes
+        // this attempt stale. The lookup rides the app-root LLM service, bound to
+        // the 60 s deadline fused with the invoking command's signal and the owner
+        // teardown signal, with NO automatic retry; failure leaves the previous
+        // selection untouched. Catalog membership is advisory — a successful
+        // resolution is the acceptance gate. Selection never starts a generation
+        // call and never touches the enable override.
+        async setModel(sessionId, provider, model, agent, signal) {
+            const generation = overrides.beginModelGeneration(sessionId);
+            const fused = fuseSignals(signal, validationTeardown.signal);
+            try {
+                const env_1 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const deadlineHandle = __addDisposableResource(env_1, deadline(fused.signal, ADVISOR_MODEL_VALIDATION_TIMEOUT_MS, ADVISOR_MODEL_VALIDATION_TIMEOUT)
+                    // Race the lookup against the fused signal: a hung adapter lookup that
+                    // ignores cancellation settles here as 'aborted' at the deadline, so
+                    // the 60 s bound holds regardless of adapter behavior. There is NO
+                    // automatic retry — one lookup, one outcome.
+                    , false);
+                    // Race the lookup against the fused signal: a hung adapter lookup that
+                    // ignores cancellation settles here as 'aborted' at the deadline, so
+                    // the 60 s bound holds regardless of adapter behavior. There is NO
+                    // automatic retry — one lookup, one outcome.
+                    const resolvedInfo = await raceSignal(appRootLlm().resolveModelInfo(provider, model, deadlineHandle.signal), deadlineHandle.signal);
+                    if (resolvedInfo === 'aborted') {
+                        // Deadline fired → the timed-out failure; otherwise the invoking
+                        // command was cancelled or the owner/session went away.
+                        if (timeoutOf(deadlineHandle.signal, ADVISOR_MODEL_VALIDATION_TIMEOUT) !== undefined) {
+                            return {
+                                kind: 'failed',
+                                reason: `model validation timed out after ${ADVISOR_MODEL_VALIDATION_TIMEOUT_MS}ms`,
+                            };
+                        }
+                        if (signal?.aborted === true)
+                            return { kind: 'cancelled' };
+                        return { kind: 'gone' };
+                    }
+                }
+                catch (e_1) {
+                    env_1.error = e_1;
+                    env_1.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_1);
+                }
+            }
+            catch (error) {
+                // A rejecting lookup (unknown route, adapter throw) — classify the
+                // same abort vocabulary, else report the failure verbatim.
+                if (signal?.aborted === true)
+                    return { kind: 'cancelled' };
+                if (validationTeardown.signal.aborted)
+                    return { kind: 'gone' };
+                return { kind: 'failed', reason: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                fused.cleanup();
+            }
+            // Fence checks AFTER the lookup settled — session/owner liveness first
+            // (a dispose/reload cannot be undone by a delayed validation completion),
+            // then the generation: a newer set/reset supersedes unresolved older
+            // work while the session is still live.
+            if (validationTeardown.signal.aborted || ctx.agents.get(sessionId) === undefined) {
+                return { kind: 'gone' };
+            }
+            if (overrides.modelGeneration(sessionId) !== generation)
+                return { kind: 'superseded' };
+            // Commit: the route-change effect fires only when the effective pair
+            // actually changed (an equal-default pin is recorded, not restarted).
+            const before = effectiveConfig(sessionId);
+            overrides.setModel(sessionId, { provider, model });
+            applyRouteChange(sessionId, before, agent.session.seq);
+            const status = sessionStatus(sessionId);
+            return before.provider === status.provider && before.model === status.model
+                ? { kind: 'unchanged', status }
+                : { kind: 'committed', status };
+        },
+        // Spec §5.3 — drop the pin and re-inherit the CURRENT global defaults.
+        // Synchronous (no lookup needed). The generation bumps FIRST — a reset is
+        // a newer model command even when there is no pin to remove (noop), so it
+        // supersedes any in-flight validation. Reset never touches the enable
+        // override, and reset to a missing global pair "succeeds" while the
+        // post-reset status reports the gate-blocked/no-call state.
+        resetModel(sessionId, sessionLength) {
+            overrides.beginModelGeneration(sessionId);
+            const before = effectiveConfig(sessionId);
+            if (!overrides.clearModel(sessionId))
+                return { kind: 'noop' };
+            applyRouteChange(sessionId, before, sessionLength);
+            return { kind: 'reset', status: sessionStatus(sessionId) };
         },
         // T2 (plan dsh-advisor-tui-client-n8): the composed-config readback.
-        // Session-less BY DESIGN — reads `safeResolved()` (schema defaults →
-        // plugin-row base → settings user layer, with the hard gate applied),
-        // the SAME bridge source the web card reads through `resolveAdvisorConfig`
-        // (`/api/advisor/get` has no session either). NEVER `effectiveConfig`/
-        // `safeEffective` here: those bake the per-session `/advisor` override
-        // into `enabled`, and a `/advisor off` session toggle must never make
-        // the settings readback misreport settings.yaml. Runtime state stays
-        // owned by `status`; this read reports config only. Every field comes
-        // from that one resolved value; the systemPrompt summary is the first
-        // line (≤ 80 chars) of `resolved.systemPrompt`, '' → unset.
+        // Session-less BY DESIGN — reads `safeResolved()` (the live entry config
+        // with the hard gate applied), the SAME bridge source the web card reads
+        // through `resolveAdvisorConfig` (`/api/advisor/get` has no session
+        // either). NEVER `effectiveConfig`/`safeEffective` here: those bake the
+        // per-session `/advisor` override into `enabled`, and a `/advisor off`
+        // session toggle must never make the config readback misreport the
+        // persisted config. Runtime state stays owned by `status`; this read
+        // reports config only. Every field comes from that one resolved value;
+        // the systemPrompt summary is the first line (≤ 80 chars) of
+        // `resolved.systemPrompt`, '' → unset.
         getConfig() {
             const resolved = safeResolved();
             return {
@@ -541,6 +852,96 @@ export function apply(ctx, config) {
             };
         },
     };
+    // B2 (issue #88 web session control): the elected owner's session face —
+    // the web surface of the SAME `controller` above (`/api/advisor/getSession`
+    // + `/api/advisor/setSessionModel`; selection null = reset). Snapshot reads
+    // ride `sessionStatus` (the resolver SSOT); writes delegate to
+    // `controller.setModel` / `controller.resetModel`, so pre-commit
+    // `resolveModelInfo` validation, per-session generation fencing, and the
+    // route-change semantics are inherited from the B1 command face, never
+    // reimplemented. Liveness is checked BEFORE any controller call (a dead
+    // target must not allocate a generation — `setModel` bumps one on entry),
+    // using the SAME seam the controller's own post-lookup fence uses
+    // (`ctx.agents.get`), so a disposed/unknown session is rejected without
+    // allocating state. SessionId is NOT authorization: the request still
+    // crossed the Connection Host/Origin + browser-auth boundary upstream;
+    // this face adds no ACL layer. Business outcomes ride the returned data
+    // (plugin-domain error tags) — the dsh failure vocabulary stays frozen.
+    const sessionLiveError = (sessionId) => ctx.agents.get(sessionId) === undefined
+        ? advisorSessionError('advisor/session-unknown', `advisor: session ${sessionId} is not live`)
+        : undefined;
+    const snapshotOfStatus = (sessionId, status) => {
+        const effective = status.provider !== undefined && status.model !== undefined
+            ? { provider: status.provider, model: status.model }
+            : undefined;
+        // The pin, when present, always IS the effective route (atomic override),
+        // so `modelSource === 'session'` marks a pinned `modelOverride`. A pin
+        // equal to the global default still reports `session` — the explicit pin
+        // is protected from later default edits.
+        const pinned = status.modelSource === 'session' ? effective : undefined;
+        return {
+            snapshot: {
+                sessionId,
+                enabled: status.enabled,
+                lifetime: 'live-session',
+                ...(pinned === undefined ? {} : { modelOverride: pinned }),
+                ...(status.modelSource === undefined ? {} : { modelSource: status.modelSource }),
+                ...(effective === undefined ? {} : { effectiveModel: effective }),
+                ...(status.disabledReason === undefined ? {} : { disabledReason: status.disabledReason }),
+            },
+        };
+    };
+    const mapSetOutcome = (sessionId, outcome) => {
+        switch (outcome.kind) {
+            case 'committed':
+            case 'unchanged':
+                return snapshotOfStatus(sessionId, outcome.status);
+            case 'rejected':
+                return advisorSessionError('advisor/rejected', `advisor: ${outcome.reason}`);
+            case 'failed':
+                return advisorSessionError('advisor/failed', `advisor: model validation failed — previous selection untouched: ${outcome.reason}`);
+            case 'cancelled':
+                return advisorSessionError('advisor/cancelled', 'advisor: the model set was cancelled — previous selection untouched');
+            case 'superseded':
+                return advisorSessionError('advisor/superseded', 'advisor: superseded by a newer model command — previous selection untouched');
+            case 'gone':
+                return advisorSessionError('advisor/session-unknown', 'advisor: this session is no longer live — selection untouched');
+        }
+    };
+    const mapResetOutcome = (sessionId, outcome) => outcome.kind === 'reset' ? snapshotOfStatus(sessionId, outcome.status) : snapshotOfStatus(sessionId, sessionStatus(sessionId));
+    const sessionControlFace = {
+        getSession(sessionId) {
+            const unknown = sessionLiveError(sessionId);
+            if (unknown !== undefined)
+                return unknown;
+            return snapshotOfStatus(sessionId, sessionStatus(sessionId));
+        },
+        async setSessionModel(sessionId, provider, model) {
+            const unknown = sessionLiveError(sessionId);
+            if (unknown !== undefined)
+                return unknown;
+            const agent = ctx.agents.get(sessionId);
+            if (agent === undefined)
+                return sessionLiveError(sessionId);
+            // No per-request signal: the web RPC has no cancellation wire — the
+            // 60 s deadline and the owner-teardown signal (fused inside setModel)
+            // bound every lookup exactly like the command face's no-signal path.
+            return mapSetOutcome(sessionId, await controller.setModel(sessionId, provider, model, agent));
+        },
+        resetSessionModel(sessionId) {
+            const unknown = sessionLiveError(sessionId);
+            if (unknown !== undefined)
+                return unknown;
+            const agent = ctx.agents.get(sessionId);
+            if (agent === undefined)
+                return sessionLiveError(sessionId);
+            // Reset with no pin is a SUCCESS (`noop`) — the post-reset status
+            // reports the inheriting (possibly gate-blocked) state, matching the
+            // command face's truthfulness.
+            return mapResetOutcome(sessionId, controller.resetModel(sessionId, agent.session.seq));
+        },
+    };
+    sessionControl = sessionControlFace;
     // T7: the command child activates ONLY when a command registry is composed
     // (conditional child activation — `commands` must NOT join the top-level
     // `inject` list, T1 fix). `/advisor` toggle/on/off/status (spec §2 S5).