gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.8e0e96cfc

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/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
+cc8431019a2c8873

package/dist/resources/GSD-WORKFLOW.md

@@ -542,74 +542,61 @@ If files disagree, **pause and surface to the user**:
 
 ---
 
-## Git Strategy: Branch-Per-Slice with Squash Merge
+## Git Strategy: Sequential Commits with Optional Milestone Isolation
 
-**Principle:** Main is always clean and working. Each slice gets an isolated branch. The user never runs a git command — the agent handles everything.
+**Principle:** GSD keeps work atomic and recoverable. By default, work happens on the current branch. If `git.isolation` is set to `worktree` or `branch`, a milestone branch is used and merged back to the recorded integration branch when the milestone completes. The user never runs a git command — the agent handles everything.
 
-### Branch Lifecycle
+### Isolation Modes
 
-1. **Slice starts** → create branch `gsd/M001/S01` from main
-2. **Per-task commits** on the branch — atomic, descriptive, bisectable
-3. **Slice completes** → squash merge to main as one clean commit
-4. **Branch deleted** — squash commit on main is the permanent record
+| Mode | Where work happens | Branch behavior |
+|------|--------------------|-----------------|
+| `none` (default) | Project root | Current branch, no isolation branch |
+| `worktree` | `.gsd/worktrees/<MID>/` | `milestone/<MID>` branch in a git worktree |
+| `branch` | Project root | `milestone/<MID>` branch checked out in place |
 
-### What Main Looks Like
+In all modes, slices and tasks commit sequentially on the active branch; there are no per-slice branches. The integration branch is captured when the milestone starts, so stale `git.main_branch` preferences do not redirect merge-back.
 
-```
-feat(M001/S03): milestone and slice discuss commands
-feat(M001/S02): extension scaffold and command routing
-feat(M001/S01): file I/O foundation
-```
+### Milestone Lifecycle
 
-One commit per slice. Individually revertable. Reads like a changelog.
+1. **Milestone starts** → capture the current integration branch.
+2. **Optional isolation** → create `milestone/M001` only when `git.isolation` is `worktree` or `branch`.
+3. **Per-task commits** — atomic, descriptive, bisectable.
+4. **Slice completes** → write slice summary, UAT script, roadmap checkbox, and milestone summary.
+5. **Milestone completes** → if isolated, squash-merge the milestone branch back to the captured integration branch and clean up the worktree/branch.
 
-### What the Branch Looks Like
+### What History Looks Like
 
 ```
-gsd/M001/S01:
-  test(S01/T03): round-trip tests passing
-  feat(S01/T03): file writer with round-trip fidelity
-  feat(S01/T02): markdown parser for plan files
-  feat(S01/T01): core types and interfaces
-  docs(S01): add slice plan
+feat: core type definitions
+feat: markdown parser for plan files
+fix: handle empty state rebuild
 ```
 
+In `none` mode these commits land directly on the current branch. In isolated modes they land on `milestone/<MID>` and are squashed back at milestone completion.
+
 ### Commit Conventions
 
 | When | Format | Example |
 |------|--------|---------|
-| Task completed | `{type}(S01/T02): <one-liner from summary>` | Type inferred from title (`feat`, `fix`, `test`, etc.) |
-| Plan/docs committed | `docs(S01): add slice plan` | Planning artifacts |
-| Slice squash to main | `type(M001/S01): <slice title>` | Type inferred from title |
-| State rebuild | `chore(S01/T02): auto-commit after state-rebuild` | Bookkeeping only |
+| Task completed | `{type}: <one-liner from summary>` | Type inferred from title (`feat`, `fix`, `test`, etc.) |
+| State rebuild | `chore: auto-commit after state-rebuild` | Bookkeeping only |
+| Milestone squash | `{type}: <milestone title>` | Type inferred from title |
 
 The system reads the task summary after execution and builds a meaningful commit message:
-- **Subject**: `{type}({sliceId}/{taskId}): {one-liner}` — the one-liner from the summary frontmatter
+- **Subject**: `{type}: {one-liner}` — the one-liner from the summary frontmatter, sanitized to one line
 - **Type**: Inferred from the task title and one-liner (`feat`, `fix`, `test`, `refactor`, `docs`, `perf`, `chore`)
 - **Body**: Key files from the summary frontmatter (up to 8 files listed)
+- **Trailers**: `GSD-Task: S##/T##`; if GitHub sync linked an issue, `Resolves #N`
 
 Commit types: `feat`, `fix`, `test`, `refactor`, `docs`, `perf`, `chore`
 
