@visual-z/xeno 0.8.4 → 0.9.1

package/README.md

@@ -1,769 +1,54 @@
 # 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
-```
-
-The on-disk session format will still change; `0.x` is that statement, and
-`xeno --version` reports the installed release. Published as `@visual-z/xeno`; the license is `UNLICENSED` (readable and installable, no reuse granted).
+A terminal coding agent whose session is a segmented, append-only log. What the
+model sees is a recomputable projection of that log. Nothing is summarized by a
+model, and nothing is rewritten in place. A step counts as done only when a command's exit
+code says so.
 
 ## 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
+npm i -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.
-- Evidence-backed goals, progress and Context Lens in `/control`, shared with the experimental JSONL app server and optional local control socket. See [`docs/app-server.md`](docs/app-server.md) for identity, events, approval, recovery and OSC 7501 status.
-- 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.
-- Verified history projections use a bounded per-session cache. Original ancestry and sealed digests are checked before every hit; a lost cache is rebuilt from the log.
-- The `foundation` tool profile adds web fetch/search, standard MCP, structured questions, transactional Patch, explicit formatters, diff and configured LSP. Build/Plan roles share the real capability and permission owner; independent code review has its own read-only context. Final JSON can be schema-validated before print output. See [`docs/foundations.md`](docs/foundations.md) for configuration and commands.
-- The app server owns multiple sessions with a typed local control client; `xeno acp` also exposes standard ACP through the official SDK. Both route cancellation, approvals and questions through the original Session.
-
-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 eval/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. The comparison Pi CLI runs on Node through
-an isolated local tool bridge; xeno's providers use the pinned Pi AI runtime described below.
-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.
-
-The new single-factor protocol separately compares tool profiles, the carried
-working set, and strict verification. It runs four isolated scenarios through
-real sessions and grades files, fresh command evidence, and pending human review.
-Use `bun eval/scripts/eval-harness.ts smoke --output /absolute/new/eval-directory`,
-then `bun eval/scripts/eval-harness.ts audit --output /absolute/new/eval-directory`.
-Smoke has no paid requests and reports synthetic usage. `plan` and `run` require
-the same explicit numeric `--budget`; inputs, source, schemas, model settings,
-and paired order are frozen before spending. Started directories cannot be
-replayed automatically. Failures and missing trials remain in the denominator,
-and unknown charges retain their reservation. Details are in `docs/benchmarks.md`.
-
-## Usage
-
-```
-xeno [-m <model>] [--provider <name>] [--api-key <key>]
-     [-w <workspace>] [--log <dir>] [--max-turns N]
-     [--trigger N --hard N] [--list-models [search]] [--fresh]
-     [-c|--continue] [-r|--resume [id]] [--session path|id]
-     [--fork path|id] [--session-dir dir] [--session-id id] [--no-session]
-     [--models patterns] [--thinking level] [--mode text|json]
-     [--export session [output.html]] [--offline] [--version]
-     [models --refresh]
-     [--system-prompt <text-or-file>] [--append-system-prompt <text>]
-     [--no-context-files|-nc]
-     [--tools names] [--exclude-tools names] [--no-tools]
-     [--tool-profile coding|readonly|research|data|full]
-     [--acceptance-file <contract.json>]
-     [--allow-tools names] [--yolo|-y] [--approve|--no-approve]
-     [--theme <name|path>] [--use-theme <name>] [--no-themes]
-     [--tui-mode regular|fullscreen]
-     [--skill <path>] [--no-skills|-ns]
-     [--prompt-template <path>] [--no-prompt-templates|-np]
-     [--extension|-e <path>] [--no-extensions|-ne]
-     [-p <prompt>] [prompt...]
-```
-
-- No prompt, a tty: interactive session.
-- `/state` shows the current request's execution outcome, command receipts,
-  verification state and diagnostic progress across segment cuts and restarts.
-  Short tasks need no `note` calls to associate evidence. Without a declared
-  acceptance contract, successful commands remain evidence rather than verified
-  task completion. A command's new output counts as progress for the stall
-  watchdog whatever its exit code; an exchange that repeats the previous one
-  exactly earns none from output that only changes with timing.
-- `/goal <objective>` sets an explicit goal:
-  - The model first drafts acceptance criteria in a single read-only request: it may read the workspace (read, find, grep) but cannot change it or run commands. Each criterion is a command that should fail until the goal is done, a human check, or a guard.
-  - A guard (`"guard": true` on a command) protects what the goal must not break, such as "the test file is unchanged" or "only plan.md changed". It passes before the work and must still pass after it. Guards are marked in the checklist.
-  - A draft that does not parse goes back to the model once with the reasons. If the model says the goal cannot be checked in this workspace, it gives the reason and no goal is set.
-  - You accept the criteria one by one: a checklist in the TUI, or `/goal accept all|1,3` in line mode.
-  - Work then starts from the objective and continues automatically until every accepted criterion has a fresh passing receipt (and human criteria have your `/accept`).
-  - It stops early, with the goal still active, when the model reports a blocker, answers two goal checks without acting, a `--max-turns` budget runs out, or the stall watchdog fires.
-  - `/goal` shows the goal and the status of each criterion; `/goal clear` ends it.
-  - "Met" comes from receipts and your decisions, never from the model saying it is done.
-  - When the accepted checks pass, each one is counter-checked: it is re-run in a disposable copy-on-write clone of the workspace with this request's file changes undone.
-    - It reports whether the check fails without the changes (it tests them) or still passes (it does not).
-    - A guard is expected to pass there. If it does, it "held" and does not count against the evidence ladder. If it fails there, it "did not hold": the check actually tests the change, and it counts as such.
-    - If every check is a guard that held, the ladder says that no check tests the change.
-    - The undo comes from a snapshot taken when the goal request starts (a private Git directory and index; your HEAD, index and stash are untouched), so changes made by shell commands are undone too.
-    - If the starting state cannot be rebuilt exactly, the result is "unavailable", for example outside a Git work tree when a shell command wrote files that no checkpoint recorded.
-    - The real workspace is never touched, and the counter-check never blocks the goal.
-  - `--blind-checks <dir>` adds hidden checks: a directory outside the workspace holding `blind.json` (`{"version":1,"checks":[{"id","description","command"}]}`) and any fixtures.
-    - The checks are frozen when the session starts and never shown to the model.
-    - When the goal's checks pass, they run against a clone of the final workspace, with the directory copied in as `.xeno-blind/`.
-    - The whole log is scanned first, and a pass after the model named the directory or read one of its files is reported as `exposed`, not independent.
-- `/acceptance` shows declared command checks and human criteria. `/accept ID`
-  records your acceptance of a human criterion; subsequent edits invalidate it.
-  Use `--acceptance-file` or a trusted project's `.xeno/acceptance.json` with
-  `{ "version": 1, "id": "task", "criteria": [{ "id": "tests", "kind": "command", "description": "tests pass", "command": "bun test" }] }`.
-  Add `"guard": true` to a command criterion that must keep passing rather than one that shows the work was done.
-  The declaration is frozen in the session. A normal execution exit does not
-  imply that human acceptance has been granted.
-  A contract may additionally declare `targets`, each with `id`, `build`
-  (a command criterion ID), `artifacts: { paths, output_roots }`, and `entry`
-  (one of those artifact paths). Optional `interpreter` is an absolute executable
-  path; `args` are literal strings, `workdir` stays inside the workspace, and
-  `port` declares an IPv4 loopback listener. A human criterion binds to it with
-  `target: "ID"`. Enable the `target` tool explicitly with `--tools` or the
-  `full` profile; the default coding profile stays compact. Run the declared
-  build with its exact artifact plan, then `target({action:"start",target:"ID"})`.
-  `inspect` rechecks the owned instance, build inputs, artifact/executable identity
-  and port ownership. `/acceptance` shows the entry, build, PID and session;
-  `/accept ID` binds your decision to that observed instance. Rebuilds, changed
-  files, process exits or lost ownership require fresh acceptance. The first
-  implementation observes macOS executable identity with the system `lsof` and
-  Linux identity with `/proc`; port checks require system `lsof`. Missing OS
-  evidence remains unknown. It never adopts an existing server or proves visual
-  correctness automatically, and a resumed session cannot reattach an old PID.
-- 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.
-- Each invocation starts a new session, including `-p`. `--fresh` remains
-  an explicit alias. Nothing is deleted.
-- `-c` continues the newest session, or starts one if none exists. `-r`
-  opens a session picker; cancelling leaves saved sessions untouched.
-  `--session <path|id>` and `-r <id>` open a specific session.
-  A portable JSONL file creates an independent imported session in the current workspace.
-- Resume restores that session's model before consulting defaults. An
-  explicit `--model` switches through a checkpoint, preserving the original
-  log without replaying another model's thinking. Missing or ambiguous saved
-  models are reported; restore their catalog entry before resuming.
-- A leftover `.xeno/log` is not migrated; continue it with `--log .xeno/log`.
-- `--models 'deepseek/*:low,anthropic/*'` resolves ordered model scopes; an
-  explicit empty scope disables cycling. `--model id:level` sets thinking,
-  with an explicit `--thinking` taking precedence.
-- `--session-id id` creates or resumes that exact local ID. `--export` writes
-  offline HTML from a saved session or portable archive without starting an agent.
-- `--theme` can be repeated for explicit files/directories; `--use-theme`
-  selects a theme. `--no-themes` disables automatic discovery.
-- Extensions can register typed native CLI flags, including in `--help`.
-  Normal startup stays offline; `--offline` also blocks remote preparation.
-
-Slash commands that exist in the session (from `/help`):
-
-```
-/model [id]        search models, or switch (cuts a node)
-/models refresh    refresh ~/.xeno/models-cache.json; preserve models.json
-/provider [provider]  connect or manage an account, API key, gateway or local server
-/provider claude-pro|codex|github-copilot|grok
-                   subscription login (first-party client credentials)
-/logout [provider] remove a stored credential
-/scoped-models     enable, disable and order models for cycling
-/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, filter, fold, label and navigate exact session events
-/fork [n]          choose an exchange to copy into a new session
-/clone             copy the active branch into a new session
-/export [file]     offline HTML, or a portable archive with a .jsonl filename
-/import <file>     validate and open an archive as an independent session
-/debug [file]      write local terminal and message diagnostics
-/changelog         show bundled release notes
-/update            check for a newer xeno and install it (restart to use)
-/trust [once|here|parent|never]
-/reload            refresh local resources at a durable context checkpoint
-/config            search resources and edit global or project overrides
-/settings [key v]  theme, thinking, queues, viewport and editor settings
-/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.
-`!cmd` runs in the workspace, streams output, and records it for the next model
-request. `!!cmd` records human history while excluding its output from model
-context. Neither starts a model request or requires a model credential.
-Escape cancels the command and its process group. During a turn, Enter queues
-steering after the current tools finish; Alt+Enter queues a follow-up after the
-turn, or submits immediately while idle. Alt+Up returns the entire queue to the
-editor. Settings expose independent `steeringMode` and `followUpMode` values
-of `all` or `one-at-a-time`.
-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.
-Ctrl+T persists `hideThinkingBlock`. `/settings` also manages new-session model
-defaults and per-model thinking overrides; clearing an override restores the
-project or global setting. `showCacheMissNotices` displays the existing prefix
-diagnostics without changing usage accounting or issuing extra model requests.
-
-`/scoped-models` changes the current session immediately; Ctrl+S saves the range.
-
-`-r` and `/resume` share a session browser: Tab changes workspace scope, Ctrl+N
-filters named sessions, Ctrl+S cycles threaded/recent/relevance ordering, Ctrl+P
-shows paths, and Ctrl+R renames. Search supports `re:<pattern>` and quoted phrases.
-Ctrl+D asks before moving an inactive session into its sibling `.trash` directory;
-the original files remain recoverable by moving that directory back. All-workspace
-discovery uses registered session roots, with no 200-session result cap.
-The tree supports Ctrl+O filter cycling, Alt+Left/Right branch folding/navigation,
-Shift+L labels, Shift+T label timestamps, and Ctrl+X copy. These actions can be rebound.
-Enter toggles a model, Ctrl+A/Ctrl+X enables/disables filtered models, Ctrl+P
-toggles a provider, and Alt+Up/Down orders enabled models. An explicit empty
-range disables cycling. `/thinking` exposes off/minimal/low/medium/high/xhigh/max
-with model capability checks; Ctrl+S saves a default for that provider/model.
-Automatic model changes clamp effort to a supported level.
-
-`xeno --list-models [search]` searches the offline union of Pi and OpenCode's
-Models.dev directory: **226 providers and 7,501 model entries** in the pinned
-snapshot. Use `provider/model` when several providers expose the same ID.
-`xeno models --refresh` atomically updates `~/.xeno/models-cache.json`;
-startup never fetches and the user's `~/.xeno/models.json` remains untouched.
-Flat catalogs, Pi `providers` and OpenCode `provider` configuration are supported.
-See [provider configuration](docs/providers.md) for local servers, model overrides,
-credentials, native cloud protocols, and explicit coverage limits.
-
-## Credentials
-
-Order: `--api-key`, `~/.xeno/auth.json`, `models.json` provider/model credentials,
-then the provider's environment variables. `/login` and `/connect` remain hidden
-aliases of `/provider`. Enter confirms the selected command argument; Tab inserts it.
-A failed explicit source does not
-fall through to another account. `/provider codex` uses the `openai-codex` protocol;
-ordinary OpenAI API models use `openai`.
-
-`/provider grok` uses official device authorization and refreshes the account token.
-Its model is `xai-grok/grok-build` on the official CLI inference proxy. xAI API keys
-remain on `xai`; credentials and rates are not shared between these accounts.
-
-Interactive sessions can start with no key and wait for `/provider`. `-p` and
-non-tty runs exit 1 and name `--api-key` or the variable; they do not mention
-`/provider`.
-
-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.
-Shell entry points (`exec_command`, `environment`, `bash`, `target`) ask
-before they run 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.
+npm downloads one native binary for your platform: macOS, Linux (glibc or
+musl) or Windows, each on arm64 or x64. Neither Node nor Bun is needed to run it.
 
