peaks-cli 1.2.7 → 1.2.9

package/dist/src/cli/commands/progress-commands.js

@@ -0,0 +1,348 @@
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+import chalk from 'chalk';
+import ora from 'ora';
+import { clearSpawnRecord, phaseAutoClosesSpawn, readSpawnRecord, readSubAgentProgress, resolveProgressProjectRoot, subAgentProgressPath, subAgentSpawnPath, writeSpawnRecord, writeSubAgentProgress } from '../../services/progress/progress-service.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { killSpawnedTerminal } from './progress-close-kill.js';
+import { buildStartSpawn } from './progress-start-spawn.js';
+import { WatchRenderer } from './progress-watch-render.js';
+export function registerProgressCommands(program, io) {
+    const progress = program.command('progress').description('Sub-agent progress surfacing (LLM-side step writes, user-side watch, auto-spawn new terminal)');
+    // ─────────────────────────────────────────────────────────────────
+    // peaks progress step
+    // LLM-side: called by the LLM on phase transitions. Near-zero
+    // token cost — one Bash call per phase change. Writes
+    // `.peaks/<sid>/system/subagent-progress.json`. No auto-spawn
+    // here; the LLM invokes `peaks progress start` separately when
+    // the user-visible window needs to open.
+    // ─────────────────────────────────────────────────────────────────
+    addJsonOption(progress
+        .command('step')
+        .description('Record a sub-agent step / phase transition. Idempotent on (step, phase); transitions append to history.')
+        .requiredOption('--request-id <rid>', 'the same <rid> used by peaks request init')
+        .requiredOption('--role <role>', 'rd | qa | ui | sc | prd (the role of the sub-agent calling this)')
+        .requiredOption('--step <text>', 'free-form human-readable step label, e.g. "running test/ut"')
+        .requiredOption('--phase <phase>', 'starting | running | verifying | completing | finished | failed | idle')
+        .option('--verdict <verdict>', 'pass | return-to-rd | blocked (only when phase is finished or failed)')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--reason <text>', 'human-readable reason for the step write, recorded in the response data')).action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : resolveProgressProjectRoot(undefined, process.cwd());
+            const canonical = resolveCanonicalProjectRoot(projectRoot);
+            const data = writeSubAgentProgress({
+                projectRoot: canonical,
+                requestId: options.requestId,
+                role: options.role,
+                step: options.step,
+                phase: options.phase,
+                ...(options.verdict !== undefined ? { verdict: options.verdict } : {}),
+                ...(options.reason !== undefined ? { outerSessionId: options.reason } : {})
+            });
+            printResult(io, ok('progress.step', {
+                projectRoot: canonical,
+                path: subAgentProgressPath(canonical),
+                sessionId: data.sessionId,
+                requestId: data.requestId,
+                role: data.role,
+                phase: data.current.phase,
+                step: data.current.step,
+                startedAt: data.current.startedAt,
+                updatedAt: data.current.updatedAt
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('progress.step', 'PROGRESS_STEP_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and that peaks workspace init has been run for it']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // ─────────────────────────────────────────────────────────────────
+    // peaks progress watch
+    // User-side: run in a separate terminal. 1s poll + ASCII
+    // spinner + elapsed. --once for a single snapshot.
+    // ─────────────────────────────────────────────────────────────────
+    addJsonOption(progress
+        .command('watch')
+        .description('Watch the sub-agent progress file in a loop (1s poll + ASCII spinner). --once for a single snapshot.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--once', 'print a single snapshot and exit (for use in scripts or statusline hooks)', false)
+        .option('--interval-ms <ms>', 'poll interval in milliseconds (default 1000)', (value) => Number.parseInt(value, 10))).action(async (options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : resolveProgressProjectRoot(undefined, process.cwd());
+            const canonical = resolveCanonicalProjectRoot(projectRoot);
+            const intervalMs = options.intervalMs !== undefined && Number.isFinite(options.intervalMs) && options.intervalMs > 0
+                ? options.intervalMs
+                : 1000;
+            if (options.once === true) {
+                const result = readSubAgentProgress({ projectRoot: canonical });
+                if (!result.ok) {
+                    printResult(io, fail('progress.watch', 'NO_PROGRESS_DATA', `No progress file present yet (${result.reason})`, { projectRoot: canonical, path: subAgentProgressPath(canonical) }, ['Run peaks progress step once on the LLM side to bootstrap the file']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                printResult(io, ok('progress.watch.snapshot', {
+                    projectRoot: canonical,
+                    path: result.path,
+                    data: result.data
+                }), options.json);
+                return;
+            }
+            // Long-running watch loop. The render layer lives in
+            // ./progress-watch-render.ts; the watch loop just polls
+            // the file and calls renderer.tick(data, n). The renderer
+            // owns cursor positioning and in-place overwrite so the
+            // output does not grow line by line as it did in the
+            // previous console.log-based implementation.
+            const renderer = new WatchRenderer({
+                projectRoot: canonical,
+                progressFilePath: subAgentProgressPath(canonical)
+            });
+            renderer.start();
+            // Hint line is painted once BELOW the dynamic block, so
+            // it is not erased on each tick. The user sees the
+            // spinner + bar above, the static hint at the bottom.
+            io.stdout(chalk.gray('  press Ctrl-C to stop watching\n'));
+            let tick = 0;
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                const result = readSubAgentProgress({ projectRoot: canonical });
+                const data = result.ok ? result.data : null;
+                renderer.tick(data, tick);
+                tick += 1;
+                // Auto-close: when the sub-agent reaches a terminal
+                // phase (finished or failed per phaseAutoClosesSpawn),
+                // paint the final frame so the user can read the
+                // verdict, then exit. Exiting the watch process makes
+                // most terminal emulators close the window
+                // (Terminal.app / gnome-terminal / konsole all do;
+                // alacritty / kitty keep it). We also clear the
+                // spawn record so a subsequent `peaks progress close`
+                // reports "nothing to close" instead of "closed a
+                // ghost record".
+                //
+                // We deliberately do NOT auto-close on `blocked` —
+                // `blocked` means the user needs to read the watch
+                // output and decide what to do.
+                if (data !== null && phaseAutoClosesSpawn(data.current.phase)) {
+                    renderer.finalize(data);
+                    clearSpawnRecord(canonical);
+                    return;
+                }
+                await new Promise((resolveWait) => setTimeout(resolveWait, intervalMs));
+            }
+        }
+        catch (error) {
+            printResult(io, fail('progress.watch', 'PROGRESS_WATCH_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and that the progress file is readable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // ─────────────────────────────────────────────────────────────────
+    // peaks progress start
+    // The "auto-spawn a new terminal running watch" entry point.
+    // Called by the LLM at the first phase transition of a slice,
+    // once per session. Cross-platform: macOS uses osascript with
+    // Terminal.app; Linux tries gnome-terminal / konsole /
+    // xterm in order; Windows uses `start cmd`. The user can
+    // close the new terminal at any time; re-invoking is a no-op
+    // if a watch is already running in another terminal.
+    // ─────────────────────────────────────────────────────────────────
+    addJsonOption(progress
+        .command('start')
+        .description('Auto-spawn a new terminal running `peaks progress watch` for this project. Called by the LLM at the first phase transition; the user can close the new terminal at any time.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--reason <text>', 'human-readable reason for the auto-spawn, recorded in the response data')).action(async (options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : resolveProgressProjectRoot(undefined, process.cwd());
+            const canonical = resolveCanonicalProjectRoot(projectRoot);
+            const currentPlatform = platform();
+            const peaksBin = process.argv[1] ?? 'peaks';
+            const reasonSuffix = options.reason !== undefined ? ` — ${options.reason}` : '';
+            // Window / tab title shared across platforms. The user
+            // asked for visible "this is peaks-cli" branding so the
+            // spawned terminal is identifiable at a glance; the title
+            // also makes `peaks progress close` self-documenting.
+            const windowTitle = `peaks-cli: sub-agent progress${reasonSuffix}`;
+            const watchCommand = `${peaksBin} progress watch --project "${canonical}"`;
+            // Build the platform-specific spawn command + args. This
+            // is extracted to ./progress-start-spawn.ts so the three
+            // platform branches can be unit-tested without spawning
+            // a real terminal.
+            const spawnSpec = buildStartSpawn({
+                peaksBin,
+                projectRoot: canonical,
+                windowTitle,
+                platform: currentPlatform
+            });
+            if (!spawnSpec.ok) {
+                printResult(io, fail('progress.start', 'UNSUPPORTED_PLATFORM', `Cannot auto-spawn a terminal on platform "${currentPlatform}". Run \`peaks progress watch --project "${canonical}"\` in a new terminal yourself.`, { projectRoot: canonical }, ['macOS / Linux / Windows are supported; other platforms need a manual terminal']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const spawnCommand = spawnSpec.command;
+            const spawnArgs = spawnSpec.args;
+            // Brief ora feedback while the terminal is launching.
+            // Skipped entirely in non-TTY mode (the LLM calls this
+            // from a Bash tool, where ora would just hang on
+            // animation) and in --json mode (where the structured
+            // response is the only signal the caller consumes).
+            const showSpinner = process.stdout.isTTY === true && options.json !== true;
+            const spinner = showSpinner
+                ? ora(`auto-spawning ${spawnCommand}…`).start()
+                : null;
+            try {
+                // spawn() with detached:true + unref() is the documented
+                // Node.js way to start a long-lived child from a CLI
+                // without blocking. We ignore stdio because the spawned
+                // terminal owns the child process group from now on; the
+                // peaks CLI exits and the terminal keeps running.
+                const child = spawn(spawnCommand, spawnArgs, { detached: true, stdio: 'ignore' });
+                child.unref();
+                // Give the spawn a beat to surface EACCES/ENOENT. We do
+                // not await the child (it is intentionally long-lived).
+                await new Promise((resolveSpawn, rejectSpawn) => {
+                    const timer = setTimeout(() => resolveSpawn(), 200);
+                    child.once('error', (spawnError) => {
+                        clearTimeout(timer);
+                        rejectSpawn(spawnError);
+                    });
+                    child.once('spawn', () => {
+                        clearTimeout(timer);
+                        resolveSpawn();
+                    });
+                });
+                if (spinner !== null) {
+                    spinner.succeed(`spawned ${spawnCommand} (new window is opening)`);
+                }
+                // Persist the spawn record so `peaks progress close` (and
+                // the watch-side auto-exit) can find and kill the window
+                // later. We write the record AFTER the spawn fires so a
+                // failed spawn never leaves a stale record behind. The
+                // record is per-session: a session rotation invalidates it
+                // because the new session gets a fresh record path.
+                const spawnRecord = writeSpawnRecord({
+                    projectRoot: canonical,
+                    pid: child.pid ?? 0,
+                    platform: currentPlatform,
+                    command: spawnCommand,
+                    args: spawnArgs,
+                    ...(options.reason !== undefined ? { reason: options.reason } : {}),
+                    windowTitle
+                });
+                printResult(io, ok('progress.start', {
+                    projectRoot: canonical,
+                    platform: currentPlatform,
+                    spawned: `${spawnCommand} ${spawnArgs.join(' ')}`,
+                    watchCommand,
+                    ...(options.reason !== undefined ? { reason: options.reason } : {}),
+                    ...(spawnRecord === null
+                        ? {
+                            spawnRecord: null,
+                            warning: 'no peaks session binding — `peaks progress close` will not be able to find this window. Close it manually.'
+                        }
+                        : {
+                            spawnRecord: {
+                                path: subAgentSpawnPath(canonical),
+                                windowTitle: spawnRecord.windowTitle,
+                                spawnedAt: spawnRecord.spawnedAt
+                            }
+                        }),
+                    autoClose: 'the watch window will close itself when the sub-agent hits `finished` or `failed`',
+                    note: 'A new terminal window is opening in the background. It will run `peaks progress watch` and refresh every second. Close the new terminal at any time, or run `peaks progress close` to programmatically close it.'
+                }), options.json);
+                return;
+            }
+            catch (spawnError) {
+                if (spinner !== null) {
+                    spinner.fail(`auto-spawn failed: ${getErrorMessage(spawnError)}`);
+                }
+                printResult(io, fail('progress.start', 'TERMINAL_SPAWN_FAILED', `Auto-spawn failed: ${getErrorMessage(spawnError)}. Run \`peaks progress watch --project "${canonical}"\` in a new terminal yourself.`, { projectRoot: canonical, platform: currentPlatform, attempted: `${spawnCommand} ${spawnArgs.join(' ')}` }, ['Verify a terminal emulator is installed (e.g. gnome-terminal / Terminal.app)']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('progress.start', 'PROGRESS_START_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and a terminal emulator is available']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // ─────────────────────────────────────────────────────────────────
+    // peaks progress close
+    // Manual escape hatch: kill the spawned watch window and
+    // clear the spawn record. Idempotent — re-running is a no-op
+    // once the record is gone, and the response distinguishes
+    // "nothing to close" from "closed it" so callers / hooks can
+    // tell the difference. The close is best-effort: if the
+    // watch process has already exited but the record is stale,
+    // we still clear the record.
+    // ─────────────────────────────────────────────────────────────────
+    addJsonOption(progress
+        .command('close')
+        .description('Close the spawned `peaks progress watch` window for this session. Idempotent: re-running when no window is open is a no-op.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action(async (options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : resolveProgressProjectRoot(undefined, process.cwd());
+            const canonical = resolveCanonicalProjectRoot(projectRoot);
+            const result = readSpawnRecord(canonical);
+            if (!result.ok) {
+                // Differentiate the failure modes so callers can decide
+                // whether to surface a warning. no-binding means peaks
+                // workspace init has not been run; no-spawn-record /
+                // invalid-json means there is nothing to close (start
+                // has not been called this session, or the window
+                // already auto-closed and the record was cleared).
+                if (result.reason === 'no-binding') {
+                    printResult(io, fail('progress.close', 'NO_BINDING', 'no peaks session binding — nothing to close', { projectRoot: canonical, path: subAgentSpawnPath(canonical) }, ['Run peaks workspace init for this project first']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                printResult(io, ok('progress.close', {
+                    projectRoot: canonical,
+                    closed: false,
+                    reason: result.reason,
+                    note: 'no spawn record found — nothing to close (start has not been called this session, or the window has already auto-closed)'
+                }), options.json);
+                return;
+            }
+            const record = result.data;
+            // Best-effort close. We try three signals in order:
+            //   (1) `pkill -f <watch command>` — the long-lived watch
+            //       process. Killing it makes the terminal emulator
+            //       close on most platforms (Terminal.app, gnome-
+            //       terminal, konsole) but not all (alacritty, kitty
+            //       keep the window).
+            //   (2) macOS: AppleScript to close the Terminal.app
+            //       window with the matching custom title.
+            //   (3) Linux: wmctrl/xdotool by WM class as a fallback.
+            //       Windows: taskkill /F /FI on the window title.
+            // We never throw from the close path — a failed close is
+            // a UX paper cut, not a correctness bug. The record is
+            // still cleared so the next `progress start` does not
+            // see a stale record.
+            const closeResult = await killSpawnedTerminal(record, canonical, platform());
+            clearSpawnRecord(canonical);
+            printResult(io, ok('progress.close', {
+                projectRoot: canonical,
+                closed: closeResult.signals.length > 0,
+                signals: closeResult.signals,
+                warnings: closeResult.warnings,
+                windowTitle: record.windowTitle,
+                spawnedAt: record.spawnedAt,
+                note: 'spawn record cleared. The next `peaks progress start` will spawn a fresh window.'
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('progress.close', 'PROGRESS_CLOSE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and that peaks workspace init has been run for it']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/progress-start-spawn.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure platform-specific spawn-args construction for
+ * `peaks progress start`. Extracted out of the commander
+ * action handler so the three platform branches (darwin /
+ * linux / win32) can be unit-tested without spawning real
+ * terminals.
+ *
+ * The CLI action calls `buildStartSpawn` once per start
+ * attempt and feeds the returned `{ command, args }` pair to
+ * `child_process.spawn(..., { detached: true, stdio: 'ignore' })`.
+ *
+ * Cross-platform strategy (see progress-commands.ts for the
+ * full design notes):
+ *
+ *   - macOS:  `osascript -e 'tell application "Terminal" to
+ *              do script "<shell>"'`. The shell command sets
+ *              the title via the OSC 0 escape (printf), runs
+ *              the brand banner, then exec's the watch.
+ *   - Linux:  First existing terminal emulator in
+ *              { gnome-terminal, konsole, xfce4-terminal,
+ *              tilix, alacritty, kitty }, with per-emulator
+ *              flag translation. The shell inside also sets
+ *              the title via OSC 0 (emulator --title is
+ *              best-effort only — the shell overrides it).
+ *   - Win32:  `cmd /c start "<title>" cmd /k <shell>`. The
+ *              shell uses the `title` builtin (cmd.exe
+ *              builtin) to re-anchor the title before the
+ *              watch runs, because cmd.exe overrides the
+ *              start-title with the running command name.
+ *
+ * The function never throws on unsupported platforms; it
+ * returns a discriminated `unsupported` result so the caller
+ * can surface a clean error envelope.
+ */
+export type StartSpawnSpec = {
+    ok: true;
+    command: string;
+    args: string[];
+} | {
+    ok: false;
+    unsupported: true;
+};
+export type BuildStartSpawnOptions = {
+    /** The peaks binary path the spawned shell will invoke. */
+    peaksBin: string;
+    /** Canonical project root (used to build the watch command). */
+    projectRoot: string;
+    /** Window/tab title shared across platforms. */
+    windowTitle: string;
+    /** Current platform (from `os.platform()`). */
+    platform: NodeJS.Platform;
+    /**
+     * Override for terminal detection on Linux. Defaults to
+     * `existsSync('/usr/bin/<name>')` for each candidate. Tests
+     * pass a stub to make the linux branch deterministic.
+     */
+    linuxTerminalExists?: (name: string) => boolean;
+};
+export declare function buildStartSpawn(options: BuildStartSpawnOptions): StartSpawnSpec;

package/dist/src/cli/commands/progress-start-spawn.js

@@ -0,0 +1,114 @@
+/**
+ * Pure platform-specific spawn-args construction for
+ * `peaks progress start`. Extracted out of the commander
+ * action handler so the three platform branches (darwin /
+ * linux / win32) can be unit-tested without spawning real
+ * terminals.
+ *
+ * The CLI action calls `buildStartSpawn` once per start
+ * attempt and feeds the returned `{ command, args }` pair to
+ * `child_process.spawn(..., { detached: true, stdio: 'ignore' })`.
+ *
+ * Cross-platform strategy (see progress-commands.ts for the
+ * full design notes):
+ *
+ *   - macOS:  `osascript -e 'tell application "Terminal" to
+ *              do script "<shell>"'`. The shell command sets
+ *              the title via the OSC 0 escape (printf), runs
+ *              the brand banner, then exec's the watch.
+ *   - Linux:  First existing terminal emulator in
+ *              { gnome-terminal, konsole, xfce4-terminal,
+ *              tilix, alacritty, kitty }, with per-emulator
+ *              flag translation. The shell inside also sets
+ *              the title via OSC 0 (emulator --title is
+ *              best-effort only — the shell overrides it).
+ *   - Win32:  `cmd /c start "<title>" cmd /k <shell>`. The
+ *              shell uses the `title` builtin (cmd.exe
+ *              builtin) to re-anchor the title before the
+ *              watch runs, because cmd.exe overrides the
+ *              start-title with the running command name.
+ *
+ * The function never throws on unsupported platforms; it
+ * returns a discriminated `unsupported` result so the caller
+ * can surface a clean error envelope.
+ */
+import { existsSync } from 'node:fs';
+/** Brand banner the user sees in the spawned shell. */
+const BANNER = 'echo "peaks-cli — sub-agent progress"';
+/**
+ * Build the POSIX OSC 0 title escape. The single-quote
+ * escape is bash's `'\''` for embedding a single quote in a
+ * single-quoted string; we need it because windowTitle may
+ * contain user-provided text (the `--reason` argument).
+ */
+function buildPosixTitleCmd(windowTitle) {
+    const escaped = windowTitle.replaceAll("'", "'\\''");
+    return `printf '\\033]0;${escaped}\\007'`;
+}
+/** cmd.exe `title` builtin call. Quoting is intentionally bare. */
+function buildWinTitleCmd(windowTitle) {
+    return `title ${windowTitle}`;
+}
+/** Shared helper: the shell command that runs the watch. */
+function buildWatchCommand(peaksBin, projectRoot) {
+    return `${peaksBin} progress watch --project "${projectRoot}"`;
+}
+export function buildStartSpawn(options) {
+    const { peaksBin, projectRoot, windowTitle, platform: currentPlatform } = options;
+    const watchCommand = buildWatchCommand(peaksBin, projectRoot);
+    const posixTitleCmd = buildPosixTitleCmd(windowTitle);
+    const winTitleCmd = buildWinTitleCmd(windowTitle);
+    if (currentPlatform === 'darwin') {
+        const innerShell = `${posixTitleCmd}; ${BANNER}; ${watchCommand}`;
+        const escapedInner = innerShell.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+        return {
+            ok: true,
+            command: 'osascript',
+            args: [
+                '-e',
+                `tell application "Terminal" to do script "${escapedInner}"`,
+                '-e',
+                'tell application "Terminal" to activate'
+            ]
+        };
+    }
+    if (currentPlatform === 'linux') {
+        const exists = options.linuxTerminalExists ?? ((name) => existsSync(`/usr/bin/${name}`));
+        const candidates = ['gnome-terminal', 'konsole', 'xfce4-terminal', 'tilix', 'alacritty', 'kitty'];
+        const terminal = candidates.find((c) => exists(c)) ?? candidates[0];
+        const titleArg = ['--title', windowTitle];
+        const bannerShell = `bash -c '${posixTitleCmd}; ${BANNER}; exec ${watchCommand}'`;
+        if (terminal === 'alacritty' || terminal === 'kitty') {
+            return {
+                ok: true,
+                command: terminal,
+                args: ['--class', 'peaks-cli-progress', ...titleArg, '-e', bannerShell]
+            };
+        }
+        if (terminal === 'gnome-terminal' || terminal === 'tilix' || terminal === 'xfce4-terminal') {
+            return {
+                ok: true,
+                command: terminal,
+                args: [...titleArg, '--', '/bin/bash', '-lc', bannerShell]
+            };
+        }
+        if (terminal === 'konsole') {
+            return {
+                ok: true,
+                command: terminal,
+                args: ['--title', windowTitle, '--p', 'tabtitle', windowTitle, '-e', bannerShell]
+            };
+        }
+        // xterm / fallback: no --title support; bannerShell only.
+        return { ok: true, command: terminal, args: ['-e', bannerShell] };
+    }
+    if (currentPlatform === 'win32') {
+        const bannerCmd = `${winTitleCmd} && echo peaks-cli --- sub-agent progress && ${watchCommand}`;
+        return {
+            ok: true,
+            command: 'cmd',
+            args: ['/c', 'start', `"${windowTitle}"`, 'cmd', '/k', bannerCmd]
+        };
+    }
+    return { ok: false, unsupported: true };
+}

package/dist/src/cli/commands/progress-watch-render.d.ts

@@ -0,0 +1,80 @@
+/**
+ * In-place progress renderer for `peaks progress watch`.
+ *
+ * Goals (in order of importance):
+ *   1. **In-place overwrite.** Every tick the dynamic rows
+ *      (status line + progress bar) get rewritten, NOT
+ *      appended. We bypass `io.stdout` (which is
+ *      `console.log` and adds a trailing `\n` per call) and
+ *      write directly to `process.stdout`. The cursor-up
+ *      and erase-line escapes are the same ones terminal-kit
+ *      emits; we do not need a terminal-kit dependency for
+ *      them.
+ *   2. **Clear PEAKS-CLI branding.** A static 3-line header
+ *      with the brand bar, the project root, and the
+ *      progress-file path is painted once. The user always
+ *      sees what they are looking at, even after the
+ *      watch loop has overwritten the dynamic rows a
+ *      thousand times.
+ *   3. **Graceful degrade.** When stdout is not a TTY
+ *      (CI / pipe / `--json`), we fall back to a single
+ *      static snapshot per tick (no cursor moves, no
+ *      SGR colour) and a single newline. This keeps the
+ *      tool scriptable without dropping into a wall of
+ *      escape codes.
+ *
+ * Token-cost note: this module is rendered to the user's
+ * terminal, never into LLM context. The watch side has
+ * zero token cost.
+ */
+import type { SubAgentProgress } from '../../services/progress/progress-service.js';
+export type WatchRendererOptions = {
+    projectRoot: string;
+    progressFilePath: string;
+};
+export declare class WatchRenderer {
+    private readonly projectRoot;
+    private readonly progressFilePath;
+    private readonly width;
+    private readonly isTty;
+    private hasRenderedDynamic;
+    constructor(options: WatchRendererOptions);
+    /**
+     * Paint the static header once at the top of the watch
+     * (the PEAKS-CLI wordmark, separator, project, path). Then
+     * paint the dynamic rows for the first tick. From here on
+     * the dynamic rows are the only thing we touch.
+     */
+    start(): void;
+    /**
+     * Repaint the 2 dynamic rows in place. First call moves
+     * the cursor up N rows from the bottom of the previously
+     * painted block; subsequent calls do the same.
+     */
+    tick(data: SubAgentProgress | null, tickCount: number): void;
+    private paintDynamicOnce;
+    /**
+     * Paint a final 2-line verdict + a farewell line below the
+     * dashboard, then return. The cursor stays at the bottom
+     * of the farewell so the user's shell prompt lands on the
+     * next row.
+     */
+    finalize(data: SubAgentProgress): void;
+    /**
+     * Force a non-ANSI snapshot of the current state, used by
+     * the `--once` mode and for fallback when stdout is not a
+     * TTY. Does NOT touch the cursor state — safe to call from
+     * any context.
+     */
+    static snapshot(data: SubAgentProgress | null): {
+        status: string;
+        bar: string;
+    };
+}
+/**
+ * Strip ANSI escapes from a string. Used for visible-length
+ * accounting; not for re-painting.
+ */
+export declare function stripAnsi(input: string): string;
+/** Reset terminal SGR — used on early-return error paths. */
+export declare function resetTerminal(): void;