@pi-archimedes/core 2.10.4 → 2.11.1

package/src/log-discipline.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect } from "vitest";
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ── The rule ────────────────────────────────────────────────────────────────
+//
+// Nothing in the suite writes to the console. Two independent reasons:
+//
+// 1. On fullscreen screen a stray `console.*` lands inside the differential
+//    frame and smears the viewport until the next full redraw (on regular
+//    screen it scrolls away unseen, which is why the habit survived so long).
+// 2. Inside a subagent child every write is silently discarded:
+//    `subagent/src/stream.ts` drops any non-JSON stdout line (`catch { return }`,
+//    a guard for pi's own startup messages), so a warning vanishes exactly when
+//    someone is debugging a child run.
+//
+// Diagnostics go to `diag()` in `log.ts` (a file, only when PI_ARCHIMEDES_LOG
+// names one) and messages the user must see go to the notification surface
+// (`ctx.ui.notify`). Both are safe on every screen and in a child process.
+//
+// The pattern demands the open parenthesis, so it is narrower than a loose
+// `grep console.log`: a monkey-patch site (`console.log = (…) => {…}`,
+// `let orig: typeof console.log`) is not a write and is not reported here.
+//
+// Every *method* is covered, not just log/warn/error. `console.info` and
+// `console.debug` land on stdout/stderr exactly like `console.log`, and
+// `console.trace`/`dir`/`table`/`group`/`count`/`clear` write too (and `clear`
+// wipes the frame outright), so naming a subset would leave a guard that stays
+// green while a future write corrupts the display.
+const PATTERN = /console\.[a-zA-Z]+\(/;
+
+interface AllowEntry {
+  readonly file: string;
+  readonly reason: string;
+}
+
+/**
+ * Files exempt from the rule, whole-file, each with the reason it is tolerated
+ * and when that goes away. A new violation in an exempt file still shows up in
+ * the census, so this list can only ever be argued down, not silently widened.
+ */
+const ALLOW_LIST: readonly AllowEntry[] = [
+  {
+    file: "packages/core/src/log.ts",
+    reason:
+      "The diagnostics sink itself. Exempt by construction: it is the one module allowed to own output plumbing, and a last-resort fallback there must not trip the guard. It writes files, never the console.",
+  },
+];
+
+// ── Walking the tree ────────────────────────────────────────────────────────
+
+/** Repo root, resolved from this file (`packages/core/src` → repo root). */
+const REPO_ROOT = fileURLToPath(new URL("../../../", import.meta.url));
+
+/** Every `packages/<name>/src` directory, plus `meta/src`. */
+function sourceDirs(): string[] {
+  const dirs: string[] = [];
+  for (const entry of readdirSync(join(REPO_ROOT, "packages"), { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const src = join(REPO_ROOT, "packages", entry.name, "src");
+    if (existsSync(src)) dirs.push(src);
+  }
+  const metaSrc = join(REPO_ROOT, "meta", "src");
+  if (existsSync(metaSrc)) dirs.push(metaSrc);
+  return dirs;
+}
+
+/** Source files under those trees; tests are excluded (they spy on the console). */
+function collectSourceFiles(): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "node_modules") walk(full);
+      } else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) {
+        out.push(relative(REPO_ROOT, full).split(/[\\/]/).join("/"));
+      }
+    }
+  };
+  for (const dir of sourceDirs()) walk(dir);
+  return out.sort();
+}
+
+interface Hit {
+  file: string;
+  line: number;
+  text: string;
+}
+
+function findViolations(files: readonly string[]): Hit[] {
+  const hits: Hit[] = [];
+  for (const file of files) {
+    const lines = readFileSync(join(REPO_ROOT, file), "utf8").split("\n");
+    lines.forEach((text, i) => {
+      if (PATTERN.test(text)) hits.push({ file, line: i + 1, text: text.trim() });
+    });
+  }
+  return hits;
+}
+
+const FILES = collectSourceFiles();
+const HITS = findViolations(FILES);
+const ALLOWED = new Set(ALLOW_LIST.map((e) => e.file));
+const VIOLATIONS = HITS.filter((h) => !ALLOWED.has(h.file));
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("console discipline: no console writes from render or event paths", () => {
+  it("walks the whole suite, not an empty file set", () => {
+    expect(existsSync(join(REPO_ROOT, "pnpm-workspace.yaml"))).toBe(true);
+    expect(FILES.length).toBeGreaterThan(50);
+    // The trees the guard covers, and the shape of what it skips.
+    for (const expected of [
+      "packages/core/src/log.ts",
+      "packages/ui/src/startup/index.ts",
+      "meta/src/index.ts",
+    ]) {
+      expect(FILES).toContain(expected);
+    }
+    expect(FILES.filter((f) => f.endsWith(".test.ts"))).toEqual([]);
+  });
+
+  it("reports no console writes outside the allow-list", () => {
+    expect(VIOLATIONS.map((v) => `${v.file}:${v.line} ${v.text}`)).toEqual([]);
+  });
+
+  it("matches any console write and not a patch site (the guard is not a loose grep)", () => {
+    const offenders = [
+      'console.log("x");',
+      '  console.warn(`y`);',
+      "console.error(err);",
+      "if (bad) console.error('nope');",
+      // The rest of the console writes to the terminal just as hard. `info` and
+      // `debug` used to be *pinned* as allowed here, which encoded the hole in
+      // the guard rather than the rule; the suite has none today, so widening
+      // costs nothing and closes it.
+      'console.info("x");',
+      'console.debug("x");',
+      "console.trace('here');",
+      'console.dir(obj);',
+      'console.table(rows);',
+      'console.group("g");',
+      "console.count();",
+      "console.clear();",
+    ];
+    for (const line of offenders) {
+      expect(PATTERN.test(line), `expected the guard to reject: ${line}`).toBe(true);
+    }
+
+    // Assignments, type references and prose about the console are not writes.
+    // This is exactly the difference between the guard and the census grep, and
+    // it is why the startup console patch this file used to exempt needed one
+    // entry for its single real write while its patch plumbing did not count.
+    const fine = [
+      "console.log = (...args) => {};",
+      "let _origLog: typeof console.log | undefined;",
+      "_origLog = console.log;",
+      "console.log = _origLog;",
+      "// Patch console.log for model scope capture",
+      "const orig = Object.getOwnPropertyDescriptor(console, 'log');",
+    ];
+    for (const line of fine) {
+      expect(PATTERN.test(line), `expected no rule to reject: ${line}`).toBe(false);
+    }
+  });
+
+  it("keeps the allow-list as small as the work that removes it", () => {
+    const sink = "packages/core/src/log.ts";
+    for (const entry of ALLOW_LIST) {
+      expect(FILES, `allow-listed file is no longer scanned: ${entry.file}`).toContain(entry.file);
+      expect(entry.reason.length).toBeGreaterThan(0);
+      // Anything exempted beyond the sink itself must name the task that
+      // removes it — otherwise the exemption is permanent by accident.
+      if (entry.file !== sink) expect(entry.reason).toMatch(/Task \d+/);
+    }
+
+    // Nothing outside the sink has a console write to excuse: the one file that
+    // did (the startup `console.log` scrape) is gone, so the sink entry is
+    // exempt by construction alone. Pin that, or the list grows a member nobody
+    // remembers granting.
+    const exercised = new Set(HITS.map((h) => h.file));
+    expect([...exercised]).toEqual([]);
+    expect(exercised.has(sink)).toBe(false);
+  });
+});

