gsd-pi 2.29.0-next.1 → 2.30.0-dev.54ac83b

package/README.md

@@ -24,14 +24,21 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.28
-
-- **`gsd headless query`** — instant JSON snapshot of project state (~50ms, no LLM session)
-- **`/gsd update`** — update GSD to the latest version without leaving your session
-- **`/gsd export --html --all`** — generate retrospective HTML reports for all milestones at once
-- **Reliability hardening** — atomic file writes, OAuth fetch timeouts, RPC exit detection, blob GC, LSP init retry with backoff
-- **RPC utilities** now part of the public API for headless/scripted integrations
-- **npm** established as the canonical package manager
+## What's New in v2.29
+
+- **Node.js 24 LTS** — CI, Docker, and package config all upgraded to Node 24 (Krypton)
+- **`searchExcludeDirs` setting** — blacklist directories from `@` file autocomplete (e.g., `node_modules`, `dist`)
+- **Automated releases** — prod-release now auto-generates changelogs, bumps versions, and publishes to npm
+- **`/gsd logs`** — browse activity, debug, and metrics logs from within a session
+- **Configurable screenshots** — browser-tools now support custom resolution, format, and quality
+- **Pre-commit secret scanning** — automatic detection of hardcoded secrets in CI and locally
+- **Per-project MCP config** — `.gsd/mcp.json` for project-scoped MCP server definitions
+- **API request metrics** — track request counts for Copilot/subscription users
+- **`/gsd keys`** — full API key lifecycle management (list, add, remove, test, rotate, doctor)
+- **Advisory verification gate** — auto-discovered checks (lint/test from package.json) no longer doom-loop on pre-existing errors
+- **Worktree living doc sync** — DECISIONS, REQUIREMENTS, PROJECT, and KNOWLEDGE now sync between worktree and project root
+- **Windows non-ASCII path support** — `cpSync` fallback for usernames with special characters
+- **`needs-discussion` routing** — milestones with draft context now route to the interactive discussion flow instead of stopping
 
 See the full [Changelog](./CHANGELOG.md) for details.
 
@@ -53,8 +60,11 @@ Full documentation is available in the [`docs/`](./docs/) directory:
 - **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts
 - **[Architecture](./docs/architecture.md)** — system design and dispatch pipeline
 - **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, forensics, recovery
+- **[CI/CD Pipeline](./docs/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod)
 - **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration
 - **[Visualizer](./docs/visualizer.md)** — workflow visualizer with stats and discussion status
