@hypercarrier/rarebit 0.1.0-alpha.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.0 — 2026-09-27
+
+- Add the `/rarebit` action palette and tabbed `/rarebit settings` editor.
+- Add a configurable `summary_prompt` for Summary format and length. Preserve
+  paragraphs and bullets; reject oversized output instead of silently cutting it.
+- Show the complete Recap in a muted, labelled TUI section. Remove
+  `/rarebit recap expand`.
+- Keep Recap outside Session messages and model context. Typing preserves it;
+  submitted input, new turns, and Session or branch changes clear it.
+- Default Summary diagnostics to off, support host or explicit IANA timezones,
+  and expose the estimated Summary input budget in settings.
+- Include a complete example config in `docs/examples/rarebit.settings.json`.
+
+## 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.
+
 ## 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 +28,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,15 @@ 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`.
+Rarebit is released from an immutable version tag by
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml). The workflow
+runs the package gates, verifies one packed artifact, scans that artifact, and
+publishes it with npm provenance. Install the exact version required by your
+Pi host.
 
 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 +27,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.2.0
 pi list
 ```
 
@@ -46,7 +46,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.2.0
 npm exec -- rarebit --help
 ```
 
@@ -60,14 +60,54 @@ npm exec -- rarebit query --session /absolute/path/to/session.jsonl --json
 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.
+The Pi extension adds one `/rarebit` parent command. In the TUI, the bare
+command opens an action palette. `/rarebit settings` opens a tabbed editor
+with Actions, Summary, Recap, and Session sections. Choose global settings or
+a trusted Project override; each field shows its effective value and source.
+Edits require Save confirmation. Blank input or Remove override restores
+inheritance. Settings apply to future operations; disabling automatic Recap
+also clears its pending or visible widget.
+
+Direct `help`, `status`, `settings`, `config`, `auto-title`, `title`, `recap`,
+`summarize`, `recall`, and `fork` subcommands remain available. Use
+`/rarebit settings global` or `/rarebit settings project` to choose the editing
+scope directly. `recap` reads the current Summary receipt and renders the
+complete multiline Summary in the TUI. It never starts synthesis.
+
+`/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
 
 Summary and Title use a dedicated configured model. They never inherit Pi's
-interactive `defaultModel`. Put this in global Pi settings, or in a trusted
-project's `.pi/settings.json`:
+interactive `defaultModel`. Start with
+[the example config](docs/examples/rarebit.settings.json). Merge its `rarebit`
+object into global Pi settings (`~/.pi/agent/settings.json`, or
+`$PI_CODING_AGENT_DIR/settings.json` when set), or a trusted project's
+`.pi/settings.json`. Preserve other settings and select a model available
+through your authenticated provider. The example includes all Pi extension
+settings with their defaults; its model is an example choice.
+
+The configuration shape is:
 
 ```json
 {
@@ -75,11 +115,48 @@ project's `.pi/settings.json`:
     "model": "provider/model",
     "min_total_length": 80000,
     "max_rarebit_ratio": 0.4,
-    "auto_title": true
+    "auto_title": true,
+    "max_input_tokens": 64000,
+    "summary_prompt": "The summary is free-form prose. State when evidence is uncertain, confusing, contradictory, or importantly missing instead of inventing a coherent account.",
+    "diagnostics": {
+      "summary_triggered": false,
+      "summary_updated": false
+    },
+    "recap": {
+      "enabled": true,
+      "delay_ms": 60000,
+      "timezone": "host"
+    }
   }
 }
 ```
 
+After a successful automatic or explicit Summary materialization, the Pi TUI
+offers the current Summary above the editor after one minute. The offer stays
+visible while you type and clears when Pi sends input, starts a new turn,
+changes Session or branch, or shuts down. Set `rarebit.recap.enabled` to
+`false` to disable the offer, or change `rarebit.recap.delay_ms` to adjust the
+delay. Set `rarebit.recap.timezone` to `host` or an IANA time zone such as
+`Asia/Hong_Kong` to format the Recap header. The header identifies the host
+zone or selected IANA zone and its offset at the observation time. The widget
+reads an existing receipt and never adds a Session message. In the Pi extension,
+`max_input_tokens` limits the Summary prompt by the existing
+`ceil(prompt characters / 4)` estimate. It
+defaults to 64,000 estimated input tokens and is not a provider output limit.
+Summary trigger and update notifications stay off unless
+`rarebit.diagnostics.summary_triggered` or
+`rarebit.diagnostics.summary_updated` is enabled.
+
+`rarebit.summary_prompt` is one scalar guidance string. It uses the default
+guidance shown in the example when omitted. The editor accepts multiline text,
+preserves its line breaks, and trims only outer whitespace. A blank value
+removes the override. The fixed evidence and JSON status contract remains
+owned by Rarebit. Keep custom guidance to a few short bullets so it leaves room
+for evidence in the configured Summary input budget. The editor rejects unsafe
+control characters and guidance longer than 64,000 UTF-16 characters. This
+guidance bound is separate from the 8,000-character Summary output safety
+limit.
+
 Then request explicit model work when you want it:
 
 ```sh