package/src/log.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { existsSync, mkdtempSync, readFileSync, rmSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { diag } from "./log.js";
+
+// A scratch directory per test file; `diag` is pointed at files inside it.
+const SANDBOX = mkdtempSync(join(tmpdir(), `archimedes-log-${randomUUID()}-`));
+
+const ENV = "PI_ARCHIMEDES_LOG";
+const previous = process.env[ENV];
+
+afterEach(() => {
+  if (previous === undefined) delete process.env[ENV];
+  else process.env[ENV] = previous;
+});
+
+describe("diag — the diagnostics sink", () => {
+  it("writes nothing at all when the env var is unset", () => {
+    // Unset is the default state of every real session, so this is the
+    // "logging costs nothing and touches no disk" guarantee. A file from an
+    // earlier enabled run proves the sink had somewhere to go; it must not
+    // gain a line now.
+    const target = join(SANDBOX, "unset.log");
+    process.env[ENV] = target;
+    diag("core", "enabled");
+
+    delete process.env[ENV];
+    expect(() => diag("core", "a message")).not.toThrow();
+
+    expect(readFileSync(target, "utf8").trimEnd().split("\n")).toEqual([
+      expect.stringContaining("[core] enabled"),
+    ]);
+  });
+
+  it("treats an empty value as off, not as the file named ''", () => {
+    // `PI_ARCHIMEDES_LOG=` is how an operator switches logging back off in a
+    // shell, and appendFileSync("") would resolve against the cwd — so the
+    // empty string must short-circuit rather than write somewhere surprising.
+    const target = join(SANDBOX, "blank.log");
+    process.env[ENV] = target;
+    diag("core", "before");
+
+    process.env[ENV] = "";
+    expect(() => diag("core", "after")).not.toThrow();
+
+    expect(readFileSync(target, "utf8").trimEnd().split("\n")).toEqual([
+      expect.stringContaining("[core] before"),
+    ]);
+  });
+
+  it("appends one line carrying an ISO-8601 timestamp, the scope and the message", () => {
+    const target = join(SANDBOX, "single.log");
+    process.env[ENV] = target;
+
+    const before = new Date();
+    diag("session-name", "title request failed");
+    const after = new Date();
+
+    const text = readFileSync(target, "utf8");
+    expect(text.endsWith("\n")).toBe(true);
+    const lines = text.trimEnd().split("\n");
+    expect(lines).toHaveLength(1);
+
+    const match = /^\[(.+?)\] \[(.+?)\] (.*)$/.exec(lines[0]!);
+    expect(match, `unexpected line shape: ${lines[0]}`).not.toBeNull();
+    const [, stamp, scope, message] = match!;
+    expect(scope).toBe("session-name");
+    expect(message).toBe("title request failed");
+    // ISO-8601 with an offset — parseable, and inside the call window.
+    const at = new Date(stamp!);
+    expect(Number.isNaN(at.getTime())).toBe(false);
+    expect(at.getTime()).toBeGreaterThanOrEqual(before.getTime() - 1000);
+    expect(at.getTime()).toBeLessThanOrEqual(after.getTime() + 1000);
+    expect(stamp!).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}(Z|[+-]\d{2}:\d{2})$/);
+  });
+
+  it("appends across calls instead of truncating the file", () => {
+    const target = join(SANDBOX, "append.log");
+    process.env[ENV] = target;
+
+    diag("bus", "first");
+    diag("footer", "second");
+
+    const lines = readFileSync(target, "utf8").trimEnd().split("\n");
+    expect(lines).toHaveLength(2);
+    expect(lines[0]).toContain("[bus] first");
+    expect(lines[1]).toContain("[footer] second");
+  });
+
+  it("re-reads the env var on every call (a later export takes effect)", () => {
+    // pi sets nothing itself: the operator exports PI_ARCHIMEDES_LOG in a shell,
+    // but a test/tool that sets it mid-run must also be honoured — reading it
+    // once at module load would freeze the no-op path.
+    const target = join(SANDBOX, "late.log");
+    delete process.env[ENV];
+    diag("core", "dropped");
+    expect(existsSync(target)).toBe(false);
+
+    process.env[ENV] = target;
+    diag("core", "captured");
+    expect(readFileSync(target, "utf8")).toContain("[core] captured");
+  });
+
+  it("never throws when the target cannot be written, and creates no directories", () => {
+    // A path under a directory that does not exist: appendFileSync fails with
+    // ENOENT. Logging must swallow it — and must not "helpfully" mkdir.
+    const missingDir = join(SANDBOX, "missing-dir");
+    process.env[ENV] = join(missingDir, "log.txt");
+
+    expect(() => diag("core", "unreachable")).not.toThrow();
+    expect(existsSync(missingDir)).toBe(false);
+  });
+
+  it("never throws when the target is a directory", () => {
+    const dir = join(SANDBOX, "a-directory");
+    mkdirSync(dir, { recursive: true });
+    process.env[ENV] = dir;
+
+    expect(() => diag("core", "EISDIR")).not.toThrow();
+  });
+
+  it("tolerates a message containing newlines without throwing", () => {
+    // Callers format error objects; a stack would arrive here multi-line. The
+    // sink keeps it verbatim rather than trying to sanitise.
+    const target = join(SANDBOX, "multiline.log");
+    process.env[ENV] = target;
+
+    expect(() => diag("core", "line one\nline two")).not.toThrow();
+    expect(readFileSync(target, "utf8")).toContain("[core] line one\nline two");
+  });
+});
+
+// ── describeError — what a swallowed error looks like in the log ───────────
+//
+// `console.error(scope, err)` used to print the stack. Routing a swallowed
+// error through a formatter that keeps only `err.message` would leave the log
+// with a message and no origin, and for these call sites the log is the ONLY
+// record: the write smears a fullscreen frame, and a subagent child discards
+// it. So the formatter keeps the whole `Error`, stack included. (The user-facing
+// surface keeps taking the message alone — see `describeError`'s doc.)
+
+import { describeError } from "./log.js";
+
+describe("describeError", () => {
+  function exploded(): Error {
+    // A named frame on purpose: the assertion below wants an origin, not just
+    // a message — that is the whole reason the stack is kept.
+    return new Error("listener exploded");
+  }
+
+  it("keeps the stack, which is the only source location a swallowed error ever gets", () => {
+    const text = describeError(exploded());
+    expect(text).toContain("listener exploded");
+    expect(text).toMatch(/\n\s+at\s+\S/);
+    expect(text).toContain("exploded");
+  });
+
+  it("falls back to the message when the error carries no stack", () => {
+    const err = new Error("no stack here");
+    delete (err as { stack?: string }).stack;
+    expect(describeError(err)).toBe("no stack here");
+  });
+
+  it("stringifies anything that is not an Error", () => {
+    expect(describeError("a string")).toBe("a string");
+    expect(describeError({ code: 42 })).toBe("[object Object]");
+    expect(describeError(undefined)).toBe("undefined");
+  });
+});