+- **[Remote Questions](./docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed
+- **[Dynamic Model Routing](./docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure
 - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
 
 ---
@@ -168,7 +178,7 @@ Auto mode is a state machine driven by files on disk. It reads `.gsd/STATE.md`,
 
 9. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
 
-10. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
+10. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Auto-discovered checks from `package.json` run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
 
 11. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
 
@@ -299,6 +309,8 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd forensics`        | Post-mortem investigation of auto-mode failures                 |
 | `/gsd cleanup`          | Archive phase directories from completed milestones             |
 | `/gsd doctor`           | Runtime health checks with auto-fix for common issues           |
+| `/gsd keys`             | API key manager — list, add, remove, test, rotate, doctor       |
+| `/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          |
 | `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                  |
@@ -439,6 +451,7 @@ auto_report: true
 | `verification_max_retries` | Max retries for verification failures (default: 2)                                               |
 | `require_slice_discussion` | Pause auto-mode before each slice for human discussion review                                    |
 | `auto_report`          | Auto-generate HTML reports after milestone completion (default: true)                                 |
+| `searchExcludeDirs`    | Directories to exclude from `@` file autocomplete (e.g., `["node_modules", ".git", "dist"]`)          |
 
 ### Agent Instructions
 
@@ -470,7 +483,7 @@ See the full [Token Optimization Guide](./docs/token-optimization.md) for detail
 
 ### Bundled Tools
 
-GSD ships with 14 extensions, all loaded automatically:
+GSD ships with 16 extensions, all loaded automatically:
 
 | Extension              | What it provides                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -482,12 +495,14 @@ GSD ships with 14 extensions, all loaded automatically:
 | **Background Shell**   | Long-running process management with readiness detection                                                               |
 | **Subagent**           | Delegated tasks with isolated context windows                                                                          |
 | **Mac Tools**          | macOS native app automation via Accessibility APIs                                                                     |
-| **MCPorter**           | Lazy on-demand MCP server integration                                                                                  |
+| **MCP Client**         | Native MCP server integration via @modelcontextprotocol/sdk                                                            |
 | **Voice**              | Real-time speech-to-text transcription (macOS, Linux — Ubuntu 22.04+)                                                  |
 | **Slash Commands**     | Custom command creation                                                                                                |
 | **LSP**                | Language Server Protocol integration — diagnostics, go-to-definition, references, hover, symbols, rename, code actions |
 | **Ask User Questions** | Structured user input with single/multi-select                                                                         |
 | **Secure Env Collect** | Masked secret collection without manual .env editing                                                                   |
+| **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                                                    |
 
 ### Bundled Agents
 
@@ -589,7 +604,7 @@ gsd (CLI binary)
 
 ## Requirements
 
-- **Node.js** ≥ 20.6.0 (22+ recommended)
+- **Node.js** ≥ 22.0.0 (24 LTS recommended)
 - **An LLM provider** — any of the 20+ supported providers (see [Use Any Model](#use-any-model))
 - **Git** — initialized automatically if missing
 

package/dist/cli.js

@@ -59,6 +59,15 @@ function parseCliArgs(argv) {
             process.stdout.write((process.env.GSD_VERSION || '0.0.0') + '\n');
             process.exit(0);
         }
+        else if (arg === '--worktree' || arg === '-w') {
+            // -w with no value → auto-generate name; -w <name> → use that name
+            if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+                flags.worktree = args[++i];
+            }
+            else {
+                flags.worktree = true;
+            }
+        }
         else if (arg === '--help' || arg === '-h') {
             printHelp(process.env.GSD_VERSION || '0.0.0');
             process.exit(0);
@@ -71,6 +80,21 @@ function parseCliArgs(argv) {
 }
 const cliFlags = parseCliArgs(process.argv);
 const isPrintMode = cliFlags.print || cliFlags.mode !== undefined;
+// Early resource-skew check — must run before TTY gate so version mismatch
+// errors surface even in non-TTY environments.
+exitIfManagedResourcesAreNewer(agentDir);
+// Early TTY check — must come before heavy initialization to avoid dangling
+// handles that prevent process.exit() from completing promptly.
+const hasSubcommand = cliFlags.messages.length > 0;
+if (!process.stdin.isTTY && !isPrintMode && !hasSubcommand && !cliFlags.listModels) {
+    process.stderr.write('[gsd] Error: Interactive mode requires a terminal (TTY).\n');
+    process.stderr.write('[gsd] Non-interactive alternatives:\n');
+    process.stderr.write('[gsd]   gsd --print "your message"     Single-shot prompt\n');
+    process.stderr.write('[gsd]   gsd --mode rpc                 JSON-RPC over stdin/stdout\n');
+    process.stderr.write('[gsd]   gsd --mode mcp                 MCP server over stdin/stdout\n');
+    process.stderr.write('[gsd]   gsd --mode text "message"      Text output mode\n');
+    process.exit(1);
+}
 // `gsd <subcommand> --help` — show subcommand-specific help
 const subcommand = cliFlags.messages[0];
 if (subcommand && process.argv.includes('--help')) {
@@ -328,6 +352,48 @@ 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') {
+        handleList(process.cwd());
+    }
+    else if (sub === 'merge') {
+        await handleMerge(process.cwd(), subArgs);
+    }
+    else if (sub === 'clean') {
+        handleClean(process.cwd());
+    }
+    else if (sub === 'remove' || sub === 'rm') {
+        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) {
+    const { handleWorktreeFlag } = await import('./worktree-cli.js');
+    handleWorktreeFlag(cliFlags.worktree);
+}
+// ---------------------------------------------------------------------------
+// Active worktree banner — remind user of unmerged worktrees on normal launch
+// ---------------------------------------------------------------------------
+if (!cliFlags.worktree && !isPrintMode) {
+    try {
+        const { handleStatusBanner } = await import('./worktree-cli.js');
+        handleStatusBanner(process.cwd());
+    }
+    catch { /* non-fatal */ }
+}
+// ---------------------------------------------------------------------------
 // Interactive mode — normal TTY session
 // ---------------------------------------------------------------------------
 // Per-directory session storage — same encoding as the upstream SDK so that
@@ -420,14 +486,5 @@ if (enabledModelPatterns && enabledModelPatterns.length > 0) {
         session.setScopedModels(scopedModels);
     }
 }
-if (!process.stdin.isTTY) {
-    process.stderr.write('[gsd] Error: Interactive mode requires a terminal (TTY).\n');
-    process.stderr.write('[gsd] Non-interactive alternatives:\n');
-    process.stderr.write('[gsd]   gsd --print "your message"     Single-shot prompt\n');
-    process.stderr.write('[gsd]   gsd --mode rpc                 JSON-RPC over stdin/stdout\n');
-    process.stderr.write('[gsd]   gsd --mode mcp                 MCP server over stdin/stdout\n');
-    process.stderr.write('[gsd]   gsd --mode text "message"      Text output mode\n');
-    process.exit(1);
-}
 const interactiveMode = new InteractiveMode(session);
 await interactiveMode.run();

package/dist/extension-registry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Extension Registry — manages manifest reading, registry persistence, and enable/disable state.
+ *
+ * Extensions without manifests always load (backwards compatible).
+ * A fresh install has an empty registry — all extensions enabled by default.
+ * The only way an extension stops loading is an explicit `gsd extensions disable <id>`.
+ */
+export interface ExtensionManifest {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    tier: "core" | "bundled" | "community";
+    requires: {
+        platform: string;
+    };
+    provides?: {
+        tools?: string[];
+        commands?: string[];
+        hooks?: string[];
+        shortcuts?: string[];
+    };
+    dependencies?: {
+        extensions?: string[];
+        runtime?: string[];
+    };
+}
+export interface ExtensionRegistryEntry {
+    id: string;
+    enabled: boolean;
+    source: "bundled" | "user" | "project";
+    disabledAt?: string;
+    disabledReason?: string;
+}
+export interface ExtensionRegistry {
+    version: 1;
+    entries: Record<string, ExtensionRegistryEntry>;
+}
+export declare function getRegistryPath(): string;
+export declare function loadRegistry(): ExtensionRegistry;
+export declare function saveRegistry(registry: ExtensionRegistry): void;
+/** Returns true if the extension is enabled (missing entries default to enabled). */
+export declare function isExtensionEnabled(registry: ExtensionRegistry, id: string): boolean;
+export declare function enableExtension(registry: ExtensionRegistry, id: string): void;
+/**
+ * Disable an extension. Returns an error string if the extension is core (cannot disable),
+ * or null on success.
+ */
+export declare function disableExtension(registry: ExtensionRegistry, id: string, manifest: ExtensionManifest | null, reason?: string): string | null;
+/** Read extension-manifest.json from a directory. Returns null if missing or invalid. */
+export declare function readManifest(extensionDir: string): ExtensionManifest | null;
+/**
+ * Given an entry path (e.g. `.../extensions/browser-tools/index.ts`),
+ * resolve the parent directory and read its manifest.
+ */
+export declare function readManifestFromEntryPath(entryPath: string): ExtensionManifest | null;
+/** Scan all subdirectories of extensionsDir for manifests. Returns a Map<id, manifest>. */
+export declare function discoverAllManifests(extensionsDir: string): Map<string, ExtensionManifest>;
+/**
+ * Auto-populate registry entries for newly discovered extensions.
+ * Extensions already in the registry are left untouched.
+ */
+export declare function ensureRegistryEntries(extensionsDir: string): void;

package/dist/extension-registry.js

@@ -0,0 +1,166 @@
+/**
+ * Extension Registry — manages manifest reading, registry persistence, and enable/disable state.
+ *
+ * Extensions without manifests always load (backwards compatible).
+ * A fresh install has an empty registry — all extensions enabled by default.
+ * The only way an extension stops loading is an explicit `gsd extensions disable <id>`.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// ─── Validation ─────────────────────────────────────────────────────────────
+function isRegistry(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const obj = data;
+    return obj.version === 1 && typeof obj.entries === "object" && obj.entries !== null;
+}
+function isManifest(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const obj = data;
+    return (typeof obj.id === "string" &&
+        typeof obj.name === "string" &&
+        typeof obj.version === "string" &&
+        typeof obj.tier === "string");
+}
+// ─── Registry Path ──────────────────────────────────────────────────────────
+export function getRegistryPath() {
+    return join(homedir(), ".gsd", "extensions", "registry.json");
+}
+// ─── Registry I/O ───────────────────────────────────────────────────────────
+function defaultRegistry() {
+    return { version: 1, entries: {} };
+}
+export function loadRegistry() {
+    const filePath = getRegistryPath();
+    try {
+        if (!existsSync(filePath))
+            return defaultRegistry();
+        const raw = readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return isRegistry(parsed) ? parsed : defaultRegistry();
+    }
+    catch {
+        return defaultRegistry();
+    }
+}
+export function saveRegistry(registry) {
+    const filePath = getRegistryPath();
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        const tmp = filePath + ".tmp";
+        writeFileSync(tmp, JSON.stringify(registry, null, 2), "utf-8");
+        renameSync(tmp, filePath);
+    }
+    catch {
+        // Non-fatal — don't let persistence failures break operation
+    }
+}
+// ─── Query ──────────────────────────────────────────────────────────────────
+/** Returns true if the extension is enabled (missing entries default to enabled). */
+export function isExtensionEnabled(registry, id) {
+    const entry = registry.entries[id];
+    if (!entry)
+        return true;
+    return entry.enabled;
+}
+// ─── Mutations ──────────────────────────────────────────────────────────────
+export function enableExtension(registry, id) {
+    const entry = registry.entries[id];
+    if (entry) {
+        entry.enabled = true;
+        delete entry.disabledAt;
+        delete entry.disabledReason;
+    }
+    else {
+        registry.entries[id] = { id, enabled: true, source: "bundled" };
+    }
+}
+/**
+ * Disable an extension. Returns an error string if the extension is core (cannot disable),
+ * or null on success.
+ */
+export function disableExtension(registry, id, manifest, reason) {
+    if (manifest?.tier === "core") {
+        return `Cannot disable "${id}" — it is a core extension.`;
+    }
+    const entry = registry.entries[id];
+    if (entry) {
+        entry.enabled = false;
+        entry.disabledAt = new Date().toISOString();
+        entry.disabledReason = reason;
+    }
+    else {
+        registry.entries[id] = {
+            id,
+            enabled: false,
+            source: "bundled",
+            disabledAt: new Date().toISOString(),
+            disabledReason: reason,
+        };
+    }
+    return null;
+}
+// ─── Manifest Reading ───────────────────────────────────────────────────────
+/** Read extension-manifest.json from a directory. Returns null if missing or invalid. */
+export function readManifest(extensionDir) {
+    const manifestPath = join(extensionDir, "extension-manifest.json");
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        return isManifest(raw) ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Given an entry path (e.g. `.../extensions/browser-tools/index.ts`),
+ * resolve the parent directory and read its manifest.
+ */
+export function readManifestFromEntryPath(entryPath) {
+    const dir = dirname(entryPath);
+    return readManifest(dir);
+}
+// ─── Discovery ──────────────────────────────────────────────────────────────
+/** Scan all subdirectories of extensionsDir for manifests. Returns a Map<id, manifest>. */
+export function discoverAllManifests(extensionsDir) {
+    const manifests = new Map();
+    if (!existsSync(extensionsDir))
+        return manifests;
+    for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const manifest = readManifest(join(extensionsDir, entry.name));
+        if (manifest) {
+            manifests.set(manifest.id, manifest);
+        }
+    }
+    return manifests;
+}
+/**
+ * Auto-populate registry entries for newly discovered extensions.
+ * Extensions already in the registry are left untouched.
+ */
+export function ensureRegistryEntries(extensionsDir) {
+    const manifests = discoverAllManifests(extensionsDir);
+    if (manifests.size === 0)
+        return;
+    const registry = loadRegistry();
+    let changed = false;
+    for (const [id, manifest] of manifests) {
+        if (!registry.entries[id]) {
+            registry.entries[id] = {
+                id,
+                enabled: true,
+                source: "bundled",
+            };
+            changed = true;
+        }
+    }
+    if (changed) {
+        saveRegistry(registry);
+    }
+}

package/dist/headless-query.d.ts

@@ -8,6 +8,10 @@
  *   state — deriveState() output (phase, milestones, progress, blockers)
  *   next  — dry-run dispatch preview (what auto-mode would do next)
  *   cost  — aggregated parallel worker costs
+ *
+ * Note: Extension modules are .ts files loaded via jiti (not compiled to .js).
+ * We use createJiti() here because this module is imported directly from cli.ts,
+ * bypassing the extension loader's jiti setup (#1137).
  */
 import type { GSDState } from './resources/extensions/gsd/types.js';
 export interface QuerySnapshot {

package/dist/headless-query.js

@@ -8,13 +8,31 @@
  *   state — deriveState() output (phase, milestones, progress, blockers)
  *   next  — dry-run dispatch preview (what auto-mode would do next)
  *   cost  — aggregated parallel worker costs
+ *
+ * Note: Extension modules are .ts files loaded via jiti (not compiled to .js).
+ * We use createJiti() here because this module is imported directly from cli.ts,
+ * bypassing the extension loader's jiti setup (#1137).
  */
-import { deriveState } from './resources/extensions/gsd/state.js';
-import { resolveDispatch } from './resources/extensions/gsd/auto-dispatch.js';
-import { readAllSessionStatuses } from './resources/extensions/gsd/session-status-io.js';
-import { loadEffectiveGSDPreferences } from './resources/extensions/gsd/preferences.js';
+import { createJiti } from '@mariozechner/jiti';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const jiti = createJiti(fileURLToPath(import.meta.url), { interopDefault: true, debug: false });
+async function loadExtensionModules() {
+    const stateModule = await jiti.import(join(__dirname, 'resources/extensions/gsd/state.ts'), {});
+    const dispatchModule = await jiti.import(join(__dirname, 'resources/extensions/gsd/auto-dispatch.ts'), {});
+    const sessionModule = await jiti.import(join(__dirname, 'resources/extensions/gsd/session-status-io.ts'), {});
+    const prefsModule = await jiti.import(join(__dirname, 'resources/extensions/gsd/preferences.ts'), {});
+    return {
+        deriveState: stateModule.deriveState,
+        resolveDispatch: dispatchModule.resolveDispatch,
+        readAllSessionStatuses: sessionModule.readAllSessionStatuses,
+        loadEffectiveGSDPreferences: prefsModule.loadEffectiveGSDPreferences,
+    };
+}
 // ─── Implementation ─────────────────────────────────────────────────────────
 export async function handleQuery(basePath) {
+    const { deriveState, resolveDispatch, readAllSessionStatuses, loadEffectiveGSDPreferences } = await loadExtensionModules();
     const state = await deriveState(basePath);
     // Derive next dispatch action
     let next;

package/dist/headless.js

@@ -128,6 +128,10 @@ async function runHeadlessOnce(options, restartCount) {
     let interrupted = false;
     const startTime = Date.now();
     const isNewMilestone = options.command === 'new-milestone';
+    // new-milestone involves codebase investigation + artifact writing — needs more time
+    if (isNewMilestone && options.timeout === 300_000) {
+        options.timeout = 600_000; // 10 minutes
+    }
     // Supervised mode cannot share stdin with --context -
     if (options.supervised && options.context === '-') {
         process.stderr.write('[headless] Error: --supervised cannot be used with --context - (both require stdin)\n');

package/dist/help-text.js

@@ -29,6 +29,37 @@ const SUBCOMMAND_HELP = {
         '',
         'Compare with --continue (-c) which always resumes the most recent session.',
     ].join('\n'),
+    worktree: [
+        'Usage: gsd worktree <command> [args]',
+        '',
+        'Manage isolated git worktrees for parallel work streams.',
+        '',
+        'Commands:',
+        '  list                 List worktrees with status (files changed, commits, dirty)',
+        '  merge [name]         Squash-merge a worktree into main and clean up',
+        '  clean                Remove all worktrees that have been merged or are empty',
+        '  remove <name>        Remove a worktree (--force to remove with unmerged changes)',
+        '',
+        'The -w flag creates/resumes worktrees for interactive sessions:',
+        '  gsd -w               Auto-name a new worktree, or resume the only active one',
+        '  gsd -w my-feature    Create or resume a named worktree',
+        '',
+        'Lifecycle:',
+        '  1. gsd -w             Create worktree, start session inside it',
+        '  2. (work normally)    All changes happen on the worktree branch',
+        '  3. Ctrl+C             Exit — dirty work is auto-committed',
+        '  4. gsd -w             Resume where you left off',
+        '  5. gsd worktree merge Squash-merge into main when done',
+        '',
+        'Examples:',
+        '  gsd -w                              Start in a new auto-named worktree',
+        '  gsd -w auth-refactor                Create/resume "auth-refactor" worktree',
+        '  gsd worktree list                   See all worktrees and their status',
+        '  gsd worktree merge auth-refactor    Merge and clean up',
+        '  gsd worktree clean                  Remove all merged/empty worktrees',
+        '  gsd worktree remove old-branch      Remove a specific worktree',
+        '  gsd worktree remove old-branch --force  Remove even with unmerged changes',
+    ].join('\n'),
     headless: [
         'Usage: gsd headless [flags] [command] [args...]',
         '',
@@ -72,6 +103,8 @@ const SUBCOMMAND_HELP = {
         'Exit codes: 0 = complete, 1 = error/timeout, 2 = blocked',
     ].join('\n'),
 };
+// Alias: `gsd wt --help` → same as `gsd worktree --help`
+SUBCOMMAND_HELP['wt'] = SUBCOMMAND_HELP['worktree'];
 export function printHelp(version) {
     process.stdout.write(`GSD v${version} — Get Shit Done\n\n`);
     process.stdout.write('Usage: gsd [options] [message...]\n\n');
@@ -79,6 +112,7 @@ export function printHelp(version) {
     process.stdout.write('  --mode <text|json|rpc|mcp> Output mode (default: interactive)\n');
     process.stdout.write('  --print, -p              Single-shot print mode\n');
     process.stdout.write('  --continue, -c           Resume the most recent session\n');
+    process.stdout.write('  --worktree, -w [name]    Start in an isolated worktree (auto-named if omitted)\n');
     process.stdout.write('  --model <id>             Override model (e.g. claude-opus-4-6)\n');
     process.stdout.write('  --no-session             Disable session persistence\n');
     process.stdout.write('  --extension <path>       Load additional extension\n');
@@ -90,6 +124,7 @@ export function printHelp(version) {
     process.stdout.write('  config                   Re-run the setup wizard\n');
     process.stdout.write('  update                   Update GSD to the latest version\n');
     process.stdout.write('  sessions                 List and resume a past session\n');
+    process.stdout.write('  worktree <cmd>           Manage worktrees (list, merge, clean, remove)\n');
     process.stdout.write('  headless [cmd] [args]    Run /gsd commands without TUI (default: auto)\n');
     process.stdout.write('\nRun gsd <subcommand> --help for subcommand-specific help.\n');
 }

package/dist/loader.js

@@ -29,6 +29,7 @@ if (firstArg === '--help' || firstArg === '-h') {
 import { agentDir, appRoot } from './app-paths.js';
 import { serializeBundledExtensionPaths } from './bundled-extension-paths.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
+import { loadRegistry, readManifestFromEntryPath, isExtensionEnabled } from './extension-registry.js';
 import { renderLogo } from './logo.js';
 // pkg/ is a shim directory: contains gsd's piConfig (package.json) and pi's
 // theme assets (dist/modes/interactive/theme/) without a src/ directory.
@@ -86,7 +87,15 @@ process.env.GSD_WORKFLOW_PATH = join(resourcesDir, 'GSD-WORKFLOW.md');
 // where initResources() will sync them.
 const bundledExtDir = join(resourcesDir, 'extensions');
 const agentExtDir = join(agentDir, 'extensions');
-const discoveredExtensionPaths = discoverExtensionEntryPaths(bundledExtDir).map((entryPath) => join(agentExtDir, relative(bundledExtDir, entryPath)));
+const registry = loadRegistry();
+const discoveredExtensionPaths = discoverExtensionEntryPaths(bundledExtDir)
+    .map((entryPath) => join(agentExtDir, relative(bundledExtDir, entryPath)))
+    .filter((entryPath) => {
+    const manifest = readManifestFromEntryPath(entryPath);
+    if (!manifest)
+        return true; // no manifest = always load
+    return isExtensionEnabled(registry, manifest.id);
+});
 process.env.GSD_BUNDLED_EXTENSION_PATHS = serializeBundledExtensionPaths(discoveredExtensionPaths);
 // Respect HTTP_PROXY / HTTPS_PROXY / NO_PROXY env vars for all outbound requests.
 // pi-coding-agent's cli.ts sets this, but GSD bypasses that entry point — so we