gsd-pi 2.63.0 → 2.64.0-dev.05b8a94

package/README.md

@@ -27,152 +27,59 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.52.0
+## What's New in v2.63.0
 
-### VS Code Extension & Web UI
+### MCP Server & Integrations
 
-- **VS Code integration** — status bar, file decorations, bash terminal, session tree, conversation history, and code lens. (#2651)
-- **Dark mode contrast** — raised token floor and flattened opacity tier system for better readability. (#2734)
-- **Auth token gate** — synthetic 401 on missing token, unauthenticated boot state, and recovery screen. (#2740)
+- **MCP server** — 6 read-only project state tools for external integrations, auto-wrapup guard, and question dedup.
+- **Ollama extension** — first-class local LLM support via Ollama, with dynamic routing enabled by default.
+- **Discord bot & daemon** — dedicated daemon package, Discord bot with 6 discord.js shard event listeners, and headless text mode with tool calls.
 
-### Capability Metadata & Model Routing
+### Intelligent Model Routing
 
-- **Capability-based model selection** — replaced model-ID pattern matching with capability metadata, making custom provider integration more reliable. (#2548)
+- **Capability-aware model routing (ADR-004)** — capability scoring, `before_model_select` hook, and task metadata extraction replace pattern-based model selection.
+- **Stop/backtrack capture classifications** — context optimization with model routing and masking.
 
-### Key Changes
+### VS Code & TUI
 
-- **`--bare` mode** — wired across headless, pi-coding-agent, and resource-loader for minimal-output operation.
-- **RPC protocol v2** — new types, init handshake with version detection, and runId generation on prompt/steer/follow_up commands.
-- **PREFERENCES.md rename** — `preferences.md` renamed to `PREFERENCES.md` for consistency. (#2700, #2738)
-- **Comprehensive SQLite audit** — indexes, caching, safety, and reconciliation fixes across gsd-db.
-- **Unified error classifier** — three overlapping error classifiers consolidated into a single classify-decide-act pipeline.
+- **VS Code sidebar redesign** — SCM provider, checkpoints, diagnostics panel, activity feed, workflow controls, session forking, and enhanced code lens.
+- **`/gsd parallel watch`** — native TUI overlay for real-time worker monitoring.
+- **Real-time TUI monitor dashboard** — self-healing dashboard with colorized headless verbose output.
 
-### Key Fixes
+### Agent & Auto-Mode
 
-- **Auto-mode stops on provider errors** — auto loop now halts after provider errors instead of retrying indefinitely. (#2762, #2764)
-- **Transaction safety** — state machine guards moved inside transactions in 5 tool handlers (#2752), and `transaction()` made re-entrant.
-- **Worktree seeding** — `preferences.md` seeded into auto-mode worktrees and included in worktree sync. (#2693)
-- **Idle watchdog** — interactive tools exempted from stall detection (#2676), and filesystem activity no longer overrides stalled-tool detection. (#2697)
-- **Milestone guards** — `allSlicesDone` guarded against vacuous truth on empty slice arrays (#2679), and `complete-milestone` dispatch blocked when validation is `needs-remediation`. (#2682)
-- **Docker overhaul** — fragile setup replaced with proven container patterns. (#2716)
-- **Windows** — EINVAL prevented by disabling detached process groups on Win32. (#2744)
-- **Audit log** — `setLogBasePath` wired into engine init to resurrect audit logging. (#2745)
+- **`/btw` skill** — ephemeral side questions without interrupting the main workflow.
+- **Codebase map** — automatic codebase map injection for fresh agent contexts.
+- **`--resume` flag** — resume previous sessions from the CLI.
+- **Concurrent invocation guard** — prevents overlapping auto-mode runs with parallel worker reliability improvements.
+- **Safety mechanisms on by default** — snapshots and pre-merge checks enabled out of the box.
 
-### v2.51.0 — Skills, RTK, and Verification
+### Infrastructure & Performance
 
-- **`/terminal` command** — direct shell execution from the slash command interface. (#2349)
-- **Managed RTK integration** — RTK binary auto-provisioned with opt-in preference and web UI toggle. (#2620)
-- **Verification classes** — compliance checked before milestone completion, with classes injected into validation prompts. (#2621, #2623)
-- **Skills overhaul** — 30+ new skill packs covering major frameworks, databases, and cloud platforms; curated catalog with `~/.agents/skills/` as primary directory.
+- **Topological sort for extensions** — correct load ordering for dependent extensions.
+- **Headless integration hardening** — real-time streaming, verbose output, and observability improvements across v2.54–v2.55.
+- **GLM-5.1 model** — new model support added.
+- **80+ bug fixes** — worktree safety, parallel mode scoping, state corruption, and more.
 
-### v2.50.0 — Quality Gates
+See the full [Changelog](./CHANGELOG.md) for details on every release.
 
-- **Quality gates** — 8-question quality gates added to planning and completion templates, with parallel evaluation via `evaluating-gates` phase.
-- **Structured error propagation** — errors wired through `UnitResult` for better diagnostics.
-
-### v2.49.0 — Git Trailers & Yolo Mode
-
-- **`--yolo` flag** — `/gsd auto --yolo` for non-interactive project init.
-- **Git trailers** — GSD metadata moved from commit subject scopes to git trailers.
-
-### v2.48.0 — Forensics & Discussion
-
-- **`/gsd discuss` for queued milestones** — target milestones still in the queue. (#2349)
-- **Enhanced forensics** — journal and activity log awareness added to `/gsd forensics`.
-
-### v2.47.0 — External Providers
-
-- **External tool execution mode** — `externalToolExecution` mode for external providers in agent-core.
-- **Claude Code CLI provider** — new provider extension for Claude Code CLI. (#2382)
-
-### Previous highlights (v2.42–v2.46)
-
-- **Single-writer state engine** — disciplined state transitions with machine guards, actor identity, reversibility, and TOCTOU hardening. (#2494)
-- **`/gsd rethink`** — conversational project reorganization. (#2459)
-- **`/gsd mcp`** — MCP server status and connectivity. (#2362)
-- **Complete offline mode** — fully offline with local models. (#2429)
-- **Global KNOWLEDGE.md injection** — cross-project knowledge via `~/.gsd/agent/KNOWLEDGE.md`. (#2331)
-- **Mobile-responsive web UI** — browser interface works on phones and tablets. (#2354)
-- **Default isolation mode changed to `none`** — set `git.isolation: worktree` explicitly if needed. (#2481)
-- **Non-API-key provider extensions** — support for Claude Code CLI and similar providers. (#2382)
-- **Docker sandbox template** — official Docker template for isolated auto mode. (#2360)
-- **DB-backed planning tools** — write-side state transitions use atomic SQLite tool calls. (#2141)
-- **Declarative workflow engine** — YAML workflows through auto-loop. (#2024)
-- **`/gsd fast`** — toggle service tier for prioritized API routing. (#1862)
-
----
-
-## What's New in v2.41.0
-
-### New Features
-
-- **Browser-based web interface** — run GSD from the browser with `gsd --web`. Full project management, real-time progress, and multi-project support via server-sent events. (#1717)
-- **Doctor: worktree lifecycle checks** — `/gsd doctor` now validates worktree health, detects orphaned worktrees, consolidates cleanup, and enhances `/worktree list` with lifecycle status. (#1814)
-- **CI: docs-only PR detection** — PRs that only change documentation skip build and test steps, with a new prompt injection scan for security. (#1699)
-- **Custom Models guide** — new documentation for adding custom providers (Ollama, vLLM, LM Studio, proxies) via `models.json`. (#1670)
-
-### Data Loss Prevention (Critical Fixes)
-
-This release includes 7 fixes preventing silent data loss in auto-mode:
-
-- **Hallucination guard** — execute-task agents that complete with zero tool calls are now rejected as hallucinated. Previously, agents could produce detailed but fabricated summaries without writing any code, wasting ~$25/milestone. (#1838)
-- **Merge anchor verification** — before deleting a milestone worktree/branch, GSD now verifies the code is actually on the integration branch. Prevents orphaning commits when squash-merge produces an empty diff. (#1829)
-- **Dirty working tree detection** — `nativeMergeSquash` now distinguishes dirty-tree rejections from content conflicts, preventing silent commit loss when synced `.gsd/` files block the merge. (#1752)
-- **Doctor cleanup safety** — the `orphaned_completed_units` check no longer auto-fixes during post-task health checks. Previously, timing races could cause the doctor to remove valid completion keys, reverting users to earlier tasks. (#1825)
-- **Root file reverse-sync** — worktree teardown now syncs root-level `.gsd/` files (PROJECT.md, REQUIREMENTS.md, completed-units.json) back to the project root. Previously these were lost on milestone closeout. (#1831)
-- **Empty merge guard** — milestone branches with unanchored code changes are preserved instead of deleted when squash-merge produces nothing to commit. (#1755)
-- **Crash-safe task closeout** — orphaned checkboxes in PLAN.md are unchecked on retry, preventing phantom task completion. (#1759)
-
-### Auto-Mode Stability
-
-- **Terminal hang fix** — `stopAuto()` now resolves pending promises, preventing the terminal from freezing permanently after stopping auto-mode. (#1818)
-- **Signal handler coverage** — SIGHUP and SIGINT now clean up lock files, not just SIGTERM. Prevents stranded locks on VS-Code crash. (#1821)
-- **Needs-discussion routing** — milestones in `needs-discussion` phase now route to the smart entry UI instead of hard-stopping, breaking the infinite loop. (#1820)
-- **Infrastructure error handling** — auto-mode stops immediately on ENOSPC, ENOMEM, and similar unrecoverable errors instead of retrying. (#1780)
-- **Dependency-aware dispatch** — slice dispatch now uses declared `depends_on` instead of positional ordering. (#1770)
-- **Queue mode depth verification** — the write gate now processes depth verification in queue mode, fixing a deadlock where CONTEXT.md writes were permanently blocked. (#1823)
-
-### Roadmap Parser Improvements
-
-- **Table format support** — roadmaps using markdown tables (`| S01 | Title | Risk | Status |`) are now parsed correctly. (#1741)
-- **Prose header fallback** — when `## Slices` contains H3 headers instead of checkboxes, the prose parser is invoked as a fallback. (#1744)
-- **Completion marker detection** — prose headers with `✓` or `(Complete)` markers are correctly identified as done. (#1816)
-- **Zero-slice stub handling** — stub roadmaps from `/gsd queue` return `pre-planning` instead of `blocked`. (#1826)
-- **Immediate roadmap fix** — roadmap checkbox and UAT stub are fixed immediately after last task instead of deferring to `complete-slice`. (#1819)
-
-### State & Git Improvements
-
-- **CONTEXT-DRAFT.md fallback** — `depends_on` is read from CONTEXT-DRAFT.md when CONTEXT.md doesn't exist, preventing draft milestones from being promoted past dependency constraints. (#1743)
-- **Unborn branch support** — `nativeBranchExists` handles repos with zero commits, preventing dispatch deadlock on new repos. (#1815)
-- **Ghost milestone detection** — empty `.gsd/milestones/` directories are skipped instead of crashing `deriveState()`. (#1817)
-- **Default branch detection** — milestone merge detects `master` vs `main` instead of hardcoding. (#1669)
-- **Milestone title extraction** — titles are pulled from CONTEXT.md headings when no ROADMAP exists. (#1729)
-
-### Windows & Platform
-
-- **Windows path handling** — 8.3 short paths, `pathToFileURL` for ESM imports, and `realpathSync.native` fixes across the test suite and verification gate. (#1804)
-- **DEP0190 fix** — `spawnSync` deprecation warning eliminated by passing commands to shell explicitly. (#1827)
-- **Web build skip on Windows** — Next.js webpack EPERM errors on system directories are handled gracefully.
-
-### Developer Experience
-
-- **@ file finder fix** — typing `@` no longer freezes the TUI. The fix adds debounce, dedup, and empty-query short-circuit. (#1832)
-- **Tool-call loop guard** — detects and breaks infinite tool-call loops within a single unit, preventing stack overflow. (#1801)
-- **Completion deferral fix** — roadmap checkbox and UAT stub are fixed at task level, closing the fragile handoff window between last task and `complete-slice`. (#1819)
-
-See the full [Changelog](./CHANGELOG.md) for all 70+ fixes in this release.
-
-### Previous highlights (v2.39–v2.41)
+<details>
+<summary>Previous highlights (v2.52 and earlier)</summary>
 
+- **VS Code integration** — status bar, file decorations, bash terminal, session tree, conversation history, and code lens
+- **Capability-based model selection** — replaced model-ID pattern matching with capability metadata
+- **Skills overhaul** — 30+ skill packs covering major frameworks, databases, and cloud platforms
+- **Quality gates** — 8-question quality gates for planning and completion templates
+- **Single-writer state engine** — disciplined state transitions with machine guards and TOCTOU hardening
+- **`/gsd rethink`** — conversational project reorganization
+- **Complete offline mode** — fully offline with local models
 - **Browser-based web interface** — run GSD from the browser with `gsd --web`
-- **GitHub sync extension** — auto-sync milestones to GitHub Issues, PRs, and Milestones
-- **Skill tool resolution** — skills auto-activate in dispatched prompts
-- **Health check phase 2** — real-time doctor issues in dashboard and visualizer
-- **Forensics upgrade** — full-access GSD debugger with anomaly detection
+- **DB-backed planning tools** — atomic SQLite tool calls for state transitions
+- **Declarative workflow engine** — YAML workflows through auto-loop
 - **7 data-loss prevention fixes** — hallucination guard, merge anchor verification, dirty tree detection, and more
-- **Pipeline decomposition** — auto-loop rewritten as linear phase pipeline
-- **Sliding-window stuck detection** — pattern-aware, fewer false positives
-- **Data-loss recovery** — automatic detection and recovery from v2.30–v2.38 migration issues
+- **Doctor: worktree lifecycle checks** — validates worktree health, detects orphans, consolidates cleanup
+
+</details>
 
 ---
 
@@ -626,7 +533,7 @@ See the full [Token Optimization Guide](./docs/token-optimization.md) for detail
 
 ### Bundled Tools
 
-GSD ships with 19 extensions, all loaded automatically:
+GSD ships with 24 extensions, all loaded automatically:
 
 | Extension              | What it provides                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -648,7 +555,12 @@ GSD ships with 19 extensions, all loaded automatically:
 | **Remote Questions**   | Route decisions to Slack/Discord when human input is needed in headless/CI mode                                         |
 | **Universal Config**   | Discover and import MCP servers and rules from other AI coding tools                                                    |
 | **AWS Auth**           | Automatic Bedrock credential refresh for AWS-hosted models                                                              |
-| **TTSR**               | Tool-use type-safe runtime validation                                                                                   |
+| **Ollama**             | First-class local LLM support via Ollama                                                                                |
+| **Claude Code CLI**    | External provider extension for Claude Code CLI                                                                         |
+| **cmux**               | Claude multiplexer integration — desktop notifications, sidebar metadata, visual subagent splits                        |
+| **GitHub Sync**        | Auto-sync milestones to GitHub Issues, PRs, and Milestones                                                              |
+| **LSP**                | Language Server Protocol — diagnostics, definitions, references, hover, rename                                          |
+| **TTSR**               | Tool-triggered system rules — conditional context injection based on tool usage                                         |
 
 ### Bundled Agents
 
@@ -733,7 +645,7 @@ gsd (CLI binary)
           ├─ resource-loader.ts  Syncs bundled extensions + agents to ~/.gsd/agent/
           └─ src/resources/
               ├─ extensions/gsd/    Core GSD extension (auto, state, commands, ...)
-              ├─ extensions/...     18 supporting extensions
+              ├─ extensions/...     23 supporting extensions
               ├─ agents/            scout, researcher, worker
               ├─ AGENTS.md          Agent routing instructions
               └─ GSD-WORKFLOW.md    Manual bootstrap protocol

package/dist/cli.js

@@ -247,6 +247,10 @@ if (cliFlags.messages[0] === 'sessions') {
 // `gsd headless` — run auto-mode without TUI
 if (cliFlags.messages[0] === 'headless') {
     await ensureRtkBootstrap();
+    // Sync bundled resources before headless runs (#3471). Without this,
+    // headless-query loads from src/resources/ while auto/interactive load
+    // from ~/.gsd/agent/extensions/ — different extension copies diverge.
+    initResources(agentDir);
     const { runHeadless, parseHeadlessArgs } = await import('./headless.js');
     await runHeadless(parseHeadlessArgs(process.argv));
     process.exit(0);
@@ -385,7 +389,7 @@ if (isPrintMode) {
     });
     await resourceLoader.reload();
     markStartup('resourceLoader.reload');
-    const { session, extensionsResult } = await createAgentSession({
+    const { session, extensionsResult, modelFallbackMessage } = await createAgentSession({
         authStorage,
         modelRegistry,
         settingsManager,
@@ -397,11 +401,30 @@ if (isPrintMode) {
     // Before this, extension-provided models (e.g. claude-code/*) were not yet in the
     // registry, causing the user's valid choice to be silently overwritten.
     validateConfiguredModel(modelRegistry, settingsManager);
+    // Re-apply the validated model to the session only when findInitialModel() used a
+    // fallback (not when restoring an existing session's model). This prevents silently
+    // overriding the persisted model of resumed conversations (#3534).
+    if (modelFallbackMessage) {
+        const validatedProvider = settingsManager.getDefaultProvider();
+        const validatedModelId = settingsManager.getDefaultModel();
+        if (validatedProvider && validatedModelId) {
+            const correctModel = modelRegistry.getAvailable()
+                .find((m) => m.provider === validatedProvider && m.id === validatedModelId);
+            if (correctModel) {
+                try {
+                    await session.setModel(correctModel);
+                }
+                catch {
+                    // Provider not ready — leave session on its current model
+                }
+            }
+        }
+    }
     if (extensionsResult.errors.length > 0) {
         for (const err of extensionsResult.errors) {
             // Downgrade conflicts with built-in tools to warnings (#1347)
-            const isSuperseded = err.error.includes("supersedes");
-            const prefix = isSuperseded ? "Extension conflict" : "Extension load error";
+            const isConflict = err.error.includes("supersedes") || err.error.includes("conflicts with");
+            const prefix = isConflict ? "Extension conflict" : "Extension load error";
             process.stderr.write(`[gsd] ${prefix}: ${err.error}\n`);
         }
     }
@@ -521,7 +544,7 @@ const resourceLoadPromise = resourceLoader.reload();
 // Then await the resource promise before creating the agent session.
 await resourceLoadPromise;
 markStartup('resourceLoader.reload');
-const { session, extensionsResult } = await createAgentSession({
+const { session, extensionsResult, modelFallbackMessage: interactiveFallbackMsg } = await createAgentSession({
     authStorage,
     modelRegistry,
     settingsManager,
@@ -533,10 +556,29 @@ markStartup('createAgentSession');
 // Before this, extension-provided models (e.g. claude-code/*) were not yet in the
 // registry, causing the user's valid choice to be silently overwritten.
 validateConfiguredModel(modelRegistry, settingsManager);
+// Re-apply the validated model to the session only when findInitialModel() used a
+// fallback (not when restoring an existing session's model). This prevents silently
+// overriding the persisted model of resumed conversations (#3534).
+if (interactiveFallbackMsg) {
+    const validatedProvider = settingsManager.getDefaultProvider();
+    const validatedModelId = settingsManager.getDefaultModel();
+    if (validatedProvider && validatedModelId) {
+        const correctModel = modelRegistry.getAvailable()
+            .find((m) => m.provider === validatedProvider && m.id === validatedModelId);
+        if (correctModel) {
+            try {
+                await session.setModel(correctModel);
+            }
+            catch {
+                // Provider not ready — leave session on its current model
+            }
+        }
+    }
+}
 if (extensionsResult.errors.length > 0) {
     for (const err of extensionsResult.errors) {
-        const isSuperseded = err.error.includes("supersedes");
-        const prefix = isSuperseded ? "Extension conflict" : "Extension load error";
+        const isConflict = err.error.includes("supersedes") || err.error.includes("conflicts with");
+        const prefix = isConflict ? "Extension conflict" : "Extension load error";
         process.stderr.write(`[gsd] ${prefix}: ${err.error}\n`);
     }
 }

package/dist/headless-query.js

@@ -15,9 +15,19 @@
  */
 import { createJiti } from '@mariozechner/jiti';
 import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 import { resolveBundledSourceResource } from './bundled-resource-path.js';
 const jiti = createJiti(fileURLToPath(import.meta.url), { interopDefault: true, debug: false });
-const gsdExtensionPath = (...segments) => resolveBundledSourceResource(import.meta.url, 'extensions', 'gsd', ...segments);
+// Resolve extensions from the synced agent directory so headless-query
+// loads the same extension copy as interactive/auto modes (#3471).
+// Falls back to bundled source for source-tree dev workflows.
+const agentExtensionsDir = join(process.env.GSD_AGENT_DIR || join(homedir(), '.gsd', 'agent'), 'extensions', 'gsd');
+const { existsSync } = await import('node:fs');
+const useAgentDir = existsSync(join(agentExtensionsDir, 'state.ts'));
+const gsdExtensionPath = (...segments) => useAgentDir
+    ? join(agentExtensionsDir, ...segments)
+    : resolveBundledSourceResource(import.meta.url, 'extensions', 'gsd', ...segments);
 async function loadExtensionModules() {
     const stateModule = await jiti.import(gsdExtensionPath('state.ts'), {});
     const dispatchModule = await jiti.import(gsdExtensionPath('auto-dispatch.ts'), {});

package/dist/headless.js

@@ -184,7 +184,9 @@ async function runHeadlessOnce(options, restartCount) {
     // per-unit timeout via auto-supervisor. Disable the overall timeout unless the
     // user explicitly set --timeout.
     const isAutoMode = options.command === 'auto';
-    const isMultiTurnCommand = options.command === 'auto' || options.command === 'next';
+    // discuss and plan are multi-turn: they involve multiple question rounds,
+    // codebase scanning, and artifact writing before the workflow completes (#3547).
+    const isMultiTurnCommand = options.command === 'auto' || options.command === 'next' || options.command === 'discuss' || options.command === 'plan';
     if (isAutoMode && options.timeout === 300_000) {
         options.timeout = 0;
     }

package/dist/help-text.js

@@ -3,12 +3,15 @@ const SUBCOMMAND_HELP = {
         'Usage: gsd config',
         '',
         'Re-run the interactive setup wizard to configure:',
-        '  - LLM provider (Anthropic, OpenAI, Google, etc.)',
+        '  - LLM provider (Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, etc.)',
         '  - Web search provider (Brave, Tavily, built-in)',
         '  - Remote questions (Discord, Slack, Telegram)',
         '  - Tool API keys (Context7, Jina, Groq)',
         '',
         'All steps are skippable and can be changed later with /login or /search-provider.',
+        '',
+        'For detailed provider setup instructions (OpenRouter, Ollama, LM Studio, vLLM,',
+        'and other OpenAI-compatible endpoints), see docs/providers.md.',
     ].join('\n'),
     update: [
         'Usage: gsd update',

package/dist/onboarding.js

@@ -59,14 +59,13 @@ const API_KEY_PREFIXES = {
     openai: ['sk-'],
 };
 const OTHER_PROVIDERS = [
-    { value: 'google', label: 'Google (Gemini)' },
-    { value: 'groq', label: 'Groq' },
-    { value: 'xai', label: 'xAI (Grok)' },
-    { value: 'openrouter', label: 'OpenRouter' },
-    { value: 'mistral', label: 'Mistral' },
-    { value: 'ollama', label: 'Ollama (Local)' },
+    { value: 'google', label: 'Google (Gemini)', hint: 'aistudio.google.com/app/apikey' },
+    { value: 'groq', label: 'Groq', hint: 'console.groq.com/keys' },
+    { value: 'xai', label: 'xAI (Grok)', hint: 'console.x.ai' },
+    { value: 'openrouter', label: 'OpenRouter', hint: '200+ models — openrouter.ai/keys' },
+    { value: 'mistral', label: 'Mistral', hint: 'console.mistral.ai/api-keys' },
     { value: 'ollama-cloud', label: 'Ollama Cloud' },
-    { value: 'custom-openai', label: 'Custom (OpenAI-compatible)' },
+    { value: 'custom-openai', label: 'Custom (OpenAI-compatible)', hint: 'Ollama, LM Studio, vLLM, proxies — see docs/providers.md' },
 ];
 // ─── Dynamic imports ──────────────────────────────────────────────────────────
 /**
@@ -385,6 +384,11 @@ async function runApiKeyFlow(p, pc, authStorage, providerId, providerLabel) {
     }
     authStorage.set(providerId, { type: 'api_key', key: trimmed });
     p.log.success(`API key saved for ${pc.green(providerLabel)}`);
+    // Provider-specific post-setup hints
+    if (providerId === 'openrouter') {
+        p.log.info(`Use ${pc.cyan('/model')} inside GSD to pick an OpenRouter model.`);
+        p.log.info(`To add custom models or control routing, see ${pc.dim('docs/providers.md#openrouter')}`);
+    }
     return true;
 }
 // ─── Ollama Local Flow ───────────────────────────────────────────────────────
@@ -428,10 +432,11 @@ async function runOllamaLocalFlow(p, pc, authStorage) {
 }
 // ─── Custom OpenAI-compatible Flow ────────────────────────────────────────────
 async function runCustomOpenAIFlow(p, pc, authStorage) {
+    p.log.info(pc.dim('Common endpoints:\n  Ollama:     http://localhost:11434/v1\n  LM Studio:  http://localhost:1234/v1\n  vLLM:       http://localhost:8000/v1'));
     // Prompt for base URL
     const baseUrl = await p.text({
         message: 'Base URL of your OpenAI-compatible endpoint:',
-        placeholder: 'https://my-proxy.example.com/v1',
+        placeholder: 'http://localhost:11434/v1',
         validate: (val) => {
             const trimmed = val?.trim();
             if (!trimmed)
@@ -512,6 +517,8 @@ async function runCustomOpenAIFlow(p, pc, authStorage) {
     p.log.success(`Custom endpoint saved: ${pc.green(trimmedUrl)}`);
     p.log.info(`Model: ${pc.cyan(trimmedModelId)}`);
     p.log.info(`Config written to ${pc.dim(modelsJsonPath)}`);
+    p.log.info(`If you get role or streaming errors, add compat settings to models.json.`);
+    p.log.info(`See ${pc.dim('docs/providers.md#common-pitfalls')} for details.`);
     return true;
 }
 // ─── Web Search Provider Step ─────────────────────────────────────────────────

package/dist/resource-loader.js

@@ -62,9 +62,13 @@ function writeManagedResourceManifest(agentDir) {
             installedExtensionDirs = entries
                 .filter(e => e.isDirectory())
                 .filter(e => {
-                // Only track directories that are actual extensions (contain index.js or index.ts)
+                // Track directories that are actual extensions — identified by an
+                // index.js/index.ts entry point OR an extension-manifest.json (e.g.
+                // remote-questions which uses mod.ts instead of index.ts).
                 const dirPath = join(bundledExtensionsDir, e.name);
-                return existsSync(join(dirPath, 'index.js')) || existsSync(join(dirPath, 'index.ts'));
+                return existsSync(join(dirPath, 'index.js'))
+                    || existsSync(join(dirPath, 'index.ts'))
+                    || existsSync(join(dirPath, 'extension-manifest.json'));
             })
                 .map(e => e.name);
         }
@@ -341,6 +345,17 @@ function pruneRemovedBundledExtensions(manifest, agentDir) {
             removeDirIfStale(prevDir);
         }
     }
+    // Sweep-based: also remove any installed extension subdirectory not in the current bundle,
+    // even if it was never tracked in the manifest (e.g. installed by a pre-manifest version).
+    try {
+        if (existsSync(extensionsDir)) {
+            for (const e of readdirSync(extensionsDir, { withFileTypes: true })) {
+                if (e.isDirectory())
+                    removeDirIfStale(e.name);
+            }
+        }
+    }
+    catch { /* non-fatal */ }
     // Always remove known stale files regardless of manifest state.
     // These were installed by pre-manifest versions so they may not appear in
     // installedExtensionRootFiles even when a manifest exists.
@@ -583,7 +598,7 @@ export function buildResourceLoader(agentDir) {
     return new DefaultResourceLoader({
         agentDir,
         additionalExtensionPaths: piExtensionPaths,
-        bundledExtensionNames: bundledKeys,
+        bundledExtensionKeys: bundledKeys,
         extensionPathsTransform: (paths) => {
             // 1. Filter community extensions through the GSD registry
             const filteredPaths = paths.filter((entryPath) => {

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

@@ -3,7 +3,7 @@
  * context injection, process discovery, footer widget, and periodic maintenance.
  */
 import { truncateToWidth, visibleWidth, } from "@gsd/pi-tui";
-import { processes, pendingAlerts, cleanupAll, cleanupSessionProcesses, persistManifest, loadManifest, pruneDeadProcesses, } from "./process-manager.js";
+import { processes, pendingAlerts, pushAlert, cleanupAll, cleanupSessionProcesses, persistManifest, loadManifest, pruneDeadProcesses, } from "./process-manager.js";
 import { formatUptime, getBgShellLiveCwd, resolveBgShellPersistenceCwd } from "./utilities.js";
 import { formatTokenCount } from "../shared/format-utils.js";
 export function registerBgShellLifecycle(pi, state) {
@@ -15,17 +15,32 @@ export function registerBgShellLifecycle(pi, state) {
             state.latestCtx = { ...state.latestCtx, cwd: syncedCwd };
         }
     }
-    // Clean up on session shutdown
-    pi.on("session_shutdown", async () => {
-        cleanupAll();
-    });
     // Register signal handlers to clean up bg processes on unexpected exit (fixes #428)
     const signalCleanup = () => {
         cleanupAll();
+        // Also kill bash-tool spawned children that bg-shell doesn't track
+        try {
+            const { listDescendants } = require("@gsd/native");
+            const descendants = listDescendants(process.pid);
+            for (const childPid of descendants) {
+                try {
+                    process.kill(childPid, "SIGKILL");
+                }
+                catch { }
+            }
+        }
+        catch { }
     };
     process.on("SIGTERM", signalCleanup);
     process.on("SIGINT", signalCleanup);
     process.on("beforeExit", signalCleanup);
+    // Clean up on session shutdown — remove signal handlers to prevent accumulation
+    pi.on("session_shutdown", async () => {
+        process.off("SIGTERM", signalCleanup);
+        process.off("SIGINT", signalCleanup);
+        process.off("beforeExit", signalCleanup);
+        cleanupAll();
+    });
     // ── Compaction Awareness: Survive Context Resets ───────────────
     /** Build a compact state summary of all alive processes for context re-injection */
     function buildProcessStateAlert(reason) {
@@ -39,7 +54,7 @@ export function registerBgShellLifecycle(pi, state) {
             const groupInfo = p.group ? ` [${p.group}]` : "";
             return `  - id:${p.id} "${p.label}" [${p.processType}] status:${p.status} uptime:${formatUptime(Date.now() - p.startedAt)}${portInfo}${urlInfo}${errInfo}${groupInfo}`;
         }).join("\n");
-        pendingAlerts.push(`${reason} ${alive.length} background process(es) are still running:\n${processSummaries}\nUse bg_shell digest/output/kill with these IDs.`);
+        pushAlert(null, `${reason} ${alive.length} background process(es) are still running:\n${processSummaries}\nUse bg_shell digest/output/kill with these IDs.`);
     }
     // After compaction, the LLM loses all memory of running processes.
     // Queue a detailed alert so the next before_agent_start injects full state.
@@ -108,7 +123,7 @@ export function registerBgShellLifecycle(pi, state) {
             }
             if (surviving.length > 0) {
                 const summary = surviving.map(s => `  - ${s.id}: ${s.label} (pid ${s.pid}, type: ${s.processType}${s.group ? `, group: ${s.group}` : ""})`).join("\n");
-                pendingAlerts.push(`${surviving.length} background process(es) from previous session still running:\n${summary}\n  Note: These processes are outside bg_shell's control. Kill them manually if needed.`);
+                pushAlert(null, `${surviving.length} background process(es) from previous session still running:\n${summary}\n  Note: These processes are outside bg_shell's control. Kill them manually if needed.`);
             }
         }
     });

package/dist/resources/extensions/bg-shell/process-manager.js

@@ -16,6 +16,7 @@ import { startPortProbing, transitionToReady } from "./readiness-detector.js";
 export const processes = new Map();
 /** Pending alerts to inject into the next agent context */
 export let pendingAlerts = [];
+const MAX_PENDING_ALERTS = 50;
 /** Replace the pendingAlerts array (used by the extension entry point) */
 export function setPendingAlerts(alerts) {
     pendingAlerts = alerts;
@@ -41,7 +42,11 @@ export function addEvent(bg, event) {
     }
 }
 export function pushAlert(bg, message) {
-    pendingAlerts.push(`[bg:${bg.id} ${bg.label}] ${message}`);
+    const prefix = bg ? `[bg:${bg.id} ${bg.label}] ` : "";
+    pendingAlerts.push(`${prefix}${message}`);
+    if (pendingAlerts.length > MAX_PENDING_ALERTS) {
+        pendingAlerts.splice(0, pendingAlerts.length - MAX_PENDING_ALERTS);
+    }
 }
 export function getInfo(p) {
     return {

package/dist/resources/extensions/cmux/index.js

@@ -1,7 +1,5 @@
-import { execFile, execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { promisify } from "node:util";
-const execFileAsync = promisify(execFile);
 const DEFAULT_SOCKET_PATH = "/tmp/cmux.sock";
 const STATUS_KEY = "gsd";
 const lastSidebarSnapshots = new Map();
@@ -147,6 +145,7 @@ export class CmuxClient {
             return execFileSync("cmux", args, {
                 encoding: "utf-8",
                 timeout: 3000,
+                stdio: ["ignore", "pipe", "pipe"],
                 env: process.env,
             });
         }
@@ -157,17 +156,27 @@ export class CmuxClient {
     async runAsync(args) {
         if (!this.canRun())
             return null;
-        try {
-            const result = await execFileAsync("cmux", args, {
-                encoding: "utf-8",
-                timeout: 5000,
+        return new Promise((resolve) => {
+            const child = spawn("cmux", args, {
+                stdio: ["ignore", "pipe", "pipe"],
                 env: process.env,
             });
-            return result.stdout;
-        }
-        catch {
-            return null;
-        }
+            const chunks = [];
+            let settled = false;
+            const done = (result) => {
+                if (!settled) {
+                    settled = true;
+                    resolve(result);
+                }
+            };
+            const timer = setTimeout(() => { child.kill(); done(null); }, 5000);
+            child.stdout.on("data", (chunk) => chunks.push(chunk));
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                done(code === 0 ? Buffer.concat(chunks).toString("utf-8") : null);
+            });
+            child.on("error", () => { clearTimeout(timer); done(null); });
+        });
     }
     getCapabilities() {
         const stdout = this.runSync(["capabilities", "--json"]);