peaks-cli 1.2.7 → 1.2.9

package/dist/src/services/perf/perf-baseline-service.js

@@ -0,0 +1,213 @@
+/**
+ * Performance baseline scaffolding for the RD stage.
+ *
+ * peaks-solo's RD stage runs before the QA stage. The user-facing pain is
+ * that performance tests (lighthouse / k6 / project-local benches / etc.)
+ * have historically only been run at QA Gate A4 — too late in the loop,
+ * because a slow regression discovered at QA triggers a return-to-rd
+ * cycle, the RD ships another "fix", QA re-runs, and the same cycle
+ * repeats up to 3 times before the slice ships.
+ *
+ * `peaks perf baseline` is the user-visible artifact of a deliberate
+ * compromise: keep the heavy performance measurement as something the
+ * RD runs themselves (lighthouse is project-shape dependent and we
+ * don't want to bake a lighthouse dependency into the CLI), but capture
+ * the result in a stable, scaffolded file under
+ * `.peaks/<sid>/rd/perf-baseline.md` so QA Gate A4 has a known-good
+ * reference to diff against. The CLI itself only writes the scaffold
+ * and records the path; the actual measurement is a project-local
+ * concern that lives in the README, not in peaks-cli.
+ *
+ * The four-grounds check (per the skill-primary-CLI-auxiliary dev
+ * preference):
+ *   1. hook/script/CI invokability  — yes, a hook can call this CLI
+ *                                     to scaffold the file on session
+ *                                     init, similar to session bootstrap.
+ *   2. JSON envelope that gates a downstream decision — yes,
+ *                                     peaks-rd reads the result and
+ *                                     attaches it to the handoff.
+ *   3. Destructive --apply side effect — yes, default dry-run.
+ *   4. Machine-enforced gate that prose cannot enforce — no, the
+ *                                     measurement still lives in
+ *                                     the LLM / project tools. We do
+ *                                     NOT add a lint gate here.
+ *
+ * Net: CLI is justified. The destructive --apply default is dry-run,
+ * matching the rest of peaks-cli's scaffolding pattern.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionId } from '../session/session-manager.js';
+import { findProjectRoot } from '../config/config-safety.js';
+const README_BODY = `# Performance baseline
+
+> Scaffolding for the RD-side performance baseline. Created by
+> \`peaks perf baseline\`. The actual measurement is the RD's
+> responsibility — see the "How to fill this in" section below.
+
+## Why this exists
+
+The QA stage's Gate A4 (performance check) compares the slice's
+performance against the most recent baseline. Without an RD-side
+baseline, the first time Gate A4 runs it has nothing to compare
+against and any regression it finds is a blind-side surprise.
+Capturing the baseline at the RD stage — right after the
+implementation lands and before QA picks it up — closes that
+gap and prevents the "QA returns 3 times for the same perf
+regression" loop.
+
+## What to capture
+
+For each performance-sensitive code path in the slice, record:
+
+- **Path / route** — which entry point (page, hook, API) the
+  measurement targets.
+- **Workload** — what you did with it (cold load, hot loop, the
+  exact N of records the slice introduces).
+- **Tool** — lighthouse / k6 / autocannon / project-local bench
+  script. Match the tool to the workload; do not introduce a new
+  one if the project already has a benchmark script.
+- **Metrics** — at minimum LCP / FCP / TBT / CLS for frontend,
+  p50/p95/p99 latency + rps for backend, rss / heap growth
+  for long-running services.
+- **Baseline value** — the number you measured, with units.
+- **Threshold** — what the slice's PRD / acceptance criteria
+  consider acceptable. If the PRD does not specify, leave this
+  field as \`TBD (ask PM)\` and surface it in the RD handoff.
+
+## How to fill this in
+
+1. Run the project's chosen performance tool against the
+   implementation you just landed. If the project does not have
+   a tool yet, the lightest first step is the chrome devtools
+   performance tab on the touched route.
+2. For each metric, copy the row from "What to capture" into
+   the "Results" table below and fill in the number.
+3. The threshold is the bar QA Gate A4 will compare against.
+   Be conservative — if the threshold is tighter than what the
+   tool reports, Gate A4 will fail.
+
+## Results
+
+| Path / route | Workload | Tool | Metric | Baseline | Threshold |
+|---|---|---|---|---|---|
+|  |  |  |  |  |  |
+
+## Notes
+
+- If the slice is documentation-only or has no user-visible
+  performance surface, write \`N/A — no perf surface\` here and
+  surface that fact in the RD handoff.
+- If the measurement exceeded the threshold on the first run,
+  do NOT loosen the threshold to make it pass. The right move
+  is to optimise the implementation and re-measure, or to
+  surface the trade-off to the PRD owner for a threshold bump.
+
+## Handoff
+
+- to peaks-qa: the \`Results\` table is the input to Gate A4.
+  Without it QA cannot establish a comparison baseline.
+- to peaks-sc: any threshold bumps captured here belong in the
+  release notes if the threshold moved.
+`;
+function renderBaselineTemplate() {
+    return README_BODY;
+}
+function buildPlan(projectRoot, apply) {
+    const sessionId = getSessionId(projectRoot);
+    const sessionRoot = sessionId !== null
+        ? join(projectRoot, '.peaks', sessionId)
+        : null;
+    const perfBaselinePath = sessionRoot !== null
+        ? join(sessionRoot, 'rd', 'perf-baseline.md')
+        : null;
+    const plannedWrites = [];
+    if (sessionRoot !== null && perfBaselinePath !== null) {
+        plannedWrites.push({
+            path: join(sessionRoot, 'rd'),
+            kind: 'directory',
+            bytes: 0,
+            content: ''
+        });
+        plannedWrites.push({
+            path: perfBaselinePath,
+            kind: 'file',
+            bytes: 0,
+            content: renderBaselineTemplate()
+        });
+        for (const write of plannedWrites) {
+            if (write.kind === 'file') {
+                write.bytes = Buffer.byteLength(write.content, 'utf8');
+            }
+        }
+    }
+    return {
+        apply,
+        projectRoot,
+        sessionId,
+        perfBaselinePath,
+        plannedWrites,
+        alreadyInitialized: false,
+        existingFiles: []
+    };
+}
+/**
+ * Idempotency: skip writes for the perf-baseline file when it
+ * already exists. Re-running `peaks perf baseline` on the same
+ * session is a normal RD retry pattern (re-measurement, threshold
+ * adjustment, etc.); we must not blow away hand-edited content.
+ */
+async function planPerfBaselineInit(options) {
+    const plan = buildPlan(options.projectRoot, options.apply ?? false);
+    if (plan.perfBaselinePath !== null && existsSync(plan.perfBaselinePath)) {
+        plan.alreadyInitialized = true;
+        plan.existingFiles = [plan.perfBaselinePath];
+        plan.plannedWrites = [];
+    }
+    return plan;
+}
+export async function executePerfBaselineInit(options) {
+    const plan = await planPerfBaselineInit(options);
+    const writtenFiles = [];
+    const createdDirectories = [];
+    if (plan.sessionId === null) {
+        return {
+            ...plan,
+            ...(options.reason !== undefined ? { reason: options.reason } : {}),
+            writtenFiles,
+            createdDirectories
+        };
+    }
+    if (plan.apply && !plan.alreadyInitialized) {
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory') {
+                if (!existsSync(write.path)) {
+                    await mkdir(write.path, { recursive: true });
+                    createdDirectories.push(write.path);
+                }
+                continue;
+            }
+            if (write.content.length === 0)
+                continue;
+            await writeFile(write.path, write.content, 'utf8');
+            writtenFiles.push(write.path);
+        }
+    }
+    return {
+        ...plan,
+        ...(options.reason !== undefined ? { reason: options.reason } : {}),
+        writtenFiles,
+        createdDirectories
+    };
+}
+/**
+ * Re-exported so the CLI command can fall back to a project-root
+ * resolution when the caller did not pass --project. The CLI does
+ * the same findProjectRoot walk that `workspace init` does; this
+ * helper exists for the command layer to import without reaching
+ * into config-safety directly.
+ */
+export function resolveProjectRootFromCwd(cwd) {
+    return findProjectRoot(cwd) ?? cwd;
+}