-New sessions default to the ten-tool `coding` profile: read, grep, find,
-write, edit, environment, exec_command, write_stdin, history and note. `readonly`,
-`research` (with branch/resolve), `data` (with query) and `full` choose other
-builtin defaults. Extensions remain available; explicit `--tools` overrides
-the profile and exclusions apply last. Default session resume keeps the frozen
-tool selection; explicit tool flags apply at a resource checkpoint. `/reload`
-reselects tools using the current settings.
-Tool selection does not bypass permission checks; restoring a tool does not
-restore approvals from the previous process.
-
-After reading an existing file, normally omit `read_handle` and `expected_sha256`
-when writing or editing it: Session checks the latest observed file version.
-Pass an exact receipt only to select a specific observation; a stale version
-still requires a fresh read. Without any prior observation, omission provides
-no stale-version protection.
-
-`--tools` / `--exclude-tools` / `--no-tools` remove tools from the schema
-the model sees. `--allow-tools exec_command` lets commands 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.
-
-`--yolo` (or `-y`) allows every available tool without an approval prompt for
-the current process. It works in interactive, print, and app-server modes;
-resumed sessions use the current invocation's choice. Tool exclusions,
-read-only branch capabilities, input checks and file path limits still apply.
-YOLO does not enable project trust or get saved in settings or session history.
-Without the flag, the next launch uses the default approval rules again.
+With Bun, trust the package so its install step can link the binary:
 
 ```bash
-bun run agent --yolo                 # interactive session from this checkout
-bun run agent --yolo -c              # continue with approvals skipped
-bun run agent --yolo -p "run tests"   # explicit approval-free automation
+bun add -g --trust @visual-z/xeno
 ```
 
