gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/README.md

@@ -18,10 +18,32 @@ 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.29
+
+- **Node.js 24 LTS** — CI, Docker, and package config all upgraded to Node 24 (Krypton)
+- **`searchExcludeDirs` setting** — blacklist directories from `@` file autocomplete (e.g., `node_modules`, `dist`)
+- **Automated releases** — prod-release now auto-generates changelogs, bumps versions, and publishes to npm
+- **`/gsd logs`** — browse activity, debug, and metrics logs from within a session
+- **Configurable screenshots** — browser-tools now support custom resolution, format, and quality
+- **Pre-commit secret scanning** — automatic detection of hardcoded secrets in CI and locally
+- **Per-project MCP config** — `.gsd/mcp.json` for project-scoped MCP server definitions
+- **API request metrics** — track request counts for Copilot/subscription users
+- **`/gsd keys`** — full API key lifecycle management (list, add, remove, test, rotate, doctor)
+- **Advisory verification gate** — auto-discovered checks (lint/test from package.json) no longer doom-loop on pre-existing errors
+- **Worktree living doc sync** — DECISIONS, REQUIREMENTS, PROJECT, and KNOWLEDGE now sync between worktree and project root
+- **Windows non-ASCII path support** — `cpSync` fallback for usernames with special characters
+- **`needs-discussion` routing** — milestones with draft context now route to the interactive discussion flow instead of stopping
+
+See the full [Changelog](./CHANGELOG.md) for details.
+
+---
+
 ## Documentation
 
 Full documentation is available in the [`docs/`](./docs/) directory:
@@ -38,8 +60,11 @@ 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
+- **[Remote Questions](./docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed
+- **[Dynamic Model Routing](./docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure
 - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
 
 ---
@@ -153,7 +178,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 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.
 
-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. **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. Auto-discovered checks from `package.json` run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
 
 11. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
 
@@ -284,6 +309,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 logs`             | Browse activity, debug, and metrics logs                        |
 | `/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)                  |
@@ -424,6 +451,7 @@ auto_report: 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)                                 |
+| `searchExcludeDirs`    | Directories to exclude from `@` file autocomplete (e.g., `["node_modules", ".git", "dist"]`)          |
 
 ### Agent Instructions
 
@@ -455,7 +483,7 @@ See the full [Token Optimization Guide](./docs/token-optimization.md) for detail
 
 ### Bundled Tools
 
-GSD ships with 14 extensions, all loaded automatically:
+GSD ships with 16 extensions, all loaded automatically:
 
 | Extension              | What it provides                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -467,12 +495,14 @@ GSD ships with 14 extensions, all loaded automatically:
 | **Background Shell**   | Long-running process management with readiness detection                                                               |
 | **Subagent**           | Delegated tasks with isolated context windows                                                                          |
 | **Mac Tools**          | macOS native app automation via Accessibility APIs                                                                     |
-| **MCPorter**           | Lazy on-demand MCP server integration                                                                                  |
+| **MCP Client**         | Native MCP server integration via @modelcontextprotocol/sdk                                                            |
 | **Voice**              | Real-time speech-to-text transcription (macOS, Linux — Ubuntu 22.04+)                                                  |
 | **Slash Commands**     | Custom command creation                                                                                                |
 | **LSP**                | Language Server Protocol integration — diagnostics, go-to-definition, references, hover, symbols, rename, code actions |
 | **Ask User Questions** | Structured user input with single/multi-select                                                                         |
 | **Secure Env Collect** | Masked secret collection without manual .env editing                                                                   |
+| **Remote Questions**   | Route decisions to Slack/Discord when human input is needed in headless/CI mode                                         |
+| **Universal Config**   | Discover and import MCP servers and rules from other AI coding tools                                                    |
 
 ### Bundled Agents
 
@@ -574,7 +604,7 @@ gsd (CLI binary)
 
 ## Requirements
 
-- **Node.js** ≥ 20.6.0 (22+ recommended)
+- **Node.js** ≥ 22.0.0 (24 LTS recommended)
 - **An LLM provider** — any of the 20+ supported providers (see [Use Any Model](#use-any-model))
 - **Git** — initialized automatically if missing
 

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;