gsd-pi 2.21.0 → 2.23.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.
@@ -242,6 +262,8 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format             |
 | `/gsd help`             | Categorized command reference for all GSD subcommands           |
 | `/gsd mode`             | Switch workflow mode (solo/team) with coordinated defaults      |
+| `/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           |
 | `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove          |
 | `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                  |
@@ -252,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 |
 
 ---
 
@@ -355,7 +380,17 @@ unique_milestone_ids: true
 | `uat_dispatch`         | Enable automatic UAT runs after slice completion                                                      |
 | `always_use_skills`    | Skills to always load when relevant                                                                   |
 | `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           |
+
+### Agent Instructions
+
+Create an `agent-instructions.md` file in your project root to inject persistent per-project behavioral guidance into every agent session. This file is loaded automatically and provides project-specific context the LLM should always have — coding standards, architectural decisions, domain terminology, or workflow preferences.
+
+### Debug Mode
+
+Start GSD with `gsd --debug` to enable structured JSONL diagnostic logging. Debug logs capture dispatch decisions, state transitions, and timing data for troubleshooting auto-mode issues.
 
 ### Token Optimization (v2.17)
 
@@ -384,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                                                                             |
@@ -470,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

@@ -9,7 +9,7 @@ import { getPiDefaultModelAndProvider, migratePiCredentials } from './pi-migrati
 import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
-import { printHelp } from './help-text.js';
+import { printHelp, printSubcommandHelp } from './help-text.js';
 function exitIfManagedResourcesAreNewer(currentAgentDir) {
     const currentVersion = process.env.GSD_VERSION || '0.0.0';
     const managedVersion = getNewerManagedResourceVersion(currentAgentDir, currentVersion);
@@ -28,7 +28,7 @@ function parseCliArgs(argv) {
         const arg = args[i];
         if (arg === '--mode' && i + 1 < args.length) {
             const m = args[++i];
-            if (m === 'text' || m === 'json' || m === 'rpc')
+            if (m === 'text' || m === 'json' || m === 'rpc' || m === 'mcp')
                 flags.mode = m;
         }
         else if (arg === '--print' || arg === '-p') {
@@ -71,6 +71,13 @@ function parseCliArgs(argv) {
 }
 const cliFlags = parseCliArgs(process.argv);
 const isPrintMode = cliFlags.print || cliFlags.mode !== undefined;
+// `gsd <subcommand> --help` — show subcommand-specific help
+const subcommand = cliFlags.messages[0];
+if (subcommand && process.argv.includes('--help')) {
+    if (printSubcommandHelp(subcommand, process.env.GSD_VERSION || '0.0.0')) {
+        process.exit(0);
+    }
+}
 // `gsd config` — replay the setup wizard and exit
 if (cliFlags.messages[0] === 'config') {
     const authStorage = AuthStorage.create(authFilePath);
@@ -84,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.
@@ -91,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())) {
@@ -245,8 +308,17 @@ if (isPrintMode) {
         await runRpcMode(session);
         process.exit(0);
     }
+    if (mode === 'mcp') {
+        const { startMcpServer } = await import('./mcp-server.js');
+        await startMcpServer({
+            tools: session.agent.state.tools ?? [],
+            version: process.env.GSD_VERSION || '0.0.0',
+        });
+        // MCP server runs until the transport closes; keep alive
+        await new Promise(() => { });
+    }
     await runPrintMode(session, {
-        mode,
+        mode: mode,
         messages: cliFlags.messages,
     });
     process.exit(0);
@@ -282,9 +354,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);
@@ -347,6 +421,7 @@ if (!process.stdin.isTTY) {
     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);
 }

package/dist/headless.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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[];
+}
+export declare function parseHeadlessArgs(argv: string[]): HeadlessOptions;
+export declare function runHeadless(options: HeadlessOptions): Promise<void>;

package/dist/headless.js

