peaks-loop 4.0.53 → 4.1.0

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

@@ -1,24 +1,5 @@
-/**
- * `peaks sub-agent heartbeat` — G6: append a heartbeat to a dispatch record.
- *
- * Pulled out of `sub-agent-commands.ts` (slice 2026-06-23-audit-p0-split)
- * to honor the 800-line file cap. The heartbeat is fire-and-forget; the
- * parent Dispatcher polls the record during the batch-sync wait and
- * renders a status line. Sub-agents should call this at least every
- * 30s (configurable via SKILL.md heartbeatIntervalSec).
- *
- * R-2 path guard: `assertSafeDispatchRecordPath` ensures the record
- * lives under `.peaks/_sub_agents/` so a malicious `--record` arg can't
- * point at a sensitive file outside the runtime tree.
- */
-import { existsSync } from 'node:fs';
-import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, printResult } from '../cli-helpers.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';
+import { addJsonOption } from '../cli-helpers.js';
+import { runHeartbeatAction } from './heartbeat-commands-action.js';
 export function registerHeartbeatCommand(parent, io) {
     addJsonOption(parent
         .command('heartbeat')
@@ -36,175 +17,25 @@ export function registerHeartbeatCommand(parent, io) {
         // 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)) {
-            printResult(io, fail('sub-agent.heartbeat', 'INVALID_RECORD_PATH', `record not found: ${options.record ?? '(empty)'}`, { recordPath: options.record ?? null, truncated: false }, [
-                'Pass the absolute path from the `peaks sub-agent dispatch` envelope.'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        if (!HEARTBEAT_STATUSES.includes(options.status)) {
-            printResult(io, fail('sub-agent.heartbeat', 'INVALID_STATUS', `--status must be one of ${HEARTBEAT_STATUSES.join(' | ')} (got ${options.status})`, { recordPath: options.record, truncated: false }, [
-                'Use one of the documented statuses; poller compares lastBeatAt against now() - 5min to set `stale`.'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        const progress = Number.parseInt(options.progress ?? 'NaN', 10);
-        if (!Number.isInteger(progress) || progress < 0 || progress > 100) {
-            printResult(io, fail('sub-agent.heartbeat', 'INVALID_PROGRESS', `--progress must be integer 0-100 (got ${options.progress})`, { recordPath: options.record, truncated: false }, [
-                'Use 0..100 inclusive.'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        if (options.note !== undefined && options.note.length > 200) {
-            printResult(io, fail('sub-agent.heartbeat', 'NOTE_TOO_LONG', `--note must be ≤ 200 chars (got ${options.note.length})`, { recordPath: options.record, truncated: false }, [
-                'Shorten the note; the record file is not a log file.'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            // R-2 guard (slice 2026-06-23-audit-3rd): trust --project or process.cwd(),
-            // NOT the --record path. deriveProjectRoot(recordPath) walked the path
-            // itself, which let an attacker point --record at any other project's
-            // .peaks/_sub_agents/ tree and slip past the guard. The relative()
-            // backstop still applies — the record must live under the trusted
-            // 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
-                // 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,
-                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({
-                    ts: new Date().toISOString(),
-                    level: 'info',
-                    command: 'sub-agent.heartbeat',
-                    msg: 'heartbeat',
-                    batchId: result.record.batchId,
-                    data: {
-                        recordPath: options.record,
-                        status: result.record.status,
-                        heartbeatCount: result.record.heartbeats.length,
-                        truncated: result.truncated
-                    }
-                });
-            }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                /* best-effort */
-            }
-        }
-        catch (error) {
-            const code = error.code ?? 'HEARTBEAT_ERROR';
-            printResult(io, fail('sub-agent.heartbeat', code, getErrorMessage(error), { recordPath: options.record ?? null, truncated: false }, [
-                heartbeatErrorNextActions(code)
-            ]), asJson);
-            process.exitCode = 1;
-        }
+        .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) => {
+        runHeartbeatAction(io, options);
     });
 }
 /**
- * Slice 2026-06-23-audit-3rd #9: branch nextActions on `error.code` so
- * the LLM-side runner gets a specific hint instead of the generic
- * "see error message" fallback.
+ * The `running` projection both arms of `heartbeat` return. The two arms were
+ * already literal-for-literal identical in the source (a dispatched node and a
+ * running node both project to `status: 'running'`); the branch is kept because
+ * merging it is a behaviour decision, not a lint one — this extraction only
+ * moves the shared object literal so the function fits `complexity`.
  */
-function heartbeatErrorNextActions(code) {
-    if (code === 'LOCK_TIMEOUT') {
-        return 'A concurrent writer (markCompleted or another heartbeat) holds the record lock for >5s; retry, or check for a crashed holder (the .lock file is reaped after 30s).';
-    }
-    if (code === 'RECORD_NOT_FOUND') {
-        return 'The dispatch record does not exist on disk. Re-run `peaks sub-agent dispatch <role>` to materialize a fresh record path; the previous batch may have been garbage-collected.';
-    }
-    if (code === 'INVALID_RECORD_JSON') {
-        return 'The record file is corrupted (truncated mid-write or hand-edited). Delete it and re-run `peaks sub-agent dispatch`; the parent Dispatcher will treat this as a fresh dispatch.';
-    }
-    if (code === 'INVALID_PROGRESS' || code === 'NOTE_TOO_LONG') {
-        return 'Pass --progress as integer 0..100 and --note as ≤ 200 chars. Both are validated by the CLI before reaching the writer.';
-    }
-    return 'See error message; if the record file is missing or corrupted, the parent Dispatcher will mark the sub-agent as stale after 5 minutes.';
+function runningHeartbeatProjection(input) {
+    return {
+        status: 'running',
+        lastHeartbeat: input.lastHeartbeat ?? input.now ?? new Date().toISOString(),
+        graphNodeId: input.graphNodeId ?? null,
+        dispatchRef: input.dispatchRef ?? null
+    };
 }
-/* ---------- Slice 4.0.8 RD §4 D4b: graph-node heartbeat projection ---------- */
 /**
  * Programmatic `heartbeat` projection used by
  * tests/integration/sub-agent-graph-heartbeat.test.ts.
@@ -212,19 +43,9 @@ function heartbeatErrorNextActions(code) {
 export function heartbeat(input) {
     const status = (input.status ?? 'dispatched');
     if (status === 'dispatched') {
-        return {
-            status: 'running',
-            lastHeartbeat: input.lastHeartbeat ?? input.now ?? new Date().toISOString(),
-            graphNodeId: input.graphNodeId ?? null,
-            dispatchRef: input.dispatchRef ?? null,
-        };
+        return runningHeartbeatProjection(input);
     }
-    return {
-        status: 'running',
-        lastHeartbeat: input.lastHeartbeat ?? input.now ?? new Date().toISOString(),
-        graphNodeId: input.graphNodeId ?? null,
-        dispatchRef: input.dispatchRef ?? null,
-    };
+    return runningHeartbeatProjection(input);
 }
 /**
  * Programmatic `markLost` projection. Mirrors the CLI failure
@@ -241,6 +62,6 @@ export function markLost(input) {
         status: 'lost',
         terminalReason: reason,
         graphNodeId: input.graphNodeId ?? null,
-        dispatchRef: input.dispatchRef ?? null,
+        dispatchRef: input.dispatchRef ?? null
     };
 }

package/dist/cli/commands/hook-handle.d.ts

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 /**
  * `peaks hook handle` —— peaks 自有 hook 协议的单一入口。

package/dist/cli/commands/hook-handle.js

@@ -23,7 +23,9 @@ async function readStdin() {
     return new Promise((resolveStdin) => {
         let data = '';
         process.stdin.setEncoding('utf8');
-        process.stdin.on('data', (chunk) => { data += chunk; });
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
         process.stdin.on('end', () => resolveStdin(data));
         process.stdin.on('error', () => resolveStdin(data));
     });
@@ -43,7 +45,9 @@ async function readStdin() {
  * peaks hook handle 即可。Slice #3 删除旧命令。
  */
 export function registerHookHandleCommand(program, io) {
-    const hook = program.command('hook').description('Peaks 自有 hook 协议单一入口（slice #1 新增；后续 slice 将逐步替代 gate enforce）');
+    const hook = program
+        .command('hook')
+        .description('Peaks 自有 hook 协议单一入口（slice #1 新增；后续 slice 将逐步替代 gate enforce）');
     addJsonOption(hook
         .command('handle')
         .description('Read stdin hook payload, auto-detect IDE, dispatch to peaks gate-enforce logic, output IDE-formatted decision')
@@ -60,7 +64,11 @@ export function registerHookHandleCommand(program, io) {
                     parsed = null;
                 }
             }
-            const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin: parsed });
+            const ide = detectIdeFromContext({
+                env: process.env,
+                cwd: process.cwd(),
+                parsedStdin: parsed
+            });
             const adapter = getAdapter(ide);
             // Slice #3: per-adapter stdin parser dispatch. The detected IDE
             // determines which parser runs; unknown IDEs fall back to the Claude
@@ -81,7 +89,9 @@ export function registerHookHandleCommand(program, io) {
             });
             // Dispatch by toolName. For slice #1+, we only handle Bash. Task tool sub-agent dispatch goes through `peaks sub-agent dispatch` (slice #009) and does not need a hook entry.
             // Other tools: allow (no-op; future events will be added here).
-            if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string' && fallbackCommand.trim().length > 0) {
+            if (hook.toolName === 'Bash' &&
+                typeof fallbackCommand === 'string' &&
+                fallbackCommand.trim().length > 0) {
                 // L2.1 P0 #1: code-commit-ban. Deny `git commit` / `git apply` from peaks-* skills
                 // BEFORE the SOP gate runs. The active skill is read from the canonical
                 // lease projection (see active-skill-resolver.ts, slice 4.0.8).
@@ -90,12 +100,21 @@ export function registerHookHandleCommand(program, io) {
                 // `canonical` for the lease + index path.
                 const activeSkill = resolveActiveSkillForCaller(projectRoot);
                 if (activeSkill.skill !== null) {
-                    const codeDecision = evaluateCodeBan({ skill: activeSkill.skill, command: fallbackCommand });
+                    const codeDecision = evaluateCodeBan({
+                        skill: activeSkill.skill,
+                        command: fallbackCommand
+                    });
                     if (codeDecision.denied) {
                         const formatted = formatDecisionResponse(ide, 'deny', codeDecision.reason);
                         emitDecision(io, formatted.stdout);
                         if (options.json === true) {
-                            emitHint(io, JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: codeDecision.reason, enforcer: 'code-ban' })));
+                            emitHint(io, JSON.stringify(ok('hook.handle', {
+                                ide,
+                                tool: hook.toolName,
+                                decision: 'deny',
+                                reason: codeDecision.reason,
+                                enforcer: 'code-ban'
+                            })));
                         }
                         return;
                     }
@@ -107,7 +126,12 @@ export function registerHookHandleCommand(program, io) {
                     const formatted = formatDecisionResponse(ide, 'deny', decision.reason);
                     emitDecision(io, formatted.stdout);
                     if (options.json === true) {
-                        emitHint(io, JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: decision.reason })));
+                        emitHint(io, JSON.stringify(ok('hook.handle', {
+                            ide,
+                            tool: hook.toolName,
+                            decision: 'deny',
+                            reason: decision.reason
+                        })));
                     }
                     return;
                 }
@@ -126,18 +150,27 @@ export function registerHookHandleCommand(program, io) {
             // root allowlist. file_path is read from toolInput.file_path (Claude
             // and most IDEs use the same shape). When the field is missing or the
             // path is not at depth 1, the enforcer allows (no-op).
-            if (hook.toolName === 'Write' || hook.toolName === 'Edit' || hook.toolName === 'MultiEdit' || hook.toolName === 'Create') {
-                const filePath = pluckString(parsed, ['tool_input', 'file_path'])
-                    ?? pluckString(parsed, ['toolInput', 'file_path'])
-                    ?? pluckString(parsed, ['tool_input', 'path'])
-                    ?? pluckString(parsed, ['toolInput', 'path']);
+            if (hook.toolName === 'Write' ||
+                hook.toolName === 'Edit' ||
+                hook.toolName === 'MultiEdit' ||
+                hook.toolName === 'Create') {
+                const filePath = pluckString(parsed, ['tool_input', 'file_path']) ??
+                    pluckString(parsed, ['toolInput', 'file_path']) ??
+                    pluckString(parsed, ['tool_input', 'path']) ??
+                    pluckString(parsed, ['toolInput', 'path']);
                 if (typeof filePath === 'string' && filePath.trim().length > 0) {
                     const rootCheck = isRootWrite({ projectRoot, filePath });
                     if (!rootCheck.allowed) {
                         const formatted = formatDecisionResponse(ide, 'deny', rootCheck.denyReason);
                         emitDecision(io, formatted.stdout);
                         if (options.json === true) {
-                            emitHint(io, JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: rootCheck.denyReason, enforcer: 'no-root-pollution' })));
+                            emitHint(io, JSON.stringify(ok('hook.handle', {
+                                ide,
+                                tool: hook.toolName,
+                                decision: 'deny',
+                                reason: rootCheck.denyReason,
+                                enforcer: 'no-root-pollution'
+                            })));
                         }
                         return;
                     }

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

@@ -1,3 +1,3 @@
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerHooksCommands(program: Command, io: ProgramIO): void;

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

@@ -23,7 +23,9 @@ function resolveScope(options) {
     return options.global ? 'global' : 'project';
 }
 function resolveProjectRoot(scope, project) {
-    return scope === 'project' ? (project ?? findProjectRoot(process.cwd()) ?? process.cwd()) : undefined;
+    return scope === 'project'
+        ? (project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+        : undefined;
 }
 /**
  * Resolve the IDE the install should target. The CLI user can override with
@@ -36,7 +38,11 @@ function resolveIdeForCommand(options, projectRoot) {
     if (options.ide !== undefined && options.ide.length > 0) {
         return options.ide;
     }
-    return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
+    return detectIdeFromContext({
+        env: process.env,
+        cwd: projectRoot ?? process.cwd(),
+        parsedStdin: null
+    });
 }
 /**
  * Slice #014: compute the per-IDE peaks hook entries for the install /
@@ -133,7 +139,9 @@ function describeHookCopy(label, copy, scope, dryRun) {
     if (scope !== 'global')
         return null;
     if (copy.copied) {
-        return dryRun ? `would copy ${label} from ${copy.source} to ${copy.target}` : `Copied ${label}: ${copy.target}`;
+        return dryRun
+            ? `would copy ${label} from ${copy.source} to ${copy.target}`
+            : `Copied ${label}: ${copy.target}`;
     }
     return `${label} NOT copied — source missing at ${copy.source}. Run the build (\`pnpm build\`) so the script ships with the package.`;
 }
@@ -296,7 +304,7 @@ export function registerHooksCommands(program, io) {
     });
     addJsonOption(hooks
         .command('uninstall')
-        .description("Remove the peaks-managed gate-enforce hook entry from the target settings.json. Any legacy progress-start entry that a pre-#014 install left behind is also removed (sentinel-based scan). Third-party hooks are preserved.")
+        .description('Remove the peaks-managed gate-enforce hook entry from the target settings.json. Any legacy progress-start entry that a pre-#014 install left behind is also removed (sentinel-based scan). Third-party hooks are preserved.')
         .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
         .option('--ide <id>', resolveIdeOptionHelp())).action((options) => {
@@ -318,7 +326,9 @@ export function registerHooksCommands(program, io) {
         }
         catch (error) {
             const message = getErrorMessage(error);
-            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [message]), options.json);
+            printResult(io, fail('hooks.uninstall', 'HOOKS_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [
+                message
+            ]), options.json);
             process.exitCode = 1;
         }
     });
@@ -364,7 +374,9 @@ export function registerHooksCommands(program, io) {
             // installed yet".
             const warnings = status.supportsHooks
                 ? []
-                : [`IDE '${ide}' cannot host peaks hooks (no HOOK_COMMAND_BY_IDE entry); nothing can be installed for it, which is why none is.`];
+                : [
+                    `IDE '${ide}' cannot host peaks hooks (no HOOK_COMMAND_BY_IDE entry); nothing can be installed for it, which is why none is.`
+                ];
             printResult(io, ok('hooks.status', {
                 ...status,
                 ide,

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

@@ -20,6 +20,6 @@
  * registered adapter. This file does NOT import any specific
  * adapter.
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerIdeCommands(program: Command, io: ProgramIO): void;

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

@@ -3,7 +3,9 @@ import { addJsonOption, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { listAdapterIds } from '../../services/ide/ide-registry.js';
 export function registerIdeCommands(program, io) {
-    const ide = program.command('ide').description('Read-only introspection helpers for the registered IDE adapter layer (slice 2026-07-09 add-zcode-adapter, Slice C)');
+    const ide = program
+        .command('ide')
+        .description('Read-only introspection helpers for the registered IDE adapter layer (slice 2026-07-09 add-zcode-adapter, Slice C)');
     addJsonOption(ide
         .command('model')
         .description('Inspect the IDE adapter model surface. Slice C supports `--current` only.')
@@ -26,14 +28,14 @@ async function runIdeModelCurrent(io, options) {
             printResult(io, ok('ide.model.current', {
                 modelId: null,
                 detected: false,
-                registeredAdapters: listAdapterIds(),
+                registeredAdapters: listAdapterIds()
             }), options.json);
             return;
         }
         printResult(io, ok('ide.model.current', {
             modelId,
             detected: true,
-            registeredAdapters: listAdapterIds(),
+            registeredAdapters: listAdapterIds()
         }), options.json);
     }
     catch (error) {

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

@@ -26,7 +26,10 @@ export function registerImpactCommands(program, io) {
         .requiredOption('--files <list>', 'comma-separated list of changed file paths (relative to project root)')
         .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
         const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const files = opts.files.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        const files = opts.files
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
         if (files.length === 0) {
             printResult(io, fail('impact.scan', 'INVALID_INPUT', 'no files provided (--files)', { projectRoot }, [
                 'Pass --files with at least one file path.'
@@ -44,7 +47,10 @@ export function registerImpactCommands(program, io) {
         .requiredOption('--files <list>', 'comma-separated list of changed file paths')
         .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
         const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const files = opts.files.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        const files = opts.files
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0);
         if (files.length === 0) {
             printResult(io, fail('impact.must-check', 'INVALID_INPUT', 'no files provided (--files)', { projectRoot }, [
                 'Pass --files with at least one file path.'

package/dist/cli/commands/job-add-slice-command.d.ts

@@ -0,0 +1,43 @@
+/**
+ * rid 2026-10-03-job-ledger-truthfulness (D1) — `peaks job add-slice`.
+ *
+ * THE DEFECT. A job's slice list was decided once, at
+ * `peaks job init --slice-list <one id>`, and no subcommand could add to it. The
+ * subcommand set was `init / status / rotate-now / subagent-cleanup / checkpoint /
+ * block / continue / resume / progress / handoff / karpathy-cost-check`. Measured
+ * against the committed build on 2026-10-03:
+ *
+ *   peaks job add-slice …                          → error: unknown command 'add-slice'
+ *   peaks job checkpoint --slice-id <new slice>    → ok:false  code:SLICE_NOT_FOUND
+ *   peaks job progress --job-id 2026-10-02-c-wave9 → { done: 1, total: 1 }  (stuck)
+ *
+ * so a wave that plans its next slice only after the previous one lands — which is
+ * how every split wave here runs — had no truthful way to record what it did. It
+ * either under-reported or opened a new job per slice, and the ledger then recorded
+ * the tooling's limitation instead of the work.
+ *
+ * WHY THIS IS ITS OWN FILE. `src/cli/commands/job-commands.ts` sits over the
+ * 300-line cap the gate already ratchets (828 raw lines, and the repository's
+ * `fileSizeExcessLines` row is held at its ceiling in both directions), so this
+ * slice could not add a subcommand there without moving a gate number — the frozen
+ * work. The command mounts onto the existing `job` parent from here, the way
+ * `api-diff-commands.ts` mounts `peaks scan api-diff`, and reuses the parent
+ * file's session/state resolution rather than re-implementing it. NOTHING about
+ * the `job` command's stored shape changed: same state file, same `slice-NNN` ids,
+ * same `progress.json` mirror, same envelope, no new ledger field.
+ *
+ * WHAT IT PROMISES, and each half is load-bearing:
+ * - **idempotent** — a label already registered on this job is reported as the
+ *   slice it already is (`added: false`) and `state.json` is not written.
+ *   Re-running the command cannot grow the job.
+ * - **honest** — an empty or whitespace-only label is refused
+ *   (`INVALID_SLICE_LABEL`) rather than appended; the mirror is rewritten only when
+ *   a slice was actually added, and only if a mirror already exists (a command that
+ *   knows nothing about progress does not invent one).
+ * - **followed by the rest of the ledger** — every `total` is `slices.length`, so
+ *   `status`, `progress`, `continue` and the mirror move together, and `checkpoint`
+ *   takes the new slice by name through the existing D7 label resolution.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerJobAddSliceCommand(program: Command, io: ProgramIO): void;