peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/index.js

@@ -0,0 +1,75 @@
+import { CommanderError } from 'commander';
+import { createProgram } from './program.js';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { printErrorEnvelope } from './cli-helpers.js';
+const defaultIo = {
+    stdout: (text) => process.stdout.write(`${text}\n`),
+    stderr: (text) => process.stderr.write(`${text}\n`)
+};
+// D-013 wrapper exit-code fix (PART 2): Commander's `--help` short-circuit
+// fires BEFORE `commander.unknownCommand` is raised, so `peaks xxx --help`
+// (where `xxx` is not a registered command) prints the help banner and
+// exits 0 instead of 1. Detect this case BEFORE Commander runs by scanning
+// `process.argv` for a non-option positional token. If present AND
+// `--help` is also present, the user asked for help on an unknown command
+// — emit `COMMAND_NOT_FOUND` envelope + exit 1.
+//
+// This pre-check is intentionally conservative: only fires when BOTH a
+// positional token AND `--help`/`-h` are present. Bare `--help` (no
+// positional) is legitimate help → exit 0. Positional without `--help`
+// is handled by the root `.action()` in `program.ts`.
+//
+// Fix-5 (2026-07-26): skip the pre-check when the first positional token
+// matches a REGISTERED subcommand. `peaks slice --help` is legitimate
+// help on a registered command (slice IS in the program.commands list) —
+// the prior blind pre-check was a false positive that printed
+// `COMMAND_NOT_FOUND` + exit 1 alongside the slice help banner. We
+// still catch true unknowns (`peaks unknown-cmd --help`): `firstPositional`
+// won't be in the registered set, so the pre-check fires and exits 1.
+const argv = process.argv.slice(2);
+const hasHelp = argv.some((arg) => arg === '--help' || arg === '-h');
+const firstPositional = argv.find((arg) => !arg.startsWith('-'));
+if (hasHelp && firstPositional !== undefined) {
+    const program = createProgram();
+    const registered = new Set(program.commands.map((c) => c.name()));
+    if (!registered.has(firstPositional)) {
+        // Defer the check by 0ms so Commander's own help handler runs first
+        // (it will print help text + try to exit 0). We then override.
+        setImmediate(() => {
+            printErrorEnvelope(defaultIo, 'cli', 'COMMAND_NOT_FOUND', `Unknown command: ${firstPositional}. Run \`peaks --help\` for available commands.`, { argv: firstPositional, combinedWithHelp: true }, ['Run `peaks --help` to list available commands.']);
+            process.exit(1);
+        });
+    }
+}
+createProgram().parseAsync(process.argv).catch((error) => {
+    if (error instanceof CommanderError && error.code === 'commander.version') {
+        return;
+    }
+    // D-013 wrapper exit-code fix: distinguish "bare `peaks --help` /
+    // `peaks help <cmd>`" (legitimate help, exit 0) from
+    // "`peaks <unknown> --help`" (user typed a non-existent command,
+    // even if they added --help, the command itself is invalid → exit 1).
+    // Commander only emits `commander.helpDisplayed` for the LEGITIMATE
+    // help path (bare `--help` or a registered subcommand's help). For
+    // unknown commands, Commander throws `commander.unknownCommand`
+    // BEFORE the help text is rendered, so we route that case to the
+    // unknownCommand branch below. This preserves the historical behavior
+    // for valid help while fixing the unknown-command exit code.
+    if (error instanceof CommanderError) {
+        if (error.code === 'commander.help' || error.code === 'commander.helpDisplayed') {
+            return;
+        }
+        if (error.code === 'commander.missingArgument' || error.code === 'commander.unknownCommand' || error.code === 'commander.unknownOption') {
+            // Emit a `COMMAND_NOT_FOUND` JSON envelope for the unknown-command
+            // path. The error text already went to stderr via Commander's
+            // default handler; we add a structured envelope for LLM-side
+            // consumers (Human-NL-Choice-Only: don't tell the human to type
+            // a CLI verb — say what the LLM can coordinate).
+            printErrorEnvelope(defaultIo, 'cli', 'COMMAND_NOT_FOUND', getErrorMessage(error), {}, ['Run `peaks --help` to list available commands.']);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    printErrorEnvelope(defaultIo, 'cli', 'UNHANDLED_ERROR', getErrorMessage(error), {}, []);
+    process.exitCode = 1;
+});

package/dist/cli/program.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+import { type ProgramIO } from './cli-helpers.js';
+export { printErrorEnvelope, printResult, type ProgramIO } from './cli-helpers.js';
+export declare function __resetBootstrapForTests(): void;
+export declare function createProgram(io?: ProgramIO): Command;

package/dist/cli/program.js

@@ -0,0 +1,213 @@
+import { Command } from 'commander';
+import { repoRoot } from 'peaks-loop-shared/paths';
+import { CLI_VERSION } from 'peaks-loop-shared/version';
+import { autoRegisterAllCommands } from './commands/_register.js';
+import { registerSuperCommands } from './commands/_super.js';
+import { registerCoreAndArtifactCommands } from './commands/core-artifact-commands.js';
+import { registerWorkflowCommands } from './commands/workflow-commands.js';
+import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capability-worker-config-sc-commands.js';
+import { registerSubAgentCommands } from './commands/sub-agent-commands.js';
+import { registerLeaseMetricsCommand } from './commands/lease-metrics-commands.js';
+import { registerLeaseStatsCommand } from './commands/lease-stats-commands.js';
+import { registerContainerCommand } from './commands/container-commands.js';
+import { registerVmCommand } from './commands/vm-commands.js';
+import { registerCronCommand } from './commands/cron-commands.js';
+import { registerCronSchedulerCommand } from './commands/cron-scheduler-commands.js';
+import { registerWorkspaceCommands } from './commands/workspace-commands.js';
+import { registerSopCommands } from './commands/sop-commands.js';
+import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
+import { applyRetention, cleanupEccCache } from '../services/log/retention.js';
+import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
+import { printSuperCommandCatalog } from './cli-helpers.js';
+export { printErrorEnvelope, printResult } from './cli-helpers.js';
+// Slice rid-001 (P0-1 envelope closure, fix #4): the prior default
+// `ProgramIO` funneled Commander's `configureOutput().writeErr` callback
+// through raw `console.error`, which bypassed the canonical envelope
+// path and left a `// TODO(g2): legacy console.error without envelope`
+// grace comment. Default io now routes stdout through `process.stdout`
+// and stderr through `process.stderr` (matching the `defaultIo` built
+// in `src/cli/index.ts`). When a caller passes its own `ProgramIO`
+// (vitest, programmatic dispatch) the closure-side `printErrorEnvelope`
+// helper in `src/cli/cli-helpers.ts` mints a real `fail()` envelope,
+// so the canonical shape is preserved end-to-end.
+function defaultStderrSink(text) {
+    process.stderr.write(`${text}\n`);
+}
+function defaultStdoutSink(text) {
+    process.stdout.write(`${text}\n`);
+}
+/**
+ * Slice 2026-06-16-cli-logging (G1, G2, G3, G7). One structured
+ * `peaks-loop start` entry per CLI invocation, plus a 7-day
+ * retention sweep. Wired into the global program so EVERY
+ * peaks-loop command — even a bare `peaks` quickstart — writes
+ * a log line.
+ *
+ * The logger NEVER writes to stdout; it touches only the log
+ * file (always) and stderr (when `verbose` is true or
+ * `PEAKS_LOG_LEVEL=debug`). JSON envelopes stay parseable.
+ */
+function bootstrapLogger(verbose) {
+    try {
+        applyRetention({ retentionDays: 7 });
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort retention sweep; never block the CLI */
+    }
+    // Slice 3 (on-demand-ecc): 7-day TTL sweep over ecc-<sha>/ cache dirs.
+    try {
+        cleanupEccCache({ retentionDays: 7, nowMs: Date.now() });
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort ECC retention sweep; never block the CLI */
+    }
+    const dateOverride = process.env.PEAKS_LOG_DATE_OVERRIDE;
+    const entry = {
+        ts: new Date().toISOString(),
+        level: 'info',
+        command: 'main',
+        msg: 'peaks-loop start',
+        version: CLI_VERSION
+    };
+    try {
+        writeLogEntry(entry, dateOverride !== undefined ? { dateOverride } : {});
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort */
+    }
+    if (verbose || process.env.PEAKS_LOG_LEVEL === 'debug') {
+        maybeWriteStderr(entry, { verbose: true });
+    }
+}
+// Slice 2026-06-16-cli-logging (AC1 regression fix, repair cycle 1):
+// Process-scoped guard so the bootstrap log line is written AT MOST
+// once per process, regardless of whether it fires from the
+// `preAction` hook (subcommand path) or from the version action
+// (`-v` / `--version` / `-V` path). Reset between test invocations
+// via `__resetBootstrapForTests`.
+let bootstrapRan = false;
+export function __resetBootstrapForTests() {
+    bootstrapRan = false;
+}
+export function createProgram(io = { stdout: defaultStdoutSink, stderr: defaultStderrSink }) {
+    const program = new Command();
+    program
+        .name('peaks')
+        .description(`Peaks Loop ${CLI_VERSION} — loop engineering CLI: workflow primitive / loop guards / evaluators / slice orchestration
+
+Run peaks (no arguments) for a quickstart. You likely want one of:
+ peaks doctor check your environment
+ peaks skill list or manage skills
+ peaks slice boundary check (tsc + vitest +3-way + verify-pipeline)
+ peaks workflow plan workflow routing dry-run graphs
+ peaks sop author your own workflow gates
+ peaks hooks install the un-bypassable gate-enforcement hook
+ peaks gate enforce/bypass SOP gates on Bash commands`)
+        .configureOutput({
+        writeOut: (text) => io.stdout(text.trimEnd()),
+        writeErr: (text) => io.stderr(text.trimEnd())
+    })
+        // Slice 2026-06-16-cli-logging (AC1 regression fix, repair cycle 1):
+        // We DO NOT use Commander's built-in `.version()` here. Commander's
+        // built-in version handler short-circuits the program BEFORE the
+        // `preAction` hook fires, which means a bare `peaks --version`
+        // invocation skips the JSONL bootstrap. Per PRD AC1 the log file
+        // MUST be created on every CLI invocation, including `--version`.
+        //
+        // Instead we register `-V` and `-v, --version` as regular options
+        // and handle them in the program-level action: run the log
+        // bootstrap, print the version, and exit. The `preAction` hook
+        // below still fires for subcommands; we deduplicate via a
+        // `bootstrapRan` guard so the start line is written at most once
+        // per process.
+        .option('-v, --version', 'output the version number')
+        .option('-V', 'output the version number')
+        // Slice 2026-06-16-cli-logging (G3): global verbose flag. Mirrors
+        // the PEAKS_LOG_LEVEL=debug env var; with this set, the logger
+        // mirrors every entry to stderr IN ADDITION to the file.
+        // Long-only: `-v` is already bound to `--version` by the
+        // `.option()` call above, so we accept the env-var form
+        // (PEAKS_LOG_LEVEL=debug) as the short-form equivalent.
+        .option('--verbose', 'mirror log lines to stderr (also: PEAKS_LOG_LEVEL=debug)')
+        .hook('preAction', () => {
+        const opts = program.opts();
+        // Slice 2026-06-16-cli-logging (repair cycle 2): gate the bootstrap on
+        // the same `bootstrapRan` guard the version action uses, so a single
+        // process that invokes the program twice (vitest, programmatic) does
+        // not emit duplicate `peaks-loop start` JSONL entries.
+        if (!bootstrapRan) {
+            bootstrapLogger(opts.verbose === true);
+            bootstrapRan = true;
+        }
+    })
+        .action(() => {
+        // D-013 wrapper exit-code fix: when the user typed a command token but
+        // it didn't match any registered subcommand, exit non-zero with a JSON
+        // `COMMAND_NOT_FOUND` envelope. Without this check, Commander's root
+        // `.action()` runs whenever no subcommand matches (including unknown
+        // commands) and prints the help banner with exit 0 — which violates
+        // the PRD AC3.9/AC3.10 contract for `peaks agent run/list` and any
+        // other deleted/hidden command.
+        //
+        // Detection: use `program.args` (Commander's parsed argv) for the
+        // first non-option token. If it's present and Commander didn't route
+        // to a subcommand (we got here, so it didn't), the user typed an
+        // unknown command. Exit 1. `program.args` works correctly under both
+        // `parseAsync(['node', 'peaks', ...])` (real CLI) and direct in-process
+        // calls (vitest integration tests), unlike `process.argv` which is
+        // the test runner's argv.
+        //
+        // --help and --version bypass this path entirely (handled below).
+        const firstNonOption = program.args.find((arg) => !arg.startsWith('-'));
+        if (firstNonOption !== undefined) {
+            // Commander reached this `.action()` despite a positional token,
+            // which means the token was NOT routed to any subcommand. This is
+            // the unknown-command path. Emit a JSON envelope + exit 1.
+            io.stdout(JSON.stringify({
+                ok: false,
+                command: 'cli',
+                code: 'COMMAND_NOT_FOUND',
+                message: `Unknown command: ${firstNonOption}. Run \`peaks --help\` for available commands.`,
+                data: { argv: firstNonOption },
+                warnings: [],
+                nextActions: ['Run `peaks --help` to list available commands.']
+            }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
+        const opts = program.opts();
+        if (opts.V || opts.version) {
+            // AC1: write the peaks-loop start log line BEFORE printing the
+            // version, so even a bare `--version` invocation creates the log
+            // file. `bootstrapRan` dedupes when `preAction` already ran.
+            if (!bootstrapRan) {
+                bootstrapLogger(opts.verbose === true);
+                bootstrapRan = true;
+            }
+            io.stdout(CLI_VERSION);
+            return;
+        }
+        printSuperCommandCatalog(io);
+    })
+        .exitOverride();
+    registerCoreAndArtifactCommands(program, io);
+    registerWorkflowCommands(program, io);
+    registerCapabilityWorkerConfigAndSCCommands(program, io);
+    registerSubAgentCommands(program, io);
+    registerWorkspaceCommands(program, io);
+    registerSopCommands(program, io);
+    registerSuperCommands(program, io);
+    registerLeaseMetricsCommand(program, io);
+    registerLeaseStatsCommand(program, io);
+    registerContainerCommand(program, io);
+    registerVmCommand(program, io);
+    registerCronCommand(program, io);
+    registerCronSchedulerCommand(program, io);
+    // Auto-route the remaining 60+ commands after the orchestrators so the
+    // lazy `skill` parent (used by adapter-commands / sediment-commands)
+    // finds the existing `peaks skill` group registered by
+    // registerCoreAndArtifactCommands instead of being created twice.
+    autoRegisterAllCommands(program, io);
+    registerSkillVisibilityCommand(program, repoRoot);
+    return program;
+}

package/dist/hooks/pre-tool-use-sub-agent.d.ts

@@ -0,0 +1,28 @@
+import { type HookGuardResult } from '../cli/commands/sub-agent-dispatch-guard.js';
+/**
+ * Read the prompt size from the LLM platform's hook stdin. Different
+ * LLMs send different payload shapes; we accept the most common:
+ *   - Claude Code: `{"tool_name": "Bash", "tool_input": {"command": "..."}}`
+ *   - Trae: `{"tool_name": "terminal", "tool_input": {"command": "..."}}`
+ *
+ * The hook reads the `command` (or `prompt`) field and computes the
+ * byte length. If neither field is present, returns 0 (always passes).
+ */
+export declare function readPromptSizeFromHookStdin(stdin: unknown): number;
+/**
+ * Execute the hook guard via spawnSync. Returns the parsed result or
+ * a fallback (allow: true) on subprocess failure.
+ *
+ * Prefer the in-process `evaluateHookGuard` (no subprocess) when the
+ * hook is called from a TypeScript context. Use `runHookGuardSubprocess`
+ * only when the hook needs to be invoked from a non-TypeScript caller
+ * (e.g. a shell script that wraps the peaks CLI).
+ */
+export declare function runHookGuardSubprocess(prompt: string): HookGuardResult;
+/**
+ * Main entry point for the hook. Reads the LLM platform's stdin,
+ * computes the prompt size, and returns the guard result. Used by
+ * the LLM platform's hook JSON to decide whether to allow the tool
+ * call.
+ */
+export declare function runHookGuard(stdin: unknown): HookGuardResult;

package/dist/hooks/pre-tool-use-sub-agent.js

@@ -0,0 +1,105 @@
+/**
+ * G9.5 PreToolUse hook execution body.
+ *
+ * Wraps `peaks sub-agent-dispatch-guard` for LLM platform integration.
+ * The hook reads the prompt size from the LLM platform's hook stdin
+ * (Claude Code / Trae / etc.), invokes the guard CLI, and returns
+ * `{allow: true/false, reason, suggest}` JSON to the LLM platform.
+ *
+ * The hook is registered via `peaks hooks install` in the LLM
+ * platform's `settings.json` `PreToolUse` array. Only IDEs with
+ * `IdeAdapter.promptSizeAware: true` get the hook installed.
+ *
+ * The hook layer is the **strictest** layer in the G9 chain (RL-30).
+ * The CLI 兜底 layer (`peaks sub-agent dispatch --force`) can override
+ * the 80% threshold; the hook layer CANNOT.
+ */
+import { spawnSync } from 'node:child_process';
+import { evaluateHookGuard } from '../cli/commands/sub-agent-dispatch-guard.js';
+/**
+ * Read the prompt size from the LLM platform's hook stdin. Different
+ * LLMs send different payload shapes; we accept the most common:
+ *   - Claude Code: `{"tool_name": "Bash", "tool_input": {"command": "..."}}`
+ *   - Trae: `{"tool_name": "terminal", "tool_input": {"command": "..."}}`
+ *
+ * The hook reads the `command` (or `prompt`) field and computes the
+ * byte length. If neither field is present, returns 0 (always passes).
+ */
+export function readPromptSizeFromHookStdin(stdin) {
+    if (stdin === null || typeof stdin !== 'object') {
+        return 0;
+    }
+    const obj = stdin;
+    const toolInput = obj.tool_input;
+    if (toolInput === null || typeof toolInput !== 'object') {
+        return 0;
+    }
+    const ti = toolInput;
+    const candidates = ['command', 'prompt', 'text', 'input'];
+    for (const key of candidates) {
+        const v = ti[key];
+        if (typeof v === 'string') {
+            return Buffer.byteLength(v, 'utf8');
+        }
+    }
+    return 0;
+}
+/**
+ * Execute the hook guard via spawnSync. Returns the parsed result or
+ * a fallback (allow: true) on subprocess failure.
+ *
+ * Prefer the in-process `evaluateHookGuard` (no subprocess) when the
+ * hook is called from a TypeScript context. Use `runHookGuardSubprocess`
+ * only when the hook needs to be invoked from a non-TypeScript caller
+ * (e.g. a shell script that wraps the peaks CLI).
+ */
+export function runHookGuardSubprocess(prompt) {
+    const result = spawnSync('node', [
+        process.argv[1] ?? 'peaks',
+        'sub-agent-dispatch-guard',
+        '--prompt', prompt,
+        '--json'
+    ], { encoding: 'utf8' });
+    if (result.status !== 0) {
+        // Fallback: allow (don't block the dispatch on a guard subprocess failure).
+        return {
+            schema: 'peaks-hook-guard/v1',
+            allow: true,
+            code: 'OK',
+            reason: `guard subprocess failed (status ${result.status}); falling through`,
+            suggest: null,
+            tier: 'ok',
+            ratio: 0,
+            bytesUsed: 0,
+            capacityBytes: 0,
+            warnings: ['HOOK_GUARD_SUBPROCESS_FAILED']
+        };
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        return {
+            schema: 'peaks-hook-guard/v1',
+            allow: true,
+            code: 'OK',
+            reason: 'guard subprocess produced unparseable JSON; falling through',
+            suggest: null,
+            tier: 'ok',
+            ratio: 0,
+            bytesUsed: 0,
+            capacityBytes: 0,
+            warnings: ['HOOK_GUARD_SUBPROCESS_INVALID_JSON']
+        };
+    }
+}
+/**
+ * Main entry point for the hook. Reads the LLM platform's stdin,
+ * computes the prompt size, and returns the guard result. Used by
+ * the LLM platform's hook JSON to decide whether to allow the tool
+ * call.
+ */
+export function runHookGuard(stdin) {
+    const promptSize = readPromptSizeFromHookStdin(stdin);
+    return evaluateHookGuard(promptSize);
+}

package/dist/lib/render/message-renderer.d.ts

@@ -0,0 +1,20 @@
+export type MessageRenderMode = 'tty' | 'plain';
+export interface MessageRenderOptions {
+    mode: MessageRenderMode;
+    /**
+     * Optional override. When `true`, the renderer returns the input unchanged
+     * regardless of `mode`. Callers should set this when `NO_COLOR` is set,
+     * `--no-color` is passed, or `--json` is requested.
+     */
+    noColor?: boolean;
+}
+/**
+ * Render a human-readable message string for the terminal.
+ *
+ * Pure function. Returns the input unchanged when:
+ *   - `input` is empty,
+ *   - `input` is not a string (defensive: callers occasionally pass numbers/objects),
+ *   - `mode === 'plain'`,
+ *   - `noColor === true` (NO_COLOR / --no-color / --json opt-out).
+ */
+export declare function renderMessage(input: string, options: MessageRenderOptions): string;

package/dist/lib/render/message-renderer.js

@@ -0,0 +1,80 @@
+// Slice 2.0.1-ux-message-renderer — pure-function human-text renderer.
+//
+// PURE function contract:
+//   - No side effects (does not read process.stdout, does not call console.*).
+//   - Returns a string. The caller decides whether to write it to stdout.
+//   - Caller resolves the `mode` (TTY detection + opt-outs) and passes it in.
+//
+// Supported transformations (tty mode only — plain mode is a no-op pass-through):
+//   1. OSC 8 hyperlink wrapping for http://, https://, and file:// URLs.
+//      Format: ESC]8;;URL ESC\ TEXT ESC]8;; ESC\
+//   2. Markdown-lite: **bold** -> ANSI bold; `code` -> inverse-video.
+//   3. Bullet markers (lines beginning with `- ` or `* `) are preserved as-is.
+//
+// `noColor: true` (caller's signal for `NO_COLOR` / `--no-color` / `--json`) forces
+// the same pass-through behavior as `mode: 'plain'`, even if the caller somehow
+// passed `mode: 'tty'`. This is a defence-in-depth opt-out: the caller should
+// also pass `mode: 'plain'`, but we don't trust that either, because the JSON
+// envelope contract must not leak escape sequences.
+// OSC 8 escape sequence fragments. Format: ESC ] 8 ; ; URL ESC \ TEXT ESC ] 8 ; ; ESC \
+// Browsers + terminals that understand OSC 8: Windows Terminal, iTerm2, WezTerm, recent GNOME Terminal.
+const ESC = '';
+const OSC8_OPEN = `${ESC}]8;;`;
+const OSC8_SEP = `${ESC}\\`;
+const OSC8_CLOSE = `${OSC8_OPEN}${OSC8_SEP}`;
+// ANSI sequences used by the markdown-lite pass.
+const ANSI_BOLD_OPEN = `${ESC}[1m`;
+const ANSI_BOLD_CLOSE = `${ESC}[22m`;
+const ANSI_INVERSE_OPEN = `${ESC}[7m`;
+const ANSI_INVERSE_CLOSE = `${ESC}[27m`;
+// Lightweight URL detector (deliberately not RFC-3986-perfect).
+// Matches http(s):// and file:// tokens up to the first whitespace or
+// common terminator. Trailing punctuation is captured as part of the URL,
+// which is fine for display; the OSC 8 link still works because terminals
+// re-tokenise on hover/click. To stay close to the slice spec's reference
+// pattern we exclude <, >, ", ', and ` from URL characters.
+const URL_PATTERN = /(https?:\/\/|file:\/\/)[^\s<>"'`]+/g;
+// **bold** markers (non-greedy, multi-char safe). Allows ** at word boundaries.
+const BOLD_PATTERN = /\*\*([^*\n]+?)\*\*/g;
+// `inline-code` markers.
+const CODE_PATTERN = /`([^`\n]+?)`/g;
+/**
+ * Render a human-readable message string for the terminal.
+ *
+ * Pure function. Returns the input unchanged when:
+ *   - `input` is empty,
+ *   - `input` is not a string (defensive: callers occasionally pass numbers/objects),
+ *   - `mode === 'plain'`,
+ *   - `noColor === true` (NO_COLOR / --no-color / --json opt-out).
+ */
+export function renderMessage(input, options) {
+    if (typeof input !== 'string' || input.length === 0) {
+        return input;
+    }
+    if (options.mode === 'plain' || options.noColor === true) {
+        return input;
+    }
+    // Markdown-lite first, then URL linking. The order matters: bold/code
+    // transformations can wrap parts of a URL (e.g. `\`code\`` containing a URL),
+    // so we link URLs on the already-formatted string. Either order would be
+    // acceptable; linking on the formatted string means a URL inside a code
+    // span still gets hyperlink-wrapped, which is the modern-terminal-friendly
+    // choice.
+    let out = applyMarkdownLite(input);
+    out = applyHyperlinks(out);
+    return out;
+}
+function applyMarkdownLite(input) {
+    let out = input.replace(BOLD_PATTERN, (_match, inner) => {
+        return `${ANSI_BOLD_OPEN}${inner}${ANSI_BOLD_CLOSE}`;
+    });
+    out = out.replace(CODE_PATTERN, (_match, inner) => {
+        return `${ANSI_INVERSE_OPEN}${inner}${ANSI_INVERSE_CLOSE}`;
+    });
+    return out;
+}
+function applyHyperlinks(input) {
+    return input.replace(URL_PATTERN, (url) => {
+        return `${OSC8_OPEN}${url}${OSC8_SEP}${url}${OSC8_CLOSE}`;
+    });
+}

package/dist/services/24h-mode/decider.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 24h mode B3 trigger evaluation + attempts counter.
+ *
+ * Rid-020a (state-only slice). `fireB3` is the single mutating
+ * primitive: it increments the per-key counter and escalates with a
+ * `B3Escalation` when the count reaches `B3_THRESHOLD` (3). The
+ * counter is **per-key** — AC-T3 mandates B1 and B2 retries do not
+ * share a global counter. The T3/T4 auto-24H_ACTIVE path is encoded
+ * in `isAutoEngageTrigger` (BRAINSTORM is bypassed for these
+ * triggers so an offline-resumed session does not deadlock in
+ * WAITING_USER — proposal §1 T3/T4 exception).
+ */
+import { type DecisionKey, type State } from './state.js';
+import type { AutoCompactMode } from '../code/auto-compact-modes.js';
+export type AttemptsMap = Record<DecisionKey, number>;
+export declare const B3_TRIGGER_REASONS: readonly ["prd_direction_change", "blocker_3_consecutive_slices", "registry_affecting_failure", "destructive_irreversible_op", "any_B1_B2_failure_3x_non_converging", "runtime_or_shared_version_mismatch", "sub-agent_stale_5min_x3"];
+export type B3Reason = (typeof B3_TRIGGER_REASONS)[number];
+export declare class B3Escalation extends Error {
+    readonly reason: B3Reason;
+    readonly attempts: number;
+    constructor(reason: B3Reason, attempts: number);
+}
+/**
+ * Result envelope for `fireB3`. We return a discriminated union
+ * (instead of throwing) so callers can branch on `kind` without
+ * try/catch ceremony. The B3Escalation class is still exported for
+ * backward compatibility with callers that prefer the throw style.
+ */
+export type FireB3Result = {
+    kind: 'continue';
+    reason: B3Reason;
+    attempts: number;
+} | {
+    kind: 'escalate';
+    reason: B3Reason;
+    attempts: number;
+};
+export declare function isB3Reason(value: string): value is B3Reason;
+export declare function isValidReason(value: string): value is DecisionKey;
+export declare function freshAttempts(): AttemptsMap;
+/**
+ * Per AC-T1 (attempts=1 continue, no B3) and AC-T2 (attempts=3
+ * escalate), the 3rd call escalates. The threshold is intentionally
+ * NOT configurable — the proposal pins the constant so QA v3 can
+ * assert it. Returns a FireB3Result instead of throwing so test
+ * code can read the `attempts` field via plain property access
+ * (Error-subclass property access through vitest 4.1.10 matchers
+ * is unreliable; the discriminated union sidesteps that).
+ */
+export declare function fireB3(reason: B3Reason, attempts: AttemptsMap): FireB3Result;
+/**
+ * T3 (runaway recovery) and T4 (offline resume) auto-engage
+ * `24H_ACTIVE` without forcing `USER_CONFIRM` — the deferred
+ * AskUserQuestion fires at the first 10min checkpoint instead, so
+ * a T4 session does not deadlock in `WAITING_USER` while the
+ * user is offline (proposal §1 T3/T4 exception).
+ */
+export declare const AUTO_ENGAGE_TRIGGERS: readonly ["T3", "T4"];
+export type AutoEngageTrigger = (typeof AUTO_ENGAGE_TRIGGERS)[number];
+export declare function isAutoEngageTrigger(t: string): t is AutoEngageTrigger;
+/**
+ * Five trigger conditions (T1-T5) from proposal §1 + companion
+ * trigger-and-decision-autonomy sediment. T1/T2/T5 flow through
+ * BRAINSTORM; T3/T4 auto-engage and skip the gate.
+ */
+export interface TriggerCheck {
+    triggered: boolean;
+    trigger: 'T1' | 'T2' | 'T3' | 'T4' | 'T5' | null;
+    reason: string;
+}
+export declare const T1_KEYWORDS: string[];
+export declare const T2_MIN_SLICES = 30;
+export declare const T2_MIN_WALL_HOURS = 6;
+export declare const T3_MIN_MONOTONIC_GUARDS = 3;
+export declare const T3_MIN_REMAINING_SLICES = 10;
+export declare const T4_SESSION_GAP_HOURS = 4;
+export declare const T5_MIN_ACTIVE_SLICES = 3;
+export declare function checkTriggers(input: {
+    userMessage: string;
+    sliceListSize: number;
+    estimatedWallHours: number;
+    monotonicGuards: number;
+    remainingSlices: number;
+    sessionGapHours: number;
+    activeSlicesAcrossServices: number;
+}): TriggerCheck;
+/**
+ * HANDOFF is reachable via three exit conditions per proposal §1:
+ *   - user abort
+ *   - all-trigger-resolved
+ *   - B3 unresolvable (B3Escalation that the user dismisses)
+ */
+export declare const HANDOFF_EXIT_CONDITIONS: readonly ["user_abort", "all_triggers_resolved", "b3_unresolvable"];
+export type HandoffExitCondition = (typeof HANDOFF_EXIT_CONDITIONS)[number];
+export declare function isHandoffExitCondition(s: string): s is HandoffExitCondition;
+export declare function isHandoffState(s: State): boolean;
+/**
+ * Slice 2026-07-28 (rid-027): resolve the auto-compact mode from
+ * 24h-mode awareness. Returns `'partial'` when the session is
+ * `24H_ACTIVE`, otherwise `'standard'`. This is the CLI-side default;
+ * the explicit `--mode` flag in `peaks compact auto` overrides it.
+ */
+export declare function getAutoCompactMode(projectRoot: string, sessionId: string): AutoCompactMode;