@hypercarrier/rarebit 0.1.0-alpha.5 → 0.1.0-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.0-alpha.6 — 2026-09-21
+
+- Add bounded `/rarebit fork` and CLI fork flows with native Pi headroom checks.
+- Add PiQ read-only recovery, machine-only lineage, repeat-fork ancestry, and
+  activity exclusion for imported entries.
+- Keep read-only package commands usable without optional Pi host peers; fork
+  runtime loads the Pi adapter only when needed.
+
+This is an unpublished release candidate. Intended npm routing after
+publication is `next=alpha.6`; `latest` remains `alpha.4`.
+
 ## 0.1.0-alpha.5 — 2026-08-16
 
 - Repair Pi 0.84.2 Summary calls to use the active Pi model runtime. The
@@ -7,8 +18,9 @@
 - Declare the unbounded Pi AI peer range from Pi 0.83.0. The release gate runs
   Recall against Pi 0.83.0 and Pi 0.84.2.
 
-This is an unpublished local release candidate. Intended npm routing after
-publication is `next=alpha.5` and `latest=alpha.4`.
+Published through GitHub Actions OIDC to npm `next`; `latest` remains alpha.4.
+The exact source, package, registry, provenance, and GitHub prerelease evidence
+is in the [alpha.5 release receipt](release/v0.1.0-alpha.5-release-receipt.md).
 
 ## 0.1.0-alpha.4 — 2026-08-02
 

package/README.md

@@ -10,15 +10,16 @@ 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.5 is an unpublished local candidate that repairs Pi 0.84.2 Summary
-calls by using the active Pi model runtime. The injected Pi AI completion path
-remains the fallback for hosts without that runtime registry. Intended npm
-routing after publication is `next=alpha.5` and `latest=alpha.4`.
+Alpha.6 is an unpublished release candidate. It adds bounded Rarebit fork
+flows, PiQ recovery, machine-only lineage, and Pi-native headroom checks.
+Intended npm routing after publication is `next=alpha.6`; `latest` remains
+`alpha.4`. Published alpha.5 repairs Pi 0.84.2 Summary calls by using the
+active Pi model runtime. Its durable publication evidence is the
+[alpha.5 release receipt](release/v0.1.0-alpha.5-release-receipt.md).
 
 The old alpha.1, alpha.2, and alpha.3 tag graphs remain public and are not
-privacy-clean. Existing alpha.1 through alpha.4 tags, releases, and npm
-artifacts remain immutable. The source-only candidate derivation and
-vendored-scanner binding is
+privacy-clean. Existing package versions, tags, and releases remain immutable.
+The source-only 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.
 
@@ -27,7 +28,7 @@ excluded from npm and does not claim publication completion.
 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.5
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.6
 pi list
 ```
 
@@ -46,7 +47,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.5
+npm install @hypercarrier/rarebit@0.1.0-alpha.6
 npm exec -- rarebit --help
 ```
 
@@ -61,7 +62,29 @@ npm exec -- rarebit extract --session /absolute/path/to/session.jsonl --json
 ```
 
 The Pi extension adds `/rarebit` controls after installation. It has `status`,
-`config`, `auto-title`, `title`, `summarize`, and `recall` subcommands.
+`config`, `auto-title`, `title`, `summarize`, `recall`, and `fork` subcommands.
+
+`/rarebit fork` validates the newest contiguous Rarebit suffix, writes a new
+Session in Pi's Session store for the current working directory, and switches
+to it without starting a model turn. Use `/rarebit fork --max-token-length 64000` to set the
+imported prose budget. Imported messages keep their roles and source outcomes,
+use zero usage, and carry machine-only lineage. The generated opening message
+records source ID/path/leaf, target directory, coverage, and the read-only PiQ
+recovery command. Legacy source entries retain `(sessionId, sourceOrder)` when
+native entry IDs are absent; Rarebit does not migrate those sources.
+
+The CLI performs the same operation without changing the caller's Session:
+
+```sh
+rarebit fork /absolute/source.jsonl
+rarebit fork /absolute/source.jsonl --max-token-length 64000 --no-launch
+```
+
+The first form launches Pi in the invocation working directory. The second
+returns JSON for automation. Fork mode requires an installed Pi coding-agent
+peer; read-only query, extract, and PiQ commands do not. Use `piq entries
+--session <path>` to read omitted native evidence without writing or migrating
+the source.
 
 ## Model setup and optional derivations
 
@@ -130,7 +153,7 @@ 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.5
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.6
 pi remove npm:@hypercarrier/rarebit
 ```
 

package/RUNBOOK.md

@@ -1,8 +1,8 @@
 # Rarebit runbook
 
