gentle-pi 3.7.0 → 4.0.0

package/tests/history-off-path.test.ts

@@ -0,0 +1,170 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import promptHistoryExtension from "../extensions/history/index.ts";
+import { writeHistoryCapturePolicy } from "../lib/history-capture-policy.ts";
+
+// The module-level selector gate reads process.env directly (that path has
+// no deps.env injection); keep the suite hermetic regardless of the ambient
+// shell so the off-path assertions cannot be flipped by the environment.
+delete process.env.GENTLE_PI_HISTORY_CAPTURE;
+
+function makeRoot(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-off-"));
+}
+
+const CWD = "/pi-history-test/project-off";
+
+interface Harness {
+  commandHandler: (args: unknown, ctx: unknown) => Promise<void>;
+}
+
+/**
+ * Load the extension against a temp root and capture the registered
+ * shortcut + history command handlers from the fake pi.
+ */
+function loadWithCommand(
+  env: NodeJS.ProcessEnv,
+  root: string,
+  configHome: string = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-off-config-")),
+): Harness {
+  const shortcuts: Array<[string, { handler: unknown }]> = [];
+  const commands: Array<[string, { handler: unknown }]> = [];
+  const pi = {
+    on: () => {},
+    registerShortcut: (key: string, def: { handler: unknown }) => {
+      shortcuts.push([key, def]);
+    },
+    registerCommand: (name: string, def: { handler: unknown }) => {
+      commands.push([name, def]);
+    },
+  };
+  promptHistoryExtension(pi as never, {
+    env,
+    root,
+    cwd: CWD,
+    instanceId: "inst-off",
+    now: () => 1700000000000,
+    // Keep any opted-in warm-up away from the real ~/.pi/agent.
+    agentDir: path.join(root, "agent"),
+    sessionsRoot: path.join(root, "sessions"),
+    // An empty config home by default: the Customize preference is unset (off).
+    gentlePiConfigHome: configHome,
+  });
+  const command = commands.find(([name]) => name === "history");
+  assert.ok(command, "the history command must be registered");
+  assert.equal(shortcuts.length, 1, "the shortcut must still be registered");
+  return {
+    commandHandler: command[1].handler as Harness["commandHandler"],
+  };
+}
+
+function fakeCtx(notifyCalls: Array<[string, string]>) {
+  return {
+    ui: {
+      notify: (message: string, level: string) => {
+        notifyCalls.push([message, level]);
+      },
+    },
+  };
+}
+
+// The open flow reads the injected deps (env/root/cwd), never the module
+// defaults, so the enabled direction is testable against a temp root too.
+
+test("with capture disabled, extension load writes nothing", async () => {
+  const root = makeRoot();
+  loadWithCommand({}, root);
+  // Flush the setImmediate warm-up.
+  await new Promise((resolve) => setImmediate(resolve));
+  // Nothing at all: no registry, no seed, no store file.
+  assert.deepEqual(fs.readdirSync(root), []);
+});
+
+test("with capture disabled, the history command imports nothing and warns", async () => {
+  const root = makeRoot();
+  const { commandHandler } = loadWithCommand({}, root);
+  await new Promise((resolve) => setImmediate(resolve));
+  const notifyCalls: Array<[string, string]> = [];
+  await commandHandler([], fakeCtx(notifyCalls));
+  assert.equal(notifyCalls.length, 1);
+  assert.equal(notifyCalls[0][1], "warning");
+  assert.ok(
+    notifyCalls[0][0].includes("GENTLE_PI_HISTORY_CAPTURE"),
+    `the warning must name the switch, got: ${notifyCalls[0][0]}`,
+  );
+  assert.ok(
+    notifyCalls[0][0].includes("Gentle → Customize"),
+    `the warning must name the Customize control, got: ${notifyCalls[0][0]}`,
+  );
+  // The gate must fire before the drain: no migration, no seed, no store.
+  assert.deepEqual(fs.readdirSync(root), []);
+});
+
+test("with capture enabled, opening the selector reads without initializing the store", async () => {
+  const root = makeRoot();
+  const { commandHandler } = loadWithCommand({ GENTLE_PI_HISTORY_CAPTURE: "1" }, root);
+  // Open before the opted-in warm-up tick: the open flow alone must not
+  // migrate, register, seed, or create a capture file.
+  const notifyCalls: Array<[string, string]> = [];
+  await commandHandler([], fakeCtx(notifyCalls));
+  assert.deepEqual(notifyCalls, [["No prompt history available.", "warning"]]);
+  assert.deepEqual(fs.readdirSync(root), []);
+});
+
+test("the Customize preference opens the selector without the env switch", async () => {
+  const root = makeRoot();
+  const configHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-off-config-"));
+  const { commandHandler } = loadWithCommand({}, root, configHome);
+  const notifyCalls: Array<[string, string]> = [];
+  await commandHandler([], fakeCtx(notifyCalls));
+  assert.equal(notifyCalls[0][1], "warning");
+  assert.match(notifyCalls[0][0], /disabled/);
+  // The same loaded extension honors a later toggle without restart.
+  writeHistoryCapturePolicy("on", { gentlePiConfigHome: configHome });
+  await commandHandler([], fakeCtx(notifyCalls));
+  assert.deepEqual(notifyCalls[1], ["No prompt history available.", "warning"]);
+});
+
+test("an explicit env off names the override instead of the Customize fix", async () => {
+  const root = makeRoot();
+  const configHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-off-config-"));
+  writeHistoryCapturePolicy("on", { gentlePiConfigHome: configHome });
+  const { commandHandler } = loadWithCommand({ GENTLE_PI_HISTORY_CAPTURE: "false" }, root, configHome);
+  const notifyCalls: Array<[string, string]> = [];
+  await commandHandler([], fakeCtx(notifyCalls));
+  assert.equal(notifyCalls.length, 1);
+  assert.match(notifyCalls[0][0], /disabled by GENTLE_PI_HISTORY_CAPTURE, which overrides the Gentle → Customize → History preference/);
+  assert.deepEqual(fs.readdirSync(root), []);
+});
+
+test("a malformed Customize preference is reported as invalid, not just off", async () => {
+  const root = makeRoot();
+  const configHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-off-config-"));
+  const preference = path.join(configHome, "history-capture.json");
+  fs.writeFileSync(preference, "{not json", "utf8");
+  const { commandHandler } = loadWithCommand({}, root, configHome);
+  const notifyCalls: Array<[string, string]> = [];
+  await commandHandler([], fakeCtx(notifyCalls));
+  assert.equal(notifyCalls.length, 1);
+  assert.equal(notifyCalls[0][1], "warning");
+  assert.match(notifyCalls[0][0], /Gentle → Customize → History preference is invalid or unreadable/);
+  assert.ok(notifyCalls[0][0].includes(preference), `the warning must name the file, got: ${notifyCalls[0][0]}`);
+  assert.ok(notifyCalls[0][0].includes("GENTLE_PI_HISTORY_CAPTURE=1"));
+  // Reporting never repairs: the malformed file and the store stay untouched.
+  assert.equal(fs.readFileSync(preference, "utf8"), "{not json");
+  assert.deepEqual(fs.readdirSync(root), []);
+});
+
+test("an env value that defers to a malformed preference still reports it", async () => {
+  const root = makeRoot();
+  const configHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-off-config-"));
+  fs.writeFileSync(path.join(configHome, "history-capture.json"), "[]", "utf8");
+  const { commandHandler } = loadWithCommand({ GENTLE_PI_HISTORY_CAPTURE: "maybe" }, root, configHome);
+  const notifyCalls: Array<[string, string]> = [];
+  await commandHandler([], fakeCtx(notifyCalls));
+  assert.equal(notifyCalls.length, 1);
+  assert.match(notifyCalls[0][0], /preference is invalid or unreadable/);
+});

