pi-supernova 0.3.2 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-supernova
 
-**One nova / `supernova({code})` invocation. Four commands inside CodeMode.**
+**One `supernova` invocation. Inline code, a workspace program, or an explicit program batch. Four commands inside CodeMode.**
 
 ```javascript
 const source = await read("validateRefreshToken");
@@ -48,6 +48,8 @@ settings. The runtime does not silently rewrite your tool policy.
 | Function | Examples and behavior |
 | --- | --- |
 | `read` | `read(path, offset?, limit?)`, `read({path,offset,limit})`; one-based line windows |
+| `read` | `return await read("plot.png")`; displays images directly, without a browser |
+| `read` | `read({path,json:".verdict"})`; parse full JSON before bounded field selection |
 | `read` | `read(directory)`, `read("symbol or question")`, `read(path,{about:question})`; questions locate and open source directly |
 | `read` | `read({query,resolve:true})`; structured source and status for a resolve-to-edit handoff |
 | `read` | `read({query,evidence:true})`; ranked evidence with provenance; optional `path` scopes discovery |
@@ -122,16 +124,33 @@ full dataflow tracking or a security sandbox.
 
 Explicit read arrays reject missing/failed paths. For typed partial outcomes use
 `Promise.allSettled(paths.map(path => read(path)))`. Successful arrays remain arrays.
-For embedded source with backslash escapes, use `String.raw` template literals
-(and escape delimiter backticks), or JSON-quoted strings. Validate generated code.
+For literal file content or scripts, prefer the optional tool-level `data` parameter:
+
+```json
+{
+  "code": "await write(data.path,data.content); return await bash({command:\"python3\",args:[data.path]});",
+  "data": {
+    "path": "probe.py",
+    "content": "print(\"literal `backticks` and ${braces}\")\n"
+  }
+}
+```
+
+`data` crosses the worker boundary as JSON, never as JavaScript source. Its
+JSON-encoded length is capped separately at `maxCodeChars`; split larger inputs.
+The binding exists only when supplied, so older programs declaring their own `data`
+remain valid. Syntax errors run no commands and give quoting guidance. For inline
+source, use `String.raw` (escaping backtick delimiters) or JSON-quoted strings.
 
 On hosts exposing `sessionManager.getArtifactsDir()`, bare `agent://<id>` and
 `artifact://<number>` read files from the calling session's artifact directory.
 They preserve ID casing and support offset/limit and structured continuation.
 These resources are read-only; ambiguous artifact IDs and escaping symlinks fail.
-This is not the full OMP URI language: cross-session search, nested path/query
-selectors and other schemes are not implemented. Hosts without an artifact
-directory report that limitation rather than treating the URI as a local path.
+A single `?q=.answer` (URL-encoded when needed) selects JSON from either resource
+using the same bounded projection as `read({path,json})`. The resource must contain
+valid JSON; ordinary Markdown is not parsed heuristically. This is not the full
+OMP URI language: full jq, cross-session search and other schemes are not implemented.
+Hosts without an artifact directory report that limitation rather than treating the URI as a local path.
 
 For unstructured logs/text, `read(path,{about:"STT database"})` returns bounded,
 line-numbered matching windows, or explicitly reports no matching text. It is not
@@ -139,6 +158,67 @@ a complete-file read. Write temporary investigation files under the workspace
 (e.g. `.work/probe.py`): ordinary `write`/`edit` paths cannot escape it, including
 absolute `/tmp` paths. Shell execution is a separate trusted boundary, not a sandbox.
 
