peaks-loop 4.0.53 → 4.1.0

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

@@ -49,7 +49,7 @@ export function registerContractCommands(program, io) {
         .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 ' +
+        "`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().');
     // ─────────────────────────────────────────────────────────────────
@@ -59,7 +59,7 @@ export function registerContractCommands(program, io) {
     // ─────────────────────────────────────────────────────────────────
     addJsonOption(contract
         .command('write')
-        .description('2.7.0 slice-dag-dispatcher MVP: persist a finished slice\'s public ' +
+        .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: ' +
@@ -77,10 +77,10 @@ export function registerContractCommands(program, io) {
         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 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 }, [
@@ -103,9 +103,7 @@ export function registerContractCommands(program, io) {
             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);
+            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;
         }
@@ -154,11 +152,18 @@ function getSignalsFromGitDiff(projectRoot) {
             cwd: projectRoot,
             stdio: ['ignore', 'pipe', 'ignore'],
             maxBuffer: 32 * 1024 * 1024,
-            windowsHide: true,
+            windowsHide: true
         }).toString('utf8');
     }
     catch {
-        return { filesChanged: 0, linesChanged: 0, touchesDependencies: false, touchesMigrationScripts: false, isPureRefactor: true, keywords: [] };
+        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;
@@ -190,7 +195,7 @@ function getSignalsFromGitDiff(projectRoot) {
         touchesDependencies,
         touchesMigrationScripts,
         isPureRefactor,
-        keywords: [],
+        keywords: []
     };
 }
 function appendAuditEntry(projectRoot, entry) {
@@ -199,7 +204,9 @@ function appendAuditEntry(projectRoot, entry) {
         try {
             mkdirSync(auditDir, { recursive: true });
         }
-        catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        catch {
+            /* ignore */
+        } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
     }
     const auditPath = join(auditDir, CLASSIFY_AUDIT_FILE);
     let body = '';
@@ -208,12 +215,16 @@ function appendAuditEntry(projectRoot, entry) {
             body = readFileSync(auditPath, 'utf8');
         }
     }
-    catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    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)
+    catch {
+        /* best-effort */
+    } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
 }
 function isTaskLevel(value) {
     return TASK_LEVELS.includes(value);
@@ -251,7 +262,7 @@ export function registerClassifyCommands(program, io) {
             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}`,
+                `audit log: .peaks/_runtime/${CLASSIFY_AUDIT_FILE}`
             ]), options.json);
         }
         catch (error) {
@@ -267,7 +278,7 @@ export function registerClassifyCommands(program, io) {
         .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) => {
+        .action((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-action.d.ts

@@ -0,0 +1,7 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type HeartbeatActionOptions } from './heartbeat-commands-validation.js';
+/**
+ * `peaks sub-agent heartbeat --record <path> --status <state> --progress <pct>`
+ * — the body the commander action calls, in the order it ran before the split.
+ */
+export declare function runHeartbeatAction(io: ProgramIO, options: HeartbeatActionOptions): void;

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

@@ -0,0 +1,192 @@
+/**
+ * The action half of `peaks sub-agent heartbeat` (G6) — the write path.
+ *
+ * Extracted VERBATIM from `heartbeat-commands.ts` (job strict-remediation-abc,
+ * slice c1-eslint-family-sweep, leaf c1w1-heartbeat-commands) so the
+ * registration file clears the 300-line cap and the `max-lines-per-function` /
+ * `complexity` findings that sat on the commander action arrow fell with it.
+ * The rejects live in `heartbeat-commands-validation.ts`.
+ *
+ * NOTHING was restructured. Same predicate order (record existence → status →
+ * progress → note → R-2 path guard → stage), same `process.exitCode = 1` at
+ * every reject, same two writes (`appendHeartbeat` then `setStage`), same
+ * response-before-release order, same catch clauses. The stage check still runs
+ * AFTER `assertSafeDispatchRecordPath` because that order is observable: an
+ * unsafe `--record` must fail before a typo'd label.
+ *
+ * On swallows: the frame that discards a failed detached lease release moved
+ * with the code it wraps — it was one, it is still one, and it was not rewritten
+ * somewhere else. No `return null` and no empty catch was introduced here to
+ * keep a function under a ceiling, and no catch in this module answers for the
+ * absence of data.
+ */
+import { existsSync } from 'node:fs';
+import { getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { appendHeartbeat, setStage, tryAutoReleaseLease } from '../../services/dispatch/dispatch-record-writer.js';
+import { assertSafeDispatchRecordPath } from '../../services/security/safe-settings-path.js';
+import { writeLogEntry } from '../../services/log/logger.js';
+import { failHeartbeat, heartbeatErrorCode, heartbeatErrorNextActions, resolveHeartbeatStage, validateHeartbeatArguments } from './heartbeat-commands-validation.js';
+// Slice 2026-07-29-worktree-l2-extended Part 3.A.2: the statuses that end a
+// dispatch. Hoisted out of the action body — a constant set is the same set on
+// every call, and its position in the sequence (after printResult) is unchanged.
+const TERMINAL_HEARTBEAT_STATUSES = new Set([
+    'done',
+    'failed',
+    'cancelled',
+    'no-execution'
+]);
+/**
+ * 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.
+ */
+function leaseHintFor(result) {
+    const leaseId = result.record.leaseId ?? null;
+    return 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;
+}
+/** The success envelope's payload, field for field, exactly as the CLI printed it. */
+function heartbeatSuccessEnvelope(recordPath, result) {
+    return {
+        // 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,
+        heartbeatCount: result.record.heartbeats.length,
+        lastBeatAt: result.record.lastBeatAt,
+        status: result.record.status,
+        truncated: result.truncated,
+        leaseHint: leaseHintFor(result)
+    };
+}
+/**
+ * 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 response has already shipped).
+ */
+function releaseLeaseForTerminalHeartbeat(trustedRoot, status, result) {
+    if (TERMINAL_HEARTBEAT_STATUSES.has(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. */
+function logHeartbeatSuccess(recordPath, result) {
+    try {
+        writeLogEntry({
+            ts: new Date().toISOString(),
+            level: 'info',
+            command: 'sub-agent.heartbeat',
+            msg: 'heartbeat',
+            batchId: result.record.batchId,
+            data: {
+                recordPath,
+                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 */
+    }
+}
+/**
+ * The write path, reached only after the R-2 guard and the stage check: append
+ * the heartbeat, promote the stage when one was supplied, print the response,
+ * then (and only then) the lease hook and the structured log.
+ */
+function writeAndReportHeartbeat(io, ctx) {
+    const result = appendHeartbeat({
+        recordPath: ctx.recordPath,
+        status: ctx.options.status,
+        progress: ctx.progress,
+        ...(ctx.options.note !== undefined ? { note: ctx.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 (ctx.stage !== null) {
+        setStage({ recordPath: ctx.recordPath, stage: ctx.stage });
+    }
+    printResult(io, ok('sub-agent.heartbeat', heartbeatSuccessEnvelope(ctx.recordPath, result), [], ['Continue business logic; heartbeat is fire-and-forget.']), ctx.asJson);
+    releaseLeaseForTerminalHeartbeat(ctx.trustedRoot, ctx.options.status, result);
+    logHeartbeatSuccess(ctx.recordPath, result);
+}
+/**
+ * `peaks sub-agent heartbeat --record <path> --status <state> --progress <pct>`
+ * — the body the commander action calls, in the order it ran before the split.
+ */
+export function runHeartbeatAction(io, options) {
+    const asJson = options.json === true;
+    if (!options.record || !existsSync(options.record)) {
+        failHeartbeat(io, {
+            asJson,
+            code: 'INVALID_RECORD_PATH',
+            message: `record not found: ${options.record ?? '(empty)'}`,
+            recordPath: options.record ?? null,
+            nextAction: 'Pass the absolute path from the `peaks sub-agent dispatch` envelope.'
+        });
+        return;
+    }
+    const recordPath = options.record;
+    const args = validateHeartbeatArguments(io, asJson, options, recordPath);
+    if (!args.ok) {
+        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(recordPath, trustedRoot);
+        const stage = resolveHeartbeatStage(io, asJson, options, recordPath);
+        if (!stage.ok) {
+            return;
+        }
+        writeAndReportHeartbeat(io, {
+            asJson,
+            options,
+            recordPath,
+            progress: args.progress,
+            trustedRoot,
+            stage: stage.stage
+        });
+    }
+    catch (error) {
+        const code = heartbeatErrorCode(error);
+        failHeartbeat(io, {
+            asJson,
+            code,
+            message: getErrorMessage(error),
+            recordPath: options.record ?? null,
+            nextAction: heartbeatErrorNextActions(code)
+        });
+    }
+}

package/dist/cli/commands/heartbeat-commands-validation.d.ts

@@ -0,0 +1,57 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type StageLabel } from '../../services/dispatch/stage-enum.js';
+import { type HeartbeatOptions } from './sub-agent-shared.js';
+/** `heartbeat` as commander hands it to the action (`--stage` is still a raw string). */
+export type HeartbeatActionOptions = HeartbeatOptions & {
+    stage?: string;
+};
+/** The progress the argument checks parsed, or nothing: the reject already printed. */
+export type HeartbeatArgumentsCheck = {
+    ok: true;
+    progress: number;
+} | {
+    ok: false;
+};
+/** The validated `--stage` (null when the flag was absent or empty), or nothing. */
+export type HeartbeatStageCheck = {
+    ok: true;
+    stage: StageLabel | null;
+} | {
+    ok: false;
+};
+/**
+ * One failure envelope, printed the same way at every reject site: print, mark
+ * the process failed, and let the caller `return`. All six sites already did
+ * exactly this, so hoisting them cannot make two of them disagree.
+ */
+export declare function failHeartbeat(io: ProgramIO, f: {
+    asJson: boolean;
+    code: string;
+    message: string;
+    recordPath: string | null;
+    nextAction: string;
+}): void;
+/**
+ * The three argument checks that follow the record-existence guard, in the
+ * order the command ran them. A reject prints and sets the exit code here; the
+ * caller only returns.
+ */
+export declare function validateHeartbeatArguments(io: ProgramIO, asJson: boolean, options: HeartbeatActionOptions, recordPath: string): HeartbeatArgumentsCheck;
+/**
+ * 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`. An absent or empty flag is not an error: it yields
+ * `stage: null`, and `setStage` stays uncalled. The caller still runs this
+ * AFTER `assertSafeDispatchRecordPath`, because which of the two fails first is
+ * observable.
+ */
+export declare function resolveHeartbeatStage(io: ProgramIO, asJson: boolean, options: HeartbeatActionOptions, recordPath: string): HeartbeatStageCheck;
+/**
+ * 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.
+ */
+export declare function heartbeatErrorNextActions(code: string): string;
+/** The writer's error code, or the catch-all the CLI has always answered with. */
+export declare function heartbeatErrorCode(error: unknown): string;

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

@@ -0,0 +1,120 @@
+/**
+ * Argument checks and failure envelopes for `peaks sub-agent heartbeat`.
+ *
+ * Extracted VERBATIM from `heartbeat-commands.ts` (job strict-remediation-abc,
+ * slice c1-eslint-family-sweep, leaf c1w1-heartbeat-commands) so the
+ * registration file clears the 300-line cap and the `max-lines-per-function` /
+ * `complexity` findings that sat on the commander action arrow fell with it.
+ * This module holds the checks that REJECT; the write path is
+ * `heartbeat-commands-action.ts`.
+ *
+ * Nothing was restructured: the predicates, their order (status → progress →
+ * note, after the record-existence guard and before the R-2 path guard), the
+ * message, hint and exit code of every reject, and the rule that a typo'd
+ * `--stage` is only reported once the record path has already been accepted as
+ * safe are the code that was already there. No check here swallows anything and
+ * none answers for the absence of data.
+ */
+import { fail } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { NOTE_MAX_CHARS } from '../../services/dispatch/dispatch-record-types.js';
+import { isStageLabel } from '../../services/dispatch/stage-enum.js';
+import { HEARTBEAT_STATUSES } from './sub-agent-shared.js';
+/**
+ * One failure envelope, printed the same way at every reject site: print, mark
+ * the process failed, and let the caller `return`. All six sites already did
+ * exactly this, so hoisting them cannot make two of them disagree.
+ */
+export function failHeartbeat(io, f) {
+    printResult(io, fail('sub-agent.heartbeat', f.code, f.message, { recordPath: f.recordPath, truncated: false }, [f.nextAction]), f.asJson);
+    process.exitCode = 1;
+}
+/**
+ * The three argument checks that follow the record-existence guard, in the
+ * order the command ran them. A reject prints and sets the exit code here; the
+ * caller only returns.
+ */
+export function validateHeartbeatArguments(io, asJson, options, recordPath) {
+    if (!HEARTBEAT_STATUSES.includes(options.status)) {
+        failHeartbeat(io, {
+            asJson,
+            code: 'INVALID_STATUS',
+            message: `--status must be one of ${HEARTBEAT_STATUSES.join(' | ')} (got ${options.status})`,
+            recordPath,
+            nextAction: 'Use one of the documented statuses; poller compares lastBeatAt against now() - 5min to set `stale`.'
+        });
+        return { ok: false };
+    }
+    const progress = Number.parseInt(options.progress ?? 'NaN', 10);
+    if (!Number.isInteger(progress) || progress < 0 || progress > 100) {
+        failHeartbeat(io, {
+            asJson,
+            code: 'INVALID_PROGRESS',
+            message: `--progress must be integer 0-100 (got ${options.progress})`,
+            recordPath,
+            nextAction: 'Use 0..100 inclusive.'
+        });
+        return { ok: false };
+    }
+    if (options.note !== undefined && options.note.length > NOTE_MAX_CHARS) {
+        failHeartbeat(io, {
+            asJson,
+            code: 'NOTE_TOO_LONG',
+            message: `--note must be ≤ 200 chars (got ${options.note.length})`,
+            recordPath,
+            nextAction: 'Shorten the note; the record file is not a log file.'
+        });
+        return { ok: false };
+    }
+    return { ok: true, progress };
+}
+/**
+ * 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`. An absent or empty flag is not an error: it yields
+ * `stage: null`, and `setStage` stays uncalled. The caller still runs this
+ * AFTER `assertSafeDispatchRecordPath`, because which of the two fails first is
+ * observable.
+ */
+export function resolveHeartbeatStage(io, asJson, options, recordPath) {
+    let stageLabel = null;
+    if (options.stage !== undefined && options.stage.length > 0) {
+        if (!isStageLabel(options.stage)) {
+            failHeartbeat(io, {
+                asJson,
+                code: 'INVALID_STAGE',
+                message: `--stage must be one of intake | planning | gathering | analyzing | writing | testing | reviewing | finalizing (got ${options.stage})`,
+                recordPath,
+                nextAction: 'Use one of the bounded stage labels; free-form text is not accepted.'
+            });
+            return { ok: false };
+        }
+        stageLabel = options.stage;
+    }
+    return { ok: true, stage: stageLabel };
+}
+/**
+ * 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.
+ */
+export 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.';
+}
+/** The writer's error code, or the catch-all the CLI has always answered with. */
+export function heartbeatErrorCode(error) {
+    return error.code ?? 'HEARTBEAT_ERROR';
+}

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

