gsd-pi 2.27.0 → 2.28.0-dev.346ee62

package/dist/headless-events.js

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Completion Detection
+// ---------------------------------------------------------------------------
+/**
+ * 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 const TERMINAL_PREFIXES = ['auto-mode stopped', 'step-mode stopped'];
+export const IDLE_TIMEOUT_MS = 15_000;
+// new-milestone is a long-running creative task where the LLM may pause
+// between tool calls (e.g. after mkdir, before writing files). Use a
+// longer idle timeout to avoid killing the session prematurely (#808).
+export const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120_000;
+export function isTerminalNotification(event) {
+    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
+        return false;
+    const message = String(event.message ?? '').toLowerCase();
+    return TERMINAL_PREFIXES.some((prefix) => message.startsWith(prefix));
+}
+export function isBlockedNotification(event) {
+    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
+        return false;
+    const message = String(event.message ?? '').toLowerCase();
+    // Blocked notifications come through stopAuto as "Auto-mode stopped (Blocked: ...)"
+    return message.includes('blocked:');
+}
+export 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
+// ---------------------------------------------------------------------------
+export const FIRE_AND_FORGET_METHODS = new Set(['notify', 'setStatus', 'setWidget', 'setTitle', 'set_editor_text']);
+export 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',
+]);
+export function isQuickCommand(command) {
+    return QUICK_COMMANDS.has(command);
+}

package/dist/headless-query.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Headless Query — `gsd headless query`
+ *
+ * Single read-only command that returns the full project snapshot as JSON
+ * to stdout, without spawning an LLM session. Instant (~50ms).
+ *
+ * Output: { state, next, cost }
+ *   state — deriveState() output (phase, milestones, progress, blockers)
+ *   next  — dry-run dispatch preview (what auto-mode would do next)
+ *   cost  — aggregated parallel worker costs
+ *
+ * Note: Extension modules are .ts files loaded via jiti (not compiled to .js).
+ * We use createJiti() here because this module is imported directly from cli.ts,
+ * bypassing the extension loader's jiti setup (#1137).
+ */
+import type { GSDState } from './resources/extensions/gsd/types.js';
+export interface QuerySnapshot {
+    state: GSDState;
+    next: {
+        action: 'dispatch' | 'stop' | 'skip';
+        unitType?: string;
+        unitId?: string;
+        reason?: string;
+    };
+    cost: {
+        workers: Array<{
+            milestoneId: string;
+            pid: number;
+            state: string;
+            cost: number;
+            lastHeartbeat: number;
+        }>;
+        total: number;
+    };
+}
+export interface QueryResult {
+    exitCode: number;
+    data?: QuerySnapshot;
+}
+export declare function handleQuery(basePath: string): Promise<QueryResult>;

package/dist/headless-query.js

@@ -0,0 +1,77 @@
+/**
+ * Headless Query — `gsd headless query`
+ *
+ * Single read-only command that returns the full project snapshot as JSON
+ * to stdout, without spawning an LLM session. Instant (~50ms).
+ *
+ * Output: { state, next, cost }
+ *   state — deriveState() output (phase, milestones, progress, blockers)
+ *   next  — dry-run dispatch preview (what auto-mode would do next)
+ *   cost  — aggregated parallel worker costs
+ *
+ * Note: Extension modules are .ts files loaded via jiti (not compiled to .js).
+ * We use createJiti() here because this module is imported directly from cli.ts,
+ * bypassing the extension loader's jiti setup (#1137).
+ */
+import { createJiti } from '@mariozechner/jiti';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const jiti = createJiti(fileURLToPath(import.meta.url), { interopDefault: true, debug: false });
+async function loadExtensionModules() {
+    const stateModule = await jiti.import(join(__dirname, 'resources/extensions/gsd/state.ts'), {});
+    const dispatchModule = await jiti.import(join(__dirname, 'resources/extensions/gsd/auto-dispatch.ts'), {});
+    const sessionModule = await jiti.import(join(__dirname, 'resources/extensions/gsd/session-status-io.ts'), {});
+    const prefsModule = await jiti.import(join(__dirname, 'resources/extensions/gsd/preferences.ts'), {});
+    return {
+        deriveState: stateModule.deriveState,
+        resolveDispatch: dispatchModule.resolveDispatch,
+        readAllSessionStatuses: sessionModule.readAllSessionStatuses,
+        loadEffectiveGSDPreferences: prefsModule.loadEffectiveGSDPreferences,
+    };
+}
+// ─── Implementation ─────────────────────────────────────────────────────────
+export async function handleQuery(basePath) {
+    const { deriveState, resolveDispatch, readAllSessionStatuses, loadEffectiveGSDPreferences } = await loadExtensionModules();
+    const state = await deriveState(basePath);
+    // Derive next dispatch action
+    let next;
+    if (!state.activeMilestone) {
+        next = {
+            action: 'stop',
+            reason: state.phase === 'complete' ? 'All milestones complete.' : state.nextAction,
+        };
+    }
+    else {
+        const loaded = loadEffectiveGSDPreferences();
+        const dispatch = await resolveDispatch({
+            basePath,
+            mid: state.activeMilestone.id,
+            midTitle: state.activeMilestone.title,
+            state,
+            prefs: loaded?.preferences,
+        });
+        next = {
+            action: dispatch.action,
+            unitType: dispatch.action === 'dispatch' ? dispatch.unitType : undefined,
+            unitId: dispatch.action === 'dispatch' ? dispatch.unitId : undefined,
+            reason: dispatch.action === 'stop' ? dispatch.reason : undefined,
+        };
+    }
+    // Aggregate parallel worker costs
+    const statuses = readAllSessionStatuses(basePath);
+    const workers = statuses.map((s) => ({
+        milestoneId: s.milestoneId,
+        pid: s.pid,
+        state: s.state,
+        cost: s.cost,
+        lastHeartbeat: s.lastHeartbeat,
+    }));
+    const snapshot = {
+        state,
+        next,
+        cost: { workers, total: workers.reduce((sum, w) => sum + w.cost, 0) },
+    };
+    process.stdout.write(JSON.stringify(snapshot) + '\n');
+    return { exitCode: 0, data: snapshot };
+}

