@cspeach/cli 1.1.32 → 1.1.34

package/dist/sap/onboarding.js

@@ -126,73 +126,79 @@ export async function runAddSapWizard() {
             default: 'approval-gated',
         });
         cfg.write_mode = write_mode;
-        const llm_mode = await select({
-            message: 'How should CSPeach reach the AI model?',
-            choices: [
-                {
-                    name: 'managed (recommended) — we handle the Anthropic account',
-                    value: 'managed',
-                    description: 'Your prompts route through api.cspeach.dev. We bill, we ratelimit, we sign skills. Simplest setup.',
-                },
-                {
-                    name: 'byok — your own Anthropic account',
-                    value: 'byok',
-                    description: 'Your prompts go direct to Anthropic with your API key. You own the contract. Skills signed + fetched from our public manifest.',
-                },
-                {
-                    name: 'ai-hub — your SAP AI Core tenant (endorsed architecture)',
-                    value: 'ai-hub',
-                    description: 'Your prompts route through your SAP BTP AI Core proxy. Data stays in your SAP landscape. Strongest compliance posture (short of SAP Partner Edge).',
-                },
-                {
-                    name: 'local — your own Ollama / vLLM endpoint (air-gap)',
-                    value: 'local',
-                    description: 'No external AI. Skills bundled with the CLI binary. Tool-calling quality depends on the local model.',
-                },
-            ],
-            default: 'managed',
-        });
-        cfg.llm = { mode: llm_mode };
-        if (llm_mode === 'ai-hub') {
-            cfg.llm.ai_hub_base_url = await input({
-                message: 'AI Core proxy URL (e.g. https://proxy.yourcorp.com/v1):',
-                validate: v => v.startsWith('https://') || v.startsWith('http://') ? true : 'Must be a URL',
-            });
-            cfg.llm.ai_hub_model_alias = await input({
-                message: 'AI Core model alias (default: anthropic--claude-opus-4-6):',
-                default: 'anthropic--claude-opus-4-6',
-            });
-            const aiHubToken = await password({
-                message: 'AI Core API token (input masked):',
-                mask: '*',
-            });
-            try {
-                await keychain.setPassword('cspeach.ai-hub', 'token', aiHubToken);
-            }
-            catch {
-                console.log(chalk.yellow('Warning: keychain unavailable; AI Hub token will be prompted per session.'));
-            }
+        if (cfg.llm?.mode === 'azure') {
+            // Azure tenant mode — the company chose the models; the wizard never changes it.
+            console.log(chalk.dim("AI models: your company's Azure (set by your company)."));
         }
-        if (llm_mode === 'local') {
-            cfg.llm.local_base_url = await input({
-                message: 'Local endpoint base URL (default: http://localhost:11434/v1 for Ollama):',
-                default: 'http://localhost:11434/v1',
-            });
-            cfg.llm.local_model = await input({
-                message: 'Model name (e.g. llama3.1:70b):',
-                default: 'llama3.1:70b',
+        else {
+            const llm_mode = await select({
+                message: 'How should CSPeach reach the AI model?',
+                choices: [
+                    {
+                        name: 'managed (recommended) — we handle the Anthropic account',
+                        value: 'managed',
+                        description: 'Your prompts route through api.cspeach.dev. We bill, we ratelimit, we sign skills. Simplest setup.',
+                    },
+                    {
+                        name: 'byok — your own Anthropic account',
+                        value: 'byok',
+                        description: 'Your prompts go direct to Anthropic with your API key. You own the contract. Skills signed + fetched from our public manifest.',
+                    },
+                    {
+                        name: 'ai-hub — your SAP AI Core tenant (endorsed architecture)',
+                        value: 'ai-hub',
+                        description: 'Your prompts route through your SAP BTP AI Core proxy. Data stays in your SAP landscape. Strongest compliance posture (short of SAP Partner Edge).',
+                    },
+                    {
+                        name: 'local — your own Ollama / vLLM endpoint (air-gap)',
+                        value: 'local',
+                        description: 'No external AI. Skills bundled with the CLI binary. Tool-calling quality depends on the local model.',
+                    },
+                ],
+                default: 'managed',
             });
-        }
-        if (llm_mode === 'byok') {
-            const byokKey = await password({
-                message: 'Anthropic API key sk-ant-... (input masked):',
-                mask: '*',
-            });
-            try {
-                await keychain.setPassword('cspeach.anthropic', 'api-key', byokKey);
+            cfg.llm = { mode: llm_mode };
+            if (llm_mode === 'ai-hub') {
+                cfg.llm.ai_hub_base_url = await input({
+                    message: 'AI Core proxy URL (e.g. https://proxy.yourcorp.com/v1):',
+                    validate: v => v.startsWith('https://') || v.startsWith('http://') ? true : 'Must be a URL',
+                });
+                cfg.llm.ai_hub_model_alias = await input({
+                    message: 'AI Core model alias (default: anthropic--claude-opus-4-6):',
+                    default: 'anthropic--claude-opus-4-6',
+                });
+                const aiHubToken = await password({
+                    message: 'AI Core API token (input masked):',
+                    mask: '*',
+                });
+                try {
+                    await keychain.setPassword('cspeach.ai-hub', 'token', aiHubToken);
+                }
+                catch {
+                    console.log(chalk.yellow('Warning: keychain unavailable; AI Hub token will be prompted per session.'));
+                }
+            }
+            if (llm_mode === 'local') {
+                cfg.llm.local_base_url = await input({
+                    message: 'Local endpoint base URL (default: http://localhost:11434/v1 for Ollama):',
+                    default: 'http://localhost:11434/v1',
+                });
+                cfg.llm.local_model = await input({
+                    message: 'Model name (e.g. llama3.1:70b):',
+                    default: 'llama3.1:70b',
+                });
             }
-            catch {
-                console.log(chalk.yellow('Warning: keychain unavailable; Anthropic key will be prompted per session.'));
+            if (llm_mode === 'byok') {
+                const byokKey = await password({
+                    message: 'Anthropic API key sk-ant-... (input masked):',
+                    mask: '*',
+                });
+                try {
+                    await keychain.setPassword('cspeach.anthropic', 'api-key', byokKey);
+                }
+                catch {
+                    console.log(chalk.yellow('Warning: keychain unavailable; Anthropic key will be prompted per session.'));
+                }
             }
         }
     }

package/dist/session/audit-export.js

@@ -31,7 +31,8 @@
 // never an invented approval.
 import { summarise } from '../cost/cost-log.js';
 import { CLI_VERSION } from '../lib/version.js';
-import { creditsActive, formatCredits } from '../cost/credits.js';
+import { creditsActive, tokensOnlyActive, formatCredits } from '../cost/credits.js';
+import { AZURE_INVOICE_LINE } from '../cost/display-mode.js';
 /**
  * Object-mutating tools — one row per completed call in the Writes table.
  * Kept as a literal name set (not the tool registry) so this pure builder
@@ -433,7 +434,13 @@ export function buildAuditReport(input) {
     const auditEntries = costEntries.filter((e) => e.label);
     const auditCost = Math.round(auditEntries.reduce((s, e) => s + e.cost, 0) * 10000) / 10000;
     const inCredits = creditsActive();
-    if (inCredits) {
+    // Azure (Task 5b): tokens only — no price of ours for the customer's deployments.
+    const tokensOnly = tokensOnlyActive();
+    const noPrice = inCredits || tokensOnly;
+    if (tokensOnly) {
+        L(`- **Total:** ${AZURE_INVOICE_LINE} · ${cost.turns} turn${cost.turns === 1 ? '' : 's'}`);
+    }
+    else if (inCredits) {
         const unit = credits?.unitLabel ?? 'credits';
         const logged = costEntries.reduce((s, e) => s + (typeof e.credits_charged === 'number' ? e.credits_charged : 0), 0);
         const total = credits && credits.sessionTotal > 0 ? credits.sessionTotal : logged;
@@ -449,14 +456,14 @@ export function buildAuditReport(input) {
     if (auditEntries.length > 0) {
         // Credits mode: the labelled-audit turn COUNT is still useful provenance;
         // its USD cost is not ours to publish to a customer.
-        L(inCredits
+        L(noPrice
             ? `- **Includes** ${auditEntries.length} labelled audit turn${auditEntries.length === 1 ? '' : 's'}`
             : `- **Includes** ${auditEntries.length} labelled audit turn${auditEntries.length === 1 ? '' : 's'}: $${auditCost.toFixed(4)}`);
     }
     if (cost.byModel.length > 1) {
         L('- **By model:**');
         for (const m of cost.byModel) {
-            L(inCredits
+            L(noPrice
                 ? `  - ${m.model}: ${m.turns} turn${m.turns === 1 ? '' : 's'}`
                 : `  - ${m.model}: ${m.turns} turn${m.turns === 1 ? '' : 's'} · $${m.cost.toFixed(4)}`);
         }

package/dist/skills/manifest-client.js

@@ -6,6 +6,31 @@ import { MANIFEST_PUBLIC_KEYS } from './signing-public-key.js';
 import { canonicalise } from './canonical.js';
 // @noble/ed25519 v2 requires an ed25519 sha512 hook.
 ed.etc.sha512Sync = (...m) => sha512(concatBytes(...m));
+/**
+ * A body that does not match its signed manifest entry. Fail closed: never
+ * loaded, never cached, and deliberately NOT a "skills unavailable" error, so
+ * it can never open the public fallback or the disk cache. Hashes stay out of
+ * the user message (they go to `debug`, written only to the debug log).
+ */
+export class SkillIntegrityError extends Error {
+    debug;
+    constructor(debug) {
+        super('This skill failed its integrity check and was not loaded. Update CSPeach or contact support.');
+        this.name = 'SkillIntegrityError';
+        this.debug = debug;
+    }
+}
+/**
+ * The manifest could not be fetched: a network failure or a 5xx (incl. 503
+ * "not yet published"). Task 8 — the ONLY manifest failure the on-disk skills
+ * cache may cover. A bad signature, a 4xx or bad JSON never is.
+ */
+export class ManifestUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ManifestUnavailableError';
+    }
+}
 export class ManifestClient {
     manifestUrl;
     constructor(manifestUrl) {
@@ -17,21 +42,29 @@ export class ManifestClient {
             r = await fetch(this.manifestUrl, { signal: AbortSignal.timeout(10_000) });
         }
         catch (e) {
-            throw new Error(`manifest fetch failed (${this.manifestUrl}): ${e.message}`);
+            throw new ManifestUnavailableError(`manifest fetch failed (${this.manifestUrl}): ${e.message}`);
         }
         if (r.status === 503) {
             const body = await r.json().catch(() => ({}));
             const raw = String(body.error ?? 'server says not ready');
             // Cap length — an untrusted server could flood the error message.
             const safe = raw.length > 200 ? raw.slice(0, 200) + '…' : raw;
-            throw new Error(`manifest not yet published (HTTP 503): ${safe}`);
+            throw new ManifestUnavailableError(`manifest not yet published (HTTP 503): ${safe}`);
         }
+        if (r.status >= 500)
+            throw new ManifestUnavailableError(`manifest fetch: HTTP ${r.status} from ${this.manifestUrl}`);
         if (!r.ok)
             throw new Error(`manifest fetch: HTTP ${r.status} from ${this.manifestUrl}`);
         return await r.json();
     }
     async fetchAndVerifyManifest() {
-        const m = await this.fetchManifest();
+        return this.verifyManifest(await this.fetchManifest());
+    }
+    /**
+     * Verify a manifest's ed25519 signature — fetched just now or read from the
+     * on-disk skills cache (Task 8). Works offline.
+     */
+    async verifyManifest(m) {
         const { signature, ...payload } = m;
         const canonical = canonicalise(payload);
         const canonicalBytes = new TextEncoder().encode(canonical);
@@ -82,7 +115,7 @@ export class ManifestClient {
         // the manifest-anchored expected value, constitutes an integrity check.
         const actualSha = bytesToHex(sha256(new TextEncoder().encode(j.body)));
         if (opts.expectedSha256 !== actualSha) {
-            throw new Error(`skill ${name}: sha256 mismatch with manifest (manifest=${opts.expectedSha256}, computed=${actualSha}) — body may have been tampered in transit`);
+            throw new SkillIntegrityError(`skill ${name}: sha256 mismatch with manifest (manifest=${opts.expectedSha256}, computed=${actualSha}) — body may have been tampered in transit`);
         }
         return { name, body: j.body, sha256: actualSha, signature: '', signedAt: j.updated_at };
     }

package/dist/skills/skills-cache.js

@@ -0,0 +1,115 @@
+/**
+ * Security batch item 2 — <CSPeach home>/skills-cache/ for byok, ai-hub and
+ * local. manifest.json (re-verified with its ed25519 signature on every load)
+ * plus one <skill>.json per body. A body loads only when its sha256 AND
+ * updated_at match the signed manifest entry; anything else is refetched.
+ * Offline use works from here within the licence check's 72-hour grace.
+ *
+ * The cache is never a trust anchor: a stored hash is never read back (the
+ * body is re-hashed every load), a corrupt or edited file loads nothing, and
+ * a name that is not a plain skill name never becomes a path.
+ *
+ * No TTL by design: the licence turn-gate (72-hour grace) bounds offline use.
+ */
+import { promises as fs } from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { cspeachRoot } from '../config/paths.js';
+const SAFE_NAME = /^[a-z0-9_-]{1,64}$/;
+const MANIFEST_FILE = 'manifest.json';
+/** A *.tmp older than this is a crash leftover (a live write renames within ms). */
+const STALE_TMP_MS = 60_000;
+/** A plain skill name, and never the manifest's own file name. */
+function safeName(name) {
+    return typeof name === 'string' && SAFE_NAME.test(name) && `${name}.json` !== MANIFEST_FILE;
+}
+export function skillsCacheDir() {
+    return path.join(cspeachRoot(), 'skills-cache');
+}
+const manifestFile = () => path.join(skillsCacheDir(), MANIFEST_FILE);
+const bodyFile = (name) => path.join(skillsCacheDir(), `${name}.json`);
+async function writeAtomic(p, text) {
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    // Unique per write (as key-resolver writeMeta): two writes in one process
+    // must never share a temp file.
+    const tmp = `${p}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    try {
+        await fs.writeFile(tmp, text, { encoding: 'utf-8', mode: 0o600 });
+        await fs.rename(tmp, p);
+    }
+    finally {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+    }
+}
+export const fileSkillsCache = {
+    async saveManifest(m) {
+        await writeAtomic(manifestFile(), JSON.stringify(m)).catch(() => { });
+    },
+    async loadManifest(verify) {
+        let parsed;
+        try {
+            parsed = JSON.parse(await fs.readFile(manifestFile(), 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+        if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.skills))
+            return null;
+        try {
+            return await verify(parsed);
+        }
+        catch {
+            return null;
+        }
+    },
+    async loadBody(entry) {
+        if (!safeName(entry.name))
+            return null;
+        try {
+            const c = JSON.parse(await fs.readFile(bodyFile(entry.name), 'utf-8'));
+            if (c.name !== entry.name || typeof c.body !== 'string' || c.updated_at !== entry.updated_at)
+                return null;
+            const actual = bytesToHex(sha256(new TextEncoder().encode(c.body)));
+            if (actual !== entry.sha256)
+                return null;
+            return { name: entry.name, body: c.body, sha256: actual, signature: '', signedAt: typeof c.signedAt === 'string' ? c.signedAt : '' };
+        }
+        catch {
+            return null;
+        }
+    },
+    async saveBody(entry, body) {
+        if (!safeName(entry.name))
+            return;
+        await writeAtomic(bodyFile(entry.name), JSON.stringify({ name: entry.name, body: body.body, updated_at: entry.updated_at, signedAt: body.signedAt })).catch(() => { });
+    },
+    async removeBody(name) {
+        if (!safeName(name))
+            return;
+        await fs.rm(bodyFile(name), { force: true }).catch(() => { });
+    },
+    async prune(m) {
+        const keep = new Set([MANIFEST_FILE, ...m.skills.filter((s) => safeName(s.name)).map((s) => `${s.name}.json`)]);
+        let removed = 0;
+        try {
+            for (const f of await fs.readdir(skillsCacheDir())) {
+                const p = path.join(skillsCacheDir(), f);
+                if (f.endsWith('.json') && !keep.has(f)) {
+                    await fs.rm(p, { force: true });
+                    removed++;
+                }
+                else if (f.endsWith('.tmp')) {
+                    const st = await fs.stat(p).catch(() => null);
+                    if (st && Date.now() - st.mtimeMs > STALE_TMP_MS) {
+                        await fs.rm(p, { force: true });
+                        removed++;
+                    }
+                }
+            }
+        }
+        catch { /* no cache yet */ }
+        return removed;
+    },
+};

package/dist/skills/source-authed.js

@@ -0,0 +1,276 @@
+/**
+ * Security batch item 2 — skill text only for signed-in seats (byok, ai-hub,
+ * local). The manifest stays public and signed (older CLIs verify it, and the
+ * routing list comes from it). Bodies come from GET /v1/skills/:name with the
+ * CSPeach bearer, and each body's sha256 is checked against the SIGNED
+ * manifest entry — the server-claimed hash is never trusted.
+ *
+ * Public bodies (manifest.cspeach.dev/v1/skills-public/…) are read only with
+ * CSPEACH_SKILLS_PUBLIC_FALLBACK=1, for one release; the route returns 410 in
+ * the next. Honest limit: any licensed seat can read the skill text — this is
+ * licence compliance, not secrecy.
+ */
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { ManifestClient, DEFAULT_MANIFEST_URL, SkillIntegrityError, ManifestUnavailableError, } from './manifest-client.js';
+import { fileSkillsCache } from './skills-cache.js';
+// Defined next to the client that throws it (Task 8 (a): typed, never string-matched).
+export { SkillIntegrityError };
+export class SkillNotInPlanError extends Error {
+    constructor(name) {
+        super(`The skill /${name} is not in your CSPeach plan. Ask your admin to add it.`);
+        this.name = 'SkillNotInPlanError';
+    }
+}
+export class SkillsUnavailableError extends Error {
+    constructor(detail) {
+        super(`Skills can't be loaded right now (${detail}). Try again in a few minutes.`);
+        this.name = 'SkillsUnavailableError';
+    }
+}
+/**
+ * The server answered, but not with a usable skill: a 4xx other than 401/403
+ * (404, 429, …) or a 200 without skill text. Deliberately NOT a
+ * SkillsUnavailableError: only network failures and 5xx may open the disk
+ * cache or the public fallback.
+ */
+export class SkillFetchError extends Error {
+    constructor(detail) {
+        super(`Skills can't be loaded right now (${detail}). Try again in a few minutes.`);
+        this.name = 'SkillFetchError';
+    }
+}
+export class SkillSignInError extends Error {
+    constructor() {
+        super('CSPeach did not accept your sign-in for skills. Run cspeach login.');
+        this.name = 'SkillSignInError';
+    }
+}
+export function publicFallbackEnabled(env = process.env) {
+    return env.CSPEACH_SKILLS_PUBLIC_FALLBACK === '1';
+}
+/** The one resolver's key (Task 4), for providers built without a bearer. */
+export async function defaultBearer() {
+    const { getStore } = await import('../auth/api-key.js');
+    return (await (await getStore()).get()) ?? '';
+}
+const FETCH_TIMEOUT_MS = 10_000;
+/** GET /v1/skills/:name with the CSPeach bearer; the body is hashed against the SIGNED manifest entry. */
+async function fetchSignedInBody(baseUrl, name, expectedSha, getBearer, doFetch) {
+    // A missing key is a sign-in problem, settled before any network call.
+    let bearer;
+    try {
+        bearer = await getBearer();
+    }
+    catch {
+        throw new SkillSignInError();
+    }
+    if (typeof bearer !== 'string' || bearer.trim() === '')
+        throw new SkillSignInError();
+    let r;
+    try {
+        r = await doFetch(`${baseUrl}/v1/skills/${encodeURIComponent(name)}`, {
+            headers: { Authorization: `Bearer ${bearer}` },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new SkillsUnavailableError('could not reach CSPeach');
+    }
+    if (r.status === 403)
+        throw new SkillNotInPlanError(name);
+    if (r.status === 401)
+        throw new SkillSignInError();
+    if (r.status >= 500)
+        throw new SkillsUnavailableError(`the server answered ${r.status}`);
+    if (!r.ok)
+        throw new SkillFetchError(`the server answered ${r.status}`);
+    const j = await r.json().catch(() => null);
+    if (!j || typeof j.body !== 'string')
+        throw new SkillFetchError('the answer had no skill text');
+    const actual = bytesToHex(sha256(new TextEncoder().encode(j.body)));
+    if (actual !== expectedSha) {
+        throw new SkillIntegrityError(`skill ${name}: sha256 mismatch with the signed manifest (manifest=${expectedSha}, computed=${actual})`);
+    }
+    return { name, body: j.body, sha256: actual, signature: '', signedAt: typeof j.signedAt === 'string' ? j.signedAt : '' };
+}
+export function createAuthedSkillSource(cfg, getBearer, deps = {}) {
+    const manifestUrl = deps.manifestUrl ?? DEFAULT_MANIFEST_URL;
+    const client = deps.client ?? new ManifestClient(manifestUrl);
+    const doFetch = deps.fetchImpl ?? fetch;
+    const env = deps.env ?? process.env;
+    const cache = deps.cache === undefined ? fileSkillsCache : deps.cache;
+    const baseUrl = cfg.proxy_url.replace(/\/$/, '');
+    let manifest = null;
+    const memory = new Map();
+    // The existing debug channel (CSPEACH_DEBUG=1 → stderr). Never user output.
+    function debugIntegrity(err) {
+        if (env.CSPEACH_DEBUG !== '1')
+            return;
+        process.stderr.write(`[skills] ${err.debug}\n`);
+    }
+    async function getManifest() {
+        if (manifest)
+            return manifest;
+        try {
+            manifest = await client.fetchAndVerifyManifest();
+            if (cache) {
+                await cache.saveManifest(manifest);
+                await cache.prune(manifest);
+            }
+        }
+        catch (err) {
+            // Only "could not reach it" (network / 5xx) may use the disk copy. A bad
+            // signature, a 4xx or bad JSON never does.
+            if (!(err instanceof ManifestUnavailableError))
+                throw err;
+            const fromDisk = cache ? await cache.loadManifest((m) => client.verifyManifest(m)) : null;
+            if (!fromDisk)
+                throw err;
+            manifest = fromDisk; // offline: the signed copy on disk, re-verified just now
+        }
+        return manifest;
+    }
+    const fetchSignedIn = (name, expectedSha) => fetchSignedInBody(baseUrl, name, expectedSha, getBearer, doFetch);
+    async function fetchPublic(name, entry) {
+        try {
+            return await client.fetchSkillBody(name, entry.body_url, { expectedSha256: entry.sha256 });
+        }
+        catch (err) {
+            if (err instanceof SkillIntegrityError)
+                throw err;
+            if (/HTTP 410\b/.test(String(err?.message))) {
+                throw new SkillsUnavailableError('the public skill route is retired; run cspeach login and unset CSPEACH_SKILLS_PUBLIC_FALLBACK');
+            }
+            throw new SkillsUnavailableError('the public skill source did not answer');
+        }
+    }
+    return {
+        async getSkillBody(name) {
+            const m = await getManifest();
+            const entry = m.skills.find((s) => s.name === name);
+            if (!entry)
+                throw new Error(`skill '${name}' not found in manifest (available: ${m.skills.map((s) => s.name).join(', ')})`);
+            const inMemory = memory.get(name);
+            if (inMemory && inMemory.sha256 === entry.sha256)
+                return inMemory;
+            let body;
+            try {
+                try {
+                    body = await fetchSignedIn(name, entry.sha256);
+                    if (cache)
+                        await cache.saveBody(entry, body);
+                }
+                catch (err) {
+                    // No longer in the plan: drop the cached copy so a later outage
+                    // cannot serve it.
+                    if (err instanceof SkillNotInPlanError && cache)
+                        await cache.removeBody(name);
+                    // Network / 5xx: a valid cached copy first (hash-checked against the
+                    // signed manifest), then — only with the switch — the public body.
+                    // 401 / 403 / a hash mismatch never fall back.
+                    if (!(err instanceof SkillsUnavailableError))
+                        throw err;
+                    const fromDisk = cache ? await cache.loadBody(entry) : null;
+                    if (fromDisk)
+                        body = fromDisk;
+                    else if (publicFallbackEnabled(env))
+                        body = await fetchPublic(name, entry);
+                    else
+                        throw err;
+                }
+            }
+            catch (err) {
+                if (err instanceof SkillIntegrityError)
+                    debugIntegrity(err);
+                throw err;
+            }
+            memory.set(name, body);
+            return body;
+        },
+        async listAvailableSkills() {
+            return (await getManifest()).skills.map((s) => s.name);
+        },
+        describe() {
+            return `signed manifest at ${manifestUrl}; bodies from ${baseUrl} for signed-in seats`;
+        },
+    };
+}
+// ── Skills cache warm-up (final review finding 1) ─────────────────────────
+// "Sign in once, then work offline": after an ok licence verdict in byok /
+// ai-hub / local, fill the disk cache with every skill body that is missing or
+// out of date — through the same signed-in, hash-checked fetch and the same
+// cache as getSkillBody. Fire-and-forget: never awaited on the start-up or
+// turn path, every error swallowed, at most once per process. Managed does no
+// work at all (its skills come from the proxy on every request).
+const WARM_CONCURRENCY = 4;
+export async function warmSkillsCache(cfg, getBearer, deps = {}, opts = {}) {
+    const result = { fetched: 0, skipped: 0, stopped: null };
+    const cache = deps.cache === undefined ? fileSkillsCache : deps.cache;
+    if (!cache)
+        return result;
+    const client = deps.client ?? new ManifestClient(deps.manifestUrl ?? DEFAULT_MANIFEST_URL);
+    const doFetch = deps.fetchImpl ?? fetch;
+    const baseUrl = cfg.proxy_url.replace(/\/$/, '');
+    let m;
+    try {
+        m = await client.fetchAndVerifyManifest();
+        await cache.saveManifest(m);
+        await cache.prune(m);
+    }
+    catch {
+        return result; // offline or a bad manifest: nothing to warm
+    }
+    // One key read for the whole warm-up, not one per skill.
+    let bearerP = null;
+    const bearerOnce = () => (bearerP ??= getBearer());
+    const queue = [...m.skills];
+    const worker = async () => {
+        for (let entry = queue.shift(); entry && !result.stopped; entry = queue.shift()) {
+            try {
+                if (await cache.loadBody(entry)) {
+                    result.skipped++;
+                    continue;
+                }
+                const body = await fetchSignedInBody(baseUrl, entry.name, entry.sha256, bearerOnce, doFetch);
+                await cache.saveBody(entry, body);
+                result.fetched++;
+            }
+            catch (err) {
+                // Coordinator ruling: only a 401 / sign-in failure stops the warm-up.
+                if (err instanceof SkillSignInError)
+                    result.stopped = 'sign-in';
+                // 403: this one skill is not in the plan — drop any cached copy (as
+                // getSkillBody does) and carry on with the rest.
+                else if (err instanceof SkillNotInPlanError)
+                    await cache.removeBody(entry.name).catch(() => { });
+                // 5xx / network, a hash mismatch or another 4xx: skip this body, carry
+                // on, never retry; nothing is cached for it.
+            }
+        }
+    };
+    const n = Math.max(1, Math.min(opts.concurrency ?? WARM_CONCURRENCY, queue.length));
+    await Promise.all(Array.from({ length: n }, worker));
+    return result;
+}
+let warmStarted = false;
+/** Test hook: forget that this process already warmed. */
+export function _resetSkillsWarmupForTests() {
+    warmStarted = false;
+}
+/**
+ * Start the warm-up when the mode is not managed and the licence verdict is
+ * ok. Returns at once: null when nothing was started, else a promise that
+ * never rejects (callers drop it; tests await it).
+ */
+export function startSkillsCacheWarmup(cfg, verdict, opts = {}) {
+    if (cfg.llm.mode === 'managed' || verdict !== 'ok' || warmStarted)
+        return null;
+    warmStarted = true;
+    try {
+        return warmSkillsCache(cfg, opts.getBearer ?? defaultBearer, opts.deps).then(() => undefined, () => undefined);
+    }
+    catch {
+        return Promise.resolve();
+    }
+}