@cspeach/cli 1.0.0 → 1.1.1

package/dist/config/loader.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises';
+import { isDeepStrictEqual } from 'node:util';
 import toml from '@iarna/toml';
 import { configFile, cspeachRoot } from './paths.js';
+import { DEFAULT_SESSION_MODEL } from './model-defaults.js';
 /**
  * Whitelist guard for WriteMode — rejects typos / stale values from disk so
  * downstream code that trusts the WriteMode type doesn't see garbage.
@@ -9,9 +11,9 @@ import { configFile, cspeachRoot } from './paths.js';
 export function isValidWriteMode(v) {
     return v === 'auto' || v === 'approval-gated' || v === 'advisory-only';
 }
-const DEFAULT_CONFIG = {
+export const DEFAULT_CONFIG = {
     proxy_url: 'https://api.cspeach.dev',
-    default_model: 'claude-opus-4-8',
+    default_model: DEFAULT_SESSION_MODEL,
     effort: 'xhigh',
     telemetry: 'minimal',
     sap: {},
@@ -134,7 +136,54 @@ export async function loadConfig() {
             // when it's strictly true — a string/typo collapses to "absent" so it
             // can't win the `local_build ?? local_files` fallback.
             local_files: parsed.local_files === true ? true : undefined,
+            // render_smoke: plain boolean, DEFAULT true (no legacy alias). Preserve
+            // only a genuine boolean; a typo/wrong-type collapses to undefined which
+            // resolveRenderSmoke reads as the default ON (fail-safe: a config typo can
+            // never silently disable the smoke).
+            render_smoke: typeof parsed.render_smoke === 'boolean' ? parsed.render_smoke : undefined,
             write_mode: isValidWriteMode(parsed.write_mode) ? parsed.write_mode : DEFAULT_CONFIG.write_mode,
+            // plan_mode: whitelist coercion — anything but the two valid literals
+            // (typos, wrong types) collapses to undefined, which callers treat as
+            // 'step' (fail-safe: a config typo can only make chaining MORE manual).
+            plan_mode: parsed.plan_mode === 'step' || parsed.plan_mode === 'guarded'
+                ? parsed.plan_mode
+                : undefined,
+            // plan_audit: whitelist coercion — anything but the two valid literals
+            // (typos, wrong types) collapses to undefined, which callers treat as
+            // 'on' (fail-safe: a config typo can only leave audits ON, never off).
+            plan_audit: parsed.plan_audit === 'on' || parsed.plan_audit === 'off'
+                ? parsed.plan_audit
+                : undefined,
+            // audit_model: preserve only a non-empty string (trimmed); a wrong-type /
+            // empty value collapses to undefined so resolveAuditModel reads the safe
+            // Sonnet default. Mirrors the optional-key hygiene of plan_mode/render_smoke.
+            audit_model: typeof parsed.audit_model === 'string' && parsed.audit_model.trim().length > 0
+                ? parsed.audit_model.trim()
+                : undefined,
+            // compact_model: mirrors audit_model — preserve only a non-empty trimmed
+            // string; a wrong-type / empty value collapses to undefined so
+            // resolveModelRole reads the safe Haiku default.
+            compact_model: typeof parsed.compact_model === 'string' && parsed.compact_model.trim().length > 0
+                ? parsed.compact_model.trim()
+                : undefined,
+            // default_model_set: INTERNAL flag — true iff the FILE carried the
+            // `default_model` key (file presence, not the value). Lets an explicit user
+            // choice beat a served roles.session_default. Stripped by saveConfig.
+            default_model_set: Object.prototype.hasOwnProperty.call(parsed, 'default_model'),
+            // sap: ALWAYS a fresh top-level object, never the shared DEFAULT_CONFIG.sap
+            // reference. Without this, a file lacking `[sap.*]` would leave
+            // `merged.sap === DEFAULT_CONFIG.sap`; the onboarding wizard then mutating
+            // `cfg.sap[alias] = {...}` would poison the module constant, and saveConfig's
+            // `isDeepStrictEqual(writable.sap, DEFAULT_CONFIG.sap)` would compare the
+            // object to itself → true → drop the just-added system. Alias sub-objects
+            // come fresh from toml.parse (or are whole-object assignments in onboarding),
+            // so a fresh container suffices — no deep clone of the aliases needed.
+            sap: { ...(parsed.sap ?? {}) },
+            // file_keys: INTERNAL — the top-level keys the FILE carried, snapshotted
+            // from `parsed` BEFORE the merge (so the absent-key `delete merged.x`
+            // hygiene below never affects it). Drives sparse serialisation in
+            // saveConfig; stripped there so it never reaches config.toml.
+            file_keys: Object.keys(parsed),
             llm: { ...DEFAULT_CONFIG.llm, ...(parsed.llm ?? {}) },
             classifier: { ...DEFAULT_CONFIG.classifier, ...(parsed.classifier ?? {}) },
             ui: { ...DEFAULT_CONFIG.ui, ...(parsed.ui ?? {}) },
@@ -156,6 +205,40 @@ export async function loadConfig() {
         // see a clean "absent" shape. resolveLocalBuild treats missing === undefined.
         if (merged.local_build === undefined)
             delete merged.local_build;
+        // Same for `render_smoke`: absent-or-invalid must not serialise as
+        // `render_smoke = undefined` — drop the key so `config show` stays clean and
+        // callers see a genuine "absent" shape (resolveRenderSmoke treats it as ON).
+        if (merged.render_smoke === undefined)
+            delete merged.render_smoke;
+        // Same for `plan_mode`: absent-or-invalid must not serialise as
+        // `plan_mode = undefined` — drop the key so `config show` stays clean and
+        // callers see a genuine "absent" shape (treated as 'step').
+        if (merged.plan_mode === undefined)
+            delete merged.plan_mode;
+        // Same for `plan_audit`: absent-or-invalid must not serialise as
+        // `plan_audit = undefined` — drop the key so `config show` stays clean and
+        // callers see a genuine "absent" shape (treated as 'on').
+        if (merged.plan_audit === undefined)
+            delete merged.plan_audit;
+        // Same for `audit_model`: absent-or-invalid must not serialise as
+        // `audit_model = undefined` — drop the key so `config show` stays clean and
+        // callers see a genuine "absent" shape (resolveAuditModel reads the default).
+        if (merged.audit_model === undefined)
+            delete merged.audit_model;
+        // Same for `compact_model`: absent-or-invalid must not serialise as
+        // `compact_model = undefined` — drop the key so `config show` stays clean and
+        // callers see a genuine "absent" shape (resolveModelRole reads the default).
+        if (merged.compact_model === undefined)
+            delete merged.compact_model;
+        // Per-alias `role`: whitelist coercion — anything but the three valid
+        // literals (typos like "production", wrong types) collapses to absent, so
+        // downstream ceiling logic sees a clean `undefined` (= no ceiling, same
+        // behavior as before roles existed). Mirrors the plan_mode pattern.
+        for (const sys of Object.values(merged.sap ?? {})) {
+            if (sys.role !== 'dev' && sys.role !== 'qas' && sys.role !== 'prd') {
+                delete sys.role;
+            }
+        }
         // One-time deprecation note: a SAP system still relies on the legacy
         // `sslVerify` toggle and has not adopted either new key. It KEEPS WORKING
         // (resolveSapTls maps sslVerify:false → insecure), but we nudge the user
@@ -177,8 +260,16 @@ export async function loadConfig() {
         return merged;
     }
     catch (err) {
+        // Absent file → defaults with an empty file_keys snapshot (nothing was
+        // user-set), so saveConfig(loadConfig()) on a missing file writes a minimal
+        // file rather than baking every default in. DEEP-copy so a first-ever nested
+        // mutation on a fresh install (onboarding `cfg.sap[alias] = …`, `cfg.llm.mode
+        // = …`, `cfg.ui.rendering = …`) can never poison the shared DEFAULT_CONFIG
+        // constant — which would make saveConfig's deep-equal check compare a table to
+        // itself and silently drop the user's data. A shallow spread shares every
+        // nested table by reference and is NOT safe here.
         if (err?.code === 'ENOENT')
-            return DEFAULT_CONFIG;
+            return { ...structuredClone(DEFAULT_CONFIG), file_keys: [] };
         throw err;
     }
 }
@@ -201,7 +292,40 @@ export function resolveLocalBuild(cfg) {
         return cfg.local_build === true;
     return cfg.local_files === true;
 }
+/**
+ * Resolve the effective `render_smoke` toggle (Track 2 D-4). Unlike
+ * `local_build`, this has NO legacy alias, so the rule is a plain default-true:
+ *
+ *     effective = render_smoke ?? true
+ *
+ * `render_smoke` is already coerced to `true | false | undefined` by loadConfig
+ * (a typo collapses to undefined), so absent/typo → ON and only an explicit
+ * `false` turns the browser-driven smoke into a skipped manual result.
+ */
+export function resolveRenderSmoke(cfg) {
+    return cfg.render_smoke ?? true;
+}
 export async function saveConfig(config) {
     await fs.mkdir(cspeachRoot(), { recursive: true });
-    await fs.writeFile(configFile(), toml.stringify(config), 'utf-8');
+    // The set of top-level keys the FILE carried (empty when it was absent).
+    // A key stays in the file if the user had it there OR its value now differs
+    // from the built-in default — see the sparse rule below.
+    const fileKeys = config.file_keys ?? [];
+    // Strip the INTERNAL flags — both are derived on load (file presence /
+    // file-key snapshot) and must never be written back into config.toml.
+    const { default_model_set: _dropSet, file_keys: _dropKeys, ...toWrite } = config;
+    // Sparse serialisation: drop any key that the file did NOT carry AND whose
+    // value is deep-equal to the built-in default. Keys absent from DEFAULT_CONFIG
+    // (optional keys like audit_model) never deep-equal a defined value, so any
+    // set value is written. This keeps `config set <one key>` from baking every
+    // default (notably default_model) into config.toml and opting the user out of
+    // the model-governance server steering. All four saveConfig callers set
+    // non-default values, so the value-diff side keeps them working unchanged.
+    const writable = toWrite;
+    for (const k of Object.keys(writable)) {
+        if (!fileKeys.includes(k) && isDeepStrictEqual(writable[k], DEFAULT_CONFIG[k])) {
+            delete writable[k];
+        }
+    }
+    await fs.writeFile(configFile(), toml.stringify(writable), 'utf-8');
 }

