peaks-cli 1.3.4 → 1.3.6

package/skills/peaks-solo/references/swarm-dispatch-contract.md

@@ -16,7 +16,7 @@ Return a compact JSON envelope — do not write prose.
 ## Hard prohibitions
 - Do NOT call Skill(skill="..."). You are the role.
 - Do NOT call `peaks skill presence:set` — the main loop owns .peaks/.active-skill.json.
-  If you need to record state, write to .peaks/<session-id>/system/sub-agent-<role>.json.
+  If you need to record state, write to .peaks/_runtime/<session-id>/system/sub-agent-<role>.json.
 - Do NOT commit, push, install hooks, or apply settings.json mutations.
 - Do NOT ask the user interactive questions. If you need clarification, return
   {"status":"blocked","blockedReason":"<text>"} and let the main loop handle it.
@@ -47,14 +47,14 @@ Steps:
 3. Read <project-scan-path> for component library / CSS framework.
 4. Run the prototype fidelity gate: Figma file? PRD visuals? Headed browser?
 5. Write TWO artefacts:
-   - .peaks/<sid>/ui/design-draft.md
-   - .peaks/<sid>/ui/requests/<rid>.md
+   - .peaks/_runtime/<sid>/ui/design-draft.md
+   - .peaks/_runtime/<sid>/ui/requests/<rid>.md
 6. Return:
    {
      "role": "ui",
      "rid": "<rid>",
      "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/<sid>/ui/design-draft.md", ".peaks/<sid>/ui/requests/<rid>.md"],
+     "artefacts": [".peaks/_runtime/<sid>/ui/design-draft.md", ".peaks/_runtime/<sid>/ui/requests/<rid>.md"],
      "warnings": [],
      "blockedReason": null
    }
@@ -80,15 +80,15 @@ Steps:
    into rd/project-scan.md.
 5. Read <existing-system-path> if archetype is legacy-*.
 6. Write the type-appropriate planning artefact:
-   - feature | refactor  → .peaks/<sid>/rd/tech-doc.md
-   - bugfix              → .peaks/<sid>/rd/bug-analysis.md
+   - feature | refactor  → .peaks/_runtime/<sid>/rd/tech-doc.md
+   - bugfix              → .peaks/_runtime/<sid>/rd/bug-analysis.md
    - config | docs | chore → no planning artefact required. Return skipped.
 7. Return:
    {
      "role": "rd-planning",
      "rid": "<rid>",
      "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/<sid>/rd/tech-doc.md"],   // or [] when skipped
+     "artefacts": [".peaks/_runtime/<sid>/rd/tech-doc.md"],   // or [] when skipped
      "warnings": [],
      "blockedReason": null
    }
@@ -106,14 +106,14 @@ Steps:
 2. peaks request show <rid> --role prd --project <repo> --json
 3. peaks request show <rid> --role rd  --project <repo> --json
 4. Read <project-scan-path>.
-5. Write .peaks/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
+5. Write .peaks/_runtime/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
    acceptance items (use **Acceptance:** A1, A2 style).
 6. Return:
    {
      "role": "qa-test-cases",
      "rid": "<rid>",
      "status": "ok" | "blocked" | "skipped",
-     "artefacts": [".peaks/<sid>/qa/test-cases/<rid>.md"],
+     "artefacts": [".peaks/_runtime/<sid>/qa/test-cases/<rid>.md"],
      "warnings": [],
      "blockedReason": null
    }

package/skills/peaks-ui/SKILL.md

@@ -13,7 +13,7 @@ UI's headed-browser work (visual inspection, regression seed capture, Figma / li
 
 ### Contract 1 — Inspection screenshots must land under .peaks/<sid>/qa/screenshots/
 
