peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/finalize-accumulator.js

@@ -0,0 +1,55 @@
+/**
+ * The finalize sweep's counters and the two pure helpers that read them, split
+ * out of `finalize-runners.ts` to keep each module under the line cap. The
+ * accumulator object replaces the mutable arrays the pre-split action closed
+ * over: it is created once and threaded explicitly through every branch.
+ */
+import { getErrorMessage } from 'peaks-loop-shared/result';
+// map outcome -> (status, outcome)
+export const OUTCOME_MAP = {
+    done: { status: 'done', outcome: 'success' },
+    failed: { status: 'failed', outcome: 'failed' },
+    cancelled: { status: 'cancelled', outcome: 'cancelled' }
+};
+export function makeAccumulator() {
+    return { finalized: [], skipped: [], errors: [] };
+}
+/**
+ * N2 — one unreadable record must not abort the sweep.
+ *
+ * Skipping `active-dispatches.json` and `batch-*.counter.json` by FILENAME
+ * removed the two non-record files that happened to be in the directory, but a
+ * single stale or foreign `dispatch-*.json` (an old `version`, hand-edited
+ * JSON, a truncated write) still made `readRecord` throw from OUTSIDE any
+ * try/catch — and the throw escaped to the action's outer handler, so
+ * `--request-id` AND `--batch` both died with `FINALIZE_ERROR` and exit 1
+ * without touching a single healthy record.
+ *
+ * A record that cannot be read is now reported in `errors[]` and skipped;
+ * every other record is processed as before.
+ */
+export function tryReadRecord(recordPath, readRecord, acc) {
+    try {
+        return readRecord(recordPath);
+    }
+    catch (e) {
+        acc.errors.push({ recordPath, error: getErrorMessage(e) });
+        return null;
+    }
+}
+export function buildFinalizeHints(acc, selection) {
+    const hints = [];
+    if (acc.errors.length > 0) {
+        hints.push('Re-run after fixing; unreadable records are listed in errors[] and were skipped, not fatal.');
+    }
+    else if (acc.finalized.length === 0 && acc.skipped.length > 0) {
+        hints.push("Nothing was finalized: every matching record had already left `queued`. See skipped[] for each record's status.");
+    }
+    else {
+        hints.push('All targeted records transitioned out of queued.');
+    }
+    if (selection !== null) {
+        hints.push(`--request-id selection (${selection.rule}): chose ${selection.chosen ?? '(none)'} of ${selection.matched} matching record(s); ${selection.rejected.length} rejected.`);
+    }
+    return hints;
+}

package/dist/cli/commands/finalize-branches.d.ts

