gsd-pi 2.51.0 → 2.52.0-dev.655ad8a

package/README.md

@@ -27,55 +27,78 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.46.0
+## What's New in v2.52.0
 
-### Single-Writer State Engine
+### VS Code Extension & Web UI
 
-The biggest architectural change since DB-backed planning tools. The single-writer engine enforces disciplined state transitions through three iterations:
+- **VS Code integration** — status bar, file decorations, bash terminal, session tree, conversation history, and code lens. (#2651)
+- **Dark mode contrast** — raised token floor and flattened opacity tier system for better readability. (#2734)
+- **Auth token gate** — synthetic 401 on missing token, unauthenticated boot state, and recovery screen. (#2740)
 
-- **v2 — discipline layer** — adds a write-side discipline layer on top of the DB architecture, ensuring all state mutations flow through controlled tool calls.
-- **v3 — state machine guards, actor identity, reversibility** — introduces formal state machine guards, tracks which actor (human vs agent) initiated each transition, and makes transitions reversible.
-- **Hardened** — closes TOCTOU race conditions, intercepts bypass attempts, and resolves status inconsistencies.
+### Capability Metadata & Model Routing
 
-All prompts are now aligned with the single-writer tool API, and a new **workflow-logger** is wired into the engine, tool, manifest, and reconcile paths for full observability. (#2494)
-
-### v2.45.0 — New Commands and Capabilities
-
-- **`/gsd rethink`** — conversational project reorganization. Rethink your milestone structure, slice decomposition, or overall approach through guided discussion. (#2459)
-- **`/gsd mcp`** — MCP server status and connectivity. Check which MCP servers are configured, connected, and healthy. (#2362)
-- **Complete offline mode** — GSD now works fully offline with local models. (#2429)
-- **Global KNOWLEDGE.md injection** — `~/.gsd/agent/KNOWLEDGE.md` is injected into the system prompt, so cross-project knowledge persists globally. (#2331)
-- **Mobile-responsive web UI** — the browser interface now works on phones and tablets. (#2354)
-- **DB tool previews** — `renderCall`/`renderResult` previews on DB tools show what each tool call does before and after execution. (#2273)
-- **Message timestamps** — user and assistant messages now include timestamps. (#2368)
+- **Capability-based model selection** — replaced model-ID pattern matching with capability metadata, making custom provider integration more reliable. (#2548)
 
 ### Key Changes
 
-- **Default isolation mode changed to `none`** — `git.isolation` now defaults to `none` instead of `worktree`. Projects that rely on worktree isolation should set `git.isolation: worktree` explicitly in preferences. (#2481)
-- **Startup checks** — GSD now validates Node.js version and git availability at startup, with clear error messages. (#2463)
-- **Worktree lifecycle journaling** — worktree create, switch, merge, and remove events are recorded in the event journal. (#2486)
-- **Milestone verification gate** — milestone completion is blocked when verification fails, preventing premature closure. (#2500)
+- **`--bare` mode** — wired across headless, pi-coding-agent, and resource-loader for minimal-output operation.
+- **RPC protocol v2** — new types, init handshake with version detection, and runId generation on prompt/steer/follow_up commands.
+- **PREFERENCES.md rename** — `preferences.md` renamed to `PREFERENCES.md` for consistency. (#2700, #2738)
+- **Comprehensive SQLite audit** — indexes, caching, safety, and reconciliation fixes across gsd-db.
+- **Unified error classifier** — three overlapping error classifiers consolidated into a single classify-decide-act pipeline.
 
 ### Key Fixes
 
-- **Auto-mode stability** — recovery attempts reset on unit re-dispatch (#2424), survivor branch recovery handles `phase=complete` (#2427), and auto mode stops on real merge conflicts (#2428).
-- **Supervision timeouts** — now respect task `est:` annotations, so complex tasks get proportionally longer timeouts. (#2434)
-- **`auto_pr: true` fixed** — three interacting bugs prevented auto-PR creation; all three are resolved. (#2433)
-- **Rich task plan preservation** — plans survive DB roundtrip without losing structured content. (#2453)
-- **Artifact truncation prevention** — `saveArtifactToDb` no longer overwrites larger files with truncated content. (#2447)
-- **Worktree teardown** — submodule state is detected and preserved during teardown (#2425), and worktree merge back to main works after `stopAuto` on milestone completion (#2430).
-- **Windows portability** — `retentionDays=0` handling and CRLF fixes on Windows. (#2460)
-- **Voice on Linux** — misleading portaudio error on PEP 668 systems replaced with actionable guidance. (#2407)
+- **Auto-mode stops on provider errors** — auto loop now halts after provider errors instead of retrying indefinitely. (#2762, #2764)
+- **Transaction safety** — state machine guards moved inside transactions in 5 tool handlers (#2752), and `transaction()` made re-entrant.
+- **Worktree seeding** — `preferences.md` seeded into auto-mode worktrees and included in worktree sync. (#2693)
+- **Idle watchdog** — interactive tools exempted from stall detection (#2676), and filesystem activity no longer overrides stalled-tool detection. (#2697)
+- **Milestone guards** — `allSlicesDone` guarded against vacuous truth on empty slice arrays (#2679), and `complete-milestone` dispatch blocked when validation is `needs-remediation`. (#2682)
+- **Docker overhaul** — fragile setup replaced with proven container patterns. (#2716)
+- **Windows** — EINVAL prevented by disabling detached process groups on Win32. (#2744)
+- **Audit log** — `setLogBasePath` wired into engine init to resurrect audit logging. (#2745)
+
+### v2.51.0 — Skills, RTK, and Verification
+
+- **`/terminal` command** — direct shell execution from the slash command interface. (#2349)
+- **Managed RTK integration** — RTK binary auto-provisioned with opt-in preference and web UI toggle. (#2620)
+- **Verification classes** — compliance checked before milestone completion, with classes injected into validation prompts. (#2621, #2623)
+- **Skills overhaul** — 30+ new skill packs covering major frameworks, databases, and cloud platforms; curated catalog with `~/.agents/skills/` as primary directory.
+
+### v2.50.0 — Quality Gates
+
+- **Quality gates** — 8-question quality gates added to planning and completion templates, with parallel evaluation via `evaluating-gates` phase.
+- **Structured error propagation** — errors wired through `UnitResult` for better diagnostics.
+
+### v2.49.0 — Git Trailers & Yolo Mode
+
+- **`--yolo` flag** — `/gsd auto --yolo` for non-interactive project init.
+- **Git trailers** — GSD metadata moved from commit subject scopes to git trailers.
+
+### v2.48.0 — Forensics & Discussion
+
+- **`/gsd discuss` for queued milestones** — target milestones still in the queue. (#2349)
+- **Enhanced forensics** — journal and activity log awareness added to `/gsd forensics`.
+
+### v2.47.0 — External Providers
+
+- **External tool execution mode** — `externalToolExecution` mode for external providers in agent-core.
+- **Claude Code CLI provider** — new provider extension for Claude Code CLI. (#2382)
 
-### Previous highlights (v2.42–v2.44)
+### Previous highlights (v2.42–v2.46)
 
+- **Single-writer state engine** — disciplined state transitions with machine guards, actor identity, reversibility, and TOCTOU hardening. (#2494)
+- **`/gsd rethink`** — conversational project reorganization. (#2459)
+- **`/gsd mcp`** — MCP server status and connectivity. (#2362)
+- **Complete offline mode** — fully offline with local models. (#2429)
+- **Global KNOWLEDGE.md injection** — cross-project knowledge via `~/.gsd/agent/KNOWLEDGE.md`. (#2331)
+- **Mobile-responsive web UI** — browser interface works on phones and tablets. (#2354)
+- **Default isolation mode changed to `none`** — set `git.isolation: worktree` explicitly if needed. (#2481)
 - **Non-API-key provider extensions** — support for Claude Code CLI and similar providers. (#2382)
 - **Docker sandbox template** — official Docker template for isolated auto mode. (#2360)
 - **DB-backed planning tools** — write-side state transitions use atomic SQLite tool calls. (#2141)
 - **Declarative workflow engine** — YAML workflows through auto-loop. (#2024)
 - **`/gsd fast`** — toggle service tier for prioritized API routing. (#1862)
-- **Forensics dedup** — duplicate detection before issue creation. (#2105)
-- **Startup optimizations** — pre-compiled extensions, compile cache, batch discovery. (#2125)
 
 ---
 
@@ -521,7 +544,7 @@ An auto-generated `index.html` shows all reports with progression metrics across
 
 ### Preferences
 
-GSD preferences live in `~/.gsd/preferences.md` (global) or `.gsd/preferences.md` (project). Manage with `/gsd prefs`.
+GSD preferences live in `~/.gsd/PREFERENCES.md` (global) or `.gsd/PREFERENCES.md` (project). Manage with `/gsd prefs`.
 
 ```yaml
 ---
@@ -672,7 +695,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 
 ### Unique Milestone Names
 
-Create or amend your `.gsd/preferences.md` file within the repo to include `unique_milestone_ids: true` e.g.
+Create or amend your `.gsd/PREFERENCES.md` file within the repo to include `unique_milestone_ids: true` e.g.
 
 ```markdown
 ---
@@ -681,7 +704,7 @@ unique_milestone_ids: true
 ---
 ```
 
-With the above `.gitignore` set up, the `.gsd/preferences.md` file is checked into the repo ensuring all teammates use unique milestone names to avoid collisions.
+With the above `.gitignore` set up, the `.gsd/PREFERENCES.md` file is checked into the repo ensuring all teammates use unique milestone names to avoid collisions.
 
 Milestone names will now be generated with a 6 char random string appended e.g. instead of `M001` you'll get something like `M001-ush8s3`
 
@@ -689,7 +712,7 @@ Milestone names will now be generated with a 6 char random string appended e.g.
 
 1. Ensure you are not in the middle of any milestones (clean state)
 2. Update the `.gsd/` related entries in your `.gitignore` to follow the `Suggested .gitignore setup` section under `Working in teams` (ensure you are no longer blanket ignoring the whole `.gsd/` directory)
-3. Update your `.gsd/preferences.md` file within the repo as per section `Unique Milestone Names`
+3. Update your `.gsd/PREFERENCES.md` file within the repo as per section `Unique Milestone Names`
 4. If you want to update all your existing milestones use this prompt in GSD: `I have turned on unique milestone ids, please update all old milestone ids to use this new format e.g. M001-abc123 where abc123 is a random 6 char lowercase alpha numeric string. Update all references in all .gsd file contents, file names and directory names. Validate your work once done to ensure referential integrity.`
 5. Commit to git
 

package/dist/headless-events.d.ts

@@ -3,7 +3,25 @@
  *
  * Detects terminal notifications, blocked notifications, milestone-ready signals,
  * and classifies commands as quick (single-turn) vs long-running.
+ *
+ * Also defines exit code constants and the status→exit-code mapping function.
+ */
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_BLOCKED = 10;
+export declare const EXIT_CANCELLED = 11;
+/**
+ * Map a headless session status string to its standardized exit code.
+ *
+ *   success   → 0
+ *   error     → 1
+ *   timeout   → 1
+ *   blocked   → 10
+ *   cancelled → 11
+ *
+ * Unknown statuses default to EXIT_ERROR (1).
  */
+export declare function mapStatusToExitCode(status: string): number;
 /**
  * Detect genuine auto-mode termination notifications.
  *

package/dist/headless-events.js

@@ -3,7 +3,43 @@
  *
  * Detects terminal notifications, blocked notifications, milestone-ready signals,
  * and classifies commands as quick (single-turn) vs long-running.
+ *
+ * Also defines exit code constants and the status→exit-code mapping function.
+ */
+// ---------------------------------------------------------------------------
+// Exit Code Constants
+// ---------------------------------------------------------------------------
+export const EXIT_SUCCESS = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_BLOCKED = 10;
+export const EXIT_CANCELLED = 11;
+/**
+ * Map a headless session status string to its standardized exit code.
+ *
+ *   success   → 0
+ *   error     → 1
+ *   timeout   → 1
+ *   blocked   → 10
+ *   cancelled → 11
+ *
+ * Unknown statuses default to EXIT_ERROR (1).
  */
+export function mapStatusToExitCode(status) {
+    switch (status) {
+        case 'success':
+        case 'complete':
+            return EXIT_SUCCESS;
+        case 'error':
+        case 'timeout':
+            return EXIT_ERROR;
+        case 'blocked':
+            return EXIT_BLOCKED;
+        case 'cancelled':
+            return EXIT_CANCELLED;
+        default:
+            return EXIT_ERROR;
+    }
+}
 // ---------------------------------------------------------------------------
 // Completion Detection
 // ---------------------------------------------------------------------------

package/dist/headless-query.js

@@ -36,7 +36,7 @@ export async function handleQuery(basePath) {
     const state = await deriveState(basePath);
     // Derive next dispatch action
     let next;
-    if (!state.activeMilestone) {
+    if (!state.activeMilestone?.id) {
         next = {
             action: 'stop',
             reason: state.phase === 'complete' ? 'All milestones complete.' : state.nextAction,

package/dist/headless-types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Headless Types — shared types for the headless orchestrator surface.
+ *
+ * Contains the structured result type emitted in --output-format json mode
+ * and the output format discriminator.
+ */
+export type OutputFormat = 'text' | 'json' | 'stream-json';
+export declare const VALID_OUTPUT_FORMATS: ReadonlySet<string>;
+export interface HeadlessJsonResult {
+    status: 'success' | 'error' | 'blocked' | 'cancelled' | 'timeout';
+    exitCode: number;
+    sessionId?: string;
+    duration: number;
+    cost: {
+        total: number;
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens: number;
+        cache_write_tokens: number;
+    };
+    toolCalls: number;
+    events: number;
+    milestone?: string;
+    phase?: string;
+    nextAction?: string;
+    artifacts?: string[];
+    commits?: string[];
+}

package/dist/headless-types.js

@@ -0,0 +1,7 @@
+/**
+ * Headless Types — shared types for the headless orchestrator surface.
+ *
+ * Contains the structured result type emitted in --output-format json mode
+ * and the output format discriminator.
+ */
+export const VALID_OUTPUT_FORMATS = new Set(['text', 'json', 'stream-json']);

package/dist/headless.d.ts

@@ -6,13 +6,16 @@
  * progress to stderr.
  *
  * Exit codes:
- *   0 — complete (command finished successfully)
- *   1 — error or timeout
- *   2 — blocked (command reported a blocker)
+ *   0  — complete (command finished successfully)
+ *   1  — error or timeout
+ *   10 — blocked (command reported a blocker)
+ *   11 — cancelled (SIGINT/SIGTERM received)
  */
+import type { OutputFormat } from './headless-types.js';
 export interface HeadlessOptions {
     timeout: number;
     json: boolean;
+    outputFormat: OutputFormat;
     model?: string;
     command: string;
     commandArgs: string[];
@@ -25,6 +28,8 @@ export interface HeadlessOptions {
     responseTimeout?: number;
     answers?: string;
     eventFilter?: Set<string>;
+    resumeSession?: string;
+    bare?: boolean;
 }
 export declare function parseHeadlessArgs(argv: string[]): HeadlessOptions;
 export declare function runHeadless(options: HeadlessOptions): Promise<void>;

package/dist/headless.js

@@ -6,16 +6,18 @@
  * progress to stderr.
  *
  * Exit codes:
- *   0 — complete (command finished successfully)
- *   1 — error or timeout
- *   2 — blocked (command reported a blocker)
+ *   0  — complete (command finished successfully)
+ *   1  — error or timeout
+ *   10 — blocked (command reported a blocker)
+ *   11 — cancelled (SIGINT/SIGTERM received)
  */
 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 { isTerminalNotification, isBlockedNotification, isMilestoneReadyNotification, isQuickCommand, FIRE_AND_FORGET_METHODS, IDLE_TIMEOUT_MS, NEW_MILESTONE_IDLE_TIMEOUT_MS, EXIT_SUCCESS, EXIT_ERROR, EXIT_BLOCKED, EXIT_CANCELLED, } from './headless-events.js';
+import { VALID_OUTPUT_FORMATS } from './headless-types.js';
 import { handleExtensionUIRequest, formatProgress, startSupervisedStdinReader, } from './headless-ui.js';
 import { loadContext, bootstrapGsdProject, } from './headless-context.js';
 // ---------------------------------------------------------------------------
@@ -25,6 +27,7 @@ export function parseHeadlessArgs(argv) {
     const options = {
         timeout: 300_000,
         json: false,
+        outputFormat: 'text',
         command: 'auto',
         commandArgs: [],
     };
@@ -44,6 +47,18 @@ export function parseHeadlessArgs(argv) {
             }
             else if (arg === '--json') {
                 options.json = true;
+                options.outputFormat = 'stream-json';
+            }
+            else if (arg === '--output-format' && i + 1 < args.length) {
+                const fmt = args[++i];
+                if (!VALID_OUTPUT_FORMATS.has(fmt)) {
+                    process.stderr.write(`[headless] Error: --output-format must be one of: text, json, stream-json (got '${fmt}')\n`);
+                    process.exit(1);
+                }
+                options.outputFormat = fmt;
+                if (fmt === 'stream-json' || fmt === '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
@@ -74,10 +89,16 @@ export function parseHeadlessArgs(argv) {
             else if (arg === '--events' && i + 1 < args.length) {
                 options.eventFilter = new Set(args[++i].split(','));
                 options.json = true; // --events implies --json
+                if (options.outputFormat === 'text') {
+                    options.outputFormat = 'stream-json';
+                }
             }
             else if (arg === '--supervised') {
                 options.supervised = true;
                 options.json = true; // supervised implies json
+                if (options.outputFormat === 'text') {
+                    options.outputFormat = 'stream-json';
+                }
             }
             else if (arg === '--response-timeout' && i + 1 < args.length) {
                 options.responseTimeout = parseInt(args[++i], 10);
@@ -86,6 +107,12 @@ export function parseHeadlessArgs(argv) {
                     process.exit(1);
                 }
             }
+            else if (arg === '--resume' && i + 1 < args.length) {
+                options.resumeSession = args[++i];
+            }
+            else if (arg === '--bare') {
+                options.bare = true;
+            }
         }
         else if (!positionalStarted) {
             positionalStarted = true;
@@ -106,7 +133,7 @@ export async function runHeadless(options) {
     while (true) {
         const result = await runHeadlessOnce(options, restartCount);
         // Success or blocked — exit normally
-        if (result.exitCode === 0 || result.exitCode === 2) {
+        if (result.exitCode === EXIT_SUCCESS || result.exitCode === EXIT_BLOCKED) {
             process.exit(result.exitCode);
         }
         // Crash/error — check if we should restart
@@ -216,6 +243,10 @@ async function runHeadlessOnce(options, restartCount) {
     if (injector) {
         clientOptions.env = injector.getSecretEnvVars();
     }
+    // Propagate --bare to the child process
+    if (options.bare) {
+        clientOptions.args = [...(clientOptions.args || []), '--bare'];
+    }
     const client = new RpcClient(clientOptions);
     // Event tracking
     let totalEvents = 0;
@@ -278,7 +309,7 @@ async function runHeadlessOnce(options, restartCount) {
     const timeoutTimer = options.timeout > 0
         ? setTimeout(() => {
             process.stderr.write(`[headless] Timeout after ${options.timeout / 1000}s\n`);
-            exitCode = 1;
+            exitCode = EXIT_ERROR;
             resolveCompletion();
         }, options.timeout)
         : null;
@@ -319,7 +350,7 @@ async function runHeadlessOnce(options, restartCount) {
             if (injector && !FIRE_AND_FORGET_METHODS.has(String(eventObj.method ?? ''))) {
                 if (injector.tryHandle(eventObj, stdinWriter)) {
                     if (completed) {
-                        exitCode = blocked ? 2 : 0;
+                        exitCode = blocked ? EXIT_BLOCKED : EXIT_SUCCESS;
                         resolveCompletion();
                     }
                     return;
@@ -343,7 +374,7 @@ async function runHeadlessOnce(options, restartCount) {
             }
             // If we detected a terminal notification, resolve after responding
             if (completed) {
-                exitCode = blocked ? 2 : 0;
+                exitCode = blocked ? EXIT_BLOCKED : EXIT_SUCCESS;
                 resolveCompletion();
                 return;
             }
@@ -361,7 +392,7 @@ async function runHeadlessOnce(options, restartCount) {
     const signalHandler = () => {
         process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
         interrupted = true;
-        exitCode = 1;
+        exitCode = EXIT_CANCELLED;
         client.stop().finally(() => {
             if (timeoutTimer)
                 clearTimeout(timeoutTimer);
@@ -411,7 +442,7 @@ async function runHeadlessOnce(options, restartCount) {
         if (!completed) {
             const msg = `[headless] Child process exited unexpectedly with code ${code ?? 'null'}\n`;
             process.stderr.write(msg);
-            exitCode = 1;
+            exitCode = EXIT_ERROR;
             resolveCompletion();
         }
     });
@@ -425,14 +456,14 @@ async function runHeadlessOnce(options, restartCount) {
     }
     catch (err) {
         process.stderr.write(`[headless] Error: Failed to send prompt: ${err instanceof Error ? err.message : String(err)}\n`);
-        exitCode = 1;
+        exitCode = EXIT_ERROR;
     }
     // Wait for completion
-    if (exitCode === 0 || exitCode === 2) {
+    if (exitCode === EXIT_SUCCESS || exitCode === EXIT_BLOCKED) {
         await completionPromise;
     }
     // Auto-mode chaining: if --auto and milestone creation succeeded, send /gsd auto
-    if (isNewMilestone && options.auto && milestoneReady && !blocked && exitCode === 0) {
+    if (isNewMilestone && options.auto && milestoneReady && !blocked && exitCode === EXIT_SUCCESS) {
         if (!options.json) {
             process.stderr.write('[headless] Milestone ready — chaining into auto-mode...\n');
         }
@@ -451,9 +482,9 @@ async function runHeadlessOnce(options, restartCount) {
         }
         catch (err) {
             process.stderr.write(`[headless] Error: Failed to start auto-mode: ${err instanceof Error ? err.message : String(err)}\n`);
-            exitCode = 1;
+            exitCode = EXIT_ERROR;
         }
-        if (exitCode === 0 || exitCode === 2) {
+        if (exitCode === EXIT_SUCCESS || exitCode === EXIT_BLOCKED) {
             await autoCompletionPromise;
         }
     }
@@ -471,7 +502,7 @@ async function runHeadlessOnce(options, restartCount) {
     await client.stop();
     // Summary
     const duration = ((Date.now() - startTime) / 1000).toFixed(1);
-    const status = blocked ? 'blocked' : exitCode === 1 ? (totalEvents === 0 ? 'error' : 'timeout') : 'complete';
+    const status = blocked ? 'blocked' : exitCode === EXIT_CANCELLED ? 'cancelled' : exitCode === EXIT_ERROR ? (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`);

package/dist/help-text.js

@@ -87,9 +87,12 @@ const SUBCOMMAND_HELP = {
         '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',
+        '  --timeout N            Overall timeout in ms (default: 300000)',
+        '  --json                 JSONL event stream to stdout (alias for --output-format stream-json)',
+        '  --output-format <fmt>  Output format: text (default), json (structured result), stream-json (JSONL events)',
+        '  --bare                 Minimal context: skip CLAUDE.md, AGENTS.md, user settings, user skills',
+        '  --resume <id>          Resume a prior headless session by ID',
+        '  --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)',
@@ -108,11 +111,19 @@ const SUBCOMMAND_HELP = {
         '  --auto               Start auto-mode after milestone creation',
         '  --verbose            Show tool calls in progress output',
         '',
+        'Output formats:',
+        '  text         Human-readable progress on stderr (default)',
+        '  json         Collect events silently, emit structured HeadlessJsonResult on stdout at exit',
+        '  stream-json  Stream JSONL events to stdout in real time (same as --json)',
+        '',
         'Examples:',
         '  gsd headless                                    Run /gsd auto',
         '  gsd headless next                               Run one unit',
-        '  gsd headless --json status                      Machine-readable status',
+        '  gsd headless --output-format json auto           Structured JSON result on stdout',
+        '  gsd headless --json status                      Machine-readable JSONL stream',
         '  gsd headless --timeout 60000                    With 1-minute timeout',
+        '  gsd headless --bare auto                        Minimal context (CI/ecosystem use)',
+        '  gsd headless --resume abc123 auto               Resume a prior session',
         '  gsd headless new-milestone --context spec.md    Create milestone from file',
         '  cat spec.md | gsd headless new-milestone --context -   From stdin',
         '  gsd headless new-milestone --context spec.md --auto    Create + auto-execute',
@@ -121,7 +132,7 @@ const SUBCOMMAND_HELP = {
         '  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',
+        'Exit codes: 0 = success, 1 = error/timeout, 10 = blocked, 11 = cancelled',
     ].join('\n'),
 };
 // Alias: `gsd wt --help` → same as `gsd worktree --help`

package/dist/onboarding.js

@@ -568,10 +568,11 @@ async function runToolKeysStep(p, pc, authStorage) {
 }
 // ─── Remote Questions Step ────────────────────────────────────────────────────
 async function runRemoteQuestionsStep(p, pc, authStorage) {
-    // Check existing config
-    const hasDiscord = authStorage.has('discord_bot') && !!authStorage.get('discord_bot')?.key;
-    const hasSlack = authStorage.has('slack_bot') && !!authStorage.get('slack_bot')?.key;
-    const hasTelegram = authStorage.has('telegram_bot') && !!authStorage.get('telegram_bot')?.key;
+    // Check existing config — use getCredentialsForProvider to skip empty-key entries
+    const hasValidKey = (provider) => authStorage.getCredentialsForProvider(provider).some((c) => c.type === 'api_key' && c.key);
+    const hasDiscord = hasValidKey('discord_bot');
+    const hasSlack = hasValidKey('slack_bot');
+    const hasTelegram = hasValidKey('telegram_bot');
     const existingChannel = hasDiscord ? 'Discord' : hasSlack ? 'Slack' : hasTelegram ? 'Telegram' : null;
     const options = [];
     if (existingChannel) {

package/dist/remote-questions-config.js

@@ -14,7 +14,7 @@ import { appRoot } from "./app-paths.js";
 // boundary — this file is compiled by tsc, but preferences.ts is loaded
 // via jiti at runtime. Importing it as .js fails because no .js exists
 // in dist/. See #592, #1110.
-const GLOBAL_PREFERENCES_PATH = join(appRoot, "preferences.md");
+const GLOBAL_PREFERENCES_PATH = join(appRoot, "PREFERENCES.md");
 export function saveRemoteQuestionsConfig(channel, channelId) {
     const prefsPath = GLOBAL_PREFERENCES_PATH;
     const block = [

package/dist/resources/extensions/async-jobs/async-bash-tool.js

@@ -7,7 +7,7 @@
  */
 import { getShellConfig, sanitizeCommand, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, } from "@gsd/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createWriteStream } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -23,19 +23,33 @@ function getTempFilePath() {
     return join(tmpdir(), `pi-async-bash-${id}.log`);
 }
 /**
- * Kill a process and its children. Uses process group kill on Unix.
+ * Kill a process and its children (cross-platform).
+ * Uses process group kill on Unix; taskkill /F /T on Windows.
  */
 function killTree(pid) {
-    try {
-        // Kill the process group (negative PID)
-        process.kill(-pid, "SIGTERM");
+    if (process.platform === "win32") {
+        try {
+            spawnSync("taskkill", ["/F", "/T", "/PID", String(pid)], {
+                timeout: 5_000,
+                stdio: "ignore",
+            });
+        }
+        catch {
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch { /* already exited */ }
+        }
     }
-    catch {
+    else {
         try {
-            process.kill(pid, "SIGTERM");
+            process.kill(-pid, "SIGTERM");
         }
         catch {
-            // Already exited
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch { /* already exited */ }
         }
     }
 }
@@ -96,9 +110,13 @@ function executeBashInBackground(command, cwd, signal, timeout) {
         const { shell, args } = getShellConfig();
         const rewrittenCommand = rewriteCommandWithRtk(command);
         const resolvedCommand = sanitizeCommand(rewrittenCommand);
+        // On Windows, detached: true sets CREATE_NEW_PROCESS_GROUP which can
+        // cause EINVAL in VSCode/ConPTY terminal contexts.  The bg-shell
+        // extension already guards this (process-manager.ts); align here.
+        // Process-tree cleanup uses taskkill /F /T on Windows regardless.
         const child = spawn(shell, [...args, resolvedCommand], {
             cwd,
-            detached: true,
+            detached: process.platform !== "win32",
             env: { ...process.env },
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -118,14 +136,8 @@ function executeBashInBackground(command, cwd, signal, timeout) {
                 // If the process ignores SIGTERM, escalate to SIGKILL
                 sigkillHandle = setTimeout(() => {
                     if (child.pid) {
-                        try {
-                            process.kill(-child.pid, "SIGKILL");
-                        }
-                        catch { /* ignore */ }
-                        try {
-                            process.kill(child.pid, "SIGKILL");
-                        }
-                        catch { /* ignore */ }
+                        // killTree already uses taskkill /F /T on Windows
+                        killTree(child.pid);
                     }
                     // Hard deadline: if even SIGKILL doesn't trigger 'close',
                     // force-resolve so the job doesn't hang forever (#2186).

package/dist/resources/extensions/async-jobs/job-manager.js

@@ -121,7 +121,10 @@ export class AsyncJobManager {
     deliverResult(job) {
         if (!this.onJobComplete)
             return;
-        this.onJobComplete(job);
+        // Defer delivery by one microtask so await_job's .then() chain runs first
+        // and can set job.awaited = true before onJobComplete checks it (#2762).
+        const cb = this.onJobComplete;
+        queueMicrotask(() => cb(job));
     }
     scheduleEviction(id) {
         const existing = this.evictionTimers.get(id);