peaks-cli 1.3.2 → 1.3.3

package/dist/src/services/slice/slice-archive-service.js

@@ -0,0 +1,111 @@
+/**
+ * Slice #009 / G5 RL-8 — sub-agent dispatch record archival + 30-day GC.
+ *
+ * Called by the `peaks session finish` / `peaks session abandon` /
+ * new-rid-startup hooks. Walks the per-session `.peaks/_sub_agents/<sid>/`
+ * tree and moves completed + disposed records to
+ * `.peaks/_runtime/<sid>/_archive/_sub_agents/<sliceId>/`.
+ *
+ * GC policy:
+ *   - Records with `disposed: true` AND `outcome ∈ {success, failed,
+ *     timeout, cancelled}` (not "no-execution") → archive + 30-day GC.
+ *   - Records with `disposed: false` (any outcome) → archive but NOT
+ *     GC'd. Next session will see them as still-pending in
+ *     `_archive/.../in-flight/` and can resume reducer work.
+ *
+ * Lazy GC: `archiveSubAgentRecords` also scans the archive dir and
+ * deletes entries older than 30 days. No cron, no background daemon.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDispatchStatus, isOutcome } from '../dispatch/dispatch-record-writer.js';
+export const ARCHIVE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+/** Build the canonical archive dir for a given session + slice id. */
+export function archiveDir(projectRoot, sessionId, sliceId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, '_archive', '_sub_agents', sliceId);
+}
+/** Build the in-flight subdir (records not yet disposed). */
+export function inFlightArchiveDir(projectRoot, sessionId, sliceId) {
+    return join(archiveDir(projectRoot, sessionId, sliceId), 'in-flight');
+}
+/**
+ * Archive the current `.peaks/_sub_agents/<sid>/` tree under
+ * `<archiveDir>` (per the sliceId), separating completed vs in-flight.
+ * Then run the 30-day GC over the archive dir.
+ */
+export function archiveSubAgentRecords(projectRoot, options) {
+    const now = options.now ?? (() => new Date());
+    const sourceDir = join(projectRoot, '.peaks', '_sub_agents', options.sessionId);
+    const completedDir = archiveDir(projectRoot, options.sessionId, options.sliceId);
+    const inFlightDir = inFlightArchiveDir(projectRoot, options.sessionId, options.sliceId);
+    mkdirSync(completedDir, { recursive: true });
+    mkdirSync(inFlightDir, { recursive: true });
+    let archivedCompleted = 0;
+    let archivedInFlight = 0;
+    if (existsSync(sourceDir)) {
+        for (const entry of readdirSync(sourceDir)) {
+            if (!entry.startsWith('dispatch-') || !entry.endsWith('.json'))
+                continue;
+            const src = join(sourceDir, entry);
+            const record = readRecordOrNull(src);
+            if (record === null)
+                continue;
+            if (record.disposed === true && isCompletedOutcome(record.outcome)) {
+                renameSync(src, join(completedDir, entry));
+                archivedCompleted += 1;
+            }
+            else {
+                renameSync(src, join(inFlightDir, entry));
+                archivedInFlight += 1;
+            }
+        }
+    }
+    // 30-day GC: walk the archive root (any sliceId), delete entries
+    // whose file mtime is older than the retention.
+    const gcDeleted = runGarbageCollection(completedDir, now().getTime());
+    return { archivedCompleted, archivedInFlight, gcDeleted };
+}
+function isCompletedOutcome(outcome) {
+    return outcome === 'success' || outcome === 'failed' || outcome === 'timeout' || outcome === 'cancelled';
+}
+function readRecordOrNull(path) {
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const obj = parsed;
+        if (!isOutcome(obj.outcome) || !isDispatchStatus(obj.status))
+            return null;
+        if (typeof obj.disposed !== 'boolean')
+            return null;
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}
+function runGarbageCollection(dir, nowMs) {
+    if (!existsSync(dir))
+        return 0;
+    let deleted = 0;
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        try {
+            const stat = statSync(full);
+            if (stat.isDirectory()) {
+                deleted += runGarbageCollection(full, nowMs);
+                continue;
+            }
+            const ageMs = nowMs - stat.mtimeMs;
+            if (ageMs > ARCHIVE_RETENTION_MS) {
+                unlinkSync(full);
+                deleted += 1;
+            }
+        }
+        catch {
+            /* skip unreadable; do not crash the archive op */
+        }
+    }
+    return deleted;
+}

