@hypercarrier/rarebit 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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

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.4.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/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),
   };
 }
@@ -755,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-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",