@@ -127,17 +204,16 @@ sensitive. Do not put their paths or content in a ticket.
 
 ## Update, uninstall, and rollback
 
-Pin alpha versions for reproducible installs:
+Pin a version for reproducible installs:
 
 ```sh
-pi install npm:@hypercarrier/rarebit@0.1.0-alpha.5
+pi install npm:@hypercarrier/rarebit@0.2.0
 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.5 recovery: unpinned npm resolution follows the
-retained `latest`, which remains alpha.4.
+that pin. Pi skips versioned npm sources during package updates. Restart Pi
+after installation to load the new extension code.
 
 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
@@ -146,7 +222,7 @@ only after you review it.
 
 ## Compatibility and support
 
-This alpha supports Node 22+ and Pi 0.83.0 or later. Its Pi AI peer has no
+Rarebit 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

package/RUNBOOK.md

@@ -1,20 +1,27 @@
 # 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
-[CHANGELOG.md](CHANGELOG.md) for release details.
+Rarebit release automation lives in
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml). It validates
+an immutable version tag, runs the package gates, verifies one packed artifact,
+and publishes that artifact with npm provenance. See [CHANGELOG.md](CHANGELOG.md)
+for product changes.
 
 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.5 pin with
-`pi install npm:@hypercarrier/rarebit@0.1.0-alpha.5`. 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
+Use `/rarebit settings` to edit the dedicated namespace. `summary_prompt`
+changes the Summary text's format and length; the evidence and structured
+status rules remain fixed. Remove the override to restore the built-in prompt.
+If a response exceeds the 8,000-character safety limit, request a shorter
+Summary in the prompt and run `/rarebit summarize` again. Oversized output
+fails explicitly instead of producing a cut-off Recap.
+
+Install or move this package to an exact version with
+`pi install npm:@hypercarrier/rarebit@<version>`. Pi treats versioned npm
+sources as pinned, so package update commands skip it. Run `pi remove
+npm:@hypercarrier/rarebit` to
 stop loading it. These commands do not modify native Sessions or remove Rarebit
 retained data.
 
@@ -25,6 +32,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/docs/examples/rarebit.settings.json

@@ -0,0 +1,19 @@
+{
+  "rarebit": {
+    "model": "openai-codex/gpt-5.6-luna",
+    "min_total_length": 80000,
+    "max_rarebit_ratio": 0.4,
+    "auto_title": true,
+    "max_input_tokens": 64000,
+    "summary_prompt": "The summary is free-form prose. State when evidence is uncertain, confusing, contradictory, or importantly missing instead of inventing a coherent account.",
+    "diagnostics": {
+      "summary_triggered": false,
+      "summary_updated": false
+    },
+    "recap": {
+      "enabled": true,
+      "delay_ms": 60000,
+      "timezone": "host"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercarrier/rarebit",
-  "version": "0.1.0-alpha.5",
+  "version": "0.2.0",
   "description": "Sparse, provenance-bearing conversational evidence recovery for Pi sessions.",
   "license": "MIT",
   "author": "HyperCarrier contributors",
@@ -24,20 +24,36 @@
   },
   "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:tui": "node scripts/e2e-v020-pi.mjs",
     "test:e2e:summary-cache": "node scripts/e2e-summary-cache.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": ">=0.83.0"
+    "@earendil-works/pi-ai": ">=0.83.0",
+    "@earendil-works/pi-coding-agent": ">=0.83.0",
+    "@earendil-works/pi-tui": ">=0.83.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "0.84.2",
     "ajv": "^6.15.0",
     "typescript": "^5.9.3"
   },
@@ -67,6 +83,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,8 +107,10 @@
   },
   "files": [
     "bin/rarebit.mjs",
+    "bin/piq.mjs",
     "src",
     "schemas",
+    "docs/examples/rarebit.settings.json",
     "scripts",
     "test",
     "README.md",