gsd-pi 2.22.0 → 2.24.0

package/README.md

@@ -221,6 +221,26 @@ gsd
 
 Both terminals read and write the same `.gsd/` files on disk. Your decisions in terminal 2 are picked up automatically at the next phase boundary — no need to stop auto mode.
 
+### Headless mode — CI and scripts
+
+`gsd headless` runs any `/gsd` command without a TUI. Designed for CI pipelines, cron jobs, and scripted automation.
+
+```bash
+# Run auto mode in CI
+gsd headless --timeout 600000
+
+# One unit at a time (cron-friendly)
+gsd headless next
+
+# Machine-readable status
+gsd headless --json status
+
+# 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.
+
 ### First launch
 
 On first run, GSD launches a branded setup wizard that walks you through LLM provider selection (OAuth or API key), then optional tool API keys (Brave Search, Context7, Jina, Slack, Discord). Every step is skippable — press Enter to skip any. If you have an existing Pi installation, your provider credentials (LLM and tool keys) are imported automatically. Run `gsd config` anytime to re-run the wizard.
@@ -254,7 +274,10 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `Ctrl+Alt+V`            | Toggle voice transcription                                      |
 | `Ctrl+Alt+B`            | Show background shell processes                                 |
 | `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 --continue` (`-c`) | Resume the most recent session for the current directory        |
+| `gsd sessions`          | Interactive session picker — browse and resume any saved session |
 
 ---
 
@@ -396,7 +419,7 @@ GSD ships with 14 extensions, all loaded automatically:
 | Extension              | What it provides                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
 | **GSD**                | Core workflow engine, auto mode, commands, dashboard                                                                   |
-| **Browser Tools**      | Playwright-based browser with form intelligence, intent-ranked element finding, and semantic actions                   |
+| **Browser Tools**      | Playwright-based browser with form intelligence, intent-ranked element finding, semantic actions, PDF export, session state persistence, network mocking, device emulation, structured extraction, visual diffing, region zoom, test code generation, and prompt injection detection |
 | **Search the Web**     | Brave Search, Tavily, or Jina page extraction                                                                          |
 | **Google Search**      | Gemini-powered web search with AI-synthesized answers                                                                  |
 | **Context7**           | Up-to-date library/framework documentation                                                                             |
@@ -482,6 +505,7 @@ GSD is a TypeScript application that embeds the Pi coding agent SDK.
 gsd (CLI binary)
   └─ loader.ts          Sets PI_PACKAGE_DIR, GSD env vars, dynamic-imports cli.ts
       └─ cli.ts         Wires SDK managers, loads extensions, starts InteractiveMode
+          ├─ headless.ts     Headless orchestrator (spawns RPC child, auto-responds, detects completion)
           ├─ onboarding.ts   First-run setup wizard (LLM provider + tool keys)
           ├─ wizard.ts       Env hydration from stored auth.json credentials
           ├─ app-paths.ts    ~/.gsd/agent/, ~/.gsd/sessions/, auth.json

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 } from './update-check.js';
+import { checkForUpdates, checkAndPromptForUpdates } from './update-check.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 function exitIfManagedResourcesAreNewer(currentAgentDir) {
     const currentVersion = process.env.GSD_VERSION || '0.0.0';
@@ -91,6 +91,59 @@ if (cliFlags.messages[0] === 'update') {
     await runUpdate();
     process.exit(0);
 }
+// `gsd sessions` — list past sessions and pick one to resume
+if (cliFlags.messages[0] === 'sessions') {
+    const cwd = process.cwd();
+    const safePath = `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+    const projectSessionsDir = join(sessionsDir, safePath);
+    process.stderr.write(chalk.dim(`Loading sessions for ${cwd}...\n`));
+    const sessions = await SessionManager.list(cwd, projectSessionsDir);
+    if (sessions.length === 0) {
+        process.stderr.write(chalk.yellow('No sessions found for this directory.\n'));
+        process.exit(0);
+    }
+    process.stderr.write(chalk.bold(`\n  Sessions (${sessions.length}):\n\n`));
+    const maxShow = 20;
+    const toShow = sessions.slice(0, maxShow);
+    for (let i = 0; i < toShow.length; i++) {
+        const s = toShow[i];
+        const date = s.modified.toLocaleString();
+        const msgs = s.messageCount;
+        const name = s.name ? ` ${chalk.cyan(s.name)}` : '';
+        const preview = s.firstMessage
+            ? s.firstMessage.replace(/\n/g, ' ').substring(0, 80)
+            : chalk.dim('(empty)');
+        const num = String(i + 1).padStart(3);
+        process.stderr.write(`  ${chalk.bold(num)}. ${chalk.green(date)} ${chalk.dim(`(${msgs} msgs)`)}${name}\n`);
+        process.stderr.write(`       ${chalk.dim(preview)}\n\n`);
+    }
+    if (sessions.length > maxShow) {
+        process.stderr.write(chalk.dim(`  ... and ${sessions.length - maxShow} more\n\n`));
+    }
+    // Interactive selection
+    const readline = await import('node:readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    const answer = await new Promise((resolve) => {
+        rl.question(chalk.bold('  Enter session number to resume (or q to quit): '), resolve);
+    });
+    rl.close();
+    const choice = parseInt(answer, 10);
+    if (isNaN(choice) || choice < 1 || choice > toShow.length) {
+        process.stderr.write(chalk.dim('Cancelled.\n'));
+        process.exit(0);
+    }
+    const selected = toShow[choice - 1];
+    process.stderr.write(chalk.green(`\nResuming session from ${selected.modified.toLocaleString()}...\n\n`));
+    // Mark for the interactive session below to open this specific session
+    cliFlags.continue = true;
+    cliFlags._selectedSessionPath = selected.path;
+}
+// `gsd headless` — run auto-mode without TUI
+if (cliFlags.messages[0] === 'headless') {
+    const { runHeadless, parseHeadlessArgs } = await import('./headless.js');
+    await runHeadless(parseHeadlessArgs(process.argv));
+    process.exit(0);
+}
 // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
 // Provision local managed binaries first so Pi sees them without probing PATH.
