peaks-loop 3.0.0

package/dist/src/cli/commands/statusline-commands.js

@@ -0,0 +1,169 @@
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { buildStatusLineModel, parseStatusLineStdin } from '../../services/skills/skill-statusline-service.js';
+import { renderStatusLine } from '../../services/skills/skill-statusline-renderer.js';
+import { applyStatusLineInstall, planStatusLineInstall, removeStatusLineInstall } from '../../services/skills/statusline-settings-service.js';
+import { readHookStatus as readSettingsStatus } from '../../services/skills/hooks-settings-service.js';
+import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+const STDIN_READ_TIMEOUT_MS = 250;
+/** Read piped stdin if present; resolve quickly with '' when attached to a TTY. */
+function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        let data = '';
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(data);
+        };
+        const timer = setTimeout(finish, STDIN_READ_TIMEOUT_MS);
+        timer.unref?.();
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => {
+            clearTimeout(timer);
+            finish();
+        });
+        process.stdin.on('error', () => {
+            clearTimeout(timer);
+            finish();
+        });
+    });
+}
+function resolveScope(options) {
+    return options.global ? 'global' : 'project';
+}
+/**
+ * Resolve the IDE the install should target. The CLI user can override with
+ * `--ide <id>`. Otherwise we delegate to `detectIdeFromContext` which checks
+ * `process.env[adapter.envVar]` → stdin shape → cwd `.trae`/`.claude` →
+ * fallback `'claude-code'`. Pass `parsedStdin: null` since `peaks statusline
+ * install` is not invoked from inside an IDE hook — there's no stdin payload.
+ */
+function resolveIdeForCommand(options, projectRoot) {
+    if (options.ide !== undefined && options.ide.length > 0) {
+        return options.ide;
+    }
+    return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
+}
+export function registerStatusLineCommands(program, io) {
+    // Top-level `peaks statusline` — register as a group with subcommands
+    // (install | uninstall | status). When the user runs `peaks statusline` with
+    // no subcommand, commander falls back to a hidden render subcommand so the
+    // status line still renders. This pattern is required by commander 12.x:
+    // when a command has both an action AND subcommands, commander's option
+    // parser conflates the parent's options with the subcommand's and drops
+    // flags. Routing through a subcommand (even one that's hidden) avoids the
+    // option-shadowing bug.
+    const statusline = addJsonOption(program
+        .command('statusline')
+        .description('Render the Peaks skill status line for the current session, or manage the adapter-driven statusLine entry. Run with no subcommand to render; with a subcommand (install | uninstall | status) to manage.'));
+    // Hidden render subcommand. This is the default behavior when the user types
+    // `peaks statusline` with no subcommand. We mark it hidden so `peaks
+    // statusline --help` does not show "render" as a subcommand.
+    statusline
+        .command('render', { hidden: true })
+        .description('Render the Peaks skill status line for the current session (reads session JSON on stdin; honors --project for the project label).')
+        .option('--project <path>', 'project root path (used to label the status line when stdin is absent)')
+        .action(async (options) => {
+        const raw = await readStdin();
+        const stdin = parseStatusLineStdin(raw);
+        const seeded = options.project
+            ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
+            : stdin;
+        const model = buildStatusLineModel(seeded, Date.now());
+        const text = renderStatusLine(model);
+        if (options.json === true) {
+            io.stdout(JSON.stringify({ ok: true, command: 'statusline.render', data: { text } }, null, 2));
+            return;
+        }
+        io.stdout(text);
+    });
+    addJsonOption(statusline
+        .command('install')
+        .description("Install the Peaks status line into the adapter's settings.json (project scope by default).")
+        .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')
+        .option('--force', 'overwrite an existing non-Peaks statusLine entry')
+        .option('--dry-run', 'show what would change without writing')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = scope === 'project'
+            ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+            : undefined;
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            if (options.dryRun) {
+                const plan = planStatusLineInstall(scope, projectRoot, { ide });
+                const warnings = plan.conflict
+                    ? [`An existing statusLine command is set: ${plan.conflictCommand}. Rerun with --force to overwrite.`]
+                    : [];
+                printResult(io, ok('statusline.install', { ...plan, ide, applied: false, dryRun: true }, warnings), options.json);
+                return;
+            }
+            const result = applyStatusLineInstall(scope, projectRoot, { force: options.force === true, ide });
+            const warnings = result.conflict && !result.applied
+                ? [`An existing statusLine command is set: ${result.conflictCommand}. Rerun with --force to overwrite.`]
+                : [];
+            const nextActions = result.applied
+                ? ['Restart the IDE (or reload the workspace) so the status line takes effect']
+                : [];
+            printResult(io, ok('statusline.install', { ...result, ide, dryRun: false }, warnings, nextActions), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.install', 'STATUSLINE_INSTALL_FAILED', message, { scope, ide, applied: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(statusline
+        .command('uninstall')
+        .description("Remove the Peaks status line from the adapter's settings.json.")
+        .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = scope === 'project'
+            ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+            : undefined;
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const result = removeStatusLineInstall(scope, projectRoot, { ide });
+            printResult(io, ok('statusline.uninstall', { ...result, ide }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.uninstall', 'STATUSLINE_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(statusline
+        .command('status')
+        .description('Report whether the Peaks status line is installed in the adapter settings.json.')
+        .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = scope === 'project'
+            ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+            : undefined;
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const status = readSettingsStatus(scope, projectRoot, { ide });
+            printResult(io, ok('statusline.status', { ...status, ide, command: 'peaks statusline' }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.status', 'STATUSLINE_STATUS_FAILED', message, { scope, ide }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/sub-agent-commands.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `peaks sub-agent` CLI command group — slice 2026-06-07-sub-agent-context-governance.
+ *
+ * Thin entry point that wires the four sub-command registrars
+ * (`dispatch`, `heartbeat`, `share`, `shared-read`, `await`) to the
+ * parent `sub-agent` command. The actual implementations live in
+ * sibling files (slice 2026-06-23-audit-p0-split refactor):
+ *
+ *   - `dispatch-commands.ts`  — `dispatch` single-dispatch action
+ *   - `dispatch-from-dag.ts`  — `dispatch --from-dag` codepath (slice 9 perf)
+ *   - `heartbeat-commands.ts` — `heartbeat` action (G6)
+ *   - `share-commands.ts`     — `share` + `shared-read` + `await` actions (G8.4 / 2.7.0)
+ *   - `sub-agent-shared.ts`   — shared types, constants, helpers
+ *
+ * Skill-first / CLI-auxiliary red line (PB-4 / AC-19/20):
+ *   These commands are primitives that the peaks-solo / peaks-rd /
+ *   peaks-qa SKILL.md compose. Users do NOT invoke them directly.
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export { validateRole } from './sub-agent-shared.js';
+export declare function registerSubAgentCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/sub-agent-commands.js

@@ -0,0 +1,19 @@
+import { registerDispatchCommand } from './dispatch-commands.js';
+import { registerHeartbeatCommand } from './heartbeat-commands.js';
+import { registerShareCommand, registerSharedReadCommand, registerAwaitCommand } from './share-commands.js';
+// Re-export `validateRole` for backward compat — the integration test
+// suite and any external callers still import it from this entry file.
+// The canonical implementation now lives in `sub-agent-shared.ts`.
+export { validateRole } from './sub-agent-shared.js';
+export function registerSubAgentCommands(program, io) {
+    const subAgent = program
+        .command('sub-agent')
+        .description('Sub-agent dispatch primitive (skill-first / CLI-auxiliary). ' +
+        'These commands are the primitives that peaks-solo / peaks-rd / ' +
+        'peaks-qa SKILL.md compose. Users do not invoke this directly.');
+    registerDispatchCommand(subAgent, io);
+    registerHeartbeatCommand(subAgent, io);
+    registerShareCommand(subAgent, io);
+    registerSharedReadCommand(subAgent, io);
+    registerAwaitCommand(subAgent, io);
+}

package/dist/src/cli/commands/sub-agent-dispatch-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `peaks sub-agent-dispatch-guard` — G9.5 / RL-30 strict hook-only atom.
+ *
+ * This is the **second-layer** gate (PreToolUse hook) for the G9 forced
+ * compression threshold. It re-validates the prompt size against the
+ * threshold table in `src/services/context/threshold.ts` and returns
+ * `{allow: true/false, reason, suggest}` JSON to the LLM platform.
+ *
+ * **NO `--force` flag is exposed at this layer** (RL-30 strict). The
+ * hook is the strictest layer in the G9 chain. If the CLI is bypassed
+ * (e.g. a user manually invokes the dispatch CLI with `--force` to
+ * override the 80% threshold), the hook catches it and returns
+ * `{allow: false}` regardless.
+ *
+ * This atom is **hidden from `peaks --help`** per dev-preference
+ * "skill-first / CLI-auxiliary" + PB-2 byte-stable. It is registered
+ * via the LLM platform's PreToolUse hook chain (e.g. Claude Code's
+ * `settings.json` `PreToolUse` array) and is not a user-facing command.
+ *
+ * The `peaks hooks install` command reads `IdeAdapter.promptSizeAware`
+ * to decide whether to register this hook for a given IDE.
+ */
+import { Command } from 'commander';
+import { type ContextGuardDecision } from '../../services/context/context-guard.js';
+export declare const HOOK_GUARD_RESULT_TYPE: "peaks-hook-guard/v1";
+export interface HookGuardResult {
+    readonly schema: typeof HOOK_GUARD_RESULT_TYPE;
+    readonly allow: boolean;
+    readonly code: ContextGuardDecision['code'];
+    readonly reason: string;
+    readonly suggest: string | null;
+    readonly tier: ContextGuardDecision['evaluation']['tier'];
+    readonly ratio: number;
+    readonly bytesUsed: number;
+    readonly capacityBytes: number;
+    readonly warnings: readonly string[];
+}
+/**
+ * Build the hook-guard result for a given prompt size. Pure function;
+ * no IO. The CLI atom (registered below) calls this and prints JSON.
+ *
+ * Even if the caller passes `force = true` in the input (it shouldn't —
+ * the hook CLI doesn't expose that flag), this function ignores it
+ * and treats the prompt as if no override were available. This is the
+ * RL-30 strict semantics.
+ */
+export declare function evaluateHookGuard(promptSize: number): HookGuardResult;
+/**
+ * Register the `peaks sub-agent-dispatch-guard` command. Intentionally
+ * NOT registered in the main `peaks --help` quickstart (dev-preference
+ * PB-2 byte-stable). The caller (the `peaks hooks install` flow) calls
+ * this directly via the imported function; the CLI registration in
+ * `src/cli/index.ts` uses a hidden command (no `description`, no help).
+ */
+export declare function registerSubAgentDispatchGuard(program: Command): void;

package/dist/src/cli/commands/sub-agent-dispatch-guard.js

@@ -0,0 +1,57 @@
+import { evaluatePromptSize } from '../../services/context/context-guard.js';
+export const HOOK_GUARD_RESULT_TYPE = 'peaks-hook-guard/v1';
+/**
+ * Build the hook-guard result for a given prompt size. Pure function;
+ * no IO. The CLI atom (registered below) calls this and prints JSON.
+ *
+ * Even if the caller passes `force = true` in the input (it shouldn't —
+ * the hook CLI doesn't expose that flag), this function ignores it
+ * and treats the prompt as if no override were available. This is the
+ * RL-30 strict semantics.
+ */
+export function evaluateHookGuard(promptSize) {
+    // Intentionally pass `force: false` always. The hook layer is strict.
+    const decision = evaluatePromptSize(promptSize, { force: false });
+    return {
+        schema: HOOK_GUARD_RESULT_TYPE,
+        allow: decision.allow,
+        code: decision.code,
+        reason: decision.allow
+            ? `prompt size ${promptSize} bytes within threshold (tier=${decision.evaluation.tier})`
+            : `prompt size ${promptSize} bytes exceeds threshold (tier=${decision.evaluation.tier}, ratio=${decision.evaluation.ratio.toFixed(3)})`,
+        suggest: decision.suggest,
+        tier: decision.evaluation.tier,
+        ratio: decision.evaluation.ratio,
+        bytesUsed: decision.evaluation.bytesUsed,
+        capacityBytes: decision.evaluation.capacityBytes,
+        warnings: decision.warnings
+    };
+}
+/**
+ * Register the `peaks sub-agent-dispatch-guard` command. Intentionally
+ * NOT registered in the main `peaks --help` quickstart (dev-preference
+ * PB-2 byte-stable). The caller (the `peaks hooks install` flow) calls
+ * this directly via the imported function; the CLI registration in
+ * `src/cli/index.ts` uses a hidden command (no `description`, no help).
+ */
+export function registerSubAgentDispatchGuard(program) {
+    program
+        .command('sub-agent-dispatch-guard')
+        .description('INTERNAL: PreToolUse hook guard (G9.5 / RL-30 strict)')
+        .requiredOption('--prompt <text>', 'the prompt to validate (size in bytes is what gets checked)')
+        .option('--prompt-length <bytes>', 'DOGFOOD ONLY: synthesize a prompt of this size (overrides --prompt content for size only)')
+        .action((options) => {
+        let prompt = options.prompt;
+        if (typeof options.promptLength === 'string' && options.promptLength.length > 0) {
+            const len = Number.parseInt(options.promptLength, 10);
+            if (Number.isInteger(len) && len > 0) {
+                prompt = 'x'.repeat(len);
+            }
+        }
+        const promptSize = Buffer.byteLength(prompt, 'utf8');
+        const result = evaluateHookGuard(promptSize);
+        // Always exit 0 — the LLM platform reads `allow` from JSON.
+        // The decision is encoded in `allow` / `code`, not the exit code.
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    });
+}

package/dist/src/cli/commands/sub-agent-shared.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared types, constants, and helpers for the `peaks sub-agent` command group.
+ *
+ * Slice 2026-06-23-audit-p0-split — pulled out of `sub-agent-commands.ts` (968
+ * lines) to honor the 800-line file cap (Karpathy #2 Simplicity First).
+ *
+ * Public exports:
+ *   - `validateRole(role)` — exported because `sub-agent-commands.test.ts`
+ *     and the integration suite rely on it as the source of truth for
+ *     role-string validation.
+ *
+ * Everything else is internal to the `peaks sub-agent` group.
+ */
+import type { SubAgentBatchResult } from '../../services/dispatch/sub-agent-dispatcher.js';
+import type { HeadroomMode } from '../../services/context/headroom-client.js';
+import type { HeartbeatStatus } from '../../services/dispatch/dispatch-record-writer.js';
+export declare const RECOMMENDED_ROLES = "rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose";
+export declare const HEARTBEAT_STATUSES: readonly HeartbeatStatus[];
+export declare const HEADROOM_MODES: readonly HeadroomMode[];
+export declare const PROMPT_LIMIT_BYTES: number;
+export type DispatchOptions = {
+    prompt?: string;
+    promptLength?: string;
+    requestId?: string;
+    sessionId?: string;
+    project?: string;
+    batchId?: string;
+    writeArtifact?: string;
+    useHeadroom?: boolean;
+    headroomMode?: string;
+    force?: boolean;
+    fromDag?: string;
+    json?: boolean;
+};
+export type HeartbeatOptions = {
+    record?: string;
+    status?: string;
+    progress?: string;
+    note?: string;
+    project?: string;
+    json?: boolean;
+};
+export type ShareOptions = {
+    batch?: string;
+    key?: string;
+    value?: string;
+    from?: string;
+    requestId?: string;
+    sessionId?: string;
+    project?: string;
+    json?: boolean;
+};
+export type SharedReadOptions = {
+    batch?: string;
+    since?: string;
+    key?: string;
+    requestId?: string;
+    sessionId?: string;
+    project?: string;
+    json?: boolean;
+};
+export type AwaitOptions = {
+    batch?: string;
+    timeout?: string;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+};
+/**
+ * Lazy-loaded module types — only resolved inside `runDispatchFromDag`
+ * to keep the warm-path dispatch CLI cold-start fast (slice 9).
+ */
+export type SliceDagModule = typeof import('../../services/dispatch/slice-dag.js');
+export type DagOrchestratorModule = typeof import('../../services/solo/dag-orchestrator.js');
+export type ContractStoreModule = typeof import('../../services/dispatch/contract-store.js');
+/**
+ * Validate a role string. Returns `null` when valid, otherwise the
+ * rejection reason (mirrors commander.js option-validation shape so
+ * the action handler can pass it straight to `fail()`).
+ *
+ * Rules (per dispatch CLI spec):
+ *   - Non-empty
+ *   - ≤ 256 chars
+ *   - No whitespace, no control characters, no DEL (0x7F)
+ */
+export declare function validateRole(role: string): string | null;
+/**
+ * Roll up a batch result array into the summary the CLI envelope exposes
+ * for `peaks sub-agent await`. Counts per status; the orchestrator
+ * surface (`SubAgentBatchResult.status`) is a closed set so a single
+ * `for` loop with `if/else if` is faster and clearer than a reduce.
+ */
+export declare function summarizeBatchResults(results: readonly SubAgentBatchResult[]): {
+    readonly total: number;
+    readonly done: number;
+    readonly failed: number;
+    readonly cancelled: number;
+    readonly timeout: number;
+};

package/dist/src/cli/commands/sub-agent-shared.js

@@ -0,0 +1,67 @@
+export const RECOMMENDED_ROLES = 'rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose';
+export const HEARTBEAT_STATUSES = [
+    'queued', 'running', 'finalizing', 'done', 'failed', 'stale'
+];
+export const HEADROOM_MODES = ['balanced', 'aggressive', 'conservative'];
+export const PROMPT_LIMIT_BYTES = 256 * 1024;
+/**
+ * Validate a role string. Returns `null` when valid, otherwise the
+ * rejection reason (mirrors commander.js option-validation shape so
+ * the action handler can pass it straight to `fail()`).
+ *
+ * Rules (per dispatch CLI spec):
+ *   - Non-empty
+ *   - ≤ 256 chars
+ *   - No whitespace, no control characters, no DEL (0x7F)
+ */
+export function validateRole(role) {
+    if (typeof role !== 'string' || role.length === 0) {
+        return 'role must be a non-empty string';
+    }
+    if (role.length > 256) {
+        return 'role must be ≤ 256 chars';
+    }
+    for (let i = 0; i < role.length; i += 1) {
+        const code = role.charCodeAt(i);
+        if (code <= 0x20 || code === 0x7F) {
+            return 'role must not contain whitespace or control characters';
+        }
+    }
+    return null;
+}
+/**
+ * Roll up a batch result array into the summary the CLI envelope exposes
+ * for `peaks sub-agent await`. Counts per status; the orchestrator
+ * surface (`SubAgentBatchResult.status`) is a closed set so a single
+ * `for` loop with `if/else if` is faster and clearer than a reduce.
+ */
+export function summarizeBatchResults(results) {
+    let done = 0;
+    let failed = 0;
+    let cancelled = 0;
+    let timeout = 0;
+    for (const r of results) {
+        if (r.status === 'done')
+            done += 1;
+        else if (r.status === 'failed')
+            failed += 1;
+        else if (r.status === 'cancelled')
+            cancelled += 1;
+        else
+            timeout += 1;
+    }
+    return { total: results.length, done, failed, cancelled, timeout };
+}
+// Note: `isHeadroomMode` and `RegisterSubCommand` used to live here as
+// duplicate exports. Removed in slice 2026-06-23-audit-p0-cleanup:
+//   - `isHeadroomMode` is exported by `src/services/context/headroom-prefs.ts`
+//     and that is the canonical source — dispatch consumer imports from
+//     there directly.
+//   - `RegisterSubCommand` was never used as a type anywhere; the entry
+//     point (`sub-agent-commands.ts`) calls each register function with
+//     `(program, io)` directly.
+//   - `deriveProjectRoot` (audit-p0-reaudit) was removed in slice
+//     2026-06-23-audit-3rd: it trusted the record path's `.peaks` segment,
+//     letting a caller point `--record` at any project's record tree. The
+//     heartbeat command now trusts `--project` (or `process.cwd()`) and
+//     leaves the relative() backstop to the R-2 guard.

package/dist/src/cli/commands/test-commands.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `peaks test <pattern...>` — slice 2.5.0 sub-fix B (Prob 2).
+ *
+ * Wraps the consumer project's test framework (jest / vitest / mocha)
+ * with a per-test fingerprint cache. The wrapper:
+ *
+ *   1. Auto-detects the framework from package.json (devDependencies +
+ *      dependencies) via detectTestFramework().
+ *   2. Spawns the framework's CLI with --cache enabled (overriding any
+ *      --no-cache in the consumer's `test` script). The user can
+ *      opt back into no-cache via `peaks test --no-cache` or
+ *      `peaks test --passthrough`.
+ *   3. Skips tests where (fileMtime, fileSha256) is unchanged AND the
+ *      previous run status was 'passed' (per-test fingerprint cache at
+ *      `<projectRoot>/.peaks/_runtime/test-cache/<hash>.json`).
+ *   4. Exits 0 on all-pass / all-skip; exits 1 on any failure.
+ *
+ * The CLI is invoked by USER (not just by skill) per slice 2.5.0
+ * sub-fix B (G16) — a documented exception to the
+ * dev-preference red-line "no new top-level peaks <cmd>".
+ *
+ * Sub-commands:
+ *   peaks test <pattern...>           — run tests matching the pattern
+ *   peaks test --all                  — run the full suite
+ *   peaks test --changed              — only files changed since HEAD
+ *   peaks test --clear-cache          — empty the fingerprint cache
+ *   peaks test --no-cache-result      — bypass the fingerprint cache
+ *   peaks test --no-cache             — pass --no-cache to the framework
+ *   peaks test --passthrough          — do NOT override the consumer's argv
+ *   peaks test --framework <name>     — force a specific framework
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type TestFramework } from '../../services/test-cache/test-cache-service.js';
+/**
+ * Build the argv for the underlying test runner. This is the SINGLE
+ * source of truth for "peaks test drops --no-cache from the
+ * consumer's script" (G7 / NG7). `--cache` is always passed
+ * unless the user explicitly opts in to `--no-cache` or `--passthrough`.
+ */
+export declare function buildRunnerArgv(framework: TestFramework, patterns: string[], options: {
+    all?: boolean;
+    changed?: boolean;
+    cache?: boolean;
+    passthrough?: boolean;
+}): string[];
+export declare function registerTestCommands(program: Command, _io: ProgramIO): void;