-Every Playwright screenshot tool call (via `peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '<args>' --json`) **MUST** pass `filename` (in the args object) inside `.peaks/<session-id>/qa/screenshots/`, named after the inspection target (e.g. `home-after-cta.png`, `empty-state-v2.png`). Do not let Playwright fall back to the project root. After every batch, run:
+Every Playwright screenshot tool call (the LLM invokes `browser_take_screenshot` directly when the Playwright MCP is present in its tool list) **MUST** pass `filename` (in the args object) inside `.peaks/<session-id>/qa/screenshots/`, named after the inspection target (e.g. `home-after-cta.png`, `empty-state-v2.png`). Do not let Playwright fall back to the project root. After every batch, run:
 
 ```bash
 ls .peaks/<sid>/qa/screenshots/*.png 2>&1
@@ -61,7 +61,7 @@ What the sub-agent **MUST** still do:
 - Do NOT call `Skill(skill="...")`.
 - Do NOT call `peaks skill presence:set` — Solo owns the active-skill file.
 - Do NOT modify application code. UI is design-direction only; the actual frontend code is written in the RD implementation phase.
-- Do NOT install MCP servers. If `peaks mcp list` shows playwright-mcp missing and the headed browser is required, return `{"status":"blocked","blockedReason":"playwright-mcp-unavailable"}` and let Solo escalate to the user.
+- Do NOT install MCP servers. If the LLM tool list does not include the Playwright MCP and the headed browser is required, return `{"status":"blocked","blockedReason":"playwright-mcp-unavailable"}` and let Solo escalate to the user. (peaks-cli no longer manages MCP install — the user runs `claude mcp add playwright -- npx @playwright/mcp@latest` themselves in Claude Code, or the IDE-specific install command otherwise.)
 - Do NOT commit, push, install hooks, or apply settings.json mutations.
 - Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}`.
 
@@ -129,14 +129,13 @@ peaks request init --role ui --id <request-id> --project <repo> --apply --json
 peaks request show <request-id> --role prd --project <repo> --json   # read linked PRD scope
 
 # 2. ensure Playwright MCP is available for the visible browser check
-peaks mcp list --json
-# if playwright-mcp.browser-validation is NOT in the list:
-peaks mcp plan  --capability playwright-mcp.browser-validation --json
-peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
-# if apply fails or user denies installation:
-#   → mark browser gate as blocked with reason "playwright-mcp-unavailable"
-#   → NEVER silently downgrade to screenshots-only, manual steps, or other tools
-#   → NEVER route through chrome-devtools-mcp as a browser-launch substitute (it cannot launch)
+# Slice #016: peaks-cli no longer manages MCP install. The LLM checks
+# its own tool list for any Playwright MCP entry in the LLM tool list. If absent, the
+# LLM tells the user the install command (`claude mcp add playwright
+# -- npx @playwright/mcp@latest` in Claude Code) and reports the gate
+# as blocked. Do NOT silently downgrade to screenshots-only, manual
+# steps, or other tools. Do NOT route through chrome-devtools-mcp as a
+# browser-launch substitute (it cannot launch a browser of its own).
 
 # 3. read project-scan for component library and CSS framework context
 #    check .peaks/<session-id>/rd/project-scan.md (blocking if missing for existing projects)
@@ -151,8 +150,8 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 #    See "Prototype fidelity gate" section for the full decision tree.
 
 # 5. drive the running page or prototype through Claude Code MCP tools
-#    (these are not Peaks-Cli CLI commands; they are invoked by the host MCP runtime)
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_navigate --args-json '{"url":"<url>"}' --json
+#    (the LLM invokes these directly from its tool list — no peaks-cli envelope)
+#    browser_navigate --args '{"url":"<url>"}'
 #    → URL (after allow-list check), launches headed browser
 #
 #    LOGIN GATE (MANDATORY checkpoint):
@@ -162,19 +161,18 @@ peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
 #    If user does not confirm within reasonable time → pause and ask.
 #    Only after user confirmation, continue to:
 #
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_take_screenshot --args-json '{"filename":"<abs-path>"}' --json
+#    browser_take_screenshot --args '{"filename":"<abs-path>"}'
 #    → visible-browser confirmation
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_snapshot --args-json '{}' --json
+#    browser_snapshot --args '{}'
 #    → accessibility tree for regression seeds
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_console_messages --args-json '{}' --json
+#    browser_console_messages --args '{}'
 #    → console errors
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_network_requests --args-json '{}' --json
+#    browser_network_requests --args '{}'
 #    → failed network