package/dist/src/services/solo/batch-heartbeat-poller.d.ts

@@ -0,0 +1,51 @@
+import { summarize, type SubAgentLiveView } from './status-line-renderer.js';
+export declare const DEFAULT_POLL_INTERVAL_MS = 10000;
+export declare const DEFAULT_STALE_THRESHOLD_MS: number;
+export type PollRecord = {
+    readonly path: string;
+    readonly role: string;
+};
+export type PollerStatusEvent = {
+    readonly kind: 'status';
+    readonly line: string;
+    readonly summary: ReturnType<typeof summarize>;
+    readonly views: readonly SubAgentLiveView[];
+};
+export type PollerStaleEvent = {
+    readonly kind: 'stale';
+    readonly path: string;
+    readonly role: string;
+    readonly lastBeatAgoSec: number;
+    readonly thresholdSec: number;
+};
+export type PollerDoneEvent = {
+    readonly kind: 'done';
+    readonly summary: ReturnType<typeof summarize>;
+};
+export type PollerEvent = PollerStatusEvent | PollerStaleEvent | PollerDoneEvent;
+export type PollerHandlers = {
+    onStatus?: (event: PollerStatusEvent) => void;
+    onStale?: (event: PollerStaleEvent) => void;
+    onDone?: (event: PollerDoneEvent) => void;
+    onError?: (error: unknown) => void;
+};
+export type PollerOptions = {
+    prefix: string;
+    intervalMs?: number;
+    staleThresholdMs?: number;
+    now?: () => Date;
+};
+export declare class BatchHeartbeatPoller {
+    private readonly records;
+    private readonly handlers;
+    private readonly options;
+    private timer;
+    private prevStale;
+    private prevSummaryDone;
+    private running;
+    constructor(records: readonly PollRecord[], handlers: PollerHandlers, options: PollerOptions);
+    start(): void;
+    stop(): void;
+    /** Force a tick (testing seam + low-level access for explicit invocation). */
+    tick(): void;
+}

package/dist/src/services/solo/batch-heartbeat-poller.js

@@ -0,0 +1,88 @@
+import { readRecords } from '../dispatch/dispatch-record-writer.js';
+import { renderStatusLine, summarize, viewSubAgent } from './status-line-renderer.js';
+export const DEFAULT_POLL_INTERVAL_MS = 10_000;
+export const DEFAULT_STALE_THRESHOLD_MS = 5 * 60 * 1000;
+const TERMINAL_STATUSES = ['done', 'failed'];
+const TERMINAL_RECORD_STATUSES = [
+    'done',
+    'failed',
+    'cancelled',
+    'no-execution'
+];
+export class BatchHeartbeatPoller {
+    records;
+    handlers;
+    options;
+    timer = null;
+    prevStale = new Set();
+    prevSummaryDone = 0;
+    running = false;
+    constructor(records, handlers, options) {
+        this.records = records;
+        this.handlers = handlers;
+        this.options = options;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.tick();
+        const interval = this.options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.timer = setInterval(() => this.tick(), interval);
+        // Don't keep the process alive just for the poller.
+        this.timer.unref?.();
+    }
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Force a tick (testing seam + low-level access for explicit invocation). */
+    tick() {
+        let recs;
+        try {
+            recs = readRecords(this.records.map((r) => r.path));
+        }
+        catch (error) {
+            this.handlers.onError?.(error);
+            return;
+        }
+        const now = this.options.now ?? (() => new Date());
+        const summary = summarize(recs);
+        const views = recs.map((r) => viewSubAgent(r, now));
+        const line = renderStatusLine(this.options.prefix, recs, now);
+        this.handlers.onStatus?.({ kind: 'status', line, summary, views });
+        const staleThresholdSec = Math.floor((this.options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS) / 1000);
+        for (const rec of recs) {
+            const v = viewSubAgent(rec, now);
+            if (v.isStale) {
+                const key = `${rec.role}::${rec.requestId}`;
+                if (!this.prevStale.has(key)) {
+                    this.prevStale.add(key);
+                    this.handlers.onStale?.({
+                        kind: 'stale',
+                        path: this.records.find((p) => p.role === rec.role)?.path ?? '',
+                        role: rec.role,
+                        lastBeatAgoSec: v.lastBeatAgoSec ?? -1,
+                        thresholdSec: staleThresholdSec
+                    });
+                }
+            }
+        }
+        if (summary.total > 0 && summary.done === summary.total && this.prevSummaryDone !== summary.done) {
+            this.prevSummaryDone = summary.done;
+            this.handlers.onDone?.({ kind: 'done', summary });
+            this.stop();
+        }
+        else if (recs.length > 0 &&
+            recs.every((r) => TERMINAL_RECORD_STATUSES.includes(r.status) || TERMINAL_STATUSES.includes(r.status))) {
+            this.handlers.onDone?.({ kind: 'done', summary });
+            this.stop();
+        }
+        else {
+            this.prevSummaryDone = summary.done;
+        }
+    }
+}

