@hypercarrier/rarebit 0.2.0 → 0.2.1

package/src/rarebit-recap.mjs

@@ -1,4 +1,5 @@
-import { exactSelectionApplies } from "./rarebit-artifact-state.mjs";
+import { RECAP_ENTRY_TYPE, RECAP_READ_TYPE, latestRecap, recapIsRead } from "./rarebit-read-checkpoint.mjs";
+import { exactSelectionApplies, projectRarebitArtifactState } from "./rarebit-artifact-state.mjs";
 import { selectRarebits } from "./rarebit-core.mjs";
 import {
   DEFAULT_RAREBIT_RECAP_DELAY_MS,
@@ -28,65 +29,47 @@ function branchSnapshot(ctx) {
   return Array.isArray(branch) ? branch.slice() : [];
 }
 
-function receiptAppliesToContext(receipt, ctx) {
-  if (receipt?.status !== "ok") return false;
+function receiptCoverage(receipt, ctx) {
+  if (receipt?.status !== "ok") return { state: null, coverage: null };
   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));
+  if (!identity.sessionId || !identity.sessionFile || receipt.sessionId !== identity.sessionId) return { state: null, coverage: null };
+  const selection = selectRarebits(branchSnapshot(ctx));
+  const current = projectRarebitArtifactState({
+    native: { availability: "available", sessionId: identity.sessionId,
+      selection: { ...selection, selectorVersion: selection.manifest.selectorVersion } },
+    materialization: { availability: "available", records: [receipt] },
+  });
+  if (current.receiptRef?.jobId !== receipt.jobId ||
+      !["request_current", "assessment_current"].includes(current.syncState)) return { state: current, coverage: null };
+  if (current.applicability === "exact_selection" && exactSelectionApplies(receipt.selection, selection))
+    return { state: current, coverage: { coveredEntryId: selection.occurrences.at(-1)?.sourceEntryId, selectionHash: receipt.selection.manifestHash } };
+  if (current.applicability === "request_generation") {
+    const covered = selection.occurrences[receipt.selection.occurrenceCount - 1];
+    return { state: current, coverage: covered ? { coveredEntryId: covered.sourceEntryId, selectionHash: receipt.selection.manifestHash } : null };
+  }
+  return { state: current, coverage: null };
 }
 
 function observedAtLabel(observedAt, timezone) {
   const date = new Date(observedAt);
-  if (Number.isNaN(date.valueOf())) return String(observedAt ?? "unknown");
+  if (Number.isNaN(date.valueOf())) return "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;
+  const options = usesHostTimezone ? {} : { timeZone: timezone };
+  const parts = new Intl.DateTimeFormat("en-US", {
+    month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit",
+    hourCycle: "h23", ...options,
+  }).formatToParts(date);
+  const value = (type) => parts.find((part) => part.type === type)?.value ?? "00";
+  let offset = "GMT";
   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}` : ""})`;
+    offset = new Intl.DateTimeFormat("en", { timeZoneName: "shortOffset", ...options })
+      .formatToParts(date).find((part) => part.type === "timeZoneName")?.value ?? "GMT";
+  } catch {}
+  return `${value("month")}/${value("day")} ${value("hour")}:${value("minute")}(${offset})`;
 }
 
 let recapWidgetComponents;
+let loadedComponents;
 
 async function loadRecapWidgetComponents() {
   if (!recapWidgetComponents) {
@@ -97,7 +80,9 @@ async function loadRecapWidgetComponents() {
       Container: tui.Container,
       Text: tui.Text,
       DynamicBorder: agent.DynamicBorder,
-    }));
+      truncateToWidth: tui.truncateToWidth,
+      visibleWidth: tui.visibleWidth,
+    })).then((components) => (loadedComponents = components));
   }
   return recapWidgetComponents;
 }