package/dist/src/services/progress/progress-service.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Sub-agent progress surfacing for the RD/QA sub-agents in
+ * `peaks-solo`'s Swarm phase. A sub-agent (or the LLM via the
+ * `peaks progress step` CLI) writes a stable JSON file at
+ * `.peaks/<sid>/system/subagent-progress.json`. The user-side
+ * `peaks progress watch` CLI polls this file in a separate
+ * terminal tab and renders elapsed / spinner / sub-step. The
+ * `peaks progress start` CLI auto-spawns the watch in a new
+ * terminal window so the user does not have to remember to do
+ * it.
+ *
+ * Token cost design (the binding constraint of this feature):
+ *   - The LLM side (step CLI) writes the file at most once per
+ *     phase transition. That is approximately one Bash call per
+ *     RD/QA sub-step. In a typical 5-step sub-agent slice the
+ *     cost is < 10 output tokens.
+ *   - The watch side polls a local file, not the LLM. Zero token
+ *     cost.
+ *   - The auto-spawn side (start CLI) is invoked once per
+ *     session by the LLM at the first phase transition. One
+ *     Bash call. The user closes the new terminal at any time;
+ *     no further side effects.
+ *
+ * Net: the LLM pays a one-time < 10 token cost per slice to
+ * give the user real-time progress visibility. The user pays
+ * zero manual setup.
+ *
+ * This module is pure filesystem. It does NOT import the LLM
+ * harness, does NOT spawn terminals, and does NOT talk to any
+ * IPC. Those are concerns of the CLI layer (../cli/commands/
+ * progress-commands.ts and hooks-settings-service.ts).
+ */
+export type SubAgentProgressPhase = 'starting' | 'running' | 'verifying' | 'completing' | 'finished' | 'failed' | 'idle';
+export type SubAgentProgressStep = {
+    /** ISO-8601 timestamp at which the sub-agent started. */
+    startedAt: string;
+    /** ISO-8601 timestamp at which the sub-agent finished (or now, if still running). */
+    updatedAt: string;
+    /** Free-form human-readable sub-step label, e.g. "running test/ut". */
+    step: string;
+    /** Current phase bucket. `idle` is the pre-start sentinel. */
+    phase: SubAgentProgressPhase;
+    /** When set, the sub-agent is finished and reports the verdict here. */
+    verdict?: 'pass' | 'return-to-rd' | 'blocked';
+    /** Optional count of in-scope files touched, assertions run, etc. */
+    counts?: {
+        filesTouched?: number;
+        testsRun?: number;
+    };
+};
+export type SubAgentProgress = {
+    version: 1;
+    sessionId: string;
+    outerSessionId?: string;
+    /** Outer-agent role that owns the slice (e.g. "rd", "qa"). */
+    role: string;
+    /** Per-slice identifier. */
+    requestId: string;
+    /** When the sub-agent entered the first non-idle state. */
+    startedAt: string;
+    /** When the sub-agent last touched the file. */
+    updatedAt: string;
+    /** Current step. */
+    current: SubAgentProgressStep;
+    /**
+     * History of completed steps. Length is unbounded; the watch
+     * tool renders the most recent N. Kept for after-the-fact
+     * forensics ("how long did step 3 take?").
+     */
+    history: SubAgentProgressStep[];
+};
+export type ReadProgressOptions = {
+    projectRoot: string;
+};
+export type ReadProgressResult = {
+    ok: true;
+    data: SubAgentProgress;
+    path: string;
+} | {
+    ok: false;
+    reason: 'no-binding' | 'no-progress-file' | 'invalid-json';
+};
+export type WriteProgressOptions = {
+    projectRoot: string;
+    requestId: string;
+    role: string;
+    step: string;
+    phase: SubAgentProgressPhase;
+    verdict?: 'pass' | 'return-to-rd' | 'blocked';
+    counts?: SubAgentProgressStep['counts'];
+    outerSessionId?: string;
+};
+/**
+ * Read the current progress file. Returns a tagged result so
+ * the CLI can map each failure mode to a distinct nextActions
+ * hint (no-binding → run peaks workspace init; no-progress-file
+ * → sub-agent has not started yet; invalid-json → the LLM wrote
+ * garbage; recover by writing a fresh file).
+ */
+export declare function readSubAgentProgress(options: ReadProgressOptions): ReadProgressResult;
+/**
+ * Append-or-replace the current step. Idempotent on identical
+ * (step, phase) — the file is rewritten with the same payload
+ * (no new history entry) so heartbeats from the same phase do
+ * not pollute the history. Phase transitions append a new step
+ * to the history and replace `current`.
+ */
+export declare function writeSubAgentProgress(options: WriteProgressOptions): SubAgentProgress;
+/**
+ * Resolve the project root for a CLI invocation: --project
+ * override wins, otherwise the canonical git-root promotion
+ * (so the sub-agent's writes land in the same `.peaks/<sid>/`
+ * the user's manual CLI would use). Re-exports the same
+ * helper peaks workspace init / session rotate already use
+ * for symmetry.
+ */
+export declare function resolveProgressProjectRoot(override: string | undefined, cwd: string): string;
+/**
+ * Compute the absolute path to the progress file for a given
+ * project root, for callers that need to display / fs.watch it
+ * (the watch banner, the auto-spawn helper, the close command).
+ * This MUST agree with `progressPath` — the read/write helpers
+ * resolve through `progressPath` and use the session sub-directory,
+ * so the displayed path does too. Without this agreement the
+ * watch banner would point at a path the file is never written
+ * to, and the user would `cat` an empty file.
+ */
+export declare function subAgentProgressPath(projectRoot: string): string;
+/**
+ * Compute the absolute path to the spawn record for a given
+ * project root. Exported so `peaks progress close` (and the
+ * start command's success payload) can advertise the on-disk
+ * location without re-deriving the session sub-directory.
+ */
+export declare function subAgentSpawnPath(projectRoot: string): string;
+export type ProgressSpawnRecord = {
+    version: 1;
+    sessionId: string;
+    pid: number;
+    platform: NodeJS.Platform;
+    command: string;
+    args: string[];
+    spawnedAt: string;
+    reason?: string;
+    /** The title we asked the terminal emulator to set. */
+    windowTitle: string;
+};
+export type WriteSpawnRecordOptions = {
+    projectRoot: string;
+    pid: number;
+    platform: NodeJS.Platform;
+    command: string;
+    args: string[];
+    reason?: string;
+    windowTitle: string;
+};
+export declare function writeSpawnRecord(options: WriteSpawnRecordOptions): ProgressSpawnRecord | null;
+export type ReadSpawnRecordResult = {
+    ok: true;
+    data: ProgressSpawnRecord;
+    path: string;
+} | {
+    ok: false;
+    reason: 'no-binding' | 'no-spawn-record' | 'invalid-json';
+};
+export declare function readSpawnRecord(projectRoot: string): ReadSpawnRecordResult;
+export declare function clearSpawnRecord(projectRoot: string): boolean;
+export type PhaseClosingTrigger = 'finished' | 'failed';
+/**
+ * True if a transition into the given phase should auto-close
+ * the spawned watch window. `finished` and `failed` both
+ * indicate the sub-agent is done; a `blocked` verdict on a
+ * `finished` step is intentionally NOT a close trigger
+ * because a blocked slice usually means the user needs to
+ * read the watch output before deciding what to do. The CLI
+ * layer reads `data.current.phase`, not the verdict, so this
+ * helper is the only close-decision source of truth.
+ */
+export declare function phaseAutoClosesSpawn(phase: SubAgentProgressPhase): boolean;

