gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.84c045fd2

package/README.md

@@ -310,7 +310,9 @@ This is what makes GSD different. Run it, walk away, come back to built software
 /gsd auto
 ```
 
-Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode reads disk state again and dispatches the next unit.
+Auto mode is a state machine driven by the GSD database at the project root. It derives the next unit of work from authoritative SQLite state, creates a fresh agent session, injects a focused prompt with all relevant context pre-inlined, and lets the LLM execute. When the LLM finishes, auto mode persists the result to the database, refreshes markdown projections such as `STATE.md`, and dispatches the next unit.
+
+The database is authoritative for milestones, slices, tasks, requirements, decisions, summaries, and completion status. Markdown under `.gsd/` is a rendered projection for review, prompts, and git-friendly history; it is not a runtime fallback unless you explicitly run a recovery/import command. In worktree mode, project-root DB state remains authoritative and worktree markdown projections are not synced back as state.
 
 **What happens under the hood:**
 
@@ -318,7 +320,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 2. **Context pre-loading** — The dispatch prompt includes inlined task plans, slice plans, prior task summaries, dependency summaries, roadmap excerpts, and decisions register. The LLM starts with everything it needs instead of spending tool calls reading files.
 
-3. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences.
+3. **Git isolation** — When `git.isolation` is set to `worktree` or `branch`, each milestone runs on its own `milestone/<MID>` branch (in a worktree or in-place). All slice work commits sequentially — no branch switching, no merge conflicts. When the milestone completes, it's squash-merged to main as one clean commit. The default is `none` (work on the current branch), configurable via preferences. If `worktree` is configured in a repo with no committed `HEAD`, GSD temporarily behaves as `none` until the first commit exists because git worktrees need a committed start point.
 
 4. **Crash recovery** — A lock file tracks the current unit. If the session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. Parallel orchestrator state is persisted to disk with PID liveness detection, so multi-worker sessions survive crashes too. In headless mode, crashes trigger automatic restart with exponential backoff (default 3 attempts).
 
@@ -450,6 +452,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd`                  | Step mode — executes one unit at a time, pauses between each                  |
 | `/gsd next`             | Explicit step mode (same as bare `/gsd`)                                      |
 | `/gsd auto`             | Autonomous mode — researches, plans, executes, commits, repeats               |
+| `/gsd new-project [--deep]` | Bootstrap a project with staged project-level discovery                  |
 | `/gsd quick`            | Execute a quick task with GSD guarantees, skip planning overhead              |
 | `/gsd stop`             | Stop auto mode gracefully                                                     |
 | `/gsd steer`            | Hard-steer plan documents during execution                                    |
@@ -471,6 +474,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd logs`             | Browse activity, debug, and metrics logs                                      |
 | `/gsd export --html`    | Generate HTML report for current or completed milestone                       |
 | `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove                        |