package/dist/src/services/solo/status-line-renderer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * G6.5 — status line renderer for the peaks-solo batch-sync wait period.
+ *
+ * Single line, 80-120 chars, status-line-friendly. The shape is
+ * documented in PRD §G6.5:
+ *
+ *   [peaks-solo] swarm 3/3 running | rd-planning 45% (12s ago) | qa-test-cases 30% (5s ago) | ui-design 20% (2s ago)
+ *   [peaks-solo] swarm 3/3 running | rd-planning 70% (8s ago) | qa-test-cases 50% (3s ago) | ui-design 30% (6s ago)
+ *   ...
+ *   [peaks-solo] swarm 3/3 done in 47.3s
+ *
+ * Pure helper; the poller calls it once per tick. No IO.
+ */
+import type { DispatchRecord } from '../dispatch/dispatch-record-writer.js';
+export type SubAgentLiveView = {
+    readonly role: string;
+    readonly status: string;
+    readonly progress: number | null;
+    readonly lastBeatAgoSec: number | null;
+    readonly isStale: boolean;
+};
+export type SwarmSummary = {
+    readonly total: number;
+    readonly running: number;
+    readonly done: number;
+    readonly failed: number;
+    readonly stale: number;
+};
+/** Build a per-sub-agent view of the current state of one record. */
+export declare function viewSubAgent(record: DispatchRecord, now?: () => Date): SubAgentLiveView;
+/** Aggregate swarm summary. */
+export declare function summarize(records: readonly DispatchRecord[]): SwarmSummary;
+/** Render a single status line. */
+export declare function renderStatusLine(prefix: string, records: readonly DispatchRecord[], now?: () => Date): string;

package/dist/src/services/solo/status-line-renderer.js

