gsd-pi 2.27.0 → 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,6 +59,7 @@ 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
@@ -141,21 +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. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too.
+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.
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-9. **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.
+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.
 
-10. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
+11. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
 
-11. **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.
+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
 
@@ -247,14 +271,14 @@ gsd headless new-milestone --context spec.md --auto
 # One unit at a time (cron-friendly)
 gsd headless next
 
-# Machine-readable JSONL event stream
-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. Auto-restarts on crash with exponential backoff. 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.
 
@@ -282,6 +306,7 @@ 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)                  |
@@ -295,6 +320,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `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 |
 
@@ -414,7 +440,8 @@ auto_report: 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)                                               |

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) {
@@ -427,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;
+    }
+}

package/dist/headless-context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Headless Context Loading — stdin reading, file context, and project bootstrapping
+ *
+ * Handles loading context from files or stdin for headless new-milestone,
+ * and bootstraps the .gsd/ directory structure when needed.
+ */
+interface ContextOptions {
+    context?: string;
+    contextText?: string;
+}
+export declare function readStdin(): Promise<string>;
+export declare function loadContext(options: ContextOptions): Promise<string>;
+/**
+ * Bootstrap .gsd/ directory structure for headless new-milestone.
+ * Mirrors the bootstrap logic from guided-flow.ts showSmartEntry().
+ */
+export declare function bootstrapGsdProject(basePath: string): void;
+export {};

package/dist/headless-context.js

@@ -0,0 +1,44 @@
+/**
+ * Headless Context Loading — stdin reading, file context, and project bootstrapping
+ *
+ * Handles loading context from files or stdin for headless new-milestone,
+ * and bootstraps the .gsd/ directory structure when needed.
+ */
+import { readFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// ---------------------------------------------------------------------------
+// Stdin Reader
+// ---------------------------------------------------------------------------
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+// ---------------------------------------------------------------------------
+// Context Loading
+// ---------------------------------------------------------------------------
+export async function loadContext(options) {
+    if (options.contextText)
+        return options.contextText;
+    if (options.context === '-') {
+        return readStdin();
+    }
+    if (options.context) {
+        return readFileSync(resolve(options.context), 'utf-8');
+    }
+    throw new Error('No context provided. Use --context <file> or --context-text <text>');
+}
+// ---------------------------------------------------------------------------
+// Project Bootstrap
+// ---------------------------------------------------------------------------
+/**
+ * Bootstrap .gsd/ directory structure for headless new-milestone.
+ * Mirrors the bootstrap logic from guided-flow.ts showSmartEntry().
+ */
+export function bootstrapGsdProject(basePath) {
+    const gsdDir = join(basePath, '.gsd');
+    mkdirSync(join(gsdDir, 'milestones'), { recursive: true });
+    mkdirSync(join(gsdDir, 'runtime'), { recursive: true });
+}

package/dist/headless-events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Headless Event Detection — notification classification and command detection
+ *
+ * Detects terminal notifications, blocked notifications, milestone-ready signals,
+ * and classifies commands as quick (single-turn) vs long-running.
+ */
+/**
+ * Detect genuine auto-mode termination notifications.
+ *
+ * Only matches the actual stop signals emitted by stopAuto():
+ *   "Auto-mode stopped..."
+ *   "Step-mode stopped..."
+ *
+ * Does NOT match progress notifications that happen to contain words like
+ * "complete" or "stopped" (e.g., "Override resolved — rewrite-docs completed",
+ * "All slices are complete — nothing to discuss", "Skipped 5+ completed units").
+ *
+ * Blocked detection is separate — checked via isBlockedNotification.
+ */
+export declare const TERMINAL_PREFIXES: string[];
+export declare const IDLE_TIMEOUT_MS = 15000;
+export declare const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120000;
+export declare function isTerminalNotification(event: Record<string, unknown>): boolean;
+export declare function isBlockedNotification(event: Record<string, unknown>): boolean;
+export declare function isMilestoneReadyNotification(event: Record<string, unknown>): boolean;
+export declare const FIRE_AND_FORGET_METHODS: Set<string>;
+export declare const QUICK_COMMANDS: Set<string>;
+export declare function isQuickCommand(command: string): boolean;