@hypercarrier/rarebit 0.1.0-alpha.2 → 0.1.0-alpha.4

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.1.0-alpha.4 — 2026-08-02
+
+Alpha.4 is a new artifact with a sanitized current source lineage and unchanged
+product capability from the alpha.3 cutoff tree `db7d388`. The old tag graphs
+remain public and are not privacy-clean. All existing alpha.1, alpha.2, and
+alpha.3 tags, releases, and npm artifacts remain immutable (there is no alpha.1
+GitHub Release). Alpha.3 remains the original readable-Recall release. Intended
+npm routing after publication is `next=alpha.4` and `latest=alpha.1`.
+The source-only machine-readable candidate derivation and vendored-scanner
+binding is [`release/privacy-lineage.v1.json`](release/privacy-lineage.v1.json).
+It is excluded from npm and does not claim publication completion.
+
+This release changes only version and release documentation; runtime behavior
+and readable Markdown Recall are unchanged.
+
+## 0.1.0-alpha.3 — 2026-08-02
+
+- Recall now sends one human-readable Markdown user message with the exact request and local private JSON evidence references. Idle and busy steer behavior remains unchanged, and JSON files remain machine authority.
+
 ## 0.1.0-alpha.2 — 2026-08-02
 
 First promoted OIDC prerelease candidate. This corrective release has no

package/README.md

@@ -10,12 +10,22 @@ and visual language can change. It is not a Task, Project, runtime, priority,
 attention, or delivery authority. Native Pi Session JSONL remains the evidence
 authority.
 
+Alpha.4 is a new artifact with a sanitized current source lineage. Product
+capability is unchanged from the alpha.3 cutoff tree `db7d388`. The old tag
+graphs remain public and are not privacy-clean. All existing alpha.1, alpha.2,
+and alpha.3 tags, releases, and npm artifacts remain immutable (there is no
+alpha.1 GitHub Release). Alpha.3 remains the original readable-Recall release.
+Intended npm routing after publication is `next=alpha.4` and `latest=alpha.1`.
+The source-only machine-readable candidate derivation and vendored-scanner
+binding is [`release/privacy-lineage.v1.json`](release/privacy-lineage.v1.json).
+It is excluded from npm and does not claim publication completion.
+
 ## Install
 
 Use Node 22 or later and Pi 0.83 or later. Install it in Pi from npm:
 
 ```sh
-pi install npm:@hypercarrier/rarebit@0.1.0-alpha.2
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.4
 pi list
 ```
 
@@ -34,7 +44,7 @@ To use the CLI in a normal Node project, install it and invoke the local bin
 with npm:
 
 ```sh
-npm install @hypercarrier/rarebit@0.1.0-alpha.2
+npm install @hypercarrier/rarebit@0.1.0-alpha.4
 npm exec -- rarebit --help
 ```
 
@@ -101,8 +111,8 @@ remain until you remove them. Session JSONL retention is controlled by Pi.
 
 Run `/rarebit recall <prompt>` in a Pi Session. Rarebit writes the exact active
 branch selection to two private files: a conversation view and detailed
-lineage evidence. It then sends one atomic user message. The message contains
-your exact request and absolute pointers to both files.
+lineage evidence. It then sends one atomic, human-readable Markdown user
+message containing your exact request and absolute pointers to both files.
 
 When Pi is idle, that message starts one turn. When Pi is busy, it queues one
 steering message. Recall does not send a second follow-up, add a custom Session
@@ -110,7 +120,7 @@ entry, or create a durable Recall receipt.
 
 The temporary directory is mode 0700 and its JSON files are mode 0600. The
 files remain after the request so Pi can read them; delete the directory after
-the turn no longer needs it. Both files and the persisted Pi envelope are
+the turn no longer needs it. Both files and the persisted Pi message are
 sensitive. Do not put their paths or content in a ticket.
 
 ## Update, uninstall, and rollback
@@ -118,11 +128,15 @@ sensitive. Do not put their paths or content in a ticket.
 Pin alpha versions for reproducible installs:
 
 ```sh
-pi install npm:@hypercarrier/rarebit@0.1.0-alpha.2
-pi update npm:@hypercarrier/rarebit
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.4
 pi remove npm:@hypercarrier/rarebit
 ```
 