package/dist/headless-ui.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Headless UI Handling — auto-response, progress formatting, and supervised stdin
+ *
+ * Handles extension UI requests (auto-responding in headless mode),
+ * formats progress events for stderr output, and reads orchestrator
+ * commands from stdin in supervised mode.
+ */
+import { RpcClient } from '@gsd/pi-coding-agent';
+interface ExtensionUIRequest {
+    type: 'extension_ui_request';
+    id: string;
+    method: string;
+    title?: string;
+    options?: string[];
+    message?: string;
+    prefill?: string;
+    timeout?: number;
+    [key: string]: unknown;
+}
+export type { ExtensionUIRequest };
+export declare function handleExtensionUIRequest(event: ExtensionUIRequest, writeToStdin: (data: string) => void): void;
+export declare function formatProgress(event: Record<string, unknown>, verbose: boolean): string | null;
+export declare function startSupervisedStdinReader(stdinWriter: (data: string) => void, client: RpcClient, onResponse: (id: string) => void): () => void;

package/dist/headless-ui.js

@@ -0,0 +1,103 @@
+/**
+ * Headless UI Handling — auto-response, progress formatting, and supervised stdin
+ *
+ * Handles extension UI requests (auto-responding in headless mode),
+ * formats progress events for stderr output, and reads orchestrator
+ * commands from stdin in supervised mode.
+ */
+import { attachJsonlLineReader, serializeJsonLine } from '@gsd/pi-coding-agent';
+// ---------------------------------------------------------------------------
+// Extension UI Auto-Responder
+// ---------------------------------------------------------------------------
+export 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
+// ---------------------------------------------------------------------------
+export 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;
+    }
+}
+// ---------------------------------------------------------------------------
+// Supervised Stdin Reader
+// ---------------------------------------------------------------------------
+export function startSupervisedStdinReader(stdinWriter, client, onResponse) {
+    return attachJsonlLineReader(process.stdin, (line) => {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            process.stderr.write(`[headless] Warning: invalid JSON from orchestrator stdin, skipping\n`);
+            return;
+        }
+        const type = String(msg.type ?? '');
+        switch (type) {
+            case 'extension_ui_response':
+                stdinWriter(line + '\n');
+                if (typeof msg.id === 'string') {
+                    onResponse(msg.id);
+                }
+                break;
+            case 'prompt':
+                client.prompt(String(msg.message ?? ''));
+                break;
+            case 'steer':
+                client.steer(String(msg.message ?? ''));
+                break;
+            case 'follow_up':
+                client.followUp(String(msg.message ?? ''));
+                break;
+            default:
+                process.stderr.write(`[headless] Warning: unknown message type "${type}" from orchestrator stdin\n`);
+                break;
+        }
+    });
+}

package/dist/headless.d.ts

@@ -23,6 +23,8 @@ export interface HeadlessOptions {
     maxRestarts?: number;
     supervised?: boolean;
     responseTimeout?: number;
+    answers?: string;
+    eventFilter?: Set<string>;
 }
 export declare function parseHeadlessArgs(argv: string[]): HeadlessOptions;
 export declare function runHeadless(options: HeadlessOptions): Promise<void>;

package/dist/headless.js

@@ -10,12 +10,14 @@
  *   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';
