gsd-pi 2.26.1-next.1 → 2.28.0-dev.346ee62

package/README.md

@@ -18,10 +18,31 @@ One command. Walk away. Come back to a built project with clean git history.
 
 <pre><code>npm install -g gsd-pi</code></pre>
 
+> **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](./docs/node-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues.
+
 </div>
 
 ---
 
+## What's New in v2.28
+
+- **`gsd headless query`** — instant JSON snapshot of project state (~50ms, no LLM session)
+- **`/gsd update`** — update GSD to the latest version without leaving your session
+- **`/gsd export --html --all`** — generate retrospective HTML reports for all milestones at once
+- **Reliability hardening** — atomic file writes, OAuth fetch timeouts, RPC exit detection, blob GC, LSP init retry with backoff
+- **RPC utilities** now part of the public API for headless/scripted integrations
+- **npm** established as the canonical package manager
+- **CI/CD Pipeline** — three-stage promotion (Dev → Test → Prod) with automated versioning
+- **Docker support** — containerized builds with multi-stage Dockerfile
+- **`/gsd keys`** — full API key lifecycle management (list, add, remove, test, rotate, doctor)
+- **Milestone parking** — park in-progress milestones to work on something else, unpark to resume
+- **Studio** — experimental Electron desktop app (early preview)
+- **Per-project MCP config** — `.gsd/mcp.json` for project-scoped MCP server definitions
+
+See the full [Changelog](./CHANGELOG.md) for details.
+
+---
+
 ## Documentation
 
 Full documentation is available in the [`docs/`](./docs/) directory:
@@ -38,7 +59,9 @@ Full documentation is available in the [`docs/`](./docs/) directory:
 - **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts
 - **[Architecture](./docs/architecture.md)** — system design and dispatch pipeline
 - **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, forensics, recovery
+- **[CI/CD Pipeline](./docs/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod)
 - **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
+- **[Visualizer](./docs/visualizer.md)** — workflow visualizer with stats and discussion status
 - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
 
 ---
@@ -67,6 +90,9 @@ GSD v2 solves all of these because it's not a prompt framework anymore — it's
 | Context injection    | "Read this file"             | Pre-inlined into dispatch prompt                        |
 | Roadmap reassessment | Manual                       | Automatic after each slice completes                    |
 | Skill discovery      | None                         | Auto-detect and install relevant skills during research |
+| Verification         | Manual                       | Automated verification commands with auto-fix retries   |
+| Reporting            | None                         | Self-contained HTML reports with metrics and dep graphs  |
+| Parallel execution   | None                         | Multi-worker parallel milestone orchestration            |
 
 ### Migrating from v1
 
@@ -117,7 +143,7 @@ Research → Plan → Execute (per task) → Complete → Reassess Roadmap → N
                                                               Validate Milestone → Complete Milestone
 ```
 
-**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
 ### `/gsd auto` — The Main Event
 
@@ -137,17 +163,23 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 3. **Git worktree isolation** — Each milestone runs in its own git worktree with a `milestone/<MID>` branch. All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit.
 
-4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context.
+4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
+
+5. **Provider error recovery** — Transient provider errors (rate limits, 500/503 server errors, overloaded) auto-resume after a delay. Permanent errors (auth, billing) pause for manual review. The model fallback chain retries transient network errors before switching models.
+
+6. **Stuck detection** — If the same unit dispatches twice (the LLM didn't produce the expected artifact), it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.
 
-5. **Stuck detection** — If the same unit dispatches twice (the LLM didn't produce the expected artifact), it retries once with a deep diagnostic. If it fails again, auto mode stops with the exact file it expected.
+7. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
 
-6. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
+8. **Cost tracking** — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.
 
-7. **Cost tracking** — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.
+9. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
 
-8. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
+10. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
 
-9. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
+11. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
+
+12. **Escape hatch** — Press Escape to pause. The conversation is preserved. Interact with the agent, inspect what happened, or just `/gsd auto` to resume from disk state.
 
 ### `/gsd` and `/gsd next` — Step Mode
 
@@ -233,17 +265,22 @@ Both terminals read and write the same `.gsd/` files on disk. Your decisions in
 # Run auto mode in CI
 gsd headless --timeout 600000
 
+# Create and execute a milestone end-to-end
+gsd headless new-milestone --context spec.md --auto
+
 # One unit at a time (cron-friendly)
 gsd headless next
 
-# Machine-readable status
-gsd headless --json status
+# Instant JSON snapshot (no LLM, ~50ms)
+gsd headless query
 
 # Force a specific pipeline phase
 gsd headless dispatch plan
 ```
 
-Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Pair with [remote questions](./docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
+Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Auto-restarts on crash with exponential backoff. Use `gsd headless query` for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with [remote questions](./docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed.
+
+**Multi-session orchestration** — headless mode supports file-based IPC in `.gsd/parallel/` for coordinating multiple GSD workers across milestones. Build orchestrators that spawn, monitor, and budget-cap a fleet of GSD workers.
 
 ### First launch
 
@@ -269,6 +306,8 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd forensics`        | Post-mortem investigation of auto-mode failures                 |
 | `/gsd cleanup`          | Archive phase directories from completed milestones             |
 | `/gsd doctor`           | Runtime health checks with auto-fix for common issues           |
+| `/gsd keys`             | API key manager — list, add, remove, test, rotate, doctor       |
+| `/gsd export --html`    | Generate HTML report for current or completed milestone         |
 | `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove          |
 | `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                  |
 | `/exit`                 | Graceful shutdown — saves session state before exiting          |
@@ -277,9 +316,11 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `Ctrl+Alt+G`            | Toggle dashboard overlay                                        |
 | `Ctrl+Alt+V`            | Toggle voice transcription                                      |
 | `Ctrl+Alt+B`            | Show background shell processes                                 |
+| `Alt+V`                 | Paste clipboard image (macOS)                                   |
 | `gsd config`            | Re-run the setup wizard (LLM provider + tool keys)              |
 | `gsd update`            | Update GSD to the latest version                                |
 | `gsd headless [cmd]`    | Run `/gsd` commands without TUI (CI, cron, scripts)             |
+| `gsd headless query`    | Instant JSON snapshot — state, next dispatch, costs (no LLM)    |
 | `gsd --continue` (`-c`) | Resume the most recent session for the current directory        |
 | `gsd sessions`          | Interactive session picker — browse and resume any saved session |
 
@@ -321,7 +362,7 @@ gsd/M001/S01 (deleted after merge):
   feat(S01/T01): core types and interfaces
 ```
 
-One squash commit per milestone on main (or whichever branch you started from). The worktree is torn down after merge. Git bisect works. Individual milestones are revertable.
+One squash commit per milestone on main (or whichever branch you started from). The worktree is torn down after merge. Git bisect works. Individual milestones are revertable. Commit messages are generated from task summaries — no more generic "complete task" messages.
 
 ### Verification
 
@@ -343,6 +384,15 @@ The verification ladder: static checks → command execution → behavioral test
 - Cost projections based on completed work
 - Completed and in-progress units
 
+### HTML Reports
+
+After a milestone completes, GSD auto-generates a self-contained HTML report in `.gsd/reports/`. Each report includes project summary, progress tree, slice dependency graph (SVG DAG), cost/token metrics with bar charts, execution timeline, changelog, and knowledge base sections. No external dependencies — all CSS and JS are inlined, printable to PDF from any browser.
+
+An auto-generated `index.html` shows all reports with progression metrics across milestones.
+
+- **Automatic** — generated after milestone completion (configurable via `auto_report` preference)
+- **Manual** — run `/gsd export --html` anytime
+
 ---
 
 ## Configuration
@@ -370,6 +420,10 @@ auto_supervisor:
   hard_timeout_minutes: 30
 budget_ceiling: 50.00
 unique_milestone_ids: true
+verification_commands:
+  - npm run lint
+  - npm run test
+auto_report: true
 ---
 ```
 
@@ -386,7 +440,13 @@ unique_milestone_ids: true
 | `skill_rules`          | Situational rules for skill routing                                                                   |
 | `skill_staleness_days` | Skills unused for N days get deprioritized (default: 60, 0 = disabled)                                |
 | `unique_milestone_ids` | Uses unique milestone names to avoid clashes when working in teams of people                          |
-| `git.isolation`        | `worktree` (default) or `none` — disable worktree isolation for projects that don't need it           |
+| `git.isolation`        | `worktree` (default), `branch`, or `none` — disable worktree isolation for projects that don't need it           |
+| `git.manage_gitignore` | Set `false` to prevent GSD from modifying `.gitignore`                                                           |
+| `verification_commands`| Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
+| `verification_auto_fix`| Auto-retry on verification failures (default: true)                                                   |
+| `verification_max_retries` | Max retries for verification failures (default: 2)                                               |
+| `require_slice_discussion` | Pause auto-mode before each slice for human discussion review                                    |
+| `auto_report`          | Auto-generate HTML reports after milestone completion (default: true)                                 |
 
 ### Agent Instructions
 
@@ -471,6 +531,10 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/runtime/
 # Git worktree working copies
 .gsd/worktrees/
+# Parallel orchestration IPC and worker status
+.gsd/parallel/
+# Generated HTML reports (regenerable via /gsd export --html)
+.gsd/reports/
 # Session-specific interrupted-work markers
 .gsd/milestones/**/continue.md
 .gsd/milestones/**/*-CONTINUE.md

package/dist/cli.js

@@ -8,7 +8,7 @@ import { loadStoredEnvKeys } from './wizard.js';
 import { getPiDefaultModelAndProvider, migratePiCredentials } from './pi-migration.js';
 import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
-import { checkForUpdates, checkAndPromptForUpdates } from './update-check.js';
+import { checkForUpdates } from './update-check.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 function exitIfManagedResourcesAreNewer(currentAgentDir) {
     const currentVersion = process.env.GSD_VERSION || '0.0.0';
@@ -71,6 +71,21 @@ function parseCliArgs(argv) {
 }
 const cliFlags = parseCliArgs(process.argv);
 const isPrintMode = cliFlags.print || cliFlags.mode !== undefined;
+// Early resource-skew check — must run before TTY gate so version mismatch
+// errors surface even in non-TTY environments.
+exitIfManagedResourcesAreNewer(agentDir);
+// Early TTY check — must come before heavy initialization to avoid dangling
+// handles that prevent process.exit() from completing promptly.
+const hasSubcommand = cliFlags.messages.length > 0;
+if (!process.stdin.isTTY && !isPrintMode && !hasSubcommand && !cliFlags.listModels) {
+    process.stderr.write('[gsd] Error: Interactive mode requires a terminal (TTY).\n');
+    process.stderr.write('[gsd] Non-interactive alternatives:\n');
+    process.stderr.write('[gsd]   gsd --print "your message"     Single-shot prompt\n');
+    process.stderr.write('[gsd]   gsd --mode rpc                 JSON-RPC over stdin/stdout\n');
+    process.stderr.write('[gsd]   gsd --mode mcp                 MCP server over stdin/stdout\n');
+    process.stderr.write('[gsd]   gsd --mode text "message"      Text output mode\n');
+    process.exit(1);
+}
 // `gsd <subcommand> --help` — show subcommand-specific help
 const subcommand = cliFlags.messages[0];
 if (subcommand && process.argv.includes('--help')) {
@@ -169,18 +184,11 @@ if (!isPrintMode && shouldRunOnboarding(authStorage, settingsManager.getDefaultP
         process.stdin.setRawMode(false);
     process.stdin.pause();
 }
-// Update check — interactive prompt when stdin is a TTY, passive banner otherwise
+// Update check — non-blocking banner check; interactive prompt deferred to avoid
+// blocking startup. The passive checkForUpdates() prints a banner if an update is
+// available (using cached data or a background fetch) without blocking the TUI.
 if (!isPrintMode) {
-    if (process.stdin.isTTY) {
-        const updated = await checkAndPromptForUpdates().catch(() => false);
-        if (updated) {
-            // User chose to update — exit so they relaunch with the new version
-            process.exit(0);
-        }
-    }
-    else {
-        checkForUpdates().catch(() => { });
-    }
+    checkForUpdates().catch(() => { });
 }
 // Warn if terminal is too narrow for readable output
 if (!isPrintMode && process.stdout.columns && process.stdout.columns < 40) {
@@ -239,7 +247,9 @@ const configuredExists = configuredProvider && configuredModel &&
     allModels.some((m) => m.provider === configuredProvider && m.id === configuredModel);
 const configuredAvailable = configuredProvider && configuredModel &&
     availableModels.some((m) => m.provider === configuredProvider && m.id === configuredModel);
-if (!configuredModel || !configuredExists || !configuredAvailable) {
+if (!configuredModel || !configuredExists) {
+    // Model not configured at all, or removed from registry — pick a fallback.
+    // Only fires when the model is genuinely unknown (not just temporarily unavailable).
     const piDefault = getPiDefaultModelAndProvider();
     const preferred = (piDefault
         ? availableModels.find((m) => m.provider === piDefault.provider && m.id === piDefault.model)
@@ -254,7 +264,7 @@ if (!configuredModel || !configuredExists || !configuredAvailable) {
         settingsManager.setDefaultModelAndProvider(preferred.provider, preferred.id);
     }
 }
-if (settingsManager.getDefaultThinkingLevel() !== 'off' && (!configuredExists || !configuredAvailable)) {
+if (settingsManager.getDefaultThinkingLevel() !== 'off' && !configuredExists) {
     settingsManager.setDefaultThinkingLevel('off');
 }
 // GSD always uses quiet startup — the gsd extension renders its own branded header
@@ -425,14 +435,5 @@ if (enabledModelPatterns && enabledModelPatterns.length > 0) {
         session.setScopedModels(scopedModels);
     }
 }
-if (!process.stdin.isTTY) {
-    process.stderr.write('[gsd] Error: Interactive mode requires a terminal (TTY).\n');
-    process.stderr.write('[gsd] Non-interactive alternatives:\n');
-    process.stderr.write('[gsd]   gsd --print "your message"     Single-shot prompt\n');
-    process.stderr.write('[gsd]   gsd --mode rpc                 JSON-RPC over stdin/stdout\n');
-    process.stderr.write('[gsd]   gsd --mode mcp                 MCP server over stdin/stdout\n');
-    process.stderr.write('[gsd]   gsd --mode text "message"      Text output mode\n');
-    process.exit(1);
-}
 const interactiveMode = new InteractiveMode(session);
 await interactiveMode.run();

package/dist/extension-discovery.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolves the entry-point file(s) for a single extension directory.
+ *
+ * 1. If the directory contains a package.json with a `pi.extensions` array,
+ *    each entry is resolved relative to the directory and returned (if it exists).
+ * 2. Otherwise falls back to `index.ts` → `index.js`.
+ */
+export declare function resolveExtensionEntries(dir: string): string[];
+/**
+ * Discovers all extension entry-point paths under an extensions directory.
+ *
+ * - Top-level .ts/.js files are treated as standalone extension entry points.
+ * - Subdirectories are resolved via `resolveExtensionEntries()` (package.json →
+ *   pi.extensions, then index.ts/index.js fallback).
+ */
+export declare function discoverExtensionEntryPaths(extensionsDir: string): string[];

package/dist/extension-discovery.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+function isExtensionFile(name) {
+    return name.endsWith('.ts') || name.endsWith('.js');
+}
+/**
+ * Resolves the entry-point file(s) for a single extension directory.
+ *
+ * 1. If the directory contains a package.json with a `pi.extensions` array,
+ *    each entry is resolved relative to the directory and returned (if it exists).
+ * 2. Otherwise falls back to `index.ts` → `index.js`.
+ */
+export function resolveExtensionEntries(dir) {
+    const packageJsonPath = join(dir, 'package.json');
+    if (existsSync(packageJsonPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const declared = pkg?.pi?.extensions;
+            if (Array.isArray(declared)) {
+                const resolved = declared
+                    .filter((entry) => typeof entry === 'string')
+                    .map((entry) => resolve(dir, entry))
+                    .filter((entry) => existsSync(entry));
+                if (resolved.length > 0) {
+                    return resolved;
+                }
+            }
+        }
+        catch {
+            // Ignore malformed manifests and fall back to index.ts/index.js discovery.
+        }
+    }
+    const indexTs = join(dir, 'index.ts');
+    if (existsSync(indexTs)) {
+        return [indexTs];
+    }
+    const indexJs = join(dir, 'index.js');
+    if (existsSync(indexJs)) {
+        return [indexJs];
+    }
+    return [];
+}
+/**
+ * Discovers all extension entry-point paths under an extensions directory.
+ *
+ * - Top-level .ts/.js files are treated as standalone extension entry points.
+ * - Subdirectories are resolved via `resolveExtensionEntries()` (package.json →
+ *   pi.extensions, then index.ts/index.js fallback).
+ */
+export function discoverExtensionEntryPaths(extensionsDir) {
+    if (!existsSync(extensionsDir)) {
+        return [];
+    }
+    const discovered = [];
+    for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
+        const entryPath = join(extensionsDir, entry.name);
+        if ((entry.isFile() || entry.isSymbolicLink()) && isExtensionFile(entry.name)) {
+            discovered.push(entryPath);
+            continue;
+        }
+        if (entry.isDirectory() || entry.isSymbolicLink()) {
+            discovered.push(...resolveExtensionEntries(entryPath));
+        }
+    }
+    return discovered;
+}

package/dist/headless-answers.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Answer Injector — pre-supply answers to headless mode questions.
+ *
+ * Loads a JSON answer file and intercepts extension_ui_request events
+ * to automatically respond with pre-configured answers, bypassing the
+ * default auto-responder or supervised mode.
+ */
+export interface AnswerFile {
+    questions?: Record<string, string | string[]>;
+    secrets?: Record<string, string>;
+    defaults?: {
+        strategy?: 'first_option' | 'cancel';
+    };
+}
+export interface AnswerInjectorStats {
+    questionsAnswered: number;
+    questionsDefaulted: number;
+    secretsProvided: number;
+}
+export declare function loadAndValidateAnswerFile(path: string): AnswerFile;
+export declare class AnswerInjector {
+    private readonly answerFile;
+    private readonly questionMetaByTitle;
+    private readonly deferredEvents;
+    private readonly usedQuestionIds;
+    private readonly usedSecretKeys;
+    private readonly stats;
+    constructor(answerFile: AnswerFile);
+    /**
+     * Observe every event for question metadata (tool_execution_start of ask_user_questions).
+     */
+    observeEvent(event: Record<string, unknown>): void;
+    /**
+     * Try to handle an extension_ui_request with pre-supplied answers.
+     * Returns true if the event was handled (or deferred for async handling).
+     */
+    tryHandle(event: Record<string, unknown>, writeToStdin: (data: string) => void): boolean;
+    /**
+     * Get secret environment variables to inject into the RPC child process.
+     */
+    getSecretEnvVars(): Record<string, string>;
+    /**
+     * Get a copy of the current stats.
+     */
+    getStats(): AnswerInjectorStats;
+    /**
+     * Get warnings for unused question IDs and secret keys.
+     */
+    getUnusedWarnings(): string[];
+    private processWithMeta;
+}

package/dist/headless-answers.js

@@ -0,0 +1,224 @@
+/**
+ * Answer Injector — pre-supply answers to headless mode questions.
+ *
+ * Loads a JSON answer file and intercepts extension_ui_request events
+ * to automatically respond with pre-configured answers, bypassing the
+ * default auto-responder or supervised mode.
+ */
+import { readFileSync } from 'node:fs';
+import { serializeJsonLine } from '@gsd/pi-coding-agent';
+// ---------------------------------------------------------------------------
+// Answer File Loader
+// ---------------------------------------------------------------------------
+export function loadAndValidateAnswerFile(path) {
+    const raw = readFileSync(path, 'utf-8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in answer file: ${path}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('Answer file must be a JSON object');
+    }
+    const obj = parsed;
+    if (obj.questions !== undefined) {
+        if (typeof obj.questions !== 'object' || obj.questions === null || Array.isArray(obj.questions)) {
+            throw new Error('Answer file "questions" must be an object');
+        }
+        const questions = obj.questions;
+        for (const [key, value] of Object.entries(questions)) {
+            if (typeof value === 'string')
+                continue;
+            if (Array.isArray(value) && value.every((v) => typeof v === 'string'))
+                continue;
+            throw new Error(`Answer file "questions.${key}" must be a string or string[]`);
+        }
+    }
+    if (obj.secrets !== undefined) {
+        if (typeof obj.secrets !== 'object' || obj.secrets === null || Array.isArray(obj.secrets)) {
+            throw new Error('Answer file "secrets" must be an object');
+        }
+        const secrets = obj.secrets;
+        for (const [key, value] of Object.entries(secrets)) {
+            if (typeof value !== 'string') {
+                throw new Error(`Answer file "secrets.${key}" must be a string`);
+            }
+        }
+    }
+    if (obj.defaults !== undefined) {
+        if (typeof obj.defaults !== 'object' || obj.defaults === null || Array.isArray(obj.defaults)) {
+            throw new Error('Answer file "defaults" must be an object');
+        }
+        const defaults = obj.defaults;
+        if (defaults.strategy !== undefined) {
+            if (defaults.strategy !== 'first_option' && defaults.strategy !== 'cancel') {
+                throw new Error('Answer file "defaults.strategy" must be "first_option" or "cancel"');
+            }
+        }
+    }
+    return obj;
+}
+export class AnswerInjector {
+    answerFile;
+    questionMetaByTitle = new Map();
+    deferredEvents = new Map();
+    usedQuestionIds = new Set();
+    usedSecretKeys = new Set();
+    stats = {
+        questionsAnswered: 0,
+        questionsDefaulted: 0,
+        secretsProvided: 0,
+    };
+    constructor(answerFile) {
+        this.answerFile = answerFile;
+    }
+    /**
+     * Observe every event for question metadata (tool_execution_start of ask_user_questions).
+     */
+    observeEvent(event) {
+        if (event.type !== 'tool_execution_start' || event.toolName !== 'ask_user_questions')
+            return;
+        // Extract questions from event.input.questions or event.args?.questions
+        const input = (event.input ?? event.args);
+        const questions = (input?.questions);
+        if (!Array.isArray(questions))
+            return;
+        for (const q of questions) {
+            const header = String(q.header ?? '');
+            const question = String(q.question ?? '');
+            const title = `${header}: ${question}`;
+            const options = Array.isArray(q.options)
+                ? q.options.map((o) => String(o.label ?? ''))
+                : [];
+            this.questionMetaByTitle.set(title, {
+                id: String(q.id ?? ''),
+                header,
+                question,
+                options,
+                allowMultiple: !!q.allowMultiple,
+            });
+        }
+        // Process any deferred events that now have metadata
+        for (const [title, deferred] of Array.from(this.deferredEvents)) {
+            if (this.questionMetaByTitle.has(title)) {
+                clearTimeout(deferred.timer);
+                this.deferredEvents.delete(title);
+                this.processWithMeta(deferred.event, deferred.writeToStdin);
+            }
+        }
+    }
+    /**
+     * Try to handle an extension_ui_request with pre-supplied answers.
+     * Returns true if the event was handled (or deferred for async handling).
+     */
+    tryHandle(event, writeToStdin) {
+        const method = String(event.method ?? '');
+        // Only handle 'select' — let auto-responder handle confirm, input, etc.
+        if (method !== 'select')
+            return false;
+        const title = String(event.title ?? '');
+        const meta = this.questionMetaByTitle.get(title);
+        if (meta) {
+            return this.processWithMeta(event, writeToStdin);
+        }
+        // No metadata yet (out-of-order) — defer and handle asynchronously
+        const strategy = this.answerFile.defaults?.strategy ?? 'first_option';
+        const timer = setTimeout(() => {
+            this.deferredEvents.delete(title);
+            this.stats.questionsDefaulted++;
+            if (strategy === 'cancel') {
+                const response = { type: 'extension_ui_response', id: event.id, cancelled: true };
+                writeToStdin(serializeJsonLine(response));
+            }
+            else {
+                // first_option — send first option as response
+                const options = event.options;
+                const response = { type: 'extension_ui_response', id: event.id, value: options?.[0] ?? '' };
+                writeToStdin(serializeJsonLine(response));
+            }
+        }, 500);
+        this.deferredEvents.set(title, { event, writeToStdin, timer });
+        return true;
+    }
+    /**
+     * Get secret environment variables to inject into the RPC child process.
+     */
+    getSecretEnvVars() {
+        return this.answerFile.secrets ?? {};
+    }
+    /**
+     * Get a copy of the current stats.
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Get warnings for unused question IDs and secret keys.
+     */
+    getUnusedWarnings() {
+        const warnings = [];
+        if (this.answerFile.questions) {
+            for (const id of Object.keys(this.answerFile.questions)) {
+                if (!this.usedQuestionIds.has(id)) {
+                    warnings.push(`[answers] Warning: question ID '${id}' was never matched`);
+                }
+            }
+        }
+        if (this.answerFile.secrets) {
+            for (const key of Object.keys(this.answerFile.secrets)) {
+                if (!this.usedSecretKeys.has(key)) {
+                    warnings.push(`[answers] Warning: secret '${key}' was provided but never requested`);
+                }
+            }
+        }
+        return warnings;
+    }
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+    processWithMeta(event, writeToStdin) {
+        const title = String(event.title ?? '');
+        const meta = this.questionMetaByTitle.get(title);
+        if (!meta)
+            return false;
+        const answer = this.answerFile.questions?.[meta.id];
+        const eventOptions = event.options;
+        if (answer !== undefined) {
+            if (meta.allowMultiple) {
+                // Multi-select: answer must be an array
+                const values = Array.isArray(answer) ? answer : [answer];
+                const valid = values.every((v) => eventOptions?.includes(v));
+                if (valid) {
+                    const response = { type: 'extension_ui_response', id: event.id, values };
+                    writeToStdin(serializeJsonLine(response));
+                    this.usedQuestionIds.add(meta.id);
+                    this.stats.questionsAnswered++;
+                    return true;
+                }
+            }
+            else {
+                // Single-select: answer must be a string in the options
+                const value = Array.isArray(answer) ? answer[0] : answer;
+                if (eventOptions?.includes(value)) {
+                    const response = { type: 'extension_ui_response', id: event.id, value };
+                    writeToStdin(serializeJsonLine(response));
+                    this.usedQuestionIds.add(meta.id);
+                    this.stats.questionsAnswered++;
+                    return true;
+                }
+            }
+        }
+        // Answer not found or not valid — apply default strategy
+        const strategy = this.answerFile.defaults?.strategy ?? 'first_option';
+        this.stats.questionsDefaulted++;
+        if (strategy === 'cancel') {
+            const response = { type: 'extension_ui_response', id: event.id, cancelled: true };
+            writeToStdin(serializeJsonLine(response));
+            return true;
+        }
+        // first_option: return false to let the auto-responder handle it
+        return false;
+    }
+}