+| `/gsd worktree` (`/gsd wt`) | TUI worktree management — list, merge, clean, remove with safety checks   |
 | `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                                |
 | `/exit`                 | Graceful shutdown — saves session state before exiting                        |
 | `/kill`                 | Kill GSD process immediately                                                  |
@@ -497,11 +501,15 @@ Every dispatch is carefully constructed. The LLM never wastes tool calls on orie
 
 | Artifact           | Purpose                                                         |
 | ------------------ | --------------------------------------------------------------- |
+| `gsd.db`           | Authoritative runtime state for hierarchy and completion        |
 | `PROJECT.md`       | Living doc — what the project is right now                      |
+| `REQUIREMENTS.md`  | Project-level capability contract and out-of-scope list         |
 | `DECISIONS.md`     | Append-only register of architectural decisions                 |
 | `KNOWLEDGE.md`     | Cross-session rules, patterns, and lessons learned              |
 | `RUNTIME.md`       | Runtime context — API endpoints, env vars, services (v2.39)     |
-| `STATE.md`         | Quick-glance dashboard — always read first                      |
+| `runtime/research-decision.json` | Deep-mode marker for project research vs skip       |
+| `research/*.md`    | Optional deep-mode project research: stack, features, architecture, pitfalls |
+| `STATE.md`         | Quick-glance dashboard rendered from the database                |
 | `M001-ROADMAP.md`  | Milestone plan with slice checkboxes, risk levels, dependencies |
 | `M001-CONTEXT.md`  | User decisions from the discuss phase                           |
 | `M001-RESEARCH.md` | Codebase and ecosystem research                                 |
@@ -597,6 +605,7 @@ auto_report: true
 | Setting                           | What it controls                                                                                      |
 | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | `models.*`                        | Per-phase model selection — string for a single model, or `{model, fallbacks}` for automatic failover |
+| `planning_depth`                  | `light` / `deep` — opt into staged project discovery before milestone planning                         |
 | `skill_discovery`                 | `auto` / `suggest` / `off` — how GSD finds and applies skills                                         |
 | `auto_supervisor.*`               | Timeout thresholds for auto mode supervision                                                          |
 | `budget_ceiling`                  | USD ceiling — auto mode pauses when reached                                                           |
@@ -605,7 +614,7 @@ auto_report: true
 | `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`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work    |
+| `git.isolation`                   | `none` (default), `worktree`, or `branch` — enable worktree or branch isolation for milestone work. `worktree` requires a committed `HEAD`; zero-commit repos temporarily run as `none`    |
 | `git.manage_gitignore`            | Set `false` to prevent GSD from modifying `.gitignore`                                                |
 | `verification_commands`           | Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`)        |
 | `verification_auto_fix`           | Auto-retry on verification failures (default: true)                                                   |
@@ -702,7 +711,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/completed-units*.json
 # State manifest — workflow state for recovery
 .gsd/state-manifest.json
-# Derived state cache — regenerated from plan/roadmap files on disk
+# Derived state projection — regenerated from the authoritative database
 .gsd/STATE.md
 # Per-developer token/cost accumulator
 .gsd/metrics.json
@@ -714,7 +723,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/worktrees/
 # Parallel orchestration IPC and worker status
 .gsd/parallel/
-# SQLite database and WAL sidecars — checkpoint state, forensics data
+# SQLite database and WAL sidecars — authoritative runtime state, local only
 .gsd/gsd.db*
 # Daily-rotated event journal — structured event log for forensics
 .gsd/journal/
@@ -779,7 +788,7 @@ gsd (CLI binary)
 - **`pkg/` shim directory** — `PI_PACKAGE_DIR` points here (not project root) to avoid Pi's theme resolution collision with our `src/` directory. Contains only `piConfig` and theme assets.
 - **Two-file loader pattern** — `loader.ts` sets all env vars with zero SDK imports, then dynamic-imports `cli.ts` which does static SDK imports. This ensures `PI_PACKAGE_DIR` is set before any SDK code evaluates.
 - **Always-overwrite sync** — `npm update -g` takes effect immediately. Bundled extensions and agents are synced to `~/.gsd/agent/` on every launch, not just first run.
-- **State lives on disk** — `.gsd/` is the source of truth. Auto mode reads it, writes it, and advances based on what it finds. No in-memory state survives across sessions.
+- **DB-authoritative state** — the project-root GSD database is the runtime source of truth. `.gsd/` markdown files are rendered projections for review, prompt context, and git history. No in-memory state survives across sessions.
 
 ---
 

package/dist/bundled-resource-path.d.ts

@@ -1,3 +1,10 @@
+export type FileExists = (path: string) => boolean;
+export declare function resolvePackageRoot(importUrl: string): string;
+export declare function hasCompleteBundledResources(resourcesDir: string, fileExists?: FileExists): boolean;
+export declare function resolveBundledResourcesDirFromPackageRoot(packageRoot: string, fileExists?: FileExists): string;
+export declare function resolveBundledResourcesDir(importUrl: string, fileExists?: FileExists): string;
+export declare function resolveBundledResource(importUrl: string, ...segments: string[]): string;
+export declare function resolveBundledGsdExtensionModule(importUrl: string, moduleFile: string, fileExists?: FileExists): string;
 /**
  * Resolve bundled raw resource files from the package root.
  *

package/dist/bundled-resource-path.js

@@ -1,5 +1,38 @@
+import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+export function resolvePackageRoot(importUrl) {
+    const moduleDir = dirname(fileURLToPath(importUrl));
+    return resolve(moduleDir, "..");
+}
+export function hasCompleteBundledResources(resourcesDir, fileExists = existsSync) {
+    return fileExists(join(resourcesDir, "agents")) &&
+        fileExists(join(resourcesDir, "extensions"));
+}
+export function resolveBundledResourcesDirFromPackageRoot(packageRoot, fileExists = existsSync) {
+    const distResources = join(packageRoot, "dist", "resources");
+    const srcResources = join(packageRoot, "src", "resources");
+    return hasCompleteBundledResources(distResources, fileExists)
+        ? distResources
+        : srcResources;
+}
+export function resolveBundledResourcesDir(importUrl, fileExists = existsSync) {
+    return resolveBundledResourcesDirFromPackageRoot(resolvePackageRoot(importUrl), fileExists);
+}
+export function resolveBundledResource(importUrl, ...segments) {
+    return join(resolveBundledResourcesDir(importUrl), ...segments);
+}
+export function resolveBundledGsdExtensionModule(importUrl, moduleFile, fileExists = existsSync) {
+    const packageRoot = resolvePackageRoot(importUrl);
+    const distResources = join(packageRoot, "dist", "resources");
+    const jsFile = moduleFile.replace(/\.ts$/, ".js");
+    const distModule = join(distResources, "extensions", "gsd", jsFile);
+    if (hasCompleteBundledResources(distResources, fileExists) && fileExists(distModule)) {
+        return distModule;
+    }
+    const tsFile = moduleFile.replace(/\.js$/, ".ts");
+    return join(packageRoot, "src", "resources", "extensions", "gsd", tsFile);
+}
 /**
  * Resolve bundled raw resource files from the package root.
  *
@@ -8,7 +41,6 @@ import { fileURLToPath } from "node:url";
  * `src/resources/**`, not next to the compiled entry point.
  */
 export function resolveBundledSourceResource(importUrl, ...segments) {
-    const moduleDir = dirname(fileURLToPath(importUrl));
-    const packageRoot = resolve(moduleDir, "..");
+    const packageRoot = resolvePackageRoot(importUrl);
     return join(packageRoot, "src", "resources", ...segments);
 }

