peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/commands/perf-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerPerfCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,41 @@
+import { executePerfBaselineInit, resolveProjectRootFromCwd } from '../../services/perf/perf-baseline-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerPerfCommands(program, io) {
+    const perf = program.command('perf').description('Manage performance baseline scaffolding for the RD stage');
+    addJsonOption(perf
+        .command('baseline')
+        .description('Scaffold .peaks/_runtime/<sid>/rd/perf-baseline.md so the RD can record the slice\'s perf numbers in a stable place that QA Gate A4 can diff against. Default dry-run; pass --apply to write.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--apply', 'write the scaffold into the target project', false)
+        .option('--reason <text>', 'human-readable reason for the baseline (recorded in the response data)')).action(async (options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : resolveProjectRootFromCwd(process.cwd());
+            const result = await executePerfBaselineInit({
+                projectRoot,
+                apply: options.apply === true,
+                ...(options.reason !== undefined ? { reason: options.reason } : {})
+            });
+            const nextActions = [];
+            if (result.sessionId === null) {
+                nextActions.push('No peaks session is bound for this project yet. Run `peaks workspace init` (or any peaks skill) first so a session directory exists.');
+            }
+            else if (result.alreadyInitialized) {
+                nextActions.push(`perf-baseline.md already exists; no files were written. Re-run only after a re-measurement if you intend to overwrite.`);
+            }
+            else if (!result.apply) {
+                nextActions.push('Re-run with --apply to write the scaffold.');
+            }
+            else {
+                nextActions.push('Open the file and fill in the Results table — that is the input QA Gate A4 will diff against.');
+            }
+            printResult(io, ok('perf.baseline', result, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('perf.baseline', 'PERF_BASELINE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/playwright-commands.d.ts

@@ -0,0 +1,95 @@
+/**
+ * `peaks playwright start | ls | stop` — slice 2.5.0 sub-fix C (Prob 3).
+ *
+ * Multi-terminal resolution for the Playwright MCP. When two or more
+ * terminals / IDE sessions each spawn a `playwright` MCP server, they
+ * fight over the same default port (8931) and the same user data
+ * dir. This command:
+ *
+ *   1. `peaks playwright start [--port N] [--browser <chromium|firefox|webkit>]`
+ *      Allocates a unique port (default 8931; walks 8931→8949 if busy),
+ *      spawns `npx playwright-mcp@latest` with the chosen port, and
+ *      writes a session file at
+ *      `<projectRoot>/.peaks/_runtime/playwright-sessions/<terminal-id>.json`
+ *      with `{ port, userDataDir, startedAt, pid }`.
+ *
+ *   2. `peaks playwright ls` — lists all running sessions (reads
+ *      `.peaks/_runtime/playwright-sessions/*.json`).
+ *
+ *   3. `peaks playwright stop [--terminal <id>]` — best-effort kills
+ *      the server process and removes the session file.
+ *
+ * Terminal ID derivation (R4):
+ *   1. process.env.TERM_SESSION_ID (macOS Terminal / iTerm2)
+ *   2. process.env.WT_SESSION (Windows Terminal)
+ *   3. hash(process.ppid + process.env.SSH_TTY || 'no-tty')
+ *
+ * The CLI does NOT bundle `playwright-mcp`; it shells out to
+ * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle
+ * orchestrator, not the install medium.
+ */
+import { spawn } from 'node:child_process';
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare const DEFAULT_PORT = 8931;
+export declare const MAX_PORT = 8949;
+declare const BROWSERS: readonly ["chromium", "firefox", "webkit"];
+type Browser = typeof BROWSERS[number];
+export interface PlaywrightSession {
+    terminalId: string;
+    port: number;
+    browser: Browser;
+    userDataDir: string;
+    startedAt: string;
+    pid?: number;
+}
+export declare const PLAYWRIGHT_SESSIONS_DIR = "playwright-sessions";
+export declare function playwrightSessionsDir(projectRoot: string): string;
+export declare function sessionFilePath(projectRoot: string, terminalId: string): string;
+/**
+ * Derive a stable terminal id from the process environment. Prefers
+ * the platform's own terminal-session id (macOS Terminal, Windows
+ * Terminal) and falls back to a hash of (ppid, tty).
+ */
+export declare function deriveTerminalId(env?: NodeJS.ProcessEnv, ppid?: number): string;
+/**
+ * Walk port range starting at `start` and return the first port
+ * that is NOT bound. Defaults: 8931 → 8949. If the range is exhausted,
+ * returns null.
+ */
+export declare function findFreePort(start?: number, max?: number, probe?: (port: number) => Promise<boolean>): Promise<number | null>;
+export declare function listSessions(projectRoot: string): PlaywrightSession[];
+export declare function readSession(projectRoot: string, terminalId: string): PlaywrightSession | null;
+export declare function writeSession(projectRoot: string, session: PlaywrightSession): void;
+export declare function removeSession(projectRoot: string, terminalId: string): boolean;
+/**
+ * Spawn the playwright MCP via npx. We do NOT bundle the binary;
+ * we just orchestrate the lifecycle. Returns the child PID so the
+ * session file can record it.
+ */
+export declare function spawnPlaywrightMcp(port: number, browser: Browser, userDataDir: string, projectRoot: string): {
+    pid: number | undefined;
+    child: ReturnType<typeof spawn>;
+};
+export declare function registerPlaywrightCommands(program: Command, _io: ProgramIO): void;
+/**
+ * Wire `peaks browser action <intent>`. The wrapper is a thin adapter
+ * for the 5 intents. The real MCP caller is provided by the IDE / agent
+ * harness — this CLI surface is invoked by tests and skills to drive
+ * browser flows without hand-shelling the MCP protocol.
+ */
+export declare function registerBrowserActionCommand(program: Command): void;
+/**
+ * Resolve and validate a caller-supplied `--user-data-dir`. The dir must
+ * live under `projectRoot` so a malicious `--user-data-dir /etc/foo`
+ * cannot coerce the playwright-mcp browser into writing state to an
+ * arbitrary filesystem path (slice 2026-06-23-audit-3rd #5).
+ *
+ * Resolves `..` segments before checking, so a path like
+ * `<projectRoot>/../escape` is correctly normalized and rejected.
+ *
+ * Throws `Error('INVALID_USER_DATA_DIR: ...')` on validation failure;
+ * the action handler catches and emits the JSON envelope.
+ */
+export declare function resolveUserDataDir(raw: string, projectRoot: string): string;
+export {};

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

@@ -0,0 +1,432 @@
+/**
+ * `peaks playwright start | ls | stop` — slice 2.5.0 sub-fix C (Prob 3).
+ *
+ * Multi-terminal resolution for the Playwright MCP. When two or more
+ * terminals / IDE sessions each spawn a `playwright` MCP server, they
+ * fight over the same default port (8931) and the same user data
+ * dir. This command:
+ *
+ *   1. `peaks playwright start [--port N] [--browser <chromium|firefox|webkit>]`
+ *      Allocates a unique port (default 8931; walks 8931→8949 if busy),
+ *      spawns `npx playwright-mcp@latest` with the chosen port, and
+ *      writes a session file at
+ *      `<projectRoot>/.peaks/_runtime/playwright-sessions/<terminal-id>.json`
+ *      with `{ port, userDataDir, startedAt, pid }`.
+ *
+ *   2. `peaks playwright ls` — lists all running sessions (reads
+ *      `.peaks/_runtime/playwright-sessions/*.json`).
+ *
+ *   3. `peaks playwright stop [--terminal <id>]` — best-effort kills
+ *      the server process and removes the session file.
+ *
+ * Terminal ID derivation (R4):
+ *   1. process.env.TERM_SESSION_ID (macOS Terminal / iTerm2)
+ *   2. process.env.WT_SESSION (Windows Terminal)
+ *   3. hash(process.ppid + process.env.SSH_TTY || 'no-tty')
+ *
+ * The CLI does NOT bundle `playwright-mcp`; it shells out to
+ * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle
+ * orchestrator, not the install medium.
+ */
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getErrorMessage } from '../cli-helpers.js';
+import { runBrowserAction } from '../../services/qa/browser-wrapper-service.js';
+export const DEFAULT_PORT = 8931;
+export const MAX_PORT = 8949;
+const BROWSERS = ['chromium', 'firefox', 'webkit'];
+export const PLAYWRIGHT_SESSIONS_DIR = 'playwright-sessions';
+export function playwrightSessionsDir(projectRoot) {
+    return join(projectRoot, '.peaks', '_runtime', PLAYWRIGHT_SESSIONS_DIR);
+}
+export function sessionFilePath(projectRoot, terminalId) {
+    return join(playwrightSessionsDir(projectRoot), `${terminalId}.json`);
+}
+/**
+ * Derive a stable terminal id from the process environment. Prefers
+ * the platform's own terminal-session id (macOS Terminal, Windows
+ * Terminal) and falls back to a hash of (ppid, tty).
+ */
+export function deriveTerminalId(env = process.env, ppid = process.ppid) {
+    const termSession = env.TERM_SESSION_ID;
+    if (termSession && termSession.length > 0) {
+        return sanitizeTerminalId(termSession);
+    }
+    const wtSession = env.WT_SESSION;
+    if (wtSession && wtSession.length > 0) {
+        return sanitizeTerminalId(`wt-${wtSession}`);
+    }
+    const tty = env.SSH_TTY ?? 'no-tty';
+    const hash = createHash('sha256').update(`${ppid}-${tty}`).digest('hex').slice(0, 16);
+    return `tty-${hash}`;
+}
+function sanitizeTerminalId(raw) {
+    return raw.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 64);
+}
+/**
+ * Walk port range starting at `start` and return the first port
+ * that is NOT bound. Defaults: 8931 → 8949. If the range is exhausted,
+ * returns null.
+ */
+export async function findFreePort(start = DEFAULT_PORT, max = MAX_PORT, probe = defaultPortProbe) {
+    for (let p = start; p <= max; p += 1) {
+        if (await probe(p))
+            return p;
+    }
+    return null;
+}
+async function defaultPortProbe(port) {
+    return new Promise((resolveProbe) => {
+        const net = require('node:net');
+        const server = net.createServer();
+        server.once('error', () => resolveProbe(false));
+        server.once('listening', () => {
+            server.close(() => resolveProbe(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+export function listSessions(projectRoot) {
+    const dir = playwrightSessionsDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith('.json'))
+            continue;
+        try {
+            const raw = readFileSync(join(dir, entry), 'utf8');
+            const session = JSON.parse(raw);
+            out.push(session);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // skip malformed session file
+        }
+    }
+    return out;
+}
+export function readSession(projectRoot, terminalId) {
+    const path = sessionFilePath(projectRoot, terminalId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+export function writeSession(projectRoot, session) {
+    const path = sessionFilePath(projectRoot, session.terminalId);
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(session, null, 2) + '\n', 'utf8');
+}
+export function removeSession(projectRoot, terminalId) {
+    const path = sessionFilePath(projectRoot, terminalId);
+    if (!existsSync(path))
+        return false;
+    unlinkSync(path);
+    return true;
+}
+/**
+ * Spawn the playwright MCP via npx. We do NOT bundle the binary;
+ * we just orchestrate the lifecycle. Returns the child PID so the
+ * session file can record it.
+ */
+export function spawnPlaywrightMcp(port, browser, userDataDir, projectRoot) {
+    const child = spawn('npx', ['playwright-mcp@latest', `--port=${port}`, `--browser=${browser}`, `--user-data-dir=${userDataDir}`], {
+        cwd: projectRoot,
+        env: process.env,
+        stdio: 'ignore',
+        detached: true
+    });
+    return { pid: child.pid, child };
+}
+export function registerPlaywrightCommands(program, _io) {
+    const playwright = program
+        .command('playwright')
+        .description('Multi-terminal Playwright MCP lifecycle. `peaks playwright start` allocates a unique port ' +
+        '(8931→8949) and writes a session file; `ls` lists running sessions; `stop` tears them down. ' +
+        'Does NOT bundle the playwright-mcp binary (uses `npx playwright-mcp@latest`). ' +
+        '(slice 2.5.0 sub-fix C)');
+    playwright
+        .command('start')
+        .description('Start a Playwright MCP server on a free port; write a session record.')
+        .option('--port <n>', 'preferred port (default 8931; walks 8931→8949 if busy)', (v) => Number(v))
+        .option('--browser <name>', `browser engine: ${BROWSERS.join(', ')} (default chromium)`, 'chromium')
+        .option('--user-data-dir <path>', 'browser user-data directory (default: <projectRoot>/.peaks/_runtime/playwright-userdata/<terminal-id>)')
+        .option('--reuse', 'if a session is already running for this terminal, return its port instead of erroring')
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--json', 'emit a JSON envelope { ok, data } to stdout')
+        .action(async (opts) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+            const browser = BROWSERS.includes(opts.browser)
+                ? opts.browser
+                : 'chromium';
+            const terminalId = deriveTerminalId();
+            // Existing session for this terminal?
+            const existing = readSession(projectRoot, terminalId);
+            if (existing) {
+                if (opts.reuse) {
+                    if (opts.json === true) {
+                        process.stdout.write(JSON.stringify({
+                            ok: true,
+                            data: { reused: true, session: existing }
+                        }) + '\n');
+                    }
+                    else {
+                        process.stdout.write(`reusing existing playwright session on port ${existing.port} (terminal ${terminalId})\n`);
+                    }
+                    return;
+                }
+                // Conflict: G21 / AC18
+                const msg = `CONFLICT: another playwright MCP is already running on port ${existing.port} (terminal ${terminalId}). Reuse it (--reuse) or pick a new port (--port <n>).`;
+                if (opts.json === true) {
+                    process.stdout.write(JSON.stringify({ ok: false, error: msg, code: 'CONFLICT' }) + '\n');
+                }
+                else {
+                    process.stderr.write(msg + '\n');
+                }
+                process.exitCode = 1;
+                return;
+            }
+            // Port allocation
+            const startPort = typeof opts.port === 'number' && Number.isFinite(opts.port) ? opts.port : DEFAULT_PORT;
+            if (startPort < 1024 || startPort > 65535) {
+                const msg = `INVALID_PORT: --port must be between 1024 and 65535 (got ${startPort})`;
+                if (opts.json === true) {
+                    process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
+                }
+                else {
+                    process.stderr.write(msg + '\n');
+                }
+                process.exitCode = 1;
+                return;
+            }
+            const port = await findFreePort(startPort, MAX_PORT);
+            if (port === null) {
+                const msg = `PORT_EXHAUSTED: no free port in ${startPort}..${MAX_PORT} range`;
+                if (opts.json === true) {
+                    process.stdout.write(JSON.stringify({ ok: false, error: msg, code: 'PORT_EXHAUSTED' }) + '\n');
+                }
+                else {
+                    process.stderr.write(msg + '\n');
+                }
+                process.exitCode = 1;
+                return;
+            }
+            // userDataDir default
+            const userDataDir = opts.userDataDir
+                ? resolveUserDataDir(opts.userDataDir, projectRoot)
+                : join(projectRoot, '.peaks', '_runtime', 'playwright-userdata', terminalId);
+            // Spawn the MCP via npx. Detached so it survives our exit.
+            const { pid, child } = spawnPlaywrightMcp(port, browser, userDataDir, projectRoot);
+            // Detach: do not wait for it.
+            child.unref();
+            const session = {
+                terminalId,
+                port,
+                browser,
+                userDataDir,
+                startedAt: new Date().toISOString(),
+                ...(pid !== undefined ? { pid } : {})
+            };
+            writeSession(projectRoot, session);
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({
+                    ok: true,
+                    data: { session, sessionFile: sessionFilePath(projectRoot, terminalId) }
+                }) + '\n');
+            }
+            else {
+                process.stdout.write(`playwright MCP started on port ${port} (browser=${browser}, terminal=${terminalId})\n`);
+            }
+        }
+        catch (error) {
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
+            }
+            else {
+                process.stderr.write(getErrorMessage(error) + '\n');
+            }
+            process.exitCode = 1;
+        }
+    });
+    playwright
+        .command('ls')
+        .description('List running Playwright MCP sessions from .peaks/_runtime/playwright-sessions/*.json')
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--json', 'emit a JSON envelope { ok, data: { sessions } }')
+        .action(async (opts) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+            const sessions = listSessions(projectRoot);
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: true, data: { sessions } }) + '\n');
+            }
+            else if (sessions.length === 0) {
+                process.stdout.write('no playwright sessions running\n');
+            }
+            else {
+                for (const s of sessions) {
+                    process.stdout.write(`port=${s.port}\tbrowser=${s.browser}\tterminal=${s.terminalId}\tpid=${s.pid ?? '?'}\tstarted=${s.startedAt}\n`);
+                }
+            }
+        }
+        catch (error) {
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
+            }
+            else {
+                process.stderr.write(getErrorMessage(error) + '\n');
+            }
+            process.exitCode = 1;
+        }
+    });
+    playwright
+        .command('stop')
+        .description('Stop a running Playwright MCP session (best-effort kill + remove session file).')
+        .option('--terminal <id>', 'terminal id to stop (default: this shell\'s derived terminal id)')
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--json', 'emit a JSON envelope { ok, data }')
+        .action(async (opts) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+            const terminalId = opts.terminal ?? deriveTerminalId();
+            const session = readSession(projectRoot, terminalId);
+            if (!session) {
+                const msg = `NO_SESSION: no playwright session for terminal ${terminalId}`;
+                if (opts.json === true) {
+                    process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
+                }
+                else {
+                    process.stderr.write(msg + '\n');
+                }
+                process.exitCode = 1;
+                return;
+            }
+            // Best-effort kill
+            if (session.pid !== undefined && session.pid !== null) {
+                try {
+                    process.kill(session.pid, 'SIGTERM');
+                }
+                catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                    /* process may have already exited */
+                }
+            }
+            removeSession(projectRoot, terminalId);
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: true, data: { stopped: session } }) + '\n');
+            }
+            else {
+                process.stdout.write(`stopped playwright session on port ${session.port} (terminal ${terminalId})\n`);
+            }
+        }
+        catch (error) {
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
+            }
+            else {
+                process.stderr.write(getErrorMessage(error) + '\n');
+            }
+            process.exitCode = 1;
+        }
+    });
+    // Slice 3: `peaks browser action <intent> [args...]` — thin wrapper
+    // around 5 Playwright MCP intents. One MCP call per invocation; no
+    // auto-snapshot between intents. See src/services/qa/browser-wrapper-service.ts.
+    registerBrowserActionCommand(program);
+}
+/**
+ * Wire `peaks browser action <intent>`. The wrapper is a thin adapter
+ * for the 5 intents. The real MCP caller is provided by the IDE / agent
+ * harness — this CLI surface is invoked by tests and skills to drive
+ * browser flows without hand-shelling the MCP protocol.
+ */
+export function registerBrowserActionCommand(program) {
+    const browser = program
+        .command('browser')
+        .description('Browser action helpers (slice 3: thin Playwright MCP wrapper, 5 intents only)');
+    browser
+        .command('action')
+        .description('Run one of 5 browser intents: navigate, click, fill, snapshot, extract')
+        .argument('<intent>', 'one of: navigate, click, fill, snapshot, extract')
+        .option('--url <url>', 'URL (navigate)')
+        .option('--selector <selector>', 'simple selector: #id, .class, tag, tag#id, tag.class')
+        .option('--value <value>', 'value to fill')
+        .option('--expression <expr>', 'JS expression to evaluate (extract)')
+        .option('--json', 'emit JSON envelope')
+        .action(async (intent, opts) => {
+        try {
+            if (!isSupportedIntent(intent)) {
+                throw new Error(`unknown intent "${intent}" — fall back to raw MCP (supported: navigate, click, fill, snapshot, extract)`);
+            }
+            // The IDE/agent harness bridges `mcp__playwright__browser_*` tools.
+            // Outside the harness, we use a pass-through caller that records
+            // the intent + args so skills and tests can route the call.
+            const result = await runBrowserAction(intent, {
+                url: opts.url,
+                selector: opts.selector,
+                value: opts.value,
+                expression: opts.expression
+            }, mockOrPassThroughCaller);
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: true, data: result }) + '\n');
+            }
+            else {
+                process.stdout.write(`intent=${result.intent} ok=${result.ok} elapsedMs=${result.elapsedMs}\n`);
+            }
+        }
+        catch (error) {
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
+            }
+            else {
+                process.stderr.write(getErrorMessage(error) + '\n');
+            }
+            process.exitCode = 1;
+        }
+    });
+}
+function isSupportedIntent(value) {
+    return value === 'navigate' || value === 'click' || value === 'fill' || value === 'snapshot' || value === 'extract';
+}
+/**
+ * Resolve and validate a caller-supplied `--user-data-dir`. The dir must
+ * live under `projectRoot` so a malicious `--user-data-dir /etc/foo`
+ * cannot coerce the playwright-mcp browser into writing state to an
+ * arbitrary filesystem path (slice 2026-06-23-audit-3rd #5).
+ *
+ * Resolves `..` segments before checking, so a path like
+ * `<projectRoot>/../escape` is correctly normalized and rejected.
+ *
+ * Throws `Error('INVALID_USER_DATA_DIR: ...')` on validation failure;
+ * the action handler catches and emits the JSON envelope.
+ */
+export function resolveUserDataDir(raw, projectRoot) {
+    const resolved = resolve(projectRoot, raw);
+    const rootResolved = resolve(projectRoot) + (projectRoot.endsWith('/') || projectRoot.endsWith('\\') ? '' : '/');
+    // Use the projectRoot + sep as the prefix; require either an exact
+    // match or a child path. The `+ '/'` guard prevents sibling-prefix
+    // collisions (e.g. /home/A/proj2 passes the check for /home/A/proj).
+    if (resolved !== resolve(projectRoot) && !resolved.startsWith(rootResolved)) {
+        throw new Error(`INVALID_USER_DATA_DIR: --user-data-dir must resolve to a path under project root ${projectRoot} (got ${resolved})`);
+    }
+    return resolved;
+}
+/**
+ * Pass-through caller used when the CLI surface is invoked outside the
+ * harness. In production the IDE/agent harness intercepts the wrapper's
+ * output and routes the underlying MCP call. Tests inject a stub via
+ * the `runBrowserAction(..., caller)` overload.
+ */
+async function mockOrPassThroughCaller(tool, args) {
+    return { tool, args, routedBy: 'peaks-loop-browser-wrapper' };
+}

