@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/src/resources/extensions/gsd/uok/model-policy.ts

@@ -1,6 +1,7 @@
 import type { TaskMetadata } from "../complexity-classifier.js";
 import { computeTaskRequirements, filterToolsForProvider } from "../model-router.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 
 export interface ModelCandidate {
   id: string;
@@ -83,23 +84,25 @@ export function applyModelPolicyFilter<T extends ModelCandidate>(
     };
     decisions.push(decision);
 
-    emitUokAuditEvent(
-      options.basePath,
-      buildAuditEnvelope({
-        traceId: options.traceId,
-        turnId: options.turnId,
-        category: "model-policy",
-        type: allowed ? "model-policy-allow" : "model-policy-deny",
-        payload: {
-          modelId: model.id,
-          provider: model.provider,
-          api: model.api,
-          reason,
-          unitType: options.unitType,
-          requirements,
-        },
-      }),
-    );
+    if (isUnifiedAuditEnabled(options.basePath)) {
+      emitUokAuditEvent(
+        options.basePath,
+        buildAuditEnvelope({
+          traceId: options.traceId,
+          turnId: options.turnId,
+          category: "model-policy",
+          type: allowed ? "model-policy-allow" : "model-policy-deny",
+          payload: {
+            modelId: model.id,
+            provider: model.provider,
+            api: model.api,
+            reason,
+            unitType: options.unitType,
+            requirements,
+          },
+        }),
+      );
+    }
 
     if (allowed) eligible.push(model);
   }

package/src/resources/extensions/gsd/validation-block-guard.ts

@@ -3,7 +3,8 @@
 
 import { existsSync } from "node:fs";
 