package/src/log.ts

@@ -0,0 +1,69 @@
+import { appendFileSync } from "node:fs";
+
+// ── Diagnostics sink ────────────────────────────────────────────────────────
+//
+// The suite does not write to the console. Two independent reasons:
+//
+// 1. On fullscreen screen a stray write lands inside the differential frame
+//    and smears the viewport until the next full redraw. On regular screen it
+//    scrolled away unseen, which is why the habit was cheap to keep.
+// 2. In a subagent child every write is discarded anyway:
+//    `subagent/src/stream.ts` drops any non-JSON stdout line (a guard for pi's
+//    own startup messages), so a warning vanishes exactly when someone is
+//    debugging a child run.
+//
+// So developer diagnostics go here, and a message the user must see goes to the
+// notification surface (`ctx.ui.notify`) — never to stdout/stderr.
+//
+// Logging is opt-in and dumb on purpose: one env var naming a file, one
+// appended line per call, and a `try/catch` that swallows every failure. A
+// diagnostic that can throw, block, or fill a disk is a new bug class, and the
+// whole point of the sink is to be trustworthy while another bug is in flight.
+// Nothing else in this module touches the filesystem — it does not create
+// directories, rotate, buffer, or truncate.
+
+/**
+ * Append one diagnostic line to `$PI_ARCHIMEDES_LOG`.
+ *
+ * No-op when the variable is unset or empty, so a default install never
+ * touches disk. When set, appends `[ISO-8601] [scope] message`. Never throws:
+ * an unwritable path (missing directory, EISDIR, EACCES, a full volume) is
+ * silently ignored, because losing a log line is always cheaper than failing a
+ * render, an event handler, or a session.
+ *
+ * One *append* per call; the message is kept verbatim, so an entry built by
+ * `describeError` spans the lines of its stack — which is the point of it.
+ *
+ * @param scope the package the line came from (e.g. `"session-name"`)
+ * @param message the diagnostic text; multi-line text is kept verbatim
+ */
+export function diag(scope: string, message: string): void {
+  const file = process.env.PI_ARCHIMEDES_LOG;
+  if (!file) return;
+  try {
+    appendFileSync(file, `[${new Date().toISOString()}] [${scope}] ${message}\n`);
+  } catch {
+    // Logging must never be the reason something failed.
+  }
+}
+
+/**
+ * An error, formatted for `diag` — stack included.
+ *
+ * Task 6 moved errors off the console, and handing an error object to the
+ * console used to print its stack on the way out. Formatting them down to
+ * `err.message` would trade a visible stack for an invisible one, and at the sites this exists for —
+ * a bus listener that threw, a footer frame that failed, a package whose
+ * `import()` was refused — the error is **swallowed**, so this log is the only
+ * place it is ever recorded and the stack is the only part naming its origin.
+ *
+ * Use the message alone (`err.message`) where someone on screen is about to
+ * read the text — `ctx.ui.notify`, a tool result, a widget. A stack belongs in a
+ * log file, never in a notification.
+ *
+ * @param err whatever a `catch` caught
+ */
+export function describeError(err: unknown): string {
+  if (err instanceof Error) return err.stack ?? err.message;
+  return String(err);
+}

