gsd-pi 2.80.0 → 2.81.0-dev.3cddbbba2

package/README.md

@@ -27,75 +27,61 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.79
+## What's New in v2.81
 
-### DB-Authoritative Runtime State
+### Worktree Safety & Projection
 
-- **Auto-mode coordination tables (#5247)** — workers, leases, dispatches, and a command queue are now first-class DB rows, replacing ad-hoc files for cross-process auto coordination.
-- **`auto.lock` + `paused-session.json` → DB (#5250)** — phase C pt 2 of the runtime-state migration. The on-disk lockfile and paused-session JSON are gone; lock acquisition, stale-lock detection, and pause state all live in `gsd.db`.
-- **Stuck-state migration (#5249)** — `copyPlanningArtifacts` / `reconcile` deleted; auto-mode writers canonicalize through the DB instead of mirroring artifacts to disk.
-- **`gsd headless recover`** — non-TTY DB recovery command for unattended environments where the interactive recover flow can't run.
-- **Doctor surfaces DB locks** — `gsd doctor` reports DB-backed stale locks and flags exhausted `run-uat` retry counters so wedged runs are visible without log archaeology.
+- **Worktree safety is now fail-closed** — write/edit operations enforce the worktree-isolation contract before touching project files. If GSD cannot prove the active worktree is healthy, rooted correctly, and attached to the intended milestone, it stops instead of guessing.
+- **Custom-engine bypasses are explicit** — custom workflow units can opt out of worktree safety checks only through the dedicated path for that runtime. That keeps normal auto-mode writes protected while avoiding false failures for engines that do not use the same worktree lifecycle.
+- **Lifecycle and projection are split into dedicated modules** — worktree entry, exit, root projection, and merge finalization now flow through clearer boundaries. This makes it easier to reason about when state is copied into a milestone worktree, when it is projected back to the project root, and which module owns each step.
+- **Milestone merge closeout is harder to wedge** — stale leases, orphaned preflight stashes, branch-mode drift, reused branches, and wrong-branch merges are detected or recovered more reliably. If GSD finds completed work stranded in a milestone branch or preflight stash, startup and closeout paths now have better recovery hooks.
+- **Projection bypasses were closed** — post-unit and phase flows now route through the Worktree State Projection path instead of ad hoc file movement. That keeps database state, milestone artifacts, and root projections aligned during long-running auto-mode sessions.
 
-### Workspace & Worktree Isolation
+### Memory, Context & Token Control
 
-- **`GsdWorkspace` + `MilestoneScope` handle types** — workspace identity is now an explicit handle threaded through writers, metrics, and the DB connection instead of a module singleton.
-- **Symlink-safe canonicalization** — `deriveState` read root and cache key are canonicalized; path normalization unified on `realpathSync.native`; `gsdRootCache` keys normalized and decoupled from per-turn cache clears; `git-root` anchor guarded against `~/.gsd` resolution.
-- **Worktree-scoped DB + metrics** — `gsd-db` connections and metrics ledgers are scoped by workspace identity, so concurrent milestones in separate worktrees can't cross-contaminate state.
-- **Worktree cwd anchoring** — subagent dispatch anchors to the canonical worktree path, `mergeAndExit` anchors cwd at project root (closes [#5079](https://github.com/gsd-build/GSD-2/issues/5079)), MCP cwd is hardened against drift, and dispatch stops on cwd anchor failures.
-- **Slice isolation through resolver (#5246)** — slice merge isolation routed through the worktree resolver; `originalBase` checks use `isSamePath` instead of string equality; `auto-worktree` validates `milestoneId` match in `ByScope` wrappers.
-- **Worktree CLI commands** — `gsd worktree {list, merge, clean, remove}` exposed in the TUI dispatcher.
+- **Memory relevance improved** — artifacts now carry integrity fingerprints, memories track last-hit time, and relevance scoring uses time decay. Recent, repeatedly useful memories can rank higher, while stale or superseded context is less likely to crowd out the current task.
+- **Artifact integrity is easier to preserve** — content hashes are retained through worktree reconciliation, so GSD can detect whether projected artifacts still match the state it expects. This supports safer recovery and reduces accidental drift between root and worktree state.
+- **Fallback memory search is safer** — when FTS5 is unavailable, LIKE-based fallback scans are capped and surfaced with warnings instead of silently becoming expensive. Memory ranking also guards against invalid decay settings producing unusable scores.
+- **Provider tools are scoped per request** — tool availability is narrowed at request time, with provider-boundary token audit support. The model sees the tools relevant to the current provider and task instead of carrying broad tool definitions through every request.
+- **Prompt and workflow context got leaner** — repeated workflow context is capped, prompt templates use portable paths, and many high-volume workflow prompts were compacted. The goal is less repeated instruction text in long sessions without removing the guardrails that keep planning, execution, and closeout on track.
+- **Token accounting is more accurate** — session tokens are reported separately from context in VS Code, the token encoder warms at startup, and provider-boundary audit hooks make it easier to understand where request size is coming from.
 
-### Deep Planning Mode (Phase 11)
+### TUI & Operator Experience
 
-- **`/gsd new-project --deep`** — opt-in deep mode for new projects, with `research-decision` and `research-project` dispatch units, deep-mode artifact validators, and gated approval flows that pause the milestone instead of aborting on grounding/discovery questions.
-- **EVAL-REVIEW system** — `/gsd eval-review` command, frontmatter schema, pre-ship soft warning when EVAL-REVIEW status is incomplete, and registration in the catalog + ops dispatcher.
-- **Project-shape-aware discuss depth** — discuss-phase questioning depth scales via the project-shape classifier; tiny apps cap research and auto-skip stale research blockers; deep research is opt-in and blocked while a marker is in flight.
-- **Approval-gate hardening** — deep approval gates verified, opening interview question protected from approval abort, plain-text setup approvals gated, deep setup state guarded against phantom transitions.
+- **Compact tool output is more useful** — compact cards show tool targets and low-signal tool output can roll up by phase.
+- **Terminal UI refreshed** — chat/tool cards align with the terminal design, adaptive refresher layouts landed, and the welcome/header lifecycle is more stable.
+- **Auto-mode stays anchored** — bottom anchoring, direct tool execution rollups, and lifecycle hook shutdown behavior were tightened.
 
-### Auto Pipeline & Dispatch
+### Reliability, Tests & CI
 
-- **Delegation-policy verdicts** — dispatch actions are annotated with a per-tool background-safety policy verdict; the policy itself is codified instead of inferred per call.
-- **Reactive-execute default** — auto-dispatch defaults to reactive-execute when ≥3 ready tasks are queued, replacing the always-sequential fallback.
-- **Proactive rate limiting (#2996)** — `min_request_interval_ms` preference paces auto-mode requests; the interval is stamped at dispatch.
-- **Manifest-driven skill surfacing** — `auto-prompts` surfaces manifest skills via recommendations + auto-match; planning-dispatch mode added to the unit manifest for slice plan/complete; runtime tools-policy enforced for planning units (#4934).
-- **Subagent telemetry** — dispatch telemetry, stronger prompt guidelines, and model-override threading (`??` consistently used for `modelOverride`).
+- **Auto-mode recovery tightened** — crash recovery, session handoff, stale milestone completion replay, stale leases, and complete-project restart loops were all hardened.
+- **E2E coverage expanded** — real-process MCP, fake LLM, native ABI, schema migration, Docker runtime, Windows runner, and multi-iteration loop coverage landed.
+- **CI is faster and less noisy** — merge/build gates were simplified, expensive PR jobs are gated, and merge-conflict PRs skip heavy jobs.
 
-### MCP, Models & Cross-Platform
+See the full [Changelog](./CHANGELOG.md) for the complete v2.81 entry and prior releases.
 
-- **Global MCP config** — `mcp-client` reads `~/.gsd/mcp.json` for user-level MCP server config.
-- **`ask_user_questions` over MCP** — host elicitation tried before remote channel; multi-select array shape preserved; explicit cancellation handled; remote answers normalized into `structuredContent`.
-- **Model routing overhaul** — cross-provider tier resolution, provider-agnostic profile-tier defaults, disabled-provider routing denylist, resolved tier model IDs normalized, and `findModelForTier` with behavioral tests.
-- **Ollama** — configurable probe/request timeouts via env vars (clamped); cloud / long-variant context windows reported correctly.
-- **Windows fixes** — home directory resolved correctly (#5015), `Path` env lookup repaired, Windows-safe env CLI shims, DEP0190 avoided in Claude CLI binary probes, tool-bootstrap skipped when tools are on PATH.
-- **Anthropic prompt-cache preserved (#5019)** — `pi-coding-agent` and `gsd` no longer thrash the cache on dispatch.
-
-### Git, GitHub Sync & Reliability
-
-- **Integration-branch self-merge guard (#5024)** — milestone refuses to self-merge when the integration branch equals the milestone branch; self-merge ref guard normalized.
-- **Slice-cadence safety** — integration branch used for slice cadence, dirty worktree state preserved on merge, checked-out slice worktrees advance safely, slice PRs deferred until completion, slice-PR sync stays retryable on failure.
-- **Milestone-ID reservation** — DB rows included in reservation; ghost IDs reused in `nextMilestoneId` to close gaps; `ensurePreconditions` guarded against phantom IDs (#4996); orphan milestone-dir doctor check (#4996); milestone-dir creation deferred until first artifact write.
-- **Auto-commit hygiene** — task commits scoped to reported files, generated commit subjects sanitized, user hooks run on automated commits, milestone-tagged commits bound when `.gsd/` is gitignored (#5033), startup blocked on `git index.lock`.
-- **GitHub sync** — issues no longer closed before delivery, failed task closure / slice PR sync stay retryable, config cache scoped by project, safe git environment used.
+<details>
+<summary>v2.80 highlights</summary>
 
-### Safety, Recovery & Hardening
+- **DB-authoritative context** — UOK contracts moved through database-backed runtime state, auto-run context mode was wired end-to-end, and planned slices recover after artifact writes.
+- **Auto, deep mode, and gates** — deep queued milestones continue, deep project milestones register cleanly, depth-verification regressions were closed, and task commits respect the milestone completion guard.
+- **MCP, post-exec, and cross-platform hardening** — post-exec import fallback handling, React Router `+types` imports, `gsd_exec` write gating, project-save behavior, and home-directory fallback behavior were tightened.
+- **Reliability and review hardening** — auto orchestration contracts, cancellation context preservation, recovery stop lifecycle events, trace correlation, cleanup-on-throw, and phase-result guards were improved.
 
-- **Policy-block pause through dispatch errors** — pause state is preserved when dispatch errors out mid-policy-block.
-- **Skip-validation persistence** — skip-validation state persists and gate rows are cleared on recover.
-- **Cancelled-gate hard block** — redirected to `ask_user_questions`; false plain-text claim dropped from the message.
-- **Write-gate basePath required** — `process.cwd()` defaults removed; basePath threaded through pre-existing tests.
-- **Atomic metrics writes** — parallel-mode `metrics.json` writes merge atomically; ledger cache invalidated after prune; `saveLedger` aborts when lock not acquired; stale-lock detection adds PID stamp + async yield.
-- **Auto-worktree teardown** — `activeWorkspace` guaranteed cleared on teardown failure; teardown try/finally broadened to cover `chdir`; cleanup steps mirrored on the abort path; warning emitted on resume when persisted worktree is missing.
-- **Empty-turn nudge** — no longer auto-replies to user questions; deferred on mid-line approval prompts.
-- **Refuses project writes from `$HOME`** — and surfaces real SQL errors from `capture_thought` instead of swallowing them.
+</details>
 
-### VS Code & TUI
+<details>
+<summary>v2.79 highlights</summary>
 
-- **Checkpoint tree view** — registered in the VS Code extension; checkpoint file existence restored; RPC file-mutation events tracked; agent diff scoped to tracked files.
-- **TUI image paste** — pasted images preserved on regular submit.
-- **Bundled `/gsd` slash command protected** — core handler refuses to overwrite the bundled command.
+- **DB-backed runtime coordination** — workers, leases, dispatches, command queue, locks, paused-session state, and stuck-state recovery moved into `gsd.db`
+- **Workspace/worktree isolation** — `GsdWorkspace` and `MilestoneScope` handles, symlink-safe canonicalization, worktree-scoped DB/metrics, cwd anchoring, and `gsd worktree {list, merge, clean, remove}`
+- **Deep planning mode** — `/gsd new-project --deep`, research dispatch units, EVAL-REVIEW, project-shape-aware questioning, and approval-gate hardening
+- **Auto pipeline upgrades** — delegation-policy verdicts, reactive-execute default, proactive rate limiting, manifest-driven skill surfacing, and subagent telemetry
+- **MCP/model/cross-platform fixes** — global MCP config, `ask_user_questions` over MCP, provider-agnostic model routing, Ollama timeouts, Windows fixes, and Anthropic prompt-cache preservation
+- **Git and recovery reliability** — self-merge guards, safer slice cadence, milestone-ID reservation, auto-commit hygiene, retryable GitHub sync, atomic metrics writes, and stronger teardown handling
+- **VS Code and TUI polish** — checkpoint tree view, image paste preservation, and bundled `/gsd` slash command protection
 
-See the full [Changelog](./CHANGELOG.md) for the complete v2.79 entry and prior releases.
+</details>
 
 <details>
 <summary>v2.78 highlights</summary>
@@ -259,6 +245,7 @@ Full documentation is in the [`docs/`](./docs/) directory:
 
 - **[Architecture](./docs/dev/architecture.md)** — system design and dispatch pipeline
 - **[CI/CD Pipeline](./docs/dev/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod)
+- **[E2E Testing](./tests/e2e/README.md)** — real-process CLI/runtime coverage and CI runner expectations
 - **[Pipeline Simplification (ADR-003)](./docs/dev/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion
 - **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
 
@@ -361,7 +348,7 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 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. **Context Mode** — Context Mode is enabled by default and gives every auto-mode unit guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; full stdout/stderr is saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads `.gsd/last-snapshot.md` after compaction or resume. Opt out with `context_mode.enabled: false`; tune sandbox timeout/output caps with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, and `context_mode.exec_digest_chars`.
+3. **Context Mode** — Context Mode is enabled by default and gives eligible auto-mode units guidance for preserving context. Agents are steered toward `gsd_exec` for noisy scans, builds, tests, and diagnostics; capped stdout/stderr and metadata are saved under `.gsd/exec/` while only a short digest enters the conversation. `gsd_exec_search` lets agents reuse prior runs instead of repeating expensive checks, and `gsd_resume` reads a prior compaction snapshot from `.gsd/last-snapshot.md` when one exists. Opt out with `context_mode.enabled: false` to disable Context Mode guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume`; tune sandbox timeout/output caps and environment forwarding with `context_mode.exec_timeout_ms`, `context_mode.exec_stdout_cap_bytes`, `context_mode.exec_digest_chars`, and `context_mode.exec_env_allowlist`.
 
 4. **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.
 
@@ -371,7 +358,7 @@ The database is authoritative for milestones, slices, tasks, requirements, decis
 
 7. **Stuck and artifact detection** — A sliding-window detector identifies repeated dispatch patterns (including multi-unit cycles). Missing expected artifacts use a separate bounded path: GSD retries artifact verification up to 3 times with failure context, then pauses auto mode with the missing artifact error instead of looping indefinitely.
 
-8. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout pauses auto mode. Recovery steering nudges the LLM to finish durable output before giving up.
+8. **Timeout supervision** — Soft timeout warns the LLM to wrap up. Idle watchdog detects stalls. Hard timeout starts recovery and only pauses auto mode if durable progress cannot be made. Runtime progress is recorded under `.gsd/runtime/`, and journal events close out unit, finalize, and iteration phases for later forensics.
 
 9. **Cost tracking** — Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending.
 
@@ -659,10 +646,11 @@ auto_report: true
 | `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. `worktree` requires a committed `HEAD`; zero-commit repos temporarily run as `none`    |
 | `git.manage_gitignore`            | Set `false` to prevent GSD from modifying `.gitignore`                                                |
-| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable `gsd_exec`, exec history guidance, and resume snapshots |
+| `context_mode.enabled`            | Context Mode is default-on; set `false` to disable prompt guidance, snapshot injection, `gsd_exec`, `gsd_exec_search`, and `gsd_resume` |
 | `context_mode.exec_timeout_ms`    | Timeout for sandboxed `gsd_exec` runs (default: 30000)                                                |
 | `context_mode.exec_stdout_cap_bytes` | Persisted stdout cap for `gsd_exec` output (default: 1048576)                                      |
 | `context_mode.exec_digest_chars`  | Trailing stdout characters returned to the agent context (default: 300)                              |
+| `context_mode.exec_env_allowlist` | Environment variables forwarded to sandboxed `gsd_exec` runs in addition to `PATH` and `HOME`        |
 | `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)                                                   |
 | `verification_max_retries`        | Max retries for verification failures (default: 2)                                                    |
@@ -762,7 +750,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/metrics.json
 # Raw JSONL session dumps — crash recovery forensics, auto-pruned
 .gsd/activity/
-# Unit execution records — dispatch phase, timeouts, and recovery tracking
+# Unit execution records — dispatch phase, timeout recovery progress, and finalize tracking
 .gsd/runtime/
 # Git worktree working copies
 .gsd/worktrees/
@@ -770,7 +758,7 @@ The best practice for working in teams is to ensure unique milestone names acros
 .gsd/parallel/
 # SQLite database and WAL sidecars — authoritative runtime state, local only
 .gsd/gsd.db*
-# Daily-rotated event journal — structured event log for forensics
+# Daily-rotated event journal — structured unit/finalize/iteration event log for forensics
 .gsd/journal/
 # Doctor run history — diagnostic check results
 .gsd/doctor-history.jsonl

package/dist/claude-cli-check.d.ts

@@ -1,3 +1,16 @@
+/**
+ * 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.
+ */
+export declare function buildClaudeSpawnInvocation(command: string, args: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
 /**
  * Platform-correct binary name for the Claude Code CLI.
  *
@@ -7,7 +20,24 @@
  * authenticated. Mirrors the `NPM_COMMAND` pattern in
  * `src/resources/extensions/gsd/pre-execution-checks.ts`.
  */
+export declare function getClaudeCommand(platform?: NodeJS.Platform): string;
 export declare const CLAUDE_COMMAND: string;
+/**
+ * Ordered list of binary names to probe for the Claude Code CLI.
+ *
+ * Windows installs vary: npm-global installs produce a `claude.cmd` shim,
+ * direct binary installs produce `claude.exe`, and Git Bash wrappers may
+ * expose a bare `claude` shim. Try all three so no valid install is missed.
+ */
+export declare function getClaudeCommandCandidates(platform?: NodeJS.Platform): string[];
+/**
+ * Decide auth state from `claude auth status` output.
+ *
+ * Newer Claude CLI builds emit JSON with a `loggedIn` boolean. Older builds
+ * emit free-form text. Prefer the structured signal; fall back to a text
+ * heuristic. The text heuristic only covers English phrasing.
+ */
+export declare function parseAuthStatus(output: string): boolean | null;
 /**
  * Check if the `claude` binary is installed (regardless of auth state).
  */

package/dist/claude-cli-check.js

@@ -14,11 +14,15 @@ import { execFileSync } from 'node:child_process';
  * 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);
+export function buildClaudeSpawnInvocation(command, args, platform = process.platform) {
+    if (platform === 'win32') {
+        return { command: 'cmd', args: ['/c', command, ...args] };
     }
-    return execFileSync(command, args, opts);
+    return { command, args };
+}
+function spawnClaude(command, args, opts) {
+    const invocation = buildClaudeSpawnInvocation(command, args);
+    return execFileSync(invocation.command, invocation.args, opts);
 }
 /**
  * Platform-correct binary name for the Claude Code CLI.
@@ -29,7 +33,10 @@ function spawnClaude(command, args, opts) {
  * authenticated. Mirrors the `NPM_COMMAND` pattern in
  * `src/resources/extensions/gsd/pre-execution-checks.ts`.
  */
-export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'claude';
+export function getClaudeCommand(platform = process.platform) {
+    return platform === 'win32' ? 'claude.cmd' : 'claude';
+}
+export const CLAUDE_COMMAND = getClaudeCommand();
 /**
  * Ordered list of binary names to probe for the Claude Code CLI.
  *
@@ -37,7 +44,11 @@ export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'cla
  * direct binary installs produce `claude.exe`, and Git Bash wrappers may
  * expose a bare `claude` shim. Try all three so no valid install is missed.
  */
-const CLAUDE_COMMAND_CANDIDATES = process.platform === 'win32' ? [CLAUDE_COMMAND, 'claude.exe', 'claude'] : [CLAUDE_COMMAND];
+export function getClaudeCommandCandidates(platform = process.platform) {
+    const command = getClaudeCommand(platform);
+    return platform === 'win32' ? [command, 'claude.exe', 'claude'] : [command];
+}
+const CLAUDE_COMMAND_CANDIDATES = getClaudeCommandCandidates();
 const VERSION_TIMEOUT_MS = 5_000;
 // Auth probe needs more headroom on Windows because the spawn goes through
 // cmd.exe → claude.cmd → node → Claude CLI.
@@ -80,7 +91,7 @@ function findWorkingCommand() {
  * emit free-form text. Prefer the structured signal; fall back to a text
  * heuristic. The text heuristic only covers English phrasing.
  */
-function parseAuthStatus(output) {
+export function parseAuthStatus(output) {
     const trimmed = output.trim();
     if (!trimmed)
         return null;

package/dist/cli.js

@@ -760,25 +760,6 @@ if (!process.stdin.isTTY || !process.stdout.isTTY) {
             : 'stdout is';
     printNonTtyErrorAndExit(missing, true);
 }
-// Welcome screen — shown on every fresh interactive session before TUI takes over.
-// Skip when the first-run banner was already printed in loader.ts (prevents double banner).
-if (!process.env.GSD_FIRST_RUN_BANNER) {
-    const { printWelcomeScreen } = await import('./welcome-screen.js');
-    let remoteChannel;
-    try {
-        const { resolveRemoteConfig } = await import('./resources/extensions/remote-questions/config.js');
-        const rc = resolveRemoteConfig();
-        if (rc)
-            remoteChannel = rc.channel;
-    }
-    catch { /* non-fatal */ }
-    printWelcomeScreen({
-        version: process.env.GSD_VERSION || '0.0.0',
-        modelName: settingsManager.getDefaultModel() || undefined,
-        provider: settingsManager.getDefaultProvider() || undefined,
-        remoteChannel,
-    });
-}
 const interactiveMode = new InteractiveMode(session);
 markStartup('InteractiveMode');
 printStartupTimings();

package/dist/headless-query.d.ts

@@ -36,6 +36,13 @@ export declare function shouldUseAgentExtensionsDir(opts: {
     agentDir: string;
     useAgentDir: boolean;
 };
+declare function loadExtensionModules(): Promise<{
+    openProjectDbIfPresent: (basePath: string) => Promise<void>;
+    deriveState: (basePath: string) => Promise<GSDState>;
+    resolveDispatch: (opts: any) => Promise<any>;
+    readAllSessionStatuses: (basePath: string) => any[];
+    loadEffectiveGSDPreferences: () => any;
+}>;
 export interface QuerySnapshot {
     state: GSDState;
     next: {
@@ -59,4 +66,7 @@ export interface QueryResult {
     exitCode: number;
     data?: QuerySnapshot;
 }
+type HeadlessQueryModules = Awaited<ReturnType<typeof loadExtensionModules>>;
+export declare function runHeadlessQuery(basePath: string, modules: HeadlessQueryModules, writeOutput?: (text: string) => void): Promise<QueryResult>;
 export declare function handleQuery(basePath: string): Promise<QueryResult>;
+export {};

package/dist/headless-query.js

@@ -77,9 +77,8 @@ async function loadExtensionModules() {
         loadEffectiveGSDPreferences: prefsModule.loadEffectiveGSDPreferences,
     };
 }
-// ─── Implementation ─────────────────────────────────────────────────────────
-export async function handleQuery(basePath) {
-    const { openProjectDbIfPresent, deriveState, resolveDispatch, readAllSessionStatuses, loadEffectiveGSDPreferences, } = await loadExtensionModules();
+export async function runHeadlessQuery(basePath, modules, writeOutput = (text) => process.stdout.write(text)) {
+    const { openProjectDbIfPresent, deriveState, resolveDispatch, readAllSessionStatuses, loadEffectiveGSDPreferences, } = modules;
     await openProjectDbIfPresent(basePath);
     const state = await deriveState(basePath);
     // Derive next dispatch action
@@ -120,6 +119,9 @@ export async function handleQuery(basePath) {
         next,
         cost: { workers, total: workers.reduce((sum, w) => sum + w.cost, 0) },
     };
-    process.stdout.write(JSON.stringify(snapshot) + '\n');
+    writeOutput(JSON.stringify(snapshot) + '\n');
     return { exitCode: 0, data: snapshot };
 }
+export async function handleQuery(basePath) {
+    return runHeadlessQuery(basePath, await loadExtensionModules());
+}

package/dist/loader-entrypoint.d.ts

@@ -0,0 +1,8 @@
+export interface LoaderEntrypointOptions {
+    gsdRoot: string;
+    invokedBinPath: string | undefined;
+    env?: NodeJS.ProcessEnv;
+    existsSync?: (path: string) => boolean;
+}
+export declare function resolveLoaderCliEntrypoint({ gsdRoot, invokedBinPath, env, existsSync, }: LoaderEntrypointOptions): string | undefined;
+export declare function applyLoaderCliEntrypointEnv(env: NodeJS.ProcessEnv, options: LoaderEntrypointOptions): string | undefined;

package/dist/loader-entrypoint.js

@@ -0,0 +1,27 @@
+// GSD-2 - Loader child-process entrypoint resolution helpers.
+import { existsSync as defaultExistsSync } from "node:fs";
+import { join, resolve } from "node:path";
+export function resolveLoaderCliEntrypoint({ gsdRoot, invokedBinPath, env = process.env, existsSync = defaultExistsSync, }) {
+    const sourceLoaderPath = join(gsdRoot, "src", "loader.ts");
+    const devCliPath = env.GSD_DEV_CLI_PATH?.trim() || join(gsdRoot, "scripts", "dev-cli.js");
+    const explicitCliPath = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
+    const isSourceLoader = Boolean(invokedBinPath && resolve(invokedBinPath) === sourceLoaderPath);
+    const rawGsdBinPath = explicitCliPath || (isSourceLoader && existsSync(devCliPath) ? devCliPath : invokedBinPath);
+    return rawGsdBinPath ? resolve(rawGsdBinPath) : undefined;
+}
+export function applyLoaderCliEntrypointEnv(env, options) {
+    const resolvedGsdBinPath = resolveLoaderCliEntrypoint({ ...options, env });
+    if (resolvedGsdBinPath) {
+        env.GSD_BIN_PATH = resolvedGsdBinPath;
+        if (!env.GSD_CLI_PATH) {
+            env.GSD_CLI_PATH = resolvedGsdBinPath;
+        }
+    }
+    else {
+        delete env.GSD_BIN_PATH;
+        if (!env.GSD_CLI_PATH) {
+            delete env.GSD_CLI_PATH;
+        }
+    }
+    return resolvedGsdBinPath;
+}

package/dist/loader.js

@@ -63,6 +63,7 @@ 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 { applyLoaderCliEntrypointEnv } from './loader-entrypoint.js';
 import { renderLogo } from './logo.js';
 // pkg/ is a shim directory: contains gsd's piConfig (package.json) and pi's
 // theme assets (dist/modes/interactive/theme/) without a src/ directory.
@@ -117,17 +118,7 @@ process.env.GSD_VERSION = gsdVersion;
 // 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;
-}
+applyLoaderCliEntrypointEnv(process.env, { gsdRoot, invokedBinPath: process.argv[1] });
 // 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.

package/dist/mcp-server.d.ts

@@ -22,6 +22,7 @@ export interface McpToolDef {
         isError?: boolean;
     }>;
 }
+export declare function mcpSdkSpecifier(subpath: 'server/index' | 'server/stdio' | 'types'): string;
 /**
  * Starts a native MCP (Model Context Protocol) server over stdin/stdout.
  *

package/dist/mcp-server.js

@@ -29,6 +29,9 @@ function isPlainObject(value) {
 // built via a template string so TypeScript's NodeNext resolver treats them as
 // `any` and skips static checking.
 const MCP_PKG = '@modelcontextprotocol/sdk';
+export function mcpSdkSpecifier(subpath) {
+    return `${MCP_PKG}/${subpath}.js`;
+}
 /**
  * Starts a native MCP (Model Context Protocol) server over stdin/stdout.
  *
@@ -45,9 +48,9 @@ const MCP_PKG = '@modelcontextprotocol/sdk';
  */
 export async function startMcpServer(options) {
     const { tools, version = '0.0.0' } = options;
-    const serverMod = await import(`${MCP_PKG}/server/index.js`);
-    const stdioMod = await import(`${MCP_PKG}/server/stdio.js`);
-    const typesMod = await import(`${MCP_PKG}/types.js`);
+    const serverMod = await import(mcpSdkSpecifier('server/index'));
+    const stdioMod = await import(mcpSdkSpecifier('server/stdio'));
+    const typesMod = await import(mcpSdkSpecifier('types'));
     const Server = serverMod.Server;
     const StdioServerTransport = stdioMod.StdioServerTransport;
     const { ListToolsRequestSchema, CallToolRequestSchema } = typesMod;

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

@@ -1 +1 @@
-63159c1114dd0d48
+f38fa6411e8b7897

package/dist/resources/GSD-WORKFLOW.md

@@ -28,7 +28,7 @@ Then do the thing `STATE.md` says to do next.
 ## The Hierarchy
 
 ```
-Milestone  →  a shippable version (4-10 slices)
+Milestone  →  a shippable version (1-10 slices, sized to the work)
   Slice    →  one demoable vertical capability (1-7 tasks)
     Task   →  one context-window-sized unit of work (fits in one session)
 ```
@@ -331,7 +331,7 @@ The **Don't Hand-Roll** and **Common Pitfalls** sections prevent the most expens
 
 **For a milestone (roadmap):**
 1. Read `M###-CONTEXT.md`, `M###-RESEARCH.md`, and `.gsd/DECISIONS.md` if they exist.
-2. Decompose the vision into 4-10 demoable vertical slices.
+2. Decompose the vision into 1-10 demoable vertical slices. Prefer one slice for tiny, single-file, or static work unless the request clearly spans independent capabilities.
 3. Order by risk (high-risk first to validate feasibility early).
 4. Write `M###-ROADMAP.md` with checkboxes, risk levels, dependencies, demo sentences.
 5. **Write the boundary map** — for each slice, specify what it produces (functions, types, interfaces, endpoints) and what it consumes from upstream slices. This forces interface thinking before implementation and enables deterministic verification that slices actually connect.

package/dist/resources/extensions/claude-code-cli/readiness.js

@@ -23,11 +23,15 @@ import { execFileSync } from "node:child_process";
  * 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);
+export function buildClaudeSpawnInvocation(command, args, platform = process.platform) {
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/c", command, ...args] };
     }
-    return execFileSync(command, args, opts);
+    return { command, args };
+}
+function spawnClaude(command, args, opts) {
+    const invocation = buildClaudeSpawnInvocation(command, args);
+    return execFileSync(invocation.command, invocation.args, opts);
 }
 /**
  * Candidate executable names for the Claude Code CLI.
@@ -35,14 +39,21 @@ function spawnClaude(command, args, opts) {
  * Keep the explicit win32 ternary selector for regression coverage (Issue #4424):
  * Node's execFileSync must target `claude.cmd` directly on Windows.
  */
-const CLAUDE_COMMAND = process.platform === "win32" ? "claude.cmd" : "claude";
+export function getClaudeCommand(platform = process.platform) {
+    return platform === "win32" ? "claude.cmd" : "claude";
+}
+const CLAUDE_COMMAND = getClaudeCommand();
 /**
  * Windows installs vary: some environments expose `claude.cmd` (npm shim),
  * `claude.exe` (direct binary install), or a bare `claude` shim on PATH
  * (for example Git Bash wrappers). Try all three to avoid false "not
  * installed" results in readiness checks.
  */
-const CLAUDE_COMMAND_CANDIDATES = process.platform === "win32" ? [CLAUDE_COMMAND, "claude.exe", "claude"] : [CLAUDE_COMMAND];
+export function getClaudeCommandCandidates(platform = process.platform) {
+    const command = getClaudeCommand(platform);
+    return platform === "win32" ? [command, "claude.exe", "claude"] : [command];
+}
+const CLAUDE_COMMAND_CANDIDATES = getClaudeCommandCandidates();
 // Keep the version probe snappy — `claude --version` is a quick path.
 const VERSION_TIMEOUT_MS = 5_000;
 // Auth status can be much slower on Windows because the spawn goes through
@@ -90,7 +101,7 @@ function findWorkingCommand() {
  * back to a text heuristic. Note: the text heuristic only covers English
  * phrasing — the JSON path is the durable signal.
  */
-function parseAuthStatus(output) {
+export function parseAuthStatus(output) {
     const trimmed = output.trim();
     if (!trimmed)
         return null;