package/dist/cli/commands/polyrepo-commands.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `peaks polyrepo *` — polyrepo workflow CLI surface.
+ *
+ * Slice S2-b of RD-2 (2026-07-08 session). Three subcommands:
+ *
+ *   init      — scan the parent dir for child git repos + write a
+ *               polyrepo manifest to `.peaks/polyrepo.json`.
+ *   status    — read the persisted manifest + report children.
+ *   dispatch  — mirror a PRD/RD/QA artifact from the parent into
+ *               each target child's
+ *               `.peaks/_runtime/<sid>/<role>/` directory.
+ *
+ * Per the project's two-axis convention, all reviewable artifacts
+ * live under `.peaks/_runtime/<sid>/<role>/` — never as top-level
+ * siblings of `.peaks/_runtime/`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface PolyrepoInitOptions {
+    json?: boolean;
+    root?: string;
+    children?: string;
+}
+export interface PolyrepoStatusOptions {
+    json?: boolean;
+    root?: string;
+}
+export interface PolyrepoDispatchOptions {
+    json?: boolean;
+    root?: string;
+    rid?: string;
+    to?: string;
+    role?: 'prd' | 'rd' | 'qa';
+    artifact?: string;
+    sid?: string;
+}
+export declare function registerPolyrepoCommands(program: Command, io: ProgramIO): void;