-### Squash Merge Message
-
-```
-feat(M001/S01): file I/O foundation
-
-Agent can parse, format, load, and save all GSD file types with round-trip fidelity.
-
-Tasks completed:
-- T01: core types and interfaces
-- T02: markdown parser for plan files
-- T03: file writer with round-trip fidelity
-```
-
 ### Rollback
 
 | Problem | Fix |
 |---------|-----|
-| Bad task | `git reset --hard HEAD~1` to previous commit on the branch |
-| Bad slice | `git revert <squash commit>` on main |
-| UAT failure after merge | Fix tasks on `gsd/M001/S01-fix` branch, squash as `fix(M001/S01): <fix>` |
+| Bad task | Revert the task commit on the active branch |
+| Bad milestone squash | Revert the squash commit on the integration branch |
+| UAT failure after merge | Create follow-up fix tasks in the current or next milestone |
 
 ---
 

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

@@ -159,6 +159,10 @@ export class AsyncJobManager {
             this.evictionTimers.delete(id);
             this.jobs.delete(id);
         }, this.evictionMs);
+        // Eviction is housekeeping; it should not keep short-lived test/CLI
+        // processes alive after the real work has finished.
+        if (typeof timer === "object" && "unref" in timer)
+            timer.unref();
         this.evictionTimers.set(id, timer);
     }
     evictOldest() {

package/dist/resources/extensions/bg-shell/bg-shell-lifecycle.js

@@ -6,6 +6,7 @@ import { truncateToWidth, visibleWidth, } from "@gsd/pi-tui";
 import { processes, pendingAlerts, pushAlert, cleanupAll, cleanupSessionProcesses, persistManifest, loadManifest, pruneDeadProcesses, } from "./process-manager.js";
 import { formatUptime, getBgShellLiveCwd, resolveBgShellPersistenceCwd } from "./utilities.js";
 import { formatTokenCount } from "../shared/format-utils.js";
+import { homedir } from "node:os";
 export function registerBgShellLifecycle(pi, state) {
     function syncLatestCtxCwd() {
         if (!state.latestCtx)
@@ -177,8 +178,8 @@ export function registerBgShellLifecycle(pi, state) {
                 render(width) {
                     // ── Line 1: pwd (branch) [session]  ...  bg status ──
                     let pwd = getBgShellLiveCwd(state.latestCtx?.cwd);
-                    const home = process.env.HOME || process.env.USERPROFILE;
-                    if (home && pwd.startsWith(home)) {
+                    const home = homedir();
+                    if (pwd.startsWith(home)) {
                         pwd = `~${pwd.slice(home.length)}`;
                     }
                     const branch = footerData.getGitBranch();

package/dist/resources/extensions/bg-shell/utilities.js

@@ -32,6 +32,7 @@ export function restoreWindowsVTInput() {
 }
 // ── Time Formatting ────────────────────────────────────────────────────────
 import { formatDuration } from "../shared/mod.js";
+import { homedir } from "node:os";
 export const formatUptime = formatDuration;
 export function formatTimeAgo(timestamp) {
     return formatDuration(Date.now() - timestamp) + " ago";
@@ -48,7 +49,7 @@ export function getBgShellLiveCwd(cachedCwd, pathExists = existsSync, getCwd = (
     }
     catch {
         const projectRoot = deriveProjectRootFromAutoWorktree(cachedCwd);
-        const home = process.env.HOME || process.env.USERPROFILE;
+        const home = homedir();
         const fallbacks = [projectRoot, cachedCwd, home, "/"].filter((candidate) => Boolean(candidate));
         for (const candidate of fallbacks) {
             if (candidate !== "/" && !pathExists(candidate))

package/dist/resources/extensions/browser-tools/tools/intent.js

@@ -1,5 +1,4 @@
 import { Type } from "@sinclair/typebox";
-import { StringEnum } from "@gsd/pi-ai";
 import { diffCompactStates } from "../core.js";
 import { setLastActionBeforeState, setLastActionAfterState, } from "../state.js";
 // ---------------------------------------------------------------------------
@@ -15,6 +14,14 @@ const INTENTS = [
     "auth_action",
     "back_navigation",
 ];
+function StringEnum(values, options) {
+    return Type.Unsafe({
+        type: "string",
+        enum: values,
+        ...(options?.description && { description: options.description }),
+        ...(options?.default && { default: options.default }),
+    });
+}
 // ---------------------------------------------------------------------------
 // Scoring evaluate script — runs entirely in-browser via page.evaluate()
 // ---------------------------------------------------------------------------