gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

package/src/resources/extensions/ollama/model-capabilities.ts

@@ -56,10 +56,44 @@ const KNOWN_MODELS: Array<[pattern: string, caps: ModelCapability]> = [
 	["llama2", { contextWindow: 4096, maxTokens: 4096, ollamaOptions: { num_ctx: 4096 } }],
 
 	// ─── Qwen family ────────────────────────────────────────────────────
+	// Long-variant entries MUST appear before the bare `qwen3` base —
+	// `baseName.startsWith(pattern)` returns true for `qwen3.5`/`qwen3-coder`/
+	// `qwen3-next` against `qwen3`, and the first match wins (#4991).
+	// ref: qwen3-next 1M ctx — https://qwen.ai/blog?id=qwen3-next
+	["qwen3-next", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
+	// ref: qwen3-coder 256K ctx — https://qwenlm.github.io/blog/qwen3-coder/
+	["qwen3-coder", { contextWindow: 262144, maxTokens: 32768, ollamaOptions: { num_ctx: 262144 } }],
+	// ref: qwen3.5 / qwen3.6 1M ctx — Ollama Cloud release notes
+	["qwen3.6", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
+	["qwen3.5", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
 	["qwen3", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
 	["qwen2.5", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
 	["qwen2", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
 
+	// ─── GLM family (Z.ai, Ollama Cloud) ────────────────────────────────
+	// ref: glm 4.6 / 5.x 200K ctx — https://docs.z.ai/devpack/using5.1
+	// Long-variant entries before bare `glm-5` / `glm-4` would-be bases to
+	// avoid prefix shadowing (#4991).
+	["glm-5.1", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+	["glm-5", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+	["glm-4.6", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+	["glm-4", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }],
+
+	// ─── Kimi K2 (Moonshot, Ollama Cloud) ──────────────────────────────
+	// ref: kimi-k2 256K ctx — https://platform.moonshot.ai/docs
+	// Same shadowing concern: kimi-k2-thinking and kimi-k2.{5,6} must
+	// match before any future bare `kimi-k2` entry (#4991).
+	["kimi-k2-thinking", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+	["kimi-k2.6", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+	["kimi-k2.5", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+	["kimi-k2", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+
+	// ─── MiniMax M2 (Ollama Cloud) ─────────────────────────────────────
+	// ref: minimax-m2 1M ctx — https://www.minimax.io/news/minimax-m2
+	["minimax-m2.7", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+	["minimax-m2.5", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+	["minimax-m2", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+
 	// ─── Gemma family ───────────────────────────────────────────────────
 	["gemma3", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }],
 	["gemma2", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }],

package/src/resources/extensions/ollama/ollama-client.ts

@@ -19,8 +19,45 @@ import type {
 import { parseNDJsonStream } from "./ndjson-stream.js";
 
 const DEFAULT_HOST = "http://localhost:11434";
-const PROBE_TIMEOUT_MS = 1500;
-const REQUEST_TIMEOUT_MS = 10000;
+const DEFAULT_PROBE_TIMEOUT_MS = 1500;
+const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * Parse a positive integer from an environment variable, falling back to
+ * `fallback` when the var is unset, empty, non-numeric, zero, or negative.
+ *
+ * Defensive parsing: a typo like `OLLAMA_PROBE_TIMEOUT_MS=abc` or
+ * `OLLAMA_PROBE_TIMEOUT_MS=0` should not silently disable the timeout —
+ * fall back to the documented default instead.
+ */
+export function envPositiveInt(name: string, fallback: number): number {
+	const raw = process.env[name];
+	if (!raw) return fallback;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+	return Math.min(parsed, MAX_TIMER_DELAY_MS);
+}
+
+/**
+ * Effective probe timeout for the startup `isRunning()` health check.
+ * Override with `OLLAMA_PROBE_TIMEOUT_MS=<ms>` for slower networks (LAN
+ * Ollama hosts, cloud endpoints, contended cold starts).
+ *
+ * Resolved at call time — tests and downstream callers can mutate
+ * `process.env` between invocations and pick up the new value.
+ */
+export function getProbeTimeoutMs(): number {
+	return envPositiveInt("OLLAMA_PROBE_TIMEOUT_MS", DEFAULT_PROBE_TIMEOUT_MS);
+}
+
+/**
+ * Effective per-request timeout for REST calls. Override with
+ * `OLLAMA_REQUEST_TIMEOUT_MS=<ms>`.
+ */
+export function getRequestTimeoutMs(): number {
+	return envPositiveInt("OLLAMA_REQUEST_TIMEOUT_MS", DEFAULT_REQUEST_TIMEOUT_MS);
+}
 
 /**
  * Get the Ollama host URL from OLLAMA_HOST or default.
@@ -57,7 +94,7 @@ function withAuth(options: RequestInit = {}): RequestInit {
 	};
 }
 
-async function fetchWithTimeout(url: string, options: RequestInit = {}, timeoutMs = REQUEST_TIMEOUT_MS): Promise<Response> {
+async function fetchWithTimeout(url: string, options: RequestInit = {}, timeoutMs = getRequestTimeoutMs()): Promise<Response> {
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), timeoutMs);
 	try {
@@ -77,7 +114,7 @@ export async function isRunning(): Promise<boolean> {
 		const host = getOllamaHost();
 		const isCloud = host.includes("ollama.com") || host.includes("cloud");
 		const probeUrl = isCloud ? `${host}/api/tags` : `${host}/`;
-		const timeout = isCloud ? REQUEST_TIMEOUT_MS : PROBE_TIMEOUT_MS;
+		const timeout = isCloud ? getRequestTimeoutMs() : getProbeTimeoutMs();
 		const response = await fetchWithTimeout(probeUrl, isCloud ? { method: "GET" } : {}, timeout);
 		return response.ok;
 	} catch {

package/src/resources/extensions/ollama/tests/model-capabilities.test.ts

@@ -84,6 +84,102 @@ describe("getModelCapabilities", () => {
 	});
 });
 
+// ─── Ordering / prefix-shadowing regression (#4991) ──────────────────────────
+//
+// The lookup is a linear scan over KNOWN_MODELS using `baseName.startsWith(pattern)`.
+// Cloud and long-variant model names share prefixes with their base families,
+// so the longer entries MUST appear earlier in the table — otherwise a base
+// like `qwen3` shadows `qwen3-coder`/`qwen3-next`/`qwen3.5` and the picker
+// reports the wrong context window. These tests pin the ordering.
+
+describe("getModelCapabilities — long-variant overrides aren't shadowed (#4991)", () => {
+	it("qwen3-coder reports 256K, not the qwen3 131K", () => {
+		const caps = getModelCapabilities("qwen3-coder:480b");
+		assert.equal(caps.contextWindow, 262144);
+		assert.equal(caps.ollamaOptions?.num_ctx, 262144);
+	});
+
+	it("qwen3-coder-next still resolves via the qwen3-coder entry", () => {
+		const caps = getModelCapabilities("qwen3-coder-next");
+		assert.equal(caps.contextWindow, 262144);
+	});
+
+	it("qwen3-next:80b reports 1M, not the qwen3 131K", () => {
+		const caps = getModelCapabilities("qwen3-next:80b");
+		assert.equal(caps.contextWindow, 1048576);
+	});
+
+	it("qwen3.5 / qwen3.6 cloud variants report 1M", () => {
+		assert.equal(getModelCapabilities("qwen3.5:397b").contextWindow, 1048576);
+		assert.equal(getModelCapabilities("qwen3.6:cloud").contextWindow, 1048576);
+	});
+
+	it("base qwen3 still resolves to its 131K entry", () => {
+		const caps = getModelCapabilities("qwen3:8b");
+		assert.equal(caps.contextWindow, 131072);
+	});
+
+	it("glm-5.1:cloud reports 200K", () => {
+		const caps = getModelCapabilities("glm-5.1:cloud");
+		assert.equal(caps.contextWindow, 204800);
+	});
+
+	it("glm-4.6:cloud reports 200K", () => {
+		const caps = getModelCapabilities("glm-4.6:cloud");
+		assert.equal(caps.contextWindow, 204800);
+	});
+
+	it("glm-4 base still resolves to its 131K entry", () => {
+		const caps = getModelCapabilities("glm-4:9b");
+		assert.equal(caps.contextWindow, 131072);
+	});
+
+	it("kimi-k2-thinking reports 256K (not shadowed by kimi-k2)", () => {
+		const caps = getModelCapabilities("kimi-k2-thinking");
+		assert.equal(caps.contextWindow, 262144);
+	});
+
+	it("kimi-k2.5:cloud and kimi-k2.6:cloud both report 256K", () => {
+		assert.equal(getModelCapabilities("kimi-k2.5:cloud").contextWindow, 262144);
+		assert.equal(getModelCapabilities("kimi-k2.6:cloud").contextWindow, 262144);
+	});
+
+	it("kimi-k2 base resolves to 256K", () => {
+		const caps = getModelCapabilities("kimi-k2:cloud");
+		assert.equal(caps.contextWindow, 262144);
+	});
+
+	it("minimax-m2.5:cloud and minimax-m2.7:cloud report 1M", () => {
+		assert.equal(getModelCapabilities("minimax-m2.5:cloud").contextWindow, 1048576);
+		assert.equal(getModelCapabilities("minimax-m2.7:cloud").contextWindow, 1048576);
+	});
+
+	it("minimax-m2 base resolves to 1M", () => {
+		const caps = getModelCapabilities("minimax-m2:cloud");
+		assert.equal(caps.contextWindow, 1048576);
+	});
+
+	it("ollamaOptions.num_ctx mirrors contextWindow for all new entries", () => {
+		// Inference time: num_ctx is what gets sent to Ollama on each chat.
+		// If contextWindow is right but num_ctx is stale, the model still
+		// gets truncated. Pin both sides.
+		for (const name of [
+			"qwen3-next:80b",
+			"qwen3-coder:480b",
+			"glm-5.1:cloud",
+			"kimi-k2-thinking",
+			"minimax-m2.7:cloud",
+		]) {
+			const caps = getModelCapabilities(name);
+			assert.equal(
+				caps.ollamaOptions?.num_ctx,
+				caps.contextWindow,
+				`${name}: num_ctx (${caps.ollamaOptions?.num_ctx}) must equal contextWindow (${caps.contextWindow})`,
+			);
+		}
+	});
+});
+
 // ─── estimateContextFromParams ───────────────────────────────────────────────
 
 describe("estimateContextFromParams", () => {

package/src/resources/extensions/ollama/tests/ollama-client-timeout-env.test.ts

@@ -0,0 +1,147 @@
+// GSD2 — Tests for OLLAMA_PROBE_TIMEOUT_MS / OLLAMA_REQUEST_TIMEOUT_MS env vars (#5003 / #4982)
+//
+// Pinned defaults: 1500 ms probe, 10 000 ms request. The defaults must be
+// preserved when the env var is unset, empty, non-numeric, zero, or negative
+// so a typo or fat-fingered value can't silently disable the timeout. When
+// the env var is set to a valid positive integer it overrides the default.
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+	envPositiveInt,
+	getProbeTimeoutMs,
+	getRequestTimeoutMs,
+	MAX_TIMER_DELAY_MS,
+} from "../ollama-client.js";
+
+const PROBE_VAR = "OLLAMA_PROBE_TIMEOUT_MS";
+const REQUEST_VAR = "OLLAMA_REQUEST_TIMEOUT_MS";
+
+function withEnv(name: string, value: string | undefined, run: () => void): void {
+	const prior = process.env[name];
+	if (value === undefined) {
+		delete process.env[name];
+	} else {
+		process.env[name] = value;
+	}
+	try {
+		run();
+	} finally {
+		if (prior === undefined) {
+			delete process.env[name];
+		} else {
+			process.env[name] = prior;
+		}
+	}
+}
+
+describe("envPositiveInt — defensive fallback", () => {
+	it("returns fallback when var is unset", () => {
+		withEnv("__GSD_TEST_INT__", undefined, () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns fallback when var is empty string", () => {
+		withEnv("__GSD_TEST_INT__", "", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns fallback when var is non-numeric", () => {
+		withEnv("__GSD_TEST_INT__", "abc", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns fallback when var is zero (would silently disable timeout)", () => {
+		withEnv("__GSD_TEST_INT__", "0", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns fallback when var is negative", () => {
+		withEnv("__GSD_TEST_INT__", "-100", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns parsed value when var is a positive integer", () => {
+		withEnv("__GSD_TEST_INT__", "5000", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 5000);
+		});
+	});
+
+	it("parses leading digits and discards trailing junk (parseInt semantics)", () => {
+		withEnv("__GSD_TEST_INT__", "1500ms", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 1500);
+		});
+	});
+
+	it("clamps values above MAX_TIMER_DELAY_MS to prevent setTimeout overflow", () => {
+		withEnv("__GSD_TEST_INT__", String(MAX_TIMER_DELAY_MS + 1), () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), MAX_TIMER_DELAY_MS);
+		});
+	});
+
+	it("accepts MAX_TIMER_DELAY_MS exactly", () => {
+		withEnv("__GSD_TEST_INT__", String(MAX_TIMER_DELAY_MS), () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), MAX_TIMER_DELAY_MS);
+		});
+	});
+});
+
+describe("getProbeTimeoutMs — OLLAMA_PROBE_TIMEOUT_MS override", () => {
+	beforeEach(() => {
+		delete process.env[PROBE_VAR];
+	});
+	afterEach(() => {
+		delete process.env[PROBE_VAR];
+	});
+
+	it("defaults to 1500 ms when unset", () => {
+		assert.equal(getProbeTimeoutMs(), 1500);
+	});
+
+	it("honours a positive override", () => {
+		process.env[PROBE_VAR] = "5000";
+		assert.equal(getProbeTimeoutMs(), 5000);
+	});
+
+	it("falls back to 1500 ms on a zero override (typo guard)", () => {
+		process.env[PROBE_VAR] = "0";
+		assert.equal(getProbeTimeoutMs(), 1500);
+	});
+
+	it("re-reads the env var on every call", () => {
+		process.env[PROBE_VAR] = "2000";
+		assert.equal(getProbeTimeoutMs(), 2000);
+		process.env[PROBE_VAR] = "8000";
+		assert.equal(getProbeTimeoutMs(), 8000);
+		delete process.env[PROBE_VAR];
+		assert.equal(getProbeTimeoutMs(), 1500);
+	});
+});
+
+describe("getRequestTimeoutMs — OLLAMA_REQUEST_TIMEOUT_MS override", () => {
+	beforeEach(() => {
+		delete process.env[REQUEST_VAR];
+	});
+	afterEach(() => {
+		delete process.env[REQUEST_VAR];
+	});
+
+	it("defaults to 10 000 ms when unset", () => {
+		assert.equal(getRequestTimeoutMs(), 10000);
+	});
+
+	it("honours a positive override", () => {
+		process.env[REQUEST_VAR] = "30000";
+		assert.equal(getRequestTimeoutMs(), 30000);
+	});
+
+	it("falls back to 10 000 ms on non-numeric input", () => {
+		process.env[REQUEST_VAR] = "thirty-seconds";
+		assert.equal(getRequestTimeoutMs(), 10000);
+	});
+});

package/src/resources/extensions/remote-questions/remote-command.ts

@@ -11,6 +11,7 @@ import { getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences } from "../gsd
 import { getRemoteConfigStatus, isValidChannelId, resolveRemoteConfig } from "./config.js";
 import { maskEditorLine, sanitizeError } from "../shared/mod.js";
 import { getLatestPromptSummary } from "./status.js";
+import { gsdHome } from "../gsd/gsd-home.js";
 
 export async function handleRemote(
   subcommand: string,
@@ -300,7 +301,7 @@ async function promptSlackChannelId(ctx: ExtensionCommandContext): Promise<strin
 }
 
 function getAuthStorage(): AuthStorage {
-  const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+  const authPath = join(gsdHome(), "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   return AuthStorage.create(authPath);
 }

package/src/resources/extensions/remote-questions/status.ts

@@ -4,12 +4,8 @@
 
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { readPromptRecord } from "./store.js";
-
-function getGsdHome(): string {
-  return process.env.GSD_HOME || join(homedir(), ".gsd");
-}
+import { gsdHome } from "../gsd/gsd-home.js";
 
 export interface LatestPromptSummary {
   id: string;
@@ -18,7 +14,7 @@ export interface LatestPromptSummary {
 }
 
 export function getLatestPromptSummary(): LatestPromptSummary | null {
-  const runtimeDir = join(getGsdHome(), "runtime", "remote-questions");
+  const runtimeDir = join(gsdHome(), "runtime", "remote-questions");
   if (!existsSync(runtimeDir)) return null;
   const files = readdirSync(runtimeDir).filter((f) => f.endsWith(".json"));
   if (files.length === 0) return null;

package/src/resources/extensions/remote-questions/store.ts

@@ -4,15 +4,11 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { gsdHome } from "../gsd/gsd-home.js";
 import type { RemotePrompt, RemotePromptRecord, RemotePromptRef, RemoteAnswer, RemotePromptStatus } from "./types.js";
 
-function getGsdHome(): string {
-  return process.env.GSD_HOME || join(homedir(), ".gsd");
-}
-
 function runtimeDir(): string {
-  return join(getGsdHome(), "runtime", "remote-questions");
+  return join(gsdHome(), "runtime", "remote-questions");
 }
 
 function recordPath(id: string): string {

package/src/resources/extensions/search-the-web/provider.ts

@@ -10,15 +10,16 @@
  */
 
 import { AuthStorage } from '@gsd/pi-coding-agent'
-import { homedir } from 'os'
 import { join } from 'path'
 import { resolveSearchProviderFromPreferences } from '../gsd/preferences.js'
+import { gsdHome } from "../gsd/gsd-home.js";
 
-// Compute authFilePath locally instead of importing from app-paths.ts,
-// because extensions are copied to ~/.gsd/agent/extensions/ at runtime
-// where the relative import '../../../app-paths.ts' doesn't resolve.
-const gsdHome = process.env.GSD_HOME || join(homedir(), '.gsd')
-const authFilePath = join(gsdHome, 'agent', 'auth.json')
+// Compute authFilePath lazily so GSD_HOME overrides (e.g. in tests) take effect.
+// Imported locally instead of from app-paths.ts because extensions are copied to
+// ~/.gsd/agent/extensions/ at runtime where '../../../app-paths.ts' doesn't resolve.
+function authFilePath(): string {
+  return join(gsdHome(), 'agent', 'auth.json');
+}
 
 export type SearchProvider = 'tavily' | 'brave' | 'ollama'
 export type SearchProviderPreference = SearchProvider | 'auto'
@@ -57,7 +58,7 @@ export function getOllamaApiKey(): string {
  * @param authPath — Override auth.json path (for testing).
  */
 export function getSearchProviderPreference(authPath?: string): SearchProviderPreference {
-  const auth = AuthStorage.create(authPath ?? authFilePath)
+  const auth = AuthStorage.create(authPath ?? authFilePath())
   const cred = auth.get(PREFERENCE_KEY)
   if (cred?.type === 'api_key' && typeof cred.key === 'string' && VALID_PREFERENCES.has(cred.key)) {
     return cred.key as SearchProviderPreference
@@ -73,7 +74,7 @@ export function getSearchProviderPreference(authPath?: string): SearchProviderPr
  * @param authPath — Override auth.json path (for testing).
  */
 export function setSearchProviderPreference(pref: SearchProviderPreference, authPath?: string): void {
-  const auth = AuthStorage.create(authPath ?? authFilePath)
+  const auth = AuthStorage.create(authPath ?? authFilePath())
   auth.remove(PREFERENCE_KEY)
   auth.set(PREFERENCE_KEY, { type: 'api_key', key: pref })
 }

package/src/resources/extensions/shared/next-action-ui.ts

@@ -118,6 +118,14 @@ export async function showNextAction(
 		}
 	});
 
+	// Headless guard: when no UI is bound (noOpUIContext), ctx.ui.custom() resolves
+	// to undefined immediately, and ctx.ui.select() does the same. Skip both and
+	// return the safe default so callers don't await two no-op promises before
+	// reaching a deterministic "not_yet". Lockup #5125 root protection.
+	if (!ctx.hasUI) {
+		return "not_yet";
+	}
+
 	const result = await ctx.ui.custom<string>((_tui: TUI, theme: Theme, _kb, done) => {
 		let cursorIdx = defaultIdx;
 		let cachedLines: string[] | undefined;

package/src/resources/extensions/shared/tests/next-action-ui-hasui.test.ts

@@ -0,0 +1,112 @@
+// GSD2 — Regression test for next-action-ui ctx.hasUI short-circuit (bare /gsd lockup)
+
+/**
+ * Regression test for the bare /gsd lockup investigated in
+ * .planning/reports/2026-04-30-gsd-bare-and-new-project-investigation.md.
+ *
+ * showNextAction() awaits ctx.ui.custom() to render a TUI prompt. In a
+ * headless context (no UI bound, ctx.hasUI === false), both ctx.ui.custom
+ * and ctx.ui.select resolve to undefined, but the call still pays for two
+ * sequential awaits before reaching the safe "not_yet" default. This test
+ * asserts the proactive short-circuit: when ctx.hasUI is false,
+ * showNextAction returns "not_yet" immediately without touching either
+ * UI method.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { showNextAction } from "../next-action-ui.js";
+
+describe("showNextAction ctx.hasUI guard (#5125 lockup root protection)", () => {
+  it("returns 'not_yet' immediately when ctx.hasUI is false (no UI calls)", async () => {
+    let customCalled = 0;
+    let selectCalled = 0;
+
+    const ctx = {
+      hasUI: false,
+      ui: {
+        custom: async () => {
+          customCalled++;
+          return undefined as never;
+        },
+        select: async () => {
+          selectCalled++;
+          return undefined;
+        },
+      },
+    };
+
+    const result = await showNextAction(ctx as any, {
+      title: "GSD — test",
+      actions: [
+        { id: "a", label: "Option A", description: "first", recommended: true },
+        { id: "b", label: "Option B", description: "second" },
+      ],
+    });
+
+    assert.equal(result, "not_yet", "should short-circuit to safe default");
+    assert.equal(customCalled, 0, "ctx.ui.custom must not be called when hasUI is false");
+    assert.equal(selectCalled, 0, "ctx.ui.select must not be called when hasUI is false");
+  });
+
+  it("uses ctx.ui.select fallback when ctx.hasUI is true and custom returns undefined", async () => {
+    let customCalled = 0;
+    let selectCalled = 0;
+
+    const ctx = {
+      hasUI: true,
+      ui: {
+        custom: async () => {
+          customCalled++;
+          return undefined as never;
+        },
+        select: async (_title: string, options: string[]) => {
+          selectCalled++;
+          return options[0];
+        },
+      },
+    };
+
+    const result = await showNextAction(ctx as any, {
+      title: "GSD — test",
+      actions: [
+        { id: "alpha", label: "Alpha", description: "first", recommended: true },
+        { id: "beta", label: "Beta", description: "second" },
+      ],
+    });
+
+    assert.equal(customCalled, 1, "ctx.ui.custom must be tried first when hasUI is true");
+    assert.equal(selectCalled, 1, "ctx.ui.select must run as fallback when custom returns undefined");
+    assert.equal(result, "alpha", "fallback should map the picked label back to the chosen action id");
+  });
+
+  it("returns the resolved id when ctx.ui.custom completes normally", async () => {
+    let selectCalled = 0;
+
+    const ctx = {
+      hasUI: true,
+      ui: {
+        custom: async (_factory: any) => {
+          // Simulate user selecting action "beta" via the TUI widget.
+          return "beta" as never;
+        },
+        select: async () => {
+          selectCalled++;
+          return undefined;
+        },
+      },
+    };
+
+    const result = await showNextAction(ctx as any, {
+      title: "GSD — test",
+      actions: [
+        { id: "alpha", label: "Alpha", description: "first", recommended: true },
+        { id: "beta", label: "Beta", description: "second" },
+      ],
+    });
+
+    assert.equal(result, "beta", "TUI selection should be returned verbatim");
+    assert.equal(selectCalled, 0, "ctx.ui.select fallback must NOT fire when custom returns a value");
+  });
+});