gsd-pi 2.78.0 → 2.78.1-dev.84a383f51

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>
 
@@ -589,19 +625,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.
 

package/dist/claude-cli-check.js

@@ -1,6 +1,9 @@
 // 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';
 /**
  * Platform-correct binary name for the Claude Code CLI.
@@ -20,60 +23,116 @@ 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,
+            execFileSync(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 = execFileSync(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);
+        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 = execFileSync(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);
     }
-    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-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';
+}

package/dist/cli.js

@@ -1,4 +1,3 @@
-import { AuthStorage, DefaultResourceLoader, ModelRegistry, runPackageCommand, SettingsManager, SessionManager, createAgentSession, InteractiveMode, runPrintMode, runRpcMode, } from '@gsd/pi-coding-agent';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { agentDir, sessionsDir, authFilePath } from './app-paths.js';
@@ -9,6 +8,7 @@ import { migratePiCredentials } from './pi-migration.js';
 import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
+import { shouldBypassManagedResourceMismatchGate } from './cli-policy.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 import { applySecurityOverrides } from './security-overrides.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
@@ -17,8 +17,11 @@ import { buildHeadlessAutoArgs, parseCliArgs, runWebCliBranch, migrateLegacyFlat
 import { stopWebMode } from './web-mode.js';
 import { getProjectSessionsDir } from './project-sessions.js';
 import { markStartup, printStartupTimings } from './startup-timings.js';
-import { bootstrapRtk, GSD_RTK_DISABLED_ENV } from './rtk.js';
-import { loadEffectiveGSDPreferences } from './resources/extensions/gsd/preferences.js';
+import { applyRtkProcessEnv, GSD_RTK_DISABLED_ENV, isTruthy } from './rtk-shared.js';
+let piCodingAgentModulePromise;
+function loadPiCodingAgentModule() {
+    return (piCodingAgentModulePromise ??= import('@gsd/pi-coding-agent'));
+}
 // ---------------------------------------------------------------------------
 // V8 compile cache — Node 22+ can cache compiled bytecode across runs,
 // eliminating repeated parse/compile overhead for unchanged modules.
@@ -129,27 +132,53 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
 // so concurrent callers await the same initialization.
 let rtkBootstrapPromise;
 async function doRtkBootstrap() {
+    let rtkStatus;
+    let rtkDisabled = isTruthy(process.env[GSD_RTK_DISABLED_ENV]);
     // RTK is opt-in via experimental.rtk preference. Default: disabled.
     // Honor GSD_RTK_DISABLED if already explicitly set in the environment
     // (env var takes precedence over preferences for manual override).
-    if (!process.env[GSD_RTK_DISABLED_ENV]) {
+    if (!rtkDisabled) {
+        const { loadEffectiveGSDPreferences } = await import('./resources/extensions/gsd/preferences.js');
         const prefs = loadEffectiveGSDPreferences();
         const rtkEnabled = prefs?.preferences.experimental?.rtk === true;
         if (!rtkEnabled) {
             process.env[GSD_RTK_DISABLED_ENV] = '1';
+            rtkDisabled = true;
         }
     }
-    const rtkStatus = await bootstrapRtk();
+    markStartup('rtkPreferenceCheck');
+    if (rtkDisabled) {
+        applyRtkProcessEnv(process.env);
+        rtkStatus = {
+            enabled: false,
+            supported: true,
+            available: false,
+            source: 'disabled',
+            reason: `${GSD_RTK_DISABLED_ENV} is set`,
+        };
+    }
+    else {
+        const { bootstrapRtk } = await import('./rtk.js');
+        rtkStatus = await bootstrapRtk();
+    }
     markStartup('bootstrapRtk');
     if (!rtkStatus.available && rtkStatus.supported && rtkStatus.enabled && rtkStatus.reason) {
         process.stderr.write(`[gsd] Warning: RTK unavailable — continuing without shell-command compression (${rtkStatus.reason}).\n`);
     }
 }
 function ensureRtkBootstrap() {
-    return (rtkBootstrapPromise ??= doRtkBootstrap());
-}
-// `gsd update` — update to the latest version via npm
-if (cliFlags.messages[0] === 'update') {
+    if (!rtkBootstrapPromise) {
+        markStartup('preRtkBootstrap');
+        rtkBootstrapPromise = doRtkBootstrap();
+    }
+    return rtkBootstrapPromise;
+}
+// `gsd update` — update to the latest version via npm.
+// MUST run before exitIfManagedResourcesAreNewer(): when the bundled resource
+// manifest is from a newer version than the running binary, every other
+// command is blocked — only `update` should bypass the gate so the user can
+// actually upgrade out of the broken state. See shouldBypassManagedResourceMismatchGate.
+if (shouldBypassManagedResourceMismatchGate(cliFlags.messages[0])) {
     const { runUpdate } = await import('./update-cmd.js');
     await runUpdate();
     process.exit(0);
@@ -246,20 +275,25 @@ const hasSubcommand = cliFlags.messages.length > 0;
 if (!process.stdin.isTTY && !isPrintMode && !hasSubcommand && !cliFlags.listModels && !cliFlags.web) {
     printNonTtyErrorAndExit(undefined, false);
 }
-const packageCommand = await runPackageCommand({
-    appName: 'gsd',
-    args: process.argv.slice(2),
-    cwd: process.cwd(),
-    agentDir,
-    stdout: process.stdout,
-    stderr: process.stderr,
-    allowedCommands: new Set(['install', 'remove', 'list']),
-});
-if (packageCommand.handled) {
-    process.exit(packageCommand.exitCode);
+const packageCommandNames = new Set(['install', 'remove', 'list']);
+if (packageCommandNames.has(cliFlags.messages[0])) {
+    const { runPackageCommand } = await loadPiCodingAgentModule();
+    const packageCommand = await runPackageCommand({
+        appName: 'gsd',
+        args: process.argv.slice(2),
+        cwd: process.cwd(),
+        agentDir,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        allowedCommands: packageCommandNames,
+    });
+    if (packageCommand.handled) {
+        process.exit(packageCommand.exitCode);
+    }
 }
 // `gsd config` — replay the setup wizard and exit
 if (cliFlags.messages[0] === 'config') {
+    const { AuthStorage } = await loadPiCodingAgentModule();
     const authStorage = AuthStorage.create(authFilePath);
     loadStoredEnvKeys(authStorage);
     await runOnboarding(authStorage);
@@ -291,6 +325,7 @@ if (cliFlags.web || (cliFlags.messages[0] === 'web' && cliFlags.messages[1] !==
 }
 // `gsd sessions` — list past sessions and pick one to resume
 if (cliFlags.messages[0] === 'sessions') {
+    const { SessionManager } = await loadPiCodingAgentModule();
     const cwd = process.cwd();
     const safePath = `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
     const projectSessionsDir = join(sessionsDir, safePath);
@@ -380,6 +415,35 @@ function flushPendingProviderRegistrations(resourceLoader, modelRegistry) {
 if (cliFlags.messages[0] === 'auto') {
     await runHeadlessFromAuto(buildHeadlessAutoArgs(cliFlags));
 }
+// ---------------------------------------------------------------------------
+// Worktree subcommand — `gsd worktree <list|merge|clean|remove>`
+// ---------------------------------------------------------------------------
+if (!isPrintMode &&
+    cliFlags.listModels === undefined &&
+    (cliFlags.messages[0] === 'worktree' || cliFlags.messages[0] === 'wt')) {
+    const { handleList, handleMerge, handleClean, handleRemove } = await import('./worktree-cli.js');
+    const sub = cliFlags.messages[1];
+    const subArgs = cliFlags.messages.slice(2);
+    if (!sub || sub === 'list') {
+        await handleList(process.cwd());
+    }
+    else if (sub === 'merge') {
+        await handleMerge(process.cwd(), subArgs);
+    }
+    else if (sub === 'clean') {
+        await handleClean(process.cwd());
+    }
+    else if (sub === 'remove' || sub === 'rm') {
+        await handleRemove(process.cwd(), subArgs);
+    }
+    else {
+        process.stderr.write(`Unknown worktree command: ${sub}\n`);
+        process.stderr.write('Commands: list, merge [name], clean, remove <name>\n');
+    }
+    process.exit(0);
+}
+const { AuthStorage, DefaultResourceLoader, ModelRegistry, SettingsManager, SessionManager, createAgentSession, InteractiveMode, runPrintMode, runRpcMode, } = await loadPiCodingAgentModule();
+markStartup('loadPiCodingAgent');
 // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
 // Provision local managed binaries first so Pi sees them without probing PATH.
@@ -431,11 +495,7 @@ if (cliFlags.listModels !== undefined) {
         additionalExtensionPaths: cliFlags.extensions.length > 0 ? cliFlags.extensions : undefined,
     });
     await listModelsLoader.reload();
-    const listModelsExtensions = listModelsLoader.getExtensions();
-    for (const { name, config } of listModelsExtensions.runtime.pendingProviderRegistrations) {
-        modelRegistry.registerProvider(name, config);
-    }
-    listModelsExtensions.runtime.pendingProviderRegistrations = [];
+    flushPendingProviderRegistrations(listModelsLoader, modelRegistry);
     const models = modelRegistry.getAvailable();
     if (models.length === 0) {
         console.log('No models available. Set API keys in environment variables.');
@@ -483,6 +543,7 @@ if (!settingsManager.getQuietStartup()) {
 if (!settingsManager.getCollapseChangelog()) {
     settingsManager.setCollapseChangelog(true);
 }
+markStartup('startupSettings');
 // ---------------------------------------------------------------------------
 // Print / subagent mode — single-shot execution, no TTY required
 // ---------------------------------------------------------------------------
@@ -515,7 +576,7 @@ if (isPrintMode) {
     flushPendingProviderRegistrations(resourceLoader, modelRegistry);
     migrateAnthropicDefaultToClaudeCode({
         authStorage,
-        isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+        isClaudeCodeReady: () => modelRegistry.isProviderRequestReady('claude-code'),
         settingsManager,
         modelRegistry,
     });
@@ -577,31 +638,6 @@ if (isPrintMode) {
     process.exit(0);
 }
 // ---------------------------------------------------------------------------
-// Worktree subcommand — `gsd worktree <list|merge|clean|remove>`
-// ---------------------------------------------------------------------------
-if (cliFlags.messages[0] === 'worktree' || cliFlags.messages[0] === 'wt') {
-    const { handleList, handleMerge, handleClean, handleRemove } = await import('./worktree-cli.js');
-    const sub = cliFlags.messages[1];
-    const subArgs = cliFlags.messages.slice(2);
-    if (!sub || sub === 'list') {
-        await handleList(process.cwd());
-    }
-    else if (sub === 'merge') {
-        await handleMerge(process.cwd(), subArgs);
-    }
-    else if (sub === 'clean') {
-        await handleClean(process.cwd());
-    }
-    else if (sub === 'remove' || sub === 'rm') {
-        await handleRemove(process.cwd(), subArgs);
-    }
-    else {
-        process.stderr.write(`Unknown worktree command: ${sub}\n`);
-        process.stderr.write('Commands: list, merge [name], clean, remove <name>\n');
-    }
-    process.exit(0);
-}
-// ---------------------------------------------------------------------------
 // Worktree flag (-w) — create/resume a worktree for the interactive session
 // ---------------------------------------------------------------------------
 if (cliFlags.worktree) {
@@ -613,11 +649,12 @@ if (cliFlags.worktree) {
 // ---------------------------------------------------------------------------
 if (!cliFlags.worktree && !isPrintMode) {
     try {
-        const { handleStatusBanner } = await import('./worktree-cli.js');
-        await handleStatusBanner(process.cwd());
+        const { showWorktreeStatusBanner } = await import('./worktree-status-banner.js');
+        showWorktreeStatusBanner(process.cwd());
     }
     catch { /* non-fatal */ }
 }