+### Reuse a program without resending its source
+
+Save a trusted JavaScript async body or arrow in the workspace, then invoke it:
+
+```json
+{"file":".work/audit.js","data":{"paths":["src/a.js","src/b.js"],"term":"TODO"}}
+```
+
+Supply exactly one of `code` or `file`. File programs get the same four commands,
+optional `data`, limits, deadlines and transaction semantics. Each invocation
+rereads the file and starts a fresh guest; there is no implicit last-program
+state, auto-replay, or retained heap. Paths inside the program still resolve from
+the calling workspace, not the script directory. This runs a Nova program, not
+an arbitrary JavaScript module or a Python/shell script.
+
+Program files must be regular UTF-8 files inside the workspace, including symlink
+targets. Invalid encoding, oversized input and syntax errors fail before commands;
+no truncated prefix is executed. Review untrusted source before running it.
+Use ordinary `edit` to revise saved programs. This is explicit source reuse, not
+conversation compression: prior calls and read results remain intact. Creation
+costs an additional call unless combined with other work, so prefer inline code
+for short one-off operations. See [token measurements](docs/TOKEN_COSTS.md).
+
+### Batch already-known continuations
+
+~~~json
+{
+  "programs": [
+    {"code": "return await edit(data.path,data.oldText,data.newText);", "data": {"path":"src/config.js","oldText":"limit = 8","newText":"limit = 16"}},
+    {"code": "return await bash(\"npm test\");"},
+    {"file": ".work/audit.js", "data": {"paths":["src/config.js"],"term":"limit"}}
+  ],
+  "timeoutMs": 60000
+}
+~~~
+
+Use programs instead of top-level code/file/data. Supply 1--32 entries, each with
+code OR file and optional data; the JSON-encoded array must fit maxCodeChars.
+Entries run sequentially in fresh guests and commit separately. A successful
+entry can create the file executed by a later entry. No implicit retries,
+reordering, shared heap or nested batches are introduced.
+
+The batch stops on the first failed entry, cancellation/deadline, or exhausted
+output/log/image budget. Earlier successful commits remain; only the active
+program's uncommitted writes roll back. Admission errors throw before any program.
+Execution failures return a **typed stop report**, rather than throwing away prior
+results/images: isError and details.ok identify failure, details.programs contains
+every attempted result, and details.attempted/total identifies unstarted work.
+Single code/file invocations retain their existing throwing behavior.
+
+The outer deadline, host-call budget, log allowance, text budget and image limits
+are shared across the batch. Individual read budgets are not reduced. Every
+attempted program's original text is returned in length-delimited blocks; ordinary
+limits still disclose clipping. Images retain program/image labels. Split a plan
+that would exceed the aggregate output budget.
+
+Batch only continuations already chosen by the agent, such as edit then known
+verification, or create then run known audits. Keep a separate call whenever new
+source/results are needed to decide the next action. This does not lower reasoning
+settings, hide observations, or infer a plan on the agent's behalf.
+
 ### Large inputs and report outputs
 
 The default program limit is 48,000 UTF-16 code units (configurable via
@@ -159,17 +239,38 @@ output delivery; progress files survive shell execution but staged VFS writes ma
 roll back.
 
 Large returned objects are bounded previews, not retained artifacts. Select fields
-and array windows before returning, rather than parsing a truncated preview:
+and array windows before returning, rather than parsing a truncated preview.
+
+## JSON reports and targeted text audits
+
+For JSON, select fields inside the read adapter, **before** output budgeting:
 
 ```js
-const report = JSON.parse(await read({path:"report.json",complete:true}));
-return {verdict:report.verdict, values:report.values.slice(5000,5003)};
+const [verdict, values] = await read({path:"report.json",json:[".verdict",".values[5000:5003]"]});
+return {verdict, values};
 ```
 
-If the raw JSON exceeds the read budget, reconstruct exact source windows or run
-a bounded parser through `bash`. There is no implicit continuation handle for
-arbitrary guest objects. For embedded code, JSON-encode the source string once;
-do not nest shell, JavaScript, and Python quoting unless it is necessary.
+Selectors support "." (root), .field, .nested[0], .items[0:10], and .["quoted.key"].
+Use json:true for the complete parsed value. Selectors are not full jq: pipes,
+filters, wildcards and negative indices fail explicitly. Missing keys and indices
+fail; false, zero and null remain values. Slices use an exclusive end and clamp to
+array length. Only own JSON properties are traversed; nothing is evaluated.
+
+Inputs are capped at 16 MiB, including staged files. JSON reads require regular
+files and reject named pipes without waiting for a writer. The entire input must
+be valid JSON before any selection. Each selector is budgeted before allocating
+the next slice; sparse selector/path/edit arrays are rejected. Selected JSON must
+fit the ordinary read budget or the
+read throws; it is never returned as malformed/truncated JSON. Oversized unwindowed
+plain .json reads also fail with a projection hint. Explicit offset/limit or
+resolve:true still allow raw inspection, but line windows are not JSON documents.
+Do not combine json with complete, line windows, or source views. External read
+overrides reject JSON projection rather than silently ignoring the option.
+
+For large Markdown/log path audits, use read(path,{about:"document path"}) or
+explicit offset/limit, not complete:true. Larger JSON needs a streaming parser via
+bash. Arbitrary returned objects still have bounded previews, not implicit
+continuation handles.
 
 ## Execution and automatic batching
 
@@ -191,7 +292,12 @@ File changes are staged until program success. A throw before an external-mutati
 barrier rolls them back. Shell execution flushes preceding changes; external shell
 side effects cannot be rolled back. Stale commits fail explicitly rather than
 silently overwriting successful concurrent changes. This is not a cross-process
-filesystem lock.
+filesystem lock. Outcomes explicitly report committed/rolledBack **file versions**
+(counted per flush/checkpoint, not unique paths) and external-call attempts. A
+successful inner checkpoint merges into the program, not necessarily onto disk.
+Pending commits or failed recovery are reported as uncertain: inspect disk and
+recovery backups before retrying. Import-based mutations and shell side effects
+are outside the VFS counters; this is not a filesystem audit.
 
 `edit(async () => {...})` creates a nested filesystem checkpoint. It returns
 `{ok:true,committed:true,value}` on success or `{ok:false,committed:false,error}` on
@@ -212,6 +318,10 @@ outside the active callback are rejected. Await the checkpoint before proceeding
   strings and result types are unchanged. This is output framing, not source
   compression. It is chosen only when shorter in characters than escaped output;
   it does not guarantee lower billed tokens for every tokenizer or input.
+  Nested multiline strings use the same approach: the complete value structure
+  references `raw[n]`, followed by length-delimited verbatim string blocks. Literal
+  `"raw[0]"` values stay quoted; duplicate source is never deduplicated. Small values
+  keep their existing format. Machine-facing result values are unchanged.
 - Intermediate values stay inside CodeMode unless returned or logged. Final text,
   errors and logs are bounded with explicit truncation. Details support rendering;
   they are not a second model-facing transcript.
@@ -220,6 +330,12 @@ outside the active callback are rejected. Await the checkpoint before proceeding
 
 Default limits are in `src/config/config.default.json`. Configuration loads from
 `~/.pi/agent/supernova.json`, the configured host directory, or `PI_SUPERNOVA_CONFIG`.
+
+Citation elision is **disabled by default** (`seenWindow: 0`): each result remains
+self-contained within the normal output budgets. A positive `seenWindow` explicitly
+opts into an experimental ledger with known retention gaps: hidden message details,
+later context transforms and missing citation targets can invalidate its assumptions.
+It is not a proven lossless optimization and is not recommended for production.
 Text limits are character budgets, not tokenizer counts. `/supernova` reports
 programs and output characters without labelling characters as tokens.
 
@@ -259,7 +375,9 @@ privileges. Do not run untrusted programs as though these adapters isolate them.
 Pi preflights the outer `supernova` call. Internal primitives do not emit ordinary
 native `tool_call` events, so third-party guards that only recognize top-level
 `edit` or `bash` need CodeMode-aware handling. Configured exclusions and supported
-host-session execution safeguards remain enforced. Actual-host smoke checks are
+host-session execution safeguards remain enforced. Guards inspecting code/file
+inputs must also understand the programs array; its entries do not emit separate
+top-level tool_call events. Actual-host smoke checks are
 not a claim that every third-party permission extension has been validated.
 
 ## Development and evidence
@@ -284,6 +402,7 @@ arbitrary wall-clock assertions.
 npm test --prefix packages/pi-supernova
 npm run lint:supernova
 npm run measure --prefix packages/pi-supernova
+npm run test:tokens --prefix packages/pi-supernova
 
 PI_SUPERNOVA_PI_ROOT=/path/to/pi-coding-agent \
 PI_SUPERNOVA_OMP=/path/to/omp \

package/docs/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.4.0] - 2026-09-10
+
+- Disable citation elision by default (`seenWindow: 0`), including direct bridge/ledger defaults. A failure-first integration regression preserves complete results across hidden, reordered and removed context. Positive windows remain an explicit research opt-in, not a validated retention guarantee. The historical ledger measurements below describe that experimental mode only.
+
+- Make the traffic gate able to see the retention ledger, and prove it can. The gate previously ran only a host that emits no lifecycle events, so it measured the conservative floor and could not observe the largest token lever in the package. It now also runs the frozen schedule against a production-shaped host that fires `context` before each request, comparing like for like against the unbatched baseline, and gates three things: an unobserved ceiling recorded after this pass, a floor requiring the observing host to beat the same schedule, and an anti-vacuity check requiring the fidelity assertion to have had a subject. Fidelity in that arm is asserted as elision-only rather than byte-equality: every surviving line must match in order and every citation must cover a run of exactly the lines it replaced.
+- Add self-tests for the elision checker itself. A checker that cannot reject anything makes every gate that relies on it vacuous; seven failure-first cases (a vanished line, an overstated or understated citation, a sub-run citation, an invented line, a reordered elision) fail if the checker is weakened or reports that it saw nothing.
+- Fix an information-loss bug the retention proof exposes: a program inside a `programs` batch could cite a peer in the same batch, whose result the model had not received yet. Nothing in a batch is collapsible against its own batch, and a regression now holds that line. The pre-existing frozen output assertion already caught this; it now has a named test.
+- Record the observed-arm ceiling in `token-baseline.json` with provenance. The frozen workload is effectively read-once, so the ledger's saving on it is 0.77%/0.85%; repeat-heavy sessions measure 43.6% and are guarded by `tests/fidelity/ledger-retention.test.mjs`.
+- Experimental only: retain the seen-ledger observation mechanism for research. Its earlier "retention proof" claim was invalid: metadata is not necessarily model-visible, context handlers can transform later, and a missing citation target is not rehydrated. The extension now subscribes to Pi's `context` hook and collapses a run only when those exact lines were observed in the messages about to be sent. The blanket `seenWindow: 0` existed because local cache residency cannot establish model-context residency; the pre-conversion host observation does not establish final-payload residency. Future collapse stops when lines disappear from the observation, but existing citations can still be dangling; a citation is never evidence of its own contents, and citations never nest. Observation costs ~1.7 ms per request on a 0.87 MB payload. On a 12-call repeated-read session: 42.8% fewer published result characters and 31.0% less cumulative replay. Changed lines are still never collapsed, explicit offset/limit reads stay pinned, and a host that never fires `context` publishes byte-identical results, so the frozen `events` and the batched arm of the gate are untouched; only a new observed-arm ceiling was added to the baseline.
+- Consolidate overlapping tests into multi-operation failure-and-repair contracts covering JSON, saved programs, checkpoints, literal argv, images and concurrent workspaces. Retain distinct admission, isolation and resource-limit regressions.
+- Fix truncation reporting for complete tool responses, including logs and wrapper metadata; make log-limit omissions visible in model-facing output.
+- Remove duplicate startup guidance and batch wrapper metadata while retaining every original per-program result. The unchanged six-call benchmark uses another 5.15%/5.17% fewer tokens than d444eb7; add a request-hash guard against moving model decision boundaries.
+
+- Add explicit sequential `programs` batches with fresh guests and separate commits. Preserve complete per-program text and earlier images in typed stop reports; share deadlines, host calls, logs and outer output/image limits. Reject malformed/nested/oversized plans before execution.
+- Make the additional 40% token gate part of `npm test`, with a frozen post-previous-pass baseline, exact logical-result checks, both tokenizers, full tool-history replay and the final answer handoff. Measured 56.19%/56.26% fewer modeled tool tokens for the fixed workload; retain the full startup reference. No provider billing or model-quality claim.
+
+- Add explicit workspace program-file input as an alternative to inline code, with fresh loading/guests, strict bounded UTF-8 admission and unchanged deadlines/transactions. No implicit replay or persistent heap.
+- Extend verbatim string framing to nested source results, preserving all fields, types, duplicate strings and lengths; retain compact scalar output. Remove redundant guidance already present in parameter/command descriptions.
+- Add reproducible two-tokenizer measurements and package comparisons in `TOKEN_COSTS.md`, including creation/definition overhead and explicit no-claim boundaries for billing and end-to-end quality.
+
+- Stress follow-up: budget each JSON selector before allocating the next slice, reject non-regular JSON inputs without blocking on FIFO open, and reject sparse selector/path/edit arrays. Add a heap-limited host-survival regression, exact input boundaries, concurrent queried-resource isolation, and failed-recovery backup verification. The mixed stress lane now exercises literal input data and JSON projection.
+
+- Add literal tool-level `data` input for Markdown/scripts/argv without nested JavaScript quoting; parse failures explicitly state no commands ran.
+- Parse full JSON before bounded field/index/slice projection with `read({path,json})`, including session `?q=.answer` resources. Reject invalid selectors, missing fields, oversized inputs/selections and incompatible read options. Oversized unwindowed plain JSON reads fail with actionable guidance.
+- Validate edit overloads before dispatch and show supported signatures, without touching a file on invalid input.
+- Report committed/rolledBack file versions and external-call attempts on failure, and distinguish uncertain commit recovery from complete rollback.
+- Advertise direct image viewing and targeted large-text reads in model-facing guidance. Add Spark papercut regressions through the registered tool and real worker.
+
 ## [0.3.2] - 2026-09-07
 
 - Focus `read(path,{about})` on matching line windows in unstructured logs/text instead of returning a truncated unrelated prefix; report no matches explicitly.