-import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
+import { isInAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";

package/src/resources/extensions/gsd/workflow-event-ledger.ts

@@ -105,7 +105,7 @@ export function writeWorktreeEventLog(
 }
 
 function emitWorkflowEventAudit(basePath: string, event: WorkflowEvent): void {
-  if (!isUnifiedAuditEnabled()) return;
+  if (!isUnifiedAuditEnabled(basePath)) return;
   try {
     const normalized = normalizeWorkflowEventCommand(event.cmd) ?? "unknown";
     emitUokAuditEvent(

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

@@ -302,7 +302,7 @@ function _push(
     _buffer.shift();
   }
 
-  if (_auditBasePath && isUnifiedAuditEnabled()) {
+  if (_auditBasePath && isUnifiedAuditEnabled(_auditBasePath)) {
     try {
       emitUokAuditEvent(
         _auditBasePath,

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

@@ -17,7 +17,7 @@ import type { MilestoneRow } from "./db-milestone-artifact-rows.js";
 import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
 import type { VerificationEvidenceRow } from "./db-verification-evidence-rows.js";
 import { atomicWriteSync } from "./atomic-write.js";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { logWarning } from "./workflow-logger.js";
@@ -26,7 +26,7 @@ import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
 import { renderPlanFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { readManifest } from "./workflow-manifest.js";
-import { gsdRoot, resolveSliceFile, resolveMilestonePath, resolveSlicePath, gsdProjectionRoot } from "./paths.js";
+import { gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveTaskFile, relTaskFile } from "./paths.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
@@ -329,24 +329,10 @@ export function renderSummaryProjection(basePath: string, milestoneId: string, s
   const evidenceRows = getVerificationEvidence(milestoneId, sliceId, taskId);
   const content = renderSummaryContent(taskRow, sliceId, milestoneId, evidenceRows);
 
-  // Layout-aware: avoid creating a milestones/ directory as a side effect for
-  // flat-phase projects. If milestonesDir() sees a freshly-created milestones/
-  // dir it treats the project as legacy, breaking all subsequent path resolution.
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
-  const phaseDir = resolveMilestonePath(basePath, milestoneId);
-  let dir: string;
-  if (slicePath && phaseDir && slicePath !== phaseDir) {
-    // Legacy layout: slice has its own slices/SID/ subdir → tasks/ subdir
-    dir = join(slicePath, "tasks");
-  } else if (phaseDir) {
-    // Flat-phase: task summaries go in the phase dir (no tasks/ subdir needed)
-    dir = phaseDir;
-  } else {
-    // Fallback: legacy hardcoded path (milestone dir not on disk yet)
-    dir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
-  }
-  mkdirSync(dir, { recursive: true });
-  atomicWriteSync(join(dir, `${taskId}-SUMMARY.md`), content);
+  const summaryPath = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY")
+    ?? join(basePath, relTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY", getMilestone(milestoneId)?.title));
+  mkdirSync(dirname(summaryPath), { recursive: true });
+  atomicWriteSync(summaryPath, content);
 }
 
 // ─── STATE.md Projection ────────────────────────────────────────────────
@@ -536,7 +522,7 @@ export async function regenerateIfMissing(
       filePath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN") ?? "";
       break;
     case "ROADMAP":
-      filePath = join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
+      filePath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP") ?? "";
       break;
     case "SUMMARY":
       // For SUMMARY, we regenerate all task summaries in the slice
@@ -553,8 +539,7 @@ export async function regenerateIfMissing(
     const doneTasks = taskRows.filter(t => t.status === "done" || t.status === "complete");
     let regenerated = 0;
     for (const task of doneTasks) {
-      const summaryPath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks", `${task.id}-SUMMARY.md`);
-      if (!existsSync(summaryPath)) {
+      if (!resolveTaskFile(basePath, milestoneId, sliceId, task.id, "SUMMARY")) {
         try {
           renderSummaryProjection(basePath, milestoneId, sliceId, task.id);
           regenerated++;
@@ -591,7 +576,7 @@ export async function regenerateIfMissing(
         return !!(resolveSliceFile(basePath, milestoneId, sliceId, "PLAN"));
       case "ROADMAP":
         await renderRoadmapFromDb(basePath, milestoneId);
-        return existsSync(filePath);
+        return !!resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
       case "STATE":
         await renderStateProjection(basePath);
         return existsSync(filePath);

package/src/resources/extensions/gsd/workspace-git-preflight.ts

@@ -3,8 +3,8 @@
 
 import { existsSync, realpathSync } from "node:fs";
 
-import { getAutoWorktreePath } from "./auto-worktree.js";
-import { isSafeToAutoResolve } from "./auto-worktree.js";
+import { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import {
   listMergeStateBlockers,

package/src/resources/extensions/gsd/workspace.ts

@@ -2,14 +2,11 @@
 
 import { dirname, join, resolve } from "node:path";
 import {
-  buildMilestoneFileName,
-  canonicalPhaseDirName,
-  isLegacyMilestonesLayout,
-  milestonesDir,
   type GsdPathContract,
   resolveGsdPathContract,
   resolveMilestoneFile,
   resolveMilestonePath,
+  targetMilestoneFile,
   normalizeRealPath,
 } from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
@@ -41,27 +38,14 @@ function tryRealpath(p: string): string {
   return normalizeRealPath(p);
 }
 
-function isLegacyMilestoneDirectory(dir: string): boolean {
-  const parent = dirname(dir);
-  return parent.endsWith("/milestones") || parent.endsWith("\\milestones");
-}
-
 function scopeMilestoneDir(basePath: string, milestoneId: string): string {
-  return resolveMilestonePath(basePath, milestoneId) ?? join(
-    milestonesDir(basePath),
-    isLegacyMilestonesLayout(basePath) ? milestoneId : canonicalPhaseDirName(milestoneId),
-  );
+  return resolveMilestonePath(basePath, milestoneId)
+    ?? dirname(targetMilestoneFile(basePath, milestoneId, "ROADMAP"));
 }
 
 function scopeMilestoneFile(basePath: string, milestoneId: string, suffix: string): string {
-  const existing = resolveMilestoneFile(basePath, milestoneId, suffix);
-  if (existing) return existing;
-
-  const dir = scopeMilestoneDir(basePath, milestoneId);
-  const filename = isLegacyMilestoneDirectory(dir)
-    ? `${milestoneId}-${suffix}.md`
-    : buildMilestoneFileName(milestoneId, suffix);
-  return join(dir, filename);
+  return resolveMilestoneFile(basePath, milestoneId, suffix)
+    ?? targetMilestoneFile(basePath, milestoneId, suffix);
 }
 
 /**

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

@@ -13,7 +13,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { loadPrompt } from "./prompt-loader.js";
 import { autoCommitCurrentBranch, getMainBranch, resolveGitHeadPath, nudgeGitBranchCache } from "./worktree.js";
-import { runWorktreePostCreateHook } from "./auto-worktree.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import { showConfirm } from "../shared/tui.js";
 import { gsdRoot, milestonesDir, resolveGsdPathContract } from "./paths.js";
 import {

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

@@ -68,19 +68,21 @@ import {
   getCurrentBranch,
 } from "./worktree.js";
 import { nativeCheckoutBranch } from "./native-git-bridge.js";
-// ADR-016 phase 2 / C2 (#5625): worktree-manager helpers inlined from
-// `./auto-worktree.js`. These seven functions are not real seams — Lifecycle
-// is the only Module that calls them, and they live alongside the Module's
-// other primitives in `auto-worktree.ts`.
+// ADR-016 phase 2 / C2 (#5625): lifecycle uses focused auto-worktree
+// modules instead of the legacy compatibility barrel. Branch, entry/path,
+// creation, and teardown primitives are still implementation-level seams for
+// Lifecycle; tests vary them through `WorktreeLifecycleTestOverrides` below.
 import {
   autoWorktreeBranch,
-  createAutoWorktree,
-  enterAutoWorktree,
   enterBranchModeForMilestone,
-  getAutoWorktreePath,
+} from "./auto-worktree-branch-lifecycle.js";
+import { createAutoWorktree } from "./auto-worktree-creation.js";
+import {
+  enterAutoWorktree,
   isInAutoWorktree,
-  teardownAutoWorktree,
-} from "./auto-worktree.js";
+} from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
+import { teardownAutoWorktree } from "./auto-worktree-teardown.js";
 import { resolveRoadmapForMilestoneMerge } from "./milestone-merge-roadmap.js";
 import type { MilestoneMergeTransactionRunner } from "./milestone-merge-transaction.js";
 
@@ -353,7 +355,7 @@ export interface MergeContext {
   originalBasePath: string;
   /**
    * Current worktree path or project root when in branch mode. Used as the
-   * cwd anchor for `mergeMilestoneToMain` and the source for
+   * cwd anchor for the milestone merge transaction and the source for
    * `Projection.finalizeProjectionForMerge`.
    */
   worktreeBasePath: string;
@@ -381,7 +383,8 @@ export interface MergeStandaloneResult {
   pushed: boolean;
   /**
    * Commit message produced by the squash merge, if available. Forwarded
-   * from `mergeMilestoneToMain`. Only populated when `merged === true`.
+   * from the milestone merge transaction. Only populated when
+   * `merged === true`.
    */
   commitMessage?: string;
 }
@@ -1373,8 +1376,9 @@ function _mergeBranchModeImpl(
  * **CWD anchor**: anchors `process.cwd()` at `originalBasePath` before
  * non-worktree merge paths to mirror the single-loop guard against ENOENT
  * after teardown (de73fb43d). Worktree-mode merge paths keep the real
- * worktree as cwd because `mergeMilestoneToMain()` infers source worktree
- * state from `process.cwd()`. Best-effort; silent on failure.
+ * worktree as cwd because the default milestone merge transaction delegates
+ * to the legacy merge primitive, which infers source worktree state from
+ * `process.cwd()`. Best-effort; silent on failure.
  *
  * **Failure handling**: `MergeConflictError` and other unrecoverable errors
  * propagate to the caller. The caller is responsible for any state restore
@@ -1475,8 +1479,8 @@ export function mergeMilestoneStandalone(
 
   // Set cwd to the correct anchor before dispatching to mode implementations.
   // Worktree mode / in-worktree override must run from the live worktree so
-  // mergeMilestoneToMain can find worktree-local state; branch mode runs from
-  // the original project root. Best-effort for synthetic test paths.
+  // The default merge transaction can find worktree-local state; branch mode
+  // runs from the original project root. Best-effort for synthetic test paths.
   const targetCwd = mode === "worktree" || inWorktree
     ? worktreeBasePath
     : originalBasePath;

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

@@ -8,7 +8,8 @@
 
 import { readdirSync } from "node:fs";
 
-import { enterAutoWorktree, getAutoWorktreePath } from "./auto-worktree.js";
+import { enterAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { getIsolationMode } from "./preferences.js";
 import { allWorktreesDirs } from "./worktree-manager.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";

package/src/resources/extensions/shared/gsd-browser-cli.ts

@@ -66,6 +66,30 @@ function splitCommandLine(commandLine: string): string[] {
   });
 }
 
+/**
+ * Extra gsd-browser CLI flags to forward verbatim to the launched daemon, from
+ * GSD_BROWSER_MCP_EXTRA_ARGS. Unlike GSD_BROWSER_MCP_ARGS (a full args override),
+ * these are *appended* to the default `mcp`/`daemon start` invocation so callers
+ * keep the managed session/identity flags. Accepts a JSON array (e.g.
+ * `["--stealth"]`) or a plain, optionally-quoted command-line string
+ * (e.g. `--stealth --browser-path /usr/bin/chromium`). This is the config-level
+ * knob for environments where Chrome needs extra launch flags — e.g. containers
+ * without unprivileged user namespaces, where `--stealth` supplies Chrome's
+ * `--no-sandbox`.
+ */
+function resolveExtraGsdBrowserArgs(env: NodeJS.ProcessEnv): string[] {
+  const raw = env.GSD_BROWSER_MCP_EXTRA_ARGS?.trim();
+  if (!raw) return [];
+  if (raw.startsWith("[")) {
+    const parsed = parseJsonEnv<unknown>(env, "GSD_BROWSER_MCP_EXTRA_ARGS");
+    if (!Array.isArray(parsed)) {
+      throw new Error("GSD_BROWSER_MCP_EXTRA_ARGS JSON must be an array of strings");
+    }
+    return parsed.map(String);
+  }
+  return splitCommandLine(raw);
+}
+
 function buildPathGsdBrowserVersionInvocation(platform: NodeJS.Platform): { command: string; args: string[] } {
   if (platform === "win32") {
     return { command: "cmd", args: ["/d", "/s", "/c", "gsd-browser", "--version"] };
@@ -297,6 +321,10 @@ export function resolveGsdBrowserMcpLaunchConfig(
     || (preferPathCli ? "gsd-browser" : undefined)
     || (bundledCliPath ? process.execPath : undefined)
     || "gsd-browser";
+  // Appended after the managed session/identity flags so they survive the
+  // daemon-start transformation (which forwards everything after `mcp`), letting
+  // callers add extra Chrome/gsd-browser launch flags via one config knob.
+  const extraArgs = resolveExtraGsdBrowserArgs(env);
   const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
     ? explicitArgs.map(String)
     : [
@@ -311,6 +339,7 @@ export function resolveGsdBrowserMcpLaunchConfig(
         identityKey,
         "--identity-project",
         identityProject,
+        ...extraArgs,
       ];
   const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
 
@@ -326,14 +355,16 @@ export function resolveGsdBrowserMcpLaunchConfig(
 }
 
 /**
- * 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.
+ * CLI invocation that runs a `daemon <action>` command against the gsd-browser
+ * session daemon with the same session and identity flags as
+ * {@link resolveGsdBrowserMcpLaunchConfig}, so start (warm-up) and stop
+ * (teardown) address the exact same managed daemon.
  */
-export function resolveGsdBrowserDaemonStartInvocation(
+function resolveGsdBrowserDaemonInvocation(
+  action: "start" | "stop",
   projectRoot: string,
-  env: NodeJS.ProcessEnv = process.env,
-  options: GsdBrowserMcpLaunchOptions = {},
+  env: NodeJS.ProcessEnv,
+  options: GsdBrowserMcpLaunchOptions,
 ): Pick<GsdBrowserMcpLaunchConfig, "command" | "args" | "cwd" | "env"> {
   const launch = resolveGsdBrowserMcpLaunchConfig(projectRoot, env, options);
   const mcpIndex = launch.args.indexOf("mcp");
@@ -345,8 +376,34 @@ export function resolveGsdBrowserDaemonStartInvocation(
   const sessionFlags = launch.args.slice(mcpIndex + 1);
   return {
     command: launch.command,
-    args: [...prefix, "daemon", "start", ...sessionFlags],
+    args: [...prefix, "daemon", action, ...sessionFlags],
     cwd: launch.cwd,
     ...(launch.env ? { env: launch.env } : {}),
   };
 }
+
+/**
+ * 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: string,
+  env: NodeJS.ProcessEnv = process.env,
+  options: GsdBrowserMcpLaunchOptions = {},
+): Pick<GsdBrowserMcpLaunchConfig, "command" | "args" | "cwd" | "env"> {
+  return resolveGsdBrowserDaemonInvocation("start", projectRoot, env, options);
+}
+
+/**
+ * CLI invocation that stops the gsd-browser session daemon warmed for browser
+ * UAT, so the Chrome process is torn down instead of lingering after the
+ * triggering task/session ends.
+ */
+export function resolveGsdBrowserDaemonStopInvocation(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+  options: GsdBrowserMcpLaunchOptions = {},
+): Pick<GsdBrowserMcpLaunchConfig, "command" | "args" | "cwd" | "env"> {
+  return resolveGsdBrowserDaemonInvocation("stop", projectRoot, env, options);
+}

package/src/resources/extensions/shared/interview-ui.ts

@@ -244,6 +244,14 @@ export async function showInterviewRound(
 		let completed = false;
 		let removeAbortListener: (() => void) | undefined;
 
+		// Preview-panel scrolling. previewScroll is the first visible line of the
+		// side-by-side preview column; the viewport/total are captured on each
+		// render so PgUp/PgDn input can clamp against real bounds.
+		let previewScroll = 0;
+		let previewViewport = 0;
+		let previewTotal = 0;
+		function resetPreviewScroll() { previewScroll = 0; }
+
 		function finish(result: RoundResult) {
 			if (completed) return;
 			completed = true;
@@ -309,6 +317,7 @@ export async function showInterviewRound(
 			if (newIdx === currentIdx) return;
 			saveEditorToState();
 			currentIdx = newIdx;
+			resetPreviewScroll();
 			loadStateToEditor();
 			focusNotes = states[currentIdx].notesVisible && states[currentIdx].notes.length > 0;
 			refresh();
@@ -455,9 +464,20 @@ export async function showInterviewRound(
 				if (matchesKey(data, Key.right)) { switchQuestion((currentIdx + 1) % questions.length); return; }
 			}
 
+			// ── Preview scrolling ────────────────────────────────────────
+			if (matchesKey(data, Key.pageUp)) {
+				if (previewScroll > 0) { previewScroll = Math.max(0, previewScroll - previewViewport); refresh(); }
+				return;
+			}
+			if (matchesKey(data, Key.pageDown)) {
+				const maxScroll = Math.max(0, previewTotal - previewViewport);
+				if (previewScroll < maxScroll) { previewScroll = Math.min(maxScroll, previewScroll + previewViewport); refresh(); }
+				return;
+			}
+
 			// ── Cursor navigation ────────────────────────────────────────
-			if (matchesKey(data, Key.up)) { st.cursorIndex = (st.cursorIndex - 1 + optCount) % optCount; refresh(); return; }
-			if (matchesKey(data, Key.down)) { st.cursorIndex = (st.cursorIndex + 1) % optCount; refresh(); return; }
+			if (matchesKey(data, Key.up)) { st.cursorIndex = (st.cursorIndex - 1 + optCount) % optCount; resetPreviewScroll(); refresh(); return; }
+			if (matchesKey(data, Key.down)) { st.cursorIndex = (st.cursorIndex + 1) % optCount; resetPreviewScroll(); refresh(); return; }
 
 			if (multiSel) {
 				const doneI = noneOrDoneIdx(currentIdx);
@@ -562,6 +582,12 @@ export async function showInterviewRound(
 
 		// ── Preview helpers ──────────────────────────────────────────────
 
+		// Centered dim label between horizontal rules, used to mark hidden/scrollable rows.
+		function scrollIndicator(lbl: string, colWidth: number): string {
+			const d = "─".repeat(Math.max(0, Math.floor((colWidth - lbl.length - 2) / 2)));
+			return truncateToWidth(theme.fg("dim", ` ${d} ${lbl} ${d}`), colWidth);
+		}
+
 		let mdThemeCache: ReturnType<typeof getMarkdownTheme> | null = null;
 		let previewCache: { markdown: string; width: number; lines: string[] } | null = null;
 
@@ -666,6 +692,10 @@ export async function showInterviewRound(
 			const useSideBySide = questionHasAnyPreview()
 				&& contentWidth >= (MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH);
 
+			// No scrollable preview unless the side-by-side path sets these below.
+			previewTotal = 0;
+			previewViewport = 0;
+
 			if (useSideBySide) {
 				// ── Preview path ──────────────────────────────────────
 				const ui = makeUI(theme, contentWidth);
@@ -707,19 +737,35 @@ export async function showInterviewRound(
 				const leftLines = fullLeft.slice(0, maxBody);
 				if (fullLeft.length > maxBody) {
 					const n = fullLeft.length - maxBody + 1;
-					const lbl = `+${n} lines hidden`;
-					const d = "─".repeat(Math.max(0, Math.floor((leftWidth - lbl.length - 2) / 2)));
-					leftLines[maxBody - 1] = truncateToWidth(theme.fg("dim", ` ${d} ${lbl} ${d}`), leftWidth);
+					leftLines[maxBody - 1] = scrollIndicator(`+${n} lines hidden`, leftWidth);
 				}
 
 				const preview = getCurrentPreview();
 				const fullRight = preview ? renderPreviewColumn(preview, previewWidth) : [];
-				const rightLines = fullRight.slice(0, maxBody);
-				if (fullRight.length > maxBody) {
-					const n = fullRight.length - maxBody + 1;
-					const lbl = `+${n} lines hidden`;
-					const d = "─".repeat(Math.max(0, Math.floor((previewWidth - lbl.length - 2) / 2)));
-					rightLines[maxBody - 1] = truncateToWidth(theme.fg("dim", ` ${d} ${lbl} ${d}`), previewWidth);
+				// The first two lines are the pinned "Preview" header; the body
+				// below them scrolls via PgUp/PgDn so no content is unreachable.
+				const headerRows = fullRight.length > 0 ? 2 : 0;
+				const previewBody = fullRight.slice(headerRows);
+				const bodyViewport = Math.max(1, maxBody - headerRows);
+				previewTotal = previewBody.length;
+				previewViewport = bodyViewport;
+				const maxScroll = Math.max(0, previewBody.length - bodyViewport);
+				if (previewScroll > maxScroll) previewScroll = maxScroll;
+
+				const rightLines = fullRight.slice(0, headerRows);
+				if (previewBody.length <= bodyViewport) {
+					rightLines.push(...previewBody);
+				} else {
+					rightLines.push(...previewBody.slice(previewScroll, previewScroll + bodyViewport));
+					const hiddenAbove = previewScroll;
+					const hiddenBelow = previewBody.length - (previewScroll + bodyViewport);
+					// Overwrite the top/bottom visible rows with scroll indicators.
+					if (hiddenAbove > 0) {
+						rightLines[headerRows] = scrollIndicator(`▲ ${hiddenAbove} more`, previewWidth);
+					}
+					if (hiddenBelow > 0) {
+						rightLines[rightLines.length - 1] = scrollIndicator(`▼ ${hiddenBelow} more · PgUp/PgDn`, previewWidth);
+					}
 				}
 
 				while (leftLines.length < maxBody) leftLines.push("");
@@ -744,6 +790,7 @@ export async function showInterviewRound(
 					if (isMultiQuestion) hints.push("←/→ navigate");
 					hints.push(isLast && allAnswered() ? "enter to review" : "enter to next");
 				}
+				if (previewTotal > previewViewport) hints.push("pgup/pgdn scroll preview");
 				hints.push("esc to exit");
 				const footer = ui.hints(hints)[0] ?? "";
 

package/src/resources/extensions/shared/tests/interview-ui-border.test.ts

@@ -16,6 +16,8 @@ import {
 const ANSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
 const ENTER = "\r";
 const ESC = "\x1b";
+const PAGE_DOWN = "\x1b[6~";
+const PAGE_UP = "\x1b[5~";
 
 before(() => { initTheme(); });
 
@@ -160,4 +162,34 @@ describe("interview-ui dialog borders", () => {
 		const widget = await captureWrapUpWidget();
 		assertFullOuterBorder(widget.render(80), 80);
 	});
+
+	it("makes an overflowing preview scrollable with PgUp/PgDn", async () => {
+		const longPreview = Array.from({ length: 60 }, (_, i) => `line ${i + 1}`).join("\n");
+		const widget = await captureInterviewWidget([{
+			...questions[0],
+			options: [
+				{ label: "Web App", description: "Frontend or full-stack", preview: longPreview },
+			],
+		}]);
+
+		// Initial render: content overflows, so a bottom "more" indicator and the
+		// scroll hint are shown, and the border stays intact.
+		const initial = stripAnsi(widget.render(100).join("\n"));
+		assertFullOuterBorder(widget.render(100), 100);
+		assert.match(initial, /▼ \d+ more/, "bottom scroll indicator should appear when preview overflows");
+		assert.match(initial, /pgup\/pgdn scroll preview/, "footer should hint at preview scrolling");
+		assert.doesNotMatch(initial, /▲ \d+ more/, "top indicator should be absent before scrolling");
+
+		// Scroll down: content below is now revealed and a top indicator appears.
+		widget.handleInput(PAGE_DOWN);
+		const scrolled = stripAnsi(widget.render(100).join("\n"));
+		assertFullOuterBorder(widget.render(100), 100);
+		assert.match(scrolled, /▲ \d+ more/, "top scroll indicator should appear after scrolling down");
+		assert.ok(scrolled !== initial, "scrolling should change the rendered preview");
+
+		// Scroll back up returns to the original view.
+		widget.handleInput(PAGE_UP);
+		const back = stripAnsi(widget.render(100).join("\n"));
+		assert.doesNotMatch(back, /▲ \d+ more/, "top indicator should disappear after scrolling back to top");
+	});
 });

package/dist/web/standalone/.next/static/chunks/app/_not-found/page-49f565245e1e4afe.js

@@ -1 +0,0 @@
-(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[9492],{29999:(e,t)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"styles",{enumerable:!0,get:function(){return l}});let l={error:{fontFamily:'system-ui,"Segoe UI",Roboto,Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"',height:"100vh",textAlign:"center",display:"flex",flexDirection:"column",alignItems:"center",justifyContent:"center"},desc:{display:"inline-block"},h1:{display:"inline-block",margin:"0 20px 0 0",padding:"0 23px 0 0",fontSize:24,fontWeight:500,verticalAlign:"top",lineHeight:"49px"},h2:{fontSize:14,fontWeight:400,lineHeight:"49px",margin:0}};("function"==typeof t.default||"object"==typeof t.default&&null!==t.default)&&void 0===t.default.__esModule&&(Object.defineProperty(t.default,"__esModule",{value:!0}),Object.assign(t.default,t),e.exports=t.default)},32910:(e,t,l)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"default",{enumerable:!0,get:function(){return o}});let r=l(18870),n=l(48664),o=function(){return(0,r.jsx)("html",{children:(0,r.jsx)("body",{children:(0,r.jsx)(n.HTTPAccessErrorFallback,{status:404,message:"This page could not be found."})})})};("function"==typeof t.default||"object"==typeof t.default&&null!==t.default)&&void 0===t.default.__esModule&&(Object.defineProperty(t.default,"__esModule",{value:!0}),Object.assign(t.default,t),e.exports=t.default)},33433:(e,t,l)=>{(window.__NEXT_P=window.__NEXT_P||[]).push(["/_not-found/page",function(){return l(32910)}])},48664:(e,t,l)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"HTTPAccessErrorFallback",{enumerable:!0,get:function(){return o}});let r=l(18870),n=l(29999);function o({status:e,message:t}){return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)("title",{children:`${e}: ${t}`}),(0,r.jsx)("div",{style:n.styles.error,children:(0,r.jsxs)("div",{children:[(0,r.jsx)("style",{dangerouslySetInnerHTML:{__html:"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}),(0,r.jsx)("h1",{className:"next-error-h1",style:n.styles.h1,children:e}),(0,r.jsx)("div",{style:n.styles.desc,children:(0,r.jsx)("h2",{style:n.styles.h2,children:t})})]})})]})}("function"==typeof t.default||"object"==typeof t.default&&null!==t.default)&&void 0===t.default.__esModule&&(Object.defineProperty(t.default,"__esModule",{value:!0}),Object.assign(t.default,t),e.exports=t.default)}},e=>{e.O(0,[9990,686,7358],()=>e(e.s=33433)),_N_E=e.O()}]);

package/dist/web/standalone/.next/static/chunks/app/page-bc4c723c6a19c6f0.js

@@ -1 +0,0 @@
-(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[8974],{13914:(e,t,n)=>{Promise.resolve().then(n.bind(n,92703))},19013:(e,t,n)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"workAsyncStorage",{enumerable:!0,get:function(){return r.workAsyncStorageInstance}});let r=n(34969)},23711:(e,t,n)=>{"use strict";n.d(t,{default:()=>u.a});var r=n(60276),u=n.n(r)},30039:(e,t)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0});var n={bindSnapshot:function(){return s},createAsyncLocalStorage:function(){return a},createSnapshot:function(){return i}};for(var r in n)Object.defineProperty(t,r,{enumerable:!0,get:n[r]});let u=Object.defineProperty(Error("Invariant: AsyncLocalStorage accessed in runtime where it is not available"),"__NEXT_ERROR_CODE",{value:"E504",enumerable:!1,configurable:!0});class l{disable(){throw u}getStore(){}run(){throw u}exit(){throw u}enterWith(){throw u}static bind(e){return e}}let o="u">typeof globalThis&&globalThis.AsyncLocalStorage;function a(){return o?new o:new l}function s(e){return o?o.bind(e):l.bind(e)}function i(){return o?o.snapshot():function(e,...t){return e(...t)}}},34969:(e,t,n)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"workAsyncStorageInstance",{enumerable:!0,get:function(){return r}});let r=(0,n(30039).createAsyncLocalStorage)()},47811:(e,t,n)=>{"use strict";function r({reason:e,children:t}){return t}Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"BailoutToCSR",{enumerable:!0,get:function(){return r}}),n(71495)},60276:(e,t,n)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"default",{enumerable:!0,get:function(){return u}});let r=n(51481)._(n(80260));function u(e,t){let n={};"function"==typeof e&&(n.loader=e);let u={...n,...t};return(0,r.default)({...u,modules:u.loadableGenerated?.modules})}("function"==typeof t.default||"object"==typeof t.default&&null!==t.default)&&void 0===t.default.__esModule&&(Object.defineProperty(t.default,"__esModule",{value:!0}),Object.assign(t.default,t),e.exports=t.default)},76670:(e,t,n)=>{"use strict";function r({moduleIds:e}){return null}Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"PreloadChunks",{enumerable:!0,get:function(){return r}}),n(18870),n(29411),n(19013),n(19132),n(63632)},80260:(e,t,n)=>{"use strict";Object.defineProperty(t,"__esModule",{value:!0}),Object.defineProperty(t,"default",{enumerable:!0,get:function(){return s}});let r=n(18870),u=n(45110),l=n(47811);function o(e){return{default:e&&"default"in e?e.default:e}}n(76670);let a={loader:()=>Promise.resolve(o(()=>null)),loading:null,ssr:!0},s=function(e){let t={...a,...e},n=(0,u.lazy)(()=>t.loader().then(o)),s=t.loading;function i(e){let o=s?(0,r.jsx)(s,{isLoading:!0,pastDelay:!0,error:null}):null,a=!t.ssr||!!t.loading,i=a?u.Suspense:u.Fragment,c=t.ssr?(0,r.jsxs)(r.Fragment,{children:[null,(0,r.jsx)(n,{...e})]}):(0,r.jsx)(l.BailoutToCSR,{reason:"next/dynamic",children:(0,r.jsx)(n,{...e})});return(0,r.jsx)(i,{...a?{fallback:o}:{},children:c})}return i.displayName="LoadableComponent",i}},92703:(e,t,n)=>{"use strict";n.r(t),n.d(t,{default:()=>l});var r=n(18870);let u=(0,n(23711).default)(()=>Promise.all([n.e(4825),n.e(5395),n.e(7882),n.e(8937)]).then(n.bind(n,38937)).then(e=>e.GSDAppShell),{loadableGenerated:{webpack:()=>[38937]},ssr:!1,loading:()=>(0,r.jsx)("div",{className:"flex h-screen items-center justify-center bg-background text-sm text-muted-foreground",children:"Loading workspace…"})});function l(){return(0,r.jsx)(u,{})}}},e=>{e.O(0,[9990,686,7358],()=>e(e.s=13914)),_N_E=e.O()}]);

package/dist/web/standalone/.next/static/chunks/next/dist/client/components/builtin/global-error-ec3eaffc9785ba48.js

@@ -1 +0,0 @@
-(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[9337],{29454:(e,s,_)=>{Promise.resolve().then(_.t.bind(_,45336,23))}},e=>{e.O(0,[9990,686,7358],()=>e(e.s=29454)),_N_E=e.O()}]);