peaks-loop 4.1.2 → 4.1.3

package/dist/cli/commands/share-error-hints.js

@@ -0,0 +1,38 @@
+/**
+ * Per-code "what to do next" hints for the failure envelopes of
+ * `peaks sub-agent share`, `peaks sub-agent shared-read`, and
+ * `peaks sub-agent await`. Extracted from `share-commands.ts` so that file
+ * stays under the line cap; each helper is pure — it maps an error code to the
+ * single actionable hint the runner places in the envelope, and nothing here
+ * prints, reads state, or throws.
+ *
+ * Each branch names the most likely next step, so a caller gets an actionable
+ * hint instead of a generic "see error message" fallback.
+ */
+export function shareErrorNextActions(code) {
+    if (code === 'LOCK_TIMEOUT') {
+        return 'A concurrent `peaks sub-agent share` is holding the channel lock for >5s; retry, or check for a crashed holder (the .lock file is reaped after 30s).';
+    }
+    if (code === 'RECORD_NOT_FOUND' || code === 'INVALID_RECORD_PATH') {
+        return 'The dispatch record path is missing or outside .peaks/_sub_agents/. Re-run `peaks sub-agent dispatch <role>` to get a fresh record path, then use that here.';
+    }
+    return 'See error message; check that --batch matches the dispatch envelope and the value is a JSON object ≤ 64KB.';
+}
+export function sharedReadErrorNextActions(code) {
+    if (code === 'INVALID_BATCH_ID' || code === 'MISSING_BATCH') {
+        return 'Pass --batch <batchId> exactly as returned by the `peaks sub-agent dispatch` envelope.';
+    }
+    return 'See error message; check that --batch matches the dispatch envelope (typo / wrong batch will return an empty channel, not an error).';
+}
+export function awaitErrorNextActions(code) {
+    if (code === 'INVALID_TIMEOUT') {
+        return 'Pass --timeout as a positive integer ms (e.g. --timeout 60000). 0 and non-numeric values are rejected.';
+    }
+    if (code === 'IDE_NOT_SUPPORTED') {
+        return 'Switch to claude-code, or rely on LLM-side await for non-claude-code IDEs in slice 1.3.';
+    }
+    if (code === 'NO_DISPATCH_RECORDS') {
+        return 'Check --session-id / --project: records live under .peaks/_sub_agents/<sessionId>/. Use the batchId exactly as printed by the dispatch envelope.';
+    }
+    return 'See error message; check that --batch matches the dispatch envelope and --timeout is a positive integer ms.';
+}

package/dist/cli/commands/share-identity.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The session id for a `share` / `shared-read` / `await` envelope: an explicit
+ * `--session-id` wins, then `PEAKS_SESSION_ID`, then the id resolved from
+ * `.peaks/_runtime/session.json` under `projectRoot`, then the literal
+ * `"unknown-sid"` fallback.
+ *
+ * `peaks sub-agent finalize` deliberately uses a DIFFERENT chain (it never
+ * consults the env var), so it keeps its own resolution rather than calling
+ * this helper.
+ */
+export declare function resolveSessionId(options: {
+    sessionId?: string;
+}, projectRoot: string): string;

package/dist/cli/commands/share-identity.js

@@ -0,0 +1,22 @@
+/**
+ * Identity resolution for the `peaks sub-agent share` family envelopes.
+ * Extracted from `share-commands.ts` so the runners can share one definition of
+ * how a session id is chosen, instead of each repeating the same fallback chain.
+ */
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+/**
+ * The session id for a `share` / `shared-read` / `await` envelope: an explicit
+ * `--session-id` wins, then `PEAKS_SESSION_ID`, then the id resolved from
+ * `.peaks/_runtime/session.json` under `projectRoot`, then the literal
+ * `"unknown-sid"` fallback.
+ *
+ * `peaks sub-agent finalize` deliberately uses a DIFFERENT chain (it never
+ * consults the env var), so it keeps its own resolution rather than calling
+ * this helper.
+ */
+export function resolveSessionId(options, projectRoot) {
+    return (options.sessionId ??
+        process.env.PEAKS_SESSION_ID ??
+        getCurrentSessionId(projectRoot) ??
+        'unknown-sid');
+}

package/dist/cli/commands/share-record-paths.d.ts

