peaks-cli 1.3.4 → 1.3.5

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

@@ -1,34 +1,31 @@
 /**
- * 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/_sub_agents/<sid>/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.
+ * Sub-agent progress file 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/_sub_agents/<sid>/subagent-progress.json`. The dispatch +
+ * heartbeat flow (slice #009 + #010) reads this file as the source
+ * of truth for "is this sub-agent still alive?".
  *
  * 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.
+ *   - The dispatch side polls the file via `peaks sub-agent
+ *     heartbeat`, not the LLM. Zero token cost.
  *
- * 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.
+ * Slice #014: the legacy `peaks progress start|watch|close` auto-spawn
+ * surface is DELETED. With dispatch + heartbeat (slice #009 + #010), the
+ * same sub-agent now runs in the same IDE/terminal as the main loop, so
+ * a separate watch window is dead weight. The only remaining consumer
+ * of this module is the `peaks progress step` write path + the
+ * dispatcher's read-back of the progress file.
  *
  * 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).
+ * IPC. The dispatch-side consumption is in
+ * `src/services/dispatch/sub-agent-dispatcher.ts` and reads the
+ * progress file via `subAgentProgressPath`.
  */
 export type SubAgentProgressPhase = 'starting' | 'running' | 'verifying' | 'completing' | 'finished' | 'failed' | 'idle';
 export type SubAgentProgressStep = {
@@ -118,88 +115,11 @@ export declare function resolveProgressProjectRoot(override: string | undefined,
 /**
  * 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.
+ * (the dispatcher's read-back, the LLM-side step write banner,
+ * etc.). 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 dispatcher's read-back would point at a path
+ * the writer never touches.
  */
 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;
-/**
- * Idempotency check for the `peaks progress start` CLI (and the Task-tool
- * PreToolUse hook that fires it on every Task call). Returns `true` when a
- * recent spawn record exists for this project's session, meaning a watch
- * window was opened within the last `ttlMs` milliseconds. The LLM-side
- * caller treats `true` as "no-op — a watch is already running somewhere".
- *
- * Why TTL instead of pid liveness: the spawned terminal's pid is the
- * osascript/gnome-terminal process, which exits as soon as it spawns the
- * nested shell. Checking pid liveness gives false negatives (the process
- * is gone by design). The spawn record is the canonical "watch was opened
- * for this session" marker. After `ttlMs` the record is treated as stale
- * (e.g. the user closed the window long ago) and a fresh start proceeds.
- *
- * `ttlMs` defaults to 5 minutes — long enough to cover a typical sub-agent
- * slice (RD parallel fan-out + QA verdict), short enough that a user who
- * closed the window gets a fresh one on the next Task call.
- */
-export type RecentSpawnCheck = {
-    recent: boolean;
-    reason: 'recent-spawn' | 'no-spawn-record' | 'no-binding' | 'invalid-json' | 'stale-spawn' | 'process-dead';
-    /** When reason is 'recent-spawn' or 'stale-spawn', the spawn record. */
-    record?: ProgressSpawnRecord;
-    ageMs?: number;
-};
-export declare function isRecentSpawn(projectRoot: string, now?: () => number, ttlMs?: number): RecentSpawnCheck;
-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

@@ -1,36 +1,33 @@
 /**
- * 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/_sub_agents/<sid>/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.
+ * Sub-agent progress file 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/_sub_agents/<sid>/subagent-progress.json`. The dispatch +
+ * heartbeat flow (slice #009 + #010) reads this file as the source
+ * of truth for "is this sub-agent still alive?".
  *
  * 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.
+ *   - The dispatch side polls the file via `peaks sub-agent
+ *     heartbeat`, not the LLM. Zero token cost.
  *
- * 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.
+ * Slice #014: the legacy `peaks progress start|watch|close` auto-spawn
+ * surface is DELETED. With dispatch + heartbeat (slice #009 + #010), the
+ * same sub-agent now runs in the same IDE/terminal as the main loop, so
+ * a separate watch window is dead weight. The only remaining consumer
+ * of this module is the `peaks progress step` write path + the
+ * dispatcher's read-back of the progress file.
  *
  * 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).
+ * IPC. The dispatch-side consumption is in
+ * `src/services/dispatch/sub-agent-dispatcher.ts` and reads the
+ * progress file via `subAgentProgressPath`.
  */
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, 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';
@@ -43,7 +40,6 @@ import { findProjectRoot } from '../config/config-safety.js';
 // --apply` (see `migrateSubAgentState` in reconcile-service.ts).
 const SUB_AGENTS_DIR = '_sub_agents';
 const PROGRESS_FILE_NAME = 'subagent-progress.json';
-const SPAWN_FILE_NAME = 'progress-spawn.json';
 function progressPath(projectRoot) {
     // The progress file lives at `.peaks/_sub_agents/<sid>/subagent-progress.json`.
     // The leading `_sub_agents/` is a meta-classification (mirrors `_runtime/`,
@@ -184,122 +180,13 @@ export function resolveProgressProjectRoot(override, 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.
+ * (the dispatcher's read-back, the LLM-side step write banner,
+ * etc.). 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 dispatcher's read-back would point at a path
+ * the writer never touches.
  */
 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', SUB_AGENTS_DIR, subDir, SPAWN_FILE_NAME);
-}
-function spawnRecordPath(projectRoot) {
-    const sessionId = getSessionIdCanonical(projectRoot);
-    const subDir = sessionId ?? 'unbound';
-    return join(projectRoot, '.peaks', SUB_AGENTS_DIR, subDir, SPAWN_FILE_NAME);
-}
-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 isRecentSpawn(projectRoot, now = Date.now, ttlMs = 5 * 60 * 1000) {
-    const result = readSpawnRecord(projectRoot);
-    if (!result.ok) {
-        return { recent: false, reason: result.reason };
-    }
-    const record = result.data;
-    const spawnedMs = Date.parse(record.spawnedAt);
-    if (Number.isNaN(spawnedMs)) {
-        // Treat unparseable timestamps as a stale record so the next start
-        // proceeds normally. This is the conservative choice — the alternative
-        // (treating unparseable as "always recent") would block legitimate
-        // re-spawns forever.
-        return { recent: false, reason: 'stale-spawn', record };
-    }
-    const ageMs = now() - spawnedMs;
-    if (ageMs < 0) {
-        // Clock skew or future-dated record: trust the record as "recent" so
-        // we do not double-spawn. Same conservative default as a 0-age record.
-        return { recent: true, reason: 'recent-spawn', record, ageMs: 0 };
-    }
-    if (ageMs >= ttlMs) {
-        return { recent: false, reason: 'stale-spawn', record, ageMs };
-    }
-    return { recent: true, reason: 'recent-spawn', record, ageMs };
-}
-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/file-size-scan.d.ts

@@ -7,6 +7,10 @@ export type FileSizeScanResult = {
     ok: boolean;
     threshold: number;
     checkedFiles: number;
+    /** Files that appeared in `git diff` but no longer exist on disk (e.g.
+     *  deleted in the working tree). Pre-#015 the scan crashed on these via
+     *  ENOENT; now they are reported here as informational data. */
+    deletedFiles: string[];
     violations: FileSizeViolation[];
 };
 export type FileSizeScanOptions = {

package/dist/src/services/scan/file-size-scan.js

@@ -1,10 +1,14 @@
 import { execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 export const DEFAULT_FILE_SIZE_THRESHOLD = 800;
 function getChangedFiles(projectRoot, baseRef) {
     try {
-        const trackedRaw = execFileSync('git', ['-C', projectRoot, 'diff', '--name-only', baseRef], { encoding: 'utf8' });
+        // --diff-filter=AM keeps only Added + Modified entries. Deleted files
+        // (--diff-filter=D) are intentionally excluded: they have no on-disk
+        // body to count, and a refactor that deletes large files is exactly
+        // when the gate should NOT block. Slice #015 fix.
+        const trackedRaw = execFileSync('git', ['-C', projectRoot, 'diff', '--name-only', '--diff-filter=AM', baseRef], { encoding: 'utf8' });
         const tracked = trackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
         const untrackedRaw = execFileSync('git', ['-C', projectRoot, 'ls-files', '--others', '--exclude-standard'], { encoding: 'utf8' });
         const untracked = untrackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
@@ -23,8 +27,32 @@ export function scanFileSize(options) {
     const threshold = options.threshold ?? DEFAULT_FILE_SIZE_THRESHOLD;
     const files = getChangedFiles(options.projectRoot, baseRef);
     const violations = [];
+    const deletedFiles = [];
+    let checkedFiles = 0;
     for (const file of files) {
         const absolute = join(options.projectRoot, file);
+        // Pre-#015: readFileSync threw ENOENT for files that appear in
+        // `git diff --name-only` but no longer exist on disk (e.g. a refactor
+        // that deletes source files). That aborted the entire
+        // `peaks request transition rd → implemented` flow with
+        // `code: PREREQUISITES_MISSING`. Now we skip missing paths — a
+        // deleted file has no lines to count. Belt-and-braces: the
+        // `getChangedFiles` filter above already excludes `--diff-filter=D`,
+        // but a manually-passed `baseRef` (tests) or a path that was
+        // untracked-then-deleted still flows through here, so the
+        // existsSync guard stays as a second line of defense.
+        if (!existsSync(absolute)) {
+            try {
+                const st = statSync(absolute);
+                if (!st.isFile())
+                    continue;
+            }
+            catch {
+                deletedFiles.push(file);
+                continue;
+            }
+        }
+        checkedFiles += 1;
         const lines = countLines(absolute);
         if (lines > threshold) {
             violations.push({ file, lines });
@@ -33,7 +61,8 @@ export function scanFileSize(options) {
     return {
         ok: violations.length === 0,
         threshold,
-        checkedFiles: files.length,
+        checkedFiles,
+        deletedFiles,
         violations
     };
 }

package/dist/src/services/skills/hooks-settings-service.d.ts

@@ -38,15 +38,36 @@ export type HookInstallOptions = {
      * Throws if the IDE is not registered in the adapter registry.
      */
     readonly ide?: IdeId;
+    /**
+     * Slice #013 (bugfix — peaks hooks install --no-progress): when `true`,
+     * skip emitting the progress-start PreToolUse hook entry while still
+     * installing the gate-enforce entry. The progress-start hook auto-spawns
+     * a new terminal running `peaks progress watch`; with dispatch +
+     * heartbeat (slice #009 + #010) that auto-spawn is dead weight. Default
+     * `false` preserves the pre-slice install shape (both entries). The
+     * sentinel-based install is idempotent: re-running with `skipProgress:
+     * true` over a settings.json that previously had the progress entry
+     * installed will remove that entry. `uninstall` honors the same flag
+     * so it can find and remove both entries when both are present and
+     * only the gate-enforce entry when only the gate-enforce is present.
+     *
+     * Slice #014 (refactor — full removal of legacy progress-start surface):
+     * the field is preserved for API stability, but the underlying
+     * install only ever emits the gate-enforce entry. The progress-start
+     * entry is no longer installed regardless of this flag's value. The
+     * legacy `peaks progress start|watch|close` CLI surface is gone
+     * (replaced by `peaks sub-agent dispatch|heartbeat|share`); the hook
+     * entry would have been pointing at a `peaks progress start` that no
+     * longer exists. The sentinel `peaks progress start` constant is still
+     * exported (some tests + back-compat reads rely on it) but no new
+     * hook entries use it.
+     */
+    readonly skipProgress?: boolean;
 };
 /** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
 export declare const HOOK_ENFORCE_SENTINEL = "peaks gate enforce";
-/** Sentinel substring identifying a peaks-managed sub-agent-progress hook entry. */
-export declare const HOOK_PROGRESS_SENTINEL = "peaks progress start";
 /** Default (claude-code) hook command — kept as a stable export for tests. */
 export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\"";
-/** Default (claude-code) progress command — kept as a stable export for tests. */
-export declare const HOOK_PROGRESS_COMMAND = "peaks progress start --project \"${CLAUDE_PROJECT_DIR}\" --reason \"auto-spawn for sub-agent Task\" --quiet";
 export type HookInstallPlan = {
     scope: HookScope;
     settingsPath: string;
@@ -70,6 +91,37 @@ export type HookStatus = {
     exists: boolean;
     installed: boolean;
 };
+/**
+ * Slice #014: read the *actually-installed* peaks-managed hook entries
+ * from a settings object. Replaces the pre-#014 `listInstalledEntriesForIde`
+ * helper in `hooks-commands.ts`, which returned the IDE-EXPECTED list
+ * (a hardcoded 2-entry array per adapter) rather than what was on disk.
+ * That bug surfaced when slice #013's local cleanup installed
+ * `peaks hooks install --no-progress` (gate-enforce only), but the
+ * status command still reported `entries: [Bash, Task]` because the
+ * helper didn't read the file.
+ *
+ * The new helper:
+ *   1. reads each `hooks.<event>` array,
+ *   2. filters to entries that are peaks-managed for the given IDE
+ *      (matches the legacy sentinel set: gate-enforce + the no-longer-
+ *      installed progress-start),
+ *   3. returns one `{ matcher, sentinel }` row per entry, taking the
+ *      FIRST matching sentinel per entry (entries have a single command
+ *      handler in practice, but the loop tolerates multi-handler
+ *      entries by taking the first match).
+ *
+ * Pre-#014 settings.json files that have a stale progress-start entry
+ * will see it surface in the result. This is intentional: the status
+ * command is the user's tool for "what is on disk right now", and
+ * surfacing a stale entry is the only way the user can know to run
+ * `peaks hooks install` (which now strips it) or `peaks hooks
+ * uninstall` (which removes it).
+ */
+export declare function readInstalledEntriesFromSettings(settings: Record<string, unknown>, ide: IdeId): ReadonlyArray<{
+    matcher: string;
+    sentinel: string;
+}>;
 /** A typed descriptor for a single peaks-managed hook entry. */
 export type PeaksHookEntry = {
     sentinel: string;
@@ -77,7 +129,7 @@ export type PeaksHookEntry = {
     command: string;
     event: string;
 };
-/** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. */
+/** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. Slice #014: only the gate-enforce entry. */
 export declare const PEAKS_HOOK_ENTRIES: ReadonlyArray<PeaksHookEntry>;
 export declare function planHookInstall(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookInstallPlan;
 export declare function applyHookInstall(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookInstallResult;