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

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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
+  injected Pi AI completion path remains the Pi 0.83.0 fallback.
+- 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.
+
+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
 
 Alpha.4 is a new artifact with a sanitized current source lineage and unchanged
@@ -7,7 +29,7 @@ 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`.
+npm routing after publication is `next=alpha.4` and `latest=alpha.4`.
 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.

package/README.md

@@ -10,22 +10,25 @@ 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.
+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 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.
 
 ## 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.4
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.6
 pi list
 ```
 
@@ -44,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.4
+npm install @hypercarrier/rarebit@0.1.0-alpha.6
 npm exec -- rarebit --help
 ```
 
@@ -59,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
 
@@ -128,14 +153,14 @@ 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.4
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.6
 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.
+unpinned source for alpha.5 recovery: unpinned npm resolution follows the
+retained `latest`, which remains alpha.4.
 
 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
@@ -144,9 +169,11 @@ only after you review it.
 
 ## Compatibility and support
 
-This alpha supports Node 22+ and Pi 0.83+. It works as a deterministic CLI
-without a model. Summary, Title, and the Pi extension require a compatible Pi
-installation and configured provider credentials.
+This alpha supports Node 22+ and Pi 0.83.0 or later. Its Pi AI peer has no
+upper bound. The release gate runs Recall against Pi 0.83.0 and Pi 0.84.2. It
+works as a deterministic CLI without a model. Summary, Title, and the Pi
+extension require a compatible Pi installation and configured provider
+credentials.
 
 Report security issues privately as described in [SECURITY.md](SECURITY.md).
 Use https://github.com/deephbz/rarebit/issues for normal support. Include no

package/RUNBOOK.md

@@ -1,19 +1,20 @@
 # 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.
+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
 `.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`.
 
-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
+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.4 recovery: unpinned npm resolution follows the retained
-`latest`, which remains alpha.1. 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.
 
@@ -24,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.4",
+  "version": "0.1.0-alpha.6",
   "description": "Sparse, provenance-bearing conversational evidence recovery for Pi sessions.",
   "license": "MIT",
   "author": "HyperCarrier contributors",
@@ -24,18 +24,30 @@
   },
   "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",
     "test:e2e:summary-cache": "node scripts/e2e-summary-cache.mjs",
-    "test:e2e:recall": "node scripts/e2e-recall-pi083.mjs",
+    "test:e2e:recall": "node scripts/e2e-recall-pi0842.mjs",
+    "test:e2e:recall:pi083": "node scripts/e2e-recall-pi083.mjs",
     "verify:package": "node scripts/verify-package.mjs"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*"
+    "@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",
     "ajv": "^6.15.0",
     "typescript": "^5.9.3"
   },
@@ -65,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"
@@ -81,6 +101,7 @@
   },
   "files": [
     "bin/rarebit.mjs",
+    "bin/piq.mjs",
     "src",
     "schemas",
     "scripts",