@hypercarrier/rarebit 0.1.0-alpha.6 → 0.2.1

package/scripts/e2e-settings-pi.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+/**
+ * Real Pi TUI settings coverage for Rarebit.
+ *
+ * The run uses a disposable agent directory, trusted project, Session root,
+ * and loopback-only model registry. The settings flow must render its tabs,
+ * save only the Rarebit namespace, and reopen with the saved value. It must
+ * not start a provider request or append a Session record.
+ */
+
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const piEntry = fileURLToPath(await import.meta.resolve("@earendil-works/pi-coding-agent"));
+const piRoot = resolve(dirname(dirname(piEntry)));
+const piCli = join(piRoot, "dist/cli.js");
+const tmux = process.env.TMUX_BIN ?? "tmux";
+
+const sleep = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+async function pane(socket, session) {
+  try {
+    const { stdout } = await execFile(tmux, ["-L", socket, "capture-pane", "-p", "-J", "-t", session, "-S", "-200"]);
+    return stdout;
+  } catch {
+    return "";
+  }
+}
+async function keys(socket, session, text) {
+  await execFile(tmux, ["-L", socket, "send-keys", "-l", "-t", session, text]);
+}
+async function press(socket, session, key) {
+  await execFile(tmux, ["-L", socket, "send-keys", "-t", session, key]);
+}
+async function submitSlash(socket, session, command) {
+  await keys(socket, session, command);
+  // Pi's editor keeps slash-command autocomplete active after the literal
+  // command text arrives through tmux. Tab accepts the selected command token;
+  // Enter then submits the now-complete extension command.
+  await sleep(500);
+  await press(socket, session, "Tab");
+  await sleep(100);
+  await press(socket, session, "Enter");
+}
+async function waitFor(label, predicate, timeout = 10_000, interval = 100) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const value = await predicate();
+    if (value) return value;
+    await sleep(interval);
+  }
+  throw new Error(`Timed out waiting for ${label}`);
+}
+async function walk(root) {
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const entry of entries) {
+    const file = join(root, entry.name);
+    if (entry.isDirectory()) files.push(...await walk(file));
+    else files.push(file);
+  }
+  return files;
+}
+
+const temp = await mkdtemp(join(tmpdir(), "rarebit-settings-pi-e2e-"));
+const agentDir = join(temp, "agent");
+const projectDir = join(temp, "project");
+const sessionDir = join(temp, "sessions");
+const rarebitRoot = join(temp, "receipts");
+const fixtureExtension = join(temp, "rarebit-fixture-extension.mjs");
+const requestLog = join(temp, "provider-requests.jsonl");
+const settingsFile = join(agentDir, "settings.json");
+const projectSettingsFile = join(projectDir, ".pi", "settings.json");
+const socket = `rarebit-settings-${process.pid}`;
+const session = "rarebit-settings-e2e";
+let provider;
+let tmuxStarted = false;
+let keepTemp = process.env.RAREBIT_KEEP_E2E_TEMP === "1";
+
+try {
+  await mkdir(agentDir, { recursive: true });
+  await mkdir(join(projectDir, ".pi"), { recursive: true });
+  await mkdir(sessionDir, { recursive: true });
+
+  const requests = [];
+  provider = createServer(async (request, response) => {
+    let body = "";
+    for await (const chunk of request) body += chunk;
+    const entry = { at: Date.now(), body: JSON.parse(body) };
+    requests.push(entry);
+    await writeFile(requestLog, `${JSON.stringify(entry)}\n`, { flag: "a", mode: 0o600 });
+    const chunk = JSON.stringify({
+          id: `rarebit-settings-${requests.length}`,
+      object: "chat.completion.chunk",
+      choices: [{ index: 0, delta: { role: "assistant", content: "SETTINGS_BASELINE_DONE" }, finish_reason: "stop" }],
+    });
+    response.writeHead(200, { "content-type": "text/event-stream", connection: "keep-alive" });
+    response.end(`data: ${chunk}\n\ndata: [DONE]\n\n`);
+  });
+  await new Promise((resolvePromise, reject) => {
+    provider.once("error", reject);
+    provider.listen(0, "127.0.0.1", resolvePromise);
+  });
+  const port = provider.address().port;
+  await writeFile(join(agentDir, "models.json"), JSON.stringify({
+    providers: {
+      local: {
+        baseUrl: `http://127.0.0.1:${port}/v1`,
+        api: "openai-completions",
+        apiKey: "fixture",
+        models: [{ id: "fixture", name: "settings fixture", reasoning: false, input: ["text"], contextWindow: 100_000, maxTokens: 512 }],
+      },
+    },
+  }, null, 2), { mode: 0o600 });
+  await writeFile(settingsFile, JSON.stringify({
+    theme: "dark",
+    another_extension: { keep: true },
+    rarebit: { model: "local/fixture", auto_title: false },
+  }, null, 2), { mode: 0o600 });
+  await writeFile(projectSettingsFile, "{}\n", { mode: 0o600 });
+  await writeFile(fixtureExtension, `import registerPiRarebit from ${JSON.stringify(pathToFileURL(join(packageRoot, "src/extension.mjs")).href)};
+export default function registerFixtureRarebit(pi) {
+  return registerPiRarebit(pi, { sessionRoot: ${JSON.stringify(sessionDir)}, rarebitRoot: ${JSON.stringify(rarebitRoot)} });
+}
+`, { mode: 0o600 });
+
+  const childEnv = { ...process.env, PI_CODING_AGENT_DIR: agentDir, PI_OFFLINE: "1", PI_TELEMETRY: "0" };
+  const command = [
+    "env", `PI_CODING_AGENT_DIR=${agentDir}`, "PI_OFFLINE=1", "PI_TELEMETRY=0",
+    process.execPath, piCli, "--no-extensions", "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files", "--approve",
+    "--extension", fixtureExtension, "--session-dir", sessionDir, "--model", "local/fixture", "--tui-mode", "regular",
+  ];
+  const child = spawn(tmux, ["-L", socket, "new-session", "-d", "-x", "140", "-y", "48", "-s", session, ...command], { cwd: projectDir, env: childEnv, stdio: "ignore" });
+  await new Promise((resolvePromise, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code) => code === 0 ? resolvePromise() : reject(new Error(`tmux exited ${code}`)));
+  });
+  tmuxStarted = true;
+  await waitFor("Pi editor", async () => (await pane(socket, session)).includes("0.0%/100k"));
+  await sleep(750);
+
+  // Establish a persisted Session before measuring settings side effects.
+  // Keep this baseline request separate from the settings no-model-call check.
+  await keys(socket, session, "settings baseline");
+  await press(socket, session, "Enter");
+  await waitFor("baseline provider response", async () => (await pane(socket, session)).includes("SETTINGS_BASELINE_DONE"), 15_000);
+  const providerRequestsBeforeSettings = requests.length;
+  const sessionSnapshot = async () => Object.fromEntries(await Promise.all(
+    (await walk(sessionDir)).filter((file) => file.endsWith(".jsonl")).sort()
+      .map(async (file) => [file, await readFile(file, "utf8")]),
+  ));
+  await waitFor("persisted baseline assistant", async () =>
+    Object.values(await sessionSnapshot()).some((text) => text.includes("SETTINGS_BASELINE_DONE")));
+  const sessionsBeforeSettings = await sessionSnapshot();
+
+  await submitSlash(socket, session, "/rarebit");
+  const palettePane = await waitFor("Rarebit parent palette", async () => {
+    const output = await pane(socket, session);
+    return output.includes("Human-only command palette") && output.includes("Command help") ? output : false;
+  });
+  await press(socket, session, "Escape");
+  await waitFor("editor after palette close", async () => !(await pane(socket, session)).includes("Human-only command palette"));
+  await sleep(200);
+
+  // Open the real command and settings surface.
+  await submitSlash(socket, session, "/rarebit settings");
+  const initialPane = await waitFor("settings tabs", async () => {
+    const output = await pane(socket, session);
+    return output.includes("Rarebit Settings") && output.includes("Actions") && output.includes("Summary") && output.includes("Recap") && output.includes("Session") ? output : false;
+  });
+  assert.match(initialPane, /Show Summary triggered/);
+  assert.match(initialPane, /Actions\s+\/\s+Summary\s+\/\s+Recap\s+\/\s+Session/);
+
+  // The editor opens on Summary. Visit Recap in the rendered TUI so the
+  // timezone and delay fields are covered, then cycle back to Summary.
+  await press(socket, session, "Tab");
+  const recapPane = await waitFor("Recap settings tab", async () => {
+    const output = await pane(socket, session);
+    return output.includes("Recap timezone") && output.includes("Recap delay (ms)") ? output : false;
+  });
+  assert.match(recapPane, /Recap timezone/);
+  assert.match(recapPane, /60,000/);
+  await press(socket, session, "Tab");
+  await sleep(100);
+  await press(socket, session, "Tab");
+  await sleep(100);
+  await press(socket, session, "Tab");
+  await sleep(100);
+  await waitFor("Summary tab after Recap", async () => (await pane(socket, session)).includes("Show Summary triggered"));
+
+  // Summary is the initial tab. Choose its first row, set `on`, and confirm.
+  await press(socket, session, "Enter");
+  await waitFor("diagnostic choices", async () => {
+    const output = await pane(socket, session);
+    return output.includes("Show Summary triggered") && output.includes("Remove override") ? output : false;
+  });
+  await press(socket, session, "Down");
+  await sleep(100);
+  await press(socket, session, "Down");
+  await sleep(100);
+  await press(socket, session, "Enter");
+  await waitFor("save confirmation", async () => (await pane(socket, session)).includes("Save Rarebit global settings?"));
+  await press(socket, session, "Enter");
+  await waitFor("saved settings notice", async () => (await pane(socket, session)).includes("Saved Rarebit global settings."));
+  await press(socket, session, "Escape");
+  await waitFor("editor after settings close", async () => !(await pane(socket, session)).includes("Rarebit Settings"));
+
+  const saved = JSON.parse(await readFile(settingsFile, "utf8"));
+  assert.equal(saved.theme, "dark");
+  assert.deepEqual(saved.another_extension, { keep: true });
+  assert.equal(saved.rarebit.diagnostics.summary_triggered, true);
+  assert.equal(requests.length, providerRequestsBeforeSettings, "settings must not call a model provider");
+
+  // Reopen in the same real TUI and verify the persisted field is visible.
+  await submitSlash(socket, session, "/rarebit settings");
+  const reopenedPane = await waitFor("reopened settings", async () => {
+    const output = await pane(socket, session);
+    return output.includes("Rarebit Settings") && output.includes("Show Summary triggered: on") ? output : false;
+  });
+  assert.match(reopenedPane, /Show Summary triggered: on/);
+  await press(socket, session, "Escape");
+  await press(socket, session, "Escape");
+  await sleep(250);
+  const sessionText = (await Promise.all((await walk(sessionDir)).filter((file) => file.endsWith(".jsonl")).map((file) => readFile(file, "utf8")))).join("\n");
+  assert.doesNotMatch(sessionText, /Saved Rarebit|Summary triggered/);
+  assert.deepEqual(await sessionSnapshot(), sessionsBeforeSettings, "palette and settings must not append or change Session records");
+  assert.equal(requests.length, providerRequestsBeforeSettings, "reopening settings must not call a model provider");
+
+  const evidence = { palettePane, initialPane, recapPane, reopenedPane, requests, settings: saved };
+  if (keepTemp) await writeFile(join(temp, "evidence.json"), JSON.stringify(evidence, null, 2), { mode: 0o600 });
+  console.log(JSON.stringify({
+    ok: true,
+    pi: JSON.parse(await readFile(join(piRoot, "package.json"), "utf8")).version,
+    providerRequests: requests.length,
+    settingsFile,
+    checks: ["real Pi TUI rendered Actions/Summary/Recap/Session tabs", "confirmed edit persisted", "reopen showed saved value", "other settings namespaces preserved", "settings made no provider request or Session write"],
+    evidenceRoot: keepTemp ? temp : null,
+  }, null, 2));
+} catch (error) {
+  keepTemp = true;
+  const failurePane = tmuxStarted ? await pane(socket, session) : "";
+  console.error(`Rarebit settings Pi E2E failed: ${error?.stack ?? error}`);
+  if (failurePane) console.error(`Pi pane at failure:\n${failurePane}`);
+  console.error(`Temporary evidence retained at ${temp}`);
+  throw error;
+} finally {
+  if (tmuxStarted) {
+    await press(socket, session, "C-c").catch(() => {});
+    await sleep(100);
+    await press(socket, session, "C-c").catch(() => {});
+    await execFile(tmux, ["-L", socket, "kill-server"]).catch(() => {});
+  }
+  if (provider?.listening) await new Promise((resolvePromise) => provider.close(resolvePromise));
+  if (keepTemp) {
+    const cleanup = await execFile(tmux, ["-L", socket, "has-session"]).then(() => "server_still_running").catch(() => "clean");
+    await writeFile(join(temp, "tmux-cleanup.txt"), `${cleanup}\n`, { mode: 0o600 });
+  } else await rm(temp, { recursive: true, force: true });
+}

