peaks-loop 4.0.42 → 4.0.43

package/dist/services/audit/audit-goal-service.js

@@ -31,19 +31,39 @@ const REQUIRED_DIMENSIONS = [
     'alternatives',
     'constraints'
 ];
+/**
+ * The allowed values for the three constrained fields.
+ *
+ * These are stated in the prompt AND enforced below: a prompt alone is a
+ * request, not a gate. Before this, the prompt named only `severity` with no
+ * allowed values, the model answered `severity: "high"`, and the gate passed
+ * it — leaving every downstream consumer that switches on
+ * `info | concern | blocker` holding a value it has never seen.
+ */
+const SEVERITIES = ['info', 'concern', 'blocker'];
+const EFFORTS = ['small', 'medium', 'large', 'epic'];
+const CONFIDENCES = ['high', 'medium', 'low'];
 const SYSTEM_PROMPT = `You are auditing a software development need. Produce a structured JSON response with EXACTLY these fields:
 - summary (1-2 sentence summary of the need)
 - audit (array of EXACTLY 6 objects, one per dimension: correctness, completeness, scope, risks, alternatives, constraints; each with dimension, finding, severity)
 - proposedGoal (what success looks like)
 - successCriteria (list of acceptance criteria)
-- roughEffort (small | medium | large | epic)
-- confidence (high | medium | low)
+- roughEffort (one of exactly: small | medium | large | epic)
+- confidence (one of exactly: high | medium | low)
 - rationale (one paragraph tying audit to goal)
 
+severity is one of exactly: info | concern | blocker. Do not invent other values.
+Any value outside the lists above is rejected and the whole response is discarded — a value that is merely plausible is not acceptable.
+
 Output ONLY valid JSON, no prose.`;
 export async function auditGoal(input, llmRunner) {
     const userPrompt = `Need: ${input.need}\n\nAudit this need across the 6 dimensions and propose a goal.`;
-    const response = await llmRunner.call(SYSTEM_PROMPT, userPrompt, { maxTokens: 2000 });
+    // 8000, not 2000: the reply is a six-dimension JSON audit, and a reasoning
+    // model shares this budget with its own thinking blocks — measured against
+    // the session's provider, a 2000-token cap returns `stop_reason: max_tokens`
+    // with the JSON cut off mid-string. That is still ONE bounded call; it is
+    // just one the model can finish.
+    const response = await llmRunner.call(SYSTEM_PROMPT, userPrompt, { maxTokens: 8000 });
     let parsed;
     try {
         parsed = JSON.parse(response.output);
@@ -59,6 +79,21 @@ export async function auditGoal(input, llmRunner) {
     if (missing.length > 0) {
         throw new IncompleteAuditError(`Missing required audit dimensions: ${missing.join(', ')}`);
     }
+    // Coverage is not validity: a reply can carry all six dimensions and still
+    // hand downstream consumers enum values that do not exist. An out-of-enum
+    // value fails here — it is never coerced into a valid one, because silently
+    // repairing the model's output is what makes the enum decorative.
+    for (const entry of parsed.audit) {
+        if (!SEVERITIES.includes(entry.severity)) {
+            throw new IncompleteAuditError(`Invalid severity for dimension "${entry.dimension}": ${JSON.stringify(entry.severity)}. Allowed values: ${SEVERITIES.join(', ')}.`);
+        }
+    }
+    if (!EFFORTS.includes(parsed.roughEffort)) {
+        throw new IncompleteAuditError(`Invalid roughEffort: ${JSON.stringify(parsed.roughEffort)}. Allowed values: ${EFFORTS.join(', ')}.`);
+    }
+    if (!CONFIDENCES.includes(parsed.confidence)) {
+        throw new IncompleteAuditError(`Invalid confidence: ${JSON.stringify(parsed.confidence)}. Allowed values: ${CONFIDENCES.join(', ')}.`);
+    }
     return parsed;
 }
 function isAuditGoalOutput(value) {

package/dist/services/doctor/doctor-service/checks/ecc-hooks-schema-drift.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Check: the third-party ECC plugin ships `hooks/hooks.json` keys that
+ * Claude Code's plugin hook schema ignores
+ * (`integration:ecc-hooks-schema-drift`).
+ *
+ * 2026-09-12 — Claude Code prints this at startup when the ECC plugin
+ * (github.com/affaan-m/ECC) is installed:
+ *
+ *   ecc: hooks.json: unknown keys "$schema", "description" in
+ *   hooks.PreToolUse[0], "id" in hooks.PreToolUse[0], ... and 42 more ignored
+ *
+ * Claude Code's plugin hook schema accepts exactly `{ matcher, hooks }`
+ * on a matcher group, and at the document root `hooks` plus an OPTIONAL
+ * top-level `description`. ECC ships a
+ * root `$schema` plus `description` AND `id` on each of its 23 matcher
+ * groups across 7 events — 47 ignored keys, matching the warning
+ * verbatim. The warning is cosmetic (the 23 hooks still load).
+ *
+ * peaks-loop does NOT write this file, and every ECC release checked
+ * (v2.2.0 / v2.2.1 / main) carries the same keys, so upgrading the
+ * plugin does not clear the warning. This check exists so a user who
+ * hits the startup line does not have to re-investigate it from
+ * scratch.
+ *
+ * Probing is split out of the check so the check itself stays a pure
+ * mapping over `EccHooksDriftProbeResult`. Tests inject the probe to
+ * keep the real `~/.claude/plugins/` tree out of fixtures.
+ */
+import type { DoctorCheckPlugin, EccHooksDriftProbeResult } from '../types.js';
+/**
+ * Unknown keys found in a plugin `hooks.json`. Mirrors the shape of
+ * Claude Code's own startup warning so the doctor message can name the
+ * same things.
+ */
+export type EccHooksDriftFinding = {
+    /** Total ignored keys (`rootKeys` + every unknown key on every matcher group). */
+    readonly unknownKeyCount: number;
+    /** Unknown keys directly under the document root (e.g. `$schema`). */
+    readonly rootKeys: ReadonlyArray<string>;
+    /** Distinct unknown keys seen on matcher groups (e.g. `description`, `id`). */
+    readonly entryKeys: ReadonlyArray<string>;
+    /** Matcher groups carrying at least one unknown key. */
+    readonly entryCount: number;
+};
+/**
+ * Pure mapping over a parsed plugin `hooks.json` payload. Exported so
+ * tests drive the key scan without touching the real plugin tree.
+ */
+export declare function findEccHooksSchemaDrift(payload: unknown): EccHooksDriftFinding;
+/**
+ * Resolve the ECC plugin's install path from Claude Code's plugin
+ * manifest (`~/.claude/plugins/installed_plugins.json`), which is the
+ * only version-agnostic way to find the versioned cache directory
+ * (`…/plugins/cache/ecc/ecc/<version>/`). Exported so tests drive the
+ * lookup with an explicit manifest path.
+ */
+export declare function readEccInstallPath(manifestPath: string): string | null;
+/**
+ * Default probe: reads the ECC plugin manifest + its `hooks/hooks.json`.
+ * `homeDir` is injectable so tests can drive the real probe against a
+ * temp dir; the zero-arg call keeps using the real homedir, so the
+ * function stays assignable to `EccHooksDriftProbe`.
+ */
+export declare function defaultEccHooksDriftProbe(homeDir?: string): EccHooksDriftProbeResult;
+export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/ecc-hooks-schema-drift.js

@@ -0,0 +1,186 @@
+/**
+ * Check: the third-party ECC plugin ships `hooks/hooks.json` keys that
+ * Claude Code's plugin hook schema ignores
+ * (`integration:ecc-hooks-schema-drift`).
+ *
+ * 2026-09-12 — Claude Code prints this at startup when the ECC plugin
+ * (github.com/affaan-m/ECC) is installed:
+ *
+ *   ecc: hooks.json: unknown keys "$schema", "description" in
+ *   hooks.PreToolUse[0], "id" in hooks.PreToolUse[0], ... and 42 more ignored
+ *
+ * Claude Code's plugin hook schema accepts exactly `{ matcher, hooks }`
+ * on a matcher group, and at the document root `hooks` plus an OPTIONAL
+ * top-level `description`. ECC ships a
+ * root `$schema` plus `description` AND `id` on each of its 23 matcher
+ * groups across 7 events — 47 ignored keys, matching the warning
+ * verbatim. The warning is cosmetic (the 23 hooks still load).
+ *
+ * peaks-loop does NOT write this file, and every ECC release checked
+ * (v2.2.0 / v2.2.1 / main) carries the same keys, so upgrading the
+ * plugin does not clear the warning. This check exists so a user who
+ * hits the startup line does not have to re-investigate it from
+ * scratch.
+ *
+ * Probing is split out of the check so the check itself stays a pure
+ * mapping over `EccHooksDriftProbeResult`. Tests inject the probe to
+ * keep the real `~/.claude/plugins/` tree out of fixtures.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+const CHECK_ID = 'integration:ecc-hooks-schema-drift';
+/** Claude Code's plugin hook schema accepts exactly these keys on a matcher group. */
+const ALLOWED_MATCHER_GROUP_KEYS = ['matcher', 'hooks'];
+/**
+ * …and at the document root: `hooks`, plus an OPTIONAL top-level
+ * `description` (Claude Code's plugin hooks docs, "Reference scripts by
+ * path", document a top-level `description` for `hooks/hooks.json` and
+ * place it as a sibling of `hooks`). A top-level `description` is
+ * therefore legal — and is exactly the shape an upstream ECC fix would
+ * land on when it consolidates its 23 per-matcher descriptions into one.
+ */
+const ALLOWED_ROOT_KEYS = ['hooks', 'description'];
+const NO_DRIFT = {
+    unknownKeyCount: 0,
+    rootKeys: [],
+    entryKeys: [],
+    entryCount: 0
+};
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Pure mapping over a parsed plugin `hooks.json` payload. Exported so
+ * tests drive the key scan without touching the real plugin tree.
+ */
+export function findEccHooksSchemaDrift(payload) {
+    if (!isPlainObject(payload))
+        return NO_DRIFT;
+    const rootKeys = Object.keys(payload).filter((key) => !ALLOWED_ROOT_KEYS.includes(key));
+    const hooks = payload.hooks;
+    if (!isPlainObject(hooks)) {
+        return { ...NO_DRIFT, unknownKeyCount: rootKeys.length, rootKeys };
+    }
+    const entryKeys = new Set();
+    let entryKeyTotal = 0;
+    let entryCount = 0;
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!isPlainObject(group))
+                continue;
+            const unknown = Object.keys(group).filter((key) => !ALLOWED_MATCHER_GROUP_KEYS.includes(key));
+            if (unknown.length === 0)
+                continue;
+            entryCount += 1;
+            entryKeyTotal += unknown.length;
+            for (const key of unknown)
+                entryKeys.add(key);
+        }
+    }
+    return {
+        unknownKeyCount: rootKeys.length + entryKeyTotal,
+        rootKeys,
+        entryKeys: [...entryKeys].sort(),
+        entryCount
+    };
+}
+function readJsonIfPresent(path) {
+    if (!existsSync(path))
+        return null;
+    // Parse errors intentionally propagate to the check's own catch, which
+    // reports them as a `skipping check` message instead of swallowing them.
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/**
+ * Resolve the ECC plugin's install path from Claude Code's plugin
+ * manifest (`~/.claude/plugins/installed_plugins.json`), which is the
+ * only version-agnostic way to find the versioned cache directory
+ * (`…/plugins/cache/ecc/ecc/<version>/`). Exported so tests drive the
+ * lookup with an explicit manifest path.
+ */
+export function readEccInstallPath(manifestPath) {
+    const manifest = readJsonIfPresent(manifestPath);
+    if (!isPlainObject(manifest))
+        return null;
+    const plugins = manifest.plugins;
+    if (!isPlainObject(plugins))
+        return null;
+    for (const [name, records] of Object.entries(plugins)) {
+        if (!name.startsWith('ecc@'))
+            continue;
+        if (!Array.isArray(records))
+            continue;
+        for (const record of records) {
+            if (!isPlainObject(record))
+                continue;
+            const installPath = record.installPath;
+            if (typeof installPath === 'string' && installPath.length > 0)
+                return installPath;
+        }
+    }
+    return null;
+}
+/**
+ * Default probe: reads the ECC plugin manifest + its `hooks/hooks.json`.
+ * `homeDir` is injectable so tests can drive the real probe against a
+ * temp dir; the zero-arg call keeps using the real homedir, so the
+ * function stays assignable to `EccHooksDriftProbe`.
+ */
+export function defaultEccHooksDriftProbe(homeDir = homedir()) {
+    const manifestPath = join(homeDir, '.claude', 'plugins', 'installed_plugins.json');
+    const installPath = readEccInstallPath(manifestPath);
+    if (installPath === null)
+        return { hooksPath: null, hooks: null };
+    const hooksPath = join(installPath, 'hooks', 'hooks.json');
+    return { hooksPath, hooks: readJsonIfPresent(hooksPath) };
+}
+function run({ options }) {
+    const probe = options.eccHooksDriftProbe ?? defaultEccHooksDriftProbe;
+    try {
+        const { hooksPath, hooks } = probe();
+        if (hooksPath === null) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: 'ECC plugin not installed (no `ecc@*` entry in ~/.claude/plugins/installed_plugins.json); no plugin hook schema drift to report'
+                }];
+        }
+        if (hooks === null) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: `No readable ECC plugin hooks.json at ${hooksPath}; no plugin hook schema drift to report`
+                }];
+        }
+        const finding = findEccHooksSchemaDrift(hooks);
+        if (finding.unknownKeyCount === 0) {
+            return [{
+                    id: CHECK_ID,
+                    ok: true,
+                    message: `ECC plugin hooks.json at ${hooksPath} carries only the keys Claude Code accepts (matcher/hooks per matcher group); the startup "unknown keys ... ignored" warning will not appear`
+                }];
+        }
+        const rootPart = finding.rootKeys.length === 0 ? '' : `at the root: ${finding.rootKeys.join(', ')}; `;
+        return [{
+                id: CHECK_ID,
+                ok: false,
+                severity: 'warning',
+                message: `ECC plugin hooks.json at ${hooksPath} carries ${finding.unknownKeyCount} key(s) that Claude Code's plugin hook schema ignores (${rootPart}on ${finding.entryCount} matcher group(s): ${finding.entryKeys.join(', ')}). Claude Code prints \`ecc: hooks.json: unknown keys ... ignored\` at startup; every hook still loads, so this warning is cosmetic. Source: the third-party ECC plugin (github.com/affaan-m/ECC) ships these keys in every release (v2.2.0 / v2.2.1 / main) — peaks-loop does NOT write this file. Fix: none inside peaks-loop; upstream ECC must drop them from its hooks/hooks.json (its scripts/ci/validate-hooks.js validates shape only, never a key allow-list, so ECC's own CI stays green). Upgrading ECC will not help.`
+            }];
+    }
+    catch (error) {
+        return [{
+                id: CHECK_ID,
+                ok: true,
+                message: `ECC hooks schema-drift probe failed (${getErrorMessage(error)}); skipping check`
+            }];
+    }
+}
+export const check = {
+    name: 'ecc-hooks-schema-drift',
+    run
+};

