@opengsd/gsd-pi 1.5.0-dev.553dc518 → 1.5.0-dev.c4c8885f

package/src/resources/extensions/gsd/uok/kernel.ts

@@ -8,10 +8,16 @@ import type { AutoSession } from "../auto/session.js";
 import type { LoopDeps } from "../auto/loop-deps.js";
 import { gsdRoot } from "../paths.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
-import { setUnifiedAuditEnabled } from "./audit-toggle.js";
-import { resolveUokFlags } from "./flags.js";
+import {
+  getUnifiedAuditOverride,
+  restoreUnifiedAuditOverride,
+  setUnifiedAuditEnabled,
+  setUnifiedAuditSuppressedForBasePath,
+} from "./audit-toggle.js";
+import { resolveUokFlags, type UokFlags } from "./flags.js";
 import { createTurnObserver } from "./loop-adapter.js";
 import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
+import { logWarning } from "../workflow-logger.js";
 
 interface RunAutoLoopWithUokArgs {
   ctx: ExtensionContext;
@@ -45,80 +51,195 @@ function writeParityEvent(basePath: string, event: Record<string, unknown>): voi
   }
 }
 
+type UokKernelPathLabel = "uok-kernel" | "legacy-wrapper" | "legacy-fallback";
+
+interface UokKernelRunPlan {
+  flags: UokFlags;
+  pathLabel: UokKernelPathLabel;
+  traceId: string;
+  useKernel: boolean;
+}
+
 function resolveKernelPathLabel(
-  flags: ReturnType<typeof resolveUokFlags>,
-): "uok-kernel" | "legacy-wrapper" | "legacy-fallback" {
+  flags: UokFlags,
+): UokKernelPathLabel {
   if (flags.legacyFallback) return "legacy-fallback";
   return flags.enabled ? "uok-kernel" : "legacy-wrapper";
 }
 
