peaks-loop 4.0.0-beta.9 → 4.0.3

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

@@ -30,7 +30,7 @@ import { EVOLUTION_TARGET_KINDS, } from "../../services/evolution/evolution-type
 import { findProjectRoot } from "../../services/config/config-safety.js";
 import { runIndependentEvaluator, } from "../../services/evolution/independent-evaluator-runner.js";
 import { addJsonOption, getErrorMessage, printResult } from "../cli-helpers.js";
-import { fail, ok } from "../../shared/result.js";
+import { fail, ok } from 'peaks-loop-shared/result';
 /**
  * Parse `--target <kind:id>`. Returns the kind + id, or `null` on
  * failure. Validates `kind` against the EVOLUTION_TARGET_KINDS

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

@@ -17,7 +17,7 @@ import { resolve as resolvePath } from 'node:path';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { generatePromotionStub, isPromotionLayer, listUnpromotedFeedback, parseFeedbackMemory, PROMOTION_LAYER_DETAILS, PROMOTION_LAYERS, promoteFeedback } from '../../services/feedback/feedback-promotion-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerFeedbackCommands(program, io) {
     const feedback = program

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

@@ -20,7 +20,7 @@
 import { existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 /** Whitelist of supported `--llm-provider` values for `peaks prepare-final-review`. */
 const SUPPORTED_LLM_PROVIDERS = ['stub'];
 function isSupportedLlmProvider(value) {

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

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path';
 import { captureDerivedVariant, captureHistoricalFixture, EDGE_CASE_VARIANTS, ENVELOPE_KINDS } from '../../services/fixture/index.js';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 function isEnvelopeKind(v) {
     return ENVELOPE_KINDS.includes(v);
 }

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

@@ -13,7 +13,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { appendSyncRecord, buildForkStatusReport, makeSyncId, readForkState, recommendStableTags, updateSyncRecordStatus, writeForkState } from '../../services/fork/fork-sync-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerForkCommands(program, io) {
     const fork = program

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

@@ -1,9 +1,11 @@
 import { enforceBashCommand, recordGateBypass, GateBypassError } from '../../services/sop/gate-enforce-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { evaluateWorktreeAuth } from '../../services/hooks/worktree-authorization-gate.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { detectIdeFromContext, parseClaudeShapeStdin } from '../../services/ide/hook-translator.js';
+import { detectIdeFromContext, parseClaudeShapeStdin, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
 import { getAdapter } from '../../services/ide/ide-registry.js';
-import { emitBlock, emitHint } from '../../services/hooks/output.js';
+import { emitBlock, emitDecision, emitHint } from '../../services/hooks/output.js';
 /**
  * Read the PreToolUse hook payload. `PEAKS_HOOK_STDIN` is a test seam; production
  * reads stdin. The CLI-side stdin reader is intentionally kept here (not in
@@ -28,6 +30,35 @@ async function readHookPayload() {
         process.stdin.on('error', () => resolveStdin(data));
     });
 }
+/**
+ * Map Claude Code tool name to the gate's internal `ToolCallKind`. Anything we don't recognize
+ * returns `'Other'` — the worktree gate is opt-in by tool, so unknown tools short-circuit to allow.
+ */
+function classifyTool(toolName) {
+    if (toolName === 'Bash')
+        return 'Bash';
+    if (toolName === 'Agent' || toolName === 'Task')
+        return 'Agent';
+    if (toolName === 'EnterWorktree')
+        return 'EnterWorktree';
+    if (toolName === 'Workflow')
+        return 'Workflow';
+    return 'Other';
+}
+/**
+ * Best-effort extraction of the `isolation` field for `Agent` / `Task` tool calls. The Claude
+ * hook payload puts args under `tool_input`, the Cursor/Trae sibling puts them under `toolInput`.
+ * Both shapes are accepted; everything else returns null.
+ */
+function extractIsolation(parsed) {
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const input = pluckObject(parsed, ['tool_input']) ?? pluckObject(parsed, ['toolInput']);
+    if (input === undefined)
+        return null;
+    const value = pluckString(input, ['isolation']);
+    return value === undefined ? null : value;
+}
 export function registerGateCommands(program, io) {
     const gate = program.command('gate').description('SOP gate enforcement (PreToolUse hook handler and bypass)');
     addJsonOption(gate
@@ -57,12 +88,69 @@ export function registerGateCommands(program, io) {
             // change required.
             const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
             if (toolName !== adapter.toolMatcher || typeof command !== 'string' || command.trim().length === 0) {
-                // Not a guarded surface — allow (no output = normal permission flow).
+                // Not a guarded surface — allow. Emit minimal JSON on stdout so Claude
+                // Code's PreToolUse hook validator accepts the response. Empty stdout
+                // is rejected with "Hook JSON output validation failed — Invalid input"
+                // in Claude Code 2.x; `{}` is the canonical no-op marker.
                 if (options.json === true) {
                     printResult(io, ok('gate.enforce', { decision: 'allow', skipped: true }), true);
                 }
+                else {
+                    emitDecision(io, {});
+                }
                 return;
             }
+            // slice 2026-07-27-worktree-user-auth: BEFORE the SOP gate runs, check the worktree
+            // authorization gate. The worktree gate is narrower than the SOP gate (it only inspects
+            // a small set of worktree-mutating operations) and is fail-CLOSED. The two layers are
+            // complementary: SOP gates decide "may this command run under this SOP's state", the
+            // worktree gate decides "did the user explicitly authorize this worktree-mutating operation
+            // in the current task". The worktree gate is cheap and self-contained, so it runs first
+            // to give the LLM a clear error reason before the SOP gate would otherwise allow.
+            //
+            // We extract the tool kind from the hook payload (Bash/Agent/EnterWorktree/Workflow).
+            // For Agent/Task we also pull `isolation` from the tool input — only "worktree" isolation
+            // is gated. For all other tool kinds the worktree gate is a no-op.
+            const toolKind = classifyTool(toolName);
+            if (toolKind !== 'Other') {
+                const sessionId = getCurrentSessionId(options.project) ?? 'unknown-sid';
+                // slice 2026-07-29-worktree-l2-extended Part 2.B: the gate consults
+                // the lease file referenced by `PEAKS_WORKTREE_LEASE_ID` as a
+                // second authorization path when no `peaks worktree auth grant`
+                // is on file. Dispatch (Part 2.C) injects the env var on every
+                // sub-agent spawn so worktree-mutating tool calls from inside
+                // the sub-agent process auto-authorize via the lease instead
+                // of requiring a separate grant.
+                const leaseId = process.env.PEAKS_WORKTREE_LEASE_ID ?? null;
+                // Part 19: container lease (L4) is the parallel path for
+                // `--isolation container` sub-agents. The env is set by the
+                // dispatch command (Part 8 + Part 12) at spawn time.
+                const containerLeaseId = process.env.PEAKS_CONTAINER_LEASE_ID ?? null;
+                const wtDecision = evaluateWorktreeAuth({
+                    projectRoot: options.project,
+                    sessionId,
+                    toolName: toolKind,
+                    command: toolKind === 'Bash' ? command : null,
+                    isolation: toolKind === 'Agent' || toolKind === 'EnterWorktree' ? extractIsolation(parsedStdin) : null,
+                    requestId: null,
+                    leaseId: leaseId !== null && /^[a-f0-9]{16}$/.test(leaseId) ? leaseId : null,
+                    containerLeaseId: containerLeaseId !== null && /^[a-f0-9]{16}$/.test(containerLeaseId) ? containerLeaseId : null
+                });
+                if (!wtDecision.allow) {
+                    // Hard block: a worktree-mutating tool call without a current-task user grant.
+                    // emitBlock writes the Claude Code permissionDecision:"deny" envelope and exits 2.
+                    // The reason includes the remediation hint so the LLM can run `peaks worktree auth grant`
+                    // and retry, and the user can read the deny text in the next-turn stderr.
+                    emitBlock(io, `[worktree-gate:${wtDecision.code}] ${wtDecision.reason} — ${wtDecision.remediation}`);
+                    if (options.json === true) {
+                        emitHint(io, JSON.stringify(ok('gate.enforce', { decision: 'deny', layer: 'worktree-auth', ...wtDecision })));
+                    }
+                    return;
+                }
+                // allow: continue to the SOP gate (the regular enforcement path).
+                // wtDecision may have arrived via lease (viaLease != null); the SOP gate does not
+                // care which path granted, only that the worktree gate said allow.
+            }
             const decision = await enforceBashCommand(options.project, command);
             if (decision.decision === 'deny') {
                 // PRD#2 (2026-06-16-fact-forcing-gate-format): a true SOP gate failure is
@@ -83,14 +171,48 @@ export function registerGateCommands(program, io) {
                 }
             }
             if (options.json === true) {
-                emitHint(io, JSON.stringify(ok('gate.enforce', decision)));
+                // --json mode: emit the canonical envelope on stdout (the
+                // documented contract for downstream tooling). The hook
+                // decision (allow/deny) is still signalled via process.exitCode
+                // + the minimal `{}` on stdout in non-`--json` mode.
+                // Slice 2026-07-30-nightshift: emitHint here was wrong —
+                // emitHint writes to stderr, but the AC5 contract expects
+                // the JSON envelope on stdout. Switch to printResult(asJson=true).
+                printResult(io, ok('gate.enforce', decision), true);
+            }
+            else {
+                // allow: emit minimal JSON on stdout so Claude Code's PreToolUse hook
+                // validator accepts the response (see comment above).
+                emitDecision(io, {});
             }
-            // allow: emit nothing on stdout → normal permission flow.
         }
         catch (error) {
             // Fail-open: a bug in enforcement must not brick Claude Code.
             emitHint(io, `gate enforce: internal error, allowing command (${getErrorMessage(error)})`);
         }
+        // Slice 2026-07-29-windows-console-flash Part 46: actively
+        // exit the process when the gate-enforce handler returns.
+        // The default behavior is to wait for stdin EOF before
+        // exiting, but the hook's stdin pipe may not close promptly
+        // (the parent can keep the handle open even after it has
+        // finished reading the JSON decision), which causes 4
+        // Node.js processes to accumulate in the user's task
+        // manager. An explicit process.exit here forces the gate
+        // process to release all handles and exit immediately.
+        //
+        // Slice 2026-07-30-nightshift: gate the `process.exit` on
+        // being invoked as a real CLI hook (no PEAKS_HOOK_STDIN test
+        // seam, no PEAKS_TEST_SEAM env var). The test harness calls
+        // `runCommand` which invokes the same action handler in
+        // process — calling `process.exit` inside the test would
+        // kill the vitest runner before assertions complete. The
+        // `process.exitCode` set above is sufficient for the test
+        // path: Commander's `parseAsync` resolves the action, then
+        // the harness reads the captured stdout/stderr before the
+        // runner exits normally with the recorded exit code.
+        if (process.env.PEAKS_HOOK_STDIN === undefined && process.env.PEAKS_TEST_SEAM === undefined) {
+            process.exit(process.exitCode || 0);
+        }
     });
     addJsonOption(gate
         .command('bypass')

package/dist/cli/commands/governance-classify-contract-commands.d.ts

@@ -0,0 +1,21 @@
+/**
+ * rid-007 Family 1 merge: contract-commands + classify-classify-commands.
+ *
+ * Pre-merge originals (now deleted):
+ *   - src/cli/commands/contract-commands.ts     (167 lines)
+ *   - src/cli/commands/classify-classify-commands.ts (190 lines)
+ *
+ * Both exported `register*Commands` functions are preserved **verbatim**
+ * (function name, signature, body). The merge is a structural refactor
+ * only — no behavior change. `autoRegisterAllCommands` discovers both
+ * exports from this single file.
+ *
+ * Why one file: the RD slice rid-007 user-confirmed one-family merge
+ * minimum; Family 1 is the cleanest demonstration because both inputs
+ * sit under 200 lines and the merged file lands at ~360 lines — well
+ * below the 400-line AC-9 sanity guard and the 800-line scan gate.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerContractCommands(program: Command, io: ProgramIO): void;
+export declare function registerClassifyCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/governance-classify-contract-commands.js

@@ -0,0 +1,273 @@
+/**
+ * rid-007 Family 1 merge: contract-commands + classify-classify-commands.
+ *
+ * Pre-merge originals (now deleted):
+ *   - src/cli/commands/contract-commands.ts     (167 lines)
+ *   - src/cli/commands/classify-classify-commands.ts (190 lines)
+ *
+ * Both exported `register*Commands` functions are preserved **verbatim**
+ * (function name, signature, body). The merge is a structural refactor
+ * only — no behavior change. `autoRegisterAllCommands` discovers both
+ * exports from this single file.
+ *
+ * Why one file: the RD slice rid-007 user-confirmed one-family merge
+ * minimum; Family 1 is the cleanest demonstration because both inputs
+ * sit under 200 lines and the merged file lands at ~360 lines — well
+ * below the 400-line AC-9 sanity guard and the 800-line scan gate.
+ */
+// ===========================================================================
+// Shared imports (consolidated; both originals pulled names from these
+// same modules — `cli-helpers.ts` re-exports `getErrorMessage` from
+// `peaks-loop-shared/result`, so the single canonical import is
+// functionally identical to either original line.)
+// ===========================================================================
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { writeContract } from '../../services/dispatch/contract-store.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { classifyTask } from '../../services/classify/classify-service.js';
+import { TASK_LEVELS } from '../../services/classify/classify-types.js';
+import { loadPreferences } from '../../services/preferences/preferences-service.js';
+// ===========================================================================
+// Section 1: `peaks contract` CLI commands (was contract-commands.ts).
+// ===========================================================================
+const INPUT_LIMIT_BYTES = 256 * 1024;
+/** Split a comma-separated flag value into a trimmed string array. */
+function splitCsv(value) {
+    if (value === undefined)
+        return [];
+    return value
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function registerContractCommands(program, io) {
+    const contract = program
+        .command('contract')
+        .description('Slice contract store (skill-first / CLI-auxiliary). These commands ' +
+        'are primitives that peaks-code / peaks-rd SKILL.md compose. The LLM-side ' +
+        'runner (the IDE-resident sub-agent that finished a slice) calls ' +
+        '`peaks contract write` to persist the slice\'s public surface; the ' +
+        'orchestrator picks it up on the next dispatch run via listContracts() ' +
+        'and splices it into downstream prompts via formatContractInjection().');
+    // ─────────────────────────────────────────────────────────────────
+    // peaks contract write --project <root> --session-id <sid>
+    //   --slice-id <id> --exports <a,b> --types <x,y> --signatures <s1,s2>
+    //   [--broadcast-to <b1,b2>] [--completed-at <iso>]
+    // ─────────────────────────────────────────────────────────────────
+    addJsonOption(contract
+        .command('write')
+        .description('2.7.0 slice-dag-dispatcher MVP: persist a finished slice\'s public ' +
+        'surface (exports / types / publicSignatures) to disk at ' +
+        '.peaks/_runtime/<sessionId>/dispatch/contracts/<slice-id>.json. ' +
+        'The orchestrator picks it up on the next dispatch run. Idempotent: ' +
+        're-running with the same inputs overwrites in place; the SHA-256 ' +
+        'contractHash is content-derived so a contract write from a different ' +
+        'runner (re-execution) is detected as a content change.')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--session-id <sid>', 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
+        .requiredOption('--slice-id <id>', 'slice id; must be non-empty; used as the contract filename basename')
+        .option('--exports <list>', 'comma-separated public export names (e.g. "validateDag,topologicalLevels")')
+        .option('--types <list>', 'comma-separated public type names (e.g. "SliceDag,SliceNode")')
+        .option('--signatures <list>', 'comma-separated public function/method signatures (e.g. "validateDag(dag: SliceDag): void")')
+        .option('--broadcast-to <list>', 'comma-separated downstream slice ids that should auto-inherit this contract (e.g. "B,C")')
+        .option('--completed-at <iso>', 'ISO 8601 timestamp; defaults to now()')).action((options) => {
+        const asJson = options.json === true;
+        const projectRoot = options.project ?? process.cwd();
+        // Slice 2026-06-26-unknown-sid-fallback-fix: see dispatch-commands.ts.
+        const sid = options.sessionId
+            ?? process.env.PEAKS_SESSION_ID
+            ?? getCurrentSessionId(projectRoot)
+            ?? 'unknown-sid';
+        const sliceId = options.sliceId;
+        if (sliceId === undefined || sliceId.length === 0) {
+            printResult(io, fail('contract.write', 'MISSING_SLICE_ID', '--slice-id is required', { path: null, contract: null }, [
+                'Re-run with --slice-id <id> (must be non-empty; used as the contract filename basename).'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const exports = splitCsv(options.exports);
+        const types = splitCsv(options.types);
+        const signatures = splitCsv(options.signatures);
+        const broadcastTo = splitCsv(options.broadcastTo);
+        // Cap the combined input to protect the file IO from runaway values
+        // (e.g. a 10MB comma-separated --signatures flag).
+        const inputSize = sliceId.length +
+            sid.length +
+            exports.join(',').length +
+            types.join(',').length +
+            signatures.join(',').length +
+            broadcastTo.join(',').length +
+            (options.completedAt?.length ?? 0);
+        if (inputSize > INPUT_LIMIT_BYTES) {
+            printResult(io, fail('contract.write', 'INPUT_TOO_LARGE', `combined input size ${inputSize} bytes exceeds ${INPUT_LIMIT_BYTES} (likely oversized --exports/--types/--signatures lists)`, { path: null, contract: null }, [
+                'Split the slice into smaller surfaces or omit optional fields.'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const input = {
+                sliceId,
+                sessionId: sid,
+                exports,
+                types,
+                publicSignatures: signatures,
+                ...(broadcastTo.length > 0 ? { broadcastTo } : {}),
+                ...(options.completedAt !== undefined ? { completedAt: options.completedAt } : {})
+            };
+            const result = writeContract(projectRoot, sid, input);
+            printResult(io, ok('contract.write', {
+                path: result.path,
+                contractHash: result.contract.contractHash,
+                sliceId: result.contract.sliceId,
+                sessionId: result.contract.sessionId,
+                completedAt: result.contract.completedAt,
+                exportCount: result.contract.exports.length,
+                typeCount: result.contract.types.length,
+                signatureCount: result.contract.publicSignatures.length,
+                broadcastTo: result.contract.broadcastTo ?? []
+            }, [], [
+                `Contract written; orchestrator will pick it up on the next \`peaks sub-agent dispatch --from-dag\` run.`,
+                `Re-running with the same inputs is idempotent (overwrites in place).`
+            ]), asJson);
+        }
+        catch (err) {
+            printResult(io, fail('contract.write', 'WRITE_ERROR', getErrorMessage(err), { path: null, contract: null }, [
+                'See error message; check that --project is a writable directory and --slice-id is a valid filename basename (no path separators).'
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+}
+const CLASSIFY_AUDIT_FILE = 'classify-audit.jsonl';
+function getSignalsFromGitDiff(projectRoot) {
+    // Use git diff --stat to extract file count + line count. Fall back to
+    // zeros if git is unavailable (e.g. fresh repo with no commits).
+    let stdout;
+    try {
+        const { execFileSync } = require('node:child_process');
+        stdout = execFileSync('git', ['diff', '--shortstat', 'HEAD'], {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 32 * 1024 * 1024,
+        }).toString('utf8');
+    }
+    catch {
+        return { filesChanged: 0, linesChanged: 0, touchesDependencies: false, touchesMigrationScripts: false, isPureRefactor: true, keywords: [] };
+    }
+    const lines = stdout.split('\n').filter((l) => l.trim().length > 0);
+    const filesChanged = lines.length;
+    let added = 0;
+    let removed = 0;
+    let touchesDependencies = false;
+    let touchesMigrationScripts = false;
+    for (const line of lines) {
+        const match = /(\d+)\s+insertion.*?(\d+)\s+deletion/.exec(line);
+        if (match) {
+            added += Number(match[1]);
+            removed += Number(match[2]);
+        }
+        if (/(package\.json|pnpm-lock\.yaml|yarn\.lock|requirements\.txt|go\.mod)/.test(line)) {
+            touchesDependencies = true;
+        }
+        if (/(migrate|codemod|backfill|schema)/.test(line)) {
+            touchesMigrationScripts = true;
+        }
+    }
+    // isPureRefactor: heuristic — if added lines / removed lines < 0.1 OR
+    // no new exports were added, treat as refactor. For L2.2 the signal is
+    // binary (true/false). Default: true (no behavior change is the safe
+    // assumption; flip to false when keyword 'add' / 'new' / 'feature' present).
+    const isPureRefactor = true;
+    return {
+        filesChanged,
+        linesChanged: added + removed,
+        touchesDependencies,
+        touchesMigrationScripts,
+        isPureRefactor,
+        keywords: [],
+    };
+}
+function appendAuditEntry(projectRoot, entry) {
+    const auditDir = join(projectRoot, '.peaks/_runtime');
+    if (!existsSync(auditDir)) {
+        try {
+            mkdirSync(auditDir, { recursive: true });
+        }
+        catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    }
+    const auditPath = join(auditDir, CLASSIFY_AUDIT_FILE);
+    let body = '';
+    try {
+        if (existsSync(auditPath)) {
+            body = readFileSync(auditPath, 'utf8');
+        }
+    }
+    catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    body += JSON.stringify(entry) + '\n';
+    try {
+        writeFileSync(auditPath, body);
+    }
+    catch { /* best-effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+}
+function isTaskLevel(value) {
+    return TASK_LEVELS.includes(value);
+}
+export function registerClassifyCommands(program, io) {
+    const classify = program
+        .command('classify')
+        .description('L1a task classification: 5-level heuristic (typo/bug/feature/refactor/migration) + override/upgrade + audit log');
+    addJsonOption(classify
+        .command('run')
+        .description('Classify the current diff (git diff HEAD) into one of 5 task levels')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--override <level>', 'force a level (one of typo|bug|feature|refactor|migration); requires --reason')
+        .option('--reason <text>', 'reason for the override (mandatory when --override is set)')).action(async (options) => {
+        try {
+            const prefs = await loadPreferences(options.project);
+            const signals = getSignalsFromGitDiff(options.project);
+            let override;
+            if (options.override !== undefined) {
+                if (!isTaskLevel(options.override)) {
+                    printResult(io, fail('classify.run', 'INVALID_LEVEL', `level must be one of: ${TASK_LEVELS.join(', ')}`, { provided: options.override }, ['Pass one of typo, bug, feature, refactor, migration']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                if (options.reason === undefined || options.reason.length === 0) {
+                    printResult(io, fail('classify.run', 'REASON_REQUIRED', '--reason is required when --override is set', {}, ['Provide a non-empty reason for the override']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                override = { level: options.override, reason: options.reason };
+            }
+            const result = classifyTask(override !== undefined
+                ? { signals, conservatism: prefs.classifyConservatism, override }
+                : { signals, conservatism: prefs.classifyConservatism }, prefs.classifyRules.feature_threshold_files, prefs.classifyRules.feature_threshold_lines);
+            appendAuditEntry(options.project, result.audit);
+            printResult(io, ok('classify.run', result, [], [
+                `gate set for level "${result.level}": ${result.gateSet.stages.join(', ')}`,
+                `audit log: .peaks/_runtime/${CLASSIFY_AUDIT_FILE}`,
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('classify.run', 'CLASSIFY_RUN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Run peaks classify --help for usage']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // Downgrade is REFUSED per spec §4. Surface this as a hard fail.
+    classify
+        .command('downgrade')
+        .description('REFUSED per spec §4 — peaks-loop never downgrades a classification; ask the user to override explicitly')
+        .requiredOption('--level <level>', 'attempted level')
+        .requiredOption('--reason <text>', 'reason for the attempt (always rejected)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--json', 'print machine-readable JSON envelope')
+        .action(async (options) => {
+        printResult(io, fail('classify.downgrade', 'DOWNGRADE_REFUSED', 'peaks classify downgrade is refused per spec §4. Use --override (with reason) on `classify run` to force a level; the CLI never downgrades a classification unilaterally.', { attemptedLevel: options.level, reason: options.reason }, ['Use `peaks classify run --override <level> --reason "<text>"` instead']), options.json);
+        process.exitCode = 2;
+    });
+}

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

@@ -12,9 +12,10 @@
  * point at a sensitive file outside the runtime tree.
  */
 import { existsSync } from 'node:fs';
-import { fail, getErrorMessage, ok } from '../../shared/result.js';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { appendHeartbeat } from '../../services/dispatch/dispatch-record-writer.js';
+import { appendHeartbeat, setStage, tryAutoReleaseLease } from '../../services/dispatch/dispatch-record-writer.js';
+import { isStageLabel } from '../../services/dispatch/stage-enum.js';
 import { assertSafeDispatchRecordPath } from '../../services/security/safe-settings-path.js';
 import { writeLogEntry } from '../../services/log/logger.js';
 import { HEARTBEAT_STATUSES } from './sub-agent-shared.js';
@@ -26,9 +27,15 @@ export function registerHeartbeatCommand(parent, io) {
         'wait and renders a status line. Sub-agents should call this at ' +
         'least every 30s (configurable via SKILL.md heartbeatIntervalSec).')
         .requiredOption('--record <path>', 'absolute path to a dispatch record JSON')
-        .requiredOption('--status <state>', 'queued | running | finalizing | done | failed | stale')
+        .requiredOption('--status <state>', 'queued | running | finalizing | done | failed | stale | cancelled | no-execution | never-started | unreadable')
         .requiredOption('--progress <pct>', 'integer 0-100')
         .option('--note <text>', 'free-form progress note (≤ 200 chars)')
+        // Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.2) —
+        // optional --stage flag. The label is bounded (see
+        // src/services/dispatch/stage-enum.ts); an unknown value is
+        // rejected with INVALID_STAGE so the watch surface never
+        // accumulates typo'd labels.
+        .option('--stage <label>', 'bounded stage label (intake | planning | gathering | analyzing | writing | testing | reviewing | finalizing)')
         .option('--project <path>', 'trusted project root (defaults to cwd); used for the R-2 path guard so a malicious --record cannot point at another project\'s dispatch record')).action((options) => {
         const asJson = options.json === true;
         if (!options.record || !existsSync(options.record)) {
@@ -69,21 +76,85 @@ export function registerHeartbeatCommand(parent, io) {
             // root's .peaks/_sub_agents/ subdir.
             const trustedRoot = options.project ?? process.cwd();
             assertSafeDispatchRecordPath(options.record, trustedRoot);
+            // Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.2) —
+            // validate the optional --stage against the bounded enum
+            // BEFORE the heartbeat write so the caller gets a specific
+            // INVALID_STAGE error rather than a generic HEARTBEAT_ERROR.
+            let stageLabel = null;
+            if (options.stage !== undefined && options.stage.length > 0) {
+                if (!isStageLabel(options.stage)) {
+                    printResult(io, fail('sub-agent.heartbeat', 'INVALID_STAGE', `--stage must be one of intake | planning | gathering | analyzing | writing | testing | reviewing | finalizing (got ${options.stage})`, { recordPath: options.record, truncated: false }, [
+                        'Use one of the bounded stage labels; free-form text is not accepted.'
+                    ]), asJson);
+                    process.exitCode = 1;
+                    return;
+                }
+                stageLabel = options.stage;
+            }
             const result = appendHeartbeat({
                 recordPath: options.record,
                 status: options.status,
                 progress,
                 ...(options.note !== undefined ? { note: options.note } : {})
             });
+            // S5 — promote the stage if --stage was supplied. setStage
+            // re-validates and is a no-op when stage is null. The
+            // appendHeartbeat call above already wrote the heartbeat;
+            // setStage is a separate file-locked read-modify-write on the
+            // same record.
+            if (stageLabel !== null) {
+                setStage({ recordPath: options.record, stage: stageLabel });
+            }
+            // Slice 2026-07-29-worktree-l2-extended Part 24: the
+            // heartbeat envelope surfaces a `leaseHint` field when the
+            // dispatch owns a lease. The hint is a one-line reminder
+            // for the sub-agent that the lease is the L2 surface it
+            // should clean up before exiting (or, per Part 3.A.2, the
+            // auto-release hook will fire on the next terminal status).
+            // The hint is opt-in via a flag so non-lease dispatches
+            // do not pollute the envelope.
+            const leaseId = result.record.leaseId ?? null;
+            const leaseHint = leaseId !== null
+                ? `You own lease \`${leaseId}\`. Run \`peaks worktree release --lease-id ${leaseId}\` before exit, or report a terminal status (done/failed/cancelled) to let peaks-loop auto-release.`
+                : null;
             printResult(io, ok('sub-agent.heartbeat', {
                 // Slice 2026-06-23-audit-4th #E1: envelopeVersion marker
-                envelopeVersion: '2.1.0',
+                // Part 24: bumped to 2.2.0 to advertise the new `leaseHint`
+                // field; readers from 2.1.0 ignore the unknown field.
+                envelopeVersion: '2.2.0',
                 recordPath: options.record,
                 heartbeatCount: result.record.heartbeats.length,
                 lastBeatAt: result.record.lastBeatAt,
                 status: result.record.status,
-                truncated: result.truncated
+                truncated: result.truncated,
+                leaseHint
             }, [], ['Continue business logic; heartbeat is fire-and-forget.']), asJson);
+            // Slice 2026-07-29-worktree-l2-extended Part 3.A.2: when the
+            // heartbeat reports a TERMINAL status (done / failed / cancelled
+            // / no-execution) AND the dispatch owns a lease, fire the
+            // detached release. This is the common path: most sub-agents
+            // finalize via heartbeat before the share-reducer calls
+            // markCompleted, so the heartbeat path is the more frequent
+            // release trigger in practice. markCompleted's hook (Part 3.A.1)
+            // remains as the safety net for sub-agents that finalize via
+            // share without a terminal heartbeat. The release is detached
+            // + best-effort; a failure here cannot roll back the heartbeat
+            // write (the printResult above already shipped the response).
+            const terminalHeartbeatStatuses = new Set([
+                'done', 'failed', 'cancelled', 'no-execution'
+            ]);
+            if (terminalHeartbeatStatuses.has(options.status) && result.record.leaseId !== null) {
+                try {
+                    tryAutoReleaseLease({
+                        projectRoot: trustedRoot,
+                        sessionId: result.record.sessionId,
+                        leaseId: result.record.leaseId
+                    });
+                }
+                catch { // best-effort
+                    /* swallow */
+                }
+            }
             // Slice 2026-06-23-audit-4th #B1: structured log on success.
             try {
                 writeLogEntry({