@hypercarrier/rarebit 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.5.0 — 2026-10-07
+
+- Add `/rarebit btw [--rarebits] [--readonly] [question]`. It opens a
+  temporary side Pi in a Herdr split on a private snapshot of the active
+  branch, so you can ask about history while the main agent keeps working.
+  `--rarebits` snapshots only Rarebit messages. By default the side Pi
+  inherits the parent's active tools; `--readonly` limits it to read-only
+  built-in tools without extensions.
+- Add the optional `rarebit.btw.model` setting and a BTW model field in
+  Rarebit settings. Unset, BTW uses the parent model and thinking level.
+- Autocomplete `/rarebit btw` flags. Add BTW actions to the command palette.
+
+## 0.4.0 — 2026-10-07
+
+- Replace Recall's hour-bucketed `rarebit_conversation/v1` with a flat
+  `rarebit_conversation/v2` message list. Each message has `seq`, `round`,
+  `role`, `kind`, second-precision UTC `time`, and `text`. Detailed evidence
+  occurrences gain the same `seq` join key.
+- Add the conversation schema and `jq` tail queries to the Recall message.
+
 ## 0.3.0 — 2026-10-04
 
 - Add `/rarebit view [context|all|peek|off]` and a View action in the palette.

package/README.md

@@ -173,6 +173,30 @@ npm exec -- piq entries --session /absolute/path/to/session.jsonl
 PiQ is read-only JSONL output for `jq`. It does not classify Rarebits, mutate a
 Session, invoke a model, or migrate legacy entries.
 
+#### BTW: side questions while the agent works
+
+`/rarebit btw` opens a temporary Pi in a Herdr split beside the current pane.
+Ask it about the history while the main agent keeps working. The main Session
+is unchanged.
+
+```text
+/rarebit btw What did we decide about the release version?
+/rarebit btw --rarebits --readonly Why did we drop the old schema?
+```
+
+- By default, BTW copies the active branch. `--rarebits` copies only the
+  Rarebit messages, which is cheaper and reaches past compaction.
+- By default, the side Pi loads extensions and enables the parent's active
+  tools. `--readonly` enables only `read`, `grep`, `find`, and `ls`, and loads
+  no extensions, skills, context files, or MCP servers.
+- The side Pi uses `rarebit.btw.model` when set, for example
+  `"btw": { "model": "provider/model:low" }`. Otherwise it uses the parent
+  model and thinking level.
+- A new BTW replaces the earlier BTW pane in the tab. Closing the pane deletes
+  the private snapshot in the OS temp directory.
+
+BTW requires Pi inside Herdr.
+
 ### 4. Summary, Title, and Recap
 
 Summary and Title are optional derivations over the selected evidence. Recap is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercarrier/rarebit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Sparse, provenance-bearing conversational evidence recovery for Pi sessions.",
   "license": "MIT",
   "author": "HyperCarrier contributors",