package/docs/TOKEN_COSTS.md

@@ -0,0 +1,171 @@
+# Token usage and benchmarks
+
+Supernova reduces repeated tool traffic through explicit program reuse and batching.
+It can also reduce escaping in nested multiline results with lossless text framing.
+These mechanisms do not summarize results, rewrite conversation history, or change
+reasoning settings. Savings depend on the workload.
+
+See the [API guide](../README.md) for program-file and batch usage.
+
+## Reproduce
+
+From a repository checkout with development dependencies installed:
+
+~~~sh
+npm run test:tokens --prefix packages/pi-supernova
+npm test --prefix packages/pi-supernova
+~~~
+
+The benchmark uses js-tiktoken 1.0.21, pinned as a development dependency. It runs
+real Supernova programs in temporary workspaces without provider calls or downloads.
+The token regression gate also runs in the normal test suite.
+
+## Workload
+
+The baseline is a frozen, non-batched implementation snapshot with program-file
+reuse and nested source framing already enabled. It is not a comparison against
+a separately published release.
+
+| Scenario | Baseline calls | Batched calls |
+| --- | ---: | ---: |
+| Inspect source, reproduce a failure, repair and verify | 4 | 3 |
+| Inspect, update and verify a JSON report | 3 | 2 |
+| Create an audit program and run it for five search terms | 6 | 1 |
+| **Total** | **13** | **6** |
+
+Both executions perform the same 13 logical programs. The batch schedule is
+hand-authored: it groups known edit-then-verify and create-then-audit continuations,
+while keeping decision points after inspection and the failing check separate.
+No model chooses the schedule during this test. The runtime does not infer plans
+or contain benchmark-specific paths, search terms, or expected results.
+
+This workload deliberately includes repeated audits that benefit from batching.
+It is a reproducible regression fixture, not a representative sample of all agent
+tasks or a guarantee of savings when a model decides how to use the tool.
+
+## Accounting
+
+For each model request, the benchmark counts:
+
+- The serialized Supernova definition: description, parameters and prompt guidance.
+- All preceding tool arguments and complete result text in the request history.
+- Newly generated tool arguments, serialized as JSON.
+
+It also counts the definition and full tool history sent for the final answer
+request. A newly produced tool result is counted when the next model request
+consumes it, not twice. Program creation is included. The complete startup
+reference is retained, so this workload needs no separate discovery call.
+
+Formally, with definition cost D, generated argument cost A_i, result cost R_i,
+and prior tool-history cost H_i = sum(A_j + R_j) for j < i:
+
+~~~text
+Total = sum(D + A_i + H_i, i = 1..N) + D + H_(N+1)
+~~~
+
+This assumes full tool-history replay. The JSON report includes per-scenario
+breakdowns. Its results field records newly produced text for inspection; that
+text contributes to totals through later history, not as a second charge.
+
+## Measured results
+
+Observed on macOS with Node v26.7.0 and Linux aarch64 with Node v24.16.0; both
+produced the same token counts.
+
+| Tokenizer | Non-batched baseline | Batched baseline (d444eb7) | Current | Further reduction | Total reduction |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| o200k_base | 40,129 | 18,535 | 17,581 | **5.15%** | **56.19%** |
+| cl100k_base | 39,697 | 18,310 | 17,363 | **5.17%** | **56.26%** |
+
+The gate requires at least 40% reduction on **each tokenizer for the complete
+workload**, not for every scenario individually. Token counts and reductions are
+computed from the recorded baseline and fresh execution results, not constants
+returned by the runtime. A second gate requires another 5% against the measured
+batched baseline from commit d444eb7. Its six-call argument hash is pinned as well
+as the original workload: removing a decision boundary cannot satisfy this gate.
+
+### What changed after the batched baseline
+
+The serialized definition falls from 1,068 to 947 tokens with o200k_base and from
+1,057 to 937 with cl100k_base. Repeated guidance now has one model-visible home;
+the command reference, safety rules and schema constraints remain available.
+Batch framing declares UTF-16 length units once instead of on every entry and
+omits redundant aggregate mutation totals from the wrapper. Every original
+per-program result, including its mutation report, remains intact. Structured
+aggregate counters are unchanged. No source text or independent result is removed.
+
+For the fixed six-call schedule, the accounting can also be written as:
+
+~~~text
+Total = (N+1)*D + sum((N-i+2)*A_i + (N-i+1)*R_i, i = 1..N)
+~~~
+
+Seven definition appearances save 7*121 = 847 tokens with o200k_base. The smaller
+batch wrappers save another 107 after history replay, for 954/18,535 = 5.15%.
+For cl100k_base the corresponding saving is 7*120 + 107 = 947 tokens. The logical
+programs, their arguments, complete results and decision boundaries are unchanged.
+
+There are still costs: the current definition exceeds the non-batched baseline
+by 39/36 tokens per request, and batching adds result framing. One-off calls should
+not be assumed to benefit from the batch API.
+
+The report also includes separate source-framing and argument-reuse comparisons.
+Those component measurements are not total-session savings, and the reported
+argument-only break-even excludes other request costs. Text framing is selected
+by character length, not a runtime tokenizer; it need not reduce tokens for every
+input or encoding.
+
+## Benchmark integrity
+
+The [baseline fixture](../tests/efficiency/token-baseline.json) contains the source
+inputs, definition, workload hash, arguments and complete outputs. The
+[runner](../tests/efficiency/workflow.mjs) executes the registered tool with real
+workers and filesystem operations. It checks that:
+
+- The workload hash matches the frozen baseline, and the six-call argument hash
+  matches the prior batched execution.
+- Every original argument, complete logical result and expected failure matches.
+- Batched output contains every original result, with no unaccounted outer text.
+- No result is truncated, and final repaired source and JSON contents match.
+
+Only run IDs, elapsed times and temporary workspace prefixes in write receipts
+are normalized. Batch framing lengths are adjusted to match that normalized text.
+The workload, batch schedule, recorded comparison totals and acceptance thresholds
+are fixed test inputs, not production execution rules. The baseline is not regenerated by the benchmark.
+
+Recorded baseline SHA-256:
+
+~~~text
+79a819eca82c8a5ff381e96b7669d8a5bf04fabbc8c10cf02f3a7c8817171b62
+~~~
+
+## Limitations
+
+- These are local estimates of model tool-token traffic, not provider billing.
+  Provider-specific envelopes, unrelated user/system messages, reasoning tokens,
+  image token costs and cache discounts are excluded.
+- There is no live-model A/B quality evaluation. Preserving observations and
+  reasoning settings does not establish unchanged end-to-end task quality.
+- Batching is appropriate only for already-chosen continuations. Actions requiring
+  a new model decision must remain separate calls.
+- Existing read, output, log, image and execution limits still apply. The
+  benchmark does not obtain savings by lowering them or hiding truncation.
+
+## Design references
+
+These sources informed the implementation choices; the measurements above compare
+Supernova implementations only, not the performance of these packages.
+
+| Reference | Mechanisms studied |
+| --- | --- |
+| [pi-codex-conversion 3.0.31](https://github.com/IgorWarzocha/howaboua-pi-stuff/tree/94eb6c0745e2f516bf19603f912f7b6478b43355) | Code transport, concise signatures and deferred discovery |
+| [pi-codemcp](https://github.com/yolonir/pi-codemcp) | Saved call chains and intermediate results |
+| [Ian Pascoe's pi-codemode](https://github.com/ian-pascoe/pi-extensions/tree/main/packages/pi-codemode) | Notebook state and tool declarations |
+| [Nick Nisi's codemode](https://github.com/nicknisi/pi-extensions/tree/main/packages/codemode) | Named snippets and explicit composition |
+| [Boozedog's pi-codemode 0.3.0](https://github.com/boozedog/pi-codemode/tree/1390c938ef4f23a0d50b814e7e3a14c03a08d39d) | Literal inputs and typed CLI capabilities |
+| [pi-cache-optimizer 2.8.2](https://github.com/jiangge/pi-cache-optimizer) | Cache-prefix and prompt handling |
+
+Unpinned repository links refer to inspected source, not independently verified
+package versions. Supernova retains fresh guests, explicit transaction boundaries
+and its general command surface rather than adopting persistent notebook state,
+restricted CLI catalogs or provider/history rewriting.