@hypercarrier/rarebit 0.1.0-alpha.5 → 0.2.0

package/src/rarebit-fork.mjs

@@ -0,0 +1,241 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { selectRarebits, sha256 } from "./rarebit-core.mjs";
+import {
+  RAREBIT_FORK_ENTRY_MARKER_VERSION,
+  RAREBIT_FORK_LINEAGE_CUSTOM_TYPE,
+  RAREBIT_FORK_LINEAGE_SCHEMA_VERSION,
+  RAREBIT_FORK_OPENING_MARKER,
+  getRarebitForkSeedEntryIds,
+} from "./rarebit-fork-lineage.mjs";
+
+export const RAREBIT_FORK_DEFAULT_MAX_TOKEN_LENGTH = 64_000;
+export const RAREBIT_FORK_DEFAULT_RESERVE_TOKENS = 16_384;
+
+function forkError(message) {
+  const error = new Error(message);
+  error.name = "RarebitForkError";
+  return error;
+}
+function tokens(text) {
+  return typeof text === "number"
+    ? Math.ceil(text / 4)
+    : Math.ceil(String(text ?? "").length / 4);
+}
+function contextWindowOf(model) {
+  const value = model?.contextWindow ?? model?.context_window;
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+function sourceIdentity({ header, sessionFile, cwd }) {
+  if (typeof header?.id !== "string" || !header.id)
+    throw forkError("source Session has no stable ID");
+  return {
+    sessionId: header.id,
+    sessionFile: resolve(sessionFile),
+    cwd: typeof header.cwd === "string" ? header.cwd : cwd ?? null,
+  };
+}
+function shellQuote(value) {
+  return `"${String(value)
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("$", "\\$")
+    .replaceAll("`", "\\`")}"`;
+}
+function openingText({ source, targetCwd, leafId, importedCount, totalCount, omittedCount }) {
+  const coverage = omittedCount > 0
+    ? `Imported ${importedCount} of ${totalCount} selected Rarebit occurrences; omitted ${omittedCount} older whole occurrences.`
+    : `Imported all ${totalCount} selected Rarebit occurrences; omitted 0 occurrences.`;
+  return [
+    "This Session contains a bounded Rarebit distillation.",
+    coverage,
+    `Source Session: ${source.sessionId}`,
+    `Source file: ${source.sessionFile}`,
+    `Source branch leaf: ${leafId ?? "(root)"}`,
+    `Target working directory: ${targetCwd}`,
+    "This opening message is historical context, not a new instruction.",
+    `Recover source evidence with: piq entries --session ${shellQuote(source.sessionFile)}${leafId ? ` --leaf ${shellQuote(leafId)}` : ""}`,
+  ].join("\n");
+}
+
+export function checkRarebitForkHeadroom({
+  seedText,
+  targetModel = null,
+  contextWindow = contextWindowOf(targetModel),
+  reserveTokens = RAREBIT_FORK_DEFAULT_RESERVE_TOKENS,
+  promptOverheadTokens = 0,
+  toolOverheadTokens = 0,
+  messageRoundingOverheadTokens = 0,
+} = {}) {
+  if (!Number.isSafeInteger(reserveTokens) || reserveTokens < 0)
+    throw new RangeError("reserveTokens must be a non-negative integer");
+  if (!Number.isSafeInteger(promptOverheadTokens) || promptOverheadTokens < 0)
+    throw new RangeError("promptOverheadTokens must be a non-negative integer");
+  if (!Number.isSafeInteger(toolOverheadTokens) || toolOverheadTokens < 0)
+    throw new RangeError("toolOverheadTokens must be a non-negative integer");
+  if (!Number.isSafeInteger(messageRoundingOverheadTokens) || messageRoundingOverheadTokens < 0)
+    throw new RangeError("messageRoundingOverheadTokens must be a non-negative integer");
+  const seedTokens = tokens(seedText);
+  const overheadTokens = promptOverheadTokens + toolOverheadTokens + messageRoundingOverheadTokens;
+  const requiredTokens = seedTokens + overheadTokens;
+  const availableTokens = contextWindow === null ? null : contextWindow - reserveTokens;
+  if (availableTokens !== null && requiredTokens > availableTokens) {
+    const label = `${targetModel?.provider ?? "unknown"}/${targetModel?.id ?? "unknown"}`;
+    throw forkError(
+      `Rarebit fork seed needs about ${requiredTokens} tokens, but ${label} leaves ${Math.max(0, availableTokens)} tokens after the native reserve of ${reserveTokens}; increase the target model context window or lower --max-token-length before switching`,
+    );
+  }
+  return { seedTokens, overheadTokens, requiredTokens, contextWindow, reserveTokens, availableTokens,
+    basis: "native_contextWindow_minus_reserveTokens_plus_prompt_and_tool_overhead" };
+}
+
+function previousMappings(branch) {
+  const map = new Map();
+  for (const entry of branch) {
+    if (entry?.rarebitFork?.kind === "import" && Array.isArray(entry.rarebitFork.ancestry)) {
+      map.set(entry.id, { importedEntryId: entry.id, ancestry: entry.rarebitFork.ancestry });
+    }
+    if (entry?.type !== "custom" || entry.customType !== RAREBIT_FORK_LINEAGE_CUSTOM_TYPE) continue;
+    for (const mapping of entry.data?.mappings ?? []) {
+      if (typeof mapping?.importedEntryId === "string" && !map.has(mapping.importedEntryId)) map.set(mapping.importedEntryId, mapping);
+    }
+  }
+  return map;
+}
+
+export function buildRarebitForkPlan({
+  header, sessionFile, cwd, branch, targetCwd, maxTokenLength = RAREBIT_FORK_DEFAULT_MAX_TOKEN_LENGTH,
+  targetModel, contextWindow, reserveTokens = RAREBIT_FORK_DEFAULT_RESERVE_TOKENS,
+  promptOverheadTokens = 0, toolOverheadTokens = 0, forkCreatedAt = new Date().toISOString(),
+} = {}) {
+  if (!Number.isSafeInteger(maxTokenLength) || maxTokenLength < 1)
+    throw new RangeError("maxTokenLength must be a positive integer");
+  if (!Array.isArray(branch)) throw forkError("source active branch is unavailable");
+  const source = sourceIdentity({ header, sessionFile, cwd });
+  const selection = selectRarebits(branch);
+  const seedIds = getRarebitForkSeedEntryIds(branch);
+  const candidates = selection.occurrences.filter((item) => !seedIds.has(item.sourceEntryId));
+  const selected = [];
+  let retainedChars = 0;
+  for (let index = candidates.length - 1; index >= 0; index -= 1) {
+    const item = candidates[index];
+    const candidateChars = retainedChars + item.text.length;
+    if (tokens(candidateChars) > maxTokenLength) {
+      if (selected.length === 0)
+        throw forkError(`The newest Rarebit occurrence needs about ${tokens(item.text)} tokens, which exceeds --max-token-length ${maxTokenLength}; raise the budget or shorten the newest source message before forking`);
+      break;
+    }
+    selected.unshift(item);
+    retainedChars = candidateChars;
+  }
+  const omittedCount = candidates.length - selected.length;
+  const leafId = branch.at(-1)?.id ?? null;
+  const resolvedTargetCwd = resolve(targetCwd ?? cwd ?? process.cwd());
+  const text = openingText({ source, targetCwd: resolvedTargetCwd, leafId, importedCount: selected.length, totalCount: candidates.length, omittedCount });
+  const headroom = checkRarebitForkHeadroom({
+    seedText: `${text}\n${selected.map((item) => item.text).join("\n")}`,
+    targetModel, contextWindow: contextWindow ?? contextWindowOf(targetModel), reserveTokens,
+    promptOverheadTokens, toolOverheadTokens,
+    messageRoundingOverheadTokens: selected.length + 1,
+  });
+  return {
+    schemaVersion: RAREBIT_FORK_LINEAGE_SCHEMA_VERSION, source, targetCwd: resolvedTargetCwd,
+    branchLeafId: leafId, forkCreatedAt, openingText: text, candidates, selected,
+    importedChars: retainedChars,
+    importedTokens: tokens(retainedChars),
+    sourceModels: new Map(selection.occurrences.map((item) => {
+      const sourceEntry = branch.find((entry) => entry?.id === item.sourceEntryId)
+        ?? branch[item.order];
+      const marker = sourceEntry?.rarebitFork;
+      const message = sourceEntry?.message;
+      const originalModel = marker && Object.hasOwn(marker, "originalModel")
+        ? marker.originalModel
+        : (message?.provider && message?.model
+            ? { provider: message.provider, id: message.model }
+            : null);
+      return [item.occurrenceId, originalModel];
+    })),
+    omittedOccurrences: omittedCount, maxTokenLength, headroom,
+    omission: { strategy: "newest_contiguous_suffix_whole_occurrences", totalOccurrenceCount: candidates.length,
+      importedOccurrenceCount: selected.length, omittedOccurrenceCount: omittedCount,
+      importedTokens: tokens(retainedChars), maxTokenLength },
+    priorMappings: previousMappings(branch), selectionManifestHash: selection.manifestHash, targetModel,
+  };
+}
+
+function randomEntryId(used) {
+  let id;
+  do id = randomUUID().replaceAll("-", "").slice(0, 8); while (used.has(id));
+  used.add(id); return id;
+}
+function sourceLocation(plan, occurrence) {
+  return { sessionId: plan.source.sessionId, entryId: occurrence.sourceEntryId,
+    sourceOrder: occurrence.order,
+    ...(typeof occurrence.timestamp === "string" ? { timestamp: occurrence.timestamp } : {}) };
+}
+function zeroUsage() {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+}
+function importedMessage(item, timestamp) {
+  if (item.role === "user") return { role: "user", content: item.text, timestamp: Date.parse(timestamp) };
+  return { role: "assistant", content: [{ type: "text", text: item.text }],
+    api: "rarebit-import", provider: "rarebit-import", model: "rarebit-import", usage: zeroUsage(),
+    stopReason: item.outcome === "continuation" ? "toolUse" : "stop", timestamp: Date.parse(timestamp) };
+}
+function marker(plan, item, ancestry, kind = "import") {
+  return { version: RAREBIT_FORK_ENTRY_MARKER_VERSION, kind,
+    ...(kind === "seed" ? { opening: RAREBIT_FORK_OPENING_MARKER } : {
+      sourceSessionId: plan.source.sessionId, sourceEntryId: item.sourceEntryId, occurrenceId: item.occurrenceId,
+      outcome: item.outcome, role: item.role, originalTimestamp: item.timestamp,
+      originalModel: plan.sourceModels.get(item.occurrenceId) ?? null, ancestry,
+    }) };
+}
+
+export function createRarebitForkEntries(plan, { sessionId = randomUUID() } = {}) {
+  const used = new Set(); const timestamp = plan.forkCreatedAt; const entries = [];
+  let parentId = null;
+  const seedEntryId = randomEntryId(used);
+  entries.push({ type: "message", id: seedEntryId, parentId, timestamp,
+    rarebitFork: marker(plan, null, [], "seed"), message: { role: "user", content: plan.openingText, timestamp: Date.parse(timestamp) } });
+  parentId = seedEntryId;
+  const importedEntryIds = []; const mappings = [];
+  for (const item of plan.selected) {
+    const id = randomEntryId(used); const prior = plan.priorMappings.get(item.sourceEntryId);
+    const ancestry = [...(prior?.ancestry ?? []), sourceLocation(plan, item)];
+    entries.push({ type: "message", id, parentId, timestamp, rarebitFork: marker(plan, item, ancestry), message: importedMessage(item, timestamp) });
+    importedEntryIds.push(id);
+    mappings.push({ importedEntryId: id, sourceEntryId: item.sourceEntryId, sourceOccurrenceId: item.occurrenceId,
+      role: item.role, outcome: item.outcome, originalTimestamp: item.timestamp,
+      originalModel: plan.sourceModels.get(item.occurrenceId) ?? null, ancestry });
+    parentId = id;
+  }
+  const manifest = { schemaVersion: RAREBIT_FORK_LINEAGE_SCHEMA_VERSION, type: "rarebit_fork_lineage",
+    source: plan.source, targetCwd: plan.targetCwd, sourceLeafEntryId: plan.branchLeafId, forkCreatedAt: timestamp,
+    opening: { marker: RAREBIT_FORK_OPENING_MARKER, seedEntryId, textHash: sha256(plan.openingText) }, omission: plan.omission,
+    selectionManifestHash: plan.selectionManifestHash, importedEntryIds, mappings };
+  entries.push({ type: "custom", id: randomEntryId(used), parentId, timestamp, customType: RAREBIT_FORK_LINEAGE_CUSTOM_TYPE, data: manifest });
+  if (plan.targetModel?.provider && plan.targetModel?.id) {
+    entries.push({ type: "model_change", id: randomEntryId(used), parentId: entries.at(-1).id, timestamp,
+      provider: plan.targetModel.provider, modelId: plan.targetModel.id });
+  }
+  return { sessionId, header: { type: "session", version: 3, id: sessionId, timestamp, cwd: plan.targetCwd, parentSession: plan.source.sessionFile }, entries, manifest };
+}
+
+export async function writeRarebitForkFile(path, session, { writeFileImpl = writeFile, renameImpl = rename, removeImpl = rm } = {}) {
+  const target = resolve(path); await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = join(dirname(target), `.${target.split("/").at(-1)}.${randomUUID()}.tmp`);
+  try {
+    await writeFileImpl(temporary, `${[session.header, ...session.entries].map(JSON.stringify).join("\n")}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await renameImpl(temporary, target); return target;
+  } catch (error) { await removeImpl(temporary, { force: true }).catch(() => {}); throw error; }
+}
+export function sessionFilenameFor({ sessionDir, forkCreatedAt, sessionId }) {
+  return join(resolve(sessionDir), `${new Date(forkCreatedAt).toISOString().replace(/[:.]/g, "-")}_${sessionId}.jsonl`);
+}
+export function forkPlanSummary(plan) {
+  return { maxTokenLength: plan.maxTokenLength, importedTokens: plan.importedTokens, importedOccurrenceCount: plan.selected.length,
+    omittedOccurrenceCount: plan.omittedOccurrences, sourceSessionId: plan.source.sessionId, sourceLeafEntryId: plan.branchLeafId,
+    targetCwd: plan.targetCwd, headroom: plan.headroom };
+}

package/src/rarebit-recap.mjs

@@ -0,0 +1,422 @@
+import { exactSelectionApplies } from "./rarebit-artifact-state.mjs";
+import { selectRarebits } from "./rarebit-core.mjs";
+import {
+  DEFAULT_RAREBIT_RECAP_DELAY_MS,
+  DEFAULT_RAREBIT_RECAP_TIMEZONE,
+  normalizeRarebitRecapTimezone,
+} from "./rarebit-settings.mjs";
+import { readRarebitCurrent } from "./rarebit-store.mjs";
+import { rarebitSummaryPresentation } from "./rarebit-visual-language.mjs";
+
+export const RAREBIT_RECAP_WIDGET_KEY = "rarebit-recap";
+export {
+  DEFAULT_RAREBIT_RECAP_DELAY_MS,
+  DEFAULT_RAREBIT_RECAP_TIMEZONE,
+} from "./rarebit-settings.mjs";
+
+function sessionIdentity(ctx) {
+  return {
+    sessionId: String(
+      ctx?.sessionManager?.getHeader?.()?.id ?? ctx?.sessionId ?? "",
+    ),
+    sessionFile: ctx?.sessionManager?.getSessionFile?.() ?? null,
+  };
+}
+
+function branchSnapshot(ctx) {
+  const branch = ctx?.sessionManager?.getBranch?.();
+  return Array.isArray(branch) ? branch.slice() : [];
+}
+
+function receiptAppliesToContext(receipt, ctx) {
+  if (receipt?.status !== "ok") return false;
+  const identity = sessionIdentity(ctx);
+  if (!identity.sessionId || !identity.sessionFile) return false;
+  if (receipt.sessionId !== identity.sessionId) return false;
+  const branch = branchSnapshot(ctx);
+  return exactSelectionApplies(receipt.selection, selectRarebits(branch));
+}
+
+function observedAtLabel(observedAt, timezone) {
+  const date = new Date(observedAt);
+  if (Number.isNaN(date.valueOf())) return String(observedAt ?? "unknown");
+  const usesHostTimezone = timezone === DEFAULT_RAREBIT_RECAP_TIMEZONE;
+  const dateOptions = {
+    dateStyle: "medium",
+    timeStyle: "short",
+    ...(usesHostTimezone ? {} : { timeZone: timezone }),
+  };
+  let dateText;
+  try {
+    dateText = new Intl.DateTimeFormat(undefined, dateOptions).format(date);
+  } catch {
+    dateText = new Intl.DateTimeFormat(undefined, {
+      dateStyle: "medium",
+      timeStyle: "short",
+    }).format(date);
+  }
+
+  let zoneText;
+  try {
+    const zoneOptions = {
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      timeZoneName: "shortOffset",
+      ...(usesHostTimezone ? {} : { timeZone: timezone }),
+    };
+    zoneText = new Intl.DateTimeFormat(undefined, zoneOptions)
+      .formatToParts(date)
+      .find((part) => part.type === "timeZoneName")?.value;
+  } catch {
+    zoneText = undefined;
+  }
+  let resolvedTimezone;
+  try {
+    resolvedTimezone = new Intl.DateTimeFormat(
+      undefined,
+      usesHostTimezone ? {} : { timeZone: timezone },
+    ).resolvedOptions().timeZone;
+  } catch {
+    resolvedTimezone = undefined;
+  }
+  const zoneLabel = usesHostTimezone
+    ? `host${resolvedTimezone ? `: ${resolvedTimezone}` : ""}`
+    : resolvedTimezone ?? timezone;
+  return `${dateText} (${zoneLabel}${zoneText ? `, ${zoneText}` : ""})`;
+}
+
+let recapWidgetComponents;
+
+async function loadRecapWidgetComponents() {
+  if (!recapWidgetComponents) {
+    recapWidgetComponents = Promise.all([
+      import("@earendil-works/pi-tui"),
+      import("@earendil-works/pi-coding-agent"),
+    ]).then(([tui, agent]) => ({
+      Container: tui.Container,
+      Text: tui.Text,
+      DynamicBorder: agent.DynamicBorder,
+    }));
+  }
+  return recapWidgetComponents;
+}
+
+function summaryContent(
+  receipt,
+  { timezone = DEFAULT_RAREBIT_RECAP_TIMEZONE } = {},
+) {
+  const presentation = rarebitSummaryPresentation(receipt.sessionStatus);
+  const mark = presentation.mark ? `${presentation.mark} ` : "";
+  const heading = `${mark}Recap · ${presentation.label} · as of ${observedAtLabel(receipt.observedAt, timezone)}`;
+  const summary = String(receipt.summary ?? "").trim();
+  return { heading, summary };
+}
+
+function currentContextOptions(ctx, options) {
+  return {
+    sessionFile: sessionIdentity(ctx).sessionFile,
+    ...(options?.sessionRoot ? { sessionRoot: options.sessionRoot } : {}),
+    ...(options?.rarebitRoot ? { rarebitRoot: options.rarebitRoot } : {}),
+    ...(options?.allowExternalSession === true
+      ? { allowExternalSession: true }
+      : {}),
+  };
+}
+
+function sameIdentity(left, right) {
+  return (
+    left?.sessionId === right?.sessionId &&
+    left?.sessionFile === right?.sessionFile
+  );
+}
+
+/**
+ * Private Pi-only presentation controller. It consumes existing receipts and
+ * writes only to the interactive TUI widget surface. It never appends to a
+ * Session and never invokes a model.
+ */
+export function createRarebitRecapController({
+  delayMs = DEFAULT_RAREBIT_RECAP_DELAY_MS,
+  timezone = DEFAULT_RAREBIT_RECAP_TIMEZONE,
+  readCurrent = readRarebitCurrent,
+  setTimeoutFn = setTimeout,
+  clearTimeoutFn = clearTimeout,
+} = {}) {
+  if (!Number.isSafeInteger(delayMs) || delayMs < 0)
+    throw new RangeError("Rarebit recap delay must be a nonnegative integer");
+  const recapTimezone = normalizeRarebitRecapTimezone(timezone);
+
+  let liveContext;
+  let liveLifecycleGeneration = 0;
+  let controllerGeneration = 0;
+  let timer;
+  let pending;
+  let offerEpoch = 0;
+  const displayedReceipts = new Set();
+
+  const tuiContext = (ctx = liveContext) =>
+    ctx?.mode === "tui" && typeof ctx?.ui?.setWidget === "function"
+      ? ctx
+      : null;
+
+  const clearWidget = (ctx = liveContext) => {
+    const target = tuiContext(ctx);
+    if (!target) return;
+    try {
+      target.ui.setWidget(RAREBIT_RECAP_WIDGET_KEY, undefined, {
+        placement: "aboveEditor",
+      });
+    } catch {
+      // TUI rendering is best-effort and must not affect Summary materialization.
+    }
+  };
+
+  const cancelTimer = () => {
+    if (timer !== undefined) clearTimeoutFn(timer);
+    timer = undefined;
+    pending = undefined;
+    offerEpoch += 1;
+  };
+
+  const updateContext = (ctx, lifecycleGeneration) => {
+    if (ctx) liveContext = ctx;
+    if (Number.isSafeInteger(lifecycleGeneration))
+      liveLifecycleGeneration = lifecycleGeneration;
+  };
+
+  const invalidate = (ctx, lifecycleGeneration) => {
+    const previousContext = liveContext;
+    clearWidget(previousContext);
+    updateContext(ctx, lifecycleGeneration);
+    controllerGeneration += 1;
+    cancelTimer();
+    clearWidget(ctx);
+  };
+
+  const captureMaterialization = (ctx) => {
+    const snapshotGeneration = ctx?.rarebitLifecycleGeneration;
+    if (
+      Number.isSafeInteger(snapshotGeneration) &&
+      snapshotGeneration !== liveLifecycleGeneration
+    )
+      return null;
+    return {
+      controllerGeneration,
+      lifecycleGeneration: Number.isSafeInteger(snapshotGeneration)
+        ? snapshotGeneration
+        : liveLifecycleGeneration,
+    };
+  };
+
+  const tokenIsCurrent = (token) =>
+    Boolean(
+      token &&
+        token.controllerGeneration === controllerGeneration &&
+        token.lifecycleGeneration === liveLifecycleGeneration,
+    );
+
+  const readReceipt = async (ctx, options) => {
+    const identity = sessionIdentity(ctx);
+    if (!identity.sessionFile) return null;
+    const current = await readCurrent({
+      ...currentContextOptions(ctx, options),
+    });
+    const receipt = current?.receipt;
+    if (!receiptAppliesToContext(receipt, ctx)) return null;
+    const artifactState = current?.artifactState;
+    if (
+      !["request_current", "assessment_current"].includes(
+        artifactState?.syncState,
+      ) ||
+      !["request_generation", "exact_selection"].includes(
+        artifactState?.applicability,
+      ) ||
+      artifactState?.receiptRef?.jobId !== receipt.jobId ||
+      artifactState?.projection?.status !== receipt.sessionStatus
+    )
+      return null;
+    return receipt;
+  };
+
+  const display = async (
+    ctx,
+    receipt,
+    { timezone = recapTimezone, token, expectedOfferEpoch } = {},
+  ) => {
+    const target = tuiContext(ctx);
+    if (!target || !receiptAppliesToContext(receipt, ctx)) return false;
+    const observedControllerGeneration = controllerGeneration;
+    const observedLifecycleGeneration = liveLifecycleGeneration;
+    const observedOfferEpoch = expectedOfferEpoch ?? offerEpoch;
+    const observedIdentity = sessionIdentity(ctx);
+    try {
+      const components = await loadRecapWidgetComponents();
+      if (
+        observedControllerGeneration !== controllerGeneration ||
+        observedLifecycleGeneration !== liveLifecycleGeneration ||
+        observedOfferEpoch !== offerEpoch ||
+        (token && !tokenIsCurrent(token)) ||
+        !sameIdentity(observedIdentity, sessionIdentity(liveContext)) ||
+        !receiptAppliesToContext(receipt, liveContext)
+      )
+        return false;
+      const content = summaryContent(receipt, {
+        timezone: normalizeRarebitRecapTimezone(timezone),
+      });
+      target.ui.setWidget(
+        RAREBIT_RECAP_WIDGET_KEY,
+        (_tui, theme) => {
+          const border = (text) => theme.fg("borderMuted", text);
+          const widget = new components.Container();
+          const heading = new components.Text("", 1, 0);
+          const summary = new components.Text("", 1, 0);
+          let previousHeading;
+          let previousSummary;
+          const themed = (text, color, component, previous) => {
+            const rendered = theme.fg(color, text);
+            if (rendered !== previous.value) {
+              previous.value = rendered;
+              component.setText(rendered);
+            }
+          };
+          const themedHeading = {
+            render: (width) => {
+              themed(content.heading, "dim", heading, previousHeading ??= {});
+              return heading.render(width);
+            },
+            invalidate: () => {
+              previousHeading = undefined;
+              heading.invalidate();
+            },
+          };
+          const themedSummary = {
+            render: (width) => {
+              themed(content.summary, "muted", summary, previousSummary ??= {});
+              return summary.render(width);
+            },
+            invalidate: () => {
+              previousSummary = undefined;
+              summary.invalidate();
+            },
+          };
+          widget.addChild(new components.DynamicBorder(border));
+          widget.addChild(themedHeading);
+          widget.addChild(themedSummary);
+          widget.addChild(new components.DynamicBorder(border));
+          return widget;
+        },
+        { placement: "aboveEditor" },
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const showExisting = async (ctx, options = {}) => {
+    controllerGeneration += 1;
+    cancelTimer();
+    updateContext(ctx);
+    const observedGeneration = controllerGeneration;
+    const observedOfferEpoch = offerEpoch;
+    const identity = sessionIdentity(ctx);
+    const receipt = await readReceipt(ctx, options).catch(() => null);
+    if (
+      observedGeneration !== controllerGeneration ||
+      observedOfferEpoch !== offerEpoch ||
+      !sameIdentity(identity, sessionIdentity(liveContext))
+    )
+      return { shown: false, reason: "stale" };
+    if (!receipt) {
+      clearWidget(ctx);
+      return { shown: false, reason: "no_current_summary" };
+    }
+    return {
+      shown: await display(ctx, receipt, {
+        timezone: options.timezone ?? options.recapTimezone ?? recapTimezone,
+        expectedOfferEpoch: observedOfferEpoch,
+      }),
+      reason: "current_summary",
+      receipt,
+    };
+  };
+
+  const offer = ({ ctx, result, token, ...options }) => {
+    const record = result?.record;
+    if (
+      !tuiContext() ||
+      !tokenIsCurrent(token) ||
+      record?.status !== "ok" ||
+      typeof record.summary !== "string" ||
+      !record.summary.trim() ||
+      options.recapEnabled === false
+    )
+      return false;
+    const key = `${record.sessionId}:${record.branch?.pathHash ?? ""}:${record.jobId}`;
+    if (displayedReceipts.has(key) || pending?.key === key) return false;
+    cancelTimer();
+    const offeredIdentity = sessionIdentity(ctx);
+    pending = {
+      token,
+      record,
+      identity: offeredIdentity,
+      options,
+      key,
+      offerEpoch: offerEpoch + 1,
+    };
+    offerEpoch = pending.offerEpoch;
+    const fire = async () => {
+      timer = undefined;
+      const offerState = pending;
+      pending = undefined;
+      if (
+        !offerState ||
+        offerState.offerEpoch !== offerEpoch ||
+        !tokenIsCurrent(offerState.token)
+      )
+        return;
+      const current = liveContext;
+      const currentIdentity = sessionIdentity(current);
+      if (!sameIdentity(offerState.identity, currentIdentity)) return;
+      const receipt = await readReceipt(current, offerState.options).catch(
+        () => null,
+      );
+      if (
+        offerState.offerEpoch !== offerEpoch ||
+        !tokenIsCurrent(offerState.token)
+      )
+        return;
+      if (!receipt || receipt.jobId !== offerState.record.jobId) return;
+      if (await display(current, receipt, {
+        token: offerState.token,
+        expectedOfferEpoch: offerState.offerEpoch,
+        timezone:
+          offerState.options.timezone ??
+          offerState.options.recapTimezone ??
+          recapTimezone,
+      })) {
+        displayedReceipts.add(offerState.key);
+        if (displayedReceipts.size > 128)
+          displayedReceipts.delete(displayedReceipts.values().next().value);
+      }
+    };
+    timer = setTimeoutFn(fire, options.recapDelayMs ?? delayMs);
+    timer?.unref?.();
+    return true;
+  };
+
+  const dispose = () => {
+    invalidate(undefined, undefined);
+    liveContext = undefined;
+  };
+
+  return {
+    captureMaterialization,
+    offer,
+    showExisting,
+    updateContext,
+    invalidate,
+    dispose,
+  };
+}