@@ -98,7 +151,10 @@ ensureManagedTools(join(agentDir, 'bin'));
 const authStorage = AuthStorage.create(authFilePath);
 loadStoredEnvKeys(authStorage);
 migratePiCredentials(authStorage);
-const modelRegistry = new ModelRegistry(authStorage);
+// Resolve models.json path with fallback to ~/.pi/agent/models.json
+const { resolveModelsJsonPath } = await import('./models-resolver.js');
+const modelsJsonPath = resolveModelsJsonPath();
+const modelRegistry = new ModelRegistry(authStorage, modelsJsonPath);
 const settingsManager = SettingsManager.create(agentDir);
 // Run onboarding wizard on first launch (no LLM provider configured)
 if (!isPrintMode && shouldRunOnboarding(authStorage, settingsManager.getDefaultProvider())) {
@@ -113,9 +169,18 @@ if (!isPrintMode && shouldRunOnboarding(authStorage, settingsManager.getDefaultP
         process.stdin.setRawMode(false);
     process.stdin.pause();
 }
-// Non-blocking update check — runs at most once per 24h, fire-and-forget
+// Update check — interactive prompt when stdin is a TTY, passive banner otherwise
 if (!isPrintMode) {
-    checkForUpdates().catch(() => { });
+    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(() => { });
+    }
 }
 // Warn if terminal is too narrow for readable output
 if (!isPrintMode && process.stdout.columns && process.stdout.columns < 40) {
@@ -298,9 +363,11 @@ if (existsSync(sessionsDir)) {
         // Non-fatal — don't block startup if migration fails
     }
 }
-const sessionManager = cliFlags.continue
-    ? SessionManager.continueRecent(cwd, projectSessionsDir)
-    : SessionManager.create(cwd, projectSessionsDir);
+const sessionManager = cliFlags._selectedSessionPath
+    ? SessionManager.open(cliFlags._selectedSessionPath, projectSessionsDir)
+    : cliFlags.continue
+        ? SessionManager.continueRecent(cwd, projectSessionsDir)
+        : SessionManager.create(cwd, projectSessionsDir);
 exitIfManagedResourcesAreNewer(agentDir);
 initResources(agentDir);
 const resourceLoader = buildResourceLoader(agentDir);

package/dist/headless.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Headless Orchestrator — `gsd headless`
+ *
+ * Runs any /gsd subcommand without a TUI by spawning a child process in
+ * RPC mode, auto-responding to extension UI requests, and streaming
+ * progress to stderr.
+ *
+ * Exit codes:
+ *   0 — complete (command finished successfully)
+ *   1 — error or timeout
+ *   2 — blocked (command reported a blocker)
+ */
+export interface HeadlessOptions {
+    timeout: number;
+    json: boolean;
+    model?: string;
+    command: string;
+    commandArgs: string[];
+    context?: string;
+    contextText?: string;
+    auto?: boolean;
+    verbose?: boolean;
+}
+export declare function parseHeadlessArgs(argv: string[]): HeadlessOptions;
+export declare function runHeadless(options: HeadlessOptions): Promise<void>;

package/dist/headless.js

@@ -0,0 +1,454 @@
+/**
+ * Headless Orchestrator — `gsd headless`
+ *
+ * Runs any /gsd subcommand without a TUI by spawning a child process in
+ * RPC mode, auto-responding to extension UI requests, and streaming
+ * progress to stderr.
+ *
+ * Exit codes:
+ *   0 — complete (command finished successfully)
+ *   1 — error or timeout
+ *   2 — blocked (command reported a blocker)
+ */
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// RpcClient is not in @gsd/pi-coding-agent's public exports — import from dist directly.
+// This relative path resolves correctly from both src/ (via tsx) and dist/ (compiled).
+import { RpcClient } from '../packages/pi-coding-agent/dist/modes/rpc/rpc-client.js';
+// ---------------------------------------------------------------------------
+// CLI Argument Parser
+// ---------------------------------------------------------------------------
+export function parseHeadlessArgs(argv) {
+    const options = {
+        timeout: 300_000,
+        json: false,
+        command: 'auto',
+        commandArgs: [],
+    };
+    const args = argv.slice(2);
+    let positionalStarted = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === 'headless')
+            continue;
+        if (!positionalStarted && arg.startsWith('--')) {
+            if (arg === '--timeout' && i + 1 < args.length) {
+                options.timeout = parseInt(args[++i], 10);
+                if (Number.isNaN(options.timeout) || options.timeout <= 0) {
+                    process.stderr.write('[headless] Error: --timeout must be a positive integer (milliseconds)\n');
+                    process.exit(1);
+                }
+            }
+            else if (arg === '--json') {
+                options.json = true;
+            }
+            else if (arg === '--model' && i + 1 < args.length) {
+                // --model can also be passed from the main CLI; headless-specific takes precedence
+                options.model = args[++i];
+            }
+            else if (arg === '--context' && i + 1 < args.length) {
+                options.context = args[++i];
+            }
+            else if (arg === '--context-text' && i + 1 < args.length) {
+                options.contextText = args[++i];
+            }
+            else if (arg === '--auto') {
+                options.auto = true;
+            }
+            else if (arg === '--verbose') {
+                options.verbose = true;
+            }
+        }
+        else if (!positionalStarted) {
+            positionalStarted = true;
+            options.command = arg;
+        }
+        else {
+            options.commandArgs.push(arg);
+        }
+    }
+    return options;
+}
+// ---------------------------------------------------------------------------
+// JSONL Helper
+// ---------------------------------------------------------------------------
+function serializeJsonLine(obj) {
+    return JSON.stringify(obj) + '\n';
+}
+// ---------------------------------------------------------------------------
+// Extension UI Auto-Responder
+// ---------------------------------------------------------------------------
+function handleExtensionUIRequest(event, writeToStdin) {
+    const { id, method } = event;
+    let response;
+    switch (method) {
+        case 'select':
+            response = { type: 'extension_ui_response', id, value: event.options?.[0] ?? '' };
+            break;
+        case 'confirm':
+            response = { type: 'extension_ui_response', id, confirmed: true };
+            break;
+        case 'input':
+            response = { type: 'extension_ui_response', id, value: '' };
+            break;
+        case 'editor':
+            response = { type: 'extension_ui_response', id, value: event.prefill ?? '' };
+            break;
+        case 'notify':
+        case 'setStatus':
+        case 'setWidget':
+        case 'setTitle':
+        case 'set_editor_text':
+            response = { type: 'extension_ui_response', id, value: '' };
+            break;
+        default:
+            process.stderr.write(`[headless] Warning: unknown extension_ui_request method "${method}", cancelling\n`);
+            response = { type: 'extension_ui_response', id, cancelled: true };
+            break;
+    }
+    writeToStdin(serializeJsonLine(response));
+}
+// ---------------------------------------------------------------------------
+// Progress Formatter
+// ---------------------------------------------------------------------------
+function formatProgress(event, verbose) {
+    const type = String(event.type ?? '');
+    switch (type) {
+        case 'tool_execution_start':
+            if (verbose)
+                return `  [tool]    ${event.toolName ?? 'unknown'}`;
+            return null;
+        case 'agent_start':
+            return '[agent]   Session started';
+        case 'agent_end':
+            return '[agent]   Session ended';
+        case 'extension_ui_request':
+            if (event.method === 'notify') {
+                return `[gsd]     ${event.message ?? ''}`;
+            }
+            if (event.method === 'setStatus') {
+                return `[status]  ${event.message ?? ''}`;
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Completion Detection
+// ---------------------------------------------------------------------------
+const TERMINAL_KEYWORDS = ['complete', 'stopped', 'blocked'];
+const IDLE_TIMEOUT_MS = 15_000;
+function isTerminalNotification(event) {
+    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
+        return false;
+    const message = String(event.message ?? '').toLowerCase();
+    return TERMINAL_KEYWORDS.some((kw) => message.includes(kw));
+}
+function isBlockedNotification(event) {
+    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
+        return false;
+    return String(event.message ?? '').toLowerCase().includes('blocked');
+}
+function isMilestoneReadyNotification(event) {
+    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
+        return false;
+    return /milestone\s+m\d+.*ready/i.test(String(event.message ?? ''));
+}
+// ---------------------------------------------------------------------------
+// Quick Command Detection
+// ---------------------------------------------------------------------------
+const QUICK_COMMANDS = new Set([
+    'status', 'queue', 'history', 'hooks', 'export', 'stop', 'pause',
+    'capture', 'skip', 'undo', 'knowledge', 'config', 'prefs',
+    'cleanup', 'migrate', 'doctor', 'remote', 'help', 'steer',
+    'triage', 'visualize',
+]);
+function isQuickCommand(command) {
+    return QUICK_COMMANDS.has(command);
+}
+// ---------------------------------------------------------------------------
+// Main Orchestrator
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Context Loading (new-milestone)
+// ---------------------------------------------------------------------------
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+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>');
+}
+/**
+ * Bootstrap .gsd/ directory structure for headless new-milestone.
+ * Mirrors the bootstrap logic from guided-flow.ts showSmartEntry().
+ */
+function bootstrapGsdProject(basePath) {
+    const gsdDir = join(basePath, '.gsd');
+    mkdirSync(join(gsdDir, 'milestones'), { recursive: true });
+    mkdirSync(join(gsdDir, 'runtime'), { recursive: true });
+}
+export async function runHeadless(options) {
+    const startTime = Date.now();
+    const isNewMilestone = options.command === 'new-milestone';
+    // For new-milestone, load context and bootstrap .gsd/ before spawning RPC child
+    if (isNewMilestone) {
+        if (!options.context && !options.contextText) {
+            process.stderr.write('[headless] Error: new-milestone requires --context <file> or --context-text <text>\n');
+            process.exit(1);
+        }
+        let contextContent;
+        try {
+            contextContent = await loadContext(options);
+        }
+        catch (err) {
+            process.stderr.write(`[headless] Error loading context: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        // Bootstrap .gsd/ if needed
+        const gsdDir = join(process.cwd(), '.gsd');
+        if (!existsSync(gsdDir)) {
+            if (!options.json) {
+                process.stderr.write('[headless] Bootstrapping .gsd/ project structure...\n');
+            }
+            bootstrapGsdProject(process.cwd());
+        }
+        // Write context to temp file for the RPC child to read
+        const runtimeDir = join(gsdDir, 'runtime');
+        mkdirSync(runtimeDir, { recursive: true });
+        writeFileSync(join(runtimeDir, 'headless-context.md'), contextContent, 'utf-8');
+    }
+    // Validate .gsd/ directory (skip for new-milestone since we just bootstrapped it)
+    const gsdDir = join(process.cwd(), '.gsd');
+    if (!isNewMilestone && !existsSync(gsdDir)) {
+        process.stderr.write('[headless] Error: No .gsd/ directory found in current directory.\n');
+        process.stderr.write("[headless] Run 'gsd' interactively first to initialize a project.\n");
+        process.exit(1);
+    }
+    // Resolve CLI path for the child process
+    const cliPath = process.env.GSD_BIN_PATH || process.argv[1];
+    if (!cliPath) {
+        process.stderr.write('[headless] Error: Cannot determine CLI path. Set GSD_BIN_PATH or run via gsd.\n');
+        process.exit(1);
+    }
+    // Create RPC client
+    const clientOptions = {
+        cliPath,
+        cwd: process.cwd(),
+    };
+    if (options.model) {
+        clientOptions.model = options.model;
+    }
+    const client = new RpcClient(clientOptions);
+    // Event tracking
+    let totalEvents = 0;
+    let toolCallCount = 0;
+    let blocked = false;
+    let completed = false;
+    let exitCode = 0;
+    let milestoneReady = false; // tracks "Milestone X ready." for auto-chaining
+    const recentEvents = [];
+    function trackEvent(event) {
+        totalEvents++;
+        const type = String(event.type ?? 'unknown');
+        if (type === 'tool_execution_start') {
+            toolCallCount++;
+        }
+        // Keep last 20 events for diagnostics
+        const detail = type === 'tool_execution_start'
+            ? String(event.toolName ?? '')
+            : type === 'extension_ui_request'
+                ? `${event.method}: ${event.title ?? event.message ?? ''}`
+                : undefined;
+        recentEvents.push({ type, timestamp: Date.now(), detail });
+        if (recentEvents.length > 20)
+            recentEvents.shift();
+    }
+    // Stdin writer for sending extension_ui_response to child
+    let stdinWriter = null;
+    // Completion promise
+    let resolveCompletion;
+    const completionPromise = new Promise((resolve) => {
+        resolveCompletion = resolve;
+    });
+    // Idle timeout — fallback completion detection
+    let idleTimer = null;
+    function resetIdleTimer() {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        if (toolCallCount > 0) {
+            idleTimer = setTimeout(() => {
+                completed = true;
+                resolveCompletion();
+            }, IDLE_TIMEOUT_MS);
+        }
+    }
+    // Overall timeout
+    const timeoutTimer = setTimeout(() => {
+        process.stderr.write(`[headless] Timeout after ${options.timeout / 1000}s\n`);
+        exitCode = 1;
+        resolveCompletion();
+    }, options.timeout);
+    // Event handler
+    client.onEvent((event) => {
+        const eventObj = event;
+        trackEvent(eventObj);
+        resetIdleTimer();
+        // --json mode: forward all events as JSONL to stdout
+        if (options.json) {
+            process.stdout.write(JSON.stringify(eventObj) + '\n');
+        }
+        else {
+            // Progress output to stderr
+            const line = formatProgress(eventObj, !!options.verbose);
+            if (line)
+                process.stderr.write(line + '\n');
+        }
+        // Handle extension_ui_request
+        if (eventObj.type === 'extension_ui_request' && stdinWriter) {
+            // Check for terminal notification before auto-responding
+            if (isBlockedNotification(eventObj)) {
+                blocked = true;
+            }
+            // Detect "Milestone X ready." for auto-mode chaining
+            if (isMilestoneReadyNotification(eventObj)) {
+                milestoneReady = true;
+            }
+            if (isTerminalNotification(eventObj)) {
+                completed = true;
+            }
+            handleExtensionUIRequest(eventObj, stdinWriter);
+            // If we detected a terminal notification, resolve after responding
+            if (completed) {
+                exitCode = blocked ? 2 : 0;
+                resolveCompletion();
+                return;
+            }
+        }
+        // Quick commands: resolve on first agent_end
+        if (eventObj.type === 'agent_end' && isQuickCommand(options.command) && !completed) {
+            completed = true;
+            resolveCompletion();
+            return;
+        }
+        // Long-running commands: agent_end after tool execution — possible completion
+        // The idle timer + terminal notification handle this case.
+    });
+    // Signal handling
+    const signalHandler = () => {
+        process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
+        exitCode = 1;
+        client.stop().finally(() => {
+            clearTimeout(timeoutTimer);
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            process.exit(exitCode);
+        });
+    };
+    process.on('SIGINT', signalHandler);
+    process.on('SIGTERM', signalHandler);
+    // Start the RPC session
+    try {
+        await client.start();
+    }
+    catch (err) {
+        process.stderr.write(`[headless] Error: Failed to start RPC session: ${err instanceof Error ? err.message : String(err)}\n`);
+        clearTimeout(timeoutTimer);
+        process.exit(1);
+    }
+    // Access stdin writer from the internal process
+    const internalProcess = client.process;
+    if (!internalProcess?.stdin) {
+        process.stderr.write('[headless] Error: Cannot access child process stdin\n');
+        await client.stop();
+        clearTimeout(timeoutTimer);
+        process.exit(1);
+    }
+    stdinWriter = (data) => {
+        internalProcess.stdin.write(data);
+    };
+    // Detect child process crash
+    internalProcess.on('exit', (code) => {
+        if (!completed) {
+            const msg = `[headless] Child process exited unexpectedly with code ${code ?? 'null'}\n`;
+            process.stderr.write(msg);
+            exitCode = 1;
+            resolveCompletion();
+        }
+    });
+    if (!options.json) {
+        process.stderr.write(`[headless] Running /gsd ${options.command}${options.commandArgs.length > 0 ? ' ' + options.commandArgs.join(' ') : ''}...\n`);
+    }
+    // Send the command
+    const command = `/gsd ${options.command}${options.commandArgs.length > 0 ? ' ' + options.commandArgs.join(' ') : ''}`;
+    try {
+        await client.prompt(command);
+    }
+    catch (err) {
+        process.stderr.write(`[headless] Error: Failed to send prompt: ${err instanceof Error ? err.message : String(err)}\n`);
+        exitCode = 1;
+    }
+    // Wait for completion
+    if (exitCode === 0 || exitCode === 2) {
+        await completionPromise;
+    }
+    // Auto-mode chaining: if --auto and milestone creation succeeded, send /gsd auto
+    if (isNewMilestone && options.auto && milestoneReady && !blocked && exitCode === 0) {
+        if (!options.json) {
+            process.stderr.write('[headless] Milestone ready — chaining into auto-mode...\n');
+        }
+        // Reset completion state for the auto-mode phase
+        completed = false;
+        milestoneReady = false;
+        blocked = false;
+        const autoCompletionPromise = new Promise((resolve) => {
+            resolveCompletion = resolve;
+        });
+        try {
+            await client.prompt('/gsd auto');
+        }
+        catch (err) {
+            process.stderr.write(`[headless] Error: Failed to start auto-mode: ${err instanceof Error ? err.message : String(err)}\n`);
+            exitCode = 1;
+        }
+        if (exitCode === 0 || exitCode === 2) {
+            await autoCompletionPromise;
+        }
+    }
+    // Cleanup
+    clearTimeout(timeoutTimer);
+    if (idleTimer)
+        clearTimeout(idleTimer);
+    process.removeListener('SIGINT', signalHandler);
+    process.removeListener('SIGTERM', signalHandler);
+    await client.stop();
+    // Summary
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+    const status = blocked ? 'blocked' : exitCode === 1 ? (totalEvents === 0 ? 'error' : 'timeout') : 'complete';
+    process.stderr.write(`[headless] Status: ${status}\n`);
+    process.stderr.write(`[headless] Duration: ${duration}s\n`);
+    process.stderr.write(`[headless] Events: ${totalEvents} total, ${toolCallCount} tool calls\n`);
+    // On failure, print last 5 events for diagnostics
+    if (exitCode !== 0) {
+        const lastFive = recentEvents.slice(-5);
+        if (lastFive.length > 0) {
+            process.stderr.write('[headless] Last events:\n');
+            for (const e of lastFive) {
+                process.stderr.write(`  ${e.type}${e.detail ? `: ${e.detail}` : ''}\n`);
+            }
+        }
+    }
+    process.exit(exitCode);
+}