@@ -0,0 +1,346 @@
+/**
+ * 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 } from 'node:fs';
+import { join } 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 (!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) {
+    const type = String(event.type ?? '');
+    switch (type) {
+        case 'tool_execution_start':
+            return `[tool] ${event.toolName ?? 'unknown'}`;
+        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 ?? ''}`;
+            }
+            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');
+}
+// ---------------------------------------------------------------------------
+// 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
+// ---------------------------------------------------------------------------
+export async function runHeadless(options) {
+    const startTime = Date.now();
+    // Validate .gsd/ directory
+    const gsdDir = join(process.cwd(), '.gsd');
+    if (!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;
+    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);
+            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;
+            }
+            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;
+    }
+    // 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);
+}

package/dist/help-text.d.ts

@@ -1 +1,2 @@
 export declare function printHelp(version: string): void;
+export declare function printSubcommandHelp(subcommand: string, version: string): boolean;

package/dist/help-text.js

@@ -1,8 +1,58 @@
+const SUBCOMMAND_HELP = {
+    config: [
+        'Usage: gsd config',
+        '',
+        'Re-run the interactive setup wizard to configure:',
+        '  - LLM provider (Anthropic, OpenAI, Google, etc.)',
+        '  - Web search provider (Brave, Tavily, built-in)',
+        '  - Remote questions (Discord, Slack, Telegram)',
+        '  - Tool API keys (Context7, Jina, Groq)',
+        '',
+        'All steps are skippable and can be changed later with /login or /search-provider.',
+    ].join('\n'),
+    update: [
+        'Usage: gsd update',
+        '',
+        'Update GSD to the latest version.',
+        '',
+        'Equivalent to: npm install -g gsd-pi@latest',
+    ].join('\n'),
+    sessions: [
+        'Usage: gsd sessions',
+        '',
+        'List all saved sessions for the current directory and interactively',
+        'pick one to resume. Shows date, message count, and a preview of the',
+        'first message for each session.',
+        '',
+        'Sessions are stored per-directory, so you only see sessions that were',
+        'started from the current working directory.',
+        '',
+        'Compare with --continue (-c) which always resumes the most recent session.',
+    ].join('\n'),
+    headless: [
+        'Usage: gsd headless [flags] [command] [args...]',
+        '',
+        'Run /gsd commands without the TUI. Default command: auto',
+        '',
+        'Flags:',
+        '  --timeout N     Overall timeout in ms (default: 300000)',
+        '  --json          JSONL event stream to stdout',
+        '  --model ID      Override model',
+        '',
+        'Examples:',
+        '  gsd headless                    Run /gsd auto',
+        '  gsd headless next               Run one unit',
+        '  gsd headless --json status      Machine-readable status',
+        '  gsd headless --timeout 60000    With 1-minute timeout',
+        '',
+        'Exit codes: 0 = complete, 1 = error/timeout, 2 = blocked',
+    ].join('\n'),
+};
 export function printHelp(version) {
     process.stdout.write(`GSD v${version} — Get Shit Done\n\n`);
     process.stdout.write('Usage: gsd [options] [message...]\n\n');
     process.stdout.write('Options:\n');
-    process.stdout.write('  --mode <text|json|rpc>   Output mode (default: interactive)\n');
+    process.stdout.write('  --mode <text|json|rpc|mcp> Output mode (default: interactive)\n');
     process.stdout.write('  --print, -p              Single-shot print mode\n');
     process.stdout.write('  --continue, -c           Resume the most recent session\n');
     process.stdout.write('  --model <id>             Override model (e.g. claude-opus-4-6)\n');
@@ -15,4 +65,15 @@ export function printHelp(version) {
     process.stdout.write('\nSubcommands:\n');
     process.stdout.write('  config                   Re-run the setup wizard\n');
     process.stdout.write('  update                   Update GSD to the latest version\n');
+    process.stdout.write('  sessions                 List and resume a past session\n');
+    process.stdout.write('  headless [cmd] [args]    Run /gsd commands without TUI (default: auto)\n');
+    process.stdout.write('\nRun gsd <subcommand> --help for subcommand-specific help.\n');
+}
+export function printSubcommandHelp(subcommand, version) {
+    const help = SUBCOMMAND_HELP[subcommand];
+    if (!help)
+        return false;
+    process.stdout.write(`GSD v${version} — Get Shit Done\n\n`);
+    process.stdout.write(help + '\n');
+    return true;
 }