package/dist/claude-cli-check.js

@@ -5,6 +5,21 @@
 // Set GSD_CLAUDE_DEBUG=1 to log probe output to stderr. Useful when
 // diagnosing platform-specific detection failures (Issue #4997).
 import { execFileSync } from 'node:child_process';
+/**
+ * Spawn the Claude CLI without triggering Node's DEP0190.
+ *
+ * Passing `args` together with `shell: true` is deprecated in Node 22+
+ * because the args are concatenated into the command string without
+ * escaping. On Windows we still need a shell to resolve `.cmd` shims, so
+ * we invoke `cmd /c <command> <args...>` explicitly. On POSIX we don't
+ * need a shell at all.
+ */
+function spawnClaude(command, args, opts) {
+    if (process.platform === 'win32') {
+        return execFileSync('cmd', ['/c', command, ...args], opts);
+    }
+    return execFileSync(command, args, opts);
+}
 /**
  * Platform-correct binary name for the Claude Code CLI.
  *
@@ -44,10 +59,9 @@ function debugLog(...parts) {
 function findWorkingCommand() {
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            execFileSync(command, ['--version'], {
+            spawnClaude(command, ['--version'], {
                 timeout: VERSION_TIMEOUT_MS,
                 stdio: 'pipe',
-                shell: process.platform === 'win32',
             });
             debugLog('version probe ok via', command);
             return command;
@@ -93,10 +107,9 @@ function parseAuthStatus(output) {
 function probeAuth(command) {
     // Try --json first (newer CLIs).
     try {
-        const out = execFileSync(command, ['auth', 'status', '--json'], {
+        const out = spawnClaude(command, ['auth', 'status', '--json'], {
             timeout: AUTH_TIMEOUT_MS,
             stdio: 'pipe',
-            shell: process.platform === 'win32',
         }).toString();
         debugLog('auth status --json output:', out.slice(0, 200));
         const parsed = parseAuthStatus(out);
@@ -108,10 +121,9 @@ function probeAuth(command) {
     }
     // Fallback: plain `auth status` (older CLIs that don't accept --json).
     try {
-        const out = execFileSync(command, ['auth', 'status'], {
+        const out = spawnClaude(command, ['auth', 'status'], {
             timeout: AUTH_TIMEOUT_MS,
             stdio: 'pipe',
-            shell: process.platform === 'win32',
         }).toString();
         debugLog('auth status output:', out.slice(0, 200));
         return parseAuthStatus(out);

package/dist/cli-auto-routing.d.ts

@@ -0,0 +1 @@
+export declare function shouldRedirectAutoToHeadless(subcommand: string | undefined, stdinIsTTY: boolean | undefined, stdoutIsTTY: boolean | undefined): boolean;

package/dist/cli-auto-routing.js

@@ -0,0 +1,5 @@
+export function shouldRedirectAutoToHeadless(subcommand, stdinIsTTY, stdoutIsTTY) {
+    if (subcommand !== 'auto')
+        return false;
+    return stdinIsTTY !== true || stdoutIsTTY !== true;
+}

package/dist/cli.js

@@ -9,6 +9,7 @@ import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
 import { shouldBypassManagedResourceMismatchGate } from './cli-policy.js';
+import { shouldRedirectAutoToHeadless } from './cli-auto-routing.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 import { applySecurityOverrides } from './security-overrides.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
@@ -409,10 +410,10 @@ function flushPendingProviderRegistrations(resourceLoader, modelRegistry) {
     }
     runtime.pendingProviderRegistrations = [];
 }
-// `gsd auto [args...]` — shorthand for `gsd headless auto [args...]` (#2732)
-// Without this, `gsd auto` falls through to the interactive TUI which hangs
-// when stdin/stdout are piped (non-TTY environments).
-if (cliFlags.messages[0] === 'auto') {
+// `gsd auto [args...]` with piped stdin/stdout — shorthand for
+// `gsd headless auto [args...]` (#2732). Keep terminal TTY launches in the
+// interactive path so Warp/iTerm/Terminal retain foreground ownership.
+if (shouldRedirectAutoToHeadless(cliFlags.messages[0], process.stdin.isTTY, process.stdout.isTTY)) {
     await runHeadlessFromAuto(buildHeadlessAutoArgs(cliFlags));
 }
 // ---------------------------------------------------------------------------
@@ -656,16 +657,6 @@ if (!cliFlags.worktree && !isPrintMode) {
 }
 markStartup('worktreeStatusBanner');
 // ---------------------------------------------------------------------------
-// Auto-redirect: `gsd auto` with piped stdout → headless mode (#2732)
-// When stdout is not a TTY (e.g. `gsd auto | cat`, `gsd auto > file`),
-// the TUI cannot render and the process hangs. Redirect to headless mode
-// which handles non-interactive output gracefully.
-// ---------------------------------------------------------------------------
-if (cliFlags.messages[0] === 'auto' && !process.stdout.isTTY) {
-    process.stderr.write('[gsd] stdout is not a terminal — running auto-mode in headless mode.\n');
-    await runHeadlessFromAuto(cliFlags.messages.slice(1));
-}
-// ---------------------------------------------------------------------------
 // Interactive mode — normal TTY session
 // ---------------------------------------------------------------------------
 await ensureRtkBootstrap();

package/dist/headless-query.js

@@ -17,7 +17,7 @@ import { createJiti } from '@mariozechner/jiti';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { resolveBundledSourceResource } from './bundled-resource-path.js';
+import { resolveBundledGsdExtensionModule } from './bundled-resource-path.js';
 const jiti = createJiti(fileURLToPath(import.meta.url), { interopDefault: true, debug: false });
 const { existsSync } = await import('node:fs');
 /**
@@ -30,7 +30,8 @@ const { existsSync } = await import('node:fs');
  * #3471 contract can be exercised in tests without spawning a subprocess.
  */
 export function resolveGsdAgentExtensionsDir(env = process.env) {
-    return join(env.GSD_AGENT_DIR || join(homedir(), '.gsd', 'agent'), 'extensions', 'gsd');
+    const agentRoot = env.GSD_AGENT_DIR || join(env.GSD_HOME || join(homedir(), '.gsd'), 'agent');
+    return join(agentRoot, 'extensions', 'gsd');
 }
 /**
  * Decide whether headless-query should load extensions from the agent
@@ -41,13 +42,27 @@ export function shouldUseAgentExtensionsDir(opts) {
     const env = opts.env ?? process.env;
     const fileExists = opts.fileExists ?? existsSync;
     const agentDir = resolveGsdAgentExtensionsDir(env);
-    return { agentDir, useAgentDir: fileExists(join(agentDir, 'state.ts')) };
+    return {
+        agentDir,
+        useAgentDir: fileExists(join(agentDir, 'state.ts')) || fileExists(join(agentDir, 'state.js')),
+    };
 }
 const agentExtensionsDir = resolveGsdAgentExtensionsDir();
-const useAgentDir = existsSync(join(agentExtensionsDir, 'state.ts'));
+const { useAgentDir } = shouldUseAgentExtensionsDir({ env: process.env });
 const gsdExtensionPath = (...segments) => useAgentDir
-    ? join(agentExtensionsDir, ...segments)
-    : resolveBundledSourceResource(import.meta.url, 'extensions', 'gsd', ...segments);
+    ? resolveAgentExtensionModule(agentExtensionsDir, segments)
+    : resolveBundledGsdExtensionModule(import.meta.url, segments.join('/'));
+function resolveAgentExtensionModule(agentDir, segments) {
+    const requested = join(agentDir, ...segments);
+    if (existsSync(requested))
+        return requested;
+    if (segments.length === 1 && segments[0].endsWith('.ts')) {
+        const jsPath = join(agentDir, segments[0].replace(/\.ts$/, '.js'));
+        if (existsSync(jsPath))
+            return jsPath;
+    }
+    return requested;
+}
 async function loadExtensionModules() {
     const stateModule = await jiti.import(gsdExtensionPath('state.ts'), {});
     const dispatchModule = await jiti.import(gsdExtensionPath('auto-dispatch.ts'), {});

package/dist/headless-recover.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Headless Recover — `gsd headless recover`
+ *
+ * Non-interactive parallel of the `/gsd recover` slash command. Clears the
+ * milestones / slices / tasks tables and re-imports them from the on-disk
+ * markdown projections (ROADMAP.md, PLAN.md, SUMMARY.md, …) via
+ * migrateHierarchyToDb. Mutating: this is the one headless subcommand that
+ * writes to the DB. Required for CI / automation flows that need to
+ * reconcile DB state from markdown without launching an LLM session or a
+ * TTY-bound interactive runtime.
+ *
+ * Output: `gsd-recover: recovered <N>M/<N>S/<N>T hierarchy\n` to stderr on
+ * success — same marker emitted by handleRecover (commands-maintenance.ts)
+ * so callers can distinguish the success path from a silent no-op.
+ *
+ * Exit codes:
+ *   0 — recovery succeeded
+ *   1 — `.gsd/` missing, DB could not be opened, or migration threw
+ */
+export interface RecoverResult {
+    exitCode: number;
+}
+export declare function handleRecover(basePath: string): Promise<RecoverResult>;

