gsd-pi 2.73.1-dev.6f61020 → 2.73.1-dev.a2eb797

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');
     }
-    return flags;
+    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');
+    }
+    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,16 +123,18 @@ 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');
@@ -170,21 +146,7 @@ exitIfManagedResourcesAreNewer(agentDir);
 // 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 +169,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 +182,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 +257,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 +420,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 +512,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 +557,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 +606,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/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) {

package/dist/onboarding.js

@@ -71,8 +71,8 @@ const OTHER_PROVIDERS = [
 ];
 // ─── Dynamic imports ──────────────────────────────────────────────────────────
 /**
- * Dynamically import @clack/prompts and picocolors.
- * Dynamic import with fallback so the module doesn't crash if they're missing.
+ * Dynamically import @clack/prompts.
+ * Dynamic import with fallback so the module doesn't crash if it's missing.
  */
 async function loadClack() {
     try {
@@ -82,10 +82,23 @@ async function loadClack() {
         throw new Error('[gsd] @clack/prompts not found — onboarding wizard requires this dependency');
     }
 }
+/**
+ * Build the PicoModule color surface from chalk. Chalk is already a
+ * dependency of the CLI; this adapter keeps the onboarding call sites stable
+ * while removing the redundant picocolors dep.
+ */
 async function loadPico() {
     try {
-        const mod = await import('picocolors');
-        return mod.default ?? mod;
+        const { default: chalk } = await import('chalk');
+        return {
+            cyan: (s) => chalk.cyan(s),
+            green: (s) => chalk.green(s),
+            yellow: (s) => chalk.yellow(s),
+            dim: (s) => chalk.dim(s),
+            bold: (s) => chalk.bold(s),
+            red: (s) => chalk.red(s),
+            reset: (s) => chalk.reset(s),
+        };
     }
     catch {
         // Fallback: return identity functions
@@ -105,9 +118,29 @@ function openBrowser(url) {
         execFile(cmd, [url], () => { });
     }
 }
-/** Check if an error is a clack cancel signal */
-function isCancelError(p, err) {
-    return p.isCancel(err);
+/** Sentinel returned by runStep when the user cancels — tells the caller
+ *  to abort the entire wizard. */
+const STEP_CANCELLED = Symbol('step-cancelled');
+/**
+ * Run a single onboarding step with shared error handling:
+ *   - user cancel (Ctrl+C) → p.cancel(cancelMessage), returns STEP_CANCELLED
+ *   - other error → p.log.warn + optional info follow-up, returns null
+ *   - success → the step's return value
+ */
+async function runStep(p, warnLabel, fn, opts = {}) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (p.isCancel(err)) {
+            p.cancel(opts.cancelMessage ?? 'Setup cancelled.');
+            return STEP_CANCELLED;
+        }
+        p.log.warn(`${warnLabel}: ${err instanceof Error ? err.message : String(err)}`);
+        if (opts.errorInfo)
+            p.log.info(opts.errorInfo);
+        return null;
+    }
 }
 // ─── Public API ───────────────────────────────────────────────────────────────
 /**
@@ -160,55 +193,28 @@ export async function runOnboarding(authStorage) {
     process.stderr.write(renderLogo(pc.cyan));
     p.intro(pc.bold('Welcome to GSD — let\'s get you set up'));
     // ── LLM Provider Selection ────────────────────────────────────────────────
-    let llmConfigured = false;
-    try {
-        llmConfigured = await runLlmStep(p, pc, authStorage);
-    }
-    catch (err) {
-        // User cancelled (Ctrl+C in clack throws) or unexpected error
-        if (isCancelError(p, err)) {
-            p.cancel('Setup cancelled — you can run /login inside GSD later.');
-            return;
-        }
-        p.log.warn(`LLM setup failed: ${err instanceof Error ? err.message : String(err)}`);
-        p.log.info('You can configure your LLM provider later with /login inside GSD.');
-    }
+    const llmResult = await runStep(p, 'LLM setup failed', () => runLlmStep(p, pc, authStorage), {
+        cancelMessage: 'Setup cancelled — you can run /login inside GSD later.',
+        errorInfo: 'You can configure your LLM provider later with /login inside GSD.',
+    });
+    if (llmResult === STEP_CANCELLED)
+        return;
+    const llmConfigured = llmResult ?? false;
     // ── Web Search Provider ──────────────────────────────────────────────────
-    let searchConfigured = null;
-    try {
-        searchConfigured = await runWebSearchStep(p, pc, authStorage, llmConfigured);
-    }
-    catch (err) {
-        if (isCancelError(p, err)) {
-            p.cancel('Setup cancelled.');
-            return;
-        }
-        p.log.warn(`Web search setup failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const searchResult = await runStep(p, 'Web search setup failed', () => runWebSearchStep(p, pc, authStorage, llmConfigured));
+    if (searchResult === STEP_CANCELLED)
+        return;
+    const searchConfigured = searchResult;
     // ── Remote Questions ─────────────────────────────────────────────────────
-    let remoteConfigured = null;
-    try {
-        remoteConfigured = await runRemoteQuestionsStep(p, pc, authStorage);
-    }
-    catch (err) {
-        if (isCancelError(p, err)) {
-            p.cancel('Setup cancelled.');
-            return;
-        }
-        p.log.warn(`Remote questions setup failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const remoteResult = await runStep(p, 'Remote questions setup failed', () => runRemoteQuestionsStep(p, pc, authStorage));
+    if (remoteResult === STEP_CANCELLED)
+        return;
+    const remoteConfigured = remoteResult;
     // ── Tool API Keys ─────────────────────────────────────────────────────────
-    let toolKeyCount = 0;
-    try {
-        toolKeyCount = await runToolKeysStep(p, pc, authStorage);
-    }
-    catch (err) {
-        if (isCancelError(p, err)) {
-            p.cancel('Setup cancelled.');
-            return;
-        }
-        p.log.warn(`Tool key setup failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const toolResult = await runStep(p, 'Tool key setup failed', () => runToolKeysStep(p, pc, authStorage));
+    if (toolResult === STEP_CANCELLED)
+        return;
+    const toolKeyCount = toolResult ?? 0;
     // ── Summary ───────────────────────────────────────────────────────────────
     const summaryLines = [];
     if (llmConfigured) {