-This runbook applies to `0.1.0-alpha.5`. This candidate repairs Pi 0.84.2
-Summary calls by using the active Pi model runtime. The injected Pi AI completion
-path remains the fallback for hosts without that runtime registry. See
+This runbook applies to `0.1.0-alpha.6`. This candidate adds bounded fork
+flows, PiQ recovery, machine-only lineage, and Pi-native headroom checks. The
+published alpha.5 release repaired Pi 0.84.2 Summary calls. See
 [CHANGELOG.md](CHANGELOG.md) for release details.
 
 Set `rarebit.model` in global Pi settings or in a trusted Project's
@@ -10,11 +10,11 @@ Set `rarebit.model` in global Pi settings or in a trusted Project's
 and `id`. Rarebit fails closed when it is missing or invalid. It does not use
 Pi's interactive `defaultModel`.
 
-Install or move this package to the alpha.5 pin with
-`pi install npm:@hypercarrier/rarebit@0.1.0-alpha.5`. Pi treats versioned npm
+Install or move this package to the alpha.6 pin with
+`pi install npm:@hypercarrier/rarebit@0.1.0-alpha.6`. Pi treats versioned npm
 sources as pinned, so package update commands skip it. Do not use an unpinned
-source for alpha.5 recovery: unpinned npm resolution follows the retained
-`latest`, which remains alpha.4. Run `pi remove npm:@hypercarrier/rarebit` to
+source for alpha.6 recovery: unpinned npm resolution follows `latest`, which
+remains alpha.4. Run `pi remove npm:@hypercarrier/rarebit` to
 stop loading it. These commands do not modify native Sessions or remove Rarebit
 retained data.
 
@@ -25,6 +25,22 @@ npm exec -- rarebit query --session <exact-session.jsonl> --json
 npm exec -- rarebit extract --session <exact-session.jsonl> --json
 ```
 
+To recover omitted source evidence, use the read-only PiQ binary:
+
+```sh
+node ./bin/piq.mjs entries --session <exact-session.jsonl>
+```
+
+`rarebit fork <source-path>` uses the invocation directory and Pi's normal
+Session store, then launches Pi in the new Session. Add `--no-launch` for JSON
+automation. Fork admission uses the target model's native
+`contextWindow - reserveTokens` threshold plus prompt, tool, and per-message
+rounding overhead. It refuses before switching when the seed lacks headroom.
+The aggregate imported-prose budget remains `ceil(total UTF-16 characters / 4)`.
+Imported entries have fork-time timestamps. Original timestamps and source model
+identity remain in machine-only lineage. Legacy entries without native IDs use
+`(source Session ID, sourceOrder)` and remain unmigrated.
+
 The current protocol reads only `materializations-v4`. A `rarebit_head` is the
 fenced semantic-current pointer. Do not select the physical last JSONL line.
 

package/bin/piq.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { PIQ_CLI_USAGE, parsePiQCliArgs, runPiQCli } from "../src/piq-cli.mjs";
+
+try {
+  const options = parsePiQCliArgs(process.argv.slice(2));
+  if (options.help) process.stdout.write(`${PIQ_CLI_USAGE}\n`);
+  else {
+    const records = await runPiQCli(options);
+    for (const record of records) process.stdout.write(`${JSON.stringify(record)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`${error?.message ?? String(error)}\n${PIQ_CLI_USAGE}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercarrier/rarebit",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "Sparse, provenance-bearing conversational evidence recovery for Pi sessions.",
   "license": "MIT",
   "author": "HyperCarrier contributors",
@@ -24,7 +24,8 @@
   },
   "types": "./src/types.d.ts",
   "bin": {
-    "rarebit": "./bin/rarebit.mjs"
+    "rarebit": "./bin/rarebit.mjs",
+    "piq": "./bin/piq.mjs"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
@@ -34,7 +35,16 @@
     "verify:package": "node scripts/verify-package.mjs"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.83.0"
+    "@earendil-works/pi-ai": ">=0.83.0",
+    "@earendil-works/pi-coding-agent": ">=0.83.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
@@ -67,6 +77,14 @@
       "types": "./src/types.d.ts",
       "import": "./src/rarebit-artifact-state.mjs"
     },
+    "./fork": {
+      "types": "./src/types.d.ts",
+      "import": "./src/rarebit-fork.mjs"
+    },
+    "./fork-lineage": {
+      "types": "./src/types.d.ts",
+      "import": "./src/rarebit-fork-lineage.mjs"
+    },
     "./visual-language": {
       "types": "./src/types.d.ts",
       "import": "./src/rarebit-visual-language.mjs"
@@ -83,6 +101,7 @@
   },
   "files": [
     "bin/rarebit.mjs",
+    "bin/piq.mjs",
     "src",
     "schemas",
     "scripts",