package/dist/src/services/progress/progress-service.js

@@ -0,0 +1,276 @@
+/**
+ * Sub-agent progress surfacing for the RD/QA sub-agents in
+ * `peaks-solo`'s Swarm phase. A sub-agent (or the LLM via the
+ * `peaks progress step` CLI) writes a stable JSON file at
+ * `.peaks/<sid>/system/subagent-progress.json`. The user-side
+ * `peaks progress watch` CLI polls this file in a separate
+ * terminal tab and renders elapsed / spinner / sub-step. The
+ * `peaks progress start` CLI auto-spawns the watch in a new
+ * terminal window so the user does not have to remember to do
+ * it.
+ *
+ * Token cost design (the binding constraint of this feature):
+ *   - The LLM side (step CLI) writes the file at most once per
+ *     phase transition. That is approximately one Bash call per
+ *     RD/QA sub-step. In a typical 5-step sub-agent slice the
+ *     cost is < 10 output tokens.
+ *   - The watch side polls a local file, not the LLM. Zero token
+ *     cost.
+ *   - The auto-spawn side (start CLI) is invoked once per
+ *     session by the LLM at the first phase transition. One
+ *     Bash call. The user closes the new terminal at any time;
+ *     no further side effects.
+ *
+ * Net: the LLM pays a one-time < 10 token cost per slice to
+ * give the user real-time progress visibility. The user pays
+ * zero manual setup.
+ *
+ * This module is pure filesystem. It does NOT import the LLM
+ * harness, does NOT spawn terminals, and does NOT talk to any
+ * IPC. Those are concerns of the CLI layer (../cli/commands/
+ * progress-commands.ts and hooks-settings-service.ts).
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { getSessionIdCanonical } from '../session/session-manager.js';
+import { findProjectRoot } from '../config/config-safety.js';
+const PROGRESS_REL_PATH = 'system/subagent-progress.json';
+const SPAWN_REL_PATH = 'system/progress-spawn.json';
+function progressPath(projectRoot) {
+    // The progress file lives under the *session* directory, not
+    // directly under .peaks/. Every other per-slice artefact
+    // (rd/tech-doc.md, qa/test-cases/<rid>.md, prd/requests/<rid>.md,
+    // memory/, openspec/) lives under .peaks/<sid>/, so progress
+    // should too. Without the session prefix, a session rotation
+    // would orphan the file in the project root, and switching
+    // sessions would have the watch reading the wrong slice's
+    // progress.
+    const sessionId = getSessionIdCanonical(projectRoot);
+    const subDir = sessionId ?? 'unbound';
+    return join(projectRoot, '.peaks', subDir, PROGRESS_REL_PATH);
+}
+function ensureParentDir(path) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Read the current progress file. Returns a tagged result so
+ * the CLI can map each failure mode to a distinct nextActions
+ * hint (no-binding → run peaks workspace init; no-progress-file
+ * → sub-agent has not started yet; invalid-json → the LLM wrote
+ * garbage; recover by writing a fresh file).
+ */
+export function readSubAgentProgress(options) {
+    const sessionId = getSessionIdCanonical(options.projectRoot);
+    if (sessionId === null) {
+        return { ok: false, reason: 'no-binding' };
+    }
+    const path = progressPath(options.projectRoot);
+    if (!existsSync(path)) {
+        return { ok: false, reason: 'no-progress-file' };
+    }
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        if (data.version !== 1 || typeof data.sessionId !== 'string') {
+            return { ok: false, reason: 'invalid-json' };
+        }
+        return { ok: true, data, path };
+    }
+    catch {
+        return { ok: false, reason: 'invalid-json' };
+    }
+}
+/**
+ * Append-or-replace the current step. Idempotent on identical
+ * (step, phase) — the file is rewritten with the same payload
+ * (no new history entry) so heartbeats from the same phase do
+ * not pollute the history. Phase transitions append a new step
+ * to the history and replace `current`.
+ */
+export function writeSubAgentProgress(options) {
+    const existing = readSubAgentProgress({ projectRoot: options.projectRoot });
+    const now = nowIso();
+    const path = progressPath(options.projectRoot);
+    if (existing.ok) {
+        const prev = existing.data;
+        // Heartbeat on the same current step: just bump updatedAt, do
+        // NOT add a history entry. The shape of `current` is preserved.
+        if (prev.current.step === options.step && prev.current.phase === options.phase) {
+            const next = {
+                ...prev,
+                updatedAt: now,
+                current: {
+                    ...prev.current,
+                    updatedAt: now,
+                    ...(options.verdict !== undefined ? { verdict: options.verdict } : {}),
+                    ...(options.counts !== undefined ? { counts: options.counts } : {})
+                }
+            };
+            ensureParentDir(path);
+            writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
+            return next;
+        }
+        // Real phase / step transition: archive the prior current
+        // into history, install the new current.
+        const archived = {
+            ...prev.current,
+            updatedAt: now
+        };
+        const next = {
+            ...prev,
+            updatedAt: now,
+            current: {
+                startedAt: now,
+                updatedAt: now,
+                step: options.step,
+                phase: options.phase,
+                ...(options.verdict !== undefined ? { verdict: options.verdict } : {}),
+                ...(options.counts !== undefined ? { counts: options.counts } : {})
+            },
+            history: [...prev.history, archived]
+        };
+        ensureParentDir(path);
+        writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
+        return next;
+    }
+    // No prior file: this is the first write. Bootstrap a fresh
+    // progress doc. The sessionId is whatever the binding points
+    // at, so cross-session confusion is impossible.
+    const sessionId = getSessionIdCanonical(options.projectRoot) ?? 'unbound';
+    const fresh = {
+        version: 1,
+        sessionId,
+        ...(options.outerSessionId !== undefined ? { outerSessionId: options.outerSessionId } : {}),
+        role: options.role,
+        requestId: options.requestId,
+        startedAt: now,
+        updatedAt: now,
+        current: {
+            startedAt: now,
+            updatedAt: now,
+            step: options.step,
+            phase: options.phase,
+            ...(options.verdict !== undefined ? { verdict: options.verdict } : {}),
+            ...(options.counts !== undefined ? { counts: options.counts } : {})
+        },
+        history: []
+    };
+    ensureParentDir(path);
+    writeFileSync(path, JSON.stringify(fresh, null, 2) + '\n', 'utf8');
+    return fresh;
+}
+/**
+ * Resolve the project root for a CLI invocation: --project
+ * override wins, otherwise the canonical git-root promotion
+ * (so the sub-agent's writes land in the same `.peaks/<sid>/`
+ * the user's manual CLI would use). Re-exports the same
+ * helper peaks workspace init / session rotate already use
+ * for symmetry.
+ */
+export function resolveProgressProjectRoot(override, cwd) {
+    if (override !== undefined)
+        return override;
+    return findProjectRoot(cwd) ?? cwd;
+}
+/**
+ * Compute the absolute path to the progress file for a given
+ * project root, for callers that need to display / fs.watch it
+ * (the watch banner, the auto-spawn helper, the close command).
+ * This MUST agree with `progressPath` — the read/write helpers
+ * resolve through `progressPath` and use the session sub-directory,
+ * so the displayed path does too. Without this agreement the
+ * watch banner would point at a path the file is never written
+ * to, and the user would `cat` an empty file.
+ */
+export function subAgentProgressPath(projectRoot) {
+    return progressPath(resolve(projectRoot));
+}
+/**
+ * Compute the absolute path to the spawn record for a given
+ * project root. Exported so `peaks progress close` (and the
+ * start command's success payload) can advertise the on-disk
+ * location without re-deriving the session sub-directory.
+ */
+export function subAgentSpawnPath(projectRoot) {
+    const sessionId = getSessionIdCanonical(projectRoot);
+    const subDir = sessionId ?? 'unbound';
+    return join(projectRoot, '.peaks', subDir, SPAWN_REL_PATH);
+}
+function spawnRecordPath(projectRoot) {
+    const sessionId = getSessionIdCanonical(projectRoot);
+    const subDir = sessionId ?? 'unbound';
+    return join(projectRoot, '.peaks', subDir, SPAWN_REL_PATH);
+}
+export function writeSpawnRecord(options) {
+    const sessionId = getSessionIdCanonical(options.projectRoot);
+    if (sessionId === null)
+        return null;
+    const now = nowIso();
+    const record = {
+        version: 1,
+        sessionId,
+        pid: options.pid,
+        platform: options.platform,
+        command: options.command,
+        args: options.args,
+        spawnedAt: now,
+        ...(options.reason !== undefined ? { reason: options.reason } : {}),
+        windowTitle: options.windowTitle
+    };
+    const path = spawnRecordPath(options.projectRoot);
+    ensureParentDir(path);
+    writeFileSync(path, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return record;
+}
+export function readSpawnRecord(projectRoot) {
+    const sessionId = getSessionIdCanonical(projectRoot);
+    if (sessionId === null)
+        return { ok: false, reason: 'no-binding' };
+    const path = spawnRecordPath(projectRoot);
+    if (!existsSync(path))
+        return { ok: false, reason: 'no-spawn-record' };
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        if (data.version !== 1 || typeof data.pid !== 'number') {
+            return { ok: false, reason: 'invalid-json' };
+        }
+        return { ok: true, data, path };
+    }
+    catch {
+        return { ok: false, reason: 'invalid-json' };
+    }
+}
+export function clearSpawnRecord(projectRoot) {
+    const path = spawnRecordPath(projectRoot);
+    if (!existsSync(path))
+        return false;
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const PHASES_THAT_AUTO_CLOSE = new Set([
+    'finished',
+    'failed'
+]);
+/**
+ * True if a transition into the given phase should auto-close
+ * the spawned watch window. `finished` and `failed` both
+ * indicate the sub-agent is done; a `blocked` verdict on a
+ * `finished` step is intentionally NOT a close trigger
+ * because a blocked slice usually means the user needs to
+ * read the watch output before deciding what to do. The CLI
+ * layer reads `data.current.phase`, not the verdict, so this
+ * helper is the only close-decision source of truth.
+ */
+export function phaseAutoClosesSpawn(phase) {
+    return PHASES_THAT_AUTO_CLOSE.has(phase);
+}

package/dist/src/services/scan/libraries-service.d.ts

@@ -0,0 +1,24 @@
+import type { LibraryReport } from './libraries-types.js';
+export type ScanLibrariesOptions = {
+    projectRoot: string;
+};
+/**
+ * Parse the major version from a semver-ish spec.
+ *
+ * Handles the common shapes:
+ *   "^5.18.0"      → 5
+ *   "~1.2.3"       → 1
+ *   "1.2.3"        → 1
+ *   ">=1.0.0"      → 1
+ *   "5"            → 5
+ *   "5.x"          → 5
+ *
+ * Returns null for non-semver specs that the LLM should not assume a
+ * major for:
+ *   "workspace:*"  → null
+ *   "file:../..."   → null
+ *   "git+https..." → null
+ *   "npm:@scope/x@1" → 1 (alias spec, we extract what we can)
+ */
+export declare function parseMajorVersion(spec: string): number | null;
+export declare function scanLibraries(options: ScanLibrariesOptions): Promise<LibraryReport>;