+The exact-version install also moves an existing Rarebit npm installation to
+that pin. Pi skips versioned npm sources during package updates. Do not use an
+unpinned source for alpha.4 recovery: unpinned npm resolution follows the
+retained `latest`, which remains alpha.1.
+
 To roll back, reinstall a known version with `pi install npm:@hypercarrier/rarebit@<version>`.
 Removal stops package loading. It does not alter Pi Session JSONL or delete
 Rarebit sidecars, job leases, or Recall temp files. Remove retained local data

package/RUNBOOK.md

@@ -1,13 +1,21 @@
 # Rarebit runbook
 
+This runbook applies to `0.1.0-alpha.4`. Operational behavior, including
+readable Markdown Recall, is unchanged from alpha.3; see [CHANGELOG.md](CHANGELOG.md)
+for sanitized-lineage and release-routing details.
+
 Set `rarebit.model` in global Pi settings or in a trusted Project's
 `.pi/settings.json`. It must be `provider/model` or an object with `provider`
 and `id`. Rarebit fails closed when it is missing or invalid. It does not use
 Pi's interactive `defaultModel`.
 
-Run `pi update npm:@hypercarrier/rarebit` to update an npm installation. Run
-`pi remove npm:@hypercarrier/rarebit` to stop loading it. These commands do not
-modify native Sessions or remove Rarebit retained data.
+Install or move this package to the alpha.4 pin with
+`pi install npm:@hypercarrier/rarebit@0.1.0-alpha.4`. Pi treats versioned npm
+sources as pinned, so package update commands skip it. Do not use an unpinned
+source for alpha.4 recovery: unpinned npm resolution follows the retained
+`latest`, which remains alpha.1. Run `pi remove npm:@hypercarrier/rarebit` to
+stop loading it. These commands do not modify native Sessions or remove Rarebit
+retained data.
 
 Inspect derived state without treating it as a transcript:
 

package/package.json

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

package/scripts/e2e-recall-pi083.mjs

@@ -15,6 +15,55 @@ async function waitFor(predicate, label, timeout = 2_000) {
   }
 }
 