package/scripts/e2e-btw-herdr.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Live Rarebit BTW canary in Herdr with the installed Pi and a real model.
+ *
+ * Uses only synthetic Session prose in a disposable directory. It opens an
+ * unfocused Herdr tab, starts Pi with this Rarebit checkout on the synthetic
+ * Session, types `/rarebit btw ...`, and checks that the side pane answers a
+ * question that needs the history but is not a copy of it. It then checks
+ * pane replacement and snapshot cleanup.
+ *
+ * Env: RAREBIT_BTW_E2E_MODEL (default magpie/claude/claude-haiku-4-5).
+ */
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+const packageRoot = resolve(dirname(new URL(import.meta.url).pathname), "..");
+const herdrBin = process.env.HERDR_BIN_PATH || "herdr";
+const model = process.env.RAREBIT_BTW_E2E_MODEL ?? "magpie/claude/claude-haiku-4-5";
+const LABEL = "rarebit-btw";
+
+const herdr = (...args) => {
+  const out = execFileSync(herdrBin, args, { encoding: "utf8", timeout: 120_000 });
+  return out.trim() ? JSON.parse(out) : {};
+};
+const herdrText = (...args) => execFileSync(herdrBin, args, { encoding: "utf8", timeout: 120_000 });
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+const quote = (value) => `'${String(value).replaceAll("'", "'\\''")}'`;
+
+function assistantMessage(text) {
+  return {
+    role: "assistant", content: [{ type: "text", text }], api: "synthetic", provider: "synthetic",
+    model: "synthetic", stopReason: "stop", timestamp: Date.parse("2026-10-07T00:00:02Z"),
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+  };
+}
+
+async function syntheticSession(directory) {
+  const file = join(directory, "source.jsonl");
+  const lines = [
+    { type: "session", version: 3, id: "btw-e2e-source", timestamp: "2026-10-07T00:00:00.000Z", cwd: directory },
+    { type: "message", id: "u1", parentId: null, timestamp: "2026-10-07T00:00:01.000Z",
+      message: { role: "user", content: "Plan: the synthetic deploy window opens at 14:30 UTC and lasts 95 minutes.", timestamp: Date.parse("2026-10-07T00:00:01Z") } },
+    { type: "message", id: "a1", parentId: "u1", timestamp: "2026-10-07T00:00:02.000Z",
+      message: assistantMessage("Noted the synthetic deploy window plan.") },
+  ];
+  await writeFile(file, `${lines.map((line) => JSON.stringify(line)).join("\n")}\n`);
+  return file;
+}
+
+const btwPanes = (tabId) => herdr("pane", "list").result.panes
+  .filter((pane) => pane.tab_id === tabId && pane.label === LABEL);
+
+async function waitForBtwPane(tabId, exclude, timeoutMs = 20_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const pane = btwPanes(tabId).find((candidate) => candidate.pane_id !== exclude);
+    if (pane) return pane.pane_id;
+    await sleep(250);
+  }
+  throw new Error("no BTW pane appeared");
+}
+
+async function snapshotDirs() {
+  return new Set((await readdir(tmpdir())).filter((name) => name.startsWith("hc-rarebit-btw-")));
+}
+
+async function ask(mainPane, tabId, command, previousPane) {
+  const before = await snapshotDirs();
+  herdrText("pane", "send-text", mainPane, command);
+  herdrText("pane", "send-keys", mainPane, "Enter");
+  const pane = await waitForBtwPane(tabId, previousPane);
+  herdrText("pane", "wait-output", pane, "--regex", "ANSWER\\s*=\\s*16:05", "--timeout", "120000");
+  const created = [...await snapshotDirs()].filter((name) => !before.has(name));
+  assert.equal(created.length, 1, "one private snapshot per BTW");
+  herdrText("pane", "wait-output", mainPane, "--match", "Rarebit BTW opened", "--timeout", "10000");
+  const snapshot = join(tmpdir(), created[0]);
+  return { pane, snapshot, launcher: await readFile(join(snapshot, "launch.sh"), "utf8") };
+}
+
+const work = await mkdtemp(join(tmpdir(), "rarebit-btw-e2e-"));
+let tabId;
+try {
+  const source = await syntheticSession(work);
+  const tab = herdr("tab", "create", "--no-focus", "--cwd", work, "--label", "rarebit-btw-e2e");
+  tabId = tab.result.tab.tab_id;
+  const mainPane = tab.result.root_pane.pane_id;
+  herdrText("pane", "run", mainPane, [
+    "pi", "--session", source, "--no-extensions", "-e", join(packageRoot, "src/extension.mjs"),
+    "--model", model, "--no-skills", "--no-context-files", "--no-mcp",
+  ].map(quote).join(" "));
+  herdrText("pane", "wait-output", mainPane, "--match", "deploy window", "--timeout", "60000");
+  await sleep(1500);
+
+  const question = "When does the deploy window close? Reply exactly as ANSWER=HH:MM";
+  const rarebits = await ask(mainPane, tabId, `/rarebit btw --rarebits --readonly ${question}`);
+  assert.match(rarebits.launcher, /'--no-extensions'.*'--tools' 'read,grep,find,ls'|'--tools' 'read,grep,find,ls'.*'--no-extensions'/s);
+  console.log(`ok read-only Rarebits BTW answered in ${rarebits.pane}`);
+
+  const full = await ask(mainPane, tabId, `/rarebit btw ${question}`, rarebits.pane);
+  assert.deepEqual(btwPanes(tabId).map((pane) => pane.pane_id), [full.pane], "the new BTW replaced the old one");
+  assert.match(full.launcher, /'--tools' '[^']*read[^']*bash/, "full BTW inherits the parent's active tools");
+  assert.doesNotMatch(full.launcher, /--no-extensions/);
+  const replacedName = rarebits.snapshot.split("/").at(-1);
+  for (const deadline = Date.now() + 15_000; (await snapshotDirs()).has(replacedName) && Date.now() < deadline;) await sleep(500);
+  assert.ok(!(await snapshotDirs()).has(replacedName), "replaced BTW deleted its snapshot");
+  console.log(`ok full BTW with inherited tools answered in ${full.pane} and replaced the earlier pane`);
+
+  herdrText("pane", "close", full.pane);
+  const name = full.snapshot.split("/").at(-1);
+  const deadline = Date.now() + 15_000;
+  while ((await snapshotDirs()).has(name) && Date.now() < deadline) await sleep(500);
+  assert.ok(!(await snapshotDirs()).has(name), "closed BTW deleted its snapshot");
+  console.log("ok closing the BTW pane deleted its snapshot");
+} catch (error) {
+  if (tabId) {
+    for (const pane of herdr("pane", "list").result.panes.filter((p) => p.tab_id === tabId))
+      console.error(`--- ${pane.pane_id} ${pane.label ?? ""}\n${herdrText("pane", "read", pane.pane_id, "--source", "recent-unwrapped").split("\n").slice(-25).join("\n")}`);
+  }
+  throw error;
+} finally {
+  if (tabId) try { herdrText("tab", "close", tabId); } catch {}
+  await rm(work, { recursive: true, force: true });
+}

package/scripts/e2e-recall-pi0842.mjs

@@ -18,29 +18,47 @@ async function waitFor(predicate, label, timeout = 2_000) {
 function expectedRecallMarkdown(conversationPath, detailedPath, request) {
   return `# Rarebit Recall
 
-*Use these local private evidence files to recover historical context for this turn.*
+*Answer the **Current request** below. Use these local private files to recover earlier context from this Session.*
 
-## How to use this bundle
+## Files
 
-1. Treat **Current request** below as the exact current user request.
-2. Read **Conversation** first for meaning.
-3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
-4. Answer the current request using this evidence.
-
-## Local private evidence files
-
-**Conversation** — \`rarebit_conversation/v1\`
+**Conversation** — \`rarebit_conversation/v2\`. Read this first.
 
 \`\`\`text
 ${conversationPath}
 \`\`\`
 
-**Detailed evidence** — \`rarebit_message_recall/v1\`
+**Detailed evidence** — \`rarebit_message_recall/v1\`. Use it only for source, Session, branch, or lineage facts. Join on \`seq\`.
 
 \`\`\`text
 ${detailedPath}
 \`\`\`
 
+## Conversation schema
+
+\`\`\`text
+{ messageCount, lastRound, messages: [{ seq, round, role, kind, time, text }] }
+seq    1-based, oldest first
+round  increments at each user message; agent messages before the first user message have round 0
+role   "user" | "agent"
+kind   "request" (user) | "progress" (agent text before a tool call) | "reply" (agent final answer)
+time   UTC "YYYY-MM-DDTHH:MM:SSZ", or null
+\`\`\`
+
+Messages contain user and agent text only. Tool calls and tool results are excluded.
+
+## Example queries
+
+Set \`F\` to the Conversation path. Read the smallest slice that answers the request.
+
+\`\`\`sh
+jq '.messages[-20:]' "$F"                                              # last 20 messages
+jq '[.messages[] | select(.role == "user")][-3:]' "$F"                 # last 3 user messages
+jq '[.messages[] | select(.kind == "reply")][-10:]' "$F"               # last 10 agent replies
+jq '.lastRound as $r | [.messages[] | select(.round > $r - 5)]' "$F"  # last 5 rounds
+jq '(now - 8*3600 | todate) as $t | [.messages[] | select(.time >= $t)]' "$F"  # last 8 hours
+\`\`\`
+
 ## Current request
 
 \`\`\`text
@@ -50,7 +68,7 @@ ${request}
 
 function conversationPathFrom(message) {
   const match = message.match(
-    /\*\*Conversation\*\* — `rarebit_conversation\/v1`\n\n```text\n([^\n]*rarebit-conversation\.json)\n```/,
+    /\*\*Conversation\*\* — `rarebit_conversation\/v2`\. Read this first\.\n\n```text\n([^\n]*rarebit-conversation\.json)\n```/,
   );
   assert.ok(match, "Recall Markdown must contain the fenced conversation path");
   return match[1];
@@ -58,7 +76,7 @@ function conversationPathFrom(message) {
 
 function detailedPathFrom(message) {
   const match = message.match(
-    /\*\*Detailed evidence\*\* — `rarebit_message_recall\/v1`\n\n```text\n([^\n]*rarebit-evidence\.json)\n```/,
+    /\*\*Detailed evidence\*\* — `rarebit_message_recall\/v1`\. Use it only for source, Session, branch, or lineage facts\. Join on `seq`\.\n\n```text\n([^\n]*rarebit-evidence\.json)\n```/,
   );
   assert.ok(match, "Recall Markdown must contain the fenced detailed path");
   return match[1];

package/src/extension.mjs

@@ -32,6 +32,7 @@ import {
   sessionFilenameFor,
   writeRarebitForkFile,
 } from "./rarebit-fork.mjs";
+import { openRarebitBtwPane, prepareRarebitBtw, watchRarebitBtwPane } from "./rarebit-btw.mjs";
 import {
   RAREBIT_CONVERSATION_SCHEMA_VERSION,
   RAREBIT_RECALL_SCHEMA_VERSION,
@@ -118,6 +119,10 @@ export async function readConfiguredRarebitSettings({
     summaryPrompt: resolved.summaryPrompt,
     diagnostics: resolved.diagnostics,
     recap: resolved.recap,
+    ...(resolved.btwModel ? { btwModel: resolved.btwModel } : {}),
+    ...(resolved.btwModelConfigurationError
+      ? { btwModelConfigurationError: resolved.btwModelConfigurationError }
+      : {}),
     reserveTokens: resolveReserveTokens(global.value, project.value, model),
   };
 }
@@ -543,25 +548,43 @@ export default function registerPiRarebit(pi, config = {}) {
   };
   const recallMessage = (recall, requestText) => `# Rarebit Recall
 
-*Use these local private evidence files to recover historical context for this turn.*
-
-## How to use this bundle
+*Answer the **Current request** below. Use these local private files to recover earlier context from this Session.*
 
-1. Treat **Current request** below as the exact current user request.
-2. Read **Conversation** first for meaning.
-3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
-4. Answer the current request using this evidence.
+## Files
 
-## Local private evidence files
-
-**Conversation** — \`rarebit_conversation/v${RAREBIT_CONVERSATION_SCHEMA_VERSION}\`
+**Conversation** — \`rarebit_conversation/v${RAREBIT_CONVERSATION_SCHEMA_VERSION}\`. Read this first.
 
 ${fence(recall.conversationPath)}
 
-**Detailed evidence** — \`rarebit_message_recall/v${RAREBIT_RECALL_SCHEMA_VERSION}\`
+**Detailed evidence** — \`rarebit_message_recall/v${RAREBIT_RECALL_SCHEMA_VERSION}\`. Use it only for source, Session, branch, or lineage facts. Join on \`seq\`.
 
 ${fence(recall.detailedPath)}
 
+## Conversation schema
+
+\`\`\`text
+{ messageCount, lastRound, messages: [{ seq, round, role, kind, time, text }] }
+seq    1-based, oldest first
+round  increments at each user message; agent messages before the first user message have round 0
+role   "user" | "agent"
+kind   "request" (user) | "progress" (agent text before a tool call) | "reply" (agent final answer)
+time   UTC "YYYY-MM-DDTHH:MM:SSZ", or null
+\`\`\`
+
+Messages contain user and agent text only. Tool calls and tool results are excluded.
+
+## Example queries
+
+Set \`F\` to the Conversation path. Read the smallest slice that answers the request.
+
+\`\`\`sh
+jq '.messages[-20:]' "$F"                                              # last 20 messages
+jq '[.messages[] | select(.role == "user")][-3:]' "$F"                 # last 3 user messages
+jq '[.messages[] | select(.kind == "reply")][-10:]' "$F"               # last 10 agent replies
+jq '.lastRound as $r | [.messages[] | select(.round > $r - 5)]' "$F"  # last 5 rounds
+jq '(now - 8*3600 | todate) as $t | [.messages[] | select(.time >= $t)]' "$F"  # last 8 hours
+\`\`\`
+
 ## Current request
 
 ${fence(requestText)}`;
@@ -737,6 +760,30 @@ ${fence(requestText)}`;
         }
         return;
       }
+      if (subcommand === "btw") {
+        const flags = command.flags ?? [];
+        let btw;
+        try {
+          const effective = await loadEffective(ctx);
+          if (effective.btwModelConfigurationError) throw new Error(effective.btwModelConfigurationError);
+          const readonly = flags.includes("--readonly");
+          btw = await prepareRarebitBtw(ctx, {
+            mode: flags.includes("--rarebits") ? "rarebits" : "full",
+            question: rest[0] ?? "",
+            readonly,
+            activeTools: readonly ? undefined : pi.getActiveTools?.(),
+            model: effective.btwModel,
+            thinking: pi.getThinkingLevel?.(),
+          });
+          const opened = await openRarebitBtwPane({ launcherPath: btw.launcherPath, cwd: ctx.cwd ?? process.cwd() });
+          watchRarebitBtwPane({ paneId: opened.paneId, directory: btw.directory });
+          notify(ctx, `Rarebit BTW opened beside this pane (${btw.mode}${btw.readonly ? ", readonly" : ""}; ${btw.model ?? "default model"}; ${btw.summary})`, "info");
+        } catch (error) {
+          await btw?.discard();
+          notify(ctx, `Rarebit BTW failed: ${error?.message ?? error}`, "error");
+        }
+        return;
+      }
       if (subcommand === "recall") {
         const prompt = rest[0];
         if (typeof pi.sendUserMessage !== "function") {

package/src/rarebit-btw.mjs

@@ -0,0 +1,245 @@
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+
+import {
+  buildRarebitForkPlan,
+  createRarebitForkEntries,
+  writeRarebitForkFile,
+} from "./rarebit-fork.mjs";
+
+/**
+ * Rarebit BTW: a temporary side Pi Session beside the main Session.
+ *
+ * The main Session stays the authority. BTW writes a private snapshot of the
+ * active branch to the OS temp directory, opens a Herdr split, and runs a
+ * second Pi on that snapshot. By default the side Pi loads extensions as
+ * usual and enables the parent's active tools. Read-only BTW enables only
+ * read-only built-in tools and loads no extensions, skills, context files,
+ * or MCP servers. Closing the side Pi deletes the snapshot.
+ */
+
+export const RAREBIT_BTW_MODES = Object.freeze(["full", "rarebits"]);
+export const RAREBIT_BTW_PANE_LABEL = "rarebit-btw";
+export const RAREBIT_BTW_READONLY_TOOLS = "read,grep,find,ls";
+
+const execFileAsync = promisify(execFile);
+
+function messageOf(entry) {
+  return entry?.type === "message" ? entry.message : null;
+}
+
+/**
+ * Drop the unfinished tail of a mid-turn snapshot: the first assistant
+ * message whose tool calls have no results, and everything after it.
+ */
+export function completedBranchPrefix(branch) {
+  const resultIds = new Set();
+  for (const entry of branch) {
+    const message = messageOf(entry);
+    if (message?.role === "toolResult" && message.toolCallId) resultIds.add(message.toolCallId);
+  }
+  const cut = branch.findIndex((entry) => {
+    const message = messageOf(entry);
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) return false;
+    return message.content.some((part) => part?.type === "toolCall" && !resultIds.has(part.id));
+  });
+  return cut < 0 ? branch : branch.slice(0, cut);
+}
+
+/** Full mode: the active branch verbatim, under a new Session header. */
+export function createFullBtwEntries({ header, sessionFile, cwd, branch, now = new Date() }) {
+  const entries = completedBranchPrefix(branch);
+  const sessionId = randomUUID();
+  return {
+    sessionId,
+    header: {
+      type: "session",
+      version: header?.version ?? 3,
+      id: sessionId,
+      timestamp: now.toISOString(),
+      cwd: resolve(cwd ?? header?.cwd ?? process.cwd()),
+      parentSession: resolve(sessionFile),
+    },
+    entries,
+    droppedTailEntries: branch.length - entries.length,
+  };
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+export function btwSystemPrompt({ mode, sourceFile, readonly = false }) {
+  const history = mode === "rarebits"
+    ? "This Session holds only the Rarebit messages of another Pi Session: user requests and final agent replies."
+    : "This Session is a copy of another Pi Session's active branch.";
+  return [
+    "## BTW side chat",
+    history,
+    "The user asks quick side questions about that history while the original agent keeps working.",
+    "- Answer from the history. Be brief.",
+    readonly
+      ? "- Do not continue the original task. Do not modify files."
+      : "- Do not continue the original task unless the user asks.",
+    `- For detail the history omits, search the source Session JSONL with grep or read: ${sourceFile}`,
+  ].join("\n");
+}
+
+function toolArguments({ readonly, activeTools }) {
+  if (readonly) return [
+    "--tools", RAREBIT_BTW_READONLY_TOOLS,
+    "--no-extensions", "--no-skills", "--no-prompt-templates", "--no-context-files", "--no-mcp",
+  ];
+  if (!Array.isArray(activeTools)) return [];
+  return activeTools.length > 0 ? ["--tools", activeTools.join(",")] : ["--no-tools"];
+}
+
+/** The argv for the side Pi. */
+export function btwPiArguments({ sessionFile, model, thinking, readonly = false, activeTools, systemPrompt, question, name }) {
+  return [
+    "--session", sessionFile,
+    ...(model?.provider && model?.id ? ["--model", `${model.provider}/${model.id}`] : []),
+    ...(thinking ? ["--thinking", thinking] : []),
+    ...toolArguments({ readonly, activeTools }),
+    "--append-system-prompt", systemPrompt,
+    ...(name ? ["--name", name] : []),
+    ...(question ? ["--", question] : []),
+  ];
+}
+
+/** A launcher that runs the side Pi, then deletes the snapshot and exits the pane shell. */
+export function btwLauncherScript({ piCommand = "pi", piArguments, directory }) {
+  return [
+    "#!/bin/sh",
+    `trap ${shellQuote(`rm -rf ${shellQuote(directory)}`)} EXIT`,
+    "trap 'exit 129' HUP INT TERM",
+    `${shellQuote(piCommand)} ${piArguments.map(shellQuote).join(" ")}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Write the snapshot and launcher. Returns paths and counts; the caller owns
+ * `discard` until the launcher runs.
+ */
+export async function prepareRarebitBtw(ctx, {
+  mode = "full",
+  question = "",
+  readonly = false,
+  activeTools,
+  model: configuredModel,
+  thinking,
+  tempRoot = tmpdir(),
+  now = () => new Date(),
+  piCommand = "pi",
+} = {}) {
+  if (!RAREBIT_BTW_MODES.includes(mode)) throw new Error(`unknown BTW mode ${mode}`);
+  const sourceFile = ctx?.sessionManager?.getSessionFile?.();
+  const branch = ctx?.sessionManager?.getBranch?.();
+  const header = ctx?.sessionManager?.getHeader?.();
+  if (typeof sourceFile !== "string" || !Array.isArray(branch))
+    throw new Error("the current Pi Session must be persisted before BTW");
+  // A configured BTW model carries its own optional `:thinking` suffix; the
+  // parent model brings the parent thinking level.
+  const model = configuredModel ?? ctx?.model ?? null;
+  const sideThinking = configuredModel ? undefined : thinking;
+  const directory = await mkdtemp(join(resolve(tempRoot), "hc-rarebit-btw-"));
+  try {
+    await chmod(directory, 0o700);
+    let session;
+    let summary;
+    if (mode === "rarebits") {
+      const plan = buildRarebitForkPlan({
+        header, sessionFile: sourceFile, cwd: ctx.cwd, branch, targetCwd: ctx.cwd,
+        maxTokenLength: Math.max(1, Math.floor((model?.contextWindow ?? ctx?.model?.contextWindow ?? 200_000) / 2)),
+        targetModel: model, forkCreatedAt: now().toISOString(),
+      });
+      session = createRarebitForkEntries(plan);
+      summary = `${plan.selected.length} Rarebit messages, ~${plan.importedTokens} tokens` +
+        (plan.omittedOccurrences ? `, ${plan.omittedOccurrences} older omitted` : "");
+    } else {
+      session = createFullBtwEntries({ header, sessionFile: sourceFile, cwd: ctx.cwd, branch, now: now() });
+      summary = `${session.entries.length} entries` +
+        (session.droppedTailEntries ? `, ${session.droppedTailEntries} unfinished dropped` : "");
+    }
+    const sessionFile = join(directory, "session.jsonl");
+    await writeRarebitForkFile(sessionFile, session);
+    const piArguments = btwPiArguments({
+      sessionFile, model, thinking: sideThinking, readonly, activeTools,
+      systemPrompt: btwSystemPrompt({ mode, sourceFile: resolve(sourceFile), readonly }),
+      question: String(question ?? "").trim(),
+      name: `btw: ${mode}${readonly ? ", readonly" : ""}`,
+    });
+    const launcherPath = join(directory, "launch.sh");
+    await writeFile(launcherPath, btwLauncherScript({ piCommand, piArguments, directory }), { mode: 0o700 });
+    return {
+      mode, readonly, directory, sessionFile, launcherPath, summary,
+      model: model?.provider && model?.id ? `${model.provider}/${model.id}` : null,
+      discard: () => rm(directory, { recursive: true, force: true }),
+    };
+  } catch (error) {
+    await rm(directory, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function herdrJson(herdrBin, args, run) {
+  const { stdout } = await run(herdrBin, args, { timeout: 5_000 });
+  return stdout.trim() ? JSON.parse(stdout) : {};
+}
+
+/**
+ * Open the side Pi in a Herdr split beside `paneId`. Another BTW pane already
+ * open in the same tab is closed first, so each BTW starts from a fresh
+ * snapshot. A BTW started inside a BTW pane keeps its own pane.
+ */
+export async function openRarebitBtwPane({
+  launcherPath,
+  cwd,
+  paneId = process.env.HERDR_PANE_ID,
+  herdrBin = process.env.HERDR_BIN_PATH || "herdr",
+  direction = "right",
+  ratio = 0.45,
+  run = execFileAsync,
+} = {}) {
+  if (!paneId) throw new Error("BTW needs Herdr: HERDR_PANE_ID is not set");
+  const current = await herdrJson(herdrBin, ["pane", "get", paneId], run);
+  const tabId = current?.result?.pane?.tab_id;
+  const listed = await herdrJson(herdrBin, ["pane", "list"], run);
+  for (const pane of listed?.result?.panes ?? []) {
+    if (pane.tab_id === tabId && pane.label === RAREBIT_BTW_PANE_LABEL && pane.pane_id !== paneId)
+      await run(herdrBin, ["pane", "close", pane.pane_id], { timeout: 5_000 });
+  }
+  const split = await herdrJson(herdrBin, [
+    "pane", "split", paneId, "--direction", direction, "--ratio", String(ratio),
+    "--cwd", cwd, "--focus",
+  ], run);
+  const newPaneId = split?.result?.pane?.pane_id;
+  if (!newPaneId) throw new Error("Herdr did not report the new pane");
+  await run(herdrBin, ["pane", "rename", newPaneId, RAREBIT_BTW_PANE_LABEL], { timeout: 5_000 });
+  await run(herdrBin, ["pane", "run", newPaneId, `exec sh ${shellQuote(launcherPath)}`], { timeout: 5_000 });
+  return { paneId: newPaneId };
+}
+
+/**
+ * Delete the snapshot once Herdr no longer reports the BTW pane. Herdr may
+ * kill the pane before the launcher's EXIT trap runs, so cleanup follows
+ * the pane's lifetime in a detached process that outlives both Pis.
+ */
+export function watchRarebitBtwPane({
+  paneId,
+  directory,
+  herdrBin = process.env.HERDR_BIN_PATH || "herdr",
+  intervalSeconds = 3,
+  spawnImpl = spawn,
+}) {
+  const script = [
+    `while [ -d ${shellQuote(directory)} ] && ${shellQuote(herdrBin)} pane get ${shellQuote(paneId)} >/dev/null 2>&1; do sleep ${Number(intervalSeconds)}; done`,
+    `rm -rf ${shellQuote(directory)}`,
+  ].join("; ");
+  spawnImpl("sh", ["-c", script], { detached: true, stdio: "ignore" }).unref();
+}

package/src/rarebit-command.mjs

@@ -10,6 +10,8 @@ const number = (usage, validate) => ({
   validate,
 });
 
+const flag = (value, description) => ({ value, description });
+
 const rest = (usage) => ({
   kind: "rest",
   usage,
@@ -49,6 +51,15 @@ export const RAREBIT_COMMAND_GRAMMAR = Object.freeze({
       description: "Recall active-branch Rarebit messages with a prompt",
       forms: [[rest("<prompt...>")]],
     },
+    {
+      name: "btw",
+      description: "Ask side questions in a temporary Pi beside this one (Herdr)",
+      flags: [
+        flag("--rarebits", "Fork only Rarebit messages (default: full branch)"),
+        flag("--readonly", "Read-only tools, no extensions (default: inherit tools)"),
+      ],
+      forms: [[], [rest("<question...>")]],
+    },
     {
       name: "fork",
       description: "Open a bounded Rarebit fork without starting a model turn",
@@ -142,7 +153,8 @@ export function rarebitCommandUsage(
   );
   if (!definition) return rarebitCommandUsage(undefined, grammar);
   const note = definition.usageNote ? ` (${definition.usageNote})` : "";
-  return `Usage: /${grammar.name} ${definition.name}${renderForms(definition.forms)}${note}`;
+  const flags = (definition.flags ?? []).map(({ value }) => ` [${value}]`).join("");
+  return `Usage: /${grammar.name} ${definition.name}${flags}${renderForms(definition.forms)}${note}`;
 }
 
 const matchToken = (definition, rawValue) => {
@@ -152,6 +164,28 @@ const matchToken = (definition, rawValue) => {
   return Number.isFinite(value) && definition.validate(value);
 };
 
+const flagValues = (definition) => new Set((definition.flags ?? []).map(({ value }) => value));
+
+// Leading flags, in any order, precede the free-form text.
+function withFlags(definition, argumentsBefore) {
+  const known = flagValues(definition);
+  let text = String(argumentsBefore.at(-1) ?? "");
+  const flags = [];
+  for (;;) {
+    const word = text.match(/^\s*(\S+)/)?.[1];
+    if (!word || !known.has(word)) break;
+    if (!flags.includes(word)) flags.push(word);
+    text = text.replace(/^\s*\S+/, "");
+  }
+  const question = text.trim() ? text.replace(/^\s/, "") : "";
+  return {
+    ok: true,
+    subcommand: definition.name,
+    flags,
+    arguments: [...argumentsBefore.slice(0, -1), ...(question ? [question] : [])],
+  };
+}
+
 export function parseRarebitCommand(input, grammar = RAREBIT_COMMAND_GRAMMAR) {
   const rawInput = String(input ?? "");
   const tokens = rawInput.trim().split(/\s+/).filter(Boolean);
@@ -170,6 +204,9 @@ export function parseRarebitCommand(input, grammar = RAREBIT_COMMAND_GRAMMAR) {
   const freeform = definition.forms.find(
     (form) => form.at(-1)?.kind === "rest",
   );
+  if (freeform && tokens.length === 1 && definition.forms.some((form) => form.length === 0)) {
+    return { ok: true, subcommand: definition.name, ...(definition.flags ? { flags: [] } : {}), arguments: [] };
+  }
   if (freeform) {
     const prefix = freeform.slice(0, -1);
     const leading = rawInput.trimStart();
@@ -191,6 +228,7 @@ export function parseRarebitCommand(input, grammar = RAREBIT_COMMAND_GRAMMAR) {
     }
     if (prefixMatches && /^\s/.test(remaining)) {
       const prompt = remaining.slice(1);
+      if (definition.flags) return withFlags(definition, [...parsed, prompt]);
       if (matchToken(freeform.at(-1), prompt)) {
         return {
           ok: true,
@@ -289,6 +327,21 @@ export function getRarebitArgumentCompletions(
   const matches = [];
   const seen = new Set();
 
+  if (definition.flags) {
+    const known = flagValues(definition);
+    if (!priorArguments.every((value) => known.has(value))) return null;
+    const flagMatches = definition.flags
+      .filter(({ value }) => !priorArguments.includes(value) && value.startsWith(partial))
+      .map(({ value, description }) =>
+        completionItem({
+          value: `${[definition.name, ...priorArguments, value].join(" ")} `,
+          label: value,
+          description,
+        }),
+      );
+    return flagMatches.length > 0 ? flagMatches : null;
+  }
+
   for (const form of definition.forms) {
     const priorMatches = priorArguments.every(
       (value, index) => form[index] && matchToken(form[index], value),

package/src/rarebit-recall.mjs

@@ -6,7 +6,7 @@ import { isAbsolute, join, resolve } from "node:path";
 import { selectRarebits } from "./rarebit-core.mjs";
 
 export const RAREBIT_RECALL_SCHEMA_VERSION = 1;
-export const RAREBIT_CONVERSATION_SCHEMA_VERSION = 1;
+export const RAREBIT_CONVERSATION_SCHEMA_VERSION = 2;
 export const RAREBIT_RECALL_DETAILED_FILENAME = "rarebit-evidence.json";
 export const RAREBIT_RECALL_CONVERSATION_FILENAME = "rarebit-conversation.json";
 
@@ -52,16 +52,20 @@ function recallDocument({ sessionId, sessionFile, branch, selection, now }) {
       occurrenceCount: selection.occurrences.length,
       uniquePayloadCount: selection.payloads.length,
       occurrences: selection.occurrences.map(
-        ({
-          occurrenceId,
+        (
+          {
+            occurrenceId,
           sourceEntryId,
           order,
           timestamp,
           role,
           outcome,
-          contentHash,
-          text,
-        }) => ({
+            contentHash,
+            text,
+          },
+          index,
+        ) => ({
+          seq: index + 1,
           occurrenceId,
           sourceEntryId,
           order,
@@ -76,37 +80,45 @@ function recallDocument({ sessionId, sessionFile, branch, selection, now }) {
   };
 }
 
-function conversationHour(timestamp) {
+// Second precision matches jq `todate`, so `.time >= (now - N | todate)` and
+// `fromdate` work without parsing fractional seconds.
+function conversationTime(timestamp) {
   if (typeof timestamp !== "string") return null;
   const value = new Date(timestamp);
   if (Number.isNaN(value.getTime())) return null;
-  return `${value.toISOString().slice(0, 13)}:00Z`;
+  return `${value.toISOString().slice(0, 19)}Z`;
 }
 
+const CONVERSATION_KIND = Object.freeze({
+  user: "request",
+  continuation: "progress",
+  stop: "reply",
+});
+
+/**
+ * One flat, branch-ordered message list. `seq` matches the detailed
+ * occurrence `seq`. A round starts at each user message, so tail slices by
+ * message, role, kind, round, or time are single jq filters.
+ */
 function conversationDocument(selection) {
-  const byHour = new Map();
-  for (const occurrence of selection.occurrences) {
-    const hour = conversationHour(occurrence.timestamp);
-    let bucket = byHour.get(hour);
-    if (!bucket) {
-      bucket = { hour, messages: [] };
-      byHour.set(hour, bucket);
-    }
-    bucket.messages.push({
-      role: occurrence.role === "user" ? "user" : "agent",
-      content: occurrence.text,
-    });
-  }
-  const hours = [...byHour.values()].sort((left, right) => {
-    if (left.hour === null) return right.hour === null ? 0 : 1;
-    if (right.hour === null) return -1;
-    return left.hour.localeCompare(right.hour);
+  let round = 0;
+  const messages = selection.occurrences.map((occurrence, index) => {
+    if (occurrence.outcome === "user") round += 1;
+    return {
+      seq: index + 1,
+      round,
+      role: occurrence.outcome === "user" ? "user" : "agent",
+      kind: CONVERSATION_KIND[occurrence.outcome],
+      time: conversationTime(occurrence.timestamp),
+      text: occurrence.text,
+    };
   });
   return {
     schemaVersion: RAREBIT_CONVERSATION_SCHEMA_VERSION,
     type: "rarebit_conversation",
-    timeZone: "UTC",
-    hours,
+    messageCount: messages.length,
+    lastRound: round,
+    messages,
   };
 }
 

package/src/rarebit-settings-ui.mjs

@@ -197,6 +197,7 @@ export const RAREBIT_SETTINGS_FIELDS = Object.freeze([
   field("recap_timezone", "Recap", "Recap timezone", ["recap", "timezone"], "timezone", `Timestamp zone. Blank uses the host timezone (${HOST_TIMEZONE}).`, { defaultValue: HOST_TIMEZONE }),
   field("auto_title", "Session", "Automatic Session title", ["auto_title"], "boolean", "Generate a Rarebit title from the first persisted owner message.", { defaultValue: true }),
   field("model", "Session", "Rarebit model", ["model"], "string", "Model in provider/model form. Blank removes the local override.", { defaultValue: "Not set" }),
+  field("btw_model", "Session", "BTW model", ["btw", "model"], "string", "Model for /rarebit btw in provider/model form; add :<thinking> to set thinking. Blank uses the parent Session model.", { defaultValue: "Parent model" }),
 ]);
 
 const paletteItems = [
@@ -207,6 +208,8 @@ const paletteItems = [
   { id: "summarize", tab: "Actions", label: "Summarize", description: "Force a Rarebit Summary materialization." },
   { id: "recall", tab: "Actions", label: "Recall", description: "Recall active-branch Rarebit messages with a prompt." },
   { id: "fork", tab: "Actions", label: "Fork", description: "Open a bounded Rarebit fork without a model turn." },
+  { id: "btw", tab: "Actions", label: "BTW", description: "Ask side questions in a temporary Pi beside this one." },
+  { id: "btw_rarebits", tab: "Actions", label: "BTW (Rarebits)", description: "BTW with Rarebit messages only." },
   { id: "summary_status", tab: "Summary", label: "Summary status", description: "Show effective Summary policy." },
   { id: "summary_settings", tab: "Summary", label: "Summary settings", description: "Edit Summary diagnostics and input policy." },
   { id: "recap", tab: "Recap", label: "Recap", description: "Show the current Recap in the TUI." },
@@ -475,6 +478,8 @@ export function rarebitPaletteCommand(selection) {
     case "recall": return "recall";
     case "title": return "title";
     case "fork": return "fork";
+    case "btw": return "btw";
+    case "btw_rarebits": return "btw --rarebits";
     case "help": return "help";
     default: return undefined;
   }

package/src/rarebit-settings.mjs

@@ -72,8 +72,8 @@ export function mergeRarebitSettings(
   return merged;
 }
 
-export function modelFromRarebitSettings(rarebit) {
-  const candidate = rarebit?.model;
+export function modelFromRarebitSettings(rarebit, { key = "model" } = {}) {
+  const candidate = key.split(".").reduce((value, part) => value?.[part], rarebit);
   if (isRecord(candidate)) {
     const provider = nonEmptyString(candidate.provider);
     const id = nonEmptyString(candidate.id);
@@ -91,10 +91,10 @@ export function modelFromRarebitSettings(rarebit) {
       };
   }
   if (candidate === undefined)
-    return { error: "Rarebit setting rarebit.model is missing" };
+    return { error: `Rarebit setting rarebit.${key} is missing` };
   return {
     error:
-      "Rarebit setting rarebit.model must be provider/model or {provider,id}",
+      `Rarebit setting rarebit.${key} must be provider/model or {provider,id}`,
   };
 }
 
@@ -110,6 +110,10 @@ export function resolveRarebitSettings(
 ) {
   const rarebit = mergeRarebitSettings(globalSettings, projectSettings);
   const resolved = modelFromRarebitSettings(rarebit);
+  // An omitted BTW model means "use the parent Session model".
+  const btw = rarebit?.btw?.model === undefined
+    ? {}
+    : modelFromRarebitSettings(rarebit, { key: "btw.model" });
   const recap =
     isRecord(rarebit?.recap)
       ? rarebit.recap
@@ -134,6 +138,8 @@ export function resolveRarebitSettings(
   return {
     ...(resolved.model ? { model: resolved.model } : {}),
     ...(resolved.error ? { modelConfigurationError: resolved.error } : {}),
+    ...(btw.model ? { btwModel: btw.model } : {}),
+    ...(btw.error ? { btwModelConfigurationError: btw.error } : {}),
     summaryPolicy: {
       ...DEFAULT_RAREBIT_SUMMARY_POLICY,
       ...(rarebit.min_total_length === undefined

package/test/rarebit-btw.test.mjs

@@ -0,0 +1,158 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+  RAREBIT_BTW_PANE_LABEL,
+  completedBranchPrefix,
+  openRarebitBtwPane,
+  prepareRarebitBtw,
+  watchRarebitBtwPane,
+} from "../src/rarebit-btw.mjs";
+import { getRarebitArgumentCompletions, parseRarebitCommand } from "../src/rarebit-command.mjs";
+import { resolveRarebitSettings } from "../src/rarebit-settings.mjs";
+
+const user = (id, parentId, text) => ({
+  type: "message", id, parentId, timestamp: "2026-10-07T00:00:00.000Z",
+  message: { role: "user", content: text, timestamp: 0 },
+});
+const assistant = (id, parentId, content, stopReason = "stop") => ({
+  type: "message", id, parentId, timestamp: "2026-10-07T00:00:01.000Z",
+  message: { role: "assistant", content, stopReason, timestamp: 0 },
+});
+const toolResult = (id, parentId, toolCallId) => ({
+  type: "message", id, parentId, timestamp: "2026-10-07T00:00:02.000Z",
+  message: { role: "toolResult", toolCallId, toolName: "read", content: [], timestamp: 0 },
+});
+
+const settledBranch = [
+  user("u1", null, "synthetic request alpha"),
+  assistant("a1", "u1", [{ type: "toolCall", id: "c1", name: "read", arguments: {} }], "toolUse"),
+  toolResult("t1", "a1", "c1"),
+  assistant("a2", "t1", [{ type: "text", text: "synthetic reply alpha" }]),
+];
+
+function contextFor(branch, sessionFile = "/synthetic/source.jsonl") {
+  return {
+    cwd: "/synthetic/cwd",
+    model: { provider: "synthetic", id: "model", contextWindow: 100_000 },
+    sessionManager: {
+      getSessionFile: () => sessionFile,
+      getBranch: () => branch,
+      getHeader: () => ({ type: "session", version: 3, id: "source-id", cwd: "/synthetic/cwd" }),
+    },
+  };
+}
+
+test("btw parses leading flags in any order before the question", () => {
+  const parsed = (input) => {
+    const { flags, arguments: rest } = parseRarebitCommand(input);
+    return { flags, rest };
+  };
+  assert.deepEqual(parsed("btw"), { flags: [], rest: [] });
+  assert.deepEqual(parsed("btw why X?"), { flags: [], rest: ["why X?"] });
+  assert.deepEqual(parsed("btw --rarebits"), { flags: ["--rarebits"], rest: [] });
+  assert.deepEqual(parsed("btw --readonly --rarebits why --rarebits?"), { flags: ["--readonly", "--rarebits"], rest: ["why --rarebits?"] });
+});
+
+test("btw autocompletes unused flags until the question starts", () => {
+  const values = (prefix) => getRarebitArgumentCompletions(prefix)?.map(({ value }) => value) ?? null;
+  assert.deepEqual(values("btw "), ["btw --rarebits ", "btw --readonly "]);
+  assert.deepEqual(values("btw --ra"), ["btw --rarebits "]);
+  assert.deepEqual(values("btw --rarebits "), ["btw --rarebits --readonly "]);
+  assert.equal(values("btw --rarebits --readonly "), null);
+  assert.equal(values("btw why "), null);
+});
+
+test("rarebit.btw.model is optional and validated like rarebit.model", () => {
+  assert.equal(resolveRarebitSettings({ rarebit: { model: "a/b" } }).btwModel, undefined);
+  assert.deepEqual(resolveRarebitSettings({ rarebit: { btw: { model: "p/m:low" } } }).btwModel, { provider: "p", id: "m:low" });
+  assert.match(resolveRarebitSettings({ rarebit: { btw: { model: "bad" } } }).btwModelConfigurationError, /rarebit\.btw\.model/);
+});
+
+test("a mid-turn snapshot drops the assistant message with unresolved tool calls", () => {
+  const pending = assistant("a3", "a2", [{ type: "toolCall", id: "c2", name: "read", arguments: {} }], "toolUse");
+  assert.deepEqual(completedBranchPrefix([...settledBranch, pending]).map((e) => e.id), ["u1", "a1", "t1", "a2"]);
+  assert.equal(completedBranchPrefix(settledBranch), settledBranch);
+});
+
+test("full BTW writes the active branch under a new Session and a self-deleting launcher", async (t) => {
+  const tempRoot = await mkdtemp(join(tmpdir(), "rarebit-btw-test-"));
+  t.after(() => rm(tempRoot, { recursive: true, force: true }));
+  const btw = await prepareRarebitBtw(contextFor(settledBranch), {
+    question: "what was alpha?", tempRoot, thinking: "low", activeTools: ["read", "bash", "team_sync"],
+  });
+  const lines = (await readFile(btw.sessionFile, "utf8")).trim().split("\n").map((line) => JSON.parse(line));
+  assert.equal(lines[0].type, "session");
+  assert.notEqual(lines[0].id, "source-id");
+  assert.equal(lines[0].parentSession, "/synthetic/source.jsonl");
+  assert.deepEqual(lines.slice(1).map((e) => e.id), ["u1", "a1", "t1", "a2"]);
+  assert.equal((await stat(btw.directory)).mode & 0o777, 0o700);
+  const launcher = await readFile(btw.launcherPath, "utf8");
+  assert.match(launcher, /trap .*rm -rf .*hc-rarebit-btw-.* EXIT/);
+  for (const flag of ["--tools' 'read,bash,team_sync", "--model' 'synthetic/model", "--thinking' 'low", "'--' 'what was alpha?'"])
+    assert.ok(launcher.includes(flag), flag);
+  assert.ok(!launcher.includes("--no-extensions"));
+  await btw.discard();
+});
+
+test("read-only BTW drops extensions and limits tools; a configured model drops parent thinking", async (t) => {
+  const tempRoot = await mkdtemp(join(tmpdir(), "rarebit-btw-test-"));
+  t.after(() => rm(tempRoot, { recursive: true, force: true }));
+  const btw = await prepareRarebitBtw(contextFor(settledBranch), {
+    tempRoot, readonly: true, thinking: "high", activeTools: ["bash"], model: { provider: "p", id: "m:low" },
+  });
+  const launcher = await readFile(btw.launcherPath, "utf8");
+  for (const flag of ["--tools' 'read,grep,find,ls", "--no-extensions", "--no-mcp", "--model' 'p/m:low", "Do not modify files"])
+    assert.ok(launcher.includes(flag), flag);
+  assert.ok(!launcher.includes("--thinking"));
+  assert.ok(!launcher.includes("bash"));
+});
+
+test("Rarebits BTW keeps only user requests and final replies", async (t) => {
+  const tempRoot = await mkdtemp(join(tmpdir(), "rarebit-btw-test-"));
+  t.after(() => rm(tempRoot, { recursive: true, force: true }));
+  const btw = await prepareRarebitBtw(contextFor(settledBranch), { mode: "rarebits", tempRoot });
+  const texts = (await readFile(btw.sessionFile, "utf8")).trim().split("\n").map((line) => JSON.parse(line))
+    .filter((entry) => entry.type === "message" && entry.rarebitFork?.kind === "import")
+    .map((entry) => entry.message.role);
+  assert.deepEqual(texts, ["user", "assistant"]);
+  assert.doesNotMatch(await readFile(btw.launcherPath, "utf8"), /' '--' '/);
+});
+
+test("the pane opener replaces another BTW pane in the same tab only, never its own", async () => {
+  const calls = [];
+  const replies = {
+    "pane get": { result: { pane: { tab_id: "tab-1" } } },
+    "pane list": { result: { panes: [
+      { pane_id: "old", tab_id: "tab-1", label: RAREBIT_BTW_PANE_LABEL },
+      { pane_id: "other-tab", tab_id: "tab-2", label: RAREBIT_BTW_PANE_LABEL },
+      { pane_id: "main", tab_id: "tab-1", label: RAREBIT_BTW_PANE_LABEL },
+    ] } },
+    "pane split": { result: { pane: { pane_id: "new" } } },
+  };
+  const run = async (_bin, args) => {
+    calls.push(args.join(" "));
+    return { stdout: JSON.stringify(replies[args.slice(0, 2).join(" ")] ?? {}) };
+  };
+  const opened = await openRarebitBtwPane({ launcherPath: "/tmp/x/launch.sh", cwd: "/w", paneId: "main", run });
+  assert.equal(opened.paneId, "new");
+  assert.deepEqual(calls.filter((c) => c.startsWith("pane close")), ["pane close old"]);
+  assert.ok(calls.includes(`pane rename new ${RAREBIT_BTW_PANE_LABEL}`));
+  assert.ok(calls.includes("pane run new exec sh '/tmp/x/launch.sh'"));
+});
+
+test("the cleanup watcher is detached and removes the snapshot after the pane is gone", () => {
+  let spawned;
+  watchRarebitBtwPane({
+    paneId: "w1:p1", directory: "/tmp/hc-rarebit-btw-x", herdrBin: "herdr",
+    spawnImpl: (command, args, options) => {
+      spawned = { command, args, options };
+      return { unref() {} };
+    },
+  });
+  assert.equal(spawned.options.detached, true);
+  assert.match(spawned.args[1], /while \[ -d '\/tmp\/hc-rarebit-btw-x' \] && 'herdr' pane get 'w1:p1'.*done; rm -rf '\/tmp\/hc-rarebit-btw-x'/);
+});

package/test/rarebit-command.test.mjs

@@ -14,11 +14,11 @@ const values = (prefix) =>
 test("one grammar derives command description and usage", () => {
   assert.equal(
     rarebitCommandDescription(),
-    "Rarebit menu/settings/view/help/status/recall/fork/config/auto-title/title/recap/got-it/summarize",
+    "Rarebit menu/settings/view/help/status/recall/btw/fork/config/auto-title/title/recap/got-it/summarize",
   );
   assert.equal(
     rarebitCommandUsage(),
-    "Usage: /rarebit [menu|settings|view|help|status|recall|fork|config|auto-title|title|recap|got-it|summarize]",
+    "Usage: /rarebit [menu|settings|view|help|status|recall|btw|fork|config|auto-title|title|recap|got-it|summarize]",
   );
   assert.equal(
     rarebitCommandUsage("config"),
@@ -105,6 +105,7 @@ test("autocomplete covers subcommands and discrete nested arguments", () => {
     "help",
     "status",
     "recall",
+    "btw",
     "fork",
     "config",
     "auto-title",

package/test/rarebit-recall.test.mjs

@@ -140,27 +140,52 @@ test("recall materialization writes private detailed evidence and a chronologica
       await readFile(result.conversationPath, "utf8"),
     );
     assert.deepEqual(conversation, {
-      schemaVersion: 1,
+      schemaVersion: 2,
       type: "rarebit_conversation",
-      timeZone: "UTC",
-      hours: [
+      messageCount: 3,
+      lastRound: 1,
+      messages: [
         {
-          hour: "2026-07-24T01:00Z",
-          messages: [{ role: "user", content: "Exact owner evidence." }],
+          seq: 1,
+          round: 1,
+          role: "user",
+          kind: "request",
+          time: "2026-07-24T01:02:03Z",
+          text: "Exact owner evidence.",
         },
         {
-          hour: "2026-07-24T02:00Z",
-          messages: [
-            { role: "agent", content: "Exact continuation evidence." },
-            { role: "agent", content: "Exact stop evidence." },
-          ],
+          seq: 2,
+          round: 1,
+          role: "agent",
+          kind: "progress",
+          time: "2026-07-24T02:00:00Z",
+          text: "Exact continuation evidence.",
+        },
+        {
+          seq: 3,
+          round: 1,
+          role: "agent",
+          kind: "reply",
+          time: "2026-07-24T02:45:00Z",
+          text: "Exact stop evidence.",
         },
       ],
     });
+    assert.deepEqual(
+      detailed.selection.occurrences.map(({ seq, sourceEntryId }) => ({
+        seq,
+        sourceEntryId,
+      })),
+      [
+        { seq: 1, sourceEntryId: "owner" },
+        { seq: 2, sourceEntryId: "continue" },
+        { seq: 3, sourceEntryId: "stop" },
+      ],
+    );
     const conversationText = await readFile(result.conversationPath, "utf8");
     assert.doesNotMatch(
       conversationText,
-      /sourceEntryId|occurrenceId|manifestHash|contentHash|timestamp|session/i,
+      /sourceEntryId|occurrenceId|manifestHash|contentHash|session/i,
     );
   } finally {
     await result.discard();
@@ -168,7 +193,7 @@ test("recall materialization writes private detailed evidence and a chronologica
   }
 });
 
-test("conversation buckets sort chronologically and treat producer-tagged input as a normal user message", async () => {
+test("conversation keeps branch order, numbers rounds, and treats producer-tagged input as a normal user message", async () => {
   const root = await fixtureRoot("bucket-order");
   const sessionFile = join(root, "session.jsonl");
   await writeFile(sessionFile, "{}\n");
@@ -218,23 +243,23 @@ test("conversation buckets sort chronologically and treat producer-tagged input
     const conversation = JSON.parse(
       await readFile(result.conversationPath, "utf8"),
     );
-    assert.deepEqual(conversation.hours, [
-      {
-        hour: "2026-07-24T01:00Z",
-        messages: [{ role: "agent", content: "Earlier agent evidence." }],
-      },
-      {
-        hour: "2026-07-24T02:00Z",
-        messages: [
-          { role: "user", content: "Unknown-origin user evidence." },
-          { role: "agent", content: "Later agent evidence." },
-        ],
-      },
-      {
-        hour: null,
-        messages: [{ role: "agent", content: "Unknown-time agent evidence." }],
-      },
-    ]);
+    assert.equal(conversation.lastRound, 1);
+    assert.deepEqual(
+      conversation.messages.map(({ seq, round, role, kind, time, text }) => [
+        seq,
+        round,
+        role,
+        kind,
+        time,
+        text,
+      ]),
+      [
+        [1, 1, "user", "request", "2026-07-24T02:10:00Z", "Unknown-origin user evidence."],
+        [2, 1, "agent", "reply", "2026-07-24T01:10:00Z", "Earlier agent evidence."],
+        [3, 1, "agent", "reply", null, "Unknown-time agent evidence."],
+        [4, 1, "agent", "reply", "2026-07-24T02:20:00Z", "Later agent evidence."],
+      ],
+    );
     assert.doesNotMatch(
       await readFile(result.conversationPath, "utf8"),
       /human|producer|rpc/,
@@ -318,29 +343,47 @@ test("recall sends one exact fenced Markdown steer message in idle and busy cont
     "\n# Heading-looking request\n- list-looking item\n```text\ninside backticks\n```\n~~~~\ninside tildes\n~~~~\nTrailing request\n";
   const expectedMessage = `# Rarebit Recall
 
-*Use these local private evidence files to recover historical context for this turn.*
-
-## How to use this bundle
+*Answer the **Current request** below. Use these local private files to recover earlier context from this Session.*
 
-1. Treat **Current request** below as the exact current user request.
-2. Read **Conversation** first for meaning.
-3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
-4. Answer the current request using this evidence.
+## Files
 
-## Local private evidence files
-
-**Conversation** — \`rarebit_conversation/v1\`
+**Conversation** — \`rarebit_conversation/v2\`. Read this first.
 
 \`\`\`text
 ${recall.conversationPath}
 \`\`\`
 
-**Detailed evidence** — \`rarebit_message_recall/v1\`
+**Detailed evidence** — \`rarebit_message_recall/v1\`. Use it only for source, Session, branch, or lineage facts. Join on \`seq\`.
 
 ~~~~text
 ${recall.detailedPath}
 ~~~~
 
+## Conversation schema
+
+\`\`\`text
+{ messageCount, lastRound, messages: [{ seq, round, role, kind, time, text }] }
+seq    1-based, oldest first
+round  increments at each user message; agent messages before the first user message have round 0
+role   "user" | "agent"
+kind   "request" (user) | "progress" (agent text before a tool call) | "reply" (agent final answer)
+time   UTC "YYYY-MM-DDTHH:MM:SSZ", or null
+\`\`\`
+
+Messages contain user and agent text only. Tool calls and tool results are excluded.
+
+## Example queries
+
+Set \`F\` to the Conversation path. Read the smallest slice that answers the request.
+
+\`\`\`sh
+jq '.messages[-20:]' "$F"                                              # last 20 messages
+jq '[.messages[] | select(.role == "user")][-3:]' "$F"                 # last 3 user messages
+jq '[.messages[] | select(.kind == "reply")][-10:]' "$F"               # last 10 agent replies
+jq '.lastRound as $r | [.messages[] | select(.round > $r - 5)]' "$F"  # last 5 rounds
+jq '(now - 8*3600 | todate) as $t | [.messages[] | select(.time >= $t)]' "$F"  # last 8 hours
+\`\`\`
+
 ## Current request
 
 \`\`\`\`text
@@ -390,7 +433,7 @@ test("long delimiter runs ending at value boundaries use the shortest safe fence
   assert.equal(harness.sent.length, 1);
   const message = harness.sent[0].args[0];
   const conversationBlock = message.match(
-    /\*\*Conversation\*\* — `rarebit_conversation\/v1`\n\n([`~]+)text\n([^\n]*)\n\1\n\n\*\*Detailed evidence\*\*/,
+    /\*\*Conversation\*\* — `rarebit_conversation\/v2`\. Read this first\.\n\n([`~]+)text\n([^\n]*)\n\1\n\n\*\*Detailed evidence\*\*/,
   );
   assert.ok(conversationBlock);
   assert.equal(conversationBlock[2], conversationPath);