@visual-z/xeno 0.1.0

package/README.md

@@ -0,0 +1,498 @@
+# xeno
+
+A segmented append-only agent log with **pure** context and handoff projections.
+
+The log is the truth. What the model sees is a recomputable projection of it. Nothing
+is ever summarized by a model, and nothing is ever rewritten in place.
+
+```
+.xeno/sessions/<id>/node-0007.jsonl    append-only events, references only
+        |
+        |  deriveHandoff()      pure, zero LLM calls
+        v
+.xeno/sessions/<id>/handoff-0007.yaml  structured state: verified completions,
+        |                              decisions, pitfalls, file digests, gate status
+        |  projectContext()     pure
+        v
+messages[]                             frozen system prefix + handoff + this node's events
+```
+
+Version **0.1.0**. The on-disk session format will still change; `0.x` is that
+statement. Published as `@visual-z/xeno`; the license is `UNLICENSED` (readable and installable, no reuse granted).
+
+## Install
+
+Bun is required. This tree was run on Bun 1.3.10. Node has not been tried.
+
+```bash
+npm i -g @visual-z/xeno    # or: bun add -g @visual-z/xeno
+xeno --help
+```
+
+From a checkout instead:
+
+```bash
+git clone <this-repo> xeno
+cd xeno
+bun install
+bun src/apps/cli.ts --help
+# or: bun link   then, anywhere: xeno --help
+```
+
+Full steps, credential variables, and what `.xeno/` writes: [`docs/install.md`](docs/install.md).
+
+Validation commands and current evidence are recorded in
+[`docs/research/harness-practice-rollout-2026-09-23.md`](docs/research/harness-practice-rollout-2026-09-23.md).
+
+## Harness capabilities
+
+- One live execution per session, with cancellation, draining, and explicit completion/stop/failure outcomes.
+- Stable work IDs with explicit unblock, reopen, and cancel operations. Verified completion still requires fresh executed evidence.
+- Shared schema validation and structured tool feedback. Reads return file versions; edits support an expected version and return a diff.
+- Writing branches start from the parent's working copy, including uncommitted files, in an isolated Git worktree. Adopt continues that checkout.
+- Independent readers and read-only branches run in a bounded window; writes and state changes are barriers. Results remain in request order.
+- `note(kind="pin", work_id, event, what)` links original observations; `supersedes` replaces an earlier reference. `history(work_id=...)`, `history(resource=...)`, and `history(events=[...])` locate or batch-read the originals.
+
+Use `/new` or `--fresh` to start with the current tool protocol. Existing sessions
+keep their saved frozen schemas and concurrency policy. New sessions default to
+three concurrent readers; programmatic callers can set `SessionConfig.maxParallelTools`.
+This setting is not a CLI flag. Evidence freshness reflects the last logged observation.
+
+The public-data evaluation protocol, architectural hypotheses, and measured
+results are in [`docs/benchmarks.md`](docs/benchmarks.md). The LongBench v2 pilot
+compares segmentation, full history, and observation masking with the same model;
+its tool-based input protocol is explicitly separate from the official leaderboard.
+The follow-up trial compares the enhanced working-state protocol and computation
+tools with a control on six previously unused questions. Real process-kill recovery
+checks are reported separately from model accuracy.
+The explicit-policy follow-up separates segmented, continuous and adaptive context
+views. Its budget-limited result and negative cases are recorded in the same report;
+neither segmentation nor the experimental adaptive rule has established a quality advantage.
+`bun run scripts/compare-harness.ts smoke --output /absolute/new/smoke-directory`
+also exercises xeno-windowed, xeno-continuous and an installed Pi CLI with shared
+confined tools, without paid model calls. Pi runs on Node through an isolated local
+tool bridge; no Pi SDK is added to the project. Its `plan` / `run` protocol freezes
+source, model, task order and spending policy, including summary calls. An explicitly
+authorized `--budget unlimited` on both `plan` and `run` records costs without a local
+dollar ceiling; upstream errors stop the trial, with HTTP 402 marked as awaiting top-up.
+This checks a controlled configuration, not stock Pi or an official leaderboard.
+
+## Usage
+
+```
+xeno [-m <model>] [--provider <name>] [--api-key <key>]
+     [-w <workspace>] [--log <dir>] [--max-turns N]
+     [--trigger N --hard N] [--list-models] [--fresh]
+     [models --refresh]
+     [--system-prompt <text-or-file>] [--append-system-prompt <text>]
+     [--no-context-files|-nc]
+     [--tools names] [--exclude-tools names] [--no-tools]
+     [--allow-tools names] [--approve|--no-approve]
+     [--theme <name|path>]
+     [--skill <path>] [--no-skills]
+     [--prompt-template <path>] [--no-prompt-templates]
+     [-p <prompt>] [prompt...]
+```
+
+- No prompt, a tty: interactive session.
+- A prompt, or `-p` / `--print`: one shot, then exit. `-p` puts only the
+  assistant's final text on stdout; the banner, usage, thinking, and tool
+  lines go to stderr. Piped stdin is appended after the command-line prompt.
+- A workspace that already holds a session is resumed. `--fresh` opens a
+  second session beside it. Nothing is deleted.
+- A leftover `.xeno/log` is not migrated; continue it with `--log .xeno/log`.
+
+Slash commands that exist in the session (from `/help`):
+
+```
+/model [id]        search models, or switch (cuts a node)
+/models refresh    fetch models.dev into ~/.xeno/models.json
+/login [provider]  choose a login method, or store an API key
+/login claude-pro|codex|github-copilot
+                   subscription login (first-party client credentials)
+/logout [provider] remove a stored credential
+/new               start a new session beside this one
+/resume [id]       search sessions, or switch to one
+/name <name>       name this session
+/session           id, path, events, usage
+/back [n [files|context]] [confirm]
+/tree              search the session tree; navigate context at an exchange boundary
+/fork [n]          choose an exchange to copy into a new session
+/clone             copy the active branch into a new session
+/trust [here|parent|never]
+/settings [key v]  theme, thinking, statusBar
+/hotkeys           bindings in effect
+/usage  /state  /help  /quit
+```
+
+Type `/` for commands, templates and skills. The editor completes command
+arguments and paths. `@file` or `@"file name"` attaches a project file anywhere
+outside code literals; choosing a file keeps the prompt in the editor.
+At line start, `!cmd` runs in the workspace and sends stdout/stderr/exit to the model; `!!cmd` runs without
+sending output. During a turn, Enter queues steering (delivered after the
+current tools finish); Alt+Enter queues a follow-up for after the turn.
+Escape interrupts; pressing Escape twice on an empty idle editor opens the tree.
+Ctrl+C clears the draft, then a quick second press exits; Ctrl+D exits an empty
+editor. Ctrl+O and Ctrl+T toggle tools and thinking throughout the history.
+
+`xeno --list-models` prints the built-in catalog (12 providers, 23 models)
+and whether a credential resolved. `xeno models --refresh` writes
+`~/.xeno/models.json`; startup never fetches.
+
+## Credentials
+
+Order: `--api-key`, then `~/.xeno/auth.json`, then the provider's environment
+variable. A stored entry owns that provider — the environment is not consulted
+after a stored value fails.
+
+Interactive sessions can start with no key and wait for `/login`. `-p` and
+non-tty runs exit 1 and name `--api-key` or the variable; they do not mention
+`/login`.
+
+Keys in `auth.json` may be a literal, `!cmd`, or `$VAR`. The file is written
+mode `0600`.
+
+## Isolation
+
+This is not a sandbox. Tools run with the permissions of the user who
+started xeno. `read` / `write` / `edit` stay inside the workspace root;
+`bash` does not — it asks before it runs so you can see the command. That
+ask is the last look at what is about to happen, **not a security
+boundary**.
+
+For untrusted repositories, generated code you do not intend to watch, or
+unattended automation, run xeno inside a container (or a VM) that holds
+only the files and credentials the task needs.
+
+Project trust (`/trust`, `--approve`) only decides whether to load
+`.xeno/settings.json` (and project-level skills, prompts, and UI files).
+It does not change what tools can do. `AGENTS.md` is loaded whether the
+project is trusted or not.
+
+`--tools` / `--exclude-tools` / `--no-tools` remove tools from the schema
+the model sees. `--allow-tools bash` lets bash run without asking, which
+is what a CI job that has no tty has to pass explicitly. Without a tty,
+an `ask` is a deny that names that flag.
+
+## Workspace data
+
+A session writes into the workspace:
+
+| Path | |
+|---|---|
+| `.xeno/sessions/<id>/` | node logs, handoffs, metadata journal, derived manifest, and observation artifacts |
+| `.xeno/blobs/` | content-addressed file snapshots used by `/back` |
+
+That tree grows with every turn and every snapshot. There is no garbage
+collection yet. Dead branches from `/back` stay on disk.
+
+`/fork` and `/clone` copy the log graph and observation artifacts, then select an
+independent cursor. Historical nodes remain intact; a fork point limits the active
+context. Workspace snapshot blobs remain shared under `.xeno/blobs/`.
+
+Ignore it in the project:
+
+```
+.xeno/
+```
+
+Config and secrets live under `~/.xeno/` (or `$XENO_CONFIG_DIR`), not in
+the workspace: `auth.json`, `settings.json`, `trust.json`, optional
+`models.json` / `keybindings.json` / `prompts/` / `skills/`.
+
+## What this does
+
+Shipped, not planned:
+
+- An agent loop with tools `read`, `write`, `edit`, `bash`, `note`,
+  `branch`, `resolve`, `grep`, `find`, `ls`, `history`, `query`. `grep` / `find` use `rg` /
+  `fd` when those binaries are on `PATH`, otherwise a TypeScript walk;
+  both paths share one output format. They do not follow symlinks out of
+  the workspace.
+- `history` searches the active ancestry, retrieves original events, and pages
+  immutable full observations. `query` filters and computes aggregates over
+  complete CSV, JSON, JSONL or text files, with source hashes. It evaluates a
+  finite query language, not generated code; resource-limit errors reject the
+  entire calculation instead of returning partial totals.
+  Missing JSON pointers identify the failed level and available keys without
+  copying source values. Writing branches inherit the same evidence tools,
+  subject to the parent's tool restrictions.
+- Durable working-state guidance is appended when the next step is missing,
+  an action/observation cycle repeats, or the request budget is nearly exhausted.
+  Existing messages, the system prefix, and tool definitions stay frozen. Model
+  notes remain annotations and cannot manufacture verified completion.
+- Two wire adapters (`anthropic-messages`, `openai-completions`). Both
+  stream; deltas are UI events and are not written to the log.
+- A built-in catalog of **12** API-key providers and **23** models
+  (anthropic, openai, google, deepseek, xai, groq, cerebras, mistral,
+  openrouter, zai, moonshotai, together). `~/.xeno/models.json` overrides
+  by id. Startup does not hit the network.
+- Sessions, resume, `/new` / `/resume` / `/name` / `/session`, `/back`
+  (files, context, or both), `/tree`, read-only `branch` / `resolve`, and
+  write branches in their own git worktree.
+- Progress tracking counts new read observations and fresh successful checks.
+  Repeated content, renamed completion claims and gate regressions do not reset
+  the three-segment stop rule. This is an anti-stall heuristic, not proof of
+  relevance or completion; [`research M.4`](docs/agent-harness-research.md) states its limits.
+- A terminal UI using the pinned Pi renderer, raw input, editor, autocomplete,
+  Markdown, searchable pickers and settings. Durable history is a pure log
+  projection across handoff boundaries. Includes tool diffs, historical folds,
+  Pi dark/light palettes, `keybindings.json`, `/settings` and `/hotkeys`.
+- Context files: `AGENTS.md` / `CLAUDE.md` and the override chain, plus
+  `--system-prompt` / `--append-system-prompt` / `-nc`.
+- Skills (`~/.xeno/skills/`, `/skill:name`) and prompt templates
+  (`~/.xeno/prompts/`, `/name`). Untrusted projects do not load the
+  project-level copies.
+- `/login` for API keys and for Claude Pro/Max, Codex, and GitHub
+  Copilot subscription flows. See Known gaps.
+
+## Known gaps
+
+- **No sandbox.** See Isolation. That is a decision, not a missing feature.
+- **Token counts are an estimate** (`chars/3.6`, labelled `kind: "estimate"`).
+  The provider `count_tokens` API is not wired. Boundaries therefore fire
+  on an approximation.
+- **OAuth has not been run against a live authorization or token endpoint.**
+  The three flows exist and pass tests against an injected transport.
+- **Tiered provider prices are stored as the base rate.** Example: the
+  catalog comment on `gpt-5.5-pro` notes a `context_over_200k` tier that
+  is not applied. `/usage` reports `{kind:"partial"}` when cache prices
+  are missing; it does not treat a missing cache price as zero.
+- **No packages or extensions.** Skills and templates are files on disk.
+  There is no installer.
+- **Bun only.** Node has not been tested.
+- **`/back` does not restore symlinks.**
+- **`.xeno/` is not collected.** Snapshots and abandoned session branches
+  stay until you delete them.
+- **No telemetry, `/share`, auto-update, or `/compact`.** Those are
+  refusals (`docs/PI_PARITY.md` D15, D16), not backlog.
+
+`docs/TUI_ARCHITECTURE.md` describes the active interaction path and verification.
+`docs/PI_PARITY.md` records deliberate differences and remaining Pi features.
+Pi's editor supports undo, not redo; an old `editor.redo` binding is diagnosed
+as unsupported rather than silently accepted. Ctrl+- and the existing Ctrl+Z
+alias invoke Pi undo.
+
+## Why this shape
+
+Three constraints, each of which rules out the obvious alternative.
+
+**In-place eviction is the worst option under prefix caching.** Releasing tokens from
+the middle of the context changes the prompt prefix, which invalidates the cached KV
+state for everything after it. Under sustained pressure you pay the cache-write cost on
+every request and never amortize it through reads — worse than compaction, which at
+least produces one stable prefix per pass (this is the failure mode
+[Beyond Compaction](https://arxiv.org/abs/2606.11213) documents). So token release must
+be a rare, coarse event, not a continuous process. Hence segments.
+
+**Summarization is unpredictably lossy, and the loss is undetectable from the result.**
+What a summarizer keeps depends on its judgment of salience at that moment, which need
+not match what the next segment needs — and you cannot tell from the compacted context
+that anything is missing. Worse, the thing summarizers reliably drop is the record of
+failed attempts, so the agent repeats them. Hence a deterministic projection plus a log
+that is still on disk: a handoff that omits something is recoverable, because the agent
+can go read it.
+
+**A handoff that is only prose is autocompact with extra steps.** If the receiving agent
+cannot interrogate what was compressed away, the structure bought nothing. The log
+being intact is what makes the difference real rather than rhetorical.
+
+## What is actually enforced
+
+The interesting part is not the field list. It is that the harness — the only layer that
+sees prompt assembly, tool mediation and lifecycle events together — can enforce a
+contract the prompt cannot.
+
+**A completion claim must cite a log event that exited zero.** The model calls a claim
+tool naming a gate; `deriveHandoff` resolves that citation against command exit codes
+recorded in the log. Unresolvable claims land in `state.unverified_claims` with a
+reason. They are neither accepted nor silently dropped, and the rendered prompt says
+they must be treated as not done.
+
+This directly targets the "migration applied successfully" failure: a tool call returned
+a nonzero exit code, nothing in the loop read it, and the model wrote a confident summary
+of a result it never saw. Here the model's account of a result carries no weight at all.
+
+Two related rules:
+
+- **Claims resolve against evidence at or before the claim.** A later failing run does
+  not erase the recorded successful execution — appending an event must never
+  rewrite that observation. That the gate is red *now* is separate
+  information, carried by `verification` and repeated inline as `evidence_superseded`
+  so a reader of `completed` cannot miss it.
+- **Evidence must come from the same segment.** A gate that passed three segments ago
+  is not proof about code that has changed since.
+
+Other invariants (`src/core/handoff.ts`, `validateHandoff`): a `pass` status requires a
+zero exit; every file anchor carries a digest; every handoff identifies its source
+node and digest; a continuation is valid only with both remaining work and a concrete next
+action. A property test asserts that `deriveHandoff` can never produce a handoff that
+violates any of them.
+
+**Append references, never copies.** A boundary event stores the id of the handoff it
+produced and a ref to its predecessor — never the history it replaces. Codex CLI
+re-embeds the full prior history into its rollout JSONL on every compaction, which is
+quadratic on disk and has been reported at 42 GB
+([openai/codex#41806](https://github.com/openai/codex/issues/41806)). The types here
+cannot express recursive history copies. Full structured state can still grow as
+new requirements, decisions and files accumulate. Handoff v2 carries a bounded
+suffix of each section and records its immutable source and exact ranges. The
+`history` tool rebuilds omitted pages from the log; no model summary is involved.
+
+The carried-state budget is 5,000 estimated tokens. A 100-node deterministic
+measurement grows the full state to about 14.7k while the carried view remains
+at or below 5k. This bounds the prompt payload; it does not claim constant disk
+space, replay time, or working memory for reconstructing the full history. The
+objective stays verbatim: an objective that cannot fit is refused explicitly.
+
+Session moves are committed to `metadata.jsonl`; `manifest.json` is a replaceable
+index rebuilt from it. Sealed node digests are checked on resume and restore.
+Interrupted tools receive an explicit unknown outcome instead of being run again.
+Tool previews that exceed their display budget include a content-addressed
+reference to the complete observation.
+
+Command evidence includes the observed workspace digest when scanning succeeds.
+Later edits mark old verification and completions as stale. A zero exit proves
+the recorded command succeeded; it does not prove the model's description is an
+adequate specification or that the test suite covers every requirement.
+
+## Segment length
+
+New sessions default to **windowed replay**: preserve the active dialogue until model
+window pressure calls for a new projection. With an explicit model window, reserve
+the configured output tokens, prepare at 70% of the remaining capacity and cut at
+80%. These are conservative hypotheses, not measured optima. Unknown model capacity
+uses the fixed segmented policy below; it is never treated as unlimited.
+
+The explicit segmented policy retains **30k trigger / 40k hard**. Its historical cost model
+
+```
+per_turn(L) = 0.05*(H+L) + 1.25*d + 1.25*(H+R)*d/(L-H)
+```
+
+(cache reads at 0.1x, writes at 1.25x; `H` = handoff size, `d` = per-turn growth,
+`R` = re-read cost after a boundary) was first evaluated with `H` *assumed* to be ~10k,
+which put the optimum near 37k. The original single-segment measurement
+(`prev=null`) gave the following historical figures:
+
+| turns | segment L | handoff H | H/L |
+|------:|----------:|----------:|----:|
+| 10 | 4.8k | 366 | 7.6% |
+| 50 | 25k | 986 | 3.9% |
+| 200 | 99k | 2218 | 2.2% |
+| 400 | 203k | 3201 | 1.6% |
+
+Those samples do not establish a bound over a continuous session: deduplication
+does not remove new, distinct facts. `bun run measure` now reports both this local
+diagnostic and 100 consecutive derivations with retained state. The cost formula
+models input caching at the stated rates; it omits task quality and cannot prove
+30k/40k is globally optimal. These legacy bounds retain their 5k work floor.
+
+`scripts/ab-suite.ts` now separates node, replay, round-preserving truncation and
+observation masking. It uses a seeded shuffled schedule and includes output cost
+and failed outcomes. Historical A/B figures predate these corrections and cannot
+establish superiority over the corrected baselines. No new live-model result is
+claimed until that experiment is run.
+
+There is also a floor with a principled reason: **a handoff only pays for itself once a
+segment's history exceeds the handoff.** Below that, replaying the history is cheaper —
+`test/log.test.ts` pins both sides of that crossover.
+
+## Layout
+
+`SessionConfig.contextPolicy` and `--context-policy` select `windowed` (new-session
+default), `segmented`, `continuous`, or the experimental `adaptive` policy. They
+share the same durable log. Saved sessions keep their original policy, including
+legacy logs without a policy, which resume as segmented. Explicit CLI `--trigger`
+selects segmented unless `--context-policy` is also set. Continuous
+keeps the dialogue until the provider window guard stops it; adaptive may defer a
+soft cut when continuation state is missing or a conservative next-input cost
+estimate favors keeping the cached prefix. It still obeys the hard boundary.
+Windowed cuts keep a bounded recent suffix of complete exchanges alongside the
+derived handoff, through event references rather than copied transcript bytes.
+The replacement targets half the usable window and at most 20k recent-history
+tokens; these are testable assumptions. New prompts are checked before dispatch.
+If no useful replacement fits, the session stops explicitly. Retained events do
+not count twice toward derived state, and model switches discard old thinking.
+The segmented 30k/40k/5k values are unchanged. Missing working state gets one
+append-only preparation notice before the boundary. These mechanisms do not
+guarantee model compliance or lower whole-task costs; see research N.6.
+
+New sessions also stop before another model call after 12 complete tool exchanges
+without new observed evidence or fresh verification, with one warning halfway.
+This watchdog is independent of context cuts and reconstructs from original log
+events. `SessionConfig.stallLimit` accepts 0 to disable or an integer of at least 2;
+old saved sessions without it retain their prior behavior. Novel content need not
+be relevant, so this is a resource guard, not a task-success judge (research N.9).
+
+Dependency direction is one-way, enforced mechanically by
+`scripts/check-boundaries.ts`:
+
+```
+apps  ->  runtime  ->  store  ->  core
+```
+
+Every path below was checked with `test -f` on this checkout.
+
+| Layer | |
+|---|---|
+| **`src/core/`** | **pure**: no I/O, no clock, no randomness, no model call |
+| `core/events.ts` | log event types; harness-derived vs model-annotated split |
+| `core/handoff.ts` | handoff schema, YAML field order, `validateHandoff` invariants |
+| `core/derive.ts` | `deriveHandoff` — events + previous handoff -> next handoff |
+| `core/project.ts` | `projectContext` — log -> messages |
+| `core/transcript.ts` / `file-references.ts` | pure human-history projection and explicit file references |
+| `core/boundary.ts` | `shouldCut`, `shouldStopAndAsk` |
+| `core/continuation.ts` / `history-query.ts` | append-only guidance and ancestry search contracts |
+| `core/context-policy.ts` | windowed replay, legacy policies and conservative cache-cost estimates |
+| `core/context-window.ts` | model-window budgets and exact recent-exchange retention |
+| `core/data-query.ts` | deterministic parsing, filtering, grouping and aggregates |
+| `core/yaml.ts` | restricted deterministic YAML emitter, no dependencies |
+| `core/tokens.ts` | token counter interface; the bundled one is an estimate and says so |
+| `core/permissions.ts` | `decide` / `selectTools` — pure rules; approval is a last look, not a boundary |
+| `core/skills.ts` / `prompts.ts` / `frontmatter.ts` | skill text and `/name` templates |
+| `core/settings.ts` / `theme.ts` / `keymap.ts` | settings merge, themes, bindings |
+| `core/queue.ts` | steering / follow-up queue |
+| **`src/store/`** | the only I/O: node JSONL, handoff files, manifest, blobs |
+| `store/log.ts` / `sessions.ts` | node tree and `.xeno/sessions/<id>/` |
+| `store/config.ts` | `~/.xeno/` paths; `auth.json` is 0600 |
+| `store/search.ts` | grep / find / ls walk |
+| `store/context-files.ts` | AGENTS.md discovery |
+| **`src/runtime/`** | impure but thin; the only layer allowed npm packages |
+| `runtime/provider.ts` / `openai.ts` | the two wire formats |
+| `runtime/catalog.ts` / `model.ts` | 12 providers, 23 models |
+| `runtime/tools.ts` / `history-tools.ts` | confined tools, complete query results and history retrieval |
+| `runtime/benchmark.ts` | actual Session trials, bounded spending and cache diagnostics |
+| `runtime/loop.ts` | orchestration; every judgement delegates to a pure function in core |
+| `runtime/auth.ts` / `oauth.ts` | credential order and subscription flows |
+| **`src/vendor/pi-tui/`** | unmodified Pi terminal and component library, pinned in `VENDOR.md` |
+| **`src/tui/`** | Pi input, component and theme adapters; no harness imports |
+| `tui/markdown.ts` / `toolview.ts` / `statusline.ts` / `tree.ts` | display |
+| **`src/apps/`** | `cli.ts` — Pi main-screen UI for TTY, clean print/JSON output otherwise |
+| `apps/startup.ts` / `shell.ts` / `commands.ts` | flags, session, slash commands |
+
+## Properties the tests pin
+
+- **Identity.** With no handoff, the projection is the identity mapping of harness
+  events onto messages. Segment 0 behaves exactly like a harness with no context
+  management, so nothing is paid for until a boundary actually fires.
+- **Prefix stability.** Appending an event only appends to the projection; it never
+  rewrites an earlier message. This pins prefix stability; actual cache hits
+  remain provider-dependent.
+- **Purity.** Identical inputs produce byte-identical YAML. `deriveHandoff` mutates
+  neither its inputs nor the previous handoff.
+- **Nothing silently dropped.** Every claim appears in exactly one of `completed` or
+  `unverified_claims`; state buckets are pairwise disjoint; accumulated state is
+  monotonic across segments.
+- **No history copies.** Tool output is referenced rather than recursively embedded.
+  The carried handoff is budgeted; full structured state remains reconstructible.
+- **YAML round-trips.** Emit -> parse -> re-emit is byte-identical, verified against a
+  real parser, with an idempotency gate and golden snapshots.
+
+```
+bun run gate                         # bun test + tsc --noEmit + the boundary checks
+bun run measure                      # the segment-length measurement
+bun run regen-golden                 # regenerate snapshots, then read the diff
+```
+
+Design notes: `docs/agent-harness-research.md`.

package/docs/install.md

@@ -0,0 +1,130 @@
+# Install xeno
+
+Published as `@visual-z/xeno`. The license is `UNLICENSED`: the package is
+public to read and install, and no right to reuse the code is granted.
+
+```bash
+npm i -g @visual-z/xeno    # or: bun add -g @visual-z/xeno
+```
+
+The installed `xeno` still runs with Bun (below). Installing from a
+checkout works the same way and is described after it.
+
+## Bun, not Node
+
+The entry point is `src/apps/cli.ts` with `#!/usr/bin/env bun`. The
+process uses Bun APIs (`Bun.file`, `Bun.spawn`, `Bun.spawnSync`,
+`for await (const line of console)`). Those are why the runtime is Bun.
+
+`engines.bun` is `>=1.1.0`. This checkout was run on **Bun 1.3.10**.
+Node is untested. That is a fact about this tree, not a promise that
+Node support is coming.
+
+Install Bun from https://bun.sh.
+
+## From a checkout
+
+```bash
+git clone <this-repo> xeno
+cd xeno
+bun install
+```
+
+`bun install` pulls the one runtime dependency (`@anthropic-ai/sdk`)
+and the TypeScript dev tooling.
+
+Run the CLI without linking:
+
+```bash
+bun src/apps/cli.ts --help
+```
+
+Or put `xeno` on your PATH from this checkout:
+
+```bash
+bun link
+```
+
+Then, in any directory:
+
+```bash
+xeno --help
+xeno --list-models
+```
+
+`bun link` writes a shim that executes the `bin` field
+(`src/apps/cli.ts`) with Bun. It does not copy the tree.
+
+A workspace that already has a session is resumed. `--fresh` starts a
+new session beside it; nothing is deleted.
+
+## Credentials
+
+Resolution order, first match wins:
+
+1. `--api-key`
+2. `~/.xeno/auth.json` (created `0600` by `/login`)
+3. the provider's environment variable
+
+A stored entry owns that provider. The environment is not a fallback
+after a stored key fails.
+
+| Provider    | Environment variable                                      |
+|-------------|-----------------------------------------------------------|
+| anthropic   | `ANTHROPIC_API_KEY`                                       |
+| openai      | `OPENAI_API_KEY`                                          |
+| google      | `GOOGLE_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` or `GEMINI_API_KEY` |
+| deepseek    | `DEEPSEEK_API_KEY`                                        |
+| xai         | `XAI_API_KEY`                                             |
+| groq        | `GROQ_API_KEY`                                            |
+| cerebras    | `CEREBRAS_API_KEY`                                        |
+| mistral     | `MISTRAL_API_KEY`                                         |
+| openrouter  | `OPENROUTER_API_KEY`                                      |
+| zai         | `ZHIPU_API_KEY`                                           |
+| moonshotai  | `MOONSHOT_API_KEY`                                        |
+| together    | `TOGETHER_API_KEY`                                        |
+
+Interactive: export one of those, or run `/login <provider>`.
+`-p` / no tty: pass `--api-key` or export the variable. `/login` is
+not a script path.
+
+`/login claude-pro`, `/login codex`, and `/login github-copilot` start
+subscription flows (authorization-code + PKCE, or a device code for
+Copilot). They use first-party client credentials; the terms-of-service
+risk is on your account. Those flows have been tested against injected
+transports, not against a live authorization endpoint.
+
+## What a run writes
+
+In the **workspace**:
+
+```
+.xeno/sessions/<id>/   node-NNNN.jsonl, handoff-NNNN.yaml, manifest
+.xeno/blobs/           content-addressed snapshots for /back
+```
+
+That directory grows. There is no garbage collection.
+
+In **your home directory** (`~/.xeno/`, or `$XENO_CONFIG_DIR`):
+
+```
+auth.json         credentials (0600)
+settings.json     theme, thinking, defaults
+trust.json        which directories may load project settings
+models.json       optional catalog overlay (written by `xeno models --refresh`)
+keybindings.json  optional
+prompts/ skills/  optional
+```
+
+A leftover `.xeno/log` from before named sessions is not moved. Continue
+it with `--log .xeno/log`.
+
+Add this to the project's `.gitignore`:
+
+```
+.xeno/
+```
+
+## Untrusted work
+
+There is no sandbox. See the Isolation section in `README.md`.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@visual-z/xeno",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "type": "module",
+  "description": "Segmented append-only agent log with pure context and handoff projections",
+  "bin": {
+    "xeno": "src/apps/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "docs/install.md"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "repository": {
+    "type": "git"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun run scripts/typecheck.ts",
+    "check": "bun run scripts/check-boundaries.ts",
+    "gate": "bun test && bun run typecheck && bun run scripts/check-boundaries.ts",
+    "verify-red": "bun run scripts/verify-red.ts",
+    "regen-golden": "bun run scripts/regen-golden.ts",
+    "measure": "bun run scripts/measure-handoff.ts",
+    "agent": "bun run src/apps/cli.ts"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/bun": "latest"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.127.0",
+    "get-east-asian-width": "1.6.0",
+    "marked": "18.0.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}