package/dist/headless-recover.js

@@ -0,0 +1,93 @@
+// gsd-pi — Headless Recover entrypoint
+/**
+ * Headless Recover — `gsd headless recover`
+ *
+ * Non-interactive parallel of the `/gsd recover` slash command. Clears the
+ * milestones / slices / tasks tables and re-imports them from the on-disk
+ * markdown projections (ROADMAP.md, PLAN.md, SUMMARY.md, …) via
+ * migrateHierarchyToDb. Mutating: this is the one headless subcommand that
+ * writes to the DB. Required for CI / automation flows that need to
+ * reconcile DB state from markdown without launching an LLM session or a
+ * TTY-bound interactive runtime.
+ *
+ * Output: `gsd-recover: recovered <N>M/<N>S/<N>T hierarchy\n` to stderr on
+ * success — same marker emitted by handleRecover (commands-maintenance.ts)
+ * so callers can distinguish the success path from a silent no-op.
+ *
+ * Exit codes:
+ *   0 — recovery succeeded
+ *   1 — `.gsd/` missing, DB could not be opened, or migration threw
+ */
+import { createJiti } from '@mariozechner/jiti';
+import { fileURLToPath } from 'node:url';
+import { resolveGsdAgentExtensionsDir, shouldUseAgentExtensionsDir } from './headless-query.js';
+import { resolveBundledGsdExtensionModule } from './bundled-resource-path.js';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+const jiti = createJiti(fileURLToPath(import.meta.url), { interopDefault: true, debug: false });
+const agentExtensionsDir = resolveGsdAgentExtensionsDir();
+const { useAgentDir } = shouldUseAgentExtensionsDir({ env: process.env });
+const gsdExtensionPath = (...segments) => useAgentDir
+    ? resolveAgentExtensionModule(agentExtensionsDir, segments)
+    : resolveBundledGsdExtensionModule(import.meta.url, segments.join('/'));
+function resolveAgentExtensionModule(agentDir, segments) {
+    const requested = join(agentDir, ...segments);
+    if (existsSync(requested))
+        return requested;
+    if (segments.length === 1 && segments[0].endsWith('.ts')) {
+        const jsPath = join(agentDir, segments[0].replace(/\.ts$/, '.js'));
+        if (existsSync(jsPath))
+            return jsPath;
+    }
+    return requested;
+}
+async function loadExtensionModules() {
+    const stateModule = await jiti.import(gsdExtensionPath('state.ts'), {});
+    const dbModule = await jiti.import(gsdExtensionPath('gsd-db.ts'), {});
+    const importerModule = await jiti.import(gsdExtensionPath('md-importer.ts'), {});
+    const dynamicToolsModule = await jiti.import(gsdExtensionPath('bootstrap/dynamic-tools.ts'), {});
+    return {
+        ensureDbOpen: dynamicToolsModule.ensureDbOpen,
+        isDbAvailable: dbModule.isDbAvailable,
+        clearEngineHierarchy: dbModule.clearEngineHierarchy,
+        transaction: dbModule.transaction,
+        migrateHierarchyToDb: importerModule.migrateHierarchyToDb,
+        invalidateStateCache: stateModule.invalidateStateCache,
+    };
+}
+export async function handleRecover(basePath) {
+    const gsdDir = join(basePath, '.gsd');
+    if (!existsSync(gsdDir)) {
+        process.stderr.write(`[headless] recover: no .gsd/ directory at ${basePath}\n`);
+        return { exitCode: 1 };
+    }
+    let modules;
+    try {
+        modules = await loadExtensionModules();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[headless] recover: failed to load extension modules: ${msg}\n`);
+        return { exitCode: 1 };
+    }
+    const opened = await modules.ensureDbOpen(basePath);
+    if (!opened || !modules.isDbAvailable()) {
+        process.stderr.write(`[headless] recover: failed to open or create the GSD database at ${basePath}\n`);
+        return { exitCode: 1 };
+    }
+    let counts;
+    try {
+        counts = modules.transaction(() => {
+            modules.clearEngineHierarchy();
+            return modules.migrateHierarchyToDb(basePath);
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[headless] recover failed: ${msg}\n`);
+        return { exitCode: 1 };
+    }
+    modules.invalidateStateCache();
+    process.stderr.write(`gsd-recover: recovered ${counts.milestones}M/${counts.slices}S/${counts.tasks}T hierarchy\n`);
+    return { exitCode: 0 };
+}