-The installed CLI accepts `xeno --yolo` in version 0.5.0 and later. To
-allow only host commands, use `--allow-tools exec_command,environment`.
-
-## Workspace data
-
-Opening a session does not snapshot the working directory. File tools save the
-original bytes before editing and record the observed result. `/back` restores
-only recorded paths, preserves unrelated files, and refuses conflicting external
-edits. Conversation-only navigation leaves files unchanged.
-
-Shell effects are not automatically reversible. Opt in for a new session with
-`--checkpoint-shell` to capture eligible Git files around commands. This uses a
-private index and object store without changing your staging area or HEAD. Git
-ignored paths, non-regular files, untracked files over 2 MiB, and effects outside
-the workspace are excluded. Capture is best effort; unavailable recovery does
-not prevent a conversation or change the command's exit result. A running process
-has a pending checkpoint until its exit is observed; overlapping writes make that
-checkpoint unavailable. Initial capture can take time.
+Without `--trust`, `xeno` still starts on macOS and Linux through a small
+launcher script.
 
-Verification observes a bounded source scope separately from file recovery.
-Unknown observations cannot certify a completion claim. Old snapshot logs remain
-readable; new file records and scope markers are appended without rewriting them.
+## Start
 
-A session writes into the workspace:
-
-| Path | |
-|---|---|
-| `.xeno/sessions/<id>/` | node logs, handoffs, metadata journal, derived manifest, and observation artifacts |
-| `.xeno/blobs/` | content-addressed before/after file versions 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. Inside a Git work tree they skip git-ignored files, as
-  Claude Code, OpenCode and Pi do; a path that names an ignored directory is
-  still searched.
-- `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.
-- Ten native wire protocols through a pinned Pi runtime adapter, alongside the
-  three existing verified transports. Streaming text, thinking, tools and opaque
-  signatures project from the same append-only log; deltas remain UI events.
-- An offline provider/model union with **226 providers** and **7,501 entries**,
-  user overrides by provider/model, and a separate explicit-refresh cache.
-  Native protocol fixtures cover requests and responses; the directory is not
-  a claim that every listed remote account/model was tested live.
-- 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 pinned OpenTUI, a native text editor, autocomplete,
-  Markdown, a command palette and searchable pickers. Durable history is a pure
-  log projection across handoff boundaries. Includes tool diffs, historical
-  folds, terminal colours, `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
-  support progressive loading, user visibility, explicit tool intersections
-  and isolated `context: fork`. Unsupported execution fields are diagnosed.
-  Loaded instructions keep frozen source hashes and recoverable artifacts.
-  Templates use `~/.xeno/prompts/` and `/name`. Untrusted projects do not load
-  project-level copies.
-- `/tasks` shows dependency readiness and claims. Long tasks can use
-  `note(kind="next", work_id="b", depends_on=["a"], ...)`, then
-  `claim_work` / `release_work`; these are scheduling intent, separate from
-  the `done` command proof. Ordinary short tasks do not need a graph.
-- `branch(background=true)` returns an owned task reference. `/branches`
-  lists its current capability; `/branches wait|cancel|status <node>` joins or
-  controls it without a model request. `resolve` exposes the same actions.
-  Restarted unfinished tasks remain unknown; sealed outcomes can be joined.
-- `/processes` separates the last logged observation from a live handle.
-  Session exit drains its own processes and archives unread output.
-- `/reload` refreshes local models, settings, keybindings, context files, skills,
-  templates and themes without losing the draft or active model. A changed system
-  prefix checkpoints first; unchanged resources do not create a new segment.
-  `/config` and `xeno config` share searchable resource provenance and enablement.
-  Relative resource paths resolve from the settings file that declares them;
-  project overrides cycle through inherit, load and skip. CLI paths remain explicit.
-  `/trust` opens a selector; `once` grants no persistent trust. Global
-  `defaultProjectTrust` cannot be overridden by project settings.
-  Templates support Pi's `$1`, `$@`, `$ARGUMENTS`, defaults and slices as well as
-  the existing `{{name}}` syntax. Arguments are substituted once.
-- Local TS/JS extensions can register commands, shortcuts, tools and lifecycle
-  hooks through Pi's factory protocol. Discovery, project trust and `/reload`
-  use the same resource inventory. Custom state and messages remain append-only
-  log events. See [extension boundaries and usage](docs/extensions.md).
-- Packages can come from local paths, npm or git: `xeno install <source>`,
-  `remove`, `update --extensions` and `list`. `--local` selects project scope;
-  `-e` tries a package for one invocation. Manifests, per-kind filters and trust
-  feed the same resource inventory. Normal startup stays offline.
-  See [package management](docs/packages.md).
-- `/provider` for API keys and for Claude Pro/Max, Codex, GitHub Copilot,
-  and official Grok account flows. See Known gaps.
-
-Images can be attached with `@path`, a dropped image path, or Ctrl+V (files,
-image, then text). Pasted and dropped images become `[Image #N]` tags at the
-caret. Left/Right cross a whole tag; Backspace/Delete remove it in one step,
-and Undo restores it. Moving the caret next to a tag shows its preview above
-the input (filename and dimensions when image display is unavailable).
-`/attachments` remains available for removal; queue recall and history
-forks retain them. The log stores immutable blob references. Provider adapters
-load verified bytes for Anthropic, Chat Completions and Responses; text-only
-models receive a visible placeholder. Custom models declare `input: ["text", "image"]`
-in `models.json`. `terminal.showImages`, `terminal.imageWidthCells`,
-`images.autoResize`, `images.blockImages` and `markdown.mermaid` are configurable
-through `/settings`. Pi syntax highlighting and Mermaid use the same rendering
-path for saved replies and live output. Image tokens are estimates until provider
-usage is available. Enabling image blocking checkpoints an existing image context;
-unblocking affects new submissions, preserving historical request prefixes.
-
-## 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.
-- **Package installation is separate from resource loading.** Local extensions,
-  skills and templates load from explicit, trusted filesystem sources.
-  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`, automatic updates, or `/compact`.** Those
-  are refusals (`docs/PI_PARITY.md` D15, D16), not backlog. xeno does say
-  when a newer version is published, checking automatically at most once a day.
-  `/update` checks and installs when you ask; `xeno update --check` only checks;
-  `docs/install.md` (Updates) lists what that request reveals and every
-  way to turn it off.
-
-`docs/TUI_ARCHITECTURE.md` describes the active interaction path and verification.
-`docs/PI_PARITY.md` records deliberate differences and remaining Pi features.
-The native editor supports undo (Ctrl+_ or Ctrl+/) and redo (Ctrl+Shift+Z).
-Registered image tags move and delete as whole units and share text undo history.
-Ctrl+Z suspends the CLI on POSIX; `fg` restores the terminal and unsent draft.
-
-Fullscreen is the default. Ctrl+P opens commands, Ctrl+L selects a model,
-PgUp/PgDn scroll, and Ctrl+Home/End jump to the start or latest messages.
-Ctrl+O expands tools, Ctrl+T expands thinking, and Ctrl+B toggles the sidebar.
-Mouse selection copies plain text when `fullscreenCopyOnSelect` is enabled;
-Ctrl+X copies a selection or the last reply. Exiting restores the terminal and
-prints a bounded execution status and a resume command. Set
-`fullscreenExitOutput` to `transcript` in `/settings` for full replay on exit.
-The composer stays at the bottom
-and grows with the draft; pickers and forms use the same input area.
-
-An empty `write_stdin` in an agent session waits for new output, command exit,
-hard timeout, cancellation or user steering. The process owner holds that wait;
-quiet commands do not consume model requests through periodic polling.
-Sending input and low-level process polling keep their bounded yield contract.
-There is no request cap by default, as in Claude Code, Codex, Gemini CLI and
-OpenCode: the stall watchdog stops a run after 12 exchanges without new
-evidence. For `--max-turns N`, budgets above one reserve the last request for a text answer.
-Tools stay frozen and are disabled for that request, with host enforcement.
-Unsupported protocols or a failed final response use an evidence-based stop
-report inside the same budget. `/usage` labels provider durations as model time.
-
-`/settings theme` previews built-in and custom themes from the config directory's
-`themes/`. Escape restores the prior theme. Custom files reload after valid edits;
-`auto` follows terminal light/dark changes. Built-in themes keep the terminal's
-background and derive readable accents from its colour replies. Namespaced action IDs work in `keybindings.json`
-alongside existing xeno names; an empty array disables an action in its own scope.
-
-## 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.
-
-`eval/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
+```bash
+export ANTHROPIC_API_KEY=…    # or OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, …
+xeno                          # interactive
+xeno -p "explain this repo"   # one prompt, then exit
+xeno -c                       # continue the newest session
+xeno -r                       # pick a session to resume
 ```
 