-export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<void> {
-  const { ctx, pi, s, deps, runKernelLoop, runLegacyLoop } = args;
-  const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
-  const flags = resolveUokFlags(prefs);
-  setUnifiedAuditEnabled(flags.auditUnified);
+function createUokKernelRunPlan(input: {
+  preferences: ReturnType<LoopDeps["loadEffectiveGSDPreferences"]> | undefined;
+  autoStartTime?: unknown;
+}): UokKernelRunPlan {
+  const flags = resolveUokFlags(input.preferences?.preferences);
   const pathLabel = resolveKernelPathLabel(flags);
-  if (pathLabel !== "uok-kernel") {
-    incrementLegacyTelemetry("legacy.uokFallbackUsed");
-  }
-
-  writeParityEvent(s.basePath, {
-    ts: new Date().toISOString(),
-    path: pathLabel,
+  return {
     flags,
-    phase: "enter",
-  });
+    pathLabel,
+    traceId: `session:${String(input.autoStartTime || Date.now())}`,
+    useKernel: flags.enabled,
+  };
+}
+
+interface KernelAuditStateController {
+  apply(enabled: boolean): void;
+  restore(): void;
+}
+
+function createKernelAuditStateController(basePath: string): KernelAuditStateController {
+  const previousAuditOverride = getUnifiedAuditOverride();
+  return {
+    apply(enabled): void {
+      setUnifiedAuditSuppressedForBasePath(basePath, !enabled);
+      setUnifiedAuditEnabled(enabled);
+    },
+    restore(): void {
+      restoreUnifiedAuditOverride(previousAuditOverride);
+    },
+  };
+}
 
-  if (flags.auditUnified) {
+function emitKernelEnterAudit(input: {
+  basePath: string;
+  plan: UokKernelRunPlan;
+  sessionId?: string;
+}): boolean {
+  if (!input.plan.flags.auditUnified) return true;
+
+  try {
     emitUokAuditEvent(
-      s.basePath,
+      input.basePath,
       buildAuditEnvelope({
-        traceId: `session:${String(s.autoStartTime || Date.now())}`,
+        traceId: input.plan.traceId,
         category: "orchestration",
         type: "uok-kernel-enter",
         payload: {
-          flags,
-          sessionId: ctx.sessionManager?.getSessionId?.(),
+          flags: input.plan.flags,
+          sessionId: input.sessionId,
         },
       }),
     );
+    return true;
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    writeParityEvent(input.basePath, {
+      ts: new Date().toISOString(),
+      path: input.plan.pathLabel,
+      flags: input.plan.flags,
+      phase: "telemetry-error",
+      telemetry: "uok-kernel-enter",
+      error: errorMessage,
+    });
+    logWarning("db", `uok-kernel-enter audit emit failed (non-fatal): ${errorMessage}`);
+    return false;
   }
+}
 
-  const decoratedDeps: LoopDeps = flags.enabled
-    ? {
-        ...deps,
-        uokObserver: createTurnObserver({
-          basePath: s.basePath,
-          gitAction: flags.gitopsTurnAction,
-          gitPush: flags.gitopsTurnPush,
-          enableAudit: flags.auditUnified,
-          enableGitops: flags.gitops,
-        }),
-      }
-    : deps;
+function decorateLoopDepsForKernel(input: {
+  deps: LoopDeps;
+  basePath: string;
+  plan: UokKernelRunPlan;
+  auditHealthy: boolean;
+}): LoopDeps {
+  if (!input.plan.useKernel) return input.deps;
+
+  return {
+    ...input.deps,
+    uokObserver: createTurnObserver({
+      basePath: input.basePath,
+      gitAction: input.plan.flags.gitopsTurnAction,
+      gitPush: input.plan.flags.gitopsTurnPush,
+      enableAudit: input.plan.flags.auditUnified && input.auditHealthy,
+      enableGitops: input.plan.flags.gitops,
+    }),
+  };
+}
+
+async function executeKernelRunPlan(input: {
+  plan: UokKernelRunPlan;
+  ctx: ExtensionContext;
+  pi: ExtensionAPI;
+  s: AutoSession;
+  deps: LoopDeps;
+  kernelDeps: LoopDeps;
+  runKernelLoop: RunAutoLoopWithUokArgs["runKernelLoop"];
+  runLegacyLoop: RunAutoLoopWithUokArgs["runLegacyLoop"];
+}): Promise<void> {
+  if (input.plan.useKernel) {
+    await input.runKernelLoop(input.ctx, input.pi, input.s, input.kernelDeps);
+    return;
+  }
+  await input.runLegacyLoop(input.ctx, input.pi, input.s, input.deps);
+}
+
+export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<void> {
+  const { ctx, pi, s, deps, runKernelLoop, runLegacyLoop } = args;
+  const auditState = createKernelAuditStateController(s.basePath);
+  let plan: UokKernelRunPlan | null = null;
 
   try {
-    if (flags.enabled) {
-      await runKernelLoop(ctx, pi, s, decoratedDeps);
-    } else {
-      await runLegacyLoop(ctx, pi, s, deps);
+    plan = createUokKernelRunPlan({
+      preferences: deps.loadEffectiveGSDPreferences(),
+      autoStartTime: s.autoStartTime,
+    });
+    auditState.apply(plan.flags.auditUnified);
+
+    if (plan.pathLabel !== "uok-kernel") {
+      incrementLegacyTelemetry("legacy.uokFallbackUsed");
     }
+
     writeParityEvent(s.basePath, {
       ts: new Date().toISOString(),
-      path: pathLabel,
-      flags,
-      phase: "exit",
-      status: "ok",
+      path: plan.pathLabel,
+      flags: plan.flags,
+      phase: "enter",
     });
-  } catch (err) {
+
+    const auditHealthy = emitKernelEnterAudit({
+      basePath: s.basePath,
+      plan,
+      sessionId: ctx.sessionManager?.getSessionId?.(),
+    });
+    auditState.apply(plan.flags.auditUnified && auditHealthy);
+
+    const kernelDeps = decorateLoopDepsForKernel({
+      deps,
+      basePath: s.basePath,
+      plan,
+      auditHealthy,
+    });
+
+    await executeKernelRunPlan({
+      plan,
+      ctx,
+      pi,
+      s,
+      deps,
+      kernelDeps,
+      runKernelLoop,
+      runLegacyLoop,
+    });
+
     writeParityEvent(s.basePath, {
       ts: new Date().toISOString(),
-      path: pathLabel,
-      flags,
+      path: plan.pathLabel,
+      flags: plan.flags,
       phase: "exit",
-      status: "error",
-      error: err instanceof Error ? err.message : String(err),
+      status: "ok",
     });
+  } catch (err) {
+    if (plan) {
+      writeParityEvent(s.basePath, {
+        ts: new Date().toISOString(),
+        path: plan.pathLabel,
+        flags: plan.flags,
+        phase: "exit",
+        status: "error",
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
     throw err;
+  } finally {
+    auditState.restore();
   }
 }

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/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.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/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;
 

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