peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/commands/code-job-shape-commands.js

@@ -0,0 +1,164 @@
+/**
+ * Slice rid-024 — `peaks code detect-job` + `peaks code read-job-shape`.
+ *
+ * Extracted from code-commands.ts (rid-024 split).
+ * Owns: detect-job (write JobShapeDecision), read-job-shape (read+print).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { readJobShapeDecision, writeJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED, JOB_SHAPE_ALREADY_DECIDED } from '../../services/code/job-shape-decision.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+export function registerCodeJobShapeCommands(code, io) {
+    // v3.1.1 Step 0.8 — Job-shape decision recorder.
+    // The CLI is a *recorder*, not a judge. The LLM supplies the verdict
+    // (--is-job, --rationale, --suggested-job-id, --suggested-strategy,
+    // --confidence); the CLI validates the shape, stamps `decidedAt`
+    // server-side, and writes to `.peaks/_runtime/<sessionId>/job-shape.json`.
+    addJsonOption(code
+        .command('detect-job')
+        .description('v3.1.1 Step 0.8: record the LLM\'s Job-shape judgement. CLI is a recorder, NOT a detector. ' +
+        'Pass --is-job true|false, --rationale <text>, --suggested-job-id <slug>. ' +
+        'Downstream steps call `peaks code read-job-shape` and refuse to proceed if missing.')
+        .requiredOption('--is-job <bool>', 'true | false (the LLM\'s semantic verdict)')
+        .requiredOption('--rationale <text>', '1-3 sentences the LLM writes explaining the call')
+        .requiredOption('--suggested-job-id <jid>', 'LLM-chosen stable id, slug-safe (/^[a-z0-9][a-z0-9-]{2,40}$/)')
+        .option('--suggested-strategy <single|rotating>', 'single | rotating', 'single')
+        .option('--confidence <high|medium|low>', 'high | medium | low', 'medium')
+        .option('--force', 'overwrite an existing decision file')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--project <path>', 'target project root (default: findProjectRoot(cwd))')
+        .option('--prompt <text>', 'override the prompt hashed into promptHash (default: read last-prompt.txt if present, else empty)')).action(async (opts) => {
+        try {
+            if (opts.isJob !== 'true' && opts.isJob !== 'false') {
+                printResult(io, fail('code.detect-job', 'INVALID_FLAG', `--is-job must be true | false (got "${opts.isJob}")`, { provided: opts.isJob }, ['Pass --is-job true or --is-job false']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.suggestedStrategy !== 'single' && opts.suggestedStrategy !== 'rotating') {
+                printResult(io, fail('code.detect-job', 'INVALID_FLAG', `--suggested-strategy must be single | rotating (got "${opts.suggestedStrategy}")`, { provided: opts.suggestedStrategy }, ['Pass --suggested-strategy single or --suggested-strategy rotating']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.confidence !== 'high' && opts.confidence !== 'medium' && opts.confidence !== 'low') {
+                printResult(io, fail('code.detect-job', 'INVALID_FLAG', `--confidence must be high | medium | low (got "${opts.confidence}")`, { provided: opts.confidence }, ['Pass --confidence high | medium | low']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const jidRe = /^[a-z0-9][a-z0-9-]{2,40}$/;
+            if (!jidRe.test(opts.suggestedJobId)) {
+                printResult(io, fail('code.detect-job', 'INVALID_FLAG', `--suggested-job-id must match /^[a-z0-9][a-z0-9-]{2,40}$/ (got "${opts.suggestedJobId}")`, { provided: opts.suggestedJobId }, ['Pass a slug-safe id (lowercase, digits, dashes; 3-41 chars)']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const sessionId = opts.sessionId ?? readActiveSidForJobShape(projectRoot);
+            if (sessionId === null) {
+                printResult(io, fail('code.detect-job', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-code`', null, ['Re-run with --session-id <sid>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Prompt source: explicit --prompt > last-prompt.txt > empty.
+            let promptText = opts.prompt ?? '';
+            if (opts.prompt === undefined) {
+                const lastPromptPath = join(projectRoot, '.peaks', '_runtime', sessionId, 'txt', 'last-prompt.txt');
+                if (existsSync(lastPromptPath)) {
+                    try {
+                        promptText = readFileSync(lastPromptPath, 'utf8');
+                    }
+                    catch { // TODO(g2): legacy silent catch — grace: 1 minor release
+                        promptText = '';
+                    }
+                }
+            }
+            const record = writeJobShapeDecision(projectRoot, sessionId, {
+                isJob: opts.isJob === 'true',
+                rationale: opts.rationale,
+                suggestedJobId: opts.suggestedJobId,
+                suggestedStrategy: opts.suggestedStrategy,
+                confidence: opts.confidence,
+                prompt: promptText
+            }, { force: opts.force === true });
+            printResult(io, ok('code.detect-job', {
+                sessionId: record.sessionId,
+                promptHash: record.promptHash,
+                decision: record.decision,
+                schemaVersion: record.schemaVersion
+            }, [], [
+                `Decision recorded: isJob=${record.decision.isJob} strategy=${record.decision.suggestedStrategy} confidence=${record.decision.confidence}`,
+                `File: .peaks/_runtime/${record.sessionId}/job-shape.json`
+            ]), opts.json);
+        }
+        catch (err) {
+            if (err instanceof JobShapeDecisionError) {
+                const code = err.code === JOB_SHAPE_ALREADY_DECIDED ? JOB_SHAPE_ALREADY_DECIDED : err.code === JOB_SHAPE_NOT_DECIDED ? JOB_SHAPE_NOT_DECIDED : err.code;
+                printResult(io, fail('code.detect-job', code, err.message, err.details ?? null, [
+                    err.code === JOB_SHAPE_ALREADY_DECIDED
+                        ? 'Re-run with --force to overwrite the existing decision.'
+                        : 'Re-run with valid flags.'
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('code.detect-job', 'DETECT_JOB_FAILED', getErrorMessage(err), null, ['Verify the flags and try again']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    // v3.1.1 Step 0.8 — read-only validator. Downstream steps call this
+    // to refuse to proceed if the LLM has not yet recorded a decision.
+    addJsonOption(code
+        .command('read-job-shape')
+        .description('v3.1.1 Step 0.8: return the recorded Job-shape decision. ' +
+        'Returns JOB_SHAPE_NOT_DECIDED when the LLM has not yet recorded a verdict.')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--project <path>', 'target project root (default: findProjectRoot(cwd))')).action((opts) => {
+        try {
+            const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const sessionId = opts.sessionId ?? readActiveSidForJobShape(projectRoot);
+            if (sessionId === null) {
+                printResult(io, fail('code.read-job-shape', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-code`', null, ['Re-run with --session-id <sid>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const record = readJobShapeDecision(projectRoot, sessionId);
+            printResult(io, ok('code.read-job-shape', {
+                sessionId: record.sessionId,
+                promptHash: record.promptHash,
+                decision: record.decision,
+                schemaVersion: record.schemaVersion
+            }, [], [
+                `Decision on file: isJob=${record.decision.isJob} strategy=${record.decision.suggestedStrategy} confidence=${record.decision.confidence}`
+            ]), opts.json);
+        }
+        catch (err) {
+            if (err instanceof JobShapeDecisionError) {
+                printResult(io, fail('code.read-job-shape', err.code, err.message, err.details ?? null, [
+                    err.code === JOB_SHAPE_NOT_DECIDED
+                        ? 'Run `peaks code detect-job` to record a decision.'
+                        : 'Investigate the decision file integrity.'
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('code.read-job-shape', 'READ_JOB_SHAPE_FAILED', getErrorMessage(err), null, ['Verify the project path and try again']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}
+// Local helper (was `readActiveSid` in code-commands.ts before rid-024 split).
+// Both detect-job and read-job-shape need to read the active sid from
+// presence. We re-import getSkillPresence here to avoid the cross-file
+// helper import.
+function readActiveSidForJobShape(projectRoot) {
+    try {
+        const presence = getSkillPresence(projectRoot);
+        if (presence === null || presence === undefined)
+            return null;
+        return presence.sessionId ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli/commands/code-mode-gate-commands.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Slice rid-024 — `peaks code plan` + `peaks code should-pause` (mode-gate).
+ *
+ * Extracted from code-commands.ts (rid-024 split).
+ * Owns: `plan` (build+print CodePlan), `should-pause` (D5 mode-gate).
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeModeGateCommands(code: Command, io: ProgramIO): void;

package/dist/cli/commands/code-mode-gate-commands.js

@@ -0,0 +1,223 @@
+/**
+ * Slice rid-024 — `peaks code plan` + `peaks code should-pause` (mode-gate).
+ *
+ * Extracted from code-commands.ts (rid-024 split).
+ * Owns: `plan` (build+print CodePlan), `should-pause` (D5 mode-gate).
+ */
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { GATED_STEPS, isHardFloorCategory, isCodeMode, isCommitBoundaryAction, shouldPauseAtGate, formatAutoProceedLogLine } from '../../services/code/mode-gate.js';
+import { checkStalePresence } from '../../services/skills/skill-presence-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { emitObservabilityEvent } from '../../services/observability/observability-service.js';
+import { buildCodePlan } from './code-commands.js';
+export function registerCodeModeGateCommands(code, io) {
+    code
+        .command('plan')
+        .description('Build and print a CodePlan without executing it')
+        .argument('<change-id>', 'change id to plan against')
+        .option('--fast', 'fast mode: skip memory full-load, standards preflight, and QA repair loop', false)
+        .option('--json', 'emit JSON envelope')
+        .action((sessionId, opts) => {
+        const plan = buildCodePlan({ sessionId, fast: opts.fast === true });
+        if (opts.json === true) {
+            process.stdout.write(JSON.stringify({ ok: true, data: plan }) + '\n');
+        }
+        else {
+            process.stdout.write(`change-id: ${plan.sessionId}\n`);
+            for (const step of plan.steps) {
+                const flag = step.skipped ? 'SKIP' : 'RUN ';
+                const repair = step.id === 'qa-cycle' ? ` repair=${step.repairLoop === true ? 'on' : 'off'}` : '';
+                process.stdout.write(`  [${flag}] ${step.id}${repair}\n`);
+            }
+        }
+    });
+    addJsonOption(code
+        .command('should-pause')
+        .description('v2.11.0 D5: ask the mode-gate whether the LLM should pause for an AskUserQuestion at a given step. ' +
+        'full-auto / swarm auto-proceed (recommended = chosen); assisted / strict pause. ' +
+        'The 3 hard-floor categories always pause regardless of mode. ' +
+        'v2.15.0 slice 002 AC-2: when --step step-1-mode-select AND the recorded skill presence is stale ' +
+        '(outer-session-mismatch / no-presence), the gate returns shouldPause: true with reason "stale-presence" ' +
+        'even if the user passed --mode full-auto. The re-ask is mandatory — sticky-mode from a previous ' +
+        'session is NOT authoritative.')
+        .requiredOption('--step <step>', `one of: ${GATED_STEPS.join(', ')}`)
+        // v2.18.4 slice 002-fix-first-run-step-gates (Bug 2):
+        // `--mode` is now OPTIONAL. Step 1's SEMANTIC is "ask the user
+        // what mode to use" — requiring --mode to ask mode is a
+        // chicken-and-egg. When --mode is omitted, default to
+        // 'full-auto' so the gate can still evaluate; the gate's hard-
+        // pause on `step-1-mode-select` (mode-selection-itself) will
+        // pause regardless, and the LLM-side caller can present
+        // AskUserQuestion without first knowing the mode.
+        .option('--mode <mode>', 'one of: full-auto, assisted, swarm, strict. Defaults to full-auto when omitted (Step 1 chicken-and-egg fix).')
+        .option('--hard-floor <category>', 'optional hard-floor override (irreversible-external-side-effect | authentication-credential | multi-day-investment | commit-boundary-side-effect)')
+        .option('--recommended <option>', 'recommended option label to log when auto-proceeding', 'recommended-option')
+        .option('--project <path>', 'v2.15.0 slice 002 AC-2: project root for presence:check-stale. Default: cwd. Pass only when step=step-1-mode-select.')
+        .option('--ignore-stale-presence', 'v2.15.0 slice 002 AC-2: skip the stale-presence check (test seam). Default false.')
+        .option('--commit-boundary-action <id>', 'v2.15.0 slice 002 AC-4 CLI seam (slice 002 repair): when the LLM is about to run a commit-boundary action (git push / tag / npm publish / global install), pass the action id here to force the hard-floor pause. Valid: git-push | git-tag | npm-publish | npm-install-global | peaks-global-install. Default: omitted (no override).')).action((opts) => {
+        try {
+            // v2.18.4 slice 002-fix-first-run-step-gates (Bug 2):
+            // --mode is optional. Default to 'full-auto' when omitted
+            // so step-1-mode-select can run without forcing the caller
+            // to know the mode up front. The gate's hard-pause on
+            // step-1-mode-select will still pause regardless.
+            const mode = opts.mode ?? 'full-auto';
+            if (!isCodeMode(mode)) {
+                printResult(io, fail('code.should-pause', 'INVALID_MODE', `mode must be one of full-auto, assisted, swarm, strict (got "${mode}")`, { provided: mode }, ['Pass --mode full-auto | assisted | swarm | strict']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!GATED_STEPS.includes(opts.step)) {
+                printResult(io, fail('code.should-pause', 'INVALID_STEP', `step must be one of the 14 GATED_STEPS (got "${opts.step}")`, { provided: opts.step, allowed: [...GATED_STEPS] }, ['Pass --step <one of the 14 GATED_STEPS>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const hardFloor = opts.hardFloor;
+            if (hardFloor !== undefined && !isHardFloorCategory(hardFloor)) {
+                printResult(io, fail('code.should-pause', 'INVALID_HARD_FLOOR', `hard-floor must be one of: irreversible-external-side-effect | authentication-credential | multi-day-investment | commit-boundary-side-effect (got "${hardFloor}")`, { provided: hardFloor }, ['Omit --hard-floor or pass a valid category']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            // v2.15.0 slice 002 repair (QA blocker): validate the
+            // --commit-boundary-action flag at the CLI boundary. The
+            // service-layer `shouldPauseAtGate` accepts a boolean
+            // `commitBoundaryAction: true`; this flag tells the CLI to
+            // pass it through. An unknown action id is rejected here
+            // (not silently ignored) so typos fail loud.
+            const commitBoundaryActionId = opts.commitBoundaryAction;
+            if (commitBoundaryActionId !== undefined && !isCommitBoundaryAction(commitBoundaryActionId)) {
+                printResult(io, fail('code.should-pause', 'INVALID_COMMIT_BOUNDARY_ACTION', `--commit-boundary-action must be one of: git-push | git-tag | npm-publish | npm-install-global | peaks-global-install (got "${commitBoundaryActionId}")`, { provided: commitBoundaryActionId }, ['Omit --commit-boundary-action or pass a valid action id']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const step = opts.step;
+            // Slice 002 (v2.15.0) AC-2: when the caller is asking about
+            // Step 1 AND the recorded presence is stale, OVERRIDE the
+            // gate decision to PAUSE with reason='stale-presence'. The
+            // hard-pause on step-1-mode-select (defect #1 fix from
+            // 2026-06-28-code-mode-bypass-fix) is already in effect, so
+            // this only adds the structured `stale` reason + an
+            // envelope-level `stalePresence` field so downstream tooling
+            // (statusline, sub-agent dispatch) can act on it.
+            let stalePresence = null;
+            if (opts.step === 'step-1-mode-select' && opts.ignoreStalePresence !== true) {
+                const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+                stalePresence = checkStalePresence({ projectRootOverride: projectRoot });
+            }
+            if (stalePresence !== null && stalePresence.stale) {
+                // Build the envelope manually so we can attach the extra
+                // structured fields (stalePresence, logLine) and emit a
+                // dedicated observability event tagged with reason='stale-presence'.
+                const sid = readActiveSidForModeGate(opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd()) ?? '';
+                if (sid.length > 0) {
+                    emitObservabilityEvent({
+                        schemaVersion: 1,
+                        ts: new Date().toISOString(),
+                        sessionId: sid,
+                        category: 'mode-gate',
+                        detail: {
+                            mode: mode,
+                            step,
+                            shouldPause: true,
+                            reason: 'stale-presence',
+                            staleReason: stalePresence.reason,
+                            recordedOuterSessionId: stalePresence.recordedOuterSessionId,
+                            currentOuterSessionId: stalePresence.currentOuterSessionId
+                        }
+                    }, { projectRoot: opts.project ?? process.cwd() });
+                }
+                printResult(io, ok('code.should-pause', {
+                    shouldPause: true,
+                    reason: `stale-presence — re-ask Step 1 (${stalePresence.reason}; recorded outer session id does not match current)`,
+                    gateKind: 'mode-selection-itself',
+                    logLine: `auto-pause (${mode}, stale-presence:${stalePresence.reason}): ${step} → re-ask`,
+                    stalePresence: {
+                        stale: true,
+                        reason: stalePresence.reason,
+                        recordedOuterSessionId: stalePresence.recordedOuterSessionId,
+                        currentOuterSessionId: stalePresence.currentOuterSessionId
+                    }
+                }, [], [
+                    `Recorded outer session id "${stalePresence.recordedOuterSessionId ?? '?'}" does not match current outer session id "${stalePresence.currentOuterSessionId ?? '?'}".`,
+                    `peaks-code Step 1 must AskUserQuestion to confirm the mode for THIS session (slice 002 AC-2).`
+                ]), opts.json);
+                return;
+            }
+            const decision = shouldPauseAtGate({
+                mode: mode,
+                step,
+                hardFloorCategory: hardFloor,
+                // v2.15.0 slice 002 repair (QA blocker): translate the CLI
+                // --commit-boundary-action flag into the service-layer
+                // boolean. The CLI accepts the action id (e.g. "git-push")
+                // for ergonomic machine consumption; the service layer only
+                // cares that *some* commit-boundary action triggered the
+                // override. The actual action id is echoed in the JSON
+                // envelope below.
+                commitBoundaryAction: commitBoundaryActionId !== undefined
+            });
+            // Slice C of v2.11.1 — observability hook #4/7. Fire-and-forget
+            // per PRD Q4 (full-auto must never fail-loud). projectRoot
+            // resolution mirrors observability-commands.ts (findProjectRoot
+            // → cwd fallback).
+            const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+            const sid = readActiveSidForModeGate(projectRoot) ?? '';
+            if (sid.length > 0) {
+                emitObservabilityEvent({
+                    schemaVersion: 1,
+                    ts: new Date().toISOString(),
+                    sessionId: sid,
+                    category: 'mode-gate',
+                    detail: {
+                        mode: mode,
+                        step,
+                        shouldPause: decision.shouldPause,
+                        reason: decision.reason,
+                        ...(decision.hardFloorCategory !== undefined ? { hardFloorCategory: decision.hardFloorCategory } : {})
+                    }
+                }, { projectRoot });
+            }
+            const logLine = formatAutoProceedLogLine({
+                mode: mode,
+                step,
+                recommendedOption: opts.recommended ?? 'recommended-option',
+                hardFloorCategory: hardFloor
+            });
+            printResult(io, 
+            // v2.15.0 slice 002 repair: include the commit-boundary
+            // action id in the envelope (when provided) so the LLM-side
+            // caller can echo which boundary was checked. Null when no
+            // --commit-boundary-action flag was passed.
+            ok('code.should-pause', {
+                ...decision,
+                logLine,
+                ...(commitBoundaryActionId !== undefined ? { commitBoundaryAction: commitBoundaryActionId } : {})
+            }, [], [
+                decision.shouldPause
+                    ? `Mode ${mode} + step ${opts.step} → PAUSE for AskUserQuestion${commitBoundaryActionId !== undefined ? ` (commit-boundary: ${commitBoundaryActionId})` : ''}`
+                    : `Mode ${mode} + step ${opts.step} → AUTO-PROCEED with recommended option`
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('code.should-pause', 'SHOULD_PAUSE_FAILED', getErrorMessage(err), null, ['Re-run with --json for envelope shape']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}
+// Local helper (was `readActiveSid` in code-commands.ts before rid-024 split).
+// The mode-gate stale-presence check needs the active sid for the
+// observability event; we re-import getSkillPresence here to avoid the
+// cross-file helper import.
+import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+function readActiveSidForModeGate(projectRoot) {
+    try {
+        const presence = getSkillPresence(projectRoot);
+        if (presence === null || presence === undefined)
+            return null;
+        return presence.sessionId ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli/commands/code-review-commands.d.ts

@@ -0,0 +1,34 @@
+/**
+ * peaks code-review * CLI surface — soft-optional ocr integration
+ * for peaks-rd Gate B3.
+ *
+ * Per the "skill-first / CLI-auxiliary" tenet, peaks-rd SKILL.md
+ * is the primary surface; this CLI returns structured JSON the
+ * skill consumes to produce a second-opinion code review.
+ *
+ * Subcommands:
+ *   - `peaks code-review detect-ocr` — JSON envelope describing the
+ *     current ocr install + config state (5 reasons: ready /
+ *     package-missing / binary-missing / config-missing /
+ *     detection-failed). Source of truth for the LLM endpoint
+ *     config is `peaksConfig.ocr.llm` in the user's peaks-loop
+ *     config (NOT `~/.opencodereview/config.json`).
+ *   - `peaks code-review run-ocr [--from --to --commit]` — invokes
+ *     `ocr review --format json` and wraps the result in a peaks
+ *     ResultEnvelope. Soft-fails when ocr isn't ready so peaks-rd
+ *     can continue without the second-opinion review. Injects the
+ *     LLM endpoint config as env vars (OCR_LLM_URL / OCR_LLM_TOKEN
+ *     / OCR_LLM_MODEL / OCR_USE_ANTHROPIC / OCR_LLM_AUTH_HEADER)
+ *     so the ocr subprocess never has to read from a file the
+ *     user did not set up themselves.
+ *   - `peaks code-review config-template` — prints the JSON snippet
+ *     the user should paste into their peaks-loop config.json. It
+ *     does NOT write anything. The user is in control of their
+ *     LLM token / URL / model. No `peaks ocr config set`; the user
+ *     either edits the JSON directly or uses `peaks config set
+ *     --key ocr.llm.url --value '...'` (a peaks-loop command, not
+ *     an ocr command).
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeReviewCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/code-review-commands.js

@@ -0,0 +1,83 @@
+import { getOcrConfigTemplate, detectOcr, runOcrReview } from '../../services/code-review/ocr-service.js';
+import { getOcrLlmConfig, getUserConfigPath, redactConfigSecrets } from '../../services/config/config-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+export function registerCodeReviewCommands(program, io) {
+    const codeReview = program
+        .command('code-review', { hidden: true })
+        .description('Code-review primitives for peaks-rd Gate B3. Wraps the soft-optional `@alibaba-group/open-code-review` (ocr) tool when it is installed + configured; peaks-rd uses the structured JSON output as a second-opinion review alongside its own LLM review. ocr is a peerDependency of peaks-loop 2.8.2+ (was briefly promoted to a hard dependency in 2.0.1/2.0.2, then demoted to optionalDependencies 2.0.3+ — peer in 2.8.2 because its postinstall downloads a Go binary via HTTPS and would otherwise slow `npm i -g peaks-loop` in restricted environments). Install manually with `npm i -g @alibaba-group/open-code-review` if you want second-opinion reviews. LLM endpoint config lives under `peaksConfig.ocr.llm` in the user config — run `peaks code-review config-template` to see the JSON snippet to paste.');
+    addJsonOption(codeReview
+        .command('detect-ocr')
+        .description('Read-only probe: returns the ocr install + config state as a JSON envelope (5 reasons: ready / package-missing / binary-missing / config-missing / detection-failed). peaks-rd calls this first to decide whether to invoke `run-ocr`. Reads the LLM endpoint from `peaksConfig.ocr.llm` (not from ~/.opencodereview/config.json).')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        try {
+            const detect = detectOcr({
+                cwd: projectRoot,
+                peaksConfigPath: getUserConfigPath(),
+                peaksOcrConfig: getOcrLlmConfig(),
+            });
+            const envelope = detect.state === 'ready'
+                ? ok('code-review.detect-ocr', detect, [...detect.warnings], [...detect.nextActions])
+                : fail('code-review.detect-ocr', detect.state.toUpperCase().replace(/-/g, '_'), `ocr is not ready: ${detect.state}`, detect, [...detect.nextActions]);
+            printResult(io, envelope, options.json);
+            if (detect.state !== 'ready') {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('code-review.detect-ocr', 'DETECT_OCR_FAILED', getErrorMessage(error), { state: 'detection-failed', packageInstalled: false, binaryPath: null, version: null, configPath: '', configValid: false, missingKeys: [] }, ['Re-run with `--project <path>` pointing at a known-good project root.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(codeReview
+        .command('run-ocr')
+        .description('Run `ocr review --format json` and return the parsed JSON envelope. Soft-fails (exit 0, ok=false) when ocr is not ready, so peaks-rd can continue without the second-opinion review and surface the install/config nextActions to the user. The peaks-loop `peaksConfig.ocr.llm` block is injected as OCR_LLM_URL / OCR_LLM_TOKEN / ... env vars so the ocr subprocess never has to read ~/.opencodereview/config.json.')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--from <ref>', 'git ref to diff from (e.g. main, origin/main)')
+        .option('--to <ref>', 'git ref to diff to (e.g. HEAD, feature-branch)')
+        .option('--commit <sha>', 'specific commit SHA to review')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        try {
+            const result = runOcrReview({
+                cwd: projectRoot,
+                peaksConfigPath: getUserConfigPath(),
+                peaksOcrConfig: getOcrLlmConfig(),
+                input: { projectRoot, ...(options.from !== undefined && { from: options.from }), ...(options.to !== undefined && { to: options.to }), ...(options.commit !== undefined && { commit: options.commit }) },
+            });
+            // Soft-fail policy: when ocr is not ready or the subprocess
+            // failed, we still return a JSON envelope (ok=false) but
+            // do NOT set process.exitCode — the caller is expected to
+            // pattern-match on the state and proceed without ocr.
+            const envelope = result.spawned && result.exitCode === 0
+                ? ok('code-review.run-ocr', result, [...result.warnings], [...result.nextActions])
+                : fail('code-review.run-ocr', result.state.toUpperCase().replace(/-/g, '_'), result.spawned ? `ocr review exited ${result.exitCode}` : `ocr is not ready: ${result.state}`, result, [...result.nextActions]);
+            printResult(io, envelope, options.json);
+            // Intentionally do NOT set process.exitCode here — soft-fail.
+        }
+        catch (error) {
+            printResult(io, fail('code-review.run-ocr', 'RUN_OCR_FAILED', getErrorMessage(error), { spawned: false, state: 'detection-failed', exitCode: null, stdout: '', stderr: '', durationMs: 0, parsed: null }, ['Run `peaks code-review detect-ocr --json` to inspect ocr install state.']), options.json);
+            // Soft-fail on exception too — peaks-rd should continue.
+        }
+    });
+    addJsonOption(codeReview
+        .command('config-template')
+        .description('Print the JSON snippet the user should paste into their peaks-loop config (`peaksConfig.ocr.llm`). This command does NOT write anything. The user is the only party that touches the LLM token / URL / model — peaks-loop never auto-configures the endpoint. Token value is shown as the placeholder "<your-api-key>"; replace it before pasting.')).action((options) => {
+        const template = getOcrConfigTemplate();
+        const targetPath = getUserConfigPath();
+        const currentConfig = getOcrLlmConfig();
+        const currentRedacted = currentConfig === null ? null : redactConfigSecrets(currentConfig, 'ocr.llm');
+        const payload = {
+            targetPath,
+            currentConfig: currentRedacted,
+            template,
+            nextActions: [
+                `Edit ${targetPath} and add the "ocr" block from the template above.`,
+                'OR use peaks-loop config set with one key at a time: `peaks config set --key ocr.llm.url --value \'<url>\'` etc.',
+                'The authToken field is sensitive and is stored in the user layer (`~/.peaks/config.json`); peaks-loop will not commit it.',
+                'Re-run `peaks code-review detect-ocr --json` to verify the new state is `ready`.',
+            ],
+        };
+        printResult(io, ok('code-review.config-template', payload), options.json);
+    });
+}

package/dist/cli/commands/code-run-command.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type CodeRun24hOptions = {
+    json?: boolean;
+    '24h'?: boolean;
+    project?: string;
+    sessionId?: string;
+    tier?: string;
+    trigger?: string;
+};
+/** Registers `peaks code run`, the thin 24h-mode bridge for peaks-code. */
+export declare function registerCodeRunCommand(code: Command, io: ProgramIO): void;

package/dist/cli/commands/code-run-command.js

@@ -0,0 +1,68 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { read24hState, write24hState } from '../../services/24h-mode/index.js';
+import { getErrorMessage } from '../cli-helpers.js';
+function emit(io, payload, json) {
+    io.stdout((json === true ? JSON.stringify(payload) : JSON.stringify(payload, null, 2)) + '\n');
+}
+async function sessionId(options, projectRoot) {
+    if (options.sessionId)
+        return options.sessionId;
+    const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
+    return getSessionIdCanonical(projectRoot);
+}
+/** Registers `peaks code run`, the thin 24h-mode bridge for peaks-code. */
+export function registerCodeRunCommand(code, io) {
+    code
+        .command('run')
+        .description('Run a code change; --24h enables the 24h orchestration bridge')
+        .argument('[change-id]', 'change id or natural-language work reference')
+        .option('--24h', 'enable 24h mode')
+        .option('--tier <tier>', 'routing tier (T1, T2, T3, or T4)')
+        .option('--trigger <trigger>', 'auto-engage trigger (T3 or T4)')
+        .option('--project <path>', 'project root (defaults to current directory)')
+        .option('--session-id <sessionId>', 'explicit session id')
+        .option('--json', 'emit machine-readable JSON')
+        .action(async (changeId, options) => {
+        if (options['24h'] !== true) {
+            emit(io, { ok: false, code: 'CODE_RUN_24H_REQUIRED', message: 'code run requires --24h for this integration surface' }, options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const projectRoot = resolveCanonicalProjectRoot(options.project ?? process.cwd());
+        const sid = await sessionId(options, projectRoot);
+        if (!sid) {
+            emit(io, { ok: false, code: 'NO_ACTIVE_SESSION', message: 'no --session-id and no canonical binding' }, options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const autoEngage = options.tier === 'T3' || options.tier === 'T4' || options.trigger === 'T3' || options.trigger === 'T4';
+        try {
+            const current = read24hState(projectRoot, sid);
+            if (!autoEngage) {
+                emit(io, {
+                    ok: true,
+                    data: { changeId: changeId ?? null, mode: '24H_REQUESTED', state: current.state, brainstorming: 'reference-only', sessionId: sid },
+                    next: 'Use the brainstorming reference-only bridge, then let peaks-code continue the normal runbook.'
+                }, options.json);
+                return;
+            }
+            const nextState = '24H_ACTIVE';
+            const next = write24hState(projectRoot, sid, {
+                ...current,
+                state: nextState,
+                enteredAt: new Date().toISOString(),
+                enteredFrom: current.state,
+                exitCondition: null
+            });
+            emit(io, {
+                ok: true,
+                data: { changeId: changeId ?? null, mode: '24H_ACTIVE', state: nextState, autoEngaged: true, trigger: options.trigger ?? options.tier, sessionId: sid, path: next.path },
+                next: 'Continue the existing 24H_ACTIVE flow; no brainstorming gate is required for T3/T4.'
+            }, options.json);
+        }
+        catch (error) {
+            emit(io, { ok: false, code: 'CODE_RUN_24H_FAILED', message: getErrorMessage(error), sessionId: sid }, options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/code-runtime-commands.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Slice rid-024 — runtime probes: post-compact-detect / auto-compact /
+ * context-now / gate-step-08 / emit-handoff.
+ *
+ * Extracted from code-commands.ts (rid-024 split).
+ * Owns: 5 sub-commands that read or mutate runtime state.
+ * Owns the `readActiveSid` helper (only used by these runtime probes).
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeRuntimeCommands(code: Command, io: ProgramIO): void;