-Every path below was checked with `test -f` on this checkout.
+In the app, `/provider` connects an account, an API key or a gateway. `/model` switches
+models, `/settings` opens settings, `/changelog` shows what changed, and
+`/update` installs a newer release.
 
-| 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-config.ts` / `model-sources.ts` | Pi + Models.dev union, offline overlays and private provider configuration |
-| `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/tui/`** | OpenTUI view components and pure display helpers; no harness imports |
-| `tui/ui/composer.ts` / `atomic-draft.ts` / `messages.ts` / `screen.ts` | native editing, atomic image tags, messages and layout |
-| **`src/apps/`** | `cli.ts` — OpenTUI for TTY, clean print/JSON output otherwise |
-| `apps/ui/app.ts` / `project.ts` / `status-model.ts` | controller, transcript projection and status facts |
-| `apps/startup.ts` / `shell.ts` / `commands.ts` | flags, session, slash commands |
+Sessions live in `.xeno/` inside the project; settings and credentials in
+`~/.xeno/` (`auth.json` is created with mode `0600`).
 
-## Properties the tests pin
+## Updates
 
-- **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.
+xeno checks the npm registry for a newer release at most once a day, in the
+background. It sends no identifier. Set `XENO_NO_UPDATE_CHECK=1`, or turn off
+*Check for updates* in `/settings`, to stop it. `xeno update --check` checks
+now.
 
-```
-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
-```
+## License
 
-Design notes: `docs/agent-harness-research.md`.
+Proprietary (`UNLICENSED`). You may install and use the published binaries;
+no right to copy, modify or redistribute them is granted.