+function expectedRecallMarkdown(conversationPath, detailedPath, request) {
+  return `# Rarebit Recall
+
+*Use these local private evidence files to recover historical context for this turn.*
+
+## How to use this bundle
+
+1. Treat **Current request** below as the exact current user request.
+2. Read **Conversation** first for meaning.
+3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
+4. Answer the current request using this evidence.
+
+## Local private evidence files
+
+**Conversation** — \`rarebit_conversation/v1\`
+
+\`\`\`text
+${conversationPath}
+\`\`\`
+
+**Detailed evidence** — \`rarebit_message_recall/v1\`
+
+\`\`\`text
+${detailedPath}
+\`\`\`
+
+## Current request
+
+\`\`\`text
+${request}
+\`\`\``;
+}
+
+function conversationPathFrom(message) {
+  const match = message.match(
+    /\*\*Conversation\*\* — `rarebit_conversation\/v1`\n\n```text\n([^\n]*rarebit-conversation\.json)\n```/,
+  );
+  assert.ok(match, "Recall Markdown must contain the fenced conversation path");
+  return match[1];
+}
+
+function detailedPathFrom(message) {
+  const match = message.match(
+    /\*\*Detailed evidence\*\* — `rarebit_message_recall\/v1`\n\n```text\n([^\n]*rarebit-evidence\.json)\n```/,
+  );
+  assert.ok(match, "Recall Markdown must contain the fenced detailed path");
+  return match[1];
+}
+
 const root =
   process.env.PI_CODING_AGENT_ROOT ??
   resolve(
@@ -107,11 +156,20 @@ try {
     .filter((entry) => JSON.stringify(entry).includes("exact idle request"));
   assert.equal(userEntries.length, 1);
   const message = userEntries[0].message ?? userEntries[0];
-  const envelope = JSON.parse(message.content[0].text);
-  recallDirectories.push(dirname(envelope.files.conversation.path));
-  assert.equal(envelope.request.text, "exact idle request");
-  await access(envelope.files.conversation.path);
-  await access(envelope.files.detailedEvidence.path);
+  const idleMessageText = message.content[0].text;
+  const idleConversationPath = conversationPathFrom(idleMessageText);
+  const idleDetailedPath = detailedPathFrom(idleMessageText);
+  assert.equal(
+    idleMessageText,
+    expectedRecallMarkdown(
+      idleConversationPath,
+      idleDetailedPath,
+      "exact idle request",
+    ),
+  );
+  recallDirectories.push(dirname(idleConversationPath));
+  await access(idleConversationPath);
+  await access(idleDetailedPath);
   assert.equal(
     manager
       .getBranch()
@@ -141,29 +199,29 @@ try {
   assert.equal(queued.steering.length, 1);
   assert.equal(queued.followUp?.length ?? 0, 0);
   const queuedMessage = queued.steering[0];
-  const busyEnvelope = JSON.parse(
+  const busyMessageText =
     typeof queuedMessage === "string"
       ? queuedMessage
-      : (queuedMessage.content?.[0]?.text ?? queuedMessage.content),
+      : (queuedMessage.content?.[0]?.text ?? queuedMessage.content);
+  const busyConversationPath = conversationPathFrom(busyMessageText);
+  const busyDetailedPath = detailedPathFrom(busyMessageText);
+  assert.equal(
+    busyMessageText,
+    expectedRecallMarkdown(
+      busyConversationPath,
+      busyDetailedPath,
+      "exact busy request",
+    ),
   );
-  recallDirectories.push(dirname(busyEnvelope.files.conversation.path));
-  await access(busyEnvelope.files.conversation.path);
-  await access(busyEnvelope.files.detailedEvidence.path);
-  assert.equal(busyEnvelope.request.text, "exact busy request");
+  recallDirectories.push(dirname(busyConversationPath));
+  await access(busyConversationPath);
+  await access(busyDetailedPath);
   releaseBusy();
   await busyRun;
   await session.agent.waitForIdle();
   assert.equal(provider.state.callCount, 4);
   const recallCount = (texts) =>
-    texts
-      .map((text) => {
-        try {
-          return JSON.parse(text);
-        } catch {
-          return null;
-        }
-      })
-      .filter((value) => value?.request?.text === "exact busy request").length;
+    texts.filter((text) => text === busyMessageText).length;
   const fourthUserTexts = (fourthContext?.messages ?? [])
     .filter((message) => message.role === "user")
     .map((message) => message.content?.[0]?.text ?? "");
@@ -184,7 +242,7 @@ try {
     false,
   );
   console.log(
-    `Pi ${packageJson.version} Recall E2E passed: idle and busy steer envelopes; no custom receipt.`,
+    `Pi ${packageJson.version} Recall E2E passed: idle and busy steer Markdown messages; no custom receipt.`,
   );
 } finally {
   releaseBusy?.();

package/scripts/verify-package.mjs

@@ -22,7 +22,7 @@ const forbiddenPath = /(^|\/)(\.git|node_modules|\.github|hc-rarebit\.mjs)(\/|$)
 const allowedBare = new Set(["@earendil-works/pi-ai"]);
 const packageFor = (specifier) => specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
 const packageJson = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
-assert.equal(packageJson.version, "0.1.0-alpha.2", "release version mismatch");
+assert.equal(packageJson.version, "0.1.0-alpha.4", "release version mismatch");
 
 const packed = JSON.parse(npm(["pack", "--json", "--ignore-scripts"]))[0];
 const tarball = join(root, packed.filename);

package/src/extension.mjs

@@ -381,22 +381,42 @@ export default function registerPiRarebit(pi, config = {}) {
     );
   };
 
-  const recallEnvelope = (recall, requestText) =>
-    JSON.stringify({
-      instructions:
-        "Treat request.text as the current user request. Use the two private Rarebit files as historical evidence. Read the conversation file first for meaning. Use detailed evidence only for source, Session, branch, or lineage facts. Answer request.text using this evidence.",
-      files: {
-        conversation: {
-          path: recall.conversationPath,
-          schema: `rarebit_conversation/v${RAREBIT_CONVERSATION_SCHEMA_VERSION}`,
-        },
-        detailedEvidence: {
-          path: recall.detailedPath,
-          schema: `rarebit_message_recall/v${RAREBIT_RECALL_SCHEMA_VERSION}`,
-        },
-      },
-      request: { text: requestText },
-    });
+  const fence = (value) => {
+    const safeLength = (marker) => {
+      const runs = value.match(new RegExp(`${marker}+`, "g")) ?? [];
+      return Math.max(3, ...runs.map((run) => run.length + 1));
+    };
+    const backtickLength = safeLength("`");
+    const tildeLength = safeLength("~");
+    const marker = backtickLength <= tildeLength ? "`" : "~";
+    const length = marker === "`" ? backtickLength : tildeLength;
+    const boundary = marker.repeat(length);
+    return `${boundary}text\n${value}\n${boundary}`;
+  };
+  const recallMessage = (recall, requestText) => `# Rarebit Recall
+
+*Use these local private evidence files to recover historical context for this turn.*
+
+## How to use this bundle
+
+1. Treat **Current request** below as the exact current user request.
+2. Read **Conversation** first for meaning.
+3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
+4. Answer the current request using this evidence.
+
+## Local private evidence files
+
+**Conversation** — \`rarebit_conversation/v${RAREBIT_CONVERSATION_SCHEMA_VERSION}\`
+
+${fence(recall.conversationPath)}
+
+**Detailed evidence** — \`rarebit_message_recall/v${RAREBIT_RECALL_SCHEMA_VERSION}\`
+
+${fence(recall.detailedPath)}
+
+## Current request
+
+${fence(requestText)}`;
 
   pi.registerCommand?.("rarebit", {
     description: rarebitCommandDescription(),
@@ -432,7 +452,7 @@ export default function registerPiRarebit(pi, config = {}) {
               "the active Pi Session or branch changed during materialization",
             );
           }
-          pi.sendUserMessage(recallEnvelope(recall, prompt), {
+          pi.sendUserMessage(recallMessage(recall, prompt), {
             deliverAs: "steer",
           });
           notify(ctx, "Rarebit recall bundle prepared; turn requested", "info");

package/test/rarebit-recall.test.mjs

@@ -303,36 +303,120 @@ function extensionHarness({ recallMaterializer, sendUserMessage } = {}) {
   return { commands, handlers, pi, sent, tools };
 }
 
-test("recall sends one self-contained steer envelope in idle and busy contexts", async () => {
+test("recall sends one exact fenced Markdown steer message in idle and busy contexts", async () => {
   const sessionFile = "/tmp/session-recall.jsonl";
   const recall = {
-    conversationPath: "/tmp/hc-rarebit-recall-test/rarebit-conversation.json",
-    detailedPath: "/tmp/hc-rarebit-recall-test/rarebit-evidence.json",
+    conversationPath:
+      "/tmp/Rare bit [会话] (one) **/tick`` and ~~\nnext/rarebit-conversation.json",
+    detailedPath:
+      "/tmp/Detailed [证据] (two) **/tick```` and ~~~\n~~~line-start/rarebit-evidence.json",
     sessionId: "session-recall",
     sessionFile,
     branchLeafId: "stop",
   };
+  const prompt =
+    "\n# Heading-looking request\n- list-looking item\n```text\ninside backticks\n```\n~~~~\ninside tildes\n~~~~\nTrailing request\n";
+  const expectedMessage = `# Rarebit Recall
+
+*Use these local private evidence files to recover historical context for this turn.*
+
+## How to use this bundle
+
+1. Treat **Current request** below as the exact current user request.
+2. Read **Conversation** first for meaning.
+3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
+4. Answer the current request using this evidence.
+
+## Local private evidence files
+
+**Conversation** — \`rarebit_conversation/v1\`
+
+\`\`\`text
+${recall.conversationPath}
+\`\`\`
+
+**Detailed evidence** — \`rarebit_message_recall/v1\`
+
+~~~~text
+${recall.detailedPath}
+~~~~
+
+## Current request
+
+\`\`\`\`text
+${prompt}
+\`\`\`\``;
+
   for (const busy of [false, true]) {
     const notices = [];
     const harness = extensionHarness({ recallMaterializer: async () => recall });
     const ctx = contextFor(branch(), sessionFile, notices);
     ctx.isIdle = () => !busy;
-    const prompt = "Use \"this\" evidence\\path\nwith  spacing.  ";
     await harness.commands.get("rarebit").handler(`recall ${prompt}`, ctx);
     assert.equal(harness.sent.length, 1);
+    assert.equal(harness.sent[0].args[0], expectedMessage);
     assert.deepEqual(harness.sent[0].args[1], { deliverAs: "steer" });
-    const envelope = JSON.parse(harness.sent[0].args[0]);
-    assert.equal(envelope.request.text, prompt);
-    assert.match(envelope.instructions, /request\.text as the current user request/i);
-    assert.equal(envelope.files.conversation.path, recall.conversationPath);
-    assert.equal(envelope.files.conversation.schema, "rarebit_conversation/v1");
-    assert.equal(envelope.files.detailedEvidence.path, recall.detailedPath);
-    assert.equal(envelope.files.detailedEvidence.schema, "rarebit_message_recall/v1");
-    assert.match(envelope.instructions, /conversation file first/i);
+    assert.equal(expectedMessage.includes(recall.conversationPath), true);
+    assert.equal(expectedMessage.includes(recall.detailedPath), true);
+    assert.equal(expectedMessage.includes(prompt), true);
     assert.match(notices.at(-1).text, /bundle prepared; turn requested/i);
   }
 });
 
+test("long delimiter runs ending at value boundaries use the shortest safe fences", async () => {
+  const pathBackticks = "`".repeat(80);
+  const pathTildes = "~".repeat(47);
+  const conversationPath = `/tmp/long-runs/${pathBackticks}/${pathTildes}`;
+  const requestTildes = "~".repeat(96);
+  const requestBackticks = "`".repeat(63);
+  const request = `Boundary ${requestTildes} ${requestBackticks}`;
+  const harness = extensionHarness({
+    recallMaterializer: async () => ({
+      conversationPath,
+      detailedPath: "/tmp/rarebit-evidence.json",
+      sessionId: "session-recall",
+      sessionFile: "/tmp/session-recall.jsonl",
+      branchLeafId: "stop",
+    }),
+  });
+
+  await harness.commands
+    .get("rarebit")
+    .handler(
+      `recall ${request}`,
+      contextFor(branch(), "/tmp/session-recall.jsonl"),
+    );
+
+  assert.equal(harness.sent.length, 1);
+  const message = harness.sent[0].args[0];
+  const conversationBlock = message.match(
+    /\*\*Conversation\*\* — `rarebit_conversation\/v1`\n\n([`~]+)text\n([^\n]*)\n\1\n\n\*\*Detailed evidence\*\*/,
+  );
+  assert.ok(conversationBlock);
+  assert.equal(conversationBlock[2], conversationPath);
+  assert.equal(conversationBlock[2].endsWith(pathTildes), true);
+  const conversationFence = conversationBlock[1];
+  assert.equal(conversationFence[0], "~");
+  assert.ok(conversationFence.length >= 3);
+  assert.equal(conversationFence.length, pathTildes.length + 1);
+  assert.ok(conversationFence.length > pathTildes.length);
+  assert.ok(conversationFence.length < pathBackticks.length + 1);
+
+  const requestBlock = message.match(
+    /## Current request\n\n([`~]+)text\n([\s\S]*)\n\1$/,
+  );
+  assert.ok(requestBlock);
+  assert.equal(requestBlock[2], request);
+  assert.equal(requestBlock[2].endsWith(requestBackticks), true);
+  const requestFence = requestBlock[1];
+  assert.equal(requestFence[0], "`");
+  assert.ok(requestFence.length >= 3);
+  assert.equal(requestFence.length, requestBackticks.length + 1);
+  assert.ok(requestFence.length > requestBackticks.length);
+  assert.ok(requestFence.length < requestTildes.length + 1);
+  assert.equal(message.endsWith(`${request}\n${requestFence}`), true);
+});
+
 test("single-send failure discards the prepared Recall bundle", async () => {
   const notices = [];
   let discarded = 0;