@@ -1,17 +1,37 @@
+/**
+ * `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.
+ *
+ * Slice c1-eslint-family-sweep / leaf c1w1-heartbeat-commands: the action the
+ * `.action()` below wires lives in `heartbeat-commands-action.ts` (write path)
+ * and `heartbeat-commands-validation.ts` (argument checks and reject envelopes)
+ * — the option surface and the graph-node projections stayed here.
+ */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerHeartbeatCommand(parent: Command, io: ProgramIO): void;
-/**
- * Programmatic `heartbeat` projection used by
- * tests/integration/sub-agent-graph-heartbeat.test.ts.
- */
-export declare function heartbeat(input: {
+/** The graph-node input both projections below read. */
+type GraphNodeHeartbeatInput = {
     dispatchRef?: string;
     graphNodeId?: string;
     status?: string;
     now?: string;
     lastHeartbeat?: string;
-}): Record<string, unknown>;
+};
+/**
+ * Programmatic `heartbeat` projection used by
+ * tests/integration/sub-agent-graph-heartbeat.test.ts.
+ */
+export declare function heartbeat(input: GraphNodeHeartbeatInput): Record<string, unknown>;
 /**
  * Programmatic `markLost` projection. Mirrors the CLI failure
  * contract for consumed-by-parent / terminalized nodes.
@@ -22,3 +42,4 @@ export declare function markLost(input: {
     status?: string;
     reason?: string;
 }): Record<string, unknown>;
+export {};