@@ -0,0 +1,55 @@
+const STALE_THRESHOLD_SEC = 5 * 60;
+/** Build a per-sub-agent view of the current state of one record. */
+export function viewSubAgent(record, now = () => new Date()) {
+    const latest = record.heartbeats[record.heartbeats.length - 1];
+    const lastBeatAgo = record.lastBeatAt
+        ? Math.max(0, Math.floor((now().getTime() - new Date(record.lastBeatAt).getTime()) / 1000))
+        : null;
+    const isStale = lastBeatAgo !== null && lastBeatAgo > STALE_THRESHOLD_SEC;
+    return {
+        role: record.role,
+        status: record.status,
+        progress: latest ? latest.progress : null,
+        lastBeatAgoSec: lastBeatAgo,
+        isStale
+    };
+}
+/** Aggregate swarm summary. */
+export function summarize(records) {
+    let running = 0;
+    let done = 0;
+    let failed = 0;
+    let stale = 0;
+    for (const r of records) {
+        const v = viewSubAgent(r);
+        if (v.isStale)
+            stale += 1;
+        if (r.status === 'done')
+            done += 1;
+        else if (r.status === 'failed' || r.status === 'cancelled')
+            failed += 1;
+        else
+            running += 1;
+    }
+    return { total: records.length, running, done, failed, stale };
+}
+/** Render a single status line. */
+export function renderStatusLine(prefix, records, now = () => new Date()) {
+    if (records.length === 0) {
+        return `${prefix} swarm 0/0 idle`;
+    }
+    const summary = summarize(records);
+    const allDone = summary.done === summary.total;
+    if (allDone) {
+        return `${prefix} swarm ${summary.done}/${summary.total} done`;
+    }
+    const parts = records.map((r) => renderOne(r, now));
+    return `${prefix} swarm ${summary.running}/${summary.total} running | ${parts.join(' | ')}`;
+}
+function renderOne(record, now) {
+    const view = viewSubAgent(record, now);
+    const pct = view.progress !== null ? `${view.progress}%` : '?%';
+    const ago = view.lastBeatAgoSec !== null ? `${view.lastBeatAgoSec}s ago` : 'no beat';
+    const stale = view.isStale ? ' ⚠ stale' : '';
+    return `${view.role} ${pct} (${ago})${stale}`;
+}

package/dist/src/services/workspace/reconcile-service.d.ts

@@ -144,6 +144,42 @@ export declare function migrateOldRuntimeState(projectRoot: string): {
         message: string;
     }>;
 };
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/<sid>/system/subagent-progress.json`
+ *   - `.peaks/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export declare function migrateSubAgentState(projectRoot: string): {
+    migratedFiles: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+};
 /**
  * Top-level orchestrator. Wires migration (added in slice
  * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,

package/dist/src/services/workspace/reconcile-service.js

@@ -16,11 +16,20 @@
  * Pure hand-rolled; uses only node:fs, node:path, and the existing
  * session-manager helper for writing the binding. No new dependencies.
  */
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { getSessionIdCanonical, setCurrentSessionBinding } from '../session/session-manager.js';
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/;
 const META_FILE = 'session.json';
+// Sub-agent state file basenames (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+// The legacy location was `.peaks/<sid>/system/<filename>`; the canonical new
+// location is `.peaks/_sub_agents/<sid>/<filename>`. `migrateSubAgentState`
+// moves the two files between these homes on every `reconcileWorkspace` run.
+const SUB_AGENT_MIGRATION_FILES = [
+    'subagent-progress.json',
+    'progress-spawn.json'
+];
+const SUB_AGENTS_DIR = '_sub_agents';
 // As of slice 2026-06-05-peaks-runtime-layer these old paths are the
 // back-compat read-only fallbacks; the canonical new home is
 // `.peaks/_runtime/`. `migrateOldRuntimeState` moves them to the new