package/dist/headless.js

@@ -265,6 +265,15 @@ async function runHeadlessOnce(options, restartCount) {
         const result = await handleQuery(process.cwd());
         return { exitCode: result.exitCode, interrupted: false };
     }
+    // Recover: rebuild DB hierarchy from on-disk markdown projections, no RPC
+    // child needed. This is the one mutating headless subcommand — required for
+    // CI / automation that needs to reconcile DB state from markdown without
+    // launching an interactive TTY-bound runtime.
+    if (options.command === 'recover') {
+        const { handleRecover } = await import('./headless-recover.js');
+        const result = await handleRecover(process.cwd());
+        process.exit(result.exitCode);
+    }
     // Doctor: read-only health check, no RPC child needed (#4904 live-regression).
     // The interactive `/gsd doctor` command lives in the GSD extension; this CLI
     // path lets non-interactive callers (CI, recovery scripts, the live-regression

package/dist/help-text.js

@@ -156,6 +156,7 @@ const SUBCOMMAND_HELP = {
         '  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',
+        '  gsd headless recover                            Rebuild DB hierarchy from markdown (mutating)',
         '',
         'Exit codes: 0 = success, 1 = error/timeout, 10 = blocked, 11 = cancelled',
     ].join('\n'),

package/dist/loader.js

