gsd-pi 2.78.1-dev.82bcf6b71 → 2.78.1-dev.84c045fd2

package/src/resources/extensions/gsd/workflow-plugins.ts

@@ -21,10 +21,10 @@ import {
 } from "node:fs";
 import { join, dirname, extname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { parse as parseYaml } from "yaml";
 
 import { loadRegistry, type TemplateEntry, type WorkflowMode } from "./workflow-templates.js";
+import { gsdHome } from "./gsd-home.js";
 
 export type { WorkflowMode } from "./workflow-templates.js";
 
@@ -58,15 +58,14 @@ function resolveBundledDir(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
   const local = join(moduleDir, "workflow-templates");
   if (existsSync(local)) return local;
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd", "workflow-templates");
+  const agentGsdDir = join(gsdHome(), "agent", "extensions", "gsd", "workflow-templates");
   if (existsSync(agentGsdDir)) return agentGsdDir;
   return local;
 }
 
 function globalPluginsDir(): string {
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  return join(gsdHome, "workflows");
+  
+  return join(gsdHome(), "workflows");
 }
 
 function projectPluginsDir(basePath: string): string {

package/src/resources/extensions/gsd/workflow-reconcile.ts

@@ -20,7 +20,7 @@ import {
 } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
 import { invalidateStateCache } from "./state.js";
-import { clearPathCache } from "./paths.js";
+import { clearPathCache, resolveGsdPathContract } from "./paths.js";
 import { clearParseCache } from "./files.js";
 import { writeManifest } from "./workflow-manifest.js";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -492,7 +492,7 @@ function _reconcileWorktreeLogsInner(
   atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
 
   // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
-  openDatabase(join(mainBasePath, ".gsd", "gsd.db"));
+  openDatabase(resolveGsdPathContract(mainBasePath).projectDb);
   replayEvents(merged);
 
   // Step 9: Write manifest
@@ -647,7 +647,7 @@ export function resolveConflict(
   writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
 
   // Replay resolved events through the DB (updates DB state)
-  openDatabase(join(basePath, ".gsd", "gsd.db"));
+  openDatabase(resolveGsdPathContract(basePath).projectDb);
   replayEvents(eventsToReplay);
   invalidateStateCache();
   clearPathCache();

package/src/resources/extensions/gsd/workflow-templates.ts

@@ -8,7 +8,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { gsdHome } from "./gsd-home.js";
 
 const __extensionDir = resolveGsdExtensionDir();
 const registryPath = join(__extensionDir, "workflow-templates", "registry.json");
@@ -17,8 +17,7 @@ const registryPath = join(__extensionDir, "workflow-templates", "registry.json")
 function resolveGsdExtensionDir(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
   if (existsSync(join(moduleDir, "workflow-templates"))) return moduleDir;
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
+  const agentGsdDir = join(gsdHome(), "agent", "extensions", "gsd");
   if (existsSync(join(agentGsdDir, "workflow-templates"))) return agentGsdDir;
   return moduleDir;
 }

package/src/resources/extensions/gsd/worktree-command.ts

@@ -15,7 +15,7 @@ import { loadPrompt } from "./prompt-loader.js";
 import { autoCommitCurrentBranch, getMainBranch, resolveGitHeadPath, nudgeGitBranchCache } from "./worktree.js";
 import { runWorktreePostCreateHook } from "./auto-worktree.js";
 import { showConfirm } from "../shared/tui.js";
-import { gsdRoot, milestonesDir } from "./paths.js";
+import { gsdRoot, milestonesDir, resolveGsdPathContract } from "./paths.js";
 import {
   createWorktree,
   listWorktrees,
@@ -651,8 +651,9 @@ async function handleMerge(
     const commitMessage = `${commitType}: merge worktree ${name}\n\nGSD-Worktree: ${name}`;
 
     // Reconcile worktree DB into main DB before squash merge
-    const wtDbPath = join(worktreePath(basePath, name), ".gsd", "gsd.db");
-    const mainDbPath = join(basePath, ".gsd", "gsd.db");
+    const contract = resolveGsdPathContract(worktreePath(basePath, name), basePath);
+    const wtDbPath = join(contract.worktreeGsd ?? join(contract.workRoot, ".gsd"), "gsd.db");
+    const mainDbPath = contract.projectDb;
     if (existsSync(wtDbPath) && existsSync(mainDbPath)) {
       try {
         const { reconcileWorktreeDb } = await import("./gsd-db.js");

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -755,10 +755,10 @@ export function diffWorktreeGSD(basePath: string, name: string): WorktreeDiffSum
  * on main when the merge is applied. If both branches have identical
  * content, this correctly returns an empty diff.
  */
-export function diffWorktreeAll(basePath: string, name: string): WorktreeDiffSummary {
+export function diffWorktreeAll(basePath: string, name: string, branchOverride?: string): WorktreeDiffSummary {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
-  const branch = worktreeBranchName(name);
+  const branch = branchOverride ?? worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
   const entries = nativeDiffNameStatus(basePath, mainBranch, branch);
@@ -770,10 +770,10 @@ export function diffWorktreeAll(basePath: string, name: string): WorktreeDiffSum
  * Get per-file line addition/deletion stats for what will change on main.
  * Uses direct diff (not merge-base) so the preview matches the actual merge outcome.
  */
-export function diffWorktreeNumstat(basePath: string, name: string): FileLineStat[] {
+export function diffWorktreeNumstat(basePath: string, name: string, branchOverride?: string): FileLineStat[] {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
-  const branch = worktreeBranchName(name);
+  const branch = branchOverride ?? worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
 
   const rawStats = nativeDiffNumstat(basePath, mainBranch, branch);
@@ -831,10 +831,10 @@ export function getWorktreeLog(basePath: string, name: string): string {
  * Must be called from the main working tree (not the worktree itself).
  * Returns the merge commit message.
  */
-export function mergeWorktreeToMain(basePath: string, name: string, commitMessage: string): string {
+export function mergeWorktreeToMain(basePath: string, name: string, commitMessage: string, branchOverride?: string): string {
   basePath = normalizeBasePathForWorktreeOps(basePath);
 
-  const branch = worktreeBranchName(name);
+  const branch = branchOverride ?? worktreeBranchName(name);
   const mainBranch = nativeDetectMainBranch(basePath);
   const current = nativeGetCurrentBranch(basePath);
 

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -30,7 +30,7 @@ import { resolveWorktreeProjectRoot } from "./worktree-root.js";
 export interface WorktreeResolverDeps {
   isInAutoWorktree: (basePath: string) => boolean;
   shouldUseWorktreeIsolation: () => boolean;
-  getIsolationMode: () => "worktree" | "branch" | "none";
+  getIsolationMode: (basePath?: string) => "worktree" | "branch" | "none";
   mergeMilestoneToMain: (
     basePath: string,
     milestoneId: string,
@@ -185,7 +185,11 @@ export class WorktreeResolver {
       return;
     }
 
-    const mode = this.deps.getIsolationMode();
+    // Resolve the project root for worktree operations via shared helper.
+    // Handles the case where originalBasePath is falsy and basePath is itself
+    // a worktree path — prevents double-nested worktree paths (#3729).
+    const basePath = resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
+    const mode = this.deps.getIsolationMode(basePath);
 
     if (mode === "none") {
       debugLog("WorktreeResolver", {
@@ -204,10 +208,6 @@ export class WorktreeResolver {
       return;
     }
 
-    // Resolve the project root for worktree operations via shared helper.
-    // Handles the case where originalBasePath is falsy and basePath is itself
-    // a worktree path — prevents double-nested worktree paths (#3729).
-    const basePath = resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
     debugLog("WorktreeResolver", {
       action: "enterMilestone",
       milestoneId,
@@ -447,7 +447,7 @@ export class WorktreeResolver {
       return;
     }
 
-    const mode = this.deps.getIsolationMode();
+    const mode = this.deps.getIsolationMode(this.s.originalBasePath || this.s.basePath);
     debugLog("WorktreeResolver", {
       action: "mergeAndExit",
       milestoneId,

package/src/resources/extensions/gsd/worktree-root.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { gsdHome } from "./gsd-home.js";
 
 export interface WorktreeSegment {
   gsdIdx: number;
@@ -58,18 +58,23 @@ export function resolveWorktreeProjectRoot(
   basePath: string,
   originalBasePath?: string | null,
 ): string {
-  const preferred =
-    originalBasePath?.trim() ||
-    process.env.GSD_PROJECT_ROOT?.trim() ||
-    basePath;
+  const explicitOriginal = originalBasePath?.trim();
+  if (explicitOriginal) return resolveProjectRootFromPath(explicitOriginal);
 
-  return resolveProjectRootFromPath(preferred);
+  const envProjectRoot = process.env.GSD_PROJECT_ROOT?.trim();
+  if (envProjectRoot && isGsdWorktreePath(basePath)) {
+    return resolveProjectRootFromPath(envProjectRoot);
+  }
+
+  return resolveProjectRootFromPath(basePath || envProjectRoot || process.cwd());
 }
 
 function resolveProjectRootFromPath(path: string): string {
   const normalizedPath = path.replaceAll("\\", "/");
   const segment = findWorktreeSegment(normalizedPath);
-  if (!segment) return resolveGitWorkingTreeRoot(path) ?? path;
+  if (!segment) {
+    return resolveNearestBootstrappedGsdRoot(path) ?? resolveGitWorkingTreeRoot(path) ?? path;
+  }
 
   const sepChar = path.includes("\\") ? "\\" : "/";
   const gsdMarker = `${sepChar}.gsd${sepChar}`;
@@ -78,10 +83,10 @@ function resolveProjectRootFromPath(path: string): string {
     ? path.slice(0, markerIdx)
     : path.slice(0, segment.gsdIdx);
 
-  const gsdHome = normalizeWorktreePathForCompare(process.env.GSD_HOME || join(homedir(), ".gsd"));
+  const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
   const candidateGsdPath = normalizeWorktreePathForCompare(join(candidate, ".gsd"));
 
-  if (candidateGsdPath === gsdHome || candidateGsdPath.startsWith(`${gsdHome}/`)) {
+  if (candidateGsdPath === gsdHomeNorm || candidateGsdPath.startsWith(`${gsdHomeNorm}/`)) {
     const realRoot = resolveProjectRootFromGitFile(path);
     return realRoot ?? path;
   }
@@ -89,13 +94,46 @@ function resolveProjectRootFromPath(path: string): string {
   return candidate;
 }
 
+function resolveNearestBootstrappedGsdRoot(path: string): string | null {
+  try {
+    let dir = existsSync(path) && !statSync(path).isDirectory()
+      ? resolve(path, "..")
+      : path;
+    const externalStateParent = normalizeWorktreePathForCompare(resolve(gsdHome(), ".."));
+
+    for (let i = 0; i < 30; i++) {
+      if (normalizeWorktreePathForCompare(dir) === externalStateParent) return null;
+      if (hasGsdBootstrapArtifacts(join(dir, ".gsd"))) return dir;
+
+      const gitPath = join(dir, ".git");
+      if (existsSync(gitPath)) return null;
+
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // Non-fatal: callers fall back to git root resolution.
+  }
+  return null;
+}
+
+function hasGsdBootstrapArtifacts(gsdPath: string): boolean {
+  return existsSync(gsdPath) &&
+    (existsSync(join(gsdPath, "PREFERENCES.md")) ||
+      existsSync(join(gsdPath, "preferences.md")) ||
+      existsSync(join(gsdPath, "milestones")));
+}
+
 function resolveGitWorkingTreeRoot(path: string): string | null {
   try {
     let dir = existsSync(path) && !statSync(path).isDirectory()
       ? resolve(path, "..")
       : path;
+    const externalStateParent = normalizeWorktreePathForCompare(resolve(gsdHome(), ".."));
 
     for (let i = 0; i < 30; i++) {
+      if (normalizeWorktreePathForCompare(dir) === externalStateParent) return null;
       const gitPath = join(dir, ".git");
       if (existsSync(gitPath)) return dir;
 

package/src/resources/extensions/gsd/write-intercept.ts

@@ -91,9 +91,9 @@ function matchesBlockedPattern(path: string): boolean {
  * Directs the agent to use engine tool calls instead.
  */
 export const BLOCKED_WRITE_ERROR = `Direct writes to .gsd/STATE.md and .gsd/gsd.db are blocked. Use engine tool calls instead:
-- To complete a task: call gsd_complete_task(milestone_id, slice_id, task_id, summary)
-- To complete a slice: call gsd_complete_slice(milestone_id, slice_id, summary, uat_result)
-- To save a decision: call gsd_save_decision(scope, decision, choice, rationale)
+- To complete a task: call gsd_task_complete(milestone_id, slice_id, task_id, summary)
+- To complete a slice: call gsd_slice_complete(milestone_id, slice_id, summary, uat_result)
+- To save a decision: call gsd_decision_save(scope, decision, choice, rationale)
 - To start a task: call gsd_start_task(milestone_id, slice_id, task_id)
 - To record verification: call gsd_record_verification(milestone_id, slice_id, task_id, evidence)
 - To report a blocker: call gsd_report_blocker(milestone_id, slice_id, task_id, description)`;

package/src/resources/extensions/mcp-client/index.ts

@@ -25,10 +25,10 @@ import { Client } from "@modelcontextprotocol/sdk/client";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { readFileSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { buildHttpTransportOpts } from "./auth.js";
 import type { McpHttpAuthConfig } from "./auth.js";
+import { gsdHome } from "../gsd/gsd-home.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -104,7 +104,7 @@ function readConfigs(): McpServerConfig[] {
 	const configPaths = [
 		join(process.cwd(), ".mcp.json"),
 		join(process.cwd(), ".gsd", "mcp.json"),
-		join(process.env.GSD_HOME || join(homedir(), ".gsd"), "mcp.json"),
+		join(gsdHome(), "mcp.json"),
 	];
 
 	for (const configPath of configPaths) {

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");
+  });
+});