@@ -488,6 +497,89 @@ function copyDirRecursiveSync(src, dest) {
         }
     }
 }
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/<sid>/system/subagent-progress.json`
+ *   - `.peaks/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export function migrateSubAgentState(projectRoot) {
+    const root = resolve(projectRoot);
+    const newDir = join(root, '.peaks', SUB_AGENTS_DIR);
+    const migratedFiles = [];
+    const errors = [];
+    for (const session of discoverSessions(projectRoot)) {
+        const oldSystemDir = join(session.path, 'system');
+        if (!existsSync(oldSystemDir))
+            continue;
+        const newSessionDir = join(newDir, session.sessionId);
+        mkdirSync(newSessionDir, { recursive: true });
+        for (const fname of SUB_AGENT_MIGRATION_FILES) {
+            const oldPath = join(oldSystemDir, fname);
+            const newPath = join(newSessionDir, fname);
+            if (!existsSync(oldPath))
+                continue;
+            if (existsSync(newPath)) {
+                // New path is authoritative; remove stale old file.
+                try {
+                    rmSync(oldPath, { force: true });
+                }
+                catch { /* best effort */ }
+                continue;
+            }
+            try {
+                try {
+                    renameSync(oldPath, newPath);
+                }
+                catch (renameError) {
+                    // Cross-device or locked-file fallback: copy + unlink.
+                    copyFileSync(oldPath, newPath);
+                    unlinkSync(oldPath);
+                }
+                migratedFiles.push(join('.peaks', session.sessionId, 'system', fname));
+            }
+            catch (error) {
+                errors.push({
+                    path: oldPath,
+                    message: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        // R-2 guard: only remove the legacy system/ dir when it has zero
+        // remaining files (the user might have unrelated content there).
+        try {
+            const remaining = readdirSync(oldSystemDir);
+            if (remaining.length === 0) {
+                rmdirSync(oldSystemDir);
+            }
+        }
+        catch { /* best effort */ }
+    }
+    return { migratedFiles, errors };
+}
 /**
  * Top-level orchestrator. Wires migration (added in slice
  * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,
@@ -503,11 +595,19 @@ export function reconcileWorkspace(options) {
     // before that read means the new path is the only path observed by
     // `getSessionIdCanonical` after this call returns.
     const migration = migrateOldRuntimeState(projectRoot);
-    const migrateErrors = migration.errors.map((e) => ({
-        kind: 'migrate',
-        path: e.path,
-        message: e.message
-    }));
+    const subAgentMigration = migrateSubAgentState(projectRoot);
+    const migrateErrors = [
+        ...migration.errors.map((e) => ({
+            kind: 'migrate',
+            path: e.path,
+            message: e.message
+        })),
+        ...subAgentMigration.errors.map((e) => ({
+            kind: 'migrate',
+            path: e.path,
+            message: e.message
+        }))
+    ];
     const sessions = discoverSessions(projectRoot);
     const activeSkillSessionId = readActiveSkillSessionId(projectRoot);
     const canonical = pickCanonicalSession(sessions, activeSkillSessionId);
@@ -575,6 +675,7 @@ export function reconcileWorkspace(options) {
         apply,
         repointed,
         migratedFiles: migration.migratedFiles,
+        subAgentStateMigrated: subAgentMigration.migratedFiles.length,
         errors: [...migrateErrors, ...deletionResult.errors],
         changeMarker,
         systemCleaned

package/dist/src/services/workspace/reconcile-types.d.ts

@@ -65,6 +65,18 @@ export type ReconcileResult = {
      * consumers can ignore this field.
      */
     migratedFiles: string[];
+    /**
+     * Count of legacy per-session sub-agent state files moved from
+     * `.peaks/<sid>/system/{subagent-progress,progress-spawn}.json` into
+     * `.peaks/_sub_agents/<sid>/` during this reconcile run.
+     *
+     * Added in slice 2026-06-06-sub-agent-spawn-bug-and-decouple. The
+     * detailed list of moved files is not surfaced here (the count is
+     * what the CLI summary and QA test assert on); the underlying
+     * `migrateSubAgentState` helper returns the full path list for
+     * forensics. Additive — older consumers can ignore this field.
+     */
+    subAgentStateMigrated: number;
     /**
      * Errors encountered during the migration step. Each entry has a
      * `kind: 'migrate'` discriminator so consumers can tell migration

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.3.2";
+export declare const CLI_VERSION = "1.3.3";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.3.2";
+export const CLI_VERSION = "1.3.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Cross-AI-IDE workflow-gating CLI + skill family (Claude Code shipped, Trae in progress; Codex / Cursor / Qoder / Tongyi Lingma on the roadmap).",
   "author": "SquabbyZ",
   "license": "MIT",
@@ -56,6 +56,7 @@
     "@colbymchenry/codegraph": "0.7.10",
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
+    "headroom-ai": "0.22.4",
     "ora": "^8.2.0",
     "shadcn": "4.7.0",
     "terminal-kit": "^3.1.2"