package/dist/services/doctor/doctor-service/plugin-registry.js

@@ -46,6 +46,7 @@ import { check as distSourceVersion } from './checks/dist-source-version.js';
 import { check as multiBinaryDrift } from './checks/multi-binary-drift.js';
 import { check as workspaceLayout } from './checks/workspace-layout.js';
 import { check as gateguardConflict } from './checks/gateguard-conflict.js';
+import { check as eccHooksSchemaDrift } from './checks/ecc-hooks-schema-drift.js';
 import { check as checkIdSchema } from './checks/check-id-schema.js';
 import { check as l3OrphanSessions } from './checks/l3-orphan-sessions.js';
 import { check as l3MemoryHealth } from './checks/l3-memory-health.js';
@@ -73,6 +74,7 @@ export const PLUGINS = [
     multiBinaryDrift, // id "build:multi-binary-drift"
     workspaceLayout, // id "build:workspace-layout-canonical"
     gateguardConflict, // id "integration:gateguard-peaks-conflict"
+    eccHooksSchemaDrift, // id "integration:ecc-hooks-schema-drift"
     checkIdSchema, // id "doctor-self:check-id-pattern"
     l3OrphanSessions, // id "L3:l3-orphan-sessions"
     l3MemoryHealth, // id "L3:l3-memory-health"

package/dist/services/doctor/doctor-service/types.d.ts

@@ -165,6 +165,24 @@ export type GateguardProbeResult = {
     projectSettings: unknown;
 };
 export type GateguardProbe = () => GateguardProbeResult;
+/**
+ * 2026-09-12 — the third-party ECC plugin (github.com/affaan-m/ECC)
+ * ships `$schema` at the root of its `hooks/hooks.json` plus
+ * `description` + `id` on every matcher group. Claude Code's plugin
+ * hook schema accepts only `{ matcher, hooks }` per matcher group, and
+ * at the root `hooks` plus an OPTIONAL top-level `description`, so it
+ * prints an `unknown keys ... ignored`
+ * line at startup for the 47 extra keys (cosmetic — the hooks still
+ * load). The probe is injected so tests never read the real
+ * `~/.claude/plugins/` tree.
+ */
+export type EccHooksDriftProbeResult = {
+    /** Absolute path to the ECC plugin's `hooks/hooks.json` (null when the plugin is not installed). */
+    hooksPath: string | null;
+    /** Parsed `hooks/hooks.json` payload (null when missing / unreadable). */
+    hooks: unknown;
+};
+export type EccHooksDriftProbe = () => EccHooksDriftProbeResult;
 /**
  * Subset of SkillPresence consumed by the doctor (slice-3b: the full
  * `SkillPresence` type lives in `src/services/skills/skill-presence-service.ts`;
@@ -230,6 +248,8 @@ export type DoctorOptions = {
     workspaceLayoutProbe?: WorkspaceLayoutProbe;
     /** Injected for the integration:gateguard-peaks-conflict check (defaults to defaultGateguardProbe on disk). */
     gateguardProbe?: GateguardProbe;
+    /** Injected for the integration:ecc-hooks-schema-drift check (defaults to defaultEccHooksDriftProbe on disk). */
+    eccHooksDriftProbe?: EccHooksDriftProbe;
     /**
      * Slice 2026-06-13-repair-pre-existing-test-failures: injected
      * root for the L3:l3-memory-health check (defaults to

package/dist/services/llm/anthropic-runner.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The first real `LlmRunner` in peaks-loop: it binds a caller to the
+ * Anthropic Messages API shape at `<ANTHROPIC_BASE_URL>/v1/messages`,
+ * which is the same endpoint the running session is already using.
+ *
+ * Why this exists: `peaks audit goal` is the entry gate for every
+ * peaks-* workflow, and until this file landed the CLI could only answer
+ * with a fixed `scaffold-only` envelope — a gate that gated nothing.
+ *
+ * No SDK and no new runtime dependency: Node 18+ global `fetch` covers it.
+ * Every transport concern (auth scheme, timeout, text extraction) lives
+ * here so the CLI layer never speaks HTTP itself, and so tests can inject
+ * a fake transport instead of reaching the network.
+ */
+import type { LlmRunner } from '../audit/audit-goal-service.js';
+/**
+ * The subset of `Response` this client touches. Declared narrowly so tests
+ * can inject a plain object and stay off the network.
+ */
+export interface LlmHttpResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+export interface LlmFetchInit {
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+    readonly signal: AbortSignal;
+}
+export type FetchLike = (url: string, init: LlmFetchInit) => Promise<LlmHttpResponse>;
+/** Which header carries the credential. */
+export type AnthropicAuthScheme = 'bearer' | 'x-api-key';
+export interface AnthropicConfig {
+    readonly baseUrl: string;
+    readonly authToken: string;
+    readonly authScheme: AnthropicAuthScheme;
+    readonly model: string;
+}
+/**
+ * Thrown when the environment cannot name a usable LLM. `code` distinguishes
+ * an absent credential from an absent model so the CLI can name the env var
+ * to set instead of degrading into a scaffold.
+ */
+export declare class LlmBindingError extends Error {
+    readonly code: 'LLM_CREDENTIAL_MISSING' | 'LLM_MODEL_MISSING';
+    /**
+     * The environment variables that were absent, verbatim.
+     *
+     * `message` also names them, but `fail()` runs every envelope message
+     * through `redactSensitiveErrorMessage`, whose catch-all pattern matches
+     * the words `token` / `api_key` and would strip them out of this very
+     * message. Callers must surface `missingEnv` on a channel the redactor
+     * does not touch (envelope `data` / `nextActions`) so the operator is told
+     * exactly what to set.
+     */
+    readonly missingEnv: readonly string[];
+    constructor(code: 'LLM_CREDENTIAL_MISSING' | 'LLM_MODEL_MISSING', message: string, missingEnv: readonly string[]);
+}
+/** Thrown when a bound LLM could not be reached, answered non-2xx, or answered without text. */
+export declare class LlmRequestError extends Error {
+    readonly code: "LLM_REQUEST_FAILED";
+    constructor(message: string);
+}
+/**
+ * Resolve the session's LLM from the environment.
+ *
+ * Precedence:
+ *   - credential: `ANTHROPIC_AUTH_TOKEN` first (it is what a Claude-Code
+ *     session exports for a gateway), else `ANTHROPIC_API_KEY`.
+ *   - auth header: `Authorization: Bearer` for `ANTHROPIC_AUTH_TOKEN`,
+ *     `x-api-key` for `ANTHROPIC_API_KEY` — each matches its own convention.
+ *   - model: `ANTHROPIC_MODEL`, else `CLAUDE_CODE_SUBAGENT_MODEL`.
+ *   - base URL: `ANTHROPIC_BASE_URL`, else the public Anthropic endpoint.
+ *     Expected WITHOUT a trailing `/v1` — this function appends `/v1/messages`.
+ *
+ * Throws `LlmBindingError` rather than defaulting: a gate that quietly
+ * falls back is the bug this file was written to remove.
+ */
+export declare function resolveAnthropicConfig(env?: NodeJS.ProcessEnv): AnthropicConfig;
+export interface AnthropicRunnerOptions {
+    /** Injected transport. Tests pass a fake so no test performs a network call. */
+    readonly fetchImpl?: FetchLike;
+    readonly timeoutMs?: number;
+}
+export declare function createAnthropicRunner(config: AnthropicConfig, options?: AnthropicRunnerOptions): LlmRunner;

package/dist/services/llm/anthropic-runner.js

@@ -0,0 +1,171 @@
+/**
+ * The first real `LlmRunner` in peaks-loop: it binds a caller to the
+ * Anthropic Messages API shape at `<ANTHROPIC_BASE_URL>/v1/messages`,
+ * which is the same endpoint the running session is already using.
+ *
+ * Why this exists: `peaks audit goal` is the entry gate for every
+ * peaks-* workflow, and until this file landed the CLI could only answer
+ * with a fixed `scaffold-only` envelope — a gate that gated nothing.
+ *
+ * No SDK and no new runtime dependency: Node 18+ global `fetch` covers it.
+ * Every transport concern (auth scheme, timeout, text extraction) lives
+ * here so the CLI layer never speaks HTTP itself, and so tests can inject
+ * a fake transport instead of reaching the network.
+ */
+import { getErrorMessage } from 'peaks-loop-shared/result';
+/** Public Anthropic endpoint. `ANTHROPIC_BASE_URL` overrides it (gateways, local proxies). */
+const DEFAULT_BASE_URL = 'https://api.anthropic.com';
+/** One call is bounded: an unbounded gate is a hung gate. */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Enough of an error body to name the cause without dumping a payload into a message. */
+const MAX_BODY_SNIPPET = 200;
+/**
+ * Wrapped rather than aliased: `fetch` takes a wider `RequestInit`, which
+ * does not satisfy `LlmFetchInit` under `strictFunctionTypes`.
+ */
+const defaultFetch = (url, init) => fetch(url, init);
+/**
+ * Thrown when the environment cannot name a usable LLM. `code` distinguishes
+ * an absent credential from an absent model so the CLI can name the env var
+ * to set instead of degrading into a scaffold.
+ */
+export class LlmBindingError extends Error {
+    code;
+    /**
+     * The environment variables that were absent, verbatim.
+     *
+     * `message` also names them, but `fail()` runs every envelope message
+     * through `redactSensitiveErrorMessage`, whose catch-all pattern matches
+     * the words `token` / `api_key` and would strip them out of this very
+     * message. Callers must surface `missingEnv` on a channel the redactor
+     * does not touch (envelope `data` / `nextActions`) so the operator is told
+     * exactly what to set.
+     */
+    missingEnv;
+    constructor(code, message, missingEnv) {
+        super(message);
+        this.name = 'LlmBindingError';
+        this.code = code;
+        this.missingEnv = missingEnv;
+    }
+}
+/** Thrown when a bound LLM could not be reached, answered non-2xx, or answered without text. */
+export class LlmRequestError extends Error {
+    code = 'LLM_REQUEST_FAILED';
+    constructor(message) {
+        super(message);
+        this.name = 'LlmRequestError';
+    }
+}
+/** A blank value is as unusable as an absent one. */
+function readEnv(env, name) {
+    const value = env[name]?.trim();
+    return value ? value : undefined;
+}
+/**
+ * Resolve the session's LLM from the environment.
+ *
+ * Precedence:
+ *   - credential: `ANTHROPIC_AUTH_TOKEN` first (it is what a Claude-Code
+ *     session exports for a gateway), else `ANTHROPIC_API_KEY`.
+ *   - auth header: `Authorization: Bearer` for `ANTHROPIC_AUTH_TOKEN`,
+ *     `x-api-key` for `ANTHROPIC_API_KEY` — each matches its own convention.
+ *   - model: `ANTHROPIC_MODEL`, else `CLAUDE_CODE_SUBAGENT_MODEL`.
+ *   - base URL: `ANTHROPIC_BASE_URL`, else the public Anthropic endpoint.
+ *     Expected WITHOUT a trailing `/v1` — this function appends `/v1/messages`.
+ *
+ * Throws `LlmBindingError` rather than defaulting: a gate that quietly
+ * falls back is the bug this file was written to remove.
+ */
+export function resolveAnthropicConfig(env = process.env) {
+    const authToken = readEnv(env, 'ANTHROPIC_AUTH_TOKEN');
+    const apiKey = readEnv(env, 'ANTHROPIC_API_KEY');
+    const credential = authToken ?? apiKey;
+    if (!credential) {
+        throw new LlmBindingError('LLM_CREDENTIAL_MISSING', 'No LLM credential in the environment: set ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY) so the audit gate can reach the LLM this session already uses.', ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY']);
+    }
+    const model = readEnv(env, 'ANTHROPIC_MODEL') ?? readEnv(env, 'CLAUDE_CODE_SUBAGENT_MODEL');
+    if (!model) {
+        throw new LlmBindingError('LLM_MODEL_MISSING', 'No LLM model in the environment: set ANTHROPIC_MODEL (or CLAUDE_CODE_SUBAGENT_MODEL) so the audit gate knows which model to bind to.', ['ANTHROPIC_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL']);
+    }
+    return {
+        baseUrl: (readEnv(env, 'ANTHROPIC_BASE_URL') ?? DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        authToken: credential,
+        authScheme: authToken ? 'bearer' : 'x-api-key',
+        model
+    };
+}
+function isTextBlock(block) {
+    return block.type === 'text' && typeof block.text === 'string';
+}
+/** `fetch` rejects on abort with a DOMException whose `name` says why. */
+function isAbort(error) {
+    return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
+}
+export function createAnthropicRunner(config, options = {}) {
+    const fetchImpl = options.fetchImpl ?? defaultFetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const url = `${config.baseUrl}/v1/messages`;
+    return {
+        async call(systemPrompt, userPrompt, opts) {
+            const body = JSON.stringify({
+                model: config.model,
+                max_tokens: opts.maxTokens,
+                system: systemPrompt,
+                messages: [{ role: 'user', content: userPrompt }]
+            });
+            let response;
+            try {
+                response = await fetchImpl(url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        'anthropic-version': '2023-06-01',
+                        ...(config.authScheme === 'bearer'
+                            ? { authorization: `Bearer ${config.authToken}` }
+                            : { 'x-api-key': config.authToken })
+                    },
+                    body,
+                    signal: AbortSignal.timeout(timeoutMs)
+                });
+            }
+            catch (error) {
+                if (isAbort(error)) {
+                    throw new LlmRequestError(`LLM request to ${url} timed out after ${timeoutMs}ms`);
+                }
+                throw new LlmRequestError(`LLM request to ${url} failed: ${getErrorMessage(error)}`);
+            }
+            if (!response.ok) {
+                throw new LlmRequestError(`LLM request to ${url} failed: HTTP ${response.status}${await bodySnippet(response)}`);
+            }
+            let payload;
+            try {
+                payload = (await response.json());
+            }
+            catch (error) {
+                throw new LlmRequestError(`LLM reply from ${url} was not valid JSON: ${getErrorMessage(error)}`);
+            }
+            const blocks = Array.isArray(payload.content) ? payload.content : [];
+            const output = blocks.filter(isTextBlock).map((block) => block.text).join('');
+            if (!output) {
+                throw new LlmRequestError(`LLM reply from ${url} carried no text block`);
+            }
+            return {
+                output,
+                tokens: {
+                    input: payload.usage?.input_tokens ?? 0,
+                    output: payload.usage?.output_tokens ?? 0
+                }
+            };
+        }
+    };
+}
+async function bodySnippet(response) {
+    try {
+        const text = (await response.text()).trim();
+        return text ? `: ${text.slice(0, MAX_BODY_SNIPPET)}` : '';
+    }
+    catch {
+        return '';
+    }
+}

package/dist/services/llm/stub-runner.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Offline `LlmRunner` behind `peaks audit goal --llm-provider stub`.
+ *
+ * It exists so CI and unit tests can exercise the CLI route — including
+ * `auditGoal()`'s 6-dimension validation — without a network call. It
+ * performs NO audit: every finding below is a placeholder, which is why
+ * the CLI reports this run as `scaffold-only` / `providerBinding: 'stub'`
+ * and never as an audit.
+ */
+import type { LlmRunner } from '../audit/audit-goal-service.js';
+export declare function createStubRunner(): LlmRunner;

package/dist/services/llm/stub-runner.js

@@ -0,0 +1,33 @@
+/**
+ * Offline `LlmRunner` behind `peaks audit goal --llm-provider stub`.
+ *
+ * It exists so CI and unit tests can exercise the CLI route — including
+ * `auditGoal()`'s 6-dimension validation — without a network call. It
+ * performs NO audit: every finding below is a placeholder, which is why
+ * the CLI reports this run as `scaffold-only` / `providerBinding: 'stub'`
+ * and never as an audit.
+ */
+const NOT_AUDITED = 'Stub provider: this placeholder is not an audit finding.';
+const STUB_REPLY = JSON.stringify({
+    summary: 'Stub provider: no audit was performed.',
+    audit: [
+        { dimension: 'correctness', finding: NOT_AUDITED, severity: 'info' },
+        { dimension: 'completeness', finding: NOT_AUDITED, severity: 'info' },
+        { dimension: 'scope', finding: NOT_AUDITED, severity: 'info' },
+        { dimension: 'risks', finding: NOT_AUDITED, severity: 'info' },
+        { dimension: 'alternatives', finding: NOT_AUDITED, severity: 'info' },
+        { dimension: 'constraints', finding: NOT_AUDITED, severity: 'info' }
+    ],
+    proposedGoal: 'Stub provider: no goal proposed.',
+    successCriteria: ['Stub provider: no acceptance criteria produced.'],
+    roughEffort: 'small',
+    confidence: 'low',
+    rationale: 'Stub provider: the six dimensions above are placeholders so the CLI route can be exercised without a network call. Treating this as an audit would defeat the gate.'
+});
+export function createStubRunner() {
+    return {
+        async call() {
+            return { output: STUB_REPLY, tokens: { input: 0, output: 0 } };
+        }
+    };
+}