+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`),
@@ -651,7 +688,9 @@ markStartup('initResources');
 // Overlap resource loading with session manager setup — both are independent.
 // resourceLoader.reload() is the most expensive step (jiti compilation), so
 // starting it early shaves ~50-200ms off interactive startup.
-const resourceLoader = buildResourceLoader(agentDir);
+const resourceLoader = await buildResourceLoader(agentDir, {
+    additionalExtensionPaths: cliFlags.extensions.length > 0 ? cliFlags.extensions : undefined,
+});
 const resourceLoadPromise = resourceLoader.reload();
 // While resources load, let session manager finish any async I/O it needs.
 // Then await the resource promise before creating the agent session.
@@ -660,10 +699,11 @@ markStartup('resourceLoader.reload');
 flushPendingProviderRegistrations(resourceLoader, modelRegistry);
 migrateAnthropicDefaultToClaudeCode({
     authStorage,
-    isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+    isClaudeCodeReady: () => modelRegistry.isProviderRequestReady('claude-code'),
     settingsManager,
     modelRegistry,
 });
+markStartup('providerMigrations');
 const { session, extensionsResult, modelFallbackMessage: interactiveFallbackMsg } = await createAgentSession({
     authStorage,
     modelRegistry,

package/dist/headless-query.d.ts

@@ -14,6 +14,28 @@
  * bypassing the extension loader's jiti setup (#1137).
  */
 import type { GSDState } from './resources/extensions/gsd/types.js';
+/**
+ * Resolve the GSD extensions root for headless-query. Prefers the synced
+ * agent directory (so headless-query loads the same extension copy as
+ * interactive/auto modes — #3471) and falls back to the bundled source
+ * resource for source-tree dev workflows.
+ *
+ * Pure on the given inputs (env + fs probe + bundled resolver) so the
+ * #3471 contract can be exercised in tests without spawning a subprocess.
+ */
+export declare function resolveGsdAgentExtensionsDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * Decide whether headless-query should load extensions from the agent
+ * sync directory (#3471) or fall back to bundled source. Returns the
+ * agent dir alongside the decision so a caller can use it directly.
+ */
+export declare function shouldUseAgentExtensionsDir(opts: {
+    env?: NodeJS.ProcessEnv;
+    fileExists?: (path: string) => boolean;
+}): {
+    agentDir: string;
+    useAgentDir: boolean;
+};
 export interface QuerySnapshot {
     state: GSDState;
     next: {