@opengsd/gsd-pi 1.9.0-dev.5c1a3ff2 → 1.9.0-dev.97ef11e3

package/src/resources/extensions/gsd/tests/register-hooks-loop-guard-auto.test.ts

@@ -6,8 +6,10 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 
 import { autoSession } from "../auto-runtime-state.ts";
+import { postUnitPreVerification } from "../auto-post-unit.ts";
 import { registerHooks } from "../bootstrap/register-hooks.ts";
 import { resetToolCallLoopGuard } from "../bootstrap/tool-call-loop-guard.ts";
+import { closeDatabase, openDatabase } from "../gsd-db.ts";
 import { readUnitHarnessAbort } from "../unit-runtime.ts";
 
 type Handler = (event: any, ctx?: any) => Promise<any> | any;
@@ -166,6 +168,109 @@ test("register-hooks does not record normal product tool failures as harness abo
   assert.equal(abort, null);
 });
 
+test("tool_execution_end latches a failed ScheduleWakeup across unrelated tool success", async (t) => {
+  const base = makeRuntimeBase();
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  autoSession.reset();
+  autoSession.active = true;
+  autoSession.basePath = base;
+  autoSession.currentUnit = { type: "discuss-milestone", id: "M001", startedAt: Date.now() };
+  t.after(() => {
+    closeDatabase();
+    autoSession.reset();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  const { emitToolExecutionEnd } = makeHookHarness();
+  const error = "`prompt` is required when `stop` is not true";
+
+  await emitToolExecutionEnd({
+    toolName: "ScheduleWakeup",
+    isError: true,
+    result: error,
+  });
+  assert.equal(autoSession.lastToolInvocationError, `ScheduleWakeup: ${error}`);
+
+  await emitToolExecutionEnd({
+    toolName: "read",
+    isError: false,
+    result: "file contents",
+  });
+  assert.equal(
+    autoSession.lastToolInvocationError,
+    `ScheduleWakeup: ${error}`,
+    "an unrelated success must not erase a failed continuation before the unit boundary",
+  );
+
+  await emitToolExecutionEnd({
+    toolName: "parse_payload",
+    isError: true,
+    result: "Unexpected end of JSON input",
+  });
+  assert.equal(
+    autoSession.lastToolInvocationError,
+    `ScheduleWakeup: ${error}`,
+    "a later invocation error must not replace the failed continuation",
+  );
+
+  let pauseCalled = false;
+  const notifications: Array<{ message: string; severity?: string }> = [];
+  const result = await postUnitPreVerification(
+    {
+      s: autoSession,
+      ctx: {
+        ui: {
+          notify: (message: string, severity?: string) => notifications.push({ message, severity }),
+        },
+      } as any,
+      pi: {} as any,
+      buildSnapshotOpts: () => ({}) as any,
+      lockBase: () => base,
+      stopAuto: async () => {},
+      pauseAuto: async () => { pauseCalled = true; },
+      updateProgressWidget: () => {},
+    },
+    { skipSettleDelay: true, skipWorktreeSync: true },
+  );
+
+  assert.equal(result, "dispatched");
+  assert.equal(pauseCalled, true);
+  assert.equal(autoSession.pendingVerificationRetry, null);
+  assert.ok(
+    notifications.some(({ message, severity }) => severity === "error" && message.includes(error)),
+    "the unit boundary must surface the rejected continuation",
+  );
+  assert.equal(autoSession.lastToolInvocationError, null);
+
+  await emitToolExecutionEnd({
+    toolName: "ScheduleWakeup",
+    isError: true,
+    result: error,
+  });
+  await emitToolExecutionEnd({
+    toolName: "ScheduleWakeup",
+    isError: false,
+    result: "Wakeup scheduled",
+  });
+  assert.equal(autoSession.lastToolInvocationError, null);
+});
+
+test("tool_execution_end ignores ScheduleWakeup-shaped business validation from other tools", async (t) => {
+  autoSession.reset();
+  autoSession.active = true;
+  t.after(() => autoSession.reset());
+
+  const { emitToolExecutionEnd } = makeHookHarness();
+  await emitToolExecutionEnd({
+    toolName: "submit_review",
+    isError: true,
+    result: "`prompt` is required when `stop` is not true",
+  });
+
+  assert.equal(autoSession.lastToolInvocationError, null);
+});
+
 test("register-hooks does not classify normal gsd_uat_exec nonzero exits as harness aborts", async (t) => {
   const base = makeRuntimeBase();
   const startedAt = Date.now();

package/src/resources/extensions/gsd/tests/state-reconciliation-drift.test.ts

@@ -1618,6 +1618,58 @@ test("ADR-017 (#5705): in-sync ROADMAP and DB → no roadmap-divergence drift",
   );
 });
 
+test("ADR-017 (#1370): roadmap-divergence skips completed milestone sharing active worktree phase", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-adr017-roadmap-shared-phase-"));
+  const milestoneDir = join(base, ".gsd", "phases", "06-rlrbot-m006-rlrbot-tool-registry-and-command-sa");
+  const roadmapPath = join(milestoneDir, "06-ROADMAP.md");
+  mkdirSync(milestoneDir, { recursive: true });
+  mkdirSync(join(base, ".gsd", "milestones", "M006"), { recursive: true });
+  mkdirSync(join(base, ".gsd", "milestones", "M006-rlrbot"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "milestones", "M006", "M006-META.json"), "{}\n");
+  writeFileSync(join(base, ".gsd", "milestones", "M006-rlrbot", "M006-rlrbot-META.json"), "{}\n");
+  const activeRoadmap = [
+    "# M006-rlrbot: Active worktree",
+    "",
+    "**Vision:** Keep the active worktree projection authoritative.",
+    "",
+    "## Slices",
+    "",
+    "- [ ] **S01: Shared slice** `risk:medium` `depends:[]`",
+    "  > After this: Active work remains pending.",
+    "",
+  ].join("\n");
+  writeFileSync(roadmapPath, activeRoadmap);
+  t.after(() => {
+    try { closeDatabase(); } catch { /* noop */ }
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M006", title: "Completed source", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M006", title: "Shared slice", status: "complete", risk: "medium", depends: [], demo: "Completed.", sequence: 1 });
+  insertMilestone({
+    id: "M006-rlrbot",
+    title: "Active worktree",
+    status: "active",
+    planning: { vision: "Keep the active worktree projection authoritative." },
+  });
+  insertSlice({ id: "S01", milestoneId: "M006-rlrbot", title: "Shared slice", status: "pending", risk: "medium", depends: [], demo: "Active work remains pending.", sequence: 1 });
+  insertTask({ id: "T01", sliceId: "S01", milestoneId: "M006-rlrbot", title: "Plan active work", status: "pending" });
+
+  const result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => makeState({ activeMilestone: { id: "M006-rlrbot", title: "Active worktree" } }),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(
+    result.repaired.some((d) => d.kind === "roadmap-divergence"),
+    false,
+    "completed milestone sharing the phase dir must not trigger roadmap-divergence repair",
+  );
+  assert.equal(readFileSync(roadmapPath, "utf-8"), activeRoadmap);
+});
+
 // ─── #5706: missing-completion-timestamp drift ──────────────────────────────
 
 test("ADR-017 (#5706): task with SUMMARY but null completed_at → backfilled", async (t) => {

package/src/resources/extensions/gsd/tests/stop-notice.test.ts

@@ -7,6 +7,8 @@ import assert from "node:assert/strict";
 
 import {
   formatStopNoticePrefix,
+  formatVerdictRecordedNotice,
+  formatVerdictRejectedNotice,
   isBlockedStopReason,
   stopNoticeDisplayReason,
   stopNoticeKind,
@@ -63,6 +65,17 @@ describe("emitter↔detector round-trip", () => {
     assert.ok(isBlockedNoticeMessage(message));
   });
 
+  test("verdict notices classify as terminal with rejected notices blocked", () => {
+    const recorded = formatVerdictRecordedNotice("Milestone M001 verdict: needs-attention -> pass").toLowerCase();
+    const rejected = formatVerdictRejectedNotice("No milestone validation found for M001.").toLowerCase();
+
+    assert.ok(isTerminalNotice(recorded));
+    assert.equal(isBlockedNoticeMessage(recorded), false);
+
+    assert.ok(isTerminalNotice(rejected));
+    assert.ok(isBlockedNoticeMessage(rejected));
+  });
+
   test("un-showable menu notices classify as blocked (#1294)", () => {
     // Emitted verbatim by notifyCommandMenuUnavailable (next-action-ui.ts / command-feedback.ts).
     const menuUnavailable =
@@ -80,7 +93,14 @@ describe("emitter↔detector round-trip", () => {
   });
 
   test("terminal prefixes cover the known stop vocabulary", () => {
-    for (const message of ["auto-mode stopped.", "auto-mode complete", "auto-mode idle", "no active milestone"]) {
+    for (const message of [
+      "auto-mode stopped.",
+      "auto-mode complete",
+      "auto-mode idle",
+      "no active milestone",
+      "verdict recorded: milestone m001 verdict: needs-attention -> pass",
+      "verdict rejected: unexpected argument: x",
+    ]) {
       assert.ok(TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix)), message);
     }
   });

package/src/resources/extensions/gsd/tests/terminated-transient.test.ts

@@ -17,6 +17,20 @@ test("#2309: 'terminated' errors should be classified as transient", () => {
   assert.equal("retryAfterMs" in result && result.retryAfterMs, 15_000, "'terminated' should use 15s backoff");
 });
 
+test("#1364: provider abort stop reasons should be classified as transient", () => {
+  const result = classifyError("Unhandled stop reason: abort");
+  assert.equal(isTransient(result), true, "'abort' provider errors should be transient");
+  assert.equal(result.kind, "connection", "'abort' matches connection");
+  assert.equal("retryAfterMs" in result && result.retryAfterMs, 15_000, "'abort' should use 15s backoff");
+});
+
+test("#1364: provider unknown stop reasons should be classified as transient", () => {
+  const result = classifyError("Unhandled stop reason: unknown");
+  assert.equal(isTransient(result), true, "'unknown' provider stop reasons should be transient");
+  assert.equal(result.kind, "connection", "'unknown' stop reasons match connection");
+  assert.equal("retryAfterMs" in result && result.retryAfterMs, 15_000, "'unknown' should use 15s backoff");
+});
+
 test("#2309: 'connection reset by peer' errors should be classified as transient (network)", () => {
   const result = classifyError("connection reset by peer");
   assert.equal(isTransient(result), true, "'connection reset by peer' should be transient");

package/src/resources/extensions/gsd/tests/tool-invocation-error-loop-break.test.ts

@@ -47,6 +47,7 @@ describe("#2883: tool invocation error tracking on AutoSession", () => {
 import {
   isDeterministicPolicyError,
   isPendingUserApprovalGateError,
+  isScheduleWakeupContinuationError,
   isToolInvocationError,
   isToolUnavailableError,
   isQueuedUserMessageSkip,
@@ -118,6 +119,24 @@ describe("#2883: isToolInvocationError classification", () => {
     assert.equal(isToolInvocationError("Invalid arguments for tool gsd_slice_complete"), true);
   });
 
+  test("scopes conditional required-field validation to ScheduleWakeup", () => {
+    const error = "`prompt` is required when `stop` is not true";
+
+    assert.equal(isToolInvocationError(error), false);
+    assert.equal(
+      isScheduleWakeupContinuationError("ScheduleWakeup", error),
+      true,
+    );
+    assert.equal(isScheduleWakeupContinuationError("read", error), false);
+    assert.equal(
+      isScheduleWakeupContinuationError(
+        "ScheduleWakeup",
+        "`evidence` is required when `status` is blocking",
+      ),
+      false,
+    );
+  });
+
   test("detects 'No such tool available' error", () => {
     assert.equal(isToolInvocationError("No such tool available: mcp__gsd-workflow__memory_query"), true);
   });

package/src/resources/extensions/gsd/tests/validate-milestone-prompt-verification-classes.test.ts

@@ -22,3 +22,10 @@ test("validate-milestone prompt routes verification class analysis into verifica
   assert.match(prompt, /If Reviewer C omitted a planned class, reconstruct the missing row/i);
   assert.match(prompt, /Do not call `gsd_validate_milestone` with a partial `verificationClasses` table/i);
 });
+
+test("validate-milestone prompt forbids reading phase directories as files", () => {
+  assert.match(prompt, /find \.gsd -type f/i);
+  assert.match(prompt, /\.gsd\/phases\/<NN>-<slug>\/` is a directory, not an artifact/i);
+  assert.match(prompt, /never pass a phase, slice, `tasks\/`, or `slices\/` directory/i);
+  assert.doesNotMatch(prompt, /Read a full SUMMARY under `\.gsd\/milestones\/\{\{milestoneId\}\}\/slices\/`/i);
+});

package/src/resources/extensions/gsd/tests/worktree-state-projection.test.ts

@@ -117,8 +117,8 @@ test("projectRootToWorktree projects flat-phase discuss artifacts before dispatc
     new WorktreeStateProjection().projectRootToWorktree(scope);
 
     assert.ok(
-      existsSync(join(worktree, ".gsd", "milestones", "M001", "M001-META.json")),
-      "milestone metadata is projected into the worktree",
+      !existsSync(join(worktree, ".gsd", "milestones")),
+      "stale metadata-only legacy milestones/ scaffold is not projected into the worktree",
     );
     assert.ok(
       existsSync(join(worktree, ".gsd", "phases", "01-foundation", "01-CONTEXT.md")),

package/src/resources/extensions/gsd/tests/worktree-sync-milestones.test.ts

@@ -246,6 +246,66 @@ describe('worktree-sync-milestones', async () => {
     }
   }
 
+  // ─── 7b. flat-phase sync skips empty legacy milestones root ───────────
+  console.log('\n=== 7b. flat-phase sync skips empty legacy milestones root ===');
+  {
+    const mainBase = mkdtempSync(join(tmpdir(), 'gsd-wt-sync-flat-main-'));
+    const wtBase = mkdtempSync(join(tmpdir(), 'gsd-wt-sync-flat-wt-'));
+
+    try {
+      const phaseDir = join(mainBase, '.gsd', 'phases', '01-foundation');
+      mkdirSync(phaseDir, { recursive: true });
+      mkdirSync(join(mainBase, '.gsd', 'milestones'), { recursive: true });
+      mkdirSync(join(wtBase, '.gsd'), { recursive: true });
+      writeFileSync(join(phaseDir, '01-CONTEXT.md'), '# Foundation\n');
+
+      syncGsdStateToWorktree(mainBase, wtBase);
+
+      assert.ok(
+        existsSync(join(wtBase, '.gsd', 'phases', '01-foundation', '01-CONTEXT.md')),
+        'flat-phase artifact is synced to worktree',
+      );
+      assert.ok(
+        !existsSync(join(wtBase, '.gsd', 'milestones')),
+        'empty legacy milestones/ root is not recreated in worktree',
+      );
+    } finally {
+      rmSync(mainBase, { recursive: true, force: true });
+      rmSync(wtBase, { recursive: true, force: true });
+    }
+  }
+
+  // ─── 7c. flat-phase sync skips metadata-only legacy milestone dirs ────
+  console.log('\n=== 7c. flat-phase sync skips metadata-only legacy milestone dirs ===');
+  {
+    const mainBase = mkdtempSync(join(tmpdir(), 'gsd-wt-sync-flat-meta-main-'));
+    const wtBase = mkdtempSync(join(tmpdir(), 'gsd-wt-sync-flat-meta-wt-'));
+
+    try {
+      const phaseDir = join(mainBase, '.gsd', 'phases', '01-foundation');
+      const metaDir = join(mainBase, '.gsd', 'milestones', 'M001');
+      mkdirSync(phaseDir, { recursive: true });
+      mkdirSync(metaDir, { recursive: true });
+      mkdirSync(join(wtBase, '.gsd'), { recursive: true });
+      writeFileSync(join(phaseDir, '01-CONTEXT.md'), '# Foundation\n');
+      writeFileSync(join(metaDir, 'M001-META.json'), '{"integrationBranch":"main"}\n');
+
+      syncGsdStateToWorktree(mainBase, wtBase);
+
+      assert.ok(
+        existsSync(join(wtBase, '.gsd', 'phases', '01-foundation', '01-CONTEXT.md')),
+        'flat-phase artifact is synced to worktree',
+      );
+      assert.ok(
+        !existsSync(join(wtBase, '.gsd', 'milestones')),
+        'metadata-only legacy milestones/ scaffold is not recreated in worktree',
+      );
+    } finally {
+      rmSync(mainBase, { recursive: true, force: true });
+      rmSync(wtBase, { recursive: true, force: true });
+    }
+  }
+
   // ─── 8. syncWorktreeStateBack does not copy task projections ───────────
   console.log('\n=== 8. syncWorktreeStateBack leaves task projections in worktree ===');
   {

package/src/resources/extensions/gsd/worktree-state-projection.ts

@@ -32,7 +32,7 @@ import {
 import { join } from "node:path";
 
 import { reconcileWorktreeDb } from "./gsd-db.js";
-import { resolveGsdPathContract } from "./paths.js";
+import { dirIsContentBearingLegacyMilestone, resolveGsdPathContract } from "./paths.js";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
 import type { MilestoneScope } from "./workspace.js";
 import { logError, logWarning } from "./workflow-logger.js";
@@ -161,6 +161,7 @@ function syncOtherMilestoneArtifacts(
       // additive safeCopyRecursive; skip it here to avoid redundant work.
       if (milestoneEntry.name === currentMilestoneId) continue;
       const srcMilestoneDir = join(srcMilestonesDir, milestoneEntry.name);
+      if (!dirIsContentBearingLegacyMilestone(srcMilestoneDir)) continue;
       const dstMilestoneDir = join(dstMilestonesDir, milestoneEntry.name);
 
       // Additively project the entire milestone subtree (force:false), not just
@@ -271,36 +272,32 @@ export function _projectRootToWorktreeImpl(
   // Without this, worktree-local files (e.g. VALIDATION.md written
   // by validate-milestone) get clobbered by stale project root copies,
   // causing an infinite re-validation loop (#1886).
-  safeCopyRecursive(
-    join(prGsd, "milestones", milestoneId),
-    join(wtGsd, "milestones", milestoneId),
-    { force: false },
-  );
+  const prMilestoneDir = join(prGsd, "milestones", milestoneId);
+  const wtMilestoneDir = join(wtGsd, "milestones", milestoneId);
+  if (dirIsContentBearingLegacyMilestone(prMilestoneDir)) {
+    safeCopyRecursive(prMilestoneDir, wtMilestoneDir, { force: false });
+
+    // Force-sync ASSESSMENT files that have a verdict from project root (#2821).
+    // The additive-only copy above preserves worktree-local files, but
+    // ASSESSMENT files are special: after run-uat writes a verdict and post-unit
+    // syncs it to the project root, the worktree may retain a stale copy (e.g.
+    // verdict:fail while the project root has verdict:pass from a retry). On
+    // session resume the DB is rebuilt from disk, and if the stale ASSESSMENT
+    // persists, checkNeedsRunUat finds no passing verdict → re-dispatches
+    // run-uat indefinitely (stuck-loop ×9).
+    forceOverwriteValidationWithVerdict(prMilestoneDir, wtMilestoneDir, milestoneId);
+    forceOverwriteAssessmentsWithVerdict(prMilestoneDir, wtMilestoneDir);
+  }
 
-  // Additively project the full subtree of every OTHER milestone so
-  // worktree-bound units can read prior-milestone context artifacts and so
-  // completed milestones retain their per-slice/per-task SUMMARY.md and
-  // UAT.md on the worktree filesystem (otherwise the stale-render detector
-  // flags them as "complete in DB but missing on disk").
+  // Additively project the full subtree of every OTHER content-bearing legacy
+  // milestone so worktree-bound units can read prior-milestone context artifacts
+  // without recreating empty/meta-only milestones/ scaffolds in flat-phase projects.
   syncOtherMilestoneArtifacts(
     join(prGsd, "milestones"),
     join(wtGsd, "milestones"),
     milestoneId,
   );
 
-  // Force-sync ASSESSMENT files that have a verdict from project root (#2821).
-  // The additive-only copy above preserves worktree-local files, but
-  // ASSESSMENT files are special: after run-uat writes a verdict and post-unit
-  // syncs it to the project root, the worktree may retain a stale copy (e.g.
-  // verdict:fail while the project root has verdict:pass from a retry). On
-  // session resume the DB is rebuilt from disk, and if the stale ASSESSMENT
-  // persists, checkNeedsRunUat finds no passing verdict → re-dispatches
-  // run-uat indefinitely (stuck-loop ×9).
-  const prMilestoneDir = join(prGsd, "milestones", milestoneId);
-  const wtMilestoneDir = join(wtGsd, "milestones", milestoneId);
-  forceOverwriteValidationWithVerdict(prMilestoneDir, wtMilestoneDir, milestoneId);
-  forceOverwriteAssessmentsWithVerdict(prMilestoneDir, wtMilestoneDir);
-
   // Forward-sync completed-units.json from project root to worktree.
   // Project root is authoritative for completion state after crash recovery;
   // without this, the worktree re-dispatches already-completed units (#1886).

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

@@ -252,6 +252,11 @@ export async function showInterviewRound(
 		let previewTotal = 0;
 		function resetPreviewScroll() { previewScroll = 0; }
 
+		let optionsScroll = 0;
+		let optionsViewport = 0;
+		let optionsTotal = 0;
+		function resetOptionsScroll() { optionsScroll = 0; }
+
 		function finish(result: RoundResult) {
 			if (completed) return;
 			completed = true;
@@ -318,6 +323,7 @@ export async function showInterviewRound(
 			saveEditorToState();
 			currentIdx = newIdx;
 			resetPreviewScroll();
+			resetOptionsScroll();
 			loadStateToEditor();
 			focusNotes = states[currentIdx].notesVisible && states[currentIdx].notes.length > 0;
 			refresh();
@@ -464,20 +470,39 @@ export async function showInterviewRound(
 				if (matchesKey(data, Key.right)) { switchQuestion((currentIdx + 1) % questions.length); return; }
 			}
 
-			// ── Preview scrolling ────────────────────────────────────────
+			// ── Side-by-side panel scrolling ─────────────────────────────
 			if (matchesKey(data, Key.pageUp)) {
-				if (previewScroll > 0) { previewScroll = Math.max(0, previewScroll - previewViewport); refresh(); }
+				let didScroll = false;
+				if (optionsScroll > 0) {
+					optionsScroll = Math.max(0, optionsScroll - optionsViewport);
+					didScroll = true;
+				}
+				if (previewScroll > 0) {
+					previewScroll = Math.max(0, previewScroll - previewViewport);
+					didScroll = true;
+				}
+				if (didScroll) refresh();
 				return;
 			}
 			if (matchesKey(data, Key.pageDown)) {
+				let didScroll = false;
+				const maxOptionsScroll = Math.max(0, optionsTotal - optionsViewport);
+				if (optionsScroll < maxOptionsScroll) {
+					optionsScroll = Math.min(maxOptionsScroll, optionsScroll + optionsViewport);
+					didScroll = true;
+				}
 				const maxScroll = Math.max(0, previewTotal - previewViewport);
-				if (previewScroll < maxScroll) { previewScroll = Math.min(maxScroll, previewScroll + previewViewport); refresh(); }
+				if (previewScroll < maxScroll) {
+					previewScroll = Math.min(maxScroll, previewScroll + previewViewport);
+					didScroll = true;
+				}
+				if (didScroll) refresh();
 				return;
 			}
 
 			// ── Cursor navigation ────────────────────────────────────────
-			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 (matchesKey(data, Key.up)) { st.cursorIndex = (st.cursorIndex - 1 + optCount) % optCount; resetPreviewScroll(); resetOptionsScroll(); refresh(); return; }
+			if (matchesKey(data, Key.down)) { st.cursorIndex = (st.cursorIndex + 1) % optCount; resetPreviewScroll(); resetOptionsScroll(); refresh(); return; }
 
 			if (multiSel) {
 				const doneI = noneOrDoneIdx(currentIdx);
@@ -695,6 +720,8 @@ export async function showInterviewRound(
 			// No scrollable preview unless the side-by-side path sets these below.
 			previewTotal = 0;
 			previewViewport = 0;
+			optionsTotal = 0;
+			optionsViewport = 0;
 
 			if (useSideBySide) {
 				// ── Preview path ──────────────────────────────────────
@@ -734,10 +761,21 @@ export async function showInterviewRound(
 				const leftWidth = Math.max(MIN_OPTIONS_WIDTH, contentWidth - previewWidth - DIVIDER_WIDTH);
 
 				const fullLeft = renderOptionsColumn(leftWidth);
-				const leftLines = fullLeft.slice(0, maxBody);
+				optionsTotal = fullLeft.length;
+				optionsViewport = maxBody;
+				const maxOptionsScroll = Math.max(0, fullLeft.length - maxBody);
+				if (optionsScroll > maxOptionsScroll) optionsScroll = maxOptionsScroll;
+
+				const leftLines = fullLeft.slice(optionsScroll, optionsScroll + maxBody);
 				if (fullLeft.length > maxBody) {
-					const n = fullLeft.length - maxBody + 1;
-					leftLines[maxBody - 1] = scrollIndicator(`+${n} lines hidden`, leftWidth);
+					const hiddenAbove = optionsScroll;
+					const hiddenBelow = fullLeft.length - (optionsScroll + maxBody);
+					if (hiddenAbove > 0) {
+						leftLines[0] = scrollIndicator(`▲ ${hiddenAbove} more`, leftWidth);
+					}
+					if (hiddenBelow > 0) {
+						leftLines[leftLines.length - 1] = scrollIndicator(`▼ ${hiddenBelow} more · PgUp/PgDn`, leftWidth);
+					}
 				}
 
 				const preview = getCurrentPreview();
@@ -791,6 +829,7 @@ export async function showInterviewRound(
 					hints.push(isLast && allAnswered() ? "enter to review" : "enter to next");
 				}
 				if (previewTotal > previewViewport) hints.push("pgup/pgdn scroll preview");
+				if (optionsTotal > optionsViewport) hints.push("pgup/pgdn scroll options");
 				hints.push("esc to exit");
 				const footer = ui.hints(hints)[0] ?? "";
 

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

@@ -192,4 +192,33 @@ describe("interview-ui dialog borders", () => {
 		const back = stripAnsi(widget.render(100).join("\n"));
 		assert.doesNotMatch(back, /▲ \d+ more/, "top indicator should disappear after scrolling back to top");
 	});
+
+	it("makes overflowing side-by-side options scrollable with PgUp/PgDn", async () => {
+		const overflowOptions = Array.from({ length: 8 }, (_, i) => ({
+			label: `Overflow Option ${i + 1}`,
+			description: `Detailed explanation for option ${i + 1} that is intentionally long enough to wrap in the options column and force vertical overflow.`,
+			...(i === 0 ? { preview: "Short preview" } : {}),
+		}));
+		const widget = await captureInterviewWidget([{
+			...questions[0],
+			options: overflowOptions,
+		}]);
+
+		const initial = stripAnsi(widget.render(100).join("\n"));
+		assertFullOuterBorder(widget.render(100), 100);
+		assert.match(initial, /▼ \d+ more/, "bottom scroll indicator should appear when options overflow");
+		assert.match(initial, /pgup\/pgdn scroll options/, "footer should hint at options scrolling");
+		assert.doesNotMatch(initial, /\+\d+ lines hidden/, "options overflow should not be a dead-end hidden-lines marker");
+		assert.doesNotMatch(initial, /▲ \d+ more/, "top indicator should be absent before scrolling");
+
+		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 options");
+
+		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");
+	});
 });