-import { attachJsonlLineReader, serializeJsonLine } from '../packages/pi-coding-agent/dist/modes/rpc/jsonl.js';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolve } from 'node:path';
+import { RpcClient } from '@gsd/pi-coding-agent';
+import { loadAndValidateAnswerFile, AnswerInjector } from './headless-answers.js';
+import { isTerminalNotification, isBlockedNotification, isMilestoneReadyNotification, isQuickCommand, FIRE_AND_FORGET_METHODS, IDLE_TIMEOUT_MS, NEW_MILESTONE_IDLE_TIMEOUT_MS, } from './headless-events.js';
+import { handleExtensionUIRequest, formatProgress, startSupervisedStdinReader, } from './headless-ui.js';
+import { loadContext, bootstrapGsdProject, } from './headless-context.js';
 // ---------------------------------------------------------------------------
 // CLI Argument Parser
 // ---------------------------------------------------------------------------
@@ -66,6 +68,13 @@ export function parseHeadlessArgs(argv) {
                     process.exit(1);
                 }
             }
+            else if (arg === '--answers' && i + 1 < args.length) {
+                options.answers = args[++i];
+            }
+            else if (arg === '--events' && i + 1 < args.length) {
+                options.eventFilter = new Set(args[++i].split(','));
+                options.json = true; // --events implies --json
+            }
             else if (arg === '--supervised') {
                 options.supervised = true;
                 options.json = true; // supervised implies json
@@ -89,186 +98,8 @@ export function parseHeadlessArgs(argv) {
     return options;
 }
 // ---------------------------------------------------------------------------
-// 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
-// ---------------------------------------------------------------------------
-/**
- * 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.
- */
-const TERMINAL_PREFIXES = ['auto-mode stopped', 'step-mode stopped'];
-const IDLE_TIMEOUT_MS = 15_000;
-// new-milestone is a long-running creative task where the LLM may pause
-// between tool calls (e.g. after mkdir, before writing files). Use a
-// longer idle timeout to avoid killing the session prematurely (#808).
-const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120_000;
-function isTerminalNotification(event) {
-    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
-        return false;
-    const message = String(event.message ?? '').toLowerCase();
-    return TERMINAL_PREFIXES.some((prefix) => message.startsWith(prefix));
-}
-function isBlockedNotification(event) {
-    if (event.type !== 'extension_ui_request' || event.method !== 'notify')
-        return false;
-    const message = String(event.message ?? '').toLowerCase();
-    // Blocked notifications come through stopAuto as "Auto-mode stopped (Blocked: ...)"
-    return message.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 FIRE_AND_FORGET_METHODS = new Set(['notify', 'setStatus', 'setWidget', 'setTitle', 'set_editor_text']);
-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);
-}
-// ---------------------------------------------------------------------------
-// Supervised Stdin Reader
-// ---------------------------------------------------------------------------
-function startSupervisedStdinReader(stdinWriter, client, onResponse) {
-    return attachJsonlLineReader(process.stdin, (line) => {
-        let msg;
-        try {
-            msg = JSON.parse(line);
-        }
-        catch {
-            process.stderr.write(`[headless] Warning: invalid JSON from orchestrator stdin, skipping\n`);
-            return;
-        }
-        const type = String(msg.type ?? '');
-        switch (type) {
-            case 'extension_ui_response':
-                stdinWriter(line + '\n');
-                if (typeof msg.id === 'string') {
-                    onResponse(msg.id);
-                }
-                break;
-            case 'prompt':
-                client.prompt(String(msg.message ?? ''));
-                break;
-            case 'steer':
-                client.steer(String(msg.message ?? ''));
-                break;
-            case 'follow_up':
-                client.followUp(String(msg.message ?? ''));
-                break;
-            default:
-                process.stderr.write(`[headless] Warning: unknown message type "${type}" from orchestrator stdin\n`);
-                break;
-        }
-    });
-}
-// ---------------------------------------------------------------------------
 // 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 maxRestarts = options.maxRestarts ?? 3;
     let restartCount = 0;
@@ -302,6 +133,21 @@ async function runHeadlessOnce(options, restartCount) {
         process.stderr.write('[headless] Error: --supervised cannot be used with --context - (both require stdin)\n');
         process.exit(1);
     }
