gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

package/README.md

@@ -27,34 +27,70 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.77
+## What's New in v2.78
 
-### Context Mode & Execution
+### Worktree Lifecycle & Forensics
 
-- **Context Mode** — a dispatch behavior that builds task-ready context automatically: it pulls in the most relevant project artifacts, prior session state, milestone/slice signals, and execution metadata before the model runs. This reduces manual prompt assembly, improves continuity across turns, and helps tasks start with the right files and constraints from the first dispatch. Enabled by default for new projects (opt out with `enabled: false`).
-- **Sandboxed execution tools** — added `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output execution paths for context-mode flows, so search/resume and follow-up execution can run with tighter boundaries and more predictable runtime behavior.
-- **Preflight hardening** — milestone completion now performs stricter clean-root preflight checks and can auto-stash when needed, reducing accidental dirty-tree transitions and helping completion flows fail fast with clearer remediation.
+- **Slice-cadence worktree collapse (#4765)** — new `git.collapse_cadence: "milestone" | "slice"` preference. With `slice`, each validated slice squash-merges to main immediately, shrinking the orphan window from milestone-size to slice-size. Pair with `git.milestone_resquash: true` to collapse per-slice commits into one milestone commit at completion.
+- **Worktree telemetry (#4764)** — new journal events (`worktree-created`, `worktree-merged`, `worktree-orphaned`, `auto-exit`, `canonical-root-redirect`, `slice-merged`, `milestone-resquash`) and a `summarizeWorktreeTelemetry` aggregator that reports orphan breakdowns, merge durations, conflict counts, exit reasons, and unmerged-exit metrics.
+- **`/gsd forensics` worktree section** — surfaces the telemetry above with two new anomalies: `worktree-orphan` and `worktree-unmerged-exit`.
+- **Worktree-aware canonical milestone root (#4761)** — `resolveCanonicalMilestoneRoot` routes validators and cross-session readers through the live worktree, so milestone validation no longer silently reads stale project-root state.
+- **Bootstrap orphan audit (#4762)** — in-progress milestones with commits ahead of main no longer get skipped; the audit emits a warning with commit count and worktree location so interrupted auto-runs are visible.
 
-### Memory Architecture (ADR-013)
+### Auto Pipeline & Component System
 
-- **Memories table is now authoritative** — all memory reads and writes now flow through the `memories` table as the single source of truth. By removing split legacy paths, memory state stays consistent across agents, tools, and UI surfaces, with fewer reconciliation edge cases and less sync drift.
-- **Structured memory fields** — `structured_fields` adds typed metadata (instead of only free-form text), so memories can carry machine-usable attributes for more accurate retrieval, stronger filtering, and more dependable downstream automation and tooling.
-- **Dual-write migration completed** — the staged migration that wrote to both old and new paths is now fully landed, including decisions backfill and parity wiring across agents, MCP tools, and extract-learnings flows. That gives a safer upgrade path while preserving historical data and reducing cutover risk.
+- **Unified component system** — skills, agents, pipelines, and marketplace are now one component model wired through runtime, dispatch, and telemetry, replacing per-surface plumbing.
+- **UnitContextManifest v2 (#4924, #4934)** — auto dispatch runs through a typed manifest with declarative tools-policy and typed computed artifacts. CI guards the schema so drift fails fast.
+- **Composer migration phase 3 (#4782)** — `complete-slice`, `research-milestone`, `run-uat`, and `reassess-roadmap` now build context through the manifest composer for a consistent shape across units.
+- **Milestone scope classifier + pipeline variants (#4781)** — auto picks a pipeline variant from milestone shape, so research-heavy and execution-heavy milestones no longer share a one-size dispatch path.
+- **Per-unit-type skill manifest resolver (#4779)** — skills wire into specific unit types instead of being globally on, with manifests expanded across the remaining types.
+- **Single-writer-v3 control plane** — closes outstanding gaps in the durable-state writer model so concurrent writers can't desync workflow state.
+- **Opt-in `reassess-roadmap` (#4778)** — gated behind the `skip_clean_reassess` preference per ADR-003 §4; auto no longer triggers reassessment unprompted.
 
-### Skills, Tooling, and UX
+### Extensions Framework
 
-- **Skill coverage expanded** — 9 gap-closing skills landed and 6 planning/design skills were surfaced, improving end-to-end workflow coverage and making specialized guidance easier to discover at the point of use.
-- **Hook stack upgrades** — Layer 0 shell hooks and additional Layer 2 events were added to widen extension integration points: hooks can act earlier in command execution, and lifecycle consumers now receive richer event signals for orchestration, policy checks, and observability.
-- **TUI polish** — skill invocations now render in a dedicated chat-frame style for clearer scanability, and active-row overflow handling was fixed to prevent terminal layout breakage during long outputs.
+- **Extension lifecycle commands** — `gsd extensions install / update / uninstall / list / info / validate` for npm, git, and local sources, with dependency warnings and user-metadata tracking.
+- **Topological extension load order** — Kahn's-algorithm sort with surfaced `ExtensionLoadWarning`s, so dependent extensions resolve deterministically and misconfigurations are visible instead of silent.
+- **cmux ↔ gsd decoupling** — static cross-imports replaced with a shared `cmux-events` contract and dynamic imports, isolating extension boundaries.
+- **Extracted `@gsd-extensions/google-search` workspace** — first reference extension carved out of core; legacy in-tree source replaced with a deprecation stub.
+
+### Models, Agent, and UX
+
+- **GPT-5.5 Codex support** — added across `gsd` and `pi-ai`, including `xhigh` thinking level for custom GPT-5.5 models.
+- **Auth mode in `/model`** — providers display alongside auth mode for clearer routing.
+- **Permission granularity picker** — Claude Code "Always Allow" prompts let you scope the grant instead of approving the broad case.
+- **Headless auto default → `bypassPermissions` (#4657)** — Claude Code CLI headless auto-mode runs without permission prompts by default.
+- **`skillFilter` for system prompts** — `pi-coding-agent` filters which skills are surfaced in `buildSystemPrompt`, with consumer exceptions guarded.
+- **Visual postinstall (#4641)** — install shows a spinner/banner UX so first-run state is legible.
+- **PR-risk verification** — risk prompt emits a copy-pasteable code block to make follow-up commands one step.
 
 ### Reliability & Safety
 
-- **Worktree and dispatch resilience** — crash-recovery dispatch is more robust, path derivation is safer, and worktree context fallback is improved, reducing stuck states and misrouted artifact operations after interruptions.
-- **DB/schema guardrails** — migration/index ordering and schema version stamping were tightened so upgrades apply deterministically and avoid index/version drift across mixed or legacy states.
-- **Security and validation fixes** — multiple hardening fixes landed across redaction paths, file/path checks, and pre-execution validation, closing false-positive/false-negative gaps while improving safety boundaries.
+- **Major git-safety pass** — clarified TOCTOU ancestry guard, atomic sync-lock acquire with PID-verified stale override, `.git/index.lock` force-removal gated by 5-min age, `GIT_DIR`/`GIT_WORK_TREE`/`GIT_INDEX_FILE` stripped from env overlays, rebase/cherry-pick/revert state detected and aborted in recovery, working tree stashed before `reset --hard` in self-heal/rollback, worktree create guarded against unborn branches, and user hooks + `commit.gpgsign` honored on auto-commits.
+- **Atomic `.gsd/` state writes** — file-locks now actually lock and throw on contention; appends are lock-wrapped to prevent interleaved writes.
+- **Compaction correctness (#4665)** — fixed chunker/truncation mismatch and silent chunk-drops that produced degenerate or empty summaries.
+- **Write-gate (#4950)** — fail-closed depth confirmation, EXDEV-safe snapshot rename, opt-out persistence default, off-by-one max-attempts fix, exception capture in `gate.execute`, and audit/DB rows for unknown gate ids.
+- **Auto state machine** — deterministic policy errors classified non-retriable (#4973), depth-verification bypass for non-interactive sessions, baseline restored between units (#4961), `restoreToolBaseline` gated by `isAutoMode` (#4966).
+- **Slice + crash recovery** — slice orchestrator state persists across crashes; ancestry-guarded force-reset, detached-HEAD refusal, and stash-by-ref recovery.
+- **Empty-turn recovery** — Claude Code CLI tool-block shape canonicalized so empty-turn recovery matches real provider output.
 
 See the full [Changelog](./CHANGELOG.md) for details on every release.
 
+<details>
+<summary>v2.77 highlights</summary>
+
+- **Context Mode** — dispatch builds task-ready context automatically (artifacts, prior session, milestone/slice signals, execution metadata); enabled by default for new projects
+- **Sandboxed execution tools** — `gsd_exec_search`, `gsd_resume`, and sandboxed tool-output paths for context-mode flows
+- **Memory architecture (ADR-013)** — `memories` table is now authoritative; `structured_fields` adds typed metadata; dual-write migration landed with decisions backfill
+- **Skill coverage** — 9 gap-closing skills landed plus 6 planning/design skills surfaced
+- **Hook stack** — Layer 0 shell hooks and additional Layer 2 lifecycle events
+- **TUI polish** — dedicated chat-frame style for skill invocations; active-row overflow fixes
+- **Worktree + dispatch resilience** — crash-recovery dispatch hardened, safer path derivation, improved worktree context fallback
+- **DB/schema guardrails** — migration/index ordering and schema version stamping tightened
+- **Preflight hardening** — milestone completion enforces stricter clean-root checks with auto-stash
+
+</details>
+
 <details>
 <summary>v2.75 highlights</summary>
 
@@ -274,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:**
 
@@ -282,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).
 
@@ -414,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                                    |
@@ -435,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                                                  |
@@ -461,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                                 |
@@ -561,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                                                           |
@@ -569,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)                                                   |
@@ -589,19 +634,19 @@ Start GSD with `gsd --debug` to enable structured JSONL diagnostic logging. Debu
 
 ### Token Optimization
 
-GSD includes a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model selection, phase skipping, and context compression:
+GSD includes a coordinated token optimization system that reduces usage by 40-60% on cost-sensitive workloads. Set a single preference to coordinate model tier selection, phase skipping, and context compression:
 
 ```yaml
 token_profile: budget # or balanced (default), quality
 ```
 
-| Profile    | Savings | What It Does                                                   |
-| ---------- | ------- | -------------------------------------------------------------- |
-| `budget`   | 40-60%  | Cheap models, skip research/reassess, minimal context inlining |
-| `balanced` | 10-20%  | Default models, skip slice research, standard context          |
-| `quality`  | 0%      | All phases, all context, full model power                      |
+| Profile    | Savings | What It Does                                                                     |
+| ---------- | ------- | -------------------------------------------------------------------------------- |
+| `budget`   | 40-60%  | Light/standard tier defaults, skip research/reassess, minimal context inlining   |
+| `balanced` | 10-20%  | Standard tier for core work, light tier for simple work, standard context        |
+| `quality`  | 0%      | Heavy tier for planning, standard tier for core work, full context               |
 
-**Complexity-based routing** automatically classifies tasks as simple/standard/complex and routes to appropriate models. Simple docs tasks get Haiku; complex architectural work gets Opus. The classification is heuristic (sub-millisecond, no LLM calls) and learns from outcomes via a persistent routing history.
+**Complexity-based routing** automatically classifies tasks as simple/standard/complex and routes to appropriate available models. Token profiles define provider-agnostic tier intentions, so simple docs tasks use a light-tier configured model and complex architectural work can use a heavy-tier configured model. The classification is heuristic (sub-millisecond, no LLM calls) and learns from outcomes via a persistent routing history.
 
 **Budget pressure** graduates model downgrading as you approach your budget ceiling — 50%, 75%, and 90% thresholds progressively shift work to cheaper tiers.
 
@@ -666,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
@@ -678,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/
@@ -743,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

@@ -1,7 +1,25 @@
 // GSD2 — Claude CLI binary detection for onboarding
 // Lightweight check used at onboarding time (before extensions load).
 // The full readiness check with caching lives in the claude-code-cli extension.
+//
+// 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.
  *
@@ -20,60 +38,113 @@ export const CLAUDE_COMMAND = process.platform === 'win32' ? 'claude.cmd' : 'cla
  * 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];
+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.
+const AUTH_TIMEOUT_MS = 15_000;
+function debugLog(...parts) {
+    if (process.env.GSD_CLAUDE_DEBUG) {
+        process.stderr.write(`[claude-cli-check] ${parts.map(p => (typeof p === 'string' ? p : JSON.stringify(p))).join(' ')}\n`);
+    }
+}
 /**
- * Try to run `args` against each candidate binary.
- * Returns the output buffer on first success, throws the last error if all fail.
+ * Find the first candidate that responds to `--version`. Returns the
+ * candidate name on success, null if none worked.
+ *
+ * On Windows with `shell: true`, a missing candidate surfaces as a
+ * non-zero exit from cmd.exe rather than ENOENT — so we cannot rely on
+ * the error code to decide "try next". Treat any failure as "try next"
+ * for the version probe.
  */
-function execClaudeCheck(args) {
-    let lastError;
+function findWorkingCommand() {
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            return execFileSync(command, args, {
-                timeout: 5_000,
+            spawnClaude(command, ['--version'], {
+                timeout: VERSION_TIMEOUT_MS,
                 stdio: 'pipe',
-                shell: process.platform === 'win32',
             });
+            debugLog('version probe ok via', command);
+            return command;
         }
         catch (error) {
-            lastError = error;
-            const code = error?.code;
-            // EINVAL can surface on Windows Git Bash for .cmd spawn failures.
-            if (code === 'ENOENT' || code === 'EINVAL')
-                continue;
-            throw error;
+            debugLog('version probe failed for', command, 'code=', error?.code);
+            continue;
         }
     }
-    throw lastError ?? new Error(`Claude CLI not found (tried: ${CLAUDE_COMMAND_CANDIDATES.join(', ')})`);
+    return null;
 }
 /**
- * Check if the `claude` binary is installed (regardless of auth state).
+ * 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 function isClaudeBinaryInstalled() {
-    try {
-        execClaudeCheck(['--version']);
-        return true;
+function parseAuthStatus(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.loggedIn === 'boolean') {
+                return parsed.loggedIn;
+            }
+        }
+        catch {
+            // Fall through to text heuristic.
+        }
     }
-    catch {
+    const lower = trimmed.toLowerCase();
+    if (/not logged in|no credentials|unauthenticated|not authenticated/.test(lower)) {
         return false;
     }
+    if (/logged in|authenticated|signed in|email|subscription/.test(lower)) {
+        return true;
+    }
+    return null;
 }
-/**
- * Check if the `claude` CLI is installed AND authenticated.
- */
-export function isClaudeCliReady() {
+function probeAuth(command) {
+    // Try --json first (newer CLIs).
     try {
-        execClaudeCheck(['--version']);
+        const out = spawnClaude(command, ['auth', 'status', '--json'], {
+            timeout: AUTH_TIMEOUT_MS,
+            stdio: 'pipe',
+        }).toString();
+        debugLog('auth status --json output:', out.slice(0, 200));
+        const parsed = parseAuthStatus(out);
+        if (parsed !== null)
+            return parsed;
     }
-    catch {
-        return false;
+    catch (error) {
+        debugLog('auth status --json threw:', error.message?.slice(0, 200));
     }
+    // Fallback: plain `auth status` (older CLIs that don't accept --json).
     try {
-        const output = execClaudeCheck(['auth', 'status'])
-            .toString()
-            .toLowerCase();
-        return !(/not logged in|no credentials|unauthenticated|not authenticated/i.test(output));
+        const out = spawnClaude(command, ['auth', 'status'], {
+            timeout: AUTH_TIMEOUT_MS,
+            stdio: 'pipe',
+        }).toString();
+        debugLog('auth status output:', out.slice(0, 200));
+        return parseAuthStatus(out);
     }
-    catch {
-        return false;
+    catch (error) {
+        debugLog('auth status threw:', error.message?.slice(0, 200));
+        return null;
     }
 }
+/**
+ * Check if the `claude` binary is installed (regardless of auth state).
+ */
+export function isClaudeBinaryInstalled() {
+    return findWorkingCommand() !== null;
+}
+/**
+ * Check if the `claude` CLI is installed AND authenticated.
+ */
+export function isClaudeCliReady() {
+    const command = findWorkingCommand();
+    if (!command)
+        return false;
+    return probeAuth(command) === true;
+}

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-policy.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Subcommands that must bypass the managed-resource-mismatch gate.
+ *
+ * When the synced resource manifest claims a newer gsd version than the
+ * running binary, exitIfManagedResourcesAreNewer() blocks every command
+ * with a "Version mismatch detected" diagnostic. The `update` subcommand
+ * MUST bypass that gate so the user can recover by upgrading the binary —
+ * otherwise they're stuck in a broken state with no escape hatch.
+ *
+ * Any new bypassed subcommand goes here. cli.ts dispatches on this
+ * predicate before calling exitIfManagedResourcesAreNewer().
+ */
+export declare function shouldBypassManagedResourceMismatchGate(firstMessage: string | undefined): boolean;

package/dist/cli-policy.js

@@ -0,0 +1,17 @@
+// Policy helpers for cli.ts — extracted as pure functions so they can be
+// unit-tested without executing cli.ts's top-level script body.
+/**
+ * Subcommands that must bypass the managed-resource-mismatch gate.
+ *
+ * When the synced resource manifest claims a newer gsd version than the
+ * running binary, exitIfManagedResourcesAreNewer() blocks every command
+ * with a "Version mismatch detected" diagnostic. The `update` subcommand
+ * MUST bypass that gate so the user can recover by upgrading the binary —
+ * otherwise they're stuck in a broken state with no escape hatch.
+ *
+ * Any new bypassed subcommand goes here. cli.ts dispatches on this
+ * predicate before calling exitIfManagedResourcesAreNewer().
+ */
+export function shouldBypassManagedResourceMismatchGate(firstMessage) {
+    return firstMessage === 'update';
+}