package/scripts/e2e-v020-pi.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+/**
+ * Packed-artifact Pi 0.84.2 verification for the v0.2 Summary/Recap surface.
+ *
+ * Set RAREBIT_PACKAGE_TGZ to a tarball produced by `npm pack` to exercise the
+ * installed artifact. Without it, the fixture imports this checkout's source.
+ * The provider is loopback-only and the Pi agent/project/Session roots are
+ * disposable.
+ */
+
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import { execFile as execFileCallback } from "node:child_process";
+import { createRequire } from "node:module";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const piEntry = fileURLToPath(await import.meta.resolve("@earendil-works/pi-coding-agent"));
+const piRoot = resolve(dirname(dirname(piEntry)));
+const piCli = join(piRoot, "dist/cli.js");
+const resolveTuiRoot = (fromRoot) => {
+  const entry = createRequire(join(fromRoot, "package.json")).resolve("@earendil-works/pi-tui");
+  return resolve(dirname(entry), "..");
+};
+const sourceTuiRoot = process.env.RAREBIT_PI_TUI_ROOT ?? resolveTuiRoot(packageRoot);
+const tmux = process.env.TMUX_BIN ?? "tmux";
+const keepTemp = process.env.RAREBIT_KEEP_E2E_TEMP === "1";
+const packageTarball = process.env.RAREBIT_PACKAGE_TGZ;
+
+const sleep = (milliseconds) => new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
+
+async function pane(socket, session, ansi = false) {
+  try {
+    const args = ["-L", socket, "capture-pane", "-p", "-J"];
+    if (ansi) args.push("-e");
+    args.push("-t", session, "-S", "-240");
+    return (await execFile(tmux, args)).stdout;
+  } catch {
+    return "";
+  }
+}
+
+async function keys(socket, session, text) {
+  await execFile(tmux, ["-L", socket, "send-keys", "-l", "-t", session, text]);
+}
+
+async function press(socket, session, key) {
+  await execFile(tmux, ["-L", socket, "send-keys", "-t", session, key]);
+}
+
+async function waitFor(label, predicate, timeout = 10_000, interval = 100) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const value = await predicate();
+    if (value) return value;
+    await sleep(interval);
+  }
+  throw new Error(`Timed out waiting for ${label}`);
+}
+
+async function walk(root) {
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  const files = [];
+  for (const entry of entries) {
+    const file = join(root, entry.name);
+    if (entry.isDirectory()) files.push(...await walk(file));
+    else files.push(file);
+  }
+  return files;
+}
+
+const temp = await mkdtemp(join(tmpdir(), "rarebit-v020-pi-e2e-"));
+const agentDir = join(temp, "agent");
+const projectDir = join(temp, "project");
+const sessionDir = join(temp, "sessions");
+const rarebitRoot = join(temp, "receipts");
+const fixtureExtension = join(temp, "rarebit-fixture-extension.mjs");
+const requestLog = join(temp, "provider-requests.jsonl");
+const installedRoot = join(temp, "installed");
+const socket = `rarebit-v020-${process.pid}`;
+const session = "rarebit-v020-e2e";
+let provider;
+let tmuxStarted = false;
+
+try {
+  await mkdir(agentDir, { recursive: true });
+  await mkdir(join(projectDir, ".pi"), { recursive: true });
+  await mkdir(sessionDir, { recursive: true });
+
+  const installedPackageRoot = packageTarball
+    ? join(installedRoot, "package")
+    : packageRoot;
+  if (packageTarball) {
+    await mkdir(installedRoot, { recursive: true });
+    await execFile("tar", ["-xzf", resolve(packageTarball), "-C", installedRoot]);
+    await mkdir(join(installedRoot, "node_modules", "@earendil-works"), { recursive: true });
+    await execFile("ln", ["-s", sourceTuiRoot, join(installedRoot, "node_modules/@earendil-works/pi-tui")]);
+    await execFile("ln", ["-s", piRoot, join(installedRoot, "node_modules/@earendil-works/pi-coding-agent")]);
+  }
+
+  const requests = [];
+  provider = createServer(async (request, response) => {
+    let body = "";
+    for await (const chunk of request) body += chunk;
+    const payload = JSON.parse(body);
+    const messages = Array.isArray(payload.messages) ? payload.messages : [];
+    const userText = messages
+      .filter((message) => message?.role === "user")
+      .map((message) => typeof message.content === "string" ? message.content : JSON.stringify(message.content ?? ""))
+      .join("\n");
+    const isSummary = /You are the HyperCarrier Rarebit summarizer/i.test(userText);
+    const interactiveNumber = requests.filter((entry) => entry.kind === "interactive").length + 1;
+    const fullSummary = Array.from({ length: 24 }, (_, index) => `line-${index + 1} FULL_RECAP_TAIL_${index + 1}`).join("\n");
+    const text = isSummary
+      ? JSON.stringify({ summary: fullSummary, sessionStatus: "finished", statusReason: "all_requests_accomplished" })
+      : `INTERACTIVE_${interactiveNumber}_DONE`;
+    const entry = { kind: isSummary ? "summary" : "interactive", body: payload, text, requestAt: Date.now(), responseAt: Date.now() };
+    requests.push(entry);
+    await writeFile(requestLog, `${JSON.stringify(entry)}\n`, { flag: "a", mode: 0o600 });
+    const id = `rarebit-v020-${requests.length}`;
+    const first = JSON.stringify({ id, object: "chat.completion.chunk", choices: [{ index: 0, delta: { role: "assistant", content: text }, finish_reason: null }] });
+    const finish = JSON.stringify({ id, object: "chat.completion.chunk", choices: [{ index: 0, delta: {}, finish_reason: "stop" }], usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 } });
+    response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
+    response.write(`data: ${first}\n\n`);
+    response.write(`data: ${finish}\n\n`);
+    response.end("data: [DONE]\n\n");
+  });
+  await new Promise((resolvePromise, reject) => {
+    provider.once("error", reject);
+    provider.listen(0, "127.0.0.1", resolvePromise);
+  });
+  const port = provider.address().port;
+
+  await writeFile(join(agentDir, "models.json"), JSON.stringify({
+    providers: {
+      local: {
+        baseUrl: `http://127.0.0.1:${port}/v1`,
+        api: "openai-completions",
+        apiKey: "fixture",
+        models: [{ id: "fixture", name: "v0.2 fixture", reasoning: false, input: ["text"], contextWindow: 100_000, maxTokens: 512 }],
+      },
+    },
+  }, null, 2), { mode: 0o600 });
+  await writeFile(join(agentDir, "settings.json"), JSON.stringify({
+    theme: "dark",
+    other_extension: { preserve: true },
+    rarebit: {
+      model: "local/fixture",
+      auto_title: false,
+      min_total_length: 0,
+      max_rarebit_ratio: 1,
+      summary_prompt: "Use short factual bullets and state uncertainty.",
+      recap: { timezone: "Asia/Hong_Kong" },
+    },
+  }, null, 2), { mode: 0o600 });
+  await writeFile(join(projectDir, ".pi", "settings.json"), "{}\n", { mode: 0o600 });
+
+  await writeFile(fixtureExtension, `import registerPiRarebit from ${JSON.stringify(pathToFileURL(join(installedPackageRoot, "src/extension.mjs")).href)};
+export default function registerFixtureRarebit(pi) {
+  return registerPiRarebit(pi, { sessionRoot: ${JSON.stringify(sessionDir)}, rarebitRoot: ${JSON.stringify(rarebitRoot)} });
+}
+`, { mode: 0o600 });
+
+  const childEnv = { ...process.env, PI_CODING_AGENT_DIR: agentDir, PI_OFFLINE: "1", PI_TELEMETRY: "0" };
+  const command = [
+    "env", `PI_CODING_AGENT_DIR=${agentDir}`, "PI_OFFLINE=1", "PI_TELEMETRY=0",
+    process.execPath, piCli, "--no-extensions", "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files", "--approve",
+    "--extension", fixtureExtension, "--session-dir", sessionDir, "--model", "local/fixture", "--tui-mode", "regular",
+  ];
+  const child = spawn(tmux, ["-L", socket, "new-session", "-d", "-x", "140", "-y", "48", "-s", session, ...command], { cwd: projectDir, env: childEnv, stdio: "ignore" });
+  await new Promise((resolvePromise, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code) => code === 0 ? resolvePromise() : reject(new Error(`tmux exited ${code}`)));
+  });
+  tmuxStarted = true;
+  await waitFor("Pi editor", async () => (await pane(socket, session)).includes("0.0%/100k"));
+  await sleep(750);
+
+  await keys(socket, session, "first v020 recap turn");
+  await press(socket, session, "Enter");
+  await waitFor("interactive response", async () => (await pane(socket, session)).includes("INTERACTIVE_1_DONE"), 15_000);
+  const summaryResponse = await waitFor("custom Summary request", async () => {
+    const summary = requests.find((entry) => entry.kind === "summary");
+    return summary?.body?.messages?.some((message) => {
+      if (message?.role !== "user") return false;
+      const content = typeof message.content === "string"
+        ? message.content
+        : JSON.stringify(message.content ?? "");
+      return content.includes("Use short factual bullets");
+    }) ? summary : false;
+  }, 15_000);
+  assert.ok(summaryResponse, "configured summary_prompt reached the provider");
+  const summaryAt = summaryResponse.responseAt;
+
+  const widgetPane = await waitFor("full Recap widget", async () => {
+    const output = await pane(socket, session);
+    return output.includes("FULL_RECAP_TAIL_24") ? output : false;
+  }, 75_000);
+  const widgetAnsi = await pane(socket, session, true);
+  assert.match(widgetPane, /Recap·appearsfinished·[0-9]{2}\/[0-9]{2} [0-9]{2}:[0-9]{2}\(GMT[+-][0-9][^\n]*\[got it\]/);
+  assert.match(widgetPane, /\[got it\]/);
+  assert.match(widgetPane, /FULL_RECAP_TAIL_1/);
+  assert.match(widgetPane, /FULL_RECAP_TAIL_24/);
+  assert.doesNotMatch(widgetPane, /recap expand/i);
+  assert.match(widgetAnsi, /\x1b\[[0-9;]*m/);
+  assert.match(widgetAnsi, /Recap/);
+  assert.match(widgetAnsi, /\x1b\[38;(?:5;241|2;102;102;102)m[^\n]*Recap/, "Recap header uses the muted foreground");
+  assert.match(widgetAnsi, /\x1b\[38;(?:5;244|2;128;128;128)m[^\n]*FULL_RECAP_TAIL_1/, "Recap body uses the faded foreground");
+  assert.ok(Date.now() - summaryAt >= 59_750, "Recap rendered before the one-minute default");
+
+  const requestCountAtWidget = requests.length;
+  await keys(socket, session, "typed while v020 Recap is visible");
+  const typingPane = await waitFor("typing preservation", async () => {
+    const output = await pane(socket, session);
+    return output.includes("typed while v020 Recap is visible") ? output : false;
+  });
+  assert.match(typingPane, /FULL_RECAP_TAIL_24/);
+  assert.equal(requests.length, requestCountAtWidget);
+
+  await press(socket, session, "Enter");
+  await waitFor("second provider request", async () => requests.filter((entry) => entry.kind === "interactive").length >= 2, 15_000);
+  const afterSubmit = await waitFor("second interactive response", async () => {
+    const output = await pane(socket, session);
+    return output.includes("INTERACTIVE_2_DONE") ? output : false;
+  }, 15_000);
+
+  const secondInteractive = requests.filter((entry) => entry.kind === "interactive")[1];
+  assert.doesNotMatch(JSON.stringify(secondInteractive.body), /FULL_RECAP_TAIL/);
+  const sessionFiles = (await walk(sessionDir)).filter((file) => file.endsWith(".jsonl"));
+  const sessionText = (await Promise.all(sessionFiles.map((file) => readFile(file, "utf8")))).join("\n");
+  const nativeEntries = sessionText.split("\n").filter(Boolean).map(JSON.parse);
+  assert.ok(nativeEntries.some((entry) => entry.type === "custom" && entry.customType === "rarebit-recap" && entry.data?.summary?.includes("FULL_RECAP_TAIL_24")), "the scrollable Recap is persisted as native custom evidence");
+  assert.ok(!nativeEntries.filter((entry) => entry.type === "message").some((entry) => JSON.stringify(entry).includes("FULL_RECAP_TAIL")), "Recap prose stays out of model conversation messages");
+  const settings = JSON.parse(await readFile(join(agentDir, "settings.json"), "utf8"));
+  assert.deepEqual(settings.other_extension, { preserve: true });
+  assert.equal(settings.rarebit.summary_prompt, "Use short factual bullets and state uncertainty.");
+
+  const evidence = { widgetPane, widgetAnsi, typingPane, afterSubmit, requests, sessionFiles, packageTarball: packageTarball ?? "source" };
+  const artifactLabel = packageTarball ? "packed artifact loaded by real Pi" : "source checkout loaded by real Pi";
+  if (keepTemp) await writeFile(join(temp, "evidence.json"), JSON.stringify(evidence, null, 2), { mode: 0o600 });
+  console.log(JSON.stringify({
+    ok: true,
+    artifact: packageTarball ?? "source",
+    pi: JSON.parse(await readFile(join(piRoot, "package.json"), "utf8")).version,
+    defaultDelayMs: 60_000,
+    elapsedFromSummaryMs: Date.now() - summaryAt,
+    providerRequests: requests.length,
+    evidenceRoot: keepTemp ? temp : null,
+    checks: [artifactLabel, "custom summary_prompt reached provider", "full multiline native Recap rendered", "ANSI themed Recap rendered", "typing preserved Recap", "native Recap evidence survived submit", "display content excluded from next provider conversation messages"],
+  }, null, 2));
+} catch (error) {
+  console.error(`Rarebit v0.2 Pi E2E failed: ${error?.stack ?? error}`);
+  console.error(`Temporary evidence retained at ${temp}`);
+  throw error;
+} finally {
+  if (tmuxStarted) {
+    await press(socket, session, "C-c").catch(() => {});
+    await sleep(100);
+    await press(socket, session, "C-c").catch(() => {});
+    await execFile(tmux, ["-L", socket, "kill-server"]).catch(() => {});
+  }
+  if (provider?.listening) await new Promise((resolvePromise) => provider.close(resolvePromise));
+  if (!keepTemp) await rm(temp, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+}

package/scripts/experiment-recap-fullscreen.mjs

@@ -0,0 +1,56 @@
+// Empirical Pi 0.84.2 renderer probe. Uses the native fullscreen renderer and
+// a synthetic terminal adapter; no provider, credentials, or private sessions.
+import assert from "node:assert/strict";
+import { TuiAltScreen, ScrollView, Container, Text } from "@earendil-works/pi-tui";
+import { createRarebitRecapController } from "../src/rarebit-recap.mjs";
+import { selectRarebits } from "../src/rarebit-core.mjs";
+
+const { renderLayoutFrame } = await import(new URL("layout.js", import.meta.resolve("@earendil-works/pi-tui")));
+
+let input;
+const terminal = {
+  columns: 80, rows: 12, kittyProtocolActive: false,
+  start(fn) { input = fn; }, stop() {}, write() {}, moveBy() {},
+  hideCursor() {}, showCursor() {}, clearLine() {}, clearFromCursor() {},
+  clearScreen() {}, setTitle() {}, setProgress() {},
+};
+const branch = [{ type: "message", id: "synthetic-owner", message: { role: "user", content: "Synthetic renderer probe" } }];
+const selection = selectRarebits(branch);
+const receipt = { status: "ok", sessionId: "synthetic-session", jobId: "synthetic-recap",
+  observedAt: new Date(0).toISOString(), sessionStatus: "finished", summary: "SCROLLABLE_RECAP_SENTINEL",
+  selection: { manifestHash: selection.manifestHash, selectorVersion: selection.manifest.selectorVersion } };
+const ctx = { mode: "tui", ui: { setWidget() {} }, sessionManager: {
+  getHeader: () => ({ id: receipt.sessionId }), getSessionFile: () => "/tmp/synthetic-probe.jsonl", getBranch: () => branch,
+} };
+const controller = createRarebitRecapController({
+  appendEntry: (customType, data) => branch.push({ type: "custom", id: "synthetic-recap-entry", customType, data }),
+  readCurrent: async () => ({ receipt, artifactState: { syncState: "assessment_current", applicability: "exact_selection",
+    receiptRef: { jobId: receipt.jobId }, projection: { status: receipt.sessionStatus } } }),
+});
+assert.equal((await controller.showExisting(ctx)).shown, true);
+const document = new Container();
+document.addChild(controller.renderEntry(branch.at(-1), {}, { fg: (_color, text) => text }));
+document.addChild(new Text(Array.from({ length: 30 }, (_, i) => `Synthetic update ${i}`).join("\n"), 0, 0));
+const scroll = new ScrollView(document, { primary: true, follow: "none" });
+const tui = new TuiAltScreen(terminal);
+tui.setLayoutRoot(scroll);
+const received = [];
+tui.addInputListener((data) => { received.push(data); });
+try {
+  tui.start(); tui.renderNow();
+  scroll.scrollToStart(); tui.renderNow();
+  const atTop = renderLayoutFrame(scroll, 80, 12, () => {}).lines;
+  assert.ok(atTop.some((line) => line.includes("SCROLLABLE_RECAP_SENTINEL")));
+  input("\x1b[<65;3;4M"); tui.renderNow();
+  const afterWheel = scroll.scrollTop;
+  assert.ok(afterWheel > 0, "native wheel events scroll the transcript");
+  input("\x1b[<0;3;2M"); input("\x1b[<0;3;2m"); input("g");
+  scroll.scrollToEnd(); tui.renderNow();
+  const atBottom = renderLayoutFrame(scroll, 80, 12, () => {}).lines;
+  assert.ok(!atBottom.some((line) => line.includes("SCROLLABLE_RECAP_SENTINEL")), "recap is not pinned");
+  console.log(JSON.stringify({ pi: "0.84.2", nativeRenderer: true, syntheticTerminal: true,
+    recapVisibleAtTop: true, recapVisibleAtBottom: false, wheelScrollTop: afterWheel,
+    keyboardReachedExtension: received.includes("g"),
+    mouseReachedExtension: received.some((data) => data.startsWith("\x1b[<")),
+  }, null, 2));
+} finally { tui.stop(); controller.dispose(); }

package/scripts/verify-package.mjs

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { execFileSync, spawnSync } from "node:child_process";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = fileURLToPath(new URL("..", import.meta.url));
@@ -15,20 +15,26 @@ const required = [
   "package/AGENTS.md", "package/CHANGELOG.md", "package/LICENSE",
   "package/SECURITY.md", "package/bin/rarebit.mjs", "package/bin/piq.mjs",
   "package/src/index.mjs", "package/src/rarebit-fork-lineage.mjs", "package/src/rarebit-fork.mjs", "package/src/types.d.ts",
+  "package/docs/examples/rarebit.settings.json",
   "package/schemas/rarebit.schema.json", "package/test/rarebit-cli.test.mjs",
   "package/scripts/e2e-recall-pi083.mjs", "package/scripts/e2e-recall-pi0842.mjs", "package/scripts/verify-package.mjs",
 ];
 const forbiddenPath = /(^|\/)(\.git|node_modules|\.github|hc-rarebit\.mjs)(\/|$)|HyperCarrier|timeline|pi-team/i;
-const allowedBare = new Set(["@earendil-works/pi-ai", "@earendil-works/pi-coding-agent"]);
+const allowedBare = new Set(["@earendil-works/pi-ai", "@earendil-works/pi-coding-agent", "@earendil-works/pi-tui"]);
 const packageFor = (specifier) => specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
-const packageJson = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
-assert.equal(packageJson.version, "0.1.0-alpha.6", "release version mismatch");
+const packageJson = JSON.parse(run("git", ["show", "HEAD:package.json"]));
 assert.equal(packageJson.peerDependencies?.["@earendil-works/pi-ai"], ">=0.83.0", "Pi AI peer range mismatch");
-for (const peer of ["@earendil-works/pi-ai", "@earendil-works/pi-coding-agent"])
+for (const peer of ["@earendil-works/pi-ai", "@earendil-works/pi-coding-agent", "@earendil-works/pi-tui"])
   assert.equal(packageJson.peerDependenciesMeta?.[peer]?.optional, true, `${peer} peer must remain optional`);
 
-const packed = JSON.parse(npm(["pack", "--json", "--ignore-scripts"]))[0];
-const tarball = join(root, packed.filename);
+const suppliedTarball = process.env.RELEASE_TARBALL;
+const packed = suppliedTarball
+  ? { filename: basename(suppliedTarball), integrity: "provided-tarball" }
+  : JSON.parse(npm(["pack", "--json", "--ignore-scripts"]))[0];
+const tarball = suppliedTarball ? resolve(root, suppliedTarball) : join(root, packed.filename);
+const packedPackageJson = JSON.parse(run("tar", ["-xOf", tarball, "package/package.json"]));
+assert.equal(packedPackageJson.name, packageJson.name, "packed package name differs from selected source");
+assert.equal(packedPackageJson.version, packageJson.version, "packed package version differs from selected source");
 const entries = run("tar", ["-tf", tarball]).trim().split("\n").filter(Boolean).sort();
 for (const path of required) assert(entries.includes(path), `tarball lacks ${path}`);
 for (const path of entries) assert(!forbiddenPath.test(path), `forbidden tar entry: ${path}`);
@@ -81,5 +87,5 @@ try {
   process.stdout.write(`verified ${packed.filename} (${packed.integrity}) with ${entries.length} tar entries\n`);
 } finally {
   await rm(temp, { recursive: true, force: true });
-  await rm(tarball, { force: true });
+  if (!suppliedTarball) await rm(tarball, { force: true });
 }