-#    peaks mcp call --capability playwright-mcp.browser-validation --tool browser_close --args-json '{}' --json
+#    browser_close --args '{}'
 #    → end the session cleanly
-# The skill body NEVER bakes in the `mcp__playwright__` prefix; the LLM's runtime
-# resolves the tool name from the registered server. The capability id
-# `playwright-mcp.browser-validation` is the contract; the registry is the source of truth.
+# The skill body NEVER bakes in the the Playwright MCP tools prefix; the LLM's runtime
+# resolves the tool name from the registered server.
 
 # 5. write design-draft artifact to .peaks/<session-id>/ui/design-draft.md
 
@@ -238,7 +236,7 @@ Use gstack as a concrete design-review workflow reference for the `Plan → Revi
 - map browser walkthrough concepts to UI regression seeds when runtime validation is approved;
 - keep accessibility, performance, and product-specific visual direction as Peaks-Cli UI acceptance inputs.
 
-For frontend work, especially full-auto mode, use Playwright MCP to inspect the running page or prototype before accepting the UI direction. The skill body never bakes in the `mcp__playwright__` prefix; it uses `peaks mcp call --capability playwright-mcp.browser-validation --tool <name> --args-json '<args>' --json` for every browser operation (browser_navigate / browser_snapshot / browser_take_screenshot / browser_console_messages / browser_network_requests / browser_close). Playwright MCP launches a headed browser on demand; if `peaks mcp list --json` does not include `playwright`, install it through `peaks mcp plan --capability playwright-mcp.browser-validation --json` then `peaks mcp apply --capability playwright-mcp.browser-validation --yes --json` before attempting to inspect. (Chrome DevTools MCP is a secondary surface that connects to an already-running Chrome via `--remote-debugging-port=9222`; it does NOT launch a browser on its own.) If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture only sanitized visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA; do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Canonical browser workflow: `peaks-solo/references/browser-workflow.md`.
+For frontend work, especially full-auto mode, use the Playwright MCP to inspect the running page or prototype before accepting the UI direction. The LLM checks its own tool list for any Playwright MCP entry in the LLM tool list; if present, it invokes the tools by name directly (browser_navigate / browser_snapshot / browser_take_screenshot / browser_console_messages / browser_network_requests / browser_close) — there is no peaks-cli envelope. Playwright MCP launches a headed browser on demand; if the tool list is empty, the user installs via `claude mcp add playwright -- npx @playwright/mcp@latest` (Claude Code) or the IDE's own MCP install path. (Chrome DevTools MCP is a secondary surface that connects to an already-running Chrome via `--remote-debugging-port=9222`; it does NOT launch a browser on its own.) If login, CAPTCHA, SSO, or MFA appears, the visible browser is already open; wait for the user to complete login and explicitly confirm completion before continuing. Capture only sanitized visible regressions, weak hierarchy, generic template patterns, console errors, and interaction problems as UI feedback that should return to design/RD before handing off to QA; do not retain login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material. Canonical browser workflow: `peaks-solo/references/browser-workflow.md`.
 
 ## Prototype fidelity gate (MANDATORY — check BEFORE any design work)
 
@@ -248,7 +246,7 @@ For frontend work, especially full-auto mode, use Playwright MCP to inspect the
 
 Check these sources in order:
 
-1. **Figma design file** — If the PRD links to a Figma file, use `peaks mcp call --capability figma-context-mcp.design-context --tool get_figma_data --args-json '{"fileKey":"<key>"}' --json` to fetch the design (the skill body never bakes in the `mcp__Figma_AI_Bridge__` prefix; the prefix is owned by the LLM runtime, and `FIGMA_API_KEY` must be set in the env before `peaks mcp apply` — the plan envelope's `envCheck.missing` field is the source of truth). The Figma data IS the design. Replicate layout, spacing, colors, typography, and component choices exactly as specified.
+1. **Figma design file** — If the PRD links to a Figma file, the LLM checks its own tool list for any the Figma MCP entry. If present, it invokes `get_figma_data` (or similar) directly with `{"fileKey":"<key>"}`; `FIGMA_API_KEY` must be set in the user's env for the MCP to authenticate. The skill body never bakes in the Figma MCP prefix; the LLM's runtime owns the namespace. The Figma data IS the design. Replicate layout, spacing, colors, typography, and component choices exactly as specified.
 2. **PRD document screenshots** — If the PRD source (Feishu/Lark doc) contains screenshots or mockups, those ARE the visual target. Check `.peaks/<id>/prd/source/` for saved screenshots.
 3. **PRD visual descriptions** — If the PRD explicitly describes layout, component placement, or visual behavior, those descriptions are constraints, not suggestions.
 4. **Existing application pages** — If modifying an existing app, the existing visual language (component library, spacing patterns, color usage) is the fidelity baseline. New pages must match existing conventions.
@@ -355,8 +353,8 @@ Use `peaks capabilities --source access-repo --json` and `peaks capabilities --s
 
 - In full-auto frontend mode, prefer the `awesome-design-md` + `taste-skill`/`design-taste-frontend` combination before shadcn/ui or generic component-library output (capability discovery must confirm availability first).
 - shadcn/ui, React Bits, awesome-design-md, taste-skill, and ui-ux-pro-max-skill are UI references; do not treat unreviewed generated UI as finished design.