package/tests/history-openflow-integration.test.ts

@@ -0,0 +1,173 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Stage-1 open-flow wiring tests (a22588fc T31/T32 port, adapted to the
+ * slice-02 DrainResult drain contract). NEVER import
+ * extensions/history/index.ts — it pulls the pi-tui runtime graph (§D3).
+ * The wiring is pinned by source-parse (command-registration pattern);
+ * loader behavior uses fs-only fixtures under the OS temp dir — NEVER the
+ * user's real ~/.pi/agent/history.
+ */
+
+const indexSource = fs.readFileSync(
+  fileURLToPath(new URL("../extensions/history/index.ts", import.meta.url)),
+  "utf8",
+);
+
+function openHistorySelectorBody(): string {
+  const start = indexSource.indexOf("async function openHistorySelector(");
+  assert.ok(start >= 0, "openHistorySelector should exist");
+  const end = indexSource.indexOf("export default function", start);
+  assert.ok(end > start, "extension entry point should follow");
+  return indexSource.slice(start, end);
+}
+
+// ---------------------------------------------------------------------------
+// T31 (adapted) — store-only drain wiring over the DrainResult contract.
+// ---------------------------------------------------------------------------
+
+test("T31 (adapted): the store drain is the entries source — DrainResult unwrapped", () => {
+  const body = openHistorySelectorBody();
+  const drainIdx = body.indexOf('const drained = drainForScope("project")');
+  assert.ok(
+    drainIdx >= 0,
+    "the load step must drain the store through drainForScope",
+  );
+  assert.ok(
+    !body.includes("mergeHistoryEntries("),
+    "no live transcript merge in the open flow (store-only scopes)",
+  );
+  assert.ok(
+    body.includes('drained.status === "blocked"'),
+    "the DrainResult blocked variant must be unwrapped before any records build",
+  );
+  assert.ok(
+    body.includes("const entries = drained.prompts"),
+    "the ok variant feeds the entries list",
+  );
+});
+
+test("T31 (adapted): records are built via recordsFromEntries over the drained entries", () => {
+  const body = openHistorySelectorBody();
+  const recIdx = body.indexOf("recordsFromEntries(entries)");
+  assert.ok(
+    recIdx >= 0,
+    "records build through the shared recordsFromEntries helper",
+  );
+});
+
+test("T31: the command-registration pins hold beside the drain contract", () => {
+  const definitions =
+    indexSource.split("async function openHistorySelector(").length - 1;
+  assert.equal(definitions, 1, "openHistorySelector defined exactly once");
+  const calls = indexSource.split("openHistorySelector(ctx)").length - 1;
+  assert.equal(
+    calls,
+    2,
+    "exactly the two entry-point call sites — the drain contract adds no occurrence",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// T32 (adapted) — synchronous open-path wiring (no-await source-parse).
+// ---------------------------------------------------------------------------
+
+test("T32 (adapted): the open path never awaits a records build (source-parse)", () => {
+  const body = openHistorySelectorBody();
+  assert.ok(
+    !body.includes("startBackgroundIndexBuild"),
+    "no background build kick lives in the selector",
+  );
+  assert.ok(
+    !/await\s+recordsFromEntries/.test(body),
+    "the open path never awaits the records build (sync const declaration)",
+  );
+  const drainIdx = body.indexOf('drainForScope("project")');
+  const emptyIdx = body.indexOf("entries.length === 0");
+  assert.ok(
+    drainIdx >= 0 && emptyIdx > drainIdx,
+    "the empty guard follows the drain",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Stage-1 skeleton pins: the minimal openable unit and its policy seams.
+// ---------------------------------------------------------------------------
+
+test("the stage-1 selector skeleton wires cancel through the overlay close", () => {
+  assert.ok(
+    indexSource.includes('kb.matches(_d, "tui.select.cancel")'),
+    "the dispatch table handles cancel",
+  );
+  assert.ok(
+    indexSource.includes("this.onCancel()"),
+    "cancel routes to the overlay close callback",
+  );
+});
+
+test("the selection result pastes into the editor via pasteToEditor", () => {
+  const body = openHistorySelectorBody();
+  assert.ok(
+    body.includes("ctx.ui.pasteToEditor(selected.text)"),
+    "the selected prompt enters the editor through the paste pipeline (a22588fc)",
+  );
+});
+
+/** Method body slice (lazy-windowing.test.ts pattern; first "\n  }" close). */
+function methodBodyOf(name: string): string {
+  const decl = indexSource.indexOf(`private ${name}(`);
+  assert.ok(decl >= 0, `private ${name}() should exist in extensions/history/index.ts`);
+  const end = indexSource.indexOf("\n  }", decl);
+  assert.ok(end > decl, `private ${name}() body should close`);
+  return indexSource.slice(decl, end);
+}
+
+// ---------------------------------------------------------------------------
+// T33 — AC-S6-3: merged header totals + third transient dim indexing segment.
+// ---------------------------------------------------------------------------
+
+test("T33 (AC-S6-3): header totals derive from filteredRecords — derivation untouched", () => {
+  const body = methodBodyOf("rebuildListWithWidth");
+  assert.ok(
+    body.includes("const count = this.filteredRecords.length;"),
+    "N derives from filteredRecords (merged by construction)",
+  );
+});
+
+test("T33 (AC-S6-3): loaded segment present, indexing segment removed", () => {
+  const body = methodBodyOf("rebuildListWithWidth");
+  const setTextAt = body.indexOf("headerRow.setText(");
+  assert.ok(setTextAt >= 0, "the header must keep the existing setText call");
+  const setTextRegion = body.slice(
+    setTextAt,
+    body.indexOf("this.listContainer.clear()"),
+  );
+  assert.ok(
+    setTextRegion.includes("loaded ") &&
+      setTextRegion.includes("this.loadedCount"),
+    "the loaded segment stays (user-restored)",
+  );
+  assert.ok(
+    !setTextRegion.includes("indexing "),
+    "the indexing segment stays removed",
+  );
+});
+
+test("T33 (AC-S6-3): Change 2 structural pins still hold beside the third segment", () => {
+  assert.ok(
+    indexSource.includes("private static readonly OVERLAY_LINES = 30;"),
+    "OVERLAY_LINES = 30 intact",
+  );
+  const body = methodBodyOf("rebuildListWithWidth");
+  const addChildCount = body.split("addChild(").length - 1;
+  assert.equal(addChildCount, 4, "no new addChild in rebuildListWithWidth");
+  const classAt = indexSource.indexOf("class PromptHistorySelector");
+  const ctorAt = indexSource.indexOf("constructor(", classAt);
+  const ctorEnd = indexSource.indexOf('this.applyFilter("")', ctorAt);
+  const ctorAddChild =
+    indexSource.slice(ctorAt, ctorEnd).split("this.addChild(").length - 1;
+  assert.equal(ctorAddChild, 14, "the constructor child sequence is unchanged");
+});

package/tests/history-overlay-margin.test.ts

@@ -0,0 +1,326 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { TUI } from "@earendil-works/pi-tui";
+import promptHistoryExtension from "../extensions/history/index.ts";
+import {
+  editorOverlayMargin,
+  SIDEBAR_OVERLAY_PADDING,
+} from "../extensions/history/selector-helpers.ts";
+import { projectHash } from "../extensions/history/store.ts";
+import {
+  installSidebar,
+  SIDEBAR_RAIL_COLUMNS,
+} from "../lib/shell-sidebar-layout.ts";
+import { sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
+
+// Sidebar-aware overlay margin (restored from Carolina's #1394 work,
+// e2cca1f9b^). The history extension reads the terminal-owned sidebar state
+// contract (lib/shell-sidebar.ts) without importing gentle-shell; the rail
+// width comes from the published `railColumns` field instead of a constant
+// duplicated in the history extension.
+
+function terminalWithState(state: unknown): object {
+  return {
+    [Symbol.for("gentle-pi.experimental-sidebar.state")]: state,
+  } as object;
+}
+
+const OWNING = {
+  active: true,
+  ownsHost: () => true,
+  railColumns: SIDEBAR_RAIL_COLUMNS,
+};
+
+test("the published rail reservation pins the gentle-shell rail geometry (RAIL_WIDTH 50 + GAP 3)", () => {
+  assert.equal(SIDEBAR_RAIL_COLUMNS, 53);
+});
+
+test("padding constant pins the user-directed 1-column breathing room", () => {
+  assert.equal(SIDEBAR_OVERLAY_PADDING, 1);
+});
+
+test("returns 0 for absent, primitive, or null terminals", () => {
+  assert.equal(editorOverlayMargin(undefined), 0);
+  assert.equal(editorOverlayMargin(null), 0);
+  assert.equal(editorOverlayMargin(42), 0);
+  assert.equal(editorOverlayMargin("terminal"), 0);
+});
+
+test("returns 0 when no sidebar state is stored on the terminal", () => {
+  assert.equal(editorOverlayMargin({}), 0);
+});
+
+test("returns 0 for malformed state shapes", () => {
+  assert.equal(editorOverlayMargin(terminalWithState(undefined)), 0);
+  assert.equal(editorOverlayMargin(terminalWithState(null)), 0);
+  assert.equal(editorOverlayMargin(terminalWithState("active")), 0);
+});
+
+test("returns 0 unless active is exactly true AND ownsHost is a function", () => {
+  assert.equal(
+    editorOverlayMargin(terminalWithState({ ...OWNING, ownsHost: undefined })),
+    0,
+    "active without ownsHost",
+  );
+  assert.equal(
+    editorOverlayMargin(terminalWithState({ ...OWNING, active: false })),
+    0,
+    "inactive",
+  );
+  assert.equal(
+    editorOverlayMargin(terminalWithState({ ...OWNING, active: 1 })),
+    0,
+    "non-boolean truthy active",
+  );
+  assert.equal(
+    editorOverlayMargin(
+      terminalWithState({ ...OWNING, ownsHost: "not-a-function" }),
+    ),
+    0,
+    "non-function ownsHost",
+  );
+});
+
+test("returns 0 unless the sidebar publishes a positive integer rail reservation", () => {
+  for (const railColumns of [undefined, 0, -53, 53.5, "53", Number.NaN]) {
+    assert.equal(
+      editorOverlayMargin(terminalWithState({ ...OWNING, railColumns })),
+      0,
+      `railColumns ${String(railColumns)}`,
+    );
+  }
+});
+
+test("returns the rail reservation plus padding only while the sidebar owns the host", () => {
+  assert.equal(editorOverlayMargin(terminalWithState(OWNING)), 54);
+  assert.equal(
+    editorOverlayMargin(terminalWithState({ ...OWNING, railColumns: 40 })),
+    41,
+    "the margin follows the published reservation",
+  );
+  assert.equal(
+    editorOverlayMargin(
+      terminalWithState({ ...OWNING, ownsHost: () => false }),
+    ),
+    0,
+    "state present but host not owned (regular mode / unpatched root)",
+  );
+});
+
+test("a throwing ownsHost degrades to 0 instead of breaking the picker", () => {
+  assert.equal(
+    editorOverlayMargin(
+      terminalWithState({
+        ...OWNING,
+        ownsHost: () => {
+          throw new Error("boom");
+        },
+      }),
+    ),
+    0,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Seam: the real gentle-shell sidebar publishes the reservation it paints.
+// ---------------------------------------------------------------------------
+
+const NODE = Symbol.for("@earendil-works/pi-tui/layout-node");
+const shellTheme = {
+  fg: (_color: string, text: string) => text,
+  bold: (text: string) => text,
+};
+
+function sidebarHost(columns: number) {
+  const root = {
+    render: () => ["transcript"],
+    invalidate() {},
+    [NODE]: () => ({ type: "vstack", entries: [] }),
+  };
+  const host = {
+    mode: "fullscreen",
+    terminal: { columns },
+    layoutRoot: root,
+    requestRender() {},
+  };
+  const tui = host as unknown as TUI;
+  sidebarPart(tui, "footer", {
+    render: (_width: number) => ["Status"],
+    invalidate() {},
+  });
+  return { host, tui, root };
+}
+
+test("the installed sidebar publishes its rail reservation; the margin tracks the breakpoint", (t) => {
+  const { host, tui, root } = sidebarHost(140);
+  t.after(installSidebar(tui, shellTheme));
+  assert.equal(sidebarState(tui).railColumns, SIDEBAR_RAIL_COLUMNS);
+  root[NODE]();
+  assert.equal(
+    editorOverlayMargin(host.terminal),
+    SIDEBAR_RAIL_COLUMNS + SIDEBAR_OVERLAY_PADDING,
+    "fullscreen at the breakpoint with a painting rail",
+  );
+  host.terminal.columns = 139;
+  root[NODE]();
+  assert.equal(editorOverlayMargin(host.terminal), 0, "below the breakpoint");
+});
+
+// ---------------------------------------------------------------------------
+// Overlay options: the picker re-reads the margin on every render pass.
+// ---------------------------------------------------------------------------
+
+const CWD = "/pi-history-fixtures/project-overlay-margin";
+
+interface OverlayOptions {
+  anchor?: string;
+  width?: string;
+  offsetY?: number;
+  margin?: { right: number };
+  visible?: (columns: number, rows: number) => boolean;
+}
+
+async function captureOverlayOptions(terminal: object): Promise<OverlayOptions> {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-margin-"));
+  const dir = path.join(root, "projects", projectHash(CWD));
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, "store.jsonl"),
+    `${JSON.stringify({ v: 1, text: "p00", ts: 1_700_000_000_000 })}\n`,
+  );
+  const commands: Array<[string, { handler: unknown }]> = [];
+  promptHistoryExtension(
+    {
+      on: () => {},
+      registerShortcut: () => {},
+      registerCommand: (name: string, def: { handler: unknown }) => {
+        commands.push([name, def]);
+      },
+    } as never,
+    {
+      env: { GENTLE_PI_HISTORY_CAPTURE: "1" },
+      gentlePiConfigHome: fs.mkdtempSync(
+        path.join(os.tmpdir(), "pi-history-margin-config-"),
+      ),
+      root,
+      cwd: CWD,
+      instanceId: "inst-margin",
+      agentDir: path.join(root, "agent"),
+      sessionsRoot: path.join(root, "sessions"),
+    },
+  );
+  const command = commands.find(([name]) => name === "history");
+  assert.ok(command, "the history command must be registered");
+  const handler = command[1].handler as (
+    args: unknown,
+    ctx: unknown,
+  ) => Promise<void>;
+  let captured: OverlayOptions | undefined;
+  const plain = (_color: string, text: string) => text;
+  await handler([], {
+    ui: {
+      notify: (message: string) => assert.fail(`unexpected: ${message}`),
+      pasteToEditor: () => {},
+      custom: (
+        factory: (
+          tui: unknown,
+          theme: unknown,
+          keybindings: unknown,
+          done: (result: unknown) => void,
+        ) => unknown,
+        options: { overlayOptions?: OverlayOptions | (() => OverlayOptions) },
+      ) => {
+        // Mount first, like pi: the factory captures the TUI handle, then
+        // the host resolves the overlay options.
+        factory(
+          { requestRender: () => {}, terminal },
+          { fg: plain, bg: plain, bold: (text: string) => text },
+          undefined,
+          () => {},
+        );
+        const resolved = options.overlayOptions;
+        captured = typeof resolved === "function" ? resolved() : resolved;
+        return Promise.resolve(null);
+      },
+    },
+  });
+  assert.ok(captured, "the selector must pass overlay options");
+  return captured;
+}
+
+test("the picker keeps the native full-window overlay without a painting sidebar", async () => {
+  const options = await captureOverlayOptions({});
+  assert.equal(options.anchor, "bottom-center");
+  assert.equal(options.width, "100%");
+  assert.equal(options.offsetY, 5);
+  assert.equal(options.margin, undefined);
+  assert.equal(options.visible?.(200, 50), true);
+});
+
+test("the picker margin stays live while the overlay is open", async () => {
+  const state = { ...OWNING };
+  const options = await captureOverlayOptions(terminalWithState(state));
+  assert.deepEqual(options.margin, { right: 54 });
+  // Resizing below the breakpoint: pi-tui calls visible() on every render
+  // pass, then re-reads margin while resolving the layout.
+  state.active = false;
+  assert.equal(options.visible?.(139, 50), true);
+  assert.equal(options.margin, undefined);
+  state.active = true;
+  assert.equal(options.visible?.(140, 50), true);
+  assert.deepEqual(options.margin, { right: 54 });
+});
+
+// Review advisory A4 (#1480): the live margin must follow the REAL installed
+// sidebar after the overlay opened, not only a hand-built state object.
+test("the open picker's margin follows the real sidebar across the breakpoint and teardown", async (t) => {
+  const { host, tui, root } = sidebarHost(139);
+  let uninstall = installSidebar(tui, shellTheme);
+  t.after(() => uninstall());
+  root[NODE]();
+  const options = await captureOverlayOptions(host.terminal);
+  assert.equal(options.margin, undefined, "opened below the breakpoint: no rail");
+
+  // Widening across the breakpoint paints the rail while the picker is open.
+  host.terminal.columns = 140;
+  root[NODE]();
+  assert.equal(options.visible?.(140, 50), true);
+  assert.deepEqual(options.margin, {
+    right: SIDEBAR_RAIL_COLUMNS + SIDEBAR_OVERLAY_PADDING,
+  });
+
+  // Narrowing below it removes the rail again.
+  host.terminal.columns = 139;
+  root[NODE]();
+  assert.equal(options.visible?.(139, 50), true);
+  assert.equal(options.margin, undefined);
+
+  // Back at the breakpoint, then the sidebar is torn down: the rail
+  // disappears and the picker returns to the full window.
+  host.terminal.columns = 140;
+  root[NODE]();
+  assert.equal(options.visible?.(140, 50), true);
+  assert.deepEqual(options.margin, {
+    right: SIDEBAR_RAIL_COLUMNS + SIDEBAR_OVERLAY_PADDING,
+  });
+  uninstall();
+  uninstall = () => {};
+  assert.equal(options.visible?.(140, 50), true);
+  assert.equal(options.margin, undefined);
+});
+
+test("the margin getter reports the value refreshed by the last visible() pass", async () => {
+  const state = { ...OWNING };
+  const options = await captureOverlayOptions(terminalWithState(state));
+  assert.deepEqual(options.margin, { right: 54 });
+  // pi-tui re-reads margin several times per layout; between visible()
+  // passes every read agrees, and the next pass picks up the change.
+  state.active = false;
+  assert.deepEqual(options.margin, { right: 54 });
+  assert.equal(options.visible?.(139, 50), true);
+  assert.equal(options.margin, undefined);
+  assert.equal(options.margin, undefined);
+});