@@ -60,6 +60,7 @@ if (firstArg === '--help' || firstArg === '-h') {
 import { agentDir, appRoot } from './app-paths.js';
 import { applyRtkProcessEnv } from './rtk-shared.js';
 import { serializeBundledExtensionPaths } from './bundled-extension-paths.js';
+import { resolveBundledResourcesDirFromPackageRoot } from './bundled-resource-path.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
 import { loadRegistry, readManifestFromEntryPath, isExtensionEnabled } from './extension-registry.js';
 import { renderLogo } from './logo.js';
@@ -112,15 +113,25 @@ const { Module } = await import('module');
 Module._initPaths?.();
 // GSD_VERSION — expose package version so extensions can display it
 process.env.GSD_VERSION = gsdVersion;
-// GSD_BIN_PATH — absolute path to this loader (dist/loader.js), used by patched subagent
-// to spawn gsd instead of pi when dispatching workflow tasks
-process.env.GSD_BIN_PATH = process.argv[1];
+// GSD_BIN_PATH — absolute path to the CLI entrypoint, used by patched
+// subagent/parallel workers to spawn gsd instead of pi when dispatching
+// workflow tasks. In source-dev mode this must remain scripts/dev-cli.js, not
+// src/loader.ts, because child processes need the --import resolve-ts wrapper.
+const invokedBinPath = process.argv[1];
+const sourceLoaderPath = join(gsdRoot, 'src', 'loader.ts');
+const devCliPath = process.env.GSD_DEV_CLI_PATH?.trim() || join(gsdRoot, 'scripts', 'dev-cli.js');
+const explicitCliPath = process.env.GSD_CLI_PATH?.trim() || process.env.GSD_BIN_PATH?.trim();
+const isSourceLoader = invokedBinPath && resolve(invokedBinPath) === sourceLoaderPath;
+const rawGsdBinPath = explicitCliPath || (isSourceLoader && existsSync(devCliPath) ? devCliPath : invokedBinPath);
+const resolvedGsdBinPath = rawGsdBinPath ? resolve(rawGsdBinPath) : undefined;
+process.env.GSD_BIN_PATH = resolvedGsdBinPath;
+if (!process.env.GSD_CLI_PATH) {
+    process.env.GSD_CLI_PATH = resolvedGsdBinPath;
+}
 // GSD_WORKFLOW_PATH — absolute path to bundled GSD-WORKFLOW.md, used by patched gsd extension
 // when dispatching workflow prompts. Prefers dist/resources/ (stable, set at build time)
 // over src/resources/ (live working tree) — see resource-loader.ts for rationale.
-const distRes = join(gsdRoot, 'dist', 'resources');
-const srcRes = join(gsdRoot, 'src', 'resources');
-const resourcesDir = existsSync(distRes) ? distRes : srcRes;
+const resourcesDir = resolveBundledResourcesDirFromPackageRoot(gsdRoot);
 process.env.GSD_WORKFLOW_PATH = join(resourcesDir, 'GSD-WORKFLOW.md');
 // GSD_BUNDLED_EXTENSION_PATHS — dynamically discovered bundled extension entry points.
 // Uses the shared discoverExtensionEntryPaths() to scan the bundled resources

package/dist/resource-loader.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
 import { loadRegistry, readManifestFromEntryPath, isExtensionEnabled, ensureRegistryEntries } from './extension-registry.js';
+import { resolveBundledResourcesDirFromPackageRoot } from './bundled-resource-path.js';
 let piCodingAgentModulePromise;
 function loadPiCodingAgentModule() {
     return (piCodingAgentModulePromise ??= import('@gsd/pi-coding-agent'));
@@ -19,14 +20,7 @@ function loadPiCodingAgentModule() {
 // dist/resources/ is populated by the build step (`npm run copy-resources`) and
 // reflects the built state, not the currently checked-out branch.
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const distResources = join(packageRoot, 'dist', 'resources');
-const srcResources = join(packageRoot, 'src', 'resources');
-// Use dist/resources only if it has the full expected structure.
-// A partial build (tsc without copy-resources) creates dist/resources/extensions/
-// but not agents/ or skills/, causing initResources to sync from an incomplete source.
-const resourcesDir = (existsSync(distResources) && existsSync(join(distResources, 'agents')))
-    ? distResources
-    : srcResources;
+const resourcesDir = resolveBundledResourcesDirFromPackageRoot(packageRoot);
 const bundledExtensionsDir = join(resourcesDir, 'extensions');
 const resourceVersionManifestName = 'managed-resources.json';
 const resourceFingerprintFileName = '.managed-resources-content-hash';
@@ -717,29 +711,38 @@ function migrateSkillsToEcosystemDir(agentDir) {
 export function hasStaleCompiledExtensionSiblings(extensionsDir, sourceDir = bundledExtensionsDir) {
     if (!existsSync(extensionsDir))
         return false;
-    const sourceFiles = existsSync(sourceDir)
-        ? new Set(readdirSync(sourceDir, { withFileTypes: true })
-            .filter((entry) => entry.isFile())
-            .map((entry) => entry.name))
-        : new Set();
-    for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
-        if (!entry.isFile())
-            continue;
-        if (!entry.name.endsWith('.ts') && !entry.name.endsWith('.js'))
-            continue;
-        const siblingName = entry.name.endsWith('.ts')
-            ? entry.name.replace(/\.ts$/, '.js')
-            : entry.name.replace(/\.js$/, '.ts');
-        if (!existsSync(join(extensionsDir, siblingName)))
+    const sourceFiles = collectRelativeFiles(sourceDir);
+    const installedFiles = collectRelativeFiles(extensionsDir);
+    for (const relPath of installedFiles) {
+        if (!relPath.endsWith('.ts') && !relPath.endsWith('.js'))
             continue;
-        if (sourceFiles.has(entry.name) && sourceFiles.has(siblingName))
+        if (sourceFiles.has(relPath))
             continue;
-        if (sourceFiles.has(entry.name) || sourceFiles.has(siblingName)) {
+        const bundledSibling = relPath.endsWith('.ts')
+            ? relPath.replace(/\.ts$/, '.js')
+            : relPath.replace(/\.js$/, '.ts');
+        if (sourceFiles.has(bundledSibling))
             return true;
-        }
     }
     return false;
 }
+function collectRelativeFiles(rootDir) {
+    const files = new Set();
+    if (!existsSync(rootDir))
+        return files;
+    const visit = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const entryPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                visit(entryPath);
+                continue;
+            }
+            files.add(relative(rootDir, entryPath).replaceAll('\\', '/'));
+        }
+    };
+    visit(rootDir);
+    return files;
+}
 /**
  * Constructs a DefaultResourceLoader that loads extensions from both
  * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-afb1073f61989a78
+858bd1ba482d00d8