peaks-loop 4.1.2 → 4.1.3

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

@@ -1,407 +1,61 @@
-import { existsSync, readdirSync, realpathSync as realpathSyncNative } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, printResult } from '../cli-helpers.js';
-import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } from 'peaks-loop-shared-channel';
-import { writeLogEntry } from '../../services/log/logger.js';
-import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
-import { summarizeBatchResults } from './sub-agent-shared.js';
-/** 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;
-}
+import { addJsonOption } from '../cli-helpers.js';
+import { runAwait } from './await-runners.js';
+import { runFinalize } from './finalize-runners.js';
+import { runShare } from './share-runners.js';
+import { runSharedRead } from './shared-read-runners.js';
+// The finalize selection contract is imported by the finalize tests from this
+// entry file, so it stays re-exported here even though its implementation
+// moved to a sibling module.
+export { FINALIZE_SELECTION_RULE, describeFinalizeRejection, selectFinalizeTarget } from './finalize-selection.js';
+const SHARE_DESCRIPTION = 'G8.4: write a shared entry to the cross sub-agent shared channel. ' +
+    'Dispatcher-mediated indirect signal: sub-agent A writes, dispatcher ' +
+    'stores, sub-agent B (still in flight) reads via `peaks sub-agent ' +
+    'shared-read`. Not peer-to-peer; pseudo-swarm property 3 preserved.';
+const SHARED_READ_DESCRIPTION = 'G8.4: read entries from the cross sub-agent shared channel. ' +
+    'Returns sibling sub-agent status. Supports --since (ISO8601) ' +
+    'and --key (glob pattern with * wildcard).';
+const AWAIT_DESCRIPTION = '2.7.0 slice-dag-dispatcher MVP: wait for a batch of dispatched sub-agents ' +
+    'to finish (or hit --timeout). Returns one BatchResult per dispatch. ' +
+    'For non-claude-code IDEs, the wait is delegated to the LLM (slice 1.3 will ' +
+    'land real per-IDE joins).';
+const FINALIZE_DESCRIPTION = 'D21: signal that a dispatched sub-agent has finished (success/failure/cancellation). Pass --all-stale for crash-recovery sweep.';
 export function registerShareCommand(parent, io) {
     addJsonOption(parent
         .command('share')
-        .description('G8.4: write a shared entry to the cross sub-agent shared channel. ' +
-        'Dispatcher-mediated indirect signal: sub-agent A writes, dispatcher ' +
-        'stores, sub-agent B (still in flight) reads via `peaks sub-agent ' +
-        'shared-read`. Not peer-to-peer; pseudo-swarm property 3 preserved.')
+        .description(SHARE_DESCRIPTION)
         .requiredOption('--batch <batchId>', 'batchId (from `peaks sub-agent dispatch` envelope)')
         .requiredOption('--key <k>', 'entry key (convention: "<role>.<event>")')
         .requiredOption('--value <json>', 'JSON object value (≤ 1KB soft warn, ≥ 64KB rejected)')
         .option('--from <role>', 'sub-agent role string; defaults to dispatch record role if available')
         .option('--request-id <rid>', 'request id (default: "unknown-rid")')
         .option('--session-id <sid>', 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
-        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => {
-        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;
-        }
-        let parsedValue;
-        try {
-            const parsed = JSON.parse(options.value);
-            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-                throw new Error('value must be a JSON object');
-            }
-            parsedValue = parsed;
-        }
-        catch (err) {
-            printResult(io, fail('sub-agent.share', 'INVALID_VALUE', `value must be a JSON object: ${getErrorMessage(err)}`, { ok: false }, ['Pass --value as a JSON object literal, e.g. --value \'{"reason":"x"}\'.']), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const projectRoot = options.project ?? process.cwd();
-            const sid = options.sessionId ??
-                process.env.PEAKS_SESSION_ID ??
-                getCurrentSessionId(projectRoot) ??
-                'unknown-sid';
-            const rid = options.requestId ?? 'unknown-rid';
-            const from = options.from ?? 'unknown-role';
-            const result = writeSharedEntry({
-                projectRoot,
-                sid,
-                rid,
-                batchId: options.batch,
-                key: options.key,
-                from,
-                value: parsedValue
-            });
-            if (!result.ok) {
-                const code = result.code;
-                printResult(io, fail('sub-agent.share', code, result.message, { ok: false, batchId: options.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;
-                return;
-            }
-            const warnings = [];
-            if (result.lastWriteWins) {
-                warnings.push('LAST_WRITE_WINS');
-            }
-            if (result.softWarning) {
-                warnings.push(`VALUE_SIZE_SOFT_WARN: ${result.entry.valueSize} > ${SHARED_CHANNEL_SOFT_VALUE_WARN} bytes`);
-            }
-            printResult(io, ok('sub-agent.share', {
-                envelopeVersion: '2.1.0',
-                ok: true,
-                batchId: options.batch,
-                entryKey: options.key,
-                writtenAt: result.entry.at,
-                channelSize: result.channelSize,
-                lastWriteWins: result.lastWriteWins,
-                valueSize: result.entry.valueSize
-            }, warnings, [
-                'Sub-agents in the same batch can read this entry via `peaks sub-agent shared-read --batch ' +
-                    options.batch +
-                    '`.'
-            ]), asJson);
-            try {
-                writeLogEntry({
-                    ts: new Date().toISOString(),
-                    level: 'info',
-                    command: 'sub-agent.share',
-                    msg: 'shared',
-                    sessionId: sid,
-                    batchId: options.batch,
-                    data: {
-                        batchId: options.batch,
-                        key: options.key,
-                        valueSize: result.entry.valueSize,
-                        lastWriteWins: result.lastWriteWins
-                    }
-                });
-            }
-            catch {
-                // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                /* best-effort */
-            }
-        }
-        catch (error) {
-            const code = error.code ?? 'SHARE_ERROR';
-            printResult(io, fail('sub-agent.share', code, getErrorMessage(error), { ok: false, batchId: options.batch }, [shareErrorNextActions(code)]), asJson);
-            process.exitCode = 1;
-        }
-    });
-}
-/**
- * runner gets an actionable hint instead of a generic "see error
- * message" fallback. Each branch names the most likely next step.
- */
-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.';
+        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => runShare(options, io));
 }
 export function registerSharedReadCommand(parent, io) {
     addJsonOption(parent
         .command('shared-read')
-        .description('G8.4: read entries from the cross sub-agent shared channel. ' +
-        'Returns sibling sub-agent status. Supports --since (ISO8601) ' +
-        'and --key (glob pattern with * wildcard).')
+        .description(SHARED_READ_DESCRIPTION)
         .requiredOption('--batch <batchId>', 'batchId (from `peaks sub-agent dispatch` envelope)')
         .option('--since <iso>', 'only return entries written after this ISO8601 timestamp')
         .option('--key <pattern>', 'glob pattern, e.g. "rd.*" or "*.completed"')
         .option('--request-id <rid>', 'request id (default: "unknown-rid")')
         .option('--session-id <sid>', 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
-        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => {
-        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 {
-            const projectRoot = options.project ?? process.cwd();
-            const sid = options.sessionId ??
-                process.env.PEAKS_SESSION_ID ??
-                getCurrentSessionId(projectRoot) ??
-                'unknown-sid';
-            const rid = options.requestId ?? 'unknown-rid';
-            const channel = readSharedChannel({
-                projectRoot,
-                sid,
-                rid,
-                batchId: options.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: options.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);
-        }
-        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 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).';
+        .option('--project <path>', 'target project root (defaults to cwd)')).action((options) => runSharedRead(options, io));
 }
 export function registerAwaitCommand(parent, io) {
     addJsonOption(parent
         .command('await')
-        .description('2.7.0 slice-dag-dispatcher MVP: wait for a batch of dispatched sub-agents ' +
-        'to finish (or hit --timeout). Returns one BatchResult per dispatch. ' +
-        'For non-claude-code IDEs, the wait is delegated to the LLM (slice 1.3 will ' +
-        'land real per-IDE joins).')
+        .description(AWAIT_DESCRIPTION)
         .requiredOption('--batch <batchId>', 'batchId from a dispatch envelope')
         .option('--timeout <ms>', 'optional cap on how long the join waits (ms; default 60000, max 120000)')
         .option('--project <path>', 'target project root (defaults to cwd)')
-        .option('--session-id <sid>', 'override active session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')).action(async (options) => {
-        const asJson = options.json === true;
-        if (!options.batch) {
-            printResult(io, fail('sub-agent.await', 'MISSING_BATCH', '--batch is required', { ok: false }, [
-                'Re-run with --batch <batchId> from a dispatch envelope.'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        let timeoutMs;
-        if (typeof options.timeout === 'string' && options.timeout.length > 0) {
-            const n = Number.parseInt(options.timeout, 10);
-            if (!Number.isInteger(n) || n <= 0) {
-                printResult(io, fail('sub-agent.await', 'INVALID_TIMEOUT', `--timeout must be a positive integer ms (got ${options.timeout})`, { ok: false }, ['Pass an integer like --timeout 60000.']), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            timeoutMs = n;
-        }
-        const projectRoot = options.project ?? process.cwd();
-        const sid = options.sessionId ??
-            process.env.PEAKS_SESSION_ID ??
-            getCurrentSessionId(projectRoot) ??
-            'unknown-sid';
-        // Lazy-import IDE modules so `peaks sub-agent share` and
-        // `peaks sub-agent shared-read` (the high-frequency G8.4 path) do not
-        // pay for adapter resolution at module-load time. Slice
-        const { detectInstalledIde } = await import('../../services/ide/ide-detector.js');
-        const { getAdapter } = await import('../../services/ide/ide-registry.js');
-        const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
-        const adapter = getAdapter(ide);
-        const dispatcher = adapter.subAgentDispatcher;
-        if (typeof dispatcher.awaitBatch !== 'function') {
-            printResult(io, fail('sub-agent.await', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support awaitBatch`, { ok: false }, [
-                'Every built-in adapter has an awaitBatch since slice 1.3; a dispatcher without one is a custom adapter registered outside the built-in set.'
-            ]), asJson);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            // session's dispatch directory. `recordPaths` used to be hardcoded to
-            // `[]`, and `awaitBatch` short-circuits on an empty list
-            // (await-batch.ts:134) — so `await` reported zero results and exited 0
-            // for every batch, forever. A batch we cannot locate is now a failure,
-            // not a success with nothing in it.
-            const { readRecord } = await import('../../services/dispatch/dispatch-record-writer.js');
-            const scan = resolveBatchRecords({
-                projectRoot,
-                sessionId: sid,
-                batchId: options.batch,
-                readOne: readRecord
-            });
-            if (scan.recordPaths.length === 0) {
-                const unreadableNote = scan.unreadable.length > 0
-                    ? ` ${scan.unreadable.length} dispatch record(s) there could not be read, so they could not be matched to this batch: ${scan.unreadable.join(', ')}`
-                    : '';
-                printResult(io, fail('sub-agent.await', 'NO_DISPATCH_RECORDS', `No dispatch record with batchId=${options.batch} under ${scan.sessionDir}.${unreadableNote}`, {
-                    ok: false,
-                    batchId: options.batch,
-                    sessionDir: scan.sessionDir,
-                    unreadableRecords: scan.unreadable
-                }, [awaitErrorNextActions('NO_DISPATCH_RECORDS')]), asJson);
-                process.exitCode = 1;
-                return;
-            }
-            const input = {
-                batchId: options.batch,
-                dispatchCount: scan.recordPaths.length,
-                recordPaths: scan.recordPaths,
-                ...(timeoutMs !== undefined ? { timeoutMs } : {})
-            };
-            const results = await dispatcher.awaitBatch(input);
-            const summary = summarizeBatchResults(results);
-            printResult(io, ok('sub-agent.await', {
-                envelopeVersion: '2.1.0',
-                batchId: options.batch,
-                ide: dispatcher.label,
-                results,
-                summary,
-                unreadableRecords: scan.unreadable
-            }, scan.unreadable.length > 0
-                ? [
-                    `${scan.unreadable.length} unreadable dispatch record(s) in this session were skipped and are NOT part of the results: ${scan.unreadable.join(', ')}`
-                ]
-                : [], [
-                // four non-Claude IDEs would report `awaitByLlm: <ide> 1.2 fallback`,
-                // the slice-1.2 marker that slice 1.3 replaced with a real
-                // file-polling await. The text survived because nothing tested it —
-                // no adapter produces that note any more (asserted in
-                // sub-agent-dispatchers.test.ts), and the emitter that produced it,
-                // `awaitByLlmFallback`, has since been removed.
-                `Each non-claude-code IDE labels its own results (see the \`note\` field), so a timed-out slot is attributable to the adapter it came from.`
-            ]), asJson);
-        }
-        catch (error) {
-            const code = error.code ?? 'AWAIT_ERROR';
-            printResult(io, fail('sub-agent.await', code, getErrorMessage(error), { ok: false }, [
-                awaitErrorNextActions(code)
-            ]), asJson);
-            process.exitCode = 1;
-        }
-    });
-}
-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.';
-}
-/**
- * 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).
- */
-function safeRecordPath(p) {
-    try {
-        return realpathSyncNative(p);
-    }
-    catch {
-        return p;
-    }
-}
-/**
- *
- * 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` (below)
- *     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.
- */
-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 };
+        .option('--session-id <sid>', 'override active session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')).action((options) => runAwait(options, io, resolveIdeDispatcher));
 }
+/** Contract: LLM MUST call once per dispatched Task, in post-completion branch. */
 export function registerFinalizeCommand(parent, io) {
     addJsonOption(parent
         .command('finalize')
-        .description('D21: signal that a dispatched sub-agent has finished (success/failure/cancellation). Pass --all-stale for crash-recovery sweep.')
+        .description(FINALIZE_DESCRIPTION)
         .option('--batch <batchId>', 'batchId from dispatch envelope')
         .option('--request-id <rid>', 'requestId from dispatch envelope')
         .option('--outcome <state>', 'done | failed | cancelled (default: done)')
@@ -409,186 +63,23 @@ export function registerFinalizeCommand(parent, io) {
         .option('--all-stale', 'bulk-mark every queued record for this session as done')
         .option('--project <path>', 'target project root (defaults to cwd)')
         .option('--session-id <sid>', 'override active session id')).action((options) => {
-        void (async () => {
-            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;
-                }
-                const outcome = (options.outcome ?? 'done');
-                const writerMod = await import('../../services/dispatch/dispatch-record-writer.js');
-                const { readRecord, markCompleted, readActiveDispatchIndex } = writerMod;
-                // map outcome -> (status, outcome)
-                const outcomeMap = {
-                    done: { status: 'done', outcome: 'success' },
-                    failed: { status: 'failed', outcome: 'failed' },
-                    cancelled: { status: 'cancelled', outcome: 'cancelled' }
-                };
-                const mapped = outcomeMap[outcome] ?? outcomeMap['done'];
-                const finalized = [];
-                const skipped = [];
-                const errors = [];
-                let selection = null;
-                /**
-                 * 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.
-                 */
-                const tryReadRecord = (recordPath) => {
-                    try {
-                        return readRecord(recordPath);
-                    }
-                    catch (e) {
-                        errors.push({ recordPath, error: getErrorMessage(e) });
-                        return null;
-                    }
-                };
-                const applyOutcome = (recordPath, rid) => {
-                    markCompleted({
-                        recordPath,
-                        now: () => new Date(),
-                        status: mapped.status,
-                        outcome: mapped.outcome,
-                        projectRoot
-                    });
-                    finalized.push({ recordPath, requestId: rid, status: mapped.status });
-                };
-                if (options.allStale) {
-                    const index = readActiveDispatchIndex(projectRoot, sessionId);
-                    for (const [recordPath, entry] of Object.entries(index)) {
-                        if (entry.status !== 'queued') {
-                            skipped.push({ recordPath, reason: 'status is ' + entry.status });
-                            continue;
-                        }
-                        try {
-                            applyOutcome(recordPath, entry.requestId);
-                        }
-                        catch (e) {
-                            errors.push({ recordPath, error: getErrorMessage(e) });
-                        }
-                    }
-                }
-                else if (options.requestId) {
-                    const fs2 = await import('node:fs');
-                    const path2 = await import('node:path');
-                    const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', 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 = tryReadRecord(p);
-                            if (r === null || r.requestId !== options.requestId)
-                                continue;
-                            candidates.push({
-                                recordPath: p,
-                                requestId: r.requestId,
-                                status: r.status,
-                                createdAt: r.createdAt
-                            });
-                        }
-                    }
-                    if (candidates.length === 0) {
-                        printResult(io, fail('sub-agent.finalize', 'RECORD_NOT_FOUND', 'No dispatch record for requestId=' + options.requestId, { ok: false }, ['Check --request-id matches the dispatch envelope.']), asJson);
-                        process.exitCode = 1;
-                        return;
-                    }
-                    // N3: same rule as `--batch` — see `selectFinalizeTarget`.
-                    const chosen = selectFinalizeTarget(candidates);
-                    selection = {
-                        requestId: options.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)
-                        }))
-                    };
-                    for (const rejected of selection.rejected) {
-                        skipped.push({ recordPath: rejected.recordPath, reason: rejected.reason });
-                    }
-                    if (chosen !== null) {
-                        try {
-                            applyOutcome(chosen.recordPath, chosen.requestId);
-                        }
-                        catch (e) {
-                            errors.push({ recordPath: chosen.recordPath, error: getErrorMessage(e) });
-                        }
-                    }
-                }
-                else {
-                    const fs2 = await import('node:fs');
-                    const path2 = await import('node:path');
-                    const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
-                    if (fs2.existsSync(dir)) {
-                        for (const f of fs2.readdirSync(dir)) {
-                            if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
-                                continue;
-                            const p = safeRecordPath(path2.join(dir, f));
-                            const r = tryReadRecord(p);
-                            if (r === null)
-                                continue;
-                            if (r.batchId !== options.batch)
-                                continue;
-                            if (r.status !== 'queued') {
-                                skipped.push({ recordPath: p, reason: 'status is ' + r.status });
-                                continue;
-                            }
-                            try {
-                                applyOutcome(p, r.requestId);
-                            }
-                            catch (e) {
-                                errors.push({ recordPath: p, error: getErrorMessage(e) });
-                            }
-                        }
-                    }
-                }
-                const hints = [];
-                if (errors.length > 0) {
-                    hints.push('Re-run after fixing; unreadable records are listed in errors[] and were skipped, not fatal.');
-                }
-                else if (finalized.length === 0 && 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.`);
-                }
-                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, selection, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], hints), asJson);
-                if (errors.length > 0)
-                    process.exitCode = 1;
-            }
-            catch (error) {
-                printResult(io, fail('sub-agent.finalize', 'FINALIZE_ERROR', getErrorMessage(error), { ok: false }, ['Inspect the error.']), asJson);
-                process.exitCode = 1;
-            }
-        })();
+        void runFinalize(options, io);
     });
 }
+/**
+ * Resolve the per-IDE sub-agent dispatcher for `await`, importing the IDE
+ * modules lazily so `peaks sub-agent share` and `peaks sub-agent shared-read`
+ * (the high-frequency G8.4 path) do not pay for adapter resolution at
+ * module-load time.
+ *
+ * This lives here, not in the await runner, because this module is the adapter
+ * registry's consumer — `tests/unit/runtime/vendor-neutral-identity-guard.test.ts`
+ * pins that this file is in the guard's measured scope.
+ */
+async function resolveIdeDispatcher(projectRoot) {
+    const { detectInstalledIde } = await import('../../services/ide/ide-detector.js');
+    const { getAdapter } = await import('../../services/ide/ide-registry.js');
+    const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
+    const adapter = getAdapter(ide);
+    return { ide, dispatcher: adapter.subAgentDispatcher };
+}

package/dist/cli/commands/share-error-hints.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function shareErrorNextActions(code: string): string;
+export declare function sharedReadErrorNextActions(code: string): string;
+export declare function awaitErrorNextActions(code: string): string;