+    // Load answer injection file
+    let injector;
+    if (options.answers) {
+        try {
+            const answerFile = loadAndValidateAnswerFile(resolve(options.answers));
+            injector = new AnswerInjector(answerFile);
+            if (!options.json) {
+                process.stderr.write(`[headless] Loaded answer file: ${options.answers}\n`);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[headless] Error loading answer file: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    }
     // For new-milestone, load context and bootstrap .gsd/ before spawning RPC child
     if (isNewMilestone) {
         if (!options.context && !options.contextText) {
@@ -336,6 +182,12 @@ async function runHeadlessOnce(options, restartCount) {
         process.stderr.write("[headless] Run 'gsd' interactively first to initialize a project.\n");
         process.exit(1);
     }
+    // Query: read-only state snapshot, no RPC child needed
+    if (options.command === 'query') {
+        const { handleQuery } = await import('./headless-query.js');
+        const result = await handleQuery(process.cwd());
+        return { exitCode: result.exitCode, interrupted: false };
+    }
     // Resolve CLI path for the child process
     const cliPath = process.env.GSD_BIN_PATH || process.argv[1];
     if (!cliPath) {
@@ -350,6 +202,9 @@ async function runHeadlessOnce(options, restartCount) {
     if (options.model) {
         clientOptions.model = options.model;
     }
+    if (injector) {
+        clientOptions.env = injector.getSecretEnvVars();
+    }
     const client = new RpcClient(clientOptions);
     // Event tracking
     let totalEvents = 0;
@@ -419,9 +274,14 @@ async function runHeadlessOnce(options, restartCount) {
         const eventObj = event;
         trackEvent(eventObj);
         resetIdleTimer();
-        // --json mode: forward all events as JSONL to stdout
+        // Answer injector: observe events for question metadata
+        injector?.observeEvent(eventObj);
+        // --json mode: forward events as JSONL to stdout (filtered if --events)
         if (options.json) {
-            process.stdout.write(JSON.stringify(eventObj) + '\n');
+            const eventType = String(eventObj.type ?? '');
+            if (!options.eventFilter || options.eventFilter.has(eventType)) {
+                process.stdout.write(JSON.stringify(eventObj) + '\n');
+            }
         }
         else {
             // Progress output to stderr
@@ -442,6 +302,16 @@ async function runHeadlessOnce(options, restartCount) {
             if (isTerminalNotification(eventObj)) {
                 completed = true;
             }
+            // Answer injection: try to handle with pre-supplied answers before supervised/auto
+            if (injector && !FIRE_AND_FORGET_METHODS.has(String(eventObj.method ?? ''))) {
+                if (injector.tryHandle(eventObj, stdinWriter)) {
+                    if (completed) {
+                        exitCode = blocked ? 2 : 0;
+                        resolveCompletion();
+                    }
+                    return;
+                }
+            }
             const method = String(eventObj.method ?? '');
             const shouldSupervise = options.supervised && !supervisedFallback
                 && !FIRE_AND_FORGET_METHODS.has(method);
@@ -585,9 +455,20 @@ async function runHeadlessOnce(options, restartCount) {
     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`);
+    if (options.eventFilter) {
+        process.stderr.write(`[headless] Event filter: ${[...options.eventFilter].join(', ')}\n`);
+    }
     if (restartCount > 0) {
         process.stderr.write(`[headless] Restarts: ${restartCount}\n`);
     }
+    // Answer injection stats
+    if (injector) {
+        const stats = injector.getStats();
+        process.stderr.write(`[headless] Answers: ${stats.questionsAnswered} answered, ${stats.questionsDefaulted} defaulted, ${stats.secretsProvided} secrets\n`);
+        for (const warning of injector.getUnusedWarnings()) {
+            process.stderr.write(`${warning}\n`);
+        }
+    }
     // On failure, print last 5 events for diagnostics
     if (exitCode !== 0) {
         const lastFive = recentEvents.slice(-5);

package/dist/help-text.js

@@ -40,12 +40,15 @@ const SUBCOMMAND_HELP = {
         '  --model ID           Override model',
         '  --supervised           Forward interactive UI requests to orchestrator via stdout/stdin',
         '  --response-timeout N   Timeout (ms) for orchestrator response (default: 30000)',
+        '  --answers <path>       Pre-supply answers and secrets (JSON file)',
+        '  --events <types>       Filter JSONL output to specific event types (comma-separated)',
         '',
         'Commands:',
         '  auto                 Run all queued units continuously (default)',
         '  next                 Run one unit',
         '  status               Show progress dashboard',
         '  new-milestone        Create a milestone from a specification document',
+        '  query                JSON snapshot: state + next dispatch + costs (no LLM)',
         '',
         'new-milestone flags:',
         '  --context <path>     Path to spec/PRD file (use \'-\' for stdin)',
@@ -62,6 +65,9 @@ const SUBCOMMAND_HELP = {
         '  cat spec.md | gsd headless new-milestone --context -   From stdin',
         '  gsd headless new-milestone --context spec.md --auto    Create + auto-execute',
         '  gsd headless --supervised auto                     Supervised orchestrator mode',
+        '  gsd headless --answers answers.json auto              With pre-supplied answers',
+        '  gsd headless --events agent_end,extension_ui_request auto   Filtered event stream',
+        '  gsd headless query                              Instant JSON state snapshot',
         '',
         'Exit codes: 0 = complete, 1 = error/timeout, 2 = blocked',
     ].join('\n'),