-- Chrome DevTools MCP and Agent Browser can support runtime UI inspection only after the user approves the app target. Install or update those MCP servers through `peaks mcp plan --capability <id> --json` then `peaks mcp apply --capability <id> --yes --json` rather than hand-editing settings; invoke their tools through `peaks mcp call --capability <id> --tool <name> --args-json '{...}' --json`.
-- Figma Context MCP and Penpot require user-authorized design access and must not persist tokens or private design data in project artifacts. Same `peaks mcp plan / apply / call` installation and invocation path applies.
+- Chrome DevTools MCP and Agent Browser can support runtime UI inspection only after the user approves the app target. (Slice #016: peaks-cli no longer auto-installs these; the user runs the IDE-native MCP install command themselves, and the LLM invokes the tool by name from its tool list when present.)
+- Figma Context MCP and Penpot require user-authorized design access and must not persist tokens or private design data in project artifacts. Same rule: the LLM's tool list is the source of truth; peaks-cli is not in the install path.
 - Check license, accessibility, and performance before translating external visual references into Peaks-Cli UI constraints.
 
 ## Boundaries

package/skills/peaks-ui/references/workflow.md

@@ -11,7 +11,7 @@ Use this path before generating or accepting frontend UI:
 3. Produce a concrete visual direction, not vague “clean modern” language.
 4. Reject generic AI UI tells: centered stock hero, uniform card grids, default shadcn/library styling, purple-blue gradients, three equal feature cards, generic placeholder copy, and static-only happy states.
 5. Require meaningful loading, empty, error, hover, focus, active, and responsive states.
-6. Use Playwright MCP on the running page or prototype to inspect real browser output (install via `peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes` if not yet present; open with `mcp__playwright__browser_navigate` / `navigate_page`, capture with `take_snapshot` and `take_screenshot`); visible browser confirmation is mandatory, and login/CAPTCHA/SSO/MFA requires waiting for explicit user confirmation before continuing.
+6. Use Playwright MCP on the running page or prototype to inspect real browser output (the LLM checks its tool list for `mcp__playwright__*`; if absent, the user installs via `claude mcp add playwright -- npx @playwright/mcp@latest` for Claude Code, or the IDE-native MCP install command otherwise — peaks-cli no longer auto-installs as of slice #016; open with `browser_navigate` / `navigate_page`, capture with `browser_snapshot` and `browser_take_screenshot`); visible browser confirmation is mandatory, and login/CAPTCHA/SSO/MFA requires waiting for explicit user confirmation before continuing.
 7. If the browser view looks generic, visually weak, broken, inaccessible, or has console/runtime errors, return to design/RD and iterate before handing off to QA.
 
 ## Outputs
@@ -21,7 +21,7 @@ Use this path before generating or accepting frontend UI:
 - visual direction with references;
 - design dials and rejected generic patterns;
 - interaction constraints;
-- Playwright MCP browser observations when frontend output exists (`mcp__playwright__browser_snapshot`, `take_screenshot`, `list_console_messages`, `list_network_requests`);
+- Playwright MCP browser observations when frontend output exists (`browser_snapshot`, `browser_take_screenshot`, `browser_console_messages`, `browser_network_requests`);
 - UI regression seeds;
 - accessibility notes;
 - taste report.

package/dist/src/cli/commands/mcp-commands.d.ts

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

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

@@ -1,144 +0,0 @@
-import { InvalidArgumentError } from 'commander';
-import { readFile } from 'node:fs/promises';
-import { scanMcpServers } from '../../services/mcp/mcp-scan-service.js';
-import { planMcpInstall } from '../../services/mcp/mcp-plan-service.js';
-import { applyMcpInstall, rollbackMcpInstall } from '../../services/mcp/mcp-apply-service.js';
-import { callMcpTool } from '../../services/mcp/mcp-call-service.js';
-import { createStdioTransportFromSpec } from '../../services/mcp/mcp-stdio-transport.js';
-import { fail, ok } from '../../shared/result.js';
-import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../cli-helpers.js';
-function parsePositiveInteger(value) {
-    if (!/^\d+$/.test(value)) {
-        throw new InvalidArgumentError('must be a positive integer');
-    }
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed) || parsed < 1) {
-        throw new InvalidArgumentError('must be a positive integer');
-    }
-    return parsed;
-}
-async function resolveCallArgs(options) {
-    if (options.argsJson !== undefined && options.args !== undefined) {
-        throw new Error('Pass either --args-json or --args, not both');
-    }
-    const raw = options.argsJson !== undefined
-        ? options.argsJson
-        : options.args !== undefined ? await readFile(options.args, 'utf8') : '{}';
-    const parsed = JSON.parse(raw);
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('MCP tool arguments must be a JSON object');
-    }
-    return parsed;
-}
-export function registerMcpCommands(program, io) {
-    const mcp = program.command('mcp').description('Manage Claude Code MCP servers');
-    addJsonOption(mcp
-        .command('list')
-        .alias('scan')
-        .description('Scan Claude Code settings for configured MCP servers')
-        .option('--project <path>', 'project root to also scan project-level .claude/settings.json')).action(async (options) => {
-        try {
-            const report = await scanMcpServers(options.project !== undefined ? { projectRoot: options.project } : {});
-            printResult(io, ok('mcp.list', report), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.list', 'MCP_LIST_FAILED', getErrorMessage(error), {}, ['Check Claude settings path and permissions before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(mcp
-        .command('plan')
-        .description('Plan an MCP server install diff for a capability (dry-run only)')
-        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
-        .option('--project <path>', 'project root for scoped scan')
-        .option('--dry-run', 'preview the install diff (always true)', true)
-        .option('--no-dry-run', 'unsupported: peaks mcp plan never writes settings')).action(async (options) => {
-        if (options.dryRun === false) {
-            failUnsupportedNonDryRun(io, 'mcp.plan', options.json);
-            return;
-        }
-        try {
-            const planOptions = options.project !== undefined ? { projectRoot: options.project } : {};
-            const plan = await planMcpInstall(options.capability, planOptions);
-            if (plan.action === 'unknown-capability') {
-                printResult(io, fail('mcp.plan', 'MCP_UNKNOWN_CAPABILITY', `No MCP install spec registered for capability ${options.capability}`, plan, plan.nextActions), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, ok('mcp.plan', plan, [], plan.nextActions), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.plan', 'MCP_PLAN_FAILED', getErrorMessage(error), { capabilityId: options.capability }, ['Check Claude settings path and the capability id before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(mcp
-        .command('apply')
-        .description('Apply an MCP server install for a capability (writes .claude/settings.json with backup)')
-        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
-        .option('--yes', 'confirm the write — required for any real side effect')
-        .option('--claim', 'take ownership of an existing non-peaks-managed server entry')
-        .option('--project <path>', 'project root for scoped scan')).action(async (options) => {
-        if (options.yes !== true) {
-            printResult(io, fail('mcp.apply', 'MCP_APPLY_REQUIRES_YES', 'Refusing to apply without --yes', { capabilityId: options.capability }, ['Re-run with --yes to confirm the write']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const applyOptions = {};
-            if (options.project !== undefined) {
-                applyOptions.projectRoot = options.project;
-            }
-            if (options.claim === true) {
-                applyOptions.claim = true;
-            }
-            const result = await applyMcpInstall(options.capability, applyOptions);
-            printResult(io, ok('mcp.apply', result), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.apply', 'MCP_APPLY_FAILED', getErrorMessage(error), { capabilityId: options.capability }, ['Check the plan first with peaks mcp plan, then re-run apply']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(mcp
-        .command('rollback')
-        .description('Restore Claude Code settings.json from a peaks-managed MCP backup file')
-        .requiredOption('--backup <path>', 'path to a previously created backup settings.json')).action(async (options) => {
-        try {
-            const result = await rollbackMcpInstall({ backupPath: options.backup });
-            printResult(io, ok('mcp.rollback', result), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.rollback', 'MCP_ROLLBACK_FAILED', getErrorMessage(error), { backupPath: options.backup }, ['Verify the backup path and rerun']), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(mcp
-        .command('call')
-        .description('Invoke a tool on an installed MCP server via stdio (spawns the server, calls tools/call, closes)')
-        .requiredOption('--capability <id>', 'capability id from the MCP install registry')
-        .requiredOption('--tool <name>', 'MCP tool name to invoke')
-        .option('--args <path>', 'path to a JSON file describing the tool arguments object')
-        .option('--args-json <jsonString>', 'inline JSON object describing the tool arguments')
-        .option('--timeout <ms>', 'per-request timeout in milliseconds', parsePositiveInteger)).action(async (options) => {
-        try {
-            const args = await resolveCallArgs(options);
-            const factory = createStdioTransportFromSpec;
-            const callOptions = {
-                capabilityId: options.capability,
-                toolName: options.tool,
-                args,
-                transportFactory: factory
-            };
-            if (options.timeout !== undefined) {
-                callOptions.timeoutMs = Number(options.timeout);
-            }
-            const result = await callMcpTool(callOptions);
-            printResult(io, ok('mcp.call', result), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('mcp.call', 'MCP_CALL_FAILED', getErrorMessage(error), { capabilityId: options.capability, toolName: options.tool }, ['Check the capability id, tool name, args JSON, and required env vars before retrying']), options.json);
-            process.exitCode = 1;
-        }
-    });
-}

package/dist/src/cli/commands/progress-close-kill.d.ts

@@ -1,51 +0,0 @@
-/**
- * Best-effort close of a spawned `peaks progress watch`
- * window. Used by `peaks progress close` (manual escape
- * hatch) and by the watch-side auto-exit when the sub-agent
- * hits a terminal phase.
- *
- * The close is best-effort by design: we never throw from
- * individual signals. One failed close primitive is a UX
- * paper cut, not a correctness bug — the caller still clears
- * the spawn record after this returns.
- *
- * Cross-platform strategy:
- *
- *   - macOS: pkill the watch process by command pattern
- *     (matches the project path, so we never close the
- *     wrong window), then send AppleScript to Terminal.app
- *     to close the window by `custom title`. Terminal.app
- *     is the dominant macOS terminal, and `custom title` is
- *     the only stable identifier we can target from outside
- *     the running shell.
- *   - Linux: pkill the watch process, then try `wmctrl -c
- *     peaks-cli-progress` to close the terminal window by
- *     WM class (set in `progress start` for alacritty /
- *     kitty; gnome-terminal / konsole / xfce4-terminal
- *     close on their own when the child exits). wmctrl is
- *     not always installed; we silently no-op on
- *     "command not found" (exit 127) and surface other
- *     errors as warnings.
- *   - Windows: `taskkill /F /FI "WINDOWTITLE eq
- *     peaks-cli:*"` to kill the cmd.exe wrapper. We use
- *     the title prefix because the exact title includes the
- *     `--reason` suffix which we do not know here.
- *
- * The kill is intentionally not a single primitive (e.g.
- * `process.kill(-pid, 'SIGTERM')` on the process group).
- * The launcher's PID is the spawn-time PID (osascript on
- * macOS, gnome-terminal on Linux), not the long-lived
- * watch process — and the long-lived process is the one we
- * actually need to terminate to make the terminal close.
- * Targeting by command pattern (pkill) + window title
- * (AppleScript / wmctrl / taskkill) is more reliable than
- * PID chasing across detached children.
- */
-import type { ProgressSpawnRecord } from '../../services/progress/progress-service.js';
-export type KillSpawnedTerminalResult = {
-    /** Each signal that was successfully sent. */
-    signals: string[];
-    /** Soft failures (e.g. pkill matched no process, wmctrl missing). */
-    warnings: string[];
-};
-export declare function killSpawnedTerminal(record: ProgressSpawnRecord, canonicalProjectRoot: string, currentPlatform: NodeJS.Platform): Promise<KillSpawnedTerminalResult>;

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

@@ -1,152 +0,0 @@
-/**
- * Best-effort close of a spawned `peaks progress watch`
- * window. Used by `peaks progress close` (manual escape
- * hatch) and by the watch-side auto-exit when the sub-agent
- * hits a terminal phase.
- *
- * The close is best-effort by design: we never throw from
- * individual signals. One failed close primitive is a UX
- * paper cut, not a correctness bug — the caller still clears
- * the spawn record after this returns.
- *
- * Cross-platform strategy:
- *
- *   - macOS: pkill the watch process by command pattern
- *     (matches the project path, so we never close the
- *     wrong window), then send AppleScript to Terminal.app
- *     to close the window by `custom title`. Terminal.app
- *     is the dominant macOS terminal, and `custom title` is
- *     the only stable identifier we can target from outside
- *     the running shell.
- *   - Linux: pkill the watch process, then try `wmctrl -c
- *     peaks-cli-progress` to close the terminal window by
- *     WM class (set in `progress start` for alacritty /
- *     kitty; gnome-terminal / konsole / xfce4-terminal
- *     close on their own when the child exits). wmctrl is
- *     not always installed; we silently no-op on
- *     "command not found" (exit 127) and surface other
- *     errors as warnings.
- *   - Windows: `taskkill /F /FI "WINDOWTITLE eq
- *     peaks-cli:*"` to kill the cmd.exe wrapper. We use
- *     the title prefix because the exact title includes the
- *     `--reason` suffix which we do not know here.
- *
- * The kill is intentionally not a single primitive (e.g.
- * `process.kill(-pid, 'SIGTERM')` on the process group).
- * The launcher's PID is the spawn-time PID (osascript on
- * macOS, gnome-terminal on Linux), not the long-lived
- * watch process — and the long-lived process is the one we
- * actually need to terminate to make the terminal close.
- * Targeting by command pattern (pkill) + window title
- * (AppleScript / wmctrl / taskkill) is more reliable than
- * PID chasing across detached children.
- */
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { getErrorMessage } from '../cli-helpers.js';
-const execFileAsync = promisify(execFile);
-export async function killSpawnedTerminal(record, canonicalProjectRoot, currentPlatform) {
-    const signals = [];
-    const warnings = [];
-    // The watch command we spawned, escaped for use as a pkill
-    // pattern. We anchor on `progress watch` (NOT `peaks progress
-    // watch`) because the actual cmdline is `.../peaks.js progress
-    // watch --project /path` — the literal substring
-    // `peaks progress watch` does NOT appear in the cmdline
-    // (there is a `.js` between `peaks` and `progress`).
-    // Anchoring on the verb + the project path is specific
-    // enough to not hit any user-owned `progress watch` process
-    // for a different project.
-    const watchPattern = `progress watch.*--project ${canonicalProjectRoot.replace(/[\\"\s]/g, '\\$&')}`;
-    if (currentPlatform === 'darwin') {
-        // pkill exit codes: 0 = matched & signalled, 1 = no processes
-        // matched (silent miss), 2 = syntax error (warning), 3 = fatal
-        // (warning). macOS pkill writes nothing to stderr on a clean
-        // miss, so the exit code is the only signal we have.
-        await trySignal('pkill', ['-f', watchPattern], signals, 'pkill-watch', warnings, /no.*process/i, new Set([1]));
-        // AppleScript to close the Terminal.app window by
-        // custom title. We use `every window whose custom title
-        // is` so we only close the right tab. AppleScript returns
-        // a non-zero exit when the window is already gone, the
-        // app is not running, or the title does not match — all
-        // of which are silent misses from the user's perspective
-        // (the user-facing outcome is identical to the success
-        // case: the window is no longer visible). Treat any
-        // non-zero exit as silent.
-        try {
-            const escapedTitle = record.windowTitle.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
-            await execFileAsync('osascript', [
-                '-e',
-                `tell application "Terminal" to close (every window whose custom title is "${escapedTitle}")`
-            ]);
-            signals.push('osascript-close-window');
-        }
-        catch {
-            // Silent miss. See comment above.
-        }
-    }
-    else if (currentPlatform === 'linux') {
-        // Same pkill exit code semantics as macOS.
-        await trySignal('pkill', ['-f', watchPattern], signals, 'pkill-watch', warnings, /no.*process/i, new Set([1]));
-        // wmctrl by WM class (set in `progress start`). Missing
-        // wmctrl is silent (exit 127) — most distros ship it but
-        // headless / minimal installs do not.
-        await trySignal('wmctrl', ['-c', 'peaks-cli-progress'], signals, 'wmctrl-close-class', warnings, /not found|No such file/i, new Set([127]));
-    }
-    else if (currentPlatform === 'win32') {
-        // Title prefix is set in `progress start` to `peaks-cli:`.
-        // We match the prefix because the full title includes
-        // the `--reason` suffix which we do not know here.
-        // taskkill exit codes: 0 = success, 1 = no tasks matched
-        // (silent miss — the window is already gone), 128 = error.
-        const titlePrefix = 'peaks-cli:';
-        await trySignal('taskkill', ['/F', '/FI', `WINDOWTITLE eq ${titlePrefix}*`], signals, 'taskkill-window-title', warnings, /no.*task/i, new Set([1]));
-    }
-    else {
-        warnings.push(`unsupported platform: ${currentPlatform}`);
-    }
-    return { signals, warnings };
-}
-/**
- * Run a single close primitive. If it throws AND either
- *   (a) the error matches the "expected" stderr pattern
- *       (e.g. "no process matched" for pkill, "command not
- *       found" for wmctrl) — most platforms print this on
- *       stderr; or
- *   (b) the exit code is in `silentMissExitCodes` (pkill 1,
- *       wmctrl 127, taskkill 1) — the primitive ran, found
- *       nothing, and is not telling us via stderr,
- * we silently no-op — that is the success case for the
- * primitive. Other errors are appended to `warnings` for
- * the caller to surface. On a clean resolve, the named
- * signal is appended to `signals`.
- */
-async function trySignal(command, args, signals, signal, warnings, expectedFailurePattern, silentMissExitCodes) {
-    try {
-        await execFileAsync(command, args);
-    }
-    catch (error) {
-        // execFile's error object exposes `code` as either a
-        // numeric exit code (when the process ran) or a string
-        // system code like 'ENOENT' (when the binary itself
-        // is missing). Only numeric exit codes are candidates
-        // for silent-miss.
-        const execError = error;
-        if (typeof execError.code === 'number' && silentMissExitCodes.has(execError.code)) {
-            // Exit code says "ran, but found nothing to act on".
-            // The user-facing outcome is identical to the success
-            // case, so do not surface a warning.
-            return;
-        }
-        const message = getErrorMessage(error);
-        if (expectedFailurePattern.test(message)) {
-            return;
-        }
-        warnings.push(`${command}: ${message}`);
-        return;
-    }
-    // Reached only if execFile resolves (exit 0). All three
-    // primitives exit non-zero on a miss, so a clean resolve
-    // means the signal landed.
-    signals.push(signal);
-}

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

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