peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/commands/statusline-commands.d.ts

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+type RenderOptions = {
+    project?: string;
+    json?: boolean;
+};
+/**
+ * Default-statusline render body. Reused by both the top-level default
+ * action (Bug-02 dispatch) and the explicit `render` subcommand. Exported
+ * so a unit test can exercise the JSON / text output paths without going
+ * through commander.
+ */
+export declare function runDefaultStatuslineRender(options: RenderOptions, io: ProgramIO): Promise<void>;
+export declare function registerStatusLineCommands(program: Command, io: ProgramIO): void;
+export {};

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

@@ -0,0 +1,231 @@
+import { fail, ok } from 'peaks-loop-shared/result';
+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';
+import { decideCompactStatusline, renderCompactStatusline, } from '../../services/compact-statusline/compact-statusline-service.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.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 });
+}
+/**
+ * Default-statusline render body. Reused by both the top-level default
+ * action (Bug-02 dispatch) and the explicit `render` subcommand. Exported
+ * so a unit test can exercise the JSON / text output paths without going
+ * through commander.
+ */
+export async function runDefaultStatuslineRender(options, io) {
+    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);
+}
+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.')
+        .option('--project <path>', 'project root path (used to label the status line when stdin is absent; applies to the default render path)'));
+    // Default behavior: when the user types `peaks statusline` with no
+    // subcommand, render the status line. Without this default action,
+    // commander falls back to printing usage (Bug-02, ice-cola surface check
+    // 2026-07-22). The hidden `render` subcommand is preserved so callers
+    // can still invoke it explicitly.
+    //
+    // Note (commander 12.x): when both a top-level `.action(...)` and
+    // subcommands exist, commander's option parser can conflate parent and
+    // child flags. We therefore parse `process.argv` for the bare `statusline`
+    // invocation here, and otherwise let the subcommand machinery handle the
+    // rest. The implementation is wrapped in `peekDefaultStatuslineRender` so
+    // it can be exercised in isolation by unit tests.
+    statusline.action(async (_parentOptions, command) => {
+        await runDefaultStatuslineRender(command.opts(), io);
+    });
+    // Hidden render subcommand. Preserved for callers that want to invoke
+    // render explicitly without going through the default-action dispatch.
+    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) => {
+        await runDefaultStatuslineRender(options, io);
+    });
+    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;
+        }
+    });
+    // peaks statusline compact (slice 2026-07-30-compact-visibility)
+    addJsonOption(statusline
+        .command('compact')
+        .description('Render the single-line auto-compact indicator the LLM embeds ' +
+        "in Claude Code's statusline. Default output is plain text; " +
+        'pass --json for the structured envelope.')
+        .option('--project <path>', 'project root (auto-detected from cwd when omitted)')
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding)')
+        .action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const sid = options.sessionId ?? getSessionIdCanonical(projectRoot) ?? null;
+            const state = decideCompactStatusline({
+                projectRoot,
+                sessionId: sid,
+                now: Date.now(),
+            });
+            const label = renderCompactStatusline(state);
+            // For non-JSON mode we print the LABEL DIRECTLY to stdout
+            // (no envelope wrapping) because the consumer is the IDE
+            // statusline, not a peaks-Loop caller.
+            if (options.json === true) {
+                printResult(io, ok('statusline.compact', { label, state }), options.json);
+            }
+            else {
+                process.stdout.write(`${label}\n`);
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.compact', 'STATUSLINE_COMPACT_FAILED', message, {}, [message]), options.json);
+            process.exitCode = 1;
+        }
+    }));
+}

package/dist/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-code / 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/cli/commands/sub-agent-commands.js

@@ -0,0 +1,20 @@
+import { registerDispatchCommand } from './dispatch-commands.js';
+import { registerHeartbeatCommand } from './heartbeat-commands.js';
+import { registerShareCommand, registerSharedReadCommand, registerAwaitCommand, registerFinalizeCommand } 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-code / 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);
+    registerFinalizeCommand(subAgent, io); // D21
+}

package/dist/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/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/cli/commands/sub-agent-shared.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 { probeShell, type ShellProbeReport, type ShellProbeOptions } from '../../services/env/shell-probe.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;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 2.C: dispatch isolation mode.
+     * Only `worktree` is currently recognised. When set, dispatch
+     * auto-spawns a worktree lease (delegates to `peaks worktree spawn`)
+     * and injects `PEAKS_WORKTREE_LEASE_ID=<id>` into the dispatch
+     * envelope so the receiving sub-agent can write to the lease's
+     * worktree without needing a separate `peaks worktree auth grant`.
+     */
+    isolation?: 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/code/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/cli/commands/sub-agent-shared.js

@@ -0,0 +1,90 @@
+// Slice 2026-07-29-dispatch-stall-governance / S6 — `probeShell` is
+// re-exported here so the dispatch chokepoint (`dispatch-commands.ts`)
+// and the sub-agent batch-sync wait can lazily acquire a typed
+// shell-probe report without importing the env service at every
+// call site. Codifies .peaks/memory/2026-07-27-windows-shell-pref.md
+// at the dispatch / tool boundary (AC-6.2).
+export { probeShell } from '../../services/env/shell-probe.js';
+export const RECOMMENDED_ROLES = 'rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose';
+// Slice 2026-07-29-dispatch-stall-governance / S2 — align the per-
+// heartbeat vocabulary with the dispatch record's aggregate status
+// union. The CLI --status help, the writer's isHeartbeatStatus guard,
+// and this constant must stay byte-identical (the parity test in
+// tests/unit/dispatch/heartbeat-parity.test.ts pins it). Adding
+// `cancelled` / `no-execution` closes AC-2.1; adding `never-started`
+// and `unreadable` closes the S1 status surface.
+export const HEARTBEAT_STATUSES = [
+    'queued',
+    'running',
+    'finalizing',
+    'done',
+    'failed',
+    'stale',
+    'cancelled',
+    'no-execution',
+    'never-started',
+    'unreadable'
+];
+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/cli/commands/swarm-commands.d.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type SwarmPlanOptions = {
+    skill?: string;
+    changeId?: string;
+    goal: string;
+    maxWorkers?: string;
+    dryRun?: boolean;
+    codeMode?: string;
+    json?: boolean;
+};
+export declare function runSwarmPlan(io: ProgramIO, options: SwarmPlanOptions): Promise<void>;
+export declare function registerSwarmCommands(program: Command, io: ProgramIO): void;