@@ -0,0 +1,34 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import type { ActiveDispatchEntry, DispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
+import { type FinalizeSelection } from './finalize-selection.js';
+import type { FinalizeAccumulator } from './finalize-accumulator.js';
+export declare function finalizeAllStale(input: {
+    readActiveDispatchIndex: (projectRoot: string, sessionId: string) => Record<string, ActiveDispatchEntry>;
+    projectRoot: string;
+    sessionId: string;
+    apply: (recordPath: string, rid: string) => void;
+    acc: FinalizeAccumulator;
+}): void;
+export declare function finalizeByRequestId(input: {
+    projectRoot: string;
+    sessionId: string;
+    requestId: string;
+    io: ProgramIO;
+    asJson: boolean;
+    readOne: (recordPath: string) => DispatchRecord | null;
+    apply: (recordPath: string, rid: string) => void;
+    acc: FinalizeAccumulator;
+}): Promise<{
+    kind: 'not-found';
+} | {
+    kind: 'ok';
+    selection: FinalizeSelection;
+}>;
+export declare function finalizeByBatch(input: {
+    projectRoot: string;
+    sessionId: string;
+    batchId: string | undefined;
+    readOne: (recordPath: string) => DispatchRecord | null;
+    apply: (recordPath: string, rid: string) => void;
+    acc: FinalizeAccumulator;
+}): Promise<void>;

package/dist/cli/commands/finalize-branches.js

@@ -0,0 +1,119 @@
+/**
+ * The three finalize sweep branches — `--all-stale`, `--request-id` and
+ * `--batch` — split out of `finalize-runners.ts` to keep each module under the
+ * line cap. Each branch reads records, decides which to act on, and records
+ * the outcome in the shared accumulator; the runner owns the envelope.
+ */
+import { fail, getErrorMessage } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { FINALIZE_SELECTION_RULE, describeFinalizeRejection, selectFinalizeTarget } from './finalize-selection.js';
+import { safeRecordPath } from './share-record-paths.js';
+export function finalizeAllStale(input) {
+    const index = input.readActiveDispatchIndex(input.projectRoot, input.sessionId);
+    for (const [recordPath, entry] of Object.entries(index)) {
+        if (entry.status !== 'queued') {
+            input.acc.skipped.push({ recordPath, reason: 'status is ' + entry.status });
+            continue;
+        }
+        try {
+            input.apply(recordPath, entry.requestId);
+        }
+        catch (e) {
+            input.acc.errors.push({ recordPath, error: getErrorMessage(e) });
+        }
+    }
+}
+export async function finalizeByRequestId(input) {
+    const candidates = await collectRequestIdCandidates(input);
+    if (candidates.length === 0) {
+        printResult(input.io, fail('sub-agent.finalize', 'RECORD_NOT_FOUND', 'No dispatch record for requestId=' + input.requestId, { ok: false }, ['Check --request-id matches the dispatch envelope.']), input.asJson);
+        process.exitCode = 1;
+        return { kind: 'not-found' };
+    }
+    // N3: same rule as `--batch` — see `selectFinalizeTarget`.
+    const { selection, chosen } = buildRequestIdSelection(candidates, input.requestId);
+    for (const rejected of selection.rejected) {
+        input.acc.skipped.push({ recordPath: rejected.recordPath, reason: rejected.reason });
+    }
+    if (chosen !== null) {
+        try {
+            input.apply(chosen.recordPath, chosen.requestId);
+        }
+        catch (e) {
+            input.acc.errors.push({ recordPath: chosen.recordPath, error: getErrorMessage(e) });
+        }
+    }
+    return { kind: 'ok', selection };
+}
+async function collectRequestIdCandidates(input) {
+    const fs2 = await import('node:fs');
+    const path2 = await import('node:path');
+    const dir = path2.resolve(input.projectRoot, '.peaks', '_sub_agents', input.sessionId);
+    const candidates = [];
+    if (fs2.existsSync(dir)) {
+        for (const f of fs2.readdirSync(dir)) {
+            // Only dispatch records are readable records. The session directory also
+            // holds `active-dispatches.json` (an index) and `batch-<uuid>.counter.json`
+            // (batch counters); neither carries a `version` field, so `readRecord` on
+            // them throws `Dispatch record version mismatch ... got undefined`. The
+            // `--batch` branch below has always used this same filter.
+            if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
+                continue;
+            const p = safeRecordPath(path2.join(dir, f));
+            const r = input.readOne(p);
+            if (r === null || r.requestId !== input.requestId)
+                continue;
+            candidates.push({
+                recordPath: p,
+                requestId: r.requestId,
+                status: r.status,
+                createdAt: r.createdAt
+            });
+        }
+    }
+    return candidates;
+}
+function buildRequestIdSelection(candidates, requestId) {
+    const chosen = selectFinalizeTarget(candidates);
+    const selection = {
+        requestId,
+        rule: FINALIZE_SELECTION_RULE,
+        matched: candidates.length,
+        chosen: chosen?.recordPath ?? null,
+        rejected: candidates
+            .filter((candidate) => candidate !== chosen)
+            .map((candidate) => ({
+            recordPath: candidate.recordPath,
+            status: candidate.status,
+            reason: describeFinalizeRejection(candidate, chosen)
+        }))
+    };
+    return { selection, chosen };
+}
+export async function finalizeByBatch(input) {
+    const fs2 = await import('node:fs');
+    const path2 = await import('node:path');
+    const dir = path2.resolve(input.projectRoot, '.peaks', '_sub_agents', input.sessionId);
+    if (!fs2.existsSync(dir))
+        return;
+    for (const f of fs2.readdirSync(dir)) {
+        if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
+            continue;
+        const p = safeRecordPath(path2.join(dir, f));
+        const r = input.readOne(p);
+        if (r === null)
+            continue;
+        if (r.batchId !== input.batchId)
+            continue;
+        if (r.status !== 'queued') {
+            input.acc.skipped.push({ recordPath: p, reason: 'status is ' + r.status });
+            continue;
+        }
+        try {
+            input.apply(p, r.requestId);
+        }
+        catch (e) {
+            input.acc.errors.push({ recordPath: p, error: getErrorMessage(e) });
+        }
+    }
+}

package/dist/cli/commands/finalize-runners.d.ts

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import type { FinalizeOptions } from './finalize-selection.js';
+export declare function runFinalize(options: FinalizeOptions, io: ProgramIO): Promise<void>;

package/dist/cli/commands/finalize-runners.js

@@ -0,0 +1,92 @@
+/**
+ * The `finalize` action body for `peaks sub-agent`, split out of
+ * `share-commands.ts` so that registrar file stays under the line cap. The
+ * registrar fires this runner without awaiting it (the original fired a
+ * floating async IIFE in the same way).
+ *
+ * `runFinalizeSweep` builds the accumulator, applies the outcome mapping and
+ * prints the envelope; the three selection branches live in
+ * `finalize-branches.ts` and the selection rule itself in
+ * `finalize-selection.ts`.
+ */
+import { resolve } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { OUTCOME_MAP, buildFinalizeHints, makeAccumulator, tryReadRecord } from './finalize-accumulator.js';
+import { finalizeAllStale, finalizeByBatch, finalizeByRequestId } from './finalize-branches.js';
+export async function runFinalize(options, io) {
+    const asJson = options.json === true;
+    try {
+        const projectRoot = resolve(options.project ?? process.cwd());
+        const sessionId = options.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        if (!options.allStale && !options.requestId && !options.batch) {
+            printResult(io, fail('sub-agent.finalize', 'MISSING_TARGET', 'Pass --request-id or --batch (or --all-stale)', { ok: false }, ['Call finalize after each Task completes.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        await runFinalizeSweep({ options, io, asJson, projectRoot, sessionId });
+    }
+    catch (error) {
+        printResult(io, fail('sub-agent.finalize', 'FINALIZE_ERROR', getErrorMessage(error), { ok: false }, [
+            'Inspect the error.'
+        ]), asJson);
+        process.exitCode = 1;
+    }
+}
+async function runFinalizeSweep(input) {
+    const { options, io, asJson, projectRoot, sessionId } = input;
+    const outcome = (options.outcome ?? 'done');
+    const writerMod = await import('../../services/dispatch/dispatch-record-writer.js');
+    const { readRecord, markCompleted, readActiveDispatchIndex } = writerMod;
+    const mapped = OUTCOME_MAP[outcome] ?? OUTCOME_MAP['done'];
+    const acc = makeAccumulator();
+    const readOne = (recordPath) => tryReadRecord(recordPath, readRecord, acc);
+    const apply = (recordPath, rid) => {
+        markCompleted({
+            recordPath,
+            now: () => new Date(),
+            status: mapped.status,
+            outcome: mapped.outcome,
+            projectRoot
+        });
+        acc.finalized.push({ recordPath, requestId: rid, status: mapped.status });
+    };
+    let selection = null;
+    if (options.allStale) {
+        finalizeAllStale({ readActiveDispatchIndex, projectRoot, sessionId, apply, acc });
+    }
+    else if (options.requestId) {
+        const result = await finalizeByRequestId({
+            projectRoot,
+            sessionId,
+            requestId: options.requestId,
+            io,
+            asJson,
+            readOne,
+            apply,
+            acc
+        });
+        if (result.kind === 'not-found')
+            return;
+        selection = result.selection;
+    }
+    else {
+        await finalizeByBatch({ projectRoot, sessionId, batchId: options.batch, readOne, apply, acc });
+    }
+    printFinalizeResult({ io, asJson, sessionId, outcome, acc, selection });
+    if (acc.errors.length > 0)
+        process.exitCode = 1;
+}
+/** Print the `sub-agent.finalize` envelope and its hints. */
+function printFinalizeResult(input) {
+    const { acc } = input;
+    printResult(input.io, ok('sub-agent.finalize', {
+        finalized: acc.finalized,
+        skipped: acc.skipped,
+        errors: acc.errors,
+        selection: input.selection,
+        sessionId: input.sessionId,
+        outcome: input.outcome
+    }, acc.errors.length > 0 ? [acc.errors.length + ' failed'] : [], buildFinalizeHints(acc, input.selection)), input.asJson);
+}

package/dist/cli/commands/finalize-selection.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The pure `--request-id` selection contract for `peaks sub-agent finalize`, plus
+ * the option shape the command registers. Extracted from `share-commands.ts` so
+ * that file stays under the line cap; these are the pieces the finalize tests
+ * import directly, and none of them touches the filesystem.
+ */
+/**
+ * A `dispatch-*.json` candidate for `finalize --request-id`, as read off disk.
+ * The record's own `createdAt` is carried as the recency key — NOT the file's
+ * mtime, which any heartbeat or finalize rewrites, so a `done` record can look
+ * newer than the `queued` one that superseded it. Keeping the key on the
+ * candidate makes the selection rule a pure function of the records and
+ * testable without a filesystem.
+ */
+export interface FinalizeCandidate {
+    readonly recordPath: string;
+    readonly requestId: string;
+    readonly status: string;
+    readonly createdAt: string;
+}
+/**
+ * What `--request-id` actually did, reported in the envelope. N3: the branch
+ * used to resolve silently and could not say WHY a record was or was not the
+ * one finalized.
+ */
+export interface FinalizeSelection {
+    readonly requestId: string;
+    readonly rule: string;
+    readonly matched: number;
+    readonly chosen: string | null;
+    readonly rejected: readonly {
+        readonly recordPath: string;
+        readonly status: string;
+        readonly reason: string;
+    }[];
+}
+/** The one selection rule `--request-id` and `--batch` now share. */
+export declare const FINALIZE_SELECTION_RULE: string;
+/** The options `peaks sub-agent finalize` accepts. */
+export interface FinalizeOptions {
+    batch?: string;
+    requestId?: string;
+    outcome?: string;
+    error?: string;
+    allStale?: boolean;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+}
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export declare function selectFinalizeTarget(candidates: readonly FinalizeCandidate[]): FinalizeCandidate | null;
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export declare function describeFinalizeRejection(candidate: FinalizeCandidate, chosen: FinalizeCandidate | null): string;

package/dist/cli/commands/finalize-selection.js

@@ -0,0 +1,35 @@
+/**
+ * The pure `--request-id` selection contract for `peaks sub-agent finalize`, plus
+ * the option shape the command registers. Extracted from `share-commands.ts` so
+ * that file stays under the line cap; these are the pieces the finalize tests
+ * import directly, and none of them touches the filesystem.
+ */
+/** The one selection rule `--request-id` and `--batch` now share. */
+export const FINALIZE_SELECTION_RULE = 'prefer status=queued; among those, newest by record createdAt (then filename); ' +
+    'no queued match means nothing is finalized';
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export function selectFinalizeTarget(candidates) {
+    const queued = candidates.filter((candidate) => candidate.status === 'queued');
+    if (queued.length === 0)
+        return null;
+    return [...queued].sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.recordPath.localeCompare(a.recordPath))[0];
+}
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export function describeFinalizeRejection(candidate, chosen) {
+    if (candidate.status !== 'queued' || chosen === null) {
+        return 'status is ' + candidate.status;
+    }
+    return 'superseded by the newer queued record ' + chosen.recordPath;
+}

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

@@ -4,6 +4,7 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { emitHint } from '../../services/hooks/output.js';
 import { parseClaudeShapeStdin } from '../../services/ide/hook-translator.js';
 import { classifyTool, emitAllowSkipped, emitAllowWorktree, emitSopAllow, emitSopDeny, emitSopWarnings, handleWorktreeGate, parseHookStdin, resolveToolMatcher } from './gate-commands-enforce.js';
+import { handleMcpSurfaceGate } from '../../services/hooks/mcp-surface-gate.js';
 export function registerGateCommands(program, io) {
     const gate = program
         .command('gate')
@@ -53,6 +54,19 @@ function exitWhenRealCliHook() {
         process.exit(process.exitCode || 0);
     }
 }
+/** Read the payload's surface out of the tool name, the adapter's matcher and the command. */
+function classifySurface(parsedStdin) {
+    const toolMatcher = resolveToolMatcher(parsedStdin);
+    const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
+    const toolKind = classifyTool(toolName);
+    const isBash = toolName === toolMatcher && typeof command === 'string' && command.trim().length > 0;
+    return {
+        toolKind,
+        command,
+        bashCommand: isBash ? command : null,
+        isWorktreeToolSurface: toolKind === 'Agent' || toolKind === 'EnterWorktree'
+    };
+}
 /**
  * Body of the `gate enforce` PreToolUse handler. The worktree-then-SOP ordering and every early
  * return / exit-code path are documented on the helpers this delegates to in `gate-commands-enforce`.
@@ -63,23 +77,27 @@ async function runGateEnforceAction(io, options) {
     try {
         const raw = await readHookPayload();
         const parsedStdin = parseHookStdin(raw);
-        const toolMatcher = resolveToolMatcher(parsedStdin);
-        const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
-        const toolKind = classifyTool(toolName);
-        const isBashSurface = toolName === toolMatcher && typeof command === 'string' && command.trim().length > 0;
-        const isWorktreeToolSurface = toolKind === 'Agent' || toolKind === 'EnterWorktree';
-        if (!isBashSurface && !isWorktreeToolSurface) {
+        // The MCP branch runs FIRST and is fail-CLOSED, so it must not sit behind
+        // the "not a guarded surface" early return below — an MCP tool name matches
+        // neither the Bash matcher nor a worktree tool, so everything after this
+        // point would wave it through. A block here has already been emitted.
+        if (handleMcpSurfaceGate(io, parsedStdin)) {
+            return;
+        }
+        const surface = classifySurface(parsedStdin);
+        const { toolKind, command } = surface;
+        if (surface.bashCommand === null && !surface.isWorktreeToolSurface) {
             emitAllowSkipped(io, options);
             return;
         }
         if (handleWorktreeGate(io, options, toolKind, { command, parsedStdin })) {
             return;
         }
-        if (!isBashSurface) {
+        if (surface.bashCommand === null) {
             emitAllowWorktree(io, options);
             return;
         }
-        const decision = await enforceBashCommand(options.project, command);
+        const decision = await enforceBashCommand(options.project, surface.bashCommand);
         if (decision.decision === 'deny') {
             emitSopDeny(io, options, decision);
             return;

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

@@ -1,18 +1,32 @@
 /**
+ * The `peaks contract` / `peaks classify` entry point.
  *
  * Pre-merge originals (now deleted):
- *   - src/cli/commands/contract-commands.ts     (167 lines)
+ *   - 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.
+ * Both `register*Commands` functions are preserved **verbatim** (function name,
+ * signature, body). The merge was a structural refactor only — no behavior
+ * change — and `autoRegisterAllCommands` discovers both exports from this single
+ * file. This module is now the entry point and no longer holds the verbs:
  *
- * minimum; Family 1 is the cleanest demonstration because both inputs
- * sit under 200 lines and the merged file lands at ~360 lines — well
+ *   `contract-write-command.ts`        `peaks contract write`
+ *   `classify-run-command.ts`          `peaks classify run`
+ *   `classify-downgrade-command.ts`    `peaks classify downgrade` (always refused)
+ *   `classify-signals.ts`              the diff signals + the audit log
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export declare function registerContractCommands(program: Command, io: ProgramIO): void;
+import type { ProgramIO } from '../cli-helpers.js';
+export { registerContractCommands } from './contract-write-command.js';
+/**
+ * peaks classify CLI (Slice L1a + L1b).
+ *
+ * Subcommands:
+ *   - peaks classify run --project <path> [--override <level> --reason "<text>"]
+ *     Classify the current diff via the heuristic + return a JSON envelope
+ *     with the chosen level, gate set, and audit log.
+ *   - peaks classify downgrade --level <level> --reason "<text>" --project <path>
+ *     Always refused (per spec §4: "peaks classify downgrade" always errors
+ *     out). LLM may ask; the CLI never grants.
+ */
 export declare function registerClassifyCommands(program: Command, io: ProgramIO): void;