package/src/overlay.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from "vitest";
+import { CURSOR_MARKER, stripTerminalSequences, visibleWidth as tuiVisibleWidth } from "@earendil-works/pi-tui";
 import {
   visibleWidth,
   padEnd,
@@ -52,9 +53,14 @@ describe("padEnd", () => {
     expect(padEnd("hi", 5)).toBe("hi   ");
   });
 
-  it("returns input unchanged when visible width >= target", () => {
+  it("leaves a line that already fits untouched", () => {
     expect(padEnd("hello", 5)).toBe("hello");
-    expect(padEnd("toolong", 5)).toBe("toolong");
+  });
+
+  it("clips a line wider than the target instead of letting it overflow", () => {
+    // The frame is a hard limit: a padded row must never measure past it, or
+    // the closing border lands off-screen and the terminal hard-wraps the row.
+    expect(visibleWidth(padEnd("toolong", 5))).toBe(5);
   });
 
   it("returns '' for width <= 0", () => {
@@ -67,11 +73,11 @@ describe("padEnd", () => {
 
 describe("wrapText", () => {
   it("wraps a long line to width", () => {
-    expect(wrapText("aaa bbb ccc ddd", 8)).toEqual(["aaa bbb ", "ccc ddd"]);
+    expect(wrapText("aaa bbb ccc ddd", 8)).toEqual(["aaa bbb", "ccc ddd"]);
   });
 
   it("wraps long words to width", () => {
-    expect(wrapText("hello world", 5)).toEqual(["hello", " ", "world"]);
+    expect(wrapText("hello world", 5)).toEqual(["hello", "world"]);
   });
 
   it("preserves empty paragraphs as blank lines", () => {
@@ -91,7 +97,10 @@ describe("hardTruncate", () => {
   });
 
   it("truncates at the visible-width boundary", () => {
-    expect(hardTruncate("hello world", 5)).toBe("hello");
+    // pi-tui closes any styling it cut into, so the visible text — not the raw
+    // bytes — is the contract.
+    expect(stripTerminalSequences(hardTruncate("hello world", 5))).toBe("hello");
+    expect(visibleWidth(hardTruncate("hello world", 5))).toBe(5);
   });
 
   it("truncates an ANSI-colored string and appends a reset", () => {
@@ -101,6 +110,80 @@ describe("hardTruncate", () => {
   });
 });
 
+// ── Terminal-hostile content ────────────────────────────────────────────────
+//
+// Every measurement in this module used to be `.length` after stripping only
+// `\x1b[…m`. That is wrong for the three things the real overlays actually
+// print: pi's cursor marker (an APC sequence, zero columns wide), OSC 8
+// hyperlinks (a URL is invisible but enormous), and east-asian text (two
+// columns per character). Each case below is measured with pi-tui's own
+// `visibleWidth`, i.e. what the terminal draws.
+
+describe("width maths on terminal-hostile content", () => {
+  it("measures a line carrying the real CURSOR_MARKER at its visible width", () => {
+    const line = `Search: plan${CURSOR_MARKER}`;
+    expect(visibleWidth(line)).toBe("Search: plan".length);
+    // The row this feeds must still land on exactly the target column: the
+    // marker occupies no cells, so the padding has to make up all of them.
+    expect(visibleWidth(padEnd(line, 20))).toBe(20);
+  });
+
+  it("returns an OSC 8 hyperlink that already fits byte-for-byte", () => {
+    const url = `https://example.com/${"a".repeat(40)}`;
+    const line = `\x1b]8;;${url}\x07docs\x1b]8;;\x07`;
+    // 4 visible columns at a limit of 4: the no-cut path. pi-tui hands the input
+    // straight back, which is what makes a fitting row render identically to the
+    // old chrome. This is NOT the cutting case — see the next test.
+    expect(visibleWidth(line)).toBe(4);
+    expect(hardTruncate(line, 4)).toBe(line);
+  });
+
+  it("cuts inside an OSC 8 hyperlink without leaving a half-written sequence", () => {
+    const url = `https://example.com/${"a".repeat(40)}`;
+    const line = `\x1b]8;;${url}\x07documentation\x1b]8;;\x07`; // 13 visible columns
+    expect(visibleWidth(line)).toBe(13);
+    const cut = hardTruncate(line, 4);
+    // The cut really happened: four columns of the linked text survive.
+    expect(tuiVisibleWidth(cut)).toBe(4);
+    expect(stripTerminalSequences(cut)).toBe("docu");
+    // The URL stays inside its escape sequence and every OSC 8 opener is
+    // terminated — a half-written OSC swallows the rest of the row, which is how
+    // the old byte-walking truncator failed here (it produced the 3-column stub
+    // "\x1b]8;" for this exact input, with no BEL and no closing sequence).
+    const opens = cut.match(/\x1b\]8;;/g) ?? [];
+    const terminated = cut.match(/\x1b\]8;;[^\x07]*\x07/g) ?? [];
+    expect(opens.length).toBeGreaterThan(0);
+    expect(terminated.length).toBe(opens.length);
+    // And the cut emits an explicit hyperlink close plus a reset, so the styling
+    // and the link target cannot bleed into the padding and the closing border.
+    expect(cut).toContain("\x1b]8;;\x07");
+    expect(cut.endsWith("\x1b[0m")).toBe(true);
+  });
+
+  it("wraps a CJK line at the right column", () => {
+    const lines = wrapText("日本語のテキストです", 6);
+    expect(lines).toEqual(["日本語", "のテキ", "ストで", "す"]);
+    for (const line of lines) {
+      expect(tuiVisibleWidth(line)).toBeLessThanOrEqual(6);
+    }
+  });
+
+  it("keeps an SGR colour across a wrap", () => {
+    const lines = wrapText("\x1b[31mred word and more words\x1b[0m", 8);
+    expect(lines.map((l) => stripTerminalSequences(l))).toEqual([
+      "red word",
+      "and more",
+      "words",
+    ]);
+    // Each continuation line re-opens the colour, so the wrap does not spill
+    // red onto whatever the surface prints next.
+    for (const line of lines) {
+      expect(line).toContain("\x1b[31m");
+      expect(tuiVisibleWidth(line)).toBeLessThanOrEqual(8);
+    }
+  });
+});
+
 // ── renderHeader / renderFooter ──────────────────────────────────────────────
 
 describe("renderHeader", () => {
@@ -164,7 +247,10 @@ describe("wrapWithBorder", () => {
     for (const line of out) {
       expect(visibleWidth(line)).toBe(W);
     }
-    expect(out[1]).toBe("│ " + "z".repeat(W - 4) + " │");
+    // Asserted on visible text, not bytes: closing the truncation appends a
+    // zero-width reset, which is what keeps the style from bleeding into the
+    // padding and the closing border.
+    expect(stripTerminalSequences(out[1]!)).toBe("│ " + "z".repeat(W - 4) + " │");
   });
 });
 
@@ -179,3 +265,89 @@ describe("OVERLAY_CHROME", () => {
     });
   });
 });
+
+// ── Frame-width audit ────────────────────────────────────────────────────────
+//
+// The automated stand-in for a `PI_TUI_WRITE_LOG` capture: render the chrome the
+// way the overlay surfaces do, measure every produced line with pi-tui's own
+// `visibleWidth` (what the terminal actually draws), and require it to fit the
+// frame. A line wider than the frame is not a cosmetic defect — the terminal
+// hard-wraps it, which shoves the closing border onto the next row and shifts
+// every row below it.
+//
+// The same audit runs per surface where that surface lives (the agents panel in
+// @pi-archimedes/subagent, the settings/onboarding overlays in meta), so the
+// numbers below are the chrome's share of the measurement.
+
+/** Hostile content, one entry per failure mode of the old `.length` maths. */
+function hostileLines(theme: OverlayTheme): string[] {
+  const url = `https://example.com/${"segment/".repeat(12)}`;
+  return [
+    // real pi cursor marker (APC: ESC _ … BEL) — zero columns wide
+    `Search: wide-query${CURSOR_MARKER}`,
+    // OSC 8 hyperlink — long invisible payload, short visible text
+    `docs: \x1b]8;;${url}\x07readme\x1b]8;;\x07 tail`,
+    // east-asian text — two columns per code unit
+    "設定パネルの横幅の測定を検証するための日本語テキスト",
+    // SGR-coloured runs
+    theme.fg("accent", "accent run ") + theme.fg("dim", "dim run ") + "tail",
+    // all three at once, wider than any frame
+    theme.fg("error", "✗ " + "失敗".repeat(40)) + `\x1b]8;;${url}\x07link\x1b]8;;\x07` + CURSOR_MARKER,
+  ];
+}
+
+interface AuditViolation {
+  surface: string;
+  frameWidth: number;
+  row: number;
+  measured: number;
+}
+
+/**
+ * Measure every produced line against the frame. Returns one entry per line
+ * that overflows (or, for a bordered frame, fails to land on it exactly).
+ */
+function auditFrameWidth(
+  surface: string,
+  frameWidth: number,
+  lines: string[],
+  bordered: boolean,
+): AuditViolation[] {
+  const violations: AuditViolation[] = [];
+  lines.forEach((line, row) => {
+    const measured = tuiVisibleWidth(line);
+    const bad = bordered ? measured !== frameWidth : measured > frameWidth;
+    if (bad) violations.push({ surface, frameWidth, row, measured });
+  });
+  return violations;
+}
+
+describe("frame-width audit (overlay chrome)", () => {
+  const FRAME_WIDTHS = [40, 60, 84, 100];
+
+  it("renders chrome inside the frame at every width, for hostile content", () => {
+    const violations: AuditViolation[] = [];
+    const content = hostileLines(mockTheme);
+
+    for (const frameWidth of FRAME_WIDTHS) {
+      const contentWidth = borderContentWidth(frameWidth);
+      // Composed the way the real surfaces compose it: header + padded body
+      // rows (some wrapped) + footer, then the border.
+      const body = content.flatMap((line) => wrapText(line, contentWidth));
+      const lines = [
+        renderHeader(" Settings ", contentWidth, mockTheme),
+        ...body.map((line) => padEnd(line, contentWidth)),
+        renderFooter(" [esc] close ", contentWidth, mockTheme),
+      ];
+      violations.push(
+        ...auditFrameWidth("chrome", frameWidth, wrapWithBorder(lines, frameWidth, mockTheme), true),
+      );
+    }
+
+    expect(
+      violations,
+      `${violations.length} chrome line(s) overflow the frame: ` +
+        violations.slice(0, 8).map((v) => `w=${v.frameWidth} row=${v.row} measured=${v.measured}`).join(", "),
+    ).toEqual([]);
+  });
+});