@cspeach/cli 0.9.0 → 1.1.0

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: {},
@@ -26,6 +28,13 @@ const DEFAULT_CONFIG = {
     write_mode: 'approval-gated',
     // Default `managed` — lowest-friction entry point; uses the cspeach.dev proxy.
     llm: { mode: 'managed' },
+    // local_build is intentionally NOT defaulted here. If it were set to `false`,
+    // the `...DEFAULT_CONFIG` spread would leave merged.local_build defined even
+    // when the file omits the key — which permanently defeats resolveLocalBuild's
+    // `local_build ?? local_files` fallback (the legacy `local_files = on` case
+    // could never fire). Absence must stay `undefined` so the fallback can read
+    // the legacy key. The effective default-off is enforced by resolveLocalBuild
+    // (returns false when both are undefined). See loadConfig coercion below.
     // Defaults tuned 2026-05-16 from session 0618a42d evidence — see CompactConfig doc.
     compact: {
         keep_recent_turns: 5,
@@ -62,6 +71,25 @@ function sanitiseCompact(raw) {
         min_turns_between_auto: intInRange(r.min_turns_between_auto, d.min_turns_between_auto, 1, 100),
     };
 }
+/**
+ * Resolve the effective TLS options for a SAP system, applying the legacy
+ * `sslVerify: false` → insecure mapping. A configured `ca_cert_path` always
+ * wins (verification on). Pure — no I/O. Shared by the connection-manager and
+ * doctor checks so they agree on the posture.
+ */
+export function resolveSapTls(sys) {
+    if (sys.ca_cert_path) {
+        return { mode: 'ca-trusted', caCertPath: sys.ca_cert_path, insecureSkipTlsVerify: false };
+    }
+    // Explicit insecure opt-in, OR the legacy sslVerify:false mapping.
+    const insecure = sys.insecure_skip_tls_verify === true || sys.sslVerify === false;
+    if (insecure) {
+        return { mode: 'insecure', insecureSkipTlsVerify: true };
+    }
+    return { mode: 'verify', insecureSkipTlsVerify: false };
+}
+/** Tracks whether the one-time legacy-sslVerify deprecation note has printed. */
+let legacySslVerifyNoticeShown = false;
 export async function loadConfig() {
     try {
         const raw = await fs.readFile(configFile(), 'utf-8');
@@ -87,10 +115,75 @@ export async function loadConfig() {
         else {
             allow = [];
         }
-        return {
+        const merged = {
             ...DEFAULT_CONFIG,
             ...parsed,
+            // Coerce defensively, but PRESERVE the absent→undefined distinction so the
+            // legacy fallback in resolveLocalBuild can fire:
+            //   - explicit `true`                → true
+            //   - explicit `false`/off           → false (defined; overrides legacy)
+            //   - present-but-invalid (string)   → false (defined; fails safe, can't
+            //     grant access via a typo, but DOES override a stale legacy on)
+            //   - absent / undefined             → undefined (legacy fallback applies)
+            // A defined `false` (whether explicit or typo) must win the
+            // `local_build ?? local_files` resolution so an explicit off is honoured.
+            local_build: parsed.local_build === true
+                ? true
+                : parsed.local_build === undefined
+                    ? undefined
+                    : false,
+            // Preserve a legacy `local_files` value (read-only backward compat) ONLY
+            // 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 ?? {}) },
@@ -100,14 +193,139 @@ export async function loadConfig() {
             compact: sanitiseCompact(parsed.compact),
             shell_exec: parsed.shell_exec === undefined ? undefined : { allow },
         };
+        // Drop the legacy `local_files` key entirely when it isn't a genuine on
+        // (the `...parsed` spread above can leave a `local_files = false` behind,
+        // and our explicit coercion sets it to `undefined`). Removing the key keeps
+        // `config show` and saveConfig output clean — no `local_files = undefined`.
+        if (merged.local_files === undefined)
+            delete merged.local_files;
+        // Same for `local_build`: when the key is absent from disk we coerce it to
+        // `undefined` (so resolveLocalBuild's legacy fallback can fire). Delete the
+        // key so it doesn't serialise as `local_build = undefined` and so callers
+        // 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
+        // once per process toward `ca_cert_path` (preferred) or the explicit
+        // insecure flag. Only fires when sslVerify is present AND no new key is set.
+        if (!legacySslVerifyNoticeShown) {
+            const legacyAlias = Object.entries(merged.sap ?? {}).find(([, s]) => typeof s?.sslVerify === 'boolean' &&
+                s.ca_cert_path === undefined &&
+                s.insecure_skip_tls_verify === undefined);
+            if (legacyAlias) {
+                legacySslVerifyNoticeShown = true;
+                const [alias, sys] = legacyAlias;
+                const suggestion = sys.sslVerify === false
+                    ? `set 'ca_cert_path' to your corporate CA (keeps verification ON), or set 'insecure_skip_tls_verify = true' to keep verification off (dev only, logs a warning)`
+                    : `the default is now verify-ON; you can drop 'sslVerify' or set 'ca_cert_path' for internal-CA systems`;
+                process.stderr.write(`[cspeach] note: [sap.${alias}] uses the deprecated 'sslVerify' key — ${suggestion}.\n`);
+            }
+        }
+        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;
     }
 }
+/**
+ * Resolve the effective "local build tools" toggle from a loaded config.
+ *
+ * Backward compat (2026-06-13 rename): the new key is `local_build`; the legacy
+ * key is `local_files`. A user who set `local_files = on` before the rename
+ * must keep working without re-running `config set`. The rule is:
+ *
+ *     effective = local_build ?? local_files   (default false)
+ *
+ * `local_build` always wins when present (so `config set local_build off`
+ * overrides a stale legacy `local_files = on`). Only when `local_build` is
+ * undefined does the legacy value apply. Both keys are already strictly coerced
+ * to `true | undefined` by loadConfig, so this is a pure read.
+ */
+export function resolveLocalBuild(cfg) {
+    if (cfg.local_build !== undefined)
+        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/_http-probe.js

@@ -35,6 +35,7 @@ export function probeGet(url, opts) {
             path: u.pathname + u.search,
             timeout: opts.timeoutMs ?? 8000,
             rejectUnauthorized: opts.rejectUnauthorized,
+            ...(opts.ca !== undefined ? { ca: opts.ca } : {}),
             headers,
         }, (res) => {
             const chunks = [];

package/dist/doctor/checks/cert.js

@@ -1,5 +1,5 @@
 import tls from 'node:tls';
-import { loadConfig } from '../../config/loader.js';
+import { loadConfig, resolveSapTls } from '../../config/loader.js';
 export async function checkCert() {
     const cfg = await loadConfig();
     const systems = Object.entries(cfg.sap).filter(([_, s]) => s.useSsl);
@@ -7,14 +7,25 @@ export async function checkCert() {
         return { name: 'cert', ok: true, message: 'n/a (no TLS SAP systems configured)' };
     const results = [];
     for (const [alias, sys] of systems) {
+        const tlsMode = resolveSapTls(sys);
         const info = await new Promise((resolve) => {
+            // Probe with rejectUnauthorized:false so we can always read the cert and
+            // report the OS-trust chain status, then describe the configured posture
+            // separately (verify / CA-trusted / INSECURE).
             const socket = tls.connect({ host: sys.host, port: sys.port, rejectUnauthorized: false, timeout: 5000 }, () => {
                 const cert = socket.getPeerCertificate();
                 const authorized = socket.authorized;
                 socket.end();
                 const chainValid = authorized ? 'yes' : 'no';
-                const clientAccepted = !sys.sslVerify ? 'yes (trust-manager allows self-signed)' : (authorized ? 'yes' : 'no');
-                resolve(`${alias}: chain valid: ${chainValid} / client accepted: ${clientAccepted} / subject: ${cert.subject?.CN ?? '?'}`);
+                // What the configured client mode means for acceptance:
+                //   verify     → accepts only if the OS/Node trust chain validates
+                //   CA-trusted → accepts via the configured CA (verification ON)
+                //   INSECURE   → accepts anything (verification OFF — dev only)
+                const clientAccepted = tlsMode.mode === 'insecure' ? 'yes (INSECURE — verification disabled, dev only)'
+                    : tlsMode.mode === 'ca-trusted' ? 'yes (CA-trusted — verification ON via configured CA)'
+                        : (authorized ? 'yes' : 'no (verify ON — configure ca_cert_path to trust an internal CA)');
+                resolve(`${alias}: mode: ${tlsMode.mode} / chain valid: ${chainValid} / ` +
+                    `client accepted: ${clientAccepted} / subject: ${cert.subject?.CN ?? '?'}`);
             });
             socket.on('error', (err) => resolve(`${alias}: ${err.message}`));
         });

package/dist/doctor/checks/sap.js

@@ -1,4 +1,5 @@
-import { loadConfig } from '../../config/loader.js';
+import { readFile } from 'node:fs/promises';
+import { loadConfig, resolveSapTls } from '../../config/loader.js';
 import { probeGet } from './_http-probe.js';
 export async function checkSap() {
     const cfg = await loadConfig();
@@ -9,23 +10,44 @@ export async function checkSap() {
     let anyFailed = false;
     for (const [alias, sys] of systems) {
         const url = `${sys.useSsl ? 'https' : 'http'}://${sys.host}:${sys.port}/sap/bc/adt/discovery`;
-        // Use node's https directly so we can honor sslVerify=false for
-        // self-signed dev systems — Node's built-in fetch() doesn't expose a
-        // per-request TLS-verify toggle. See checks/_http-probe.ts.
+        // TLS posture (2026-06-14): verification ON by default. resolveSapTls maps
+        // the per-alias config (ca_cert_path / insecure_skip_tls_verify, legacy
+        // sslVerify:false fallback). Node's built-in fetch() doesn't expose a
+        // per-request TLS-verify toggle, so we use node's https directly — see
+        // checks/_http-probe.ts.
+        const tls = resolveSapTls(sys);
+        // Tag the connectivity result with the cert mode so doctor surfaces it.
+        const modeTag = tls.mode === 'verify' ? 'verify'
+            : tls.mode === 'ca-trusted' ? 'CA-trusted'
+                : 'INSECURE';
+        let ca;
+        if (tls.mode === 'ca-trusted' && tls.caCertPath) {
+            try {
+                ca = await readFile(tls.caCertPath);
+            }
+            catch (e) {
+                // Fail closed, like the connection path: a configured-but-unreadable CA
+                // is an error, not a reason to drop verification.
+                results.push(`${alias}: CA unreadable at ${tls.caCertPath} (${e.message})`);
+                anyFailed = true;
+                continue;
+            }
+        }
         const r = await probeGet(url, {
-            rejectUnauthorized: sys.sslVerify,
+            rejectUnauthorized: tls.mode !== 'insecure',
+            ca,
             timeoutMs: 8000,
         });
         if (r.error) {
-            results.push(`${alias}: ${r.error}`);
+            results.push(`${alias}: ${r.error} [${modeTag}]`);
             anyFailed = true;
         }
         else if (r.status === 200 || r.status === 401) {
             // 200 = anonymous discovery allowed; 401 = reachable + auth-required (expected, fine)
-            results.push(`${alias}: reachable`);
+            results.push(`${alias}: reachable [${modeTag}]`);
         }
         else {
-            results.push(`${alias}: HTTP ${r.status}`);
+            results.push(`${alias}: HTTP ${r.status} [${modeTag}]`);
             anyFailed = true;
         }
     }

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/checks/zcspeach.js

@@ -1,5 +1,6 @@
 import keytar from 'keytar';
-import { loadConfig } from '../../config/loader.js';
+import { readFile } from 'node:fs/promises';
+import { loadConfig, resolveSapTls } from '../../config/loader.js';
 import { probeGet } from './_http-probe.js';
 const SAP_SERVICE = 'cspeach-sap';
 export async function checkZcspeach() {
@@ -29,10 +30,24 @@ export async function checkZcspeach() {
             results.push(`${alias}: skipped (no password in keychain)`);
             continue;
         }
-        // Use node's https directly so we can honor sslVerify=false for
-        // self-signed dev systems. See checks/_http-probe.ts.
+        // TLS posture (2026-06-14): verification ON by default; resolveSapTls maps
+        // the per-alias config (ca_cert_path / insecure_skip_tls_verify, legacy
+        // sslVerify:false fallback). See checks/_http-probe.ts.
+        const tls = resolveSapTls(sys);
+        let ca;
+        if (tls.mode === 'ca-trusted' && tls.caCertPath) {
+            try {
+                ca = await readFile(tls.caCertPath);
+            }
+            catch (e) {
+                results.push(`${alias}: CA unreadable at ${tls.caCertPath} (${e.message})`);
+                anyFailed = true;
+                continue;
+            }
+        }
         const r = await probeGet(url, {
-            rejectUnauthorized: sys.sslVerify,
+            rejectUnauthorized: tls.mode !== 'insecure',
+            ca,
             auth: `${sys.username}:${pwd}`,
             accept: 'application/json',
             timeoutMs: 5000,

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;
+        }
+    }
+}