@@ -107,12 +92,70 @@ function summaryContent(
   { 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 mark = presentation.mark ?? "";
+  const heading = `${mark}Recap·${presentation.label.replaceAll(" ", "")}·${observedAtLabel(receipt.observedAt, timezone)}`;
   const summary = String(receipt.summary ?? "").trim();
   return { heading, summary };
 }
 
+function recapComponent(content, theme) {
+  const border = (text) => theme.fg("borderMuted", text);
+  const widget = new loadedComponents.Container();
+  const summary = new loadedComponents.Text("", 1, 0);
+  const compactSummary = new loadedComponents.Text("", 0, 0);
+  let previousSummary;
+  let previousCompactSummary;
+  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) {
+      const action = content.action
+        ? loadedComponents.truncateToWidth(theme.fg("dim", content.action), Math.max(0, width), "")
+        : "";
+      const actionWidth = loadedComponents.visibleWidth(action);
+      const heading = loadedComponents.truncateToWidth(
+        theme.fg("dim", content.heading), Math.max(0, width - actionWidth), "",
+      );
+      return [`${heading}${action}`];
+    },
+    invalidate() {},
+  };
+  const themedSummary = {
+    render(width) {
+      if (width < 3) {
+        themed(content.summary, "muted", compactSummary, previousCompactSummary ??= {});
+        return compactSummary.render(width);
+      }
+      themed(content.summary, "muted", summary, previousSummary ??= {});
+      return summary.render(width);
+    },
+    invalidate() {
+      previousSummary = undefined;
+      previousCompactSummary = undefined;
+      summary.invalidate();
+      compactSummary.invalidate();
+    },
+  };
+  widget.addChild(new loadedComponents.DynamicBorder(border));
+  widget.addChild(themedHeading);
+  widget.addChild(themedSummary);
+  widget.addChild(new loadedComponents.DynamicBorder(border));
+  return {
+    render(width) {
+      const lines = widget.render(width);
+      return width < 3
+        ? lines.map((line) => loadedComponents.truncateToWidth(line, Math.max(0, width), ""))
+        : lines;
+    },
+    invalidate() { widget.invalidate(); },
+  };
+}
+
 function currentContextOptions(ctx, options) {
   return {
     sessionFile: sessionIdentity(ctx).sessionFile,
@@ -133,13 +176,14 @@ function sameIdentity(left, right) {
 
 /**
  * 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.
+ * uses native custom entries for scrollable, human-only Recaps and read state.
+ * Older Pi versions retain the widget fallback. It never invokes a model.
  */
 export function createRarebitRecapController({
   delayMs = DEFAULT_RAREBIT_RECAP_DELAY_MS,
   timezone = DEFAULT_RAREBIT_RECAP_TIMEZONE,
   readCurrent = readRarebitCurrent,
+  appendEntry,
   setTimeoutFn = setTimeout,
   clearTimeoutFn = clearTimeout,
 } = {}) {
@@ -223,88 +267,65 @@ export function createRarebitRecapController({
       ...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;
+    if (!receipt || !["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 { receipt: null, reason: artifactState?.projection?.reason ?? artifactState?.retry?.reason ?? artifactState?.syncState ?? "no_summary" };
+    const projection = receiptCoverage(receipt, ctx);
+    return projection.coverage ? { receipt, coverage: projection.coverage } : {
+      receipt: null, reason: projection.state?.retry?.reason ?? projection.state?.projection?.reason ?? projection.state?.syncState ?? "stale_or_divergent",
+    };
   };
 
   const display = async (
     ctx,
     receipt,
-    { timezone = recapTimezone, token, expectedOfferEpoch } = {},
+    { timezone = recapTimezone, token, expectedOfferEpoch, storeOptions } = {},
   ) => {
     const target = tuiContext(ctx);
-    if (!target || !receiptAppliesToContext(receipt, ctx)) return false;
+    let coverage = receiptCoverage(receipt, ctx).coverage;
+    if (!target || !coverage) return false;
     const observedControllerGeneration = controllerGeneration;
     const observedLifecycleGeneration = liveLifecycleGeneration;
     const observedOfferEpoch = expectedOfferEpoch ?? offerEpoch;
     const observedIdentity = sessionIdentity(ctx);
     try {
-      const components = await loadRecapWidgetComponents();
+      await loadRecapWidgetComponents();
+      const current = await readReceipt(liveContext, storeOptions).catch(() => null);
       if (
         observedControllerGeneration !== controllerGeneration ||
         observedLifecycleGeneration !== liveLifecycleGeneration ||
         observedOfferEpoch !== offerEpoch ||
         (token && !tokenIsCurrent(token)) ||
         !sameIdentity(observedIdentity, sessionIdentity(liveContext)) ||
-        !receiptAppliesToContext(receipt, liveContext)
+        !current?.receipt || current.receipt.jobId !== receipt.jobId ||
+        current.coverage.coveredEntryId !== coverage.coveredEntryId ||
+        current.coverage.selectionHash !== coverage.selectionHash
       )
         return false;
+      receipt = current.receipt;
+      coverage = current.coverage;
       const content = summaryContent(receipt, {
         timezone: normalizeRarebitRecapTimezone(timezone),
       });
+      if (typeof appendEntry === "function") {
+        const existing = branchSnapshot(ctx).findLast((entry) =>
+          entry.type === "custom" && entry.customType === RECAP_ENTRY_TYPE &&
+          entry.data?.version === 1 && entry.data.jobId === receipt.jobId &&
+          entry.data.coveredEntryId === coverage.coveredEntryId &&
+          entry.data.selectionHash === coverage.selectionHash);
+        if (!existing) appendEntry(RECAP_ENTRY_TYPE, {
+          version: 1, ...content, jobId: receipt.jobId,
+          coveredEntryId: coverage.coveredEntryId, selectionHash: coverage.selectionHash,
+        });
+        return true;
+      }
       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;
+          return recapComponent(content, theme);
         },
         { placement: "aboveEditor" },
       );
@@ -321,25 +342,23 @@ export function createRarebitRecapController({
     const observedGeneration = controllerGeneration;
     const observedOfferEpoch = offerEpoch;
     const identity = sessionIdentity(ctx);
-    const receipt = await readReceipt(ctx, options).catch(() => null);
+    const current = await readReceipt(ctx, options).catch(() => null);
     if (
       observedGeneration !== controllerGeneration ||
       observedOfferEpoch !== offerEpoch ||
       !sameIdentity(identity, sessionIdentity(liveContext))
     )
       return { shown: false, reason: "stale" };
-    if (!receipt) {
+    if (!current?.receipt) {
       clearWidget(ctx);
-      return { shown: false, reason: "no_current_summary" };
+      return { shown: false, reason: current?.reason ?? "no_current_summary" };
     }
-    return {
-      shown: await display(ctx, receipt, {
-        timezone: options.timezone ?? options.recapTimezone ?? recapTimezone,
-        expectedOfferEpoch: observedOfferEpoch,
-      }),
-      reason: "current_summary",
-      receipt,
-    };
+    const shown = await display(ctx, current.receipt, {
+      storeOptions: options,
+      timezone: options.timezone ?? options.recapTimezone ?? recapTimezone,
+      expectedOfferEpoch: observedOfferEpoch,
+    });
+    return { shown, reason: shown ? "current_summary" : "stale_or_unavailable", receipt: current.receipt };
   };
 
   const offer = ({ ctx, result, token, ...options }) => {
@@ -379,7 +398,7 @@ export function createRarebitRecapController({
       const current = liveContext;
       const currentIdentity = sessionIdentity(current);
       if (!sameIdentity(offerState.identity, currentIdentity)) return;
-      const receipt = await readReceipt(current, offerState.options).catch(
+      const currentReceipt = await readReceipt(current, offerState.options).catch(
         () => null,
       );
       if (
@@ -387,8 +406,9 @@ export function createRarebitRecapController({
         !tokenIsCurrent(offerState.token)
       )
         return;
-      if (!receipt || receipt.jobId !== offerState.record.jobId) return;
-      if (await display(current, receipt, {
+      if (!currentReceipt?.receipt || currentReceipt.receipt.jobId !== offerState.record.jobId) return;
+      if (await display(current, currentReceipt.receipt, {
+        storeOptions: offerState.options,
         token: offerState.token,
         expectedOfferEpoch: offerState.offerEpoch,
         timezone:
@@ -406,12 +426,49 @@ export function createRarebitRecapController({
     return true;
   };
 
+  const renderEntry = (entry, _options, theme) => {
+    if (entry.data?.version !== 1 || typeof entry.data.summary !== "string" ||
+        typeof entry.data.heading !== "string") return undefined;
+    let component;
+    // Resume can render entries before the optional Pi imports settle. Keep a
+    // placeholder while the optional components load, then request a redraw.
+    if (!loadedComponents)
+      void loadRecapWidgetComponents().then(() => clearWidget()).catch(() => {});
+    return {
+      render(width) {
+        if (!loadedComponents) return [theme.fg("dim", "Recap loading…".slice(0, width))];
+        const read = recapIsRead(branchSnapshot(liveContext), entry);
+        component = recapComponent({ ...entry.data,
+          action: read ? " ✓ got it" : " [got it]" }, theme);
+        return component.render(width);
+      },
+      invalidate() { component?.invalidate(); },
+    };
+  };
+
+  const acknowledge = (ctx) => {
+    if (typeof appendEntry !== "function" || !sameIdentity(sessionIdentity(ctx), sessionIdentity(liveContext)))
+      return { acknowledged: false, reason: "unavailable" };
+    const branch = branchSnapshot(ctx);
+    const recap = latestRecap(branch);
+    if (!recap) return { acknowledged: false, reason: "no_recap" };
+    if (recapIsRead(branch, recap))
+      return { acknowledged: false, reason: "already_read" };
+    appendEntry(RECAP_READ_TYPE, { version: 1, recapEntryId: recap.id,
+      jobId: recap.data.jobId, coveredEntryId: recap.data.coveredEntryId,
+      selectionHash: recap.data.selectionHash });
+    clearWidget(ctx);
+    return { acknowledged: true };
+  };
+
   const dispose = () => {
     invalidate(undefined, undefined);
     liveContext = undefined;
   };
 
   return {
+    renderEntry,
+    acknowledge,
     captureMaterialization,
     offer,
     showExisting,

package/src/rarebit-service.mjs

@@ -1,3 +1,4 @@
+import { recapReadCheckpoint } from "./rarebit-read-checkpoint.mjs";
 import {
   DEFAULT_RAREBIT_SUMMARY_POLICY,
   DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE,
@@ -35,7 +36,7 @@ import {
 } from "./automatic-summary-policy.mjs";
 
 export const RAREBIT_TITLE_IMPLEMENTATION_VERSION = "hc-rarebit-title-v4";
-export const RAREBIT_SUMMARY_IMPLEMENTATION_VERSION = "hc-rarebit-summary-v6";
+export const RAREBIT_SUMMARY_IMPLEMENTATION_VERSION = "hc-rarebit-summary-v7";
 export const RAREBIT_SUMMARY_SCHEMA_VERSION = 4;
 export const RAREBIT_INPUT_CHARS_PER_TOKEN = 4;
 export const DEFAULT_RAREBIT_MAX_PROMPT_CHARS =
@@ -151,6 +152,7 @@ export async function processRarebitSummary(ctx, config = {}) {
   const sessionFile = config.sessionFile ?? sessionFileFrom(ctx);
   const sessionId = config.sessionId ?? sessionIdFrom(ctx);
   const selection = selectRarebits(branch);
+  const readCheckpoint = recapReadCheckpoint(branch, selection);
   const measurement = measureRarebits(branch, selection);
   const policy = normalizeRarebitSummaryPolicy(
     config.summaryPolicy ?? DEFAULT_RAREBIT_SUMMARY_POLICY,
@@ -227,7 +229,7 @@ export async function processRarebitSummary(ctx, config = {}) {
     branch: branchRef,
     selection,
     policy,
-    inputPolicy: inputCoveragePolicy,
+    inputPolicy: { ...inputCoveragePolicy, ...(readCheckpoint ? { readCheckpoint } : {}) },
     lifecycleBoundary,
     promptVersion,
     promptIdentity: summaryPrompt.promptIdentity,
@@ -322,6 +324,7 @@ export async function processRarebitSummary(ctx, config = {}) {
     const derivationInput = composeRarebitSummaryDerivationInput(selection, {
       promptVersion,
       summaryPrompt: config.summaryPrompt,
+      readCheckpoint,
       lifecycleBoundary,
       maxPromptChars,
     });

package/src/types.d.ts

@@ -272,6 +272,7 @@ export function composeRarebitSummaryDerivationInput(
     summaryPrompt?: unknown;
     lifecycleBoundary?: "owner_request" | "agent_settled" | "manual";
     maxPromptChars?: number;
+    readCheckpoint?: { coveredEntryId: string } | null;
   }): {
   prompt: string;
   promptIdentity: string | null;
@@ -285,6 +286,7 @@ export function composeRarebitSummaryPrompt(
     summaryPrompt?: unknown;
     lifecycleBoundary?: "owner_request" | "agent_settled" | "manual";
     maxPromptChars?: number;
+    readCheckpoint?: { coveredEntryId: string } | null;
   },
 ): string;
 export function composeRarebitTitlePrompt(
@@ -380,7 +382,8 @@ type RarebitSummaryReceiptCommon = {
   implementationVersion:
     | "hc-rarebit-summary-v4"
     | "hc-rarebit-summary-v5"
-    | "hc-rarebit-summary-v6";
+    | "hc-rarebit-summary-v6"
+    | "hc-rarebit-summary-v7";
   synthesisMode: "forced" | "automatic";
   inputCoveragePolicy: RarebitInputCoveragePolicy;
   promptVersion: string;
@@ -445,7 +448,7 @@ export type RarebitNativeObservation =
   | { availability: "missing" | "unreadable" };
 
 export const RAREBIT_SUMMARY_SCHEMA_VERSION: 4;
-export const RAREBIT_SUMMARY_IMPLEMENTATION_VERSION: "hc-rarebit-summary-v6";
+export const RAREBIT_SUMMARY_IMPLEMENTATION_VERSION: "hc-rarebit-summary-v7";
 export const RAREBIT_INPUT_CHARS_PER_TOKEN: 4;
 export const DEFAULT_RAREBIT_MAX_PROMPT_CHARS: 256000;
 export function processRarebitSummary(

package/test/rarebit-artifact-state.test.mjs

@@ -285,12 +285,18 @@ test("only agent_settled ends an active request generation; exact start/manual c
     });
     assert.equal(state.syncState, "request_current");
   }
+  const exact = [owner, continuation];
+  const settled = receipt({ occurrences: exact, boundary: "agent_settled", observedAt: "2026-07-25T10:03:00.000Z" });
+  const newerManual = receipt({ occurrences: exact, boundary: "manual", observedAt: "2026-07-25T10:04:00.000Z" });
+  const promoted = projectRarebitArtifactState({
+    native: native(exact),
+    materialization: { availability: "available", records: [settled, newerManual] },
+  });
+  assert.equal(promoted.syncState, "assessment_current");
+  assert.equal(promoted.receiptRef.lifecycleBoundary, "manual");
   const manualOnly = projectRarebitArtifactState({
     native: native([owner]),
-    materialization: {
-      availability: "available",
-      records: [receipt({ boundary: "manual" })],
-    },
+    materialization: { availability: "available", records: [receipt({ boundary: "manual" })] },
   });
   assert.equal(manualOnly.syncState, "assessment_current");
 });

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/help/status/recall/fork/config/auto-title/title/recap/summarize",
+    "Rarebit menu/settings/help/status/recall/fork/config/auto-title/title/recap/got-it/summarize",
   );
   assert.equal(
     rarebitCommandUsage(),
-    "Usage: /rarebit [menu|settings|help|status|recall|fork|config|auto-title|title|recap|summarize]",
+    "Usage: /rarebit [menu|settings|help|status|recall|fork|config|auto-title|title|recap|got-it|summarize]",
   );
   assert.equal(
     rarebitCommandUsage("config"),
@@ -53,6 +53,8 @@ test("parser accepts exactly the command grammar", () => {
   assert.equal(parseRarebitCommand("auto-title off").ok, true);
   assert.equal(parseRarebitCommand("title").ok, true);
   assert.equal(parseRarebitCommand("summarize").ok, true);
+  assert.equal(parseRarebitCommand("got-it").ok, true);
+  assert.equal(parseRarebitCommand("got-it now").ok, false);
   assert.deepEqual(
     parseRarebitCommand(
       "recall Review the evidence, then  continue exactly.  ",
@@ -103,6 +105,7 @@ test("autocomplete covers subcommands and discrete nested arguments", () => {
     "auto-title",
     "title",
     "recap",
+    "got-it",
     "summarize",
   ]);
   assert.deepEqual(values("s"), ["settings", "status", "summarize"]);

package/test/rarebit-core.test.mjs

@@ -160,6 +160,56 @@ test("bounded Summary input retains newest evidence and declares every omission"
   assert.equal(DEFAULT_RAREBIT_MAX_PROMPT_CHARS, 256_000);
 });
 
+test("read checkpoints stay metadata beside a retained evidence suffix and do not replace pending approval", () => {
+  const selection = selectRarebits([
+    entry("early", { role: "user", content: `EARLY-${"e".repeat(5_000)}` }),
+    entry("approval", { role: "assistant", stopReason: "stop", content: `${"p".repeat(5_000)}-APPROVAL-STILL-NEEDED` }),
+  ]);
+  const input = composeRarebitSummaryDerivationInput(selection, {
+    maxPromptChars: 6_000,
+    readCheckpoint: { coveredEntryId: "approval", coveredOrder: 1 },
+  });
+  const lines = input.prompt.split("BEGIN_RAREBIT_MESSAGES_JSONL\n")[1].split("\nEND_RAREBIT_MESSAGES_JSONL")[0].split("\n").map(JSON.parse);
+  assert.ok(input.prompt.length <= 6_000);
+  assert.equal(input.coverage.totalMessageCount, 2);
+  assert.equal(input.coverage.includedMessageCount, 1);
+  assert.ok(lines.some((line) => line.type === "recap_read"));
+  assert.ok(lines.some((line) => line.text?.includes("APPROVAL-STILL-NEEDED")));
+  assert.doesNotMatch(input.prompt, /EARLY-/);
+  assert.match(input.prompt, /omitted|trimmed/);
+});
+
+test("read boundaries stay before, at, or after the retained evidence suffix", () => {
+  const selection = selectRarebits(Array.from({ length: 4 }, (_, index) =>
+    entry(`u${index}`, { role: "user", content: `evidence-${index}-${"x".repeat(1_200)}` })));
+  for (const coveredIndex of [0, 1, 3]) {
+    const input = composeRarebitSummaryDerivationInput(selection, {
+      maxPromptChars: 7_500,
+      readCheckpoint: { coveredEntryId: `u${coveredIndex}`, coveredOrder: coveredIndex },
+    });
+    const body = input.prompt.split("BEGIN_RAREBIT_MESSAGES_JSONL\n")[1].split("\nEND_RAREBIT_MESSAGES_JSONL")[0];
+    const lines = body.split("\n").map(JSON.parse);
+    const ordered = lines.filter((line) => !line.omitted);
+    const readIndex = ordered.findIndex((line) => line.type === "recap_read");
+    const evidence = ordered.filter((line) => line.type !== "recap_read");
+    assert.ok(input.coverage.omittedMessageCount > 0);
+    assert.ok(input.prompt.length <= 7_500);
+    if (coveredIndex === 0) assert.equal(readIndex, 0, "a boundary before the suffix leads it");
+    if (coveredIndex === 1) assert.equal(readIndex, 1, "a boundary at the first retained message follows it");
+    if (coveredIndex === 3) assert.equal(readIndex, evidence.length, "a boundary after the suffix follows all retained messages");
+  }
+});
+
+test("fixed prompt overflow preserves evidence when even empty trimmed input cannot fit", () => {
+  const text = "PENDING-APPROVAL-" + "x".repeat(500);
+  const selection = selectRarebits([entry("u", { role: "user", content: text })]);
+  const input = composeRarebitSummaryDerivationInput(selection, { maxPromptChars: 3_100 });
+  assert.ok(input.prompt.length > 3_100);
+  assert.equal(input.coverage.omittedTextChars, 0);
+  assert.match(input.prompt, /PENDING-APPROVAL/);
+  assert.doesNotMatch(input.prompt, /leading characters.*trimmed/);
+});
+
 test("one oversized newest message is tail-bounded with an explicit character omission", () => {
   const selection = selectRarebits([
     entry("huge", {