@@ -0,0 +1,37 @@
+import type { DispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
+/**
+ * Resolve a record's on-disk path through `realpathSync` so the value returned
+ * here matches the value `writeInitialDispatchRecord` produces — which itself
+ * passes through `assertSafeDispatchRecordPath` and ends up canonicalized. On
+ * macOS, `mkdtempSync(join(tmpdir(), prefix))` returns `/var/folders/...`
+ * while `process.cwd()` after `chdir` returns `/private/var/folders/...`;
+ * without this helper the test fixture's `queuedPath` (canonical) and the
+ * envelope's `finalized[].recordPath` (raw) never compare equal. Falls back
+ * to the lexical path when the file is missing (race between scan and write).
+ */
+export declare function safeRecordPath(p: string): string;
+/**
+ * Resolve the dispatch records belonging to a batch.
+ *
+ * Reuses the conventions already in the repo instead of inventing a new one:
+ *   - records live at `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json`
+ *     (`dispatchRecordPath`, src/services/security/safe-settings-path.ts);
+ *   - a record's batch is its own `batchId` field, written by
+ *     `writeInitialDispatchRecord`. The `--batch` branch of `finalize` and
+ *     `findBatchRecords` in heartbeat-watch-command.ts resolve a batch the
+ *     same way: scan the session dir, filter `dispatch-*.json`, compare field.
+ *
+ * `unreadable` lists the `dispatch-*.json` candidates whose batch could NOT be
+ * determined. The caller must not fold them into "no such batch": a record it
+ * cannot read is not evidence that the batch is empty.
+ */
+export declare function resolveBatchRecords(input: {
+    projectRoot: string;
+    sessionId: string;
+    batchId: string;
+    readOne: (recordPath: string) => DispatchRecord;
+}): {
+    sessionDir: string;
+    recordPaths: string[];
+    unreadable: string[];
+};

package/dist/cli/commands/share-record-paths.js

@@ -0,0 +1,68 @@
+/**
+ * Dispatch-record path helpers shared by `peaks sub-agent await` (which scans a
+ * session directory for a batch's records) and `peaks sub-agent finalize`
+ * (which canonicalizes a record path before reporting it). Extracted from
+ * `share-commands.ts` so that file stays under the line cap; every helper here
+ * is pure — it takes its inputs and returns a value.
+ */
+import { existsSync, readdirSync, realpathSync as realpathSyncNative } from 'node:fs';
+import { join, resolve } from 'node:path';
+/**
+ * Resolve a record's on-disk path through `realpathSync` so the value returned
+ * here matches the value `writeInitialDispatchRecord` produces — which itself
+ * passes through `assertSafeDispatchRecordPath` and ends up canonicalized. On
+ * macOS, `mkdtempSync(join(tmpdir(), prefix))` returns `/var/folders/...`
+ * while `process.cwd()` after `chdir` returns `/private/var/folders/...`;
+ * without this helper the test fixture's `queuedPath` (canonical) and the
+ * envelope's `finalized[].recordPath` (raw) never compare equal. Falls back
+ * to the lexical path when the file is missing (race between scan and write).
+ */
+export function safeRecordPath(p) {
+    try {
+        return realpathSyncNative(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Resolve the dispatch records belonging to a batch.
+ *
+ * Reuses the conventions already in the repo instead of inventing a new one:
+ *   - records live at `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json`
+ *     (`dispatchRecordPath`, src/services/security/safe-settings-path.ts);
+ *   - a record's batch is its own `batchId` field, written by
+ *     `writeInitialDispatchRecord`. The `--batch` branch of `finalize` and
+ *     `findBatchRecords` in heartbeat-watch-command.ts resolve a batch the
+ *     same way: scan the session dir, filter `dispatch-*.json`, compare field.
+ *
+ * `unreadable` lists the `dispatch-*.json` candidates whose batch could NOT be
+ * determined. The caller must not fold them into "no such batch": a record it
+ * cannot read is not evidence that the batch is empty.
+ */
+export function resolveBatchRecords(input) {
+    const sessionDir = resolve(input.projectRoot, '.peaks', '_sub_agents', input.sessionId);
+    const recordPaths = [];
+    const unreadable = [];
+    if (!existsSync(sessionDir))
+        return { sessionDir, recordPaths, unreadable };
+    for (const name of readdirSync(sessionDir)) {
+        // `active-dispatches.json` (the index) and `batch-<uuid>.counter.json` are
+        // not records; neither carries a `version`, so `readRecord` would reject
+        // them as "version mismatch". Same filter as the `--batch` branch below.
+        if (!name.startsWith('dispatch-') || !name.endsWith('.json'))
+            continue;
+        const recordPath = safeRecordPath(join(sessionDir, name));
+        let batchId;
+        try {
+            batchId = input.readOne(recordPath).batchId;
+        }
+        catch {
+            unreadable.push(recordPath);
+            continue;
+        }
+        if (batchId === input.batchId)
+            recordPaths.push(recordPath);
+    }
+    return { sessionDir, recordPaths, unreadable };
+}

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

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import type { ShareOptions } from './sub-agent-shared.js';
+export declare function runShare(options: ShareOptions, io: ProgramIO): void;

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

@@ -0,0 +1,158 @@
+/**
+ * The `share` action body for `peaks sub-agent`, moved out of
+ * `share-commands.ts` so that registrar file stays under the line cap.
+ *
+ * The registrar keeps the command shape (name, description, options) and
+ * delegates to `runShare` here. Every envelope field, error code, hint text and
+ * log entry is byte-identical to the pre-split version.
+ */
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { SHARED_CHANNEL_SOFT_VALUE_WARN, writeSharedEntry } from 'peaks-loop-shared-channel';
+import { printResult } from '../cli-helpers.js';
+import { writeLogEntry } from '../../services/log/logger.js';
+import { shareErrorNextActions } from './share-error-hints.js';
+import { resolveSessionId } from './share-identity.js';
+export function runShare(options, io) {
+    const asJson = options.json === true;
+    if (!options.batch || !options.key || !options.value) {
+        printResult(io, fail('sub-agent.share', 'MISSING_ARG', '--batch, --key, and --value are required', { ok: false }, ['Re-run with --batch <batchId> --key <key> --value <jsonObject>.']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    const parsed = parseShareValue(options.value);
+    if (!parsed.ok) {
+        printResult(io, fail('sub-agent.share', 'INVALID_VALUE', `value must be a JSON object: ${parsed.message}`, { ok: false }, ['Pass --value as a JSON object literal, e.g. --value \'{"reason":"x"}\'.']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    writeShareEntry({
+        options,
+        io,
+        asJson,
+        batch: options.batch,
+        key: options.key,
+        parsedValue: parsed.value
+    });
+}
+/**
+ * Parse `--value`, which must be a JSON object literal. Mirrors the original
+ * inline parse: a parse failure and a non-object parse both surface as
+ * `INVALID_VALUE` carrying the thrown message.
+ */
+function parseShareValue(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('value must be a JSON object');
+        }
+        return { ok: true, value: parsed };
+    }
+    catch (err) {
+        return { ok: false, message: getErrorMessage(err) };
+    }
+}
+function resolveShareIdentity(options, projectRoot) {
+    return {
+        sid: resolveSessionId(options, projectRoot),
+        rid: options.requestId ?? 'unknown-rid',
+        from: options.from ?? 'unknown-role'
+    };
+}
+function writeShareEntry(input) {
+    try {
+        const projectRoot = input.options.project ?? process.cwd();
+        const { sid, rid, from } = resolveShareIdentity(input.options, projectRoot);
+        const result = writeSharedEntry({
+            projectRoot,
+            sid,
+            rid,
+            batchId: input.batch,
+            key: input.key,
+            from,
+            value: input.parsedValue
+        });
+        if (!result.ok) {
+            reportShareFailure(result, input.batch, input.io, input.asJson);
+            return;
+        }
+        printShareSuccess({
+            result,
+            batch: input.batch,
+            key: input.key,
+            io: input.io,
+            asJson: input.asJson
+        });
+        logShareWrite({
+            sid,
+            batchId: input.batch,
+            key: input.key,
+            valueSize: result.entry.valueSize,
+            lastWriteWins: result.lastWriteWins
+        });
+    }
+    catch (error) {
+        reportShareError(error, input.batch, input.io, input.asJson);
+    }
+}
+/** Report a thrown share failure, mapping a missing error code to `SHARE_ERROR`. */
+function reportShareError(error, batch, io, asJson) {
+    const code = error.code ?? 'SHARE_ERROR';
+    printResult(io, fail('sub-agent.share', code, getErrorMessage(error), { ok: false, batchId: batch }, [
+        shareErrorNextActions(code)
+    ]), asJson);
+    process.exitCode = 1;
+}
+function reportShareFailure(result, batch, io, asJson) {
+    const code = result.code;
+    printResult(io, fail('sub-agent.share', code, result.message, { ok: false, batchId: batch }, [
+        code === 'VALUE_TOO_LARGE'
+            ? 'Reduce value size; 1KB is a soft warning, 64KB is a hard reject.'
+            : 'See error message; check --batch, --key, --value arguments.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+function printShareSuccess(input) {
+    const warnings = [];
+    if (input.result.lastWriteWins) {
+        warnings.push('LAST_WRITE_WINS');
+    }
+    if (input.result.softWarning) {
+        warnings.push(`VALUE_SIZE_SOFT_WARN: ${input.result.entry.valueSize} > ${SHARED_CHANNEL_SOFT_VALUE_WARN} bytes`);
+    }
+    printResult(input.io, ok('sub-agent.share', {
+        envelopeVersion: '2.1.0',
+        ok: true,
+        batchId: input.batch,
+        entryKey: input.key,
+        writtenAt: input.result.entry.at,
+        channelSize: input.result.channelSize,
+        lastWriteWins: input.result.lastWriteWins,
+        valueSize: input.result.entry.valueSize
+    }, warnings, [
+        'Sub-agents in the same batch can read this entry via `peaks sub-agent shared-read --batch ' +
+            input.batch +
+            '`.'
+    ]), input.asJson);
+}
+function logShareWrite(input) {
+    try {
+        writeLogEntry({
+            ts: new Date().toISOString(),
+            level: 'info',
+            command: 'sub-agent.share',
+            msg: 'shared',
+            sessionId: input.sid,
+            batchId: input.batchId,
+            data: {
+                batchId: input.batchId,
+                key: input.key,
+                valueSize: input.valueSize,
+                lastWriteWins: input.lastWriteWins
+            }
+        });
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort */
+    }
+}

package/dist/cli/commands/shared-read-runners.d.ts

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import type { SharedReadOptions } from './sub-agent-shared.js';
+export declare function runSharedRead(options: SharedReadOptions, io: ProgramIO): void;

package/dist/cli/commands/shared-read-runners.js

@@ -0,0 +1,51 @@
+/**
+ * The `shared-read` action body for `peaks sub-agent`, split out of
+ * `share-runners.ts` to keep each module under the line cap. The registrar in
+ * `share-commands.ts` delegates here; the envelope, error code and hint text are
+ * byte-identical to the pre-split version.
+ */
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { readSharedChannel } from 'peaks-loop-shared-channel';
+import { printResult } from '../cli-helpers.js';
+import { sharedReadErrorNextActions } from './share-error-hints.js';
+import { resolveSessionId } from './share-identity.js';
+export function runSharedRead(options, io) {
+    const asJson = options.json === true;
+    if (!options.batch) {
+        printResult(io, fail('sub-agent.shared-read', 'MISSING_BATCH', '--batch is required', { ok: false }, ['Re-run with --batch <batchId>.']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        printSharedReadSuccess(options, options.batch, io, asJson);
+    }
+    catch (error) {
+        const code = error.code ?? 'SHARED_READ_ERROR';
+        printResult(io, fail('sub-agent.shared-read', code, getErrorMessage(error), { ok: false, batchId: options.batch }, [sharedReadErrorNextActions(code)]), asJson);
+        process.exitCode = 1;
+    }
+}
+function printSharedReadSuccess(options, batch, io, asJson) {
+    const projectRoot = options.project ?? process.cwd();
+    const sid = resolveSessionId(options, projectRoot);
+    const rid = options.requestId ?? 'unknown-rid';
+    const channel = readSharedChannel({
+        projectRoot,
+        sid,
+        rid,
+        batchId: batch,
+        ...(options.since !== undefined ? { since: options.since } : {}),
+        ...(options.key !== undefined ? { keyPattern: options.key } : {})
+    });
+    printResult(io, ok('sub-agent.shared-read', {
+        envelopeVersion: '2.1.0',
+        ok: true,
+        batchId: batch,
+        entries: channel.entries,
+        totalEntries: Object.keys(channel.entries).length,
+        channelSize: JSON.stringify(channel).length,
+        updatedAt: channel.updatedAt
+    }, [], [
+        'Shared channel is dispatcher-mediated; do not attempt to read sibling dispatch records directly.'
+    ]), asJson);
+}

package/dist/cli/commands/slice-check-command.d.ts

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

package/dist/cli/commands/slice-check-command.js

@@ -0,0 +1,54 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { sliceCheck } from '../../services/slice/slice-check-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const CHECK_DESCRIPTION = 'Boundary check for a slice (post-micro-cycle, pre-peaks-qa). ' +
+    'Runs 4 stages in order: typecheck -> unit-tests (changed-only by default; ' +
+    'use --run-tests for the full suite, or --skip-tests to opt out) -> ' +
+    'review-fanout -> gate-verify-pipeline. ' +
+    'Each stage reports pass / fail / skipped. ' +
+    'Exit 0 only if every stage passes or is skipped.';
+const CHECK_PROJECT_HELP = 'target project root';
+const CHECK_RID_HELP = 'request id; REQUIRED — there is no binding to fall back to, and slice check fails without it';
+const CHECK_REFRESH_FANOUT_HELP = 're-run the 3-way review fan-out (peaks-rd) even if the review files already exist';
+const CHECK_RUN_TESTS_HELP = 'opt in to the FULL test suite at the boundary (default is the changed-only suite via `vitest run --changed`); use the peaks-test skill to run the full suite standalone';
+const CHECK_SKIP_TESTS_HELP = 'skip the unit-test stage entirely (e.g. docs-only slices); use the peaks-test skill to run the full suite manually if you want a separate check';
+const CHECK_ALLOW_PRE_EXISTING_HELP = 'opt-in: if the unit-test stage fails, report it as `skipped` with a reason naming the failure count (useful when the repo has unrelated pre-existing failures; the long-term fix is to .skip or coverage.exclude those tests). Only meaningful with --run-tests or the default changed-only mode.';
+async function runSliceCheck(options, io) {
+    try {
+        const projectRoot = resolveCanonicalProjectRoot(options.project);
+        const result = await sliceCheck({
+            projectRoot,
+            ...(options.rid ? { rid: options.rid } : {}),
+            refreshFanout: options.refreshFanout === true,
+            runTests: options.runTests === true,
+            skipTests: options.skipTests === true,
+            allowPreExistingFailures: options.allowPreExistingFailures === true
+        });
+        const warnings = [];
+        if (result.stages.some((s) => s.status === 'fail')) {
+            warnings.push(`${result.stages.filter((s) => s.status === 'fail').length} of ${result.stages.length} stages failed. 边界 NOT ready -- fix the failures and re-run, or proceed at your own risk.`);
+        }
+        printResult(io, ok('slice.check', result, warnings, result.nextActions), options.json ?? false);
+        if (!result.boundaryReady) {
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        printResult(io, fail('slice.check', 'SLICE_CHECK_FAILED', getErrorMessage(error), { projectRoot: options.project }, [
+            `Verify the project path is a peaks repo and --rid names a slice (letters, digits, dots, underscores or dashes): ${options.rid ?? '(no --rid given)'}`
+        ]), options.json ?? false);
+        process.exitCode = 1;
+    }
+}
+export function registerSliceCheckCommand(slice, io) {
+    addJsonOption(slice
+        .command('check')
+        .description(CHECK_DESCRIPTION)
+        .option('--project <path>', CHECK_PROJECT_HELP, '.')
+        .option('--rid <rid>', CHECK_RID_HELP)
+        .option('--refresh-fanout', CHECK_REFRESH_FANOUT_HELP, false)
+        .option('--run-tests', CHECK_RUN_TESTS_HELP, false)
+        .option('--skip-tests', CHECK_SKIP_TESTS_HELP, false)
+        .option('--allow-pre-existing-failures', CHECK_ALLOW_PRE_EXISTING_HELP, false)).action((options) => runSliceCheck(options, io));
+}

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

@@ -1,24 +1,4 @@
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
+export { parsePickedFile } from './slice-plan-command.js';
 export declare function registerSliceCommands(program: Command, io: ProgramIO): void;
-interface PickedEnvelope {
-    readonly rid: string;
-    readonly picked: readonly {
-        readonly rid: string;
-        readonly files: readonly string[];
-        readonly label: string;
-    }[];
-}
-/**
- * Validate a -picked.json envelope. Throws a CLI-friendly Error on any
- * shape violation; the catch in the slice.plan action converts it to
- * a fail() envelope with `code: 'PICKED_ENVELOPE_INVALID'`.
- *
- * Schema:
- *   { rid: string; picked: Array<{ rid, files: string[], label }> }
- *
- * Rejects: missing rid, missing/invalid picked array, picked[i] missing
- * rid / files / label, picked[i].files empty.
- */
-export declare function parsePickedFile(pickedPath: string): PickedEnvelope;
-export {};