package/dist/config/model-defaults.js

@@ -0,0 +1,14 @@
+// model-governance step 2d (2026-07-10) — the session-default built-in model id,
+// factored into a leaf module so it has ONE source of truth without forcing
+// resolve.ts to import it from loader.ts.
+//
+// Why not import DEFAULT_CONFIG from loader.ts directly: several tests fully
+// mock '../config/loader.js' (e.g. classifier-confidence.integration), and a
+// total mock does not re-export DEFAULT_CONFIG. resolveModelRole runs inside
+// those test paths (via one-shot.ts / repl.tsx), so reading DEFAULT_CONFIG from
+// the mocked module would throw "No DEFAULT_CONFIG export defined on the mock".
+// This leaf module is never mocked, so both loader.ts (which builds
+// DEFAULT_CONFIG from it) and resolve.ts read the identical constant — no
+// duplication, no drift, no mock fragility.
+/** The built-in session-default model id — today's DEFAULT_CONFIG.default_model. */
+export const DEFAULT_SESSION_MODEL = 'claude-opus-4-8';

package/dist/cost/pricing.js

@@ -22,6 +22,7 @@
  * Unknown models → returns null + records the model name to a process-level
  * Set so we surface them as an obvious warning rather than silently zeroing.
  */
+import { getServerModelConfig } from '../models/server-config.js';
 const PRICING = {
     // Claude Opus 4.5+ — input 5, output 25, cache_read 0.50, cache_write 6.25 (1.25x input).
     // 2026-06-07 correction: 4.5/4.6/4.7 were carried at the LEGACY $15/$75; actual
@@ -42,6 +43,20 @@ const PRICING = {
     'claude-haiku-4': { inputPer1M: 1.00, outputPer1M: 5.00, cacheReadPer1M: 0.10, cacheCreatePer1M: 1.25 },
 };
 const seenUnknownModels = new Set();
+/**
+ * Normalise a served rate (whose `cacheCreatePer1M` is optional in the proxy
+ * shape) to the CLI's full ModelRate. When the served entry omits the cache
+ * write rate we derive it as 1.25× input — the same convention this file's
+ * built-in table applies per Anthropic's docs.
+ */
+function fromServerRate(r) {
+    return {
+        inputPer1M: r.inputPer1M,
+        outputPer1M: r.outputPer1M,
+        cacheReadPer1M: r.cacheReadPer1M,
+        cacheCreatePer1M: r.cacheCreatePer1M ?? r.inputPer1M * 1.25,
+    };
+}
 /**
  * Look up a per-1M-token rate for a model. Normalises to lowercase and
  * strips Anthropic's optional `-YYYYMMDD` date suffix so e.g.
@@ -53,9 +68,20 @@ const seenUnknownModels = new Set();
  */
 export function getRate(model) {
     const normalized = model.toLowerCase();
+    const stripDate = normalized.replace(/-\d{8}$/, '');
+    // Served model-governance map wins over the built-in table (model-governance
+    // step 4). Same normalization as the built-in path: lowercase + strip the
+    // optional `-YYYYMMDD` date suffix. The built-in PRICING below stays as the
+    // offline fallback (locked decision Q4). The snapshot is sync (server-config
+    // module snapshot), so getRate stays sync.
+    const served = getServerModelConfig()?.pricing;
+    if (served) {
+        const hit = served[normalized] ?? served[stripDate];
+        if (hit)
+            return fromServerRate(hit);
+    }
     if (PRICING[normalized])
         return PRICING[normalized];
-    const stripDate = normalized.replace(/-\d{8}$/, '');
     if (PRICING[stripDate])
         return PRICING[stripDate];
     if (!seenUnknownModels.has(normalized)) {

package/dist/doctor/checks/system-roles.js

@@ -0,0 +1,41 @@
+/**
+ * Doctor check: system-roles (UX Wave 1, Task 1).
+ *
+ * Surfaces the per-alias `role` (dev | qas | prd) that feeds the write-mode
+ * ceiling (repl/mode-ceiling.ts): prd → advisory-only, qas → approval-gated,
+ * dev/unset → no ceiling.
+ *
+ * An alias WITHOUT a role is a warn, not a failure — the ceiling only ADDS
+ * restriction, so "unset" is a valid (if risky-on-prd-boxes) configuration.
+ * Warn renders via the yellow skipped state (ok:false + skipped:true), which
+ * never counts toward the doctor's failed total. Pure — no I/O beyond cfg.
+ */
+export async function checkSystemRoles(cfg) {
+    const entries = Object.entries(cfg.sap ?? {});
+    if (entries.length === 0) {
+        return {
+            name: 'system-roles',
+            ok: false,
+            skipped: true,
+            message: 'no SAP system configured',
+            hint: 'Run: cspeach config add-sap',
+        };
+    }
+    const unset = entries.filter(([, sys]) => sys.role === undefined).map(([alias]) => alias);
+    const set = entries.filter(([, sys]) => sys.role !== undefined);
+    if (unset.length === 0) {
+        return {
+            name: 'system-roles',
+            ok: true,
+            message: `roles set: ${set.map(([alias, sys]) => `${alias}=${sys.role}`).join(', ')}`,
+        };
+    }
+    // Warn-level: yellow, never fails doctor.
+    return {
+        name: 'system-roles',
+        ok: false,
+        skipped: true,
+        message: `${unset.join(', ')}: role unset: treated as dev (no ceiling)`,
+        hint: `set with cspeach config set sap.${unset[0]}.role prd|qas|dev`,
+    };
+}

package/dist/doctor/run.js

@@ -11,6 +11,7 @@ import { checkKeychainFallback } from './checks/keychain-fallback.js';
 import { checkWriteMode } from './checks/write-mode.js';
 import { checkLlmMode } from './checks/llm-mode.js';
 import { checkForgeRules } from './checks/forge-rules.js';
+import { checkSystemRoles } from './checks/system-roles.js';
 export async function runDoctor() {
     console.log(chalk.cyan.bold('\nCSPeach — doctor\n'));
     const cfg = await loadConfig();
@@ -19,6 +20,7 @@ export async function runDoctor() {
     checks.push(await checkAuth());
     checks.push(await checkLlmMode(cfg));
     checks.push(await checkWriteMode(cfg));
+    checks.push(await checkSystemRoles(cfg));
     checks.push(await checkKeychain());
     checks.push(await checkSap());
     checks.push(await checkZcspeach());

package/dist/models/resolve.js

@@ -0,0 +1,61 @@
+// model-governance step 2d (2026-07-10) — the generalized role→model resolver.
+//
+// resolveAuditModel (commands/plan-audit.ts) was the prototype: a pure function
+// that layered env > local config > built-in for ONE role. This generalizes it
+// to every CLI pipeline role and inserts the SERVED config (server-config.ts's
+// module snapshot) as a new layer BELOW local config and ABOVE the built-in
+// constant:
+//
+//     env  >  local config  >  server  >  built-in constant
+//
+// Locked invariant: with NOTHING set (no env, default_model_set false, no server
+// snapshot) every role resolves to today's constant — byte-identical to before
+// this feature.
+//
+// Pure in the resolveAuditModel sense: no async I/O, no fetch. The only external
+// read is getServerModelConfig(), a synchronous in-memory snapshot the caller
+// (or the startup fetch) has already populated. `router` is proxy-side only and
+// is deliberately NOT a CLI role.
+import { DEFAULT_SESSION_MODEL } from '../config/model-defaults.js';
+import { PLAN_TIER_SONNET_MODEL } from '../commands/plan-model-tier.js';
+import { COMPACTION_MODEL } from '../commands/compact.js';
+import { getServerModelConfig } from './server-config.js';
+/** First non-empty (trimmed) candidate in precedence order, else the built-in. */
+function firstSet(candidates, builtin) {
+    for (const c of candidates) {
+        const t = c?.trim();
+        if (t)
+            return t;
+    }
+    return builtin;
+}
+/**
+ * Resolve the model for a pipeline role. Precedence: env > local config >
+ * server > built-in constant.
+ *
+ * `session_default` reads the local `default_model` ONLY when `default_model_set`
+ * is true — i.e. the user's config file explicitly carried the key. The value
+ * that the DEFAULT_CONFIG merge supplies (when the file omits the key) must NOT
+ * beat the server, which is what lets an admin-served default apply while an
+ * explicit user choice (even one equal to the built-in) still wins.
+ */
+export function resolveModelRole(role, cfg, env = process.env) {
+    const server = getServerModelConfig();
+    switch (role) {
+        case 'session_default':
+            return firstSet([
+                env.CSPEACH_DEFAULT_MODEL,
+                cfg.default_model_set ? cfg.default_model : undefined,
+                server?.roles.session_default,
+            ], DEFAULT_SESSION_MODEL);
+        case 'audit':
+            return firstSet([env.CSPEACH_AUDIT_MODEL, cfg.audit_model, server?.roles.audit], PLAN_TIER_SONNET_MODEL);
+        case 'compact':
+            return firstSet([env.CSPEACH_COMPACT_MODEL, cfg.compact_model, server?.roles.compact], COMPACTION_MODEL);
+        default: {
+            // Exhaustiveness guard — a new ModelRole must extend the switch.
+            const _never = role;
+            return _never;
+        }
+    }
+}

package/dist/models/server-config.js

@@ -0,0 +1,155 @@
+// model-governance step 2d (2026-07-10) — the CLI-side reader for the served
+// model-governance config.
+//
+// The proxy serves `GET {proxy_url}/v1/model-config` (Task 3):
+//   { roles: { session_default, audit, compact, router },
+//     pricing: Record<model, { inputPer1M, outputPer1M, cacheReadPer1M, cacheCreatePer1M? }>,
+//     updated_at }
+// top-level keys snake_case, pricing entries camelCase, Cache-Control 60s, no auth.
+//
+// This module fetches that config ONCE at startup (fire-and-forget from repl.tsx
+// / one-shot.ts) and holds it in a synchronous module snapshot that
+// resolveModelRole (resolve.ts) reads. Precedence-wise the served config sits
+// BELOW env + local config and ABOVE the built-in constants — so nothing set ⇒
+// built-ins ⇒ byte-identical to before this feature.
+//
+// Fail-safe contract (locked):
+//   - managed mode ONLY — non-managed modes (byok/local/ai-hub) never fetch.
+//   - startup is NEVER blocked on the fetch: a turn that starts before the fetch
+//     lands simply uses the built-ins.
+//   - on ANY failure (timeout, network, non-2xx, malformed) fall back to a disk
+//     cache written by the last good fetch, but only if it is < 24h old; else
+//     leave the snapshot null (built-ins win).
+//   - loadServerModelConfig NEVER throws.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { cspeachRoot } from '../config/paths.js';
+// ── Synchronous module snapshot ───────────────────────────────────────────────
+let snapshot = null;
+/** The current served-config snapshot, or null (⇒ built-ins win). Pure sync read. */
+export function getServerModelConfig() {
+    return snapshot;
+}
+/** Test-only setter for the module snapshot. */
+export function __setServerModelConfigForTests(c) {
+    snapshot = c;
+}
+// ── Constants ─────────────────────────────────────────────────────────────────
+const FETCH_TIMEOUT_MS = 5_000;
+const CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+function cacheFilePath() {
+    return path.join(cspeachRoot(), 'model-config.json');
+}
+const ROLE_KEYS = ['session_default', 'audit', 'compact', 'router'];
+// ── Coercion ──────────────────────────────────────────────────────────────────
+/** Keep only string, non-empty role entries; unknown keys are dropped. */
+function coerceRoles(raw) {
+    const out = {};
+    if (!raw || typeof raw !== 'object')
+        return out;
+    const r = raw;
+    for (const k of ROLE_KEYS) {
+        const v = r[k];
+        if (typeof v === 'string' && v.trim().length > 0)
+            out[k] = v.trim();
+    }
+    return out;
+}
+function coercePricing(raw) {
+    return raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : {};
+}
+/**
+ * Map a served (or cached) document to a ServerModelConfig, or null when the
+ * shape is unusable. `fetchedAt`, when provided, is preserved (disk-cache read);
+ * otherwise a fresh client timestamp is stamped (live fetch). A document with
+ * NO recognised role is treated as unusable (null) — there is nothing to serve.
+ */
+function coerceDocument(body, fetchedAt) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const b = body;
+    const roles = coerceRoles(b.roles);
+    if (Object.keys(roles).length === 0)
+        return null;
+    return {
+        roles,
+        pricing: coercePricing(b.pricing),
+        fetchedAt: typeof fetchedAt === 'string' && fetchedAt.length > 0 ? fetchedAt : new Date().toISOString(),
+    };
+}
+// ── Disk cache (net-new; whole-document atomic tmp+rename, same as session/store) ─
+async function writeDiskCache(c) {
+    const dir = cspeachRoot();
+    await fs.mkdir(dir, { recursive: true });
+    const file = cacheFilePath();
+    const tmp = `${file}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(c, null, 2), 'utf-8');
+    await fs.rename(tmp, file);
+}
+/** Read the disk cache, returning it ONLY when parseable AND < 24h old. */
+async function readFreshDiskCache() {
+    let parsed;
+    try {
+        const raw = await fs.readFile(cacheFilePath(), 'utf-8');
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null; // absent or corrupt/unparseable = no cache
+    }
+    const fetchedAt = parsed && typeof parsed === 'object'
+        ? parsed.fetchedAt
+        : undefined;
+    const doc = coerceDocument(parsed, typeof fetchedAt === 'string' ? fetchedAt : undefined);
+    if (!doc)
+        return null;
+    const age = Date.now() - Date.parse(doc.fetchedAt);
+    if (!Number.isFinite(age) || age < 0 || age >= CACHE_MAX_AGE_MS)
+        return null;
+    return doc;
+}
+// ── Public entrypoint ─────────────────────────────────────────────────────────
+/**
+ * Fetch the served model-config and update the module snapshot. Managed mode
+ * ONLY. Fire-and-forget from startup; NEVER throws.
+ */
+export async function loadServerModelConfig(cfg) {
+    // Non-managed modes bypass the proxy for inference and must never fetch.
+    if (cfg.llm?.mode !== 'managed')
+        return;
+    try {
+        // URL construction lives INSIDE the try: a degenerate config (e.g. a
+        // non-string proxy_url that loader.ts never coerced) would otherwise throw
+        // synchronously out of this fire-and-forget call and become an unhandled
+        // rejection that crashes startup. Keep it caught like every other failure.
+        const url = `${cfg.proxy_url.replace(/\/$/, '')}/v1/model-config`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        timer.unref?.();
+        let body;
+        try {
+            const r = await fetch(url, { signal: controller.signal });
+            if (!r.ok)
+                throw new Error(`model-config fetch: status ${r.status}`);
+            body = await r.json();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const doc = coerceDocument(body);
+        if (!doc)
+            throw new Error('model-config fetch: malformed payload');
+        snapshot = doc;
+        // Best-effort cache write — a cache-write failure must not fail the fetch.
+        await writeDiskCache(doc).catch(() => { });
+        return;
+    }
+    catch {
+        // On ANY failure fall back to a fresh (<24h) disk cache; else leave the
+        // snapshot as-is (null at startup) so the built-ins win.
+        const cached = await readFreshDiskCache();
+        if (cached)
+            snapshot = cached;
+    }
+}

package/dist/one-shot.js

@@ -5,6 +5,8 @@ import { getConnection } from './sap/connection-manager.js';
 import { AdtClient } from '@cspeach/sap-client';
 import { makeSessionId, saveSession } from './session/store.js';
 import { newSession } from './session/schema.js';
+import { resolveModelRole } from './models/resolve.js';
+import { loadServerModelConfig } from './models/server-config.js';
 import { createProviderForMode } from './agent/providers/factory.js';
 import { assertModeLicensed, CspeachLicenseError } from './agent/providers/license-gate.js';
 import { runTurn } from './agent/loop.js';
@@ -12,7 +14,9 @@ import { classifyPrompt, parseShortcut, rejectUnknownSkill } from './router/clas
 import { setRenderingOverride, setHeadlessOverride } from './renderer/tty.js';
 import { alwaysDeclinePreviewHook } from './repl/update-method-preview-hook.js';
 import { createClassicOutputEmitter } from './renderer/notices.js';
+import { todoEmitter } from './ui/todo-emitter.js';
 import { applyLocalBuildConfig } from './tools/local-build.js';
+import { getEffectiveWriteMode } from './repl/mode-cycle.js';
 // Side-effect imports for tool registration.
 import './tools/sap-read.js';
 import './tools/sap-write.js';
@@ -21,6 +25,7 @@ import './tools/approval.js';
 import './tools/snapshot.js';
 import './tools/ask-question.js';
 import './tools/dispatch-skill.js';
+import './tools/todo.js';
 import './tools/filesystem/file-read.js';
 import './tools/filesystem/read-document.js';
 import './tools/filesystem/file-edit.js';
@@ -46,6 +51,10 @@ import './tools/subagent/agent_run.js';
 export async function runOneShot(prompt, opts) {
     const cfg = await loadConfig();
     setRenderingOverride(cfg.ui.rendering);
+    // model-governance step 2d — fire-and-forget fetch of the served model-config
+    // (managed mode only, never blocks). A turn that starts before it lands uses
+    // the built-ins (fail-safe).
+    void loadServerModelConfig(cfg);
     // B5 (2026-06-11) — one-shot is headless by design: a single turn, no
     // REPL, often piped (CI / battery). Any stdin prompt would hang forever
     // (defect D1). The headless answer policy (ask_question auto-answers,
@@ -54,7 +63,16 @@ export async function runOneShot(prompt, opts) {
     // Task C.10 — advisory-only is the only mode the one-shot announces, because
     // non-interactive output should stay minimal. The user needs to know that
     // writes will NOT be executed before a skill that normally writes runs.
-    if (cfg.write_mode === 'advisory-only') {
+    //
+    // Task 3 (ux-wave1) — gate on the EFFECTIVE mode: one-shot's alias choice is
+    // deterministic (--sap-alias or first configured), so the role clamp can be
+    // computed here. A prd alias makes the run advisory even when the config
+    // says gated/auto — the banner must say so. No role ⇒ effective === config
+    // (byte-identical). Alias absent (no SAP configured) ⇒ error out below,
+    // same as before.
+    const oneShotAlias = opts?.sapAlias ?? Object.keys(cfg.sap)[0];
+    const oneShotRole = oneShotAlias !== undefined ? cfg.sap[oneShotAlias]?.role : undefined;
+    if (getEffectiveWriteMode(cfg.write_mode, oneShotRole) === 'advisory-only') {
         console.log(chalk.yellow('⚠  Advisory mode: writes will be proposed, not executed.'));
     }
     // local_build toggle — force-enable the flag-gated filesystem tools AND
@@ -84,7 +102,7 @@ export async function runOneShot(prompt, opts) {
     }
     const conn = await getConnection(alias, cfg.sap[alias]);
     const adt = new AdtClient(conn);
-    const session = newSession(makeSessionId(), alias, null, cfg.default_model);
+    const session = newSession(makeSessionId(), alias, null, resolveModelRole('session_default', cfg));
     await saveSession(session);
     const parsed = parseShortcut(prompt);
     const body = parsed.prompt;
@@ -152,7 +170,11 @@ export async function runOneShot(prompt, opts) {
         // B2 fix (2026-06-12): one-shot runs render tool notices ('warn'/'info'
         // — Rule 9 transport overrides, snapshot lines) to stdout instead of
         // dropping them. Headless transcripts need these for auditability.
-        ctx: { adt, sapAlias: alias, session, cwd: process.cwd(), provider, skillSource: provider.skillSource, previewHook: alwaysDeclinePreviewHook, chunkEmitter: createClassicOutputEmitter() },
+        // Task 5 (ux-wave2): todoEmitter wired for the uniform top-level-ctx
+        // contract — no listener exists in one-shot, so emits are no-ops, but
+        // "top-level ctxs carry it / subagent ctxs omit it" stays the single
+        // rule (see ui/todo-emitter.ts).
+        ctx: { adt, sapAlias: alias, session, cwd: process.cwd(), provider, skillSource: provider.skillSource, previewHook: alwaysDeclinePreviewHook, chunkEmitter: createClassicOutputEmitter(), todoEmitter },
     });
     return 0;
 }

package/dist/projects/extract-cca.js

@@ -30,7 +30,9 @@
  * Parsing is permissive — missing optional fields produce defaults; a
  * missing manifest block throws so callers know to surface the error.
  */
-const MANIFEST_RE = /<!--\s*csforge:cca-manifest\s*\n([\s\S]*?)\n\s*-->/;
+// E2 dual-read: accept both the legacy `csforge:` and current `cspeach:`
+// prefixes (legacy acceptance is permanent — old saved artifacts carry it).
+const MANIFEST_RE = /<!--\s*(?:csforge|cspeach):cca-manifest\s*\n([\s\S]*?)\n\s*-->/;
 function parseManifestBlock(markdown) {
     const m = MANIFEST_RE.exec(markdown);
     if (!m) {

package/dist/projects/extract-modernize.js

@@ -27,7 +27,9 @@
  * Parsing is permissive — missing optional fields produce defaults; a
  * missing manifest block throws so callers know to surface the error.
  */
-const MANIFEST_RE = /<!--\s*csforge:modernize-manifest\s*\n([\s\S]*?)\n\s*-->/;
+// E2 dual-read: accept both the legacy `csforge:` and current `cspeach:`
+// prefixes (legacy acceptance is permanent — old saved artifacts carry it).
+const MANIFEST_RE = /<!--\s*(?:csforge|cspeach):modernize-manifest\s*\n([\s\S]*?)\n\s*-->/;
 function parseManifestBlock(markdown) {
     const m = MANIFEST_RE.exec(markdown);
     if (!m) {