@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/dist/resources/extensions/shared/gsd-browser-cli.js

@@ -38,6 +38,28 @@ function compareSemverLocal(a, b) {
 function parseGsdBrowserVersion(output) {
     return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
 }
+function splitCommandLine(commandLine) {
+    const parts = commandLine.match(/(?:"[^"]*"|'[^']*'|[^\s"']+)/g) ?? [];
+    return parts.map((part) => {
+        const quote = part[0];
+        if ((quote === '"' || quote === "'") && part.endsWith(quote)) {
+            return part.slice(1, -1);
+        }
+        return part;
+    });
+}
+function buildPathGsdBrowserVersionInvocation(platform) {
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/d", "/s", "/c", "gsd-browser", "--version"] };
+    }
+    return { command: "gsd-browser", args: ["--version"] };
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function resolveExplicitGsdBrowserCliPath(env) {
+    return env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim() || undefined;
+}
 function resolveBundledGsdBrowserPackageVersion() {
     try {
         const requireFromHere = createRequire(import.meta.url);
@@ -49,12 +71,20 @@ function resolveBundledGsdBrowserPackageVersion() {
         return null;
     }
 }
+// The `gsd-browser --version` subprocess result cannot change mid-session (the
+// engine-switch guard forbids restarting with a different engine), and both the
+// availability probe and the launch-config resolution ask for it at session
+// start — memoize so the up-to-2s spawn happens once per process.
+let cachedPathProbeVersion;
 function resolvePathGsdBrowserVersion(env) {
     const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
     if (explicit)
         return parseGsdBrowserVersion(explicit);
+    if (cachedPathProbeVersion !== undefined)
+        return cachedPathProbeVersion;
     try {
-        return parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+        const invocation = buildPathGsdBrowserVersionInvocation(process.platform);
+        cachedPathProbeVersion = parseGsdBrowserVersion(execFileSync(invocation.command, invocation.args, {
             encoding: "utf-8",
             env,
             stdio: ["ignore", "pipe", "ignore"],
@@ -62,18 +92,51 @@ function resolvePathGsdBrowserVersion(env) {
         }));
     }
     catch {
-        return null;
+        cachedPathProbeVersion = null;
+    }
+    return cachedPathProbeVersion;
+}
+function resolveGsdBrowserNativeBinaryPath(launcherPath, platform = process.platform) {
+    const binDir = resolve(launcherPath, "..");
+    const nativeName = platform === "win32" ? "gsd-browser.exe" : "gsd-browser-bin";
+    return resolve(binDir, nativeName);
+}
+function isNodeShLauncher(launcherPath) {
+    try {
+        return readFileSync(launcherPath, "utf-8").startsWith("#!");
+    }
+    catch {
+        // Non-text launchers (native binaries) are runnable without a sibling shim.
+        return false;
     }
 }
+/**
+ * The npm package ships a node launcher that execs `gsd-browser-bin` beside it.
+ * pnpm can skip postinstall, leaving only the launcher — which exits immediately
+ * and surfaces as MCP "Connection closed". Treat that layout as unavailable.
+ */
+function isGsdBrowserPackageLauncherRunnable(launcherPath) {
+    if (!existsSync(launcherPath))
+        return false;
+    const nativePath = resolveGsdBrowserNativeBinaryPath(launcherPath);
+    if (existsSync(nativePath))
+        return true;
+    return !isNodeShLauncher(launcherPath);
+}
 function shouldPreferPathGsdBrowser(env) {
     const pathVersion = resolvePathGsdBrowserVersion(env);
     if (!pathVersion)
         return false;
     const bundledVersion = resolveBundledGsdBrowserPackageVersion();
-    return !bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0;
+    if (!bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0) {
+        return true;
+    }
+    // Same or newer bundled semver still loses when the package launcher cannot run.
+    const bundledLauncher = resolveBundledGsdBrowserLauncherPath(env);
+    return bundledLauncher !== null && !isGsdBrowserPackageLauncherRunnable(bundledLauncher);
 }
-export function resolveBundledGsdBrowserCliPath(env = process.env) {
-    const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+function resolveBundledGsdBrowserLauncherPath(env = process.env) {
+    const explicit = resolveExplicitGsdBrowserCliPath(env);
     if (explicit)
         return explicit;
     try {
@@ -96,6 +159,42 @@ export function resolveBundledGsdBrowserCliPath(env = process.env) {
     }
     return null;
 }
+export function resolveBundledGsdBrowserCliPath(env = process.env) {
+    const launcher = resolveBundledGsdBrowserLauncherPath(env);
+    if (!launcher || !isGsdBrowserPackageLauncherRunnable(launcher))
+        return null;
+    return launcher;
+}
+/**
+ * Cheap availability probe for the gsd-browser CLI: explicit env overrides,
+ * then the bundled @opengsd/gsd-browser binary (filesystem checks only), then
+ * a PATH lookup (one short subprocess, memoized). Used by Browser Automation
+ * Engine resolution to decide whether the managed engine is provable before
+ * preferring it over legacy Playwright. `via` names the provable source, not
+ * necessarily the launch source — resolveGsdBrowserMcpLaunchConfig may still
+ * prefer a newer PATH CLI over the bundled one.
+ */
+export function resolveGsdBrowserCliAvailability(env = process.env) {
+    const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
+    if (explicitCommand) {
+        return { available: true, via: "explicit-env", detail: `GSD_BROWSER_MCP_COMMAND=${explicitCommand}` };
+    }
+    const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
+    if (explicitCliPath) {
+        return existsSync(explicitCliPath)
+            ? { available: true, via: "explicit-env", detail: `CLI at ${explicitCliPath}` }
+            : { available: false, detail: `configured gsd-browser CLI path does not exist: ${explicitCliPath}` };
+    }
+    const bundledCliPath = resolveBundledGsdBrowserCliPath(env);
+    if (bundledCliPath) {
+        return { available: true, via: "bundled", detail: `bundled CLI at ${bundledCliPath}` };
+    }
+    const pathVersion = resolvePathGsdBrowserVersion(env);
+    if (pathVersion) {
+        return { available: true, via: "path", detail: `gsd-browser ${pathVersion} on PATH` };
+    }
+    return { available: false, detail: "no bundled or PATH gsd-browser CLI found" };
+}
 export function buildGsdBrowserSessionName(projectRoot, suffix) {
     const resolvedProjectRoot = resolve(projectRoot);
     const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
@@ -103,13 +202,38 @@ export function buildGsdBrowserSessionName(projectRoot, suffix) {
     const cleanSuffix = suffix ? sanitizeSessionSegment(suffix) : "";
     return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
 }
+/**
+ * Recognize an MCP server config (from .mcp.json / Claude settings) as a
+ * gsd-browser server. Paired with resolveGsdBrowserMcpLaunchConfig: this module
+ * writes the config shape, so it also owns recognizing it. New launch shapes
+ * are taught here, in one place.
+ */
+export function isGsdBrowserMcpServerConfig(config) {
+    if (!isRecord(config))
+        return false;
+    const command = typeof config.command === "string" ? config.command : "";
+    if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
+        return true;
+    }
+    if (isRecord(config.env)) {
+        const env = config.env;
+        if (typeof env.GSD_BROWSER_CLI_PATH === "string"
+            || typeof env.GSD_BROWSER_BIN_PATH === "string"
+            || typeof env.GSD_BROWSER_MCP_COMMAND === "string") {
+            return true;
+        }
+    }
+    const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
+    return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
+}
 export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env, options = {}) {
     const resolvedProjectRoot = resolve(projectRoot);
     const serverName = env.GSD_BROWSER_MCP_NAME?.trim() || GSD_BROWSER_MCP_SERVER_NAME;
     const explicitArgs = parseJsonEnv(env, "GSD_BROWSER_MCP_ARGS");
     const explicitEnv = parseJsonEnv(env, "GSD_BROWSER_MCP_ENV");
-    const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
-    const explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+    const explicitCommandLine = env.GSD_BROWSER_MCP_COMMAND?.trim();
+    const [explicitCommand, ...explicitCommandArgs] = explicitCommandLine ? splitCommandLine(explicitCommandLine) : [];
+    const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
     const preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
     const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
         ? resolveBundledGsdBrowserCliPath(env)
@@ -119,6 +243,9 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
     // profile/cookies persist across pi sessions for the same project. gsd-browser
     // rejects --identity-scope unless --identity-key is also supplied.
     const identityKey = env.GSD_BROWSER_IDENTITY_KEY?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
+    // identity-project must be a safe identifier (no path separators); full paths
+    // cause daemon startup to fail with "invalid name".
+    const identityProject = env.GSD_BROWSER_IDENTITY_PROJECT?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
     const command = explicitCommand
         || explicitCliPath
         || (preferPathCli ? "gsd-browser" : undefined)
@@ -127,6 +254,7 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
     const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
         ? explicitArgs.map(String)
         : [
+            ...explicitCommandArgs,
             ...(bundledCliPath ? [bundledCliPath] : []),
             "mcp",
             "--session",
@@ -136,7 +264,7 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
             "--identity-key",
             identityKey,
             "--identity-project",
-            resolvedProjectRoot,
+            identityProject,
         ];
     const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
     return {
@@ -149,3 +277,23 @@ export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env,
         sessionName,
     };
 }
+/**
+ * CLI invocation that starts the gsd-browser session daemon with the same
+ * session and identity flags as {@link resolveGsdBrowserMcpLaunchConfig}, so
+ * browser UAT can warm Chrome/CDP before the first MCP navigation.
+ */
+export function resolveGsdBrowserDaemonStartInvocation(projectRoot, env = process.env, options = {}) {
+    const launch = resolveGsdBrowserMcpLaunchConfig(projectRoot, env, options);
+    const mcpIndex = launch.args.indexOf("mcp");
+    if (mcpIndex < 0) {
+        throw new Error("gsd-browser launch config is missing mcp subcommand");
+    }
+    const prefix = launch.args.slice(0, mcpIndex);
+    const sessionFlags = launch.args.slice(mcpIndex + 1);
+    return {
+        command: launch.command,
+        args: [...prefix, "daemon", "start", ...sessionFlags],
+        cwd: launch.cwd,
+        ...(launch.env ? { env: launch.env } : {}),
+    };
+}

package/dist/resources/extensions/shared/interview-ui.js

@@ -146,7 +146,7 @@ export async function showInterviewRound(questions, opts, ctx) {
         }
         // External cancellation (e.g. remote channel won the race)
         if (opts.signal) {
-            const onAbort = () => finish({ endInterview: false, answers: {} });
+            const onAbort = () => finish({ endInterview: false, answers: {}, interrupted: true });
             if (opts.signal.aborted) {
                 onAbort();
             }
@@ -800,5 +800,5 @@ export async function showInterviewRound(questions, opts, ctx) {
             invalidate: () => { cachedLines = undefined; },
             handleInput,
         };
-    });
+    }, opts.overlay ? { overlay: true } : undefined);
 }

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

@@ -28,6 +28,7 @@ import { loadEffectiveGSDPreferences } from "../gsd/preferences.js";
 import { emitJournalEvent } from "../gsd/journal.js";
 import { CmuxClient, shellEscape } from "../cmux/index.js";
 import { buildShellEnvAssignments, createSubagentLaunchPlan, isSubagentChildProcess, } from "./launch.js";
+import { resolveSubagentWorktreeCwd } from "./worktree-cwd.js";
 import { SubagentRunStore, createInitialRunRecord, createSubagentTrackingName, deriveRunStatus, } from "./run-store.js";
 export { buildSubagentProcessArgs } from "./launch.js";
 const MAX_PARALLEL_TASKS = 8;
@@ -815,16 +816,19 @@ export default function (pi) {
                 : hasTasks && taskParams.some((task) => (task.context ?? contextMode) === "fork")
                     ? "fork"
                     : contextMode;
-            const dispatchChildren = dispatchAgents.map((agent, index) => ({
-                agent,
-                trackingName: dispatchTrackingNames[index],
-                task: dispatchTasks[index] ?? "",
-                cwd: hasChain
+            const dispatchChildren = dispatchAgents.map((agent, index) => {
+                const rawCwd = hasChain
                     ? chainParams[index]?.cwd
                     : hasTasks
                         ? taskParams[index]?.cwd
-                        : params.cwd,
-            }));
+                        : params.cwd;
+                return {
+                    agent,
+                    trackingName: dispatchTrackingNames[index],
+                    task: dispatchTasks[index] ?? "",
+                    cwd: resolveSubagentWorktreeCwd(ctx.cwd, rawCwd),
+                };
+            });
             try {
                 runStore.create(createInitialRunRecord({
                     runId: dispatchId,
@@ -1023,12 +1027,12 @@ export default function (pi) {
                     void (async () => {
                         let isolation = null;
                         try {
-                            const effectiveCwd = params.cwd ?? ctx.cwd;
+                            const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, params.cwd);
                             if (useIsolation) {
                                 const taskId = crypto.randomUUID();
                                 isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
                             }
-                            const result = await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, undefined, (partial) => {
+                            const result = await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : effectiveCwd, undefined, undefined, (partial) => {
                                 if (partial.details?.results[0])
                                     persistRunResults([partial.details.results[0]]);
                             }, makeDetails("single"), params.model, contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[0], params.thinking);
@@ -1087,7 +1091,8 @@ export default function (pi) {
                                 }
                             }
                         };
-                        const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), step.model || params.model, step.context ?? contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[i], step.thinking || params.thinking);
+                        const stepCwd = resolveSubagentWorktreeCwd(ctx.cwd, step.cwd);
+                        const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, stepCwd, i + 1, signal, chainUpdate, makeDetails("chain"), step.model || params.model, step.context ?? contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[i], step.thinking || params.thinking);
                         results.push(result);
                         persistRunResults(results);
                         const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
@@ -1172,13 +1177,13 @@ export default function (pi) {
                             : runSingleAgent(ctx.cwd, agents, t.agent, t.task, runCwd, undefined, signal, updateParallelResult, makeDetails("parallel"), taskModel, t.context ?? contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[index], taskThinking);
                         const runTask = async () => {
                             let isolation = null;
-                            const effectiveCwd = t.cwd ?? ctx.cwd;
+                            const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, t.cwd);
                             try {
                                 if (useIsolation) {
                                     const taskId = crypto.randomUUID();
                                     isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
                                 }
-                                const result = await executeOnce(isolation ? isolation.workDir : t.cwd);
+                                const result = await executeOnce(isolation ? isolation.workDir : effectiveCwd);
                                 if (isolation && result.exitCode === 0) {
                                     const patches = await isolation.captureDelta();
                                     const mergeResult = patches.length > 0
@@ -1235,7 +1240,7 @@ export default function (pi) {
                     let isolation = null;
                     let mergeResult;
                     try {
-                        const effectiveCwd = params.cwd ?? ctx.cwd;
+                        const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, params.cwd);
                         if (useIsolation) {
                             const taskId = crypto.randomUUID();
                             isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
@@ -1247,8 +1252,8 @@ export default function (pi) {
                                 onUpdate(partial);
                         };
                         const result = cmuxSplitsEnabled
-                            ? await runSingleAgentInCmuxSplit(cmuxClient, "right", ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, singleUpdate, makeDetails("single"), params.model, contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[0], params.thinking)
-                            : await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, singleUpdate, makeDetails("single"), params.model, contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[0], params.thinking);
+                            ? await runSingleAgentInCmuxSplit(cmuxClient, "right", ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : effectiveCwd, undefined, signal, singleUpdate, makeDetails("single"), params.model, contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[0], params.thinking)
+                            : await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : effectiveCwd, undefined, signal, singleUpdate, makeDetails("single"), params.model, contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[0], params.thinking);
                         finalResults = [result];
                         // Capture and merge delta if isolated
                         if (isolation) {

package/dist/resources/extensions/subagent/worktree-cwd.js

@@ -0,0 +1,31 @@
+// Project/App: gsd-pi
+// File Purpose: Pin subagent cwd to the parent milestone worktree so parallel
+// reactive-execute children cannot spawn at the project root.
+import path from "node:path";
+import { isGsdWorktreePath } from "../gsd/worktree-root.js";
+function pathInside(parent, target) {
+    const parentWithSep = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
+    return target === parent || target.startsWith(parentWithSep);
+}
+/**
+ * Resolve the cwd for a subagent child. When the parent is already inside a GSD
+ * milestone worktree, children must stay in that worktree — even if the model
+ * omits `cwd` or passes the project root (the root-write leak vector for
+ * reactive-execute).
+ */
+export function resolveSubagentWorktreeCwd(parentCwd, taskCwd) {
+    const resolvedParent = path.resolve(parentCwd);
+    if (!isGsdWorktreePath(resolvedParent)) {
+        return taskCwd ? path.resolve(resolvedParent, taskCwd) : resolvedParent;
+    }
+    if (!taskCwd) {
+        return resolvedParent;
+    }
+    const resolvedTask = path.isAbsolute(taskCwd)
+        ? path.resolve(taskCwd)
+        : path.resolve(resolvedParent, taskCwd);
+    if (pathInside(resolvedParent, resolvedTask)) {
+        return resolvedTask;
+    }
+    return resolvedParent;
+}

package/dist/resources/shared/claude-runtime-floor.js

@@ -0,0 +1,182 @@
+import { execFileSync as nodeExecFileSync } from 'node:child_process';
+import { existsSync as nodeExistsSync, realpathSync as nodeRealpathSync, readFileSync as nodeReadFileSync } from 'node:fs';
+import { delimiter, dirname, extname, join, resolve as resolvePath } from 'node:path';
+export const CLAUDE_CODE_RUNTIME_FLOOR = '2.1.168';
+export const CLAUDE_CODE_PROVIDER = 'claude-code';
+export const CLAUDE_CODE_PACKAGE = '@anthropic-ai/claude-code';
+const VERSION_TIMEOUT_MS = 5_000;
+function compareVersionTriplets(a, b) {
+    const left = a.split('.').map(Number);
+    const right = b.split('.').map(Number);
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const leftValue = left[index] || 0;
+        const rightValue = right[index] || 0;
+        if (leftValue > rightValue)
+            return 1;
+        if (leftValue < rightValue)
+            return -1;
+    }
+    return 0;
+}
+export function parseClaudeRuntimeVersion(output) {
+    return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+}
+export function isClaudeCodeConfigured(settings) {
+    if (settings.defaultProvider === CLAUDE_CODE_PROVIDER)
+        return true;
+    return settings.defaultModel?.startsWith(`${CLAUDE_CODE_PROVIDER}/`) ?? false;
+}
+function readSettingsFile(path, deps) {
+    try {
+        if (!deps.existsSync(path))
+            return {};
+        const raw = JSON.parse(deps.readFileSync(path, 'utf-8'));
+        return {
+            ...(typeof raw.defaultProvider === 'string' ? { defaultProvider: raw.defaultProvider } : {}),
+            ...(typeof raw.defaultModel === 'string' ? { defaultModel: raw.defaultModel } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export function loadClaudeRuntimeSettings(options) {
+    const deps = {
+        existsSync: options.existsSync ?? nodeExistsSync,
+        readFileSync: options.readFileSync ?? nodeReadFileSync,
+    };
+    const globalSettings = readSettingsFile(join(options.agentDir, 'settings.json'), deps);
+    const projectSettings = options.cwd
+        ? readSettingsFile(join(options.cwd, '.gsd', 'settings.json'), deps)
+        : {};
+    return {
+        ...globalSettings,
+        ...projectSettings,
+    };
+}
+export function buildClaudeSpawnInvocation(command, args, platform = process.platform) {
+    if (platform === 'win32') {
+        return { command: 'cmd', args: ['/c', command, ...args] };
+    }
+    return { command, args };
+}
+export function getClaudeRuntimeCommandCandidates(platform = process.platform) {
+    return platform === 'win32' ? ['claude.cmd', 'claude.exe', 'claude'] : ['claude'];
+}
+function pathEntries(env) {
+    return (env.PATH ?? '')
+        .split(delimiter)
+        .map(entry => entry.trim())
+        .filter(Boolean);
+}
+function executableNames(command, env, platform) {
+    if (platform !== 'win32' || extname(command))
+        return [command];
+    const extensions = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map(value => value.trim().toLowerCase())
+        .filter(Boolean);
+    return [command, ...extensions.map(extension => `${command}${extension}`)];
+}
+export function resolveExecutablePath(command, env = process.env, platform = process.platform, existsSync = nodeExistsSync) {
+    if (dirname(command) !== '.') {
+        return existsSync(command) ? resolvePath(command) : null;
+    }
+    for (const entry of pathEntries(env)) {
+        for (const name of executableNames(command, env, platform)) {
+            const candidate = join(entry, name);
+            if (existsSync(candidate))
+                return resolvePath(candidate);
+        }
+    }
+    return null;
+}
+function realpathOrNull(path, realpathSync) {
+    if (!path)
+        return null;
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+export function probeClaudeRuntime(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const execFileSync = options.execFileSync ?? nodeExecFileSync;
+    const existsSync = options.existsSync ?? nodeExistsSync;
+    const realpathSync = options.realpathSync ?? nodeRealpathSync;
+    for (const command of getClaudeRuntimeCommandCandidates(platform)) {
+        try {
+            const invocation = buildClaudeSpawnInvocation(command, ['--version'], platform);
+            const output = execFileSync(invocation.command, invocation.args, {
+                encoding: 'utf-8',
+                env,
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: VERSION_TIMEOUT_MS,
+            });
+            const version = parseClaudeRuntimeVersion(String(output));
+            if (!version)
+                continue;
+            const displayPath = resolveExecutablePath(command, env, platform, existsSync);
+            return {
+                command,
+                displayPath,
+                realPath: realpathOrNull(displayPath, realpathSync),
+                version,
+            };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function normalizedPath(value) {
+    return (value ?? '').replace(/\\/g, '/').toLowerCase();
+}
+export function inferClaudeRuntimeUpgradeCommand(probe, platform = process.platform) {
+    const combined = `${normalizedPath(probe.displayPath)}\n${normalizedPath(probe.realPath)}`;
+    if (combined.includes('/.pnpm/') && combined.includes('@anthropic-ai+claude-code@')) {
+        return { command: `pnpm add -g ${CLAUDE_CODE_PACKAGE}@latest`, source: 'pnpm' };
+    }
+    if (combined.includes('/node_modules/') && combined.includes('/@anthropic-ai/claude-code/')) {
+        return { command: `npm install -g ${CLAUDE_CODE_PACKAGE}@latest`, source: 'npm' };
+    }
+    if (combined.includes('/.bun/') || combined.includes('/bun/install/global/')) {
+        return { command: `bun add -g ${CLAUDE_CODE_PACKAGE}@latest`, source: 'bun' };
+    }
+    if (combined.includes('/homebrew/') || combined.includes('/caskroom/claude-code')) {
+        return { command: 'brew upgrade claude-code', source: 'homebrew' };
+    }
+    if (platform === 'win32' && (combined.includes('/winget/') || combined.includes('/anthropic.claudecode'))) {
+        return { command: 'winget upgrade Anthropic.ClaudeCode', source: 'winget' };
+    }
+    if (combined.includes('claude code.app') || combined.includes('/anthropic/claude')) {
+        return { command: null, source: 'native' };
+    }
+    return { command: null, source: 'unknown' };
+}
+export function formatClaudeRuntimeFloorAdvisory(probe, floor = CLAUDE_CODE_RUNTIME_FLOOR, platform = process.platform) {
+    const upgrade = inferClaudeRuntimeUpgradeCommand(probe, platform);
+    const pathText = probe.displayPath ? ` at ${probe.displayPath}` : '';
+    const base = `Warning: Claude Code Runtime is below GSD's validated floor: detected v${probe.version}, expected >= v${floor}. ` +
+        'GSD can still update, but older Claude Code may silently reduce output quality or miss model/runtime features.';
+    if (upgrade.command) {
+        return `${base} Upgrade the claude binary${pathText} with: ${upgrade.command}`;
+    }
+    return (`${base} Upgrade the claude binary${pathText} using the method you installed it with. ` +
+        'See docs/user-docs/claude-code-subscription.md#upgrade-claude-code.');
+}
+export function buildClaudeRuntimeFloorAdvisory(options) {
+    const settings = loadClaudeRuntimeSettings(options);
+    if (!isClaudeCodeConfigured(settings))
+        return null;
+    const probe = probeClaudeRuntime(options);
+    if (!probe)
+        return null;
+    if (compareVersionTriplets(probe.version, CLAUDE_CODE_RUNTIME_FLOOR) >= 0)
+        return null;
+    return formatClaudeRuntimeFloorAdvisory(probe, CLAUDE_CODE_RUNTIME_FLOOR, options.platform);
+}