gsd-pi 2.73.1 → 2.74.0-dev.0306a2e

package/dist/cli-web-branch.d.ts

@@ -1,9 +1,10 @@
 import { launchWebMode, stopWebMode, type WebModeLaunchStatus, type WebModeStopOptions, type WebModeStopResult } from './web-mode.js';
 export interface CliFlags {
-    mode?: 'text' | 'json' | 'rpc';
+    mode?: 'text' | 'json' | 'rpc' | 'mcp';
     print?: boolean;
     continue?: boolean;
     noSession?: boolean;
+    worktree?: boolean | string;
     model?: string;
     listModels?: string | true;
     extensions: string[];
@@ -19,8 +20,8 @@ export interface CliFlags {
     webPort?: number;
     /** Additional allowed origins for CORS: `--allowed-origins http://192.168.1.10:8080` */
     webAllowedOrigins?: string[];
-    help?: boolean;
-    version?: boolean;
+    /** Set by `gsd sessions` when the user picks a specific session to resume */
+    _selectedSessionPath?: string;
 }
 type WritableLike = Pick<typeof process.stderr, 'write'>;
 export interface RunWebCliBranchDeps {

package/dist/cli-web-branch.js

@@ -10,7 +10,7 @@ export function parseCliArgs(argv) {
         const arg = args[i];
         if (arg === '--mode' && i + 1 < args.length) {
             const mode = args[++i];
-            if (mode === 'text' || mode === 'json' || mode === 'rpc')
+            if (mode === 'text' || mode === 'json' || mode === 'rpc' || mode === 'mcp')
                 flags.mode = mode;
         }
         else if (arg === '--print' || arg === '-p') {
@@ -22,6 +22,15 @@ export function parseCliArgs(argv) {
         else if (arg === '--no-session') {
             flags.noSession = true;
         }
+        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 === '--web') {
             flags.web = true;
             // Peek at next arg — if it looks like a path (not another flag), capture it
@@ -58,12 +67,6 @@ export function parseCliArgs(argv) {
         else if (arg === '--list-models') {
             flags.listModels = (i + 1 < args.length && !args[i + 1].startsWith('-')) ? args[++i] : true;
         }
-        else if (arg === '--version' || arg === '-v') {
-            flags.version = true;
-        }
-        else if (arg === '--help' || arg === '-h') {
-            flags.help = true;
-        }
         else if (!arg.startsWith('--') && !arg.startsWith('-')) {
             flags.messages.push(arg);
         }

package/dist/cli.js

@@ -5,13 +5,14 @@ import { agentDir, sessionsDir, authFilePath } from './app-paths.js';
 import { initResources, buildResourceLoader, getNewerManagedResourceVersion } from './resource-loader.js';
 import { ensureManagedTools } from './tool-bootstrap.js';
 import { loadStoredEnvKeys } from './wizard.js';
-import { migratePiCredentials, getPiDefaultModelAndProvider } from './pi-migration.js';
+import { migratePiCredentials } from './pi-migration.js';
 import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
 import { applySecurityOverrides } from './security-overrides.js';
-import { parseCliArgs as parseWebCliArgs, runWebCliBranch, migrateLegacyFlatSessions, } from './cli-web-branch.js';
+import { validateConfiguredModel } from './startup-model-validation.js';
+import { parseCliArgs, runWebCliBranch, migrateLegacyFlatSessions, } from './cli-web-branch.js';
 import { stopWebMode } from './web-mode.js';
 import { getProjectSessionsDir } from './project-sessions.js';
 import { markStartup, printStartupTimings } from './startup-timings.js';
@@ -36,112 +37,85 @@ function exitIfManagedResourcesAreNewer(currentAgentDir) {
         `[gsd] Run ${chalk.bold('npm install -g gsd-pi@latest')} or ${chalk.bold('gsd update')}, then try again.\n`);
     process.exit(1);
 }
-function parseCliArgs(argv) {
-    const flags = { extensions: [], messages: [] };
-    const args = argv.slice(2); // skip node + script
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === '--mode' && i + 1 < args.length) {
-            const m = args[++i];
-            if (m === 'text' || m === 'json' || m === 'rpc' || m === 'mcp')
-                flags.mode = m;
-        }
-        else if (arg === '--print' || arg === '-p') {
-            flags.print = true;
-        }
-        else if (arg === '--continue' || arg === '-c') {
-            flags.continue = true;
-        }
-        else if (arg === '--no-session') {
-            flags.noSession = true;
-        }
-        else if (arg === '--model' && i + 1 < args.length) {
-            flags.model = args[++i];
-        }
-        else if (arg === '--extension' && i + 1 < args.length) {
-            flags.extensions.push(args[++i]);
-        }
-        else if (arg === '--append-system-prompt' && i + 1 < args.length) {
-            flags.appendSystemPrompt = args[++i];
-        }
-        else if (arg === '--tools' && i + 1 < args.length) {
-            flags.tools = args[++i].split(',');
-        }
-        else if (arg === '--list-models') {
-            flags.listModels = (i + 1 < args.length && !args[i + 1].startsWith('-')) ? args[++i] : true;
-        }
-        else if (arg === '--version' || arg === '-v') {
-            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);
-        }
-        else if (arg === '--web') {
-            flags.web = true;
-            // Capture optional project path after --web (not a flag)
-            if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
-                flags.webPath = args[++i];
-            }
-        }
-        else if (!arg.startsWith('--') && !arg.startsWith('-')) {
-            flags.messages.push(arg);
-        }
+// ---------------------------------------------------------------------------
+// Shared helpers used by both the print and interactive code paths
+// ---------------------------------------------------------------------------
+/**
+ * Print the non-interactive-mode error and exit. Called both from the early
+ * TTY gate (before heavy init) and from the interactive-mode TTY gate right
+ * before `InteractiveMode.run()`. The `includeWebHint` variant also lists
+ * `--web` and `headless` as alternatives.
+ */
+function printNonTtyErrorAndExit(missing, includeWebHint) {
+    const suffix = missing ? ` but ${missing} not a TTY` : '';
+    process.stderr.write(`[gsd] Error: Interactive mode requires a terminal (TTY)${suffix}.\n`);
+    process.stderr.write('[gsd] Non-interactive alternatives:\n');
+    process.stderr.write('[gsd]   gsd auto                       Auto-mode (pipeable, no TUI)\n');
+    process.stderr.write('[gsd]   gsd --print "your message"     Single-shot prompt\n');
+    if (includeWebHint) {
+        process.stderr.write('[gsd]   gsd --web [path]               Browser-only web mode\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');
+    if (includeWebHint) {
+        process.stderr.write('[gsd]   gsd headless                   Auto-mode without TUI\n');
     }
-    return flags;
+    process.exit(1);
 }
 /**
- * Validate the configured default model against the registry and reset it if
- * it no longer exists.  Must run AFTER extensions have registered their
- * providers so that extension models (e.g. pi-claude-cli) are visible.
+ * Print extension load/conflict errors from an extensions result. Downgrades
+ * conflicts with built-in tools to warnings (#1347).
  */
-function validateConfiguredModel(modelRegistry, settingsManager) {
-    const configuredProvider = settingsManager.getDefaultProvider();
-    const configuredModel = settingsManager.getDefaultModel();
-    const allModels = modelRegistry.getAll();
-    const availableModels = modelRegistry.getAvailable();
-    const configuredExists = configuredProvider && configuredModel &&
-        allModels.some((m) => m.provider === configuredProvider && m.id === configuredModel);
-    const configuredAvailable = configuredProvider && configuredModel &&
-        availableModels.some((m) => m.provider === configuredProvider && m.id === configuredModel);
-    if (!configuredModel || !configuredExists) {
-        // Model not configured at all, or removed from registry — pick a fallback.
-        // Only fires when the model is genuinely unknown (not just temporarily unavailable).
-        const piDefault = getPiDefaultModelAndProvider();
-        const preferred = (piDefault
-            ? availableModels.find((m) => m.provider === piDefault.provider && m.id === piDefault.model)
-            : undefined) ||
-            availableModels.find((m) => m.provider === 'openai' && m.id === 'gpt-5.4') ||
-            availableModels.find((m) => m.provider === 'openai') ||
-            availableModels.find((m) => m.provider === 'anthropic' && m.id === 'claude-opus-4-6') ||
-            availableModels.find((m) => m.provider === 'anthropic' && m.id.includes('opus')) ||
-            availableModels.find((m) => m.provider === 'anthropic') ||
-            availableModels[0];
-        if (preferred) {
-            settingsManager.setDefaultModelAndProvider(preferred.provider, preferred.id);
-        }
+function printExtensionErrors(errors) {
+    for (const err of errors) {
+        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`);
+    }
+}
+/**
+ * Re-apply the validated model to the session when `createAgentSession()`
+ * reports that it had to use a fallback. Prevents silently overriding the
+ * persisted model of resumed conversations (#3534).
+ */
+async function reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, fallbackMessage) {
+    if (!fallbackMessage)
+        return;
+    const validatedProvider = settingsManager.getDefaultProvider();
+    const validatedModelId = settingsManager.getDefaultModel();
+    if (!validatedProvider || !validatedModelId)
+        return;
+    const correctModel = modelRegistry.getAvailable()
+        .find((m) => m.provider === validatedProvider && m.id === validatedModelId);
+    if (!correctModel)
+        return;
+    try {
+        await session.setModel(correctModel);
     }
-    if (settingsManager.getDefaultThinkingLevel() !== 'off' && !configuredExists) {
-        settingsManager.setDefaultThinkingLevel('off');
+    catch {
+        // Provider not ready — leave session on its current model
     }
 }
 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.
-async function ensureRtkBootstrap() {
-    if (ensureRtkBootstrap._done)
-        return;
+// `gsd [subcommand] --help` / `-h` — print help before any subcommand runs.
+// loader.ts only catches --help/-h as the *first* arg; here we handle the
+// case where it appears later (e.g. `gsd update --help`, `gsd --foo --help`).
+// Prefer subcommand-specific help when the first positional is a known
+// subcommand, otherwise fall back to general help.
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    const helpSubcommand = cliFlags.messages[0];
+    const version = process.env.GSD_VERSION || '0.0.0';
+    if (!helpSubcommand || !printSubcommandHelp(helpSubcommand, version)) {
+        printHelp(version);
+    }
+    process.exit(0);
+}
+// RTK bootstrap — runs once per process, memoized via a module-level promise
+// so concurrent callers await the same initialization.
+let rtkBootstrapPromise;
+async function doRtkBootstrap() {
     // 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).
@@ -149,42 +123,115 @@ async function ensureRtkBootstrap() {
         const prefs = loadEffectiveGSDPreferences();
         const rtkEnabled = prefs?.preferences.experimental?.rtk === true;
         if (!rtkEnabled) {
-            process.env[GSD_RTK_DISABLED_ENV] = "1";
+            process.env[GSD_RTK_DISABLED_ENV] = '1';
         }
     }
     const rtkStatus = await bootstrapRtk();
-    ensureRtkBootstrap._done = true;
     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') {
     const { runUpdate } = await import('./update-cmd.js');
     await runUpdate();
     process.exit(0);
 }
+// ---------------------------------------------------------------------------
+// Graph subcommand — `gsd graph build|status|query|diff`
+// ---------------------------------------------------------------------------
+if (cliFlags.messages[0] === 'graph') {
+    const sub = cliFlags.messages[1];
+    const { buildGraph, writeGraph, graphStatus, graphQuery, graphDiff, resolveGsdRoot } = await import('@gsd-build/mcp-server');
+    const projectDir = process.cwd();
+    const gsdRoot = resolveGsdRoot(projectDir);
+    if (!sub || sub === 'build') {
+        try {
+            const graph = await buildGraph(projectDir);
+            await writeGraph(gsdRoot, graph);
+            process.stdout.write(`Graph built: ${graph.nodes.length} nodes, ${graph.edges.length} edges\n`);
+        }
+        catch (err) {
+            process.stderr.write(`[gsd] graph build failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    }
+    else if (sub === 'status') {
+        try {
+            const result = await graphStatus(projectDir);
+            if (!result.exists) {
+                process.stdout.write('Graph: not built yet. Run: gsd graph build\n');
+            }
+            else {
+                process.stdout.write(`Graph status:\n`);
+                process.stdout.write(`  exists:    ${result.exists}\n`);
+                process.stdout.write(`  nodes:     ${result.nodeCount}\n`);
+                process.stdout.write(`  edges:     ${result.edgeCount}\n`);
+                process.stdout.write(`  stale:     ${result.stale}\n`);
+                process.stdout.write(`  ageHours:  ${result.ageHours !== undefined ? result.ageHours.toFixed(2) : 'n/a'}\n`);
+                process.stdout.write(`  lastBuild: ${result.lastBuild ?? 'n/a'}\n`);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[gsd] graph status failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    }
+    else if (sub === 'query') {
+        const term = cliFlags.messages[2];
+        if (!term) {
+            process.stderr.write('Usage: gsd graph query <term>\n');
+            process.exit(1);
+        }
+        try {
+            const result = await graphQuery(projectDir, term);
+            if (result.nodes.length === 0) {
+                process.stdout.write(`No nodes found for term: "${term}"\n`);
+            }
+            else {
+                process.stdout.write(`Query results for "${term}" (${result.nodes.length} nodes, ${result.edges.length} edges):\n`);
+                for (const node of result.nodes) {
+                    process.stdout.write(`  [${node.type}] ${node.label} (${node.confidence})\n`);
+                }
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[gsd] graph query failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    }
+    else if (sub === 'diff') {
+        try {
+            const result = await graphDiff(projectDir);
+            process.stdout.write(`Graph diff:\n`);
+            process.stdout.write(`  nodes added:    ${result.nodes.added.length}\n`);
+            process.stdout.write(`  nodes removed:  ${result.nodes.removed.length}\n`);
+            process.stdout.write(`  nodes changed:  ${result.nodes.changed.length}\n`);
+            process.stdout.write(`  edges added:    ${result.edges.added.length}\n`);
+            process.stdout.write(`  edges removed:  ${result.edges.removed.length}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`[gsd] graph diff failed: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    }
+    else {
+        process.stderr.write(`Unknown graph command: ${sub}\n`);
+        process.stderr.write('Commands: build, status, query <term>, diff\n');
+        process.exit(1);
+    }
+    process.exit(0);
+}
 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 && !cliFlags.web) {
-    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 auto                       Auto-mode (pipeable, no TUI)\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')) {
-    if (printSubcommandHelp(subcommand, process.env.GSD_VERSION || '0.0.0')) {
-        process.exit(0);
-    }
+    printNonTtyErrorAndExit(undefined, false);
 }
 const packageCommand = await runPackageCommand({
     appName: 'gsd',
@@ -207,8 +254,7 @@ if (cliFlags.messages[0] === 'config') {
 }
 // `gsd web stop [path|all]` — stop web server before anything else
 if (cliFlags.messages[0] === 'web' && cliFlags.messages[1] === 'stop') {
-    const webFlags = parseWebCliArgs(process.argv);
-    const webBranch = await runWebCliBranch(webFlags, {
+    const webBranch = await runWebCliBranch(cliFlags, {
         stopWebMode,
         stderr: process.stderr,
         baseSessionsDir: sessionsDir,
@@ -221,8 +267,7 @@ if (cliFlags.messages[0] === 'web' && cliFlags.messages[1] === 'stop') {
 // `gsd --web [path]` or `gsd web [start] [path]` — launch browser-only web mode
 if (cliFlags.web || (cliFlags.messages[0] === 'web' && cliFlags.messages[1] !== 'stop')) {
     await ensureRtkBootstrap();
-    const webFlags = parseWebCliArgs(process.argv);
-    const webBranch = await runWebCliBranch(webFlags, {
+    const webBranch = await runWebCliBranch(cliFlags, {
         stderr: process.stderr,
         baseSessionsDir: sessionsDir,
         agentDir,
@@ -297,21 +342,23 @@ if (cliFlags.messages[0] === 'headless') {
     await runHeadless(parseHeadlessArgs(process.argv));
     process.exit(0);
 }
+/**
+ * Run a headless command by invoking the headless entrypoint with a synthetic
+ * argv. Shared by the `auto` shorthand (#2732) and the auto-piped-stdout
+ * redirect so they use the same bootstrap + dynamic-import dance.
+ */
+async function runHeadlessFromAuto(headlessArgs) {
+    await ensureRtkBootstrap();
+    const { runHeadless, parseHeadlessArgs } = await import('./headless.js');
+    const argv = [process.argv[0], process.argv[1], 'headless', ...headlessArgs];
+    await runHeadless(parseHeadlessArgs(argv));
+    process.exit(0);
+}
 // `gsd auto [args...]` — shorthand for `gsd headless auto [args...]` (#2732)
 // Without this, `gsd auto` falls through to the interactive TUI which hangs
 // when stdin/stdout are piped (non-TTY environments).
 if (cliFlags.messages[0] === 'auto') {
-    await ensureRtkBootstrap();
-    const { runHeadless, parseHeadlessArgs } = await import('./headless.js');
-    // Rewrite argv so parseHeadlessArgs sees: [node, gsd, headless, auto, ...rest]
-    const rewrittenArgv = [
-        process.argv[0],
-        process.argv[1],
-        'headless',
-        ...cliFlags.messages, // ['auto', ...extra args]
-    ];
-    await runHeadless(parseHeadlessArgs(rewrittenArgv));
-    process.exit(0);
+    await runHeadlessFromAuto(cliFlags.messages);
 }
 // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
@@ -458,37 +505,8 @@ 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 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`);
-        }
-    }
-    // Validate configured model now that extension providers are registered.
-    // Must run after createAgentSession() which flushes pendingProviderRegistrations
-    // so extension models (e.g. pi-claude-cli) are visible in the registry.
-    validateConfiguredModel(modelRegistry, settingsManager);
+    await reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, modelFallbackMessage);
+    printExtensionErrors(extensionsResult.errors);
     // Apply --model override if specified
     if (cliFlags.model) {
         const available = modelRegistry.getAvailable();
@@ -579,11 +597,8 @@ if (!cliFlags.worktree && !isPrintMode) {
 // which handles non-interactive output gracefully.
 // ---------------------------------------------------------------------------
 if (cliFlags.messages[0] === 'auto' && !process.stdout.isTTY) {
-    await ensureRtkBootstrap();
-    const { runHeadless, parseHeadlessArgs } = await import('./headless.js');
     process.stderr.write('[gsd] stdout is not a terminal — running auto-mode in headless mode.\n');
-    await runHeadless(parseHeadlessArgs(['node', 'gsd', 'headless', ...cliFlags.messages.slice(1)]));
-    process.exit(0);
+    await runHeadlessFromAuto(cliFlags.messages.slice(1));
 }
 // ---------------------------------------------------------------------------
 // Interactive mode — normal TTY session
@@ -627,36 +642,8 @@ 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 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`);
-    }
-}
-// Validate configured model now that extension providers are registered.
-// Must run after createAgentSession() which flushes pendingProviderRegistrations
-// so extension models (e.g. pi-claude-cli) are visible in the registry.
-validateConfiguredModel(modelRegistry, settingsManager);
+await reapplyValidatedModelOnFallback(session, modelRegistry, settingsManager, interactiveFallbackMsg);
+printExtensionErrors(extensionsResult.errors);
 // Restore scoped models from settings on startup.
 // The upstream InteractiveMode reads enabledModels from settings when /scoped-models is opened,
 // but doesn't apply them to the session at startup — so Ctrl+P cycles all models instead of
@@ -704,16 +691,7 @@ if (!process.stdin.isTTY || !process.stdout.isTTY) {
         : !process.stdin.isTTY
             ? 'stdin is'
             : 'stdout is';
-    process.stderr.write(`[gsd] Error: Interactive mode requires a terminal (TTY) but ${missing} not a TTY.\n`);
-    process.stderr.write('[gsd] Non-interactive alternatives:\n');
-    process.stderr.write('[gsd]   gsd auto                       Auto-mode (pipeable, no TUI)\n');
-    process.stderr.write('[gsd]   gsd --print "your message"     Single-shot prompt\n');
-    process.stderr.write('[gsd]   gsd --web [path]               Browser-only web mode\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.stderr.write('[gsd]   gsd headless                   Auto-mode without TUI\n');
-    process.exit(1);
+    printNonTtyErrorAndExit(missing, true);
 }
 // Welcome screen — shown on every fresh interactive session before TUI takes over.
 // Skip when the first-run banner was already printed in loader.ts (prevents double banner).

package/dist/headless-query.js

@@ -33,7 +33,9 @@ async function loadExtensionModules() {
     const dispatchModule = await jiti.import(gsdExtensionPath('auto-dispatch.ts'), {});
     const sessionModule = await jiti.import(gsdExtensionPath('session-status-io.ts'), {});
     const prefsModule = await jiti.import(gsdExtensionPath('preferences.ts'), {});
+    const autoStartModule = await jiti.import(gsdExtensionPath('auto-start.ts'), {});
     return {
+        openProjectDbIfPresent: autoStartModule.openProjectDbIfPresent,
         deriveState: stateModule.deriveState,
         resolveDispatch: dispatchModule.resolveDispatch,
         readAllSessionStatuses: sessionModule.readAllSessionStatuses,
@@ -42,7 +44,8 @@ async function loadExtensionModules() {
 }
 // ─── Implementation ─────────────────────────────────────────────────────────
 export async function handleQuery(basePath) {
-    const { deriveState, resolveDispatch, readAllSessionStatuses, loadEffectiveGSDPreferences } = await loadExtensionModules();
+    const { openProjectDbIfPresent, deriveState, resolveDispatch, readAllSessionStatuses, loadEffectiveGSDPreferences, } = await loadExtensionModules();
+    await openProjectDbIfPresent(basePath);
     const state = await deriveState(basePath);
     // Derive next dispatch action
     let next;

package/dist/help-text.js

@@ -84,6 +84,28 @@ const SUBCOMMAND_HELP = {
         '  gsd worktree remove old-branch      Remove a specific worktree',
         '  gsd worktree remove old-branch --force  Remove even with unmerged changes',
     ].join('\n'),
+    graph: [
+        'Usage: gsd graph <subcommand> [options]',
+        '',
+        'Manage the GSD project knowledge graph. Reads .gsd/ artifacts and builds',
+        'a queryable graph of milestones, slices, tasks, rules, patterns, and lessons.',
+        '',
+        'Subcommands:',
+        '  build   Parse .gsd/ artifacts (STATE.md, milestone ROADMAPs, slice PLANs,',
+        '          KNOWLEDGE.md) and write .gsd/graphs/graph.json atomically.',
+        '  query   Search graph nodes by term (BFS from seed matches, budget-trimmed).',
+        '          Returns matching nodes and reachable edges within the token budget.',
+        '  status  Show whether graph.json exists, its age, node/edge counts, and',
+        '          whether it is stale (built more than 24 hours ago).',
+        '  diff    Compare current graph.json with .last-build-snapshot.json.',
+        '          Returns added, removed, and changed nodes and edges.',
+        '',
+        'Examples:',
+        '  gsd graph build                        Build the graph from .gsd/ artifacts',
+        '  gsd graph status                       Check graph age and node/edge counts',
+        '  gsd graph query auth                   Find nodes related to "auth"',
+        '  gsd graph diff                         Show changes since last snapshot',
+    ].join('\n'),
     headless: [
         'Usage: gsd headless [flags] [command] [args...]',
         '',
@@ -165,6 +187,7 @@ export function printHelp(version) {
     process.stdout.write('  worktree <cmd>           Manage worktrees (list, merge, clean, remove)\n');
     process.stdout.write('  auto [args]              Run auto-mode without TUI (pipeable)\n');
     process.stdout.write('  headless [cmd] [args]    Run /gsd commands without TUI (default: auto)\n');
+    process.stdout.write('  graph <subcommand>       Manage knowledge graph (build, query, status, diff)\n');
     process.stdout.write('\nRun gsd <subcommand> --help for subcommand-specific help.\n');
 }
 export function printSubcommandHelp(subcommand, version) {

package/dist/logo.d.ts

@@ -10,7 +10,7 @@ export declare const GSD_LOGO: readonly string[];
 /**
  * Render the logo block with a color function applied to each line.
  *
- * @param color — e.g. `(s) => `\x1b[36m${s}\x1b[0m`` or picocolors.cyan
+ * @param color — e.g. `(s) => `\x1b[36m${s}\x1b[0m`` or chalk.cyan
  * @returns Ready-to-write string with leading/trailing newlines.
  */
 export declare function renderLogo(color: (s: string) => string): string;

package/dist/logo.js

@@ -17,7 +17,7 @@ export const GSD_LOGO = [
 /**
  * Render the logo block with a color function applied to each line.
  *
- * @param color — e.g. `(s) => `\x1b[36m${s}\x1b[0m`` or picocolors.cyan
+ * @param color — e.g. `(s) => `\x1b[36m${s}\x1b[0m`` or chalk.cyan
  * @returns Ready-to-write string with leading/trailing newlines.
  */
 export function renderLogo(color) {