@hraness/xcb 0.9.1

package/README.md

@@ -0,0 +1,555 @@
+<!-- hraness:xcb-landing:start -->
+# xcb
+
+xcb, short for Excalibur, routes coding tasks across the Claude, Codex, and
+Devin subscriptions you already pay for. Each task runs on an account that is
+signed in, idle, and not at a known usage limit, on a model that fits the
+work, and xcb holds that account until the provider process has exited.
+
+It is for developers who pay for more than one coding agent and want one
+workflow around them: another agent can hand it work with one JSON command,
+`xcb --json route`, an application can embed the TypeScript SDK, and the
+terminal workspace is built on the same router. The native Rust app is a
+source preview for supported Claude, Codex, and Devin runtimes. It includes
+workspace file tools, an isolated Linux command runner, customizable panes,
+and a separate application API. The managed harness, which is being rebuilt as
+a self-evolving ALGAL harness, is in development and does not run
+self-modifying routing policies. It does not replace every feature of the
+providers' own tools; provider support and limits are listed below.
+<!-- hraness:xcb-landing:end -->
+
+[Project site](https://xcb.sh) · [Getting started](https://xcb.sh/docs/getting-started) ·
+[Compare tools](https://xcb.sh/compare) · [Source](https://github.com/hraness/xcb) ·
+[Route contract](docs/route.md) · [Application API](docs/application-api.md) · [Compatibility reference](docs/compatibility.md) · [Contributing](CONTRIBUTING.md)
+
+xcb picks one signed-in, idle account for each task and keeps it locked until
+the provider process has exited, so permission stays explicit: the design every
+Hraness project shares.
+[The thread through hraness](https://hraness.com/writing/the-thread-through-hraness)
+follows that design across the projects, and the
+[ALGAL vision](https://algal.computer/docs/vision/) states the bet behind it.
+
+## Readiness
+
+**xcb is not yet a daily-driver replacement for Codex, Claude Code, and Devin.**
+The native broker lists, reads, searches, and writes workspace files, creates
+directories, and removes or renames regular files with revision checks. The
+source also includes an isolated Linux command runner for tests and builds on
+macOS ARM64. The current backend passed its 12-case VM boundary suite, including
+filtered Git inspection, public dependency fetching, and offline Cargo/Bun use
+from immutable caches. Installed Claude and Codex coding workflows passed on
+macOS ARM64: an expected test failure, exact repair, passing test, and filtered
+Git status, with joined processes and settled effects. This evidence covers the
+tested accounts and admitted builds. Devin's credential-free boundary checks
+are separate from authenticated coding acceptance. See the [command runner contract](docs/command-runner.md)
+for setup, supported boundaries, and current limits.
+
+| Provider | Native Rust CLI | TypeScript compatibility CLI |
+| --- | --- | --- |
+| Claude | Installed coding workflow verified on macOS ARM64 with the tested account; Linux remains an execution candidate after sign-in, binary admission, and confinement checks | Execution candidate, subject to its own admission and confinement checks |
+| Codex | Native app-server on macOS for exact build **0.156.1**; credential-free boundary and tool-manifest checks passed; authenticated coding acceptance was recorded on the previous admitted build and has not been rerun on this one | Discovery only; managed task execution gated on host qualification |
+| Devin | Native ACP candidate on macOS for exact builds **3000.11.3**, **3000.11.1** and **3000.10.31**; all passed credential-free boundary checks; model availability is checked against the connected account's fresh catalog at launch | ACP implementation exists; task execution disabled pending exact-runtime qualification |
+
+A successful `doctor` or a visible model does not prove a working coding session.
+The current Devin CLI can be authenticated and can return its model catalog, but
+that provider login is separate from xcb's explicit credential import and from
+an admitted coding turn. Devin validates the selected model against the
+connected account's fresh catalog before each turn. The September 20, 2026
+quota result is historical evidence, not a statement of current availability.
+`xcb doctor` marks an unqualified provider build with ⚠ ("found, but xcb
+can't run this build yet"). Codex and
+Devin candidates require the checked executable digest as well as the version;
+other builds and their Linux execution paths remain unavailable. Automated
+fixtures check boundaries; they do not establish authentication, service
+reliability, or real-model task quality. The TypeScript compatibility CLI's
+Codex and Devin task routes remain unqualified and disabled.
+
+## Native xcb
+
+Native release binaries are built for macOS ARM64 (`darwin-aarch64`) and
+Linux x86_64 (`linux-x86_64`) as `xcb-<version>-<platform>.tar.gz` with an
+adjacent `.sha256` checksum; other hosts build from source. The
+[release assets](https://github.com/hraness/xcb/releases) show the latest
+verified version and the [project site](https://xcb.sh/download) reflects the
+same datum. The source version number is a build identity, not a published
+release. Releases tagged v0.3.0 and earlier are AgentMixer package archives,
+not native xcb binaries.
+
+### Install a verified release
+
+On a supported platform, download the archive and checksum for your host from
+the release assets, or let the installer fetch and verify one exact version
+from a source checkout:
+
+```sh
+XCB_VERSION=<version> ./scripts/install-native.sh
+```
+
+The installer refuses a missing archive, a checksum mismatch, or an archive
+that contains anything other than the `xcb` binary. When no verified native
+release exists yet, install from source instead.
+
+### Install from source
+
+Requires Git, the pinned Rust **1.97.1** toolchain, and platform build tools.
+Claude's supported execution boundary is macOS Seatbelt or Linux with a working,
+admitted `bwrap` configuration. The native Codex and Devin candidates currently
+require macOS Seatbelt; unsupported confinement fails closed.
+
+```sh
+git clone https://github.com/hraness/xcb.git
+cd xcb
+rustup toolchain install 1.97.1 --profile minimal
+./scripts/install-native.sh
+export PATH="$HOME/.local/bin:$PATH"
+xcb --version
+xcb --help
+```
+
+The installer builds with the lockfile and installs `~/.local/bin/xcb`.
+`XCB_INSTALL_PREFIX` changes the prefix; `XCB_ADD_PATH=yes` appends the bin
+directory to your shell profile when it is not already on `PATH`. The
+TypeScript compatibility CLI installs as `xcb-compat`, so it does not shadow
+the native `xcb`; an older compatibility install that still used the `xcb`
+name should be removed, and `command -v xcb` shows which binary answers.
+The installer also records a private install manifest under the prefix and
+keeps the exact installer beside the binary, so later upgrades use the same
+verified path.
+
+### Updates and global operation
+
+The native binary is a user-global install when it lives in `~/.local/bin` and
+that directory is on `PATH`. xcb follows an OpenCode-style policy: `notify` is
+the default, `auto` installs only an exact stable release with its checksum,
+and `disable` turns checks off. Scheduled checks are macOS-only: a LaunchAgent
+runs the check once a day when you enable it, and it never reads project
+settings or updates from `main`. On Linux, run `xcb update check` from your
+own user timer; `xcb update enable` reports that scheduling is unavailable.
+
+```sh
+xcb update check
+xcb update enable --policy notify   # macOS only: check daily and tell you when a release exists
+xcb update enable --policy auto     # macOS only: check daily and install verified releases
+xcb update status
+xcb upgrade                         # install the latest verified native release
+xcb update disable
+```
+
+Native release binaries are built for macOS ARM64 (`darwin-aarch64`) and
+Linux x86_64 (`linux-x86_64`). The updater installs only a verified
+`xcb-<version>-<platform>.tar.gz` asset with its matching checksum for the
+running host; on any other host, or when no such release exists yet, it fails
+closed and leaves the installed binary alone. After any replacement, restart
+open terminals; provider pins rebind to the new host build automatically while
+their pinned provider bytes are unchanged.
+
+Managed supervisors record their exact executable identity. When that binary
+is replaced, a current supervisor stops starting new turns, retains custody of
+its active workers until they settle, then exits. Queued tasks and tasks waiting
+for input remain saved. Wait for that exit, restart the terminal, and reopen
+the thread or project view to continue; provider pins rebind automatically.
+A different running build produces an explicit supervisor-version error.
+Legacy supervisors without an identity record need their exact process verified
+and stopped after active workers settle; a saved PID or a deleted lock file is
+not a safe replacement for that verification.
+
+Managed records can gain fields that older source builds reject. Restart old
+clients and supervisors before using updated managed state, and retain that state
+during an installation rollback. Replacing the binary does not migrate provider
+sessions or establish fresh live acceptance across all three providers.
+
+### First managed conversation
+
+Install an admitted Claude Code binary (major 2, version 2.1.268 or newer).
+xcb performs its own account sign-in below; it does
+not silently import your existing provider login. Replace `<account-id>` below
+with the generated ID printed by `accounts add` or `accounts import-*` (the
+`xcb accounts` ID column is shortened; `xcb accounts --json` lists full IDs).
+Account names come from observed provider identities;
+custom labels are not accepted.
+
+```sh
+xcb setup claude --plan Max
+xcb --cwd /absolute/path/to/your/project
+```
+
+`xcb setup` adds the account (or reuses the one you have), checks Claude Code
+the way `xcb doctor` does, opens the browser sign-in, and loads the account's
+models. Each step is also its own command:
+
+```sh
+xcb accounts add claude --plan Max
+xcb doctor --provider claude
+xcb accounts login <account-id>
+xcb accounts refresh <account-id>
+xcb models
+```
+
+Plain `xcb` opens your thread from any directory. The thread is one managed
+conversation per machine that spans your projects: xcb picks the project
+directory each task runs in and says why in its reply, for example
+“Started Fix the parser in `xcb` · named `xcb` · /workspace to move”.
+It uses a path or project name in the prompt, the project you focused with
+`/workspace`, the task you are continuing, and only then the directory you
+launched from, so `--cwd` is a hint. When none of these settles it, xcb asks
+which project, keeps your draft, and saves nothing. A less certain choice, or
+a prompt that names a project other than the focused one, waits 8 seconds
+before it starts so you can move it with `/workspace <name|path>`. xcb only
+picks directories you have used or registered: `/workspace add <dir>` or
+`xcb workspaces add <dir>` registers one, and xcb refuses your home directory,
+its hidden directories, `~/Library`, xcb's own state and system directories.
+`xcb chat --new` starts a separate project view whose tasks all run in the
+current directory.
+
+Prompts become durable managed tasks routed through admitted Codex, Claude, or
+Devin sessions; closing the terminal detaches without cancelling them. Open
+another terminal for another view of the same task swarm, use `/tasks` to
+inspect work, or `/sessions` to switch between the thread and project views.
+Ordinary prompts create new work.
+In the v0.7 terminal, select a task in `/agents` and press `s` to guide it or `a`
+to answer its current question; the prompt displays the target. `/task` returns
+to new work and Tab queues it. Independent workspaces can run concurrently;
+tasks in the same workspace, or in a directory inside it, run one at a time. Use
+`/cancel <task-id>` to request cancellation and inspect `/tasks` for settlement.
+
+A project is a directory. Its backlog, work history, autonomy grant, working
+memory and Wordcell binding belong to that directory and are shared by the
+thread and every project view over it. A grant authorizes automatic work only
+in its own directory, even though the thread holds tasks for several.
+Use `/backlog` for this conversation's backlog (in the thread, narrowed to the
+focused project) and `/backlog all` to browse all
+projects. `/attention` collects questions, approvals and actions across agents.
+Use `/steer <task-id> <guidance>` to queue guidance for a task's next safe turn,
+and `/inbox` to inspect acceptance and delivery. `/watch <target-id> <source-id>`
+requests a completion report in the target's inbox. Available reports and messages
+share a bounded batch; they do not renew budgets or reopen closed work. The CLI
+offers the same `steer`, `watch` and `inbox` controls, including stable IDs for
+retries and paginated JSON inspection.
+Deferred work can be edited, released, or completed with a summary. `/project
+grant [project] <tasks> <hours> <goal>` delegates a bounded follow-up budget;
+`/project pause` holds future automatic work. In the thread, `/project` and
+`/memory` use the project you name, then the focused project, then the selected
+task's directory; `/schedule` and `/backlog add` use the focused project or the
+selected task's directory. None of them guesses: without a project they ask and
+save nothing. `/schedule` manages recurring prompts, and
+`xcb schedules program` pins bounded ALGAL planners. Starting in v0.6.0, add
+`--managed-calls 2`
+to run a controller that can suspend for up to two ordinary worker tasks, or use
+`xcb backlog program` to run one immediately. `/program` and
+`xcb backlog program-status <task-id>` show its linked child, progress and
+receipt. Every occurrence retains its normal task history and
+attention states. Workers can propose follow-ups,
+read recent summaries, and search an explicitly bound Wordcell vault. Explicit
+note promotion keeps long-term knowledge separate from working memory. See
+[persistent project agents](docs/project-agents.md) and [opt-in login
+startup](docs/habitat-service.md) for controls and limits.
+
+The Rust supervisor owns scheduling and deterministic safety decisions. ALGAL
+records bounded transition receipts; it does not infer permissions, establish
+provider qualification, or replace the supervisor’s execution policy.
+`xcb tasks verify <task-id>` replays that task’s local receipt chain and checks
+it against the current record; it does not attest provider claims or real-world
+outcomes.
+
+Managed routing and unpinned `xcb run` first filter for qualified, credentialed,
+idle, quota-usable accounts. ALGAL's fitted classifier can select a capability
+tier through one bounded typed judgment; routing works deterministically when
+that optional service is absent. Substantial prompts use the highest known
+quality among eligible models. Quota-driven downgrades are visible. Explicit
+provider/model requests remain constraints; routine work still considers
+relative cost, latency and workspace preferences. Official temporary
+offers are cached as expiring observations. They do not prove account entitlement
+or reduce a route’s estimated cost without that evidence. They never activate an
+unqualified provider or survive stale terms. Managed Claude, Codex and Devin workers share
+`xcb_swarm_status`, `xcb_message_list` and `xcb_message_send` for durable,
+workspace-scoped cross-provider coordination.
+
+A settled authentication failure marks that account as requiring reconnection
+and excludes it from new task routes, including after restart. Other eligible
+accounts still respect the requested provider. Successful sign-in or an explicit
+import with changed credential material clears the block; catalog refresh and
+reimporting the same credentials do not. Older failure records have no credential
+generation binding, so an upgraded account may need one new bounded attempt to
+establish this block.
+
+`--plan` is a display label; it does not verify your subscription. Complete the
+browser sign-in when prompted. `accounts refresh` probes supported model and
+usage metadata. Unknown or stale usage percentages remain unknown. A proven
+Claude account-wide quota exhaustion stays blocked until its reported reset,
+even when its percentage has gone stale. The account list shows a retry estimate;
+see [quota routing](docs/quota-routing.md) for the scope and credential binding.
+You do not need to select a model for managed chat or `xcb run`. To pin a model
+for a direct run, pass its full observed key with `--model`; stored direct
+sessions keep their existing binding. Begin a managed task with `Use Claude`,
+`Use Codex`, or `Use Devin` when you want to require that provider.
+
+If discovery finds the wrong binary, use
+`xcb doctor --provider claude --executable /absolute/path/to/claude`.
+The pin binds a private copy of the executable bytes plus version, so a
+provider auto-update cannot move the pinned install: xcb adopts an updated
+build automatically only when it is an admitted version and keeps routing the
+pinned build otherwise. For exact-artifact providers, admission also accepts
+reviewed (version, digest) pairs published in the repository's
+`qualified-builds.json`: a discovered build nothing yet admits is parked as
+awaiting catalog admission (`xcb doctor` reports it), and a published entry
+adopts it on the next hourly refresh without an xcb upgrade. The catalog is
+admission-only — a denied digest is rejected outright, and the stored copy
+is reused when the network is unavailable. After upgrading xcb, restart open
+xcb terminals; the
+pins rebind to the new host build on next use. A process started from the old
+binary cannot adopt the replacement binary's pin, and older clients refuse
+new run records whose credential-custody format they do not understand.
+An account, metadata pin, or model listing cannot activate an unqualified adapter.
+
+### Connect Codex on macOS
+
+Use the exact admitted **0.156.1** build. Its credential-free boundary and
+tool-manifest checks passed on macOS ARM64. Authenticated broker read/write/read
+and installed coding-workflow acceptance were recorded on the previous admitted
+build (0.155.0-alpha.2.6) and have not been rerun on this one. None of this
+qualifies arbitrary provider versions or the separate application API. xcb supervises the official
+CLI's ChatGPT device sign-in in a private profile:
+
+```sh
+xcb doctor --provider codex
+xcb accounts add codex --plan ChatGPT
+xcb accounts login <account-id>
+xcb accounts refresh <account-id>
+xcb models
+```
+
+Follow the device sign-in instructions shown in the terminal. Alternatively,
+copy one existing ChatGPT credential into a new xcb account by selecting its
+private `auth.json` explicitly:
+
+```sh
+xcb accounts import-codex --source /absolute/path/to/auth.json
+xcb accounts refresh <account-id>
+```
+
+The source file is preserved. Import does not copy provider configuration,
+plugins, sessions, or transcripts. API-key credentials are not accepted by this
+route. Refreshed ChatGPT credentials are persisted only after the owned provider
+process has joined.
+
+### Connect Devin on macOS
+
+Use the exact admitted **3000.11.3** build; **3000.11.1** and **3000.10.31**
+remain admitted. All passed credential-free native boundary checks; authenticated coding
+acceptance requires separate evidence for the account, model, and build.
+Model availability is checked against the connected account's fresh catalog at
+launch. xcb preserves an unknown quota reset as unknown. Sign in through the
+provider CLI, then explicitly select its
+`credentials.toml` to create a private xcb account:
+
+```sh
+devin auth login
+xcb doctor --provider devin
+xcb accounts import-devin --source /absolute/path/to/credentials.toml
+xcb accounts refresh <account-id>
+xcb models
+```
+
+The source file and provider sessions are preserved. xcb copies only the
+credential for the supported provider endpoints. To update just the catalog,
+use `xcb models refresh devin --account <account-id>`; Devin discovery requires
+an explicitly connected account. Native Devin currently uses fixed ACP model
+choices. Adaptive and Fusion catalog representations in the compatibility
+package do not establish native support.
+
+For either provider, `xcb run` automatically selects an eligible model. An
+optional explicit default for direct interactive sessions can be set with a
+full matching key from `xcb models` using `xcb models default <key>`. Select the account with
+`xcb accounts default <account>` for new direct sessions, or pass
+`--account <account> --model <key>` to `xcb run`. A provider upgrade is not
+automatically admitted; xcb keeps routing the pinned qualified build until an
+xcb release qualifies the new artifact.
+
+### Isolated tests, builds, and Git
+
+Project commands use an explicitly provisioned Linux VM through `workspace_exec`.
+Follow the [command runner setup](docs/command-runner.md#setup-and-admission)
+from the same source checkout as the installed native CLI. Commands run offline
+against a staged workspace; host dependencies, credentials, and build products
+are excluded. Native macOS and Xcode builds are unavailable. The explicit
+[public dependency preparation frontend](docs/command-runner.md#dependencies-and-git)
+passed the current VM boundary suite, including rejection of a cache after its
+manifest changed. Installed Claude and Codex coding workflows passed on macOS
+ARM64 with the tested accounts; other repositories and toolchains still need
+their own checks.
+
+The Git projection is limited to filtered, read-only HEAD and index data for
+status and diffs. Original history, remotes, and hooks are omitted; commit and
+push workflows are unavailable. Publication checks file revisions and replaces
+each file atomically; it is not a transaction across every changed file. Failed,
+cancelled, or uncertain command state is retained. Successfully published and
+durably settled commands remove their verified input snapshot.
+
+### Application integration
+
+The [application API](docs/application-api.md) provides bounded, ephemeral
+inference with no tools or hooks. It requires evidence for the exact xcb binary,
+provider, account and model before accepting application traffic.
+[Textbutler](https://github.com/hraness/textbutler), an MIT-licensed reference
+application, keeps its contact access and messaging approval in its own host.
+Sign-in and a successful `doctor` alone do not qualify the application route.
+
+### Everyday commands
+
+```sh
+xcb                                              # your thread, from any directory
+xcb --cwd /absolute/path/to/your/project       # the thread, hinting this project
+xcb chat --new                                   # a new project view for this directory
+xcb conversations                                # the thread and project views
+xcb chat --resume <conversation-id>
+xcb workspaces                                   # project directories the thread picks from
+xcb tasks                                        # global managed task swarm
+xcb backlog                                      # backlog and work history across projects
+xcb attention                                    # questions, approvals and actions
+xcb schedules                                    # durable recurring prompts
+xcb projects                                     # project goals and remaining autonomy grants
+xcb memory status <dir>                          # explicit Wordcell binding
+xcb service status                               # opt-in macOS login startup
+xcb tasks verify <task-id>                       # verify local transition receipts
+xcb tasks messages <task-id>                     # durable cross-provider mailbox
+xcb offers --refresh                             # refresh official expiring offers
+xcb models tiers --task "fix a race"             # inspect Pareto layers
+xcb models route --task "fix a race"             # preview the eligible smart route
+xcb --cwd /absolute/path/to/your/project run --account <account-id> -p "Explain this repository"
+xcb sessions                                     # direct provider sessions
+xcb resume                                       # latest direct provider session
+xcb resume <session-id>
+xcb accounts
+xcb config
+xcb plugins
+xcb panes
+xcb doctor
+xcb completions zsh > /path/to/completions/_xcb
+```
+
+For another program — typically a coding agent — `xcb --json route` is the
+closed machine contract: one JSON task document on stdin selects an eligible
+account/model route and runs exactly one bounded turn, returning the selected
+route, saved session id, and settled outcome facts as bounded JSON. See
+[the route contract](docs/route.md).
+
+`xcb chat --resume` reopens the thread or a project view; `xcb resume` opens a saved
+direct provider session and its workspace. Neither is a headless continuation
+command. `/help` lists terminal commands. The [terminal guide](docs/terminal.md)
+covers editing keys, optional Vim editing, transcript search, agent guidance,
+and draft recovery.
+Conversations, tasks, provider
+sessions, and credentials live in the private native state root
+`~/.local/share/xcb`; `--state /absolute/path` or `XCB_STATE` overrides it.
+The `xcb-compat` compatibility CLI uses `~/.xcb` instead. Do not point both
+implementations at the same state directory. `xcb --json run` includes the native session ID
+in its result so it can be reopened with `xcb resume <session-id>`.
+
+One provider turn has a 30-minute default deadline, including initialization.
+The `turn_timeout_ms` setting in the private state root's `config.json` accepts
+1,000–3,600,000 milliseconds (one second to 60 minutes); `xcb config` displays the
+effective configuration. Older configurations that omit it use the default.
+Cancellation remains available before the deadline, and automatic continuation
+has its own separate limits.
+
+Control conversations are concurrent and share one durable task supervisor.
+Each account still owns at most one active provider turn, and one workspace can
+have only one admitted writer even when different accounts or terminals are
+available. Independent workspaces and accounts can run concurrently; a
+workspace and a directory inside it take turns. Managed
+cancellation may be requested from the task’s originating conversation or by an
+explicit task ID/title elsewhere. In the thread, a bare `/cancel` cancels the
+selected task or the only cancellable one; when several could be cancelled it
+asks which, listing each task's project. Direct provider-session cancellation is
+owned by its terminal. Ctrl-C and SIGTERM request bounded cleanup for a headless
+run. `xcb run` reports success only for a completed, joined, settled idle result.
+
+Cancellation joins the owned process before releasing custody. If `doctor`
+reports an unsettled run, inspect `xcb recover` and the process state; an expired
+lease or a quiet terminal is not proof that the provider stopped. Recovery is
+an explicit operation, not a reason to delete state or lock files.
+
+### Fleet and remote devices
+
+Each machine can enroll as a device on a shared relay fleet. Linked machines
+publish an encrypted presence and task projection and accept fenced commands;
+a controller device or another enrolled machine drives them through the same
+CLI. Remote task content stays encrypted at the device boundary.
+
+```sh
+xcb link --relay <relay-url> --email <owner email>   # enroll this machine (email one-time code)
+xcb remote admit <device>                          # admit a newly linked device
+xcb fleet                                          # devices, presence, projection staleness
+xcb dispatch <device> <workspace> -p "<task>"      # run a managed task on a remote machine
+xcb remote status <command-id> --wait              # wait for a posted command to settle
+xcb remote steer|cancel|answer <device> <task>     # drive a remote task
+```
+
+Ids may be typed as unambiguous prefixes (`xcb remote cancel 513c t_a65b`).
+Every remote verb is `--json`-scriptable with closed exit codes, which is the
+contract a driving agent (for example a bot) should use. See
+[remote operations](docs/remote-operations.md) for enrollment, controller
+semantics and recovery.
+
+### Optional behavior
+
+Auto-continue and Gobstopper context management default on with bounded
+continuation and settled-boundary checks. Disable either with
+`xcb plugins disable auto-continue` or `xcb plugins disable gobstopper`.
+Local usage measurement stays local. aiCharts upload is unavailable; local
+exports, external judgment, and executable hooks require separate opt-in.
+Panes are presentation data and cannot grant execution authority.
+
+The optional judge uses TypeSafe System One (`jev-latest`) to advise routing,
+continuation, and context retention. It sends bounded task/response context to
+that service; old tool-result bodies are excluded from compaction advice.
+A judge cannot qualify a provider or bypass deterministic safety gates.
+Store a key through stdin on macOS or Linux, then explicitly enable it:
+
+```sh
+xcb judge token < /secure/path/to/judge-key
+xcb judge status
+xcb judge enable
+xcb judge test
+# Later:
+xcb judge disable
+xcb judge logout
+```
+
+The input file is an existing private credential file, not a command-line key.
+Keys are vaulted mode-0600 outside the workspace. `XCB_JEV_API_KEY` or
+`TYPESAFE_API_KEY` may supply a key via the environment. Custom endpoints require
+an explicit environment key; the vaulted key remains bound to System One.
+
+## Migrating from AgentMixer
+
+The native command imports **one Claude credential**, preserving the source:
+
+```sh
+xcb accounts import-agentmixer --source /absolute/path/to/.agentmixer
+```
+
+The account name comes from the observed provider identity. It does not
+migrate transcripts or sessions. The `xcb-compat` compatibility CLI has its
+own `migrate` command and identifier changes; see the
+[compatibility migration reference](docs/compatibility.md#migrating-from-agentmixer).
+Do not run compatibility migration commands against the native state root.
+
+## Standalone package
+
+The retained TypeScript source provides host-owned routing, account custody,
+bounded tools, and provider adapters. It is separate from the native Rust app.
+For building it locally, library examples, qualification requirements, and its
+CLI commands, see the [compatibility reference](docs/compatibility.md) and
+[managed Codex contract](MANAGED-CODEX.md). The
+[publishing contract](docs/publishing.md) describes future verified artifacts;
+it is not evidence of a published package.
+
+## Development
+
+See [Contributing](CONTRIBUTING.md) for setup and the native, compatibility, and
+site checks. The credential-free [native Codex boundary fixtures](qualification/codex-native.md)
+and [native Devin boundary fixture](qualification/devin-native.md) document
+repeatable checks separately from authenticated live acceptance.
+Release notes live in [CHANGELOG.md](CHANGELOG.md).
+Report vulnerabilities through [Security](SECURITY.md). Licensed under [MIT](LICENSE).

package/dist/accounts.d.ts

@@ -0,0 +1,46 @@
+import type { SqliteDatabase } from "./sqlite-port.ts";
+import { type AgentProvider } from "./validation.ts";
+export type AccountLease = Readonly<{
+    provider: AgentProvider;
+    accountId: string;
+    owner: string;
+    generation: number;
+    expiresAt: number;
+}>;
+export interface AccountLeaseStore {
+    acquire(input: {
+        provider: AgentProvider;
+        accountId: string;
+        owner: string;
+        now: number;
+        ttlMs: number;
+    }): AccountLease;
+    renew(lease: AccountLease, now: number, ttlMs: number): AccountLease;
+    release(lease: AccountLease): boolean;
+    /** Optional read of a currently held lease, for host recovery flows. */
+    inspect?(provider: AgentProvider, accountId: string): AccountLease | null;
+    /** Optional host recovery; proveStopped must supply independent
+     * process-exit evidence — a TTL or heartbeat is never sufficient. */
+    recover?(lease: AccountLease, proveStopped: (lease: AccountLease) => Promise<boolean>): Promise<boolean>;
+}
+/**
+ * Shared host database, outside every agent workspace. A heartbeat deadline is
+ * diagnostic, never permission to steal custody from a possibly live process.
+ */
+export declare class SqliteAccountLeases implements AccountLeaseStore {
+    private readonly db;
+    constructor(db: SqliteDatabase);
+    acquire(input: {
+        provider: AgentProvider;
+        accountId: string;
+        owner: string;
+        now: number;
+        ttlMs: number;
+    }): AccountLease;
+    renew(lease: AccountLease, now: number, ttlMs: number): AccountLease;
+    /** Call only after the adapter proves its provider process/controller stopped. */
+    release(lease: AccountLease): boolean;
+    inspect(providerValue: AgentProvider, accountId: string): AccountLease | null;
+    /** Host recovery supplies independent process custody evidence; no automatic TTL recovery. */
+    recover(lease: AccountLease, proveStopped: (lease: AccountLease) => Promise<boolean>): Promise<boolean>;
+}

package/dist/broker-descriptors.d.ts

@@ -0,0 +1,5 @@
+import { type BrokerToolName } from "./broker.ts";
+import type { CapabilityDescriptor } from "./capabilities.ts";
+/** Descriptions shared by native tool inventories and application profiles.
+ * createToolBroker remains the semantic parser and effect authority. */
+export declare function brokerDescriptors(names: readonly BrokerToolName[]): readonly CapabilityDescriptor[];

package/dist/broker.d.ts

@@ -0,0 +1,62 @@
+export interface WorkspaceFiles {
+    /** Host must confine resolution by directory handle, reject links, and bound IO. */
+    read(workspaceId: string, path: string, signal: AbortSignal): Promise<{
+        text: string;
+        revision: string;
+    }>;
+    /** Conditional writes prevent an agent from overwriting a concurrent human edit. */
+    write(workspaceId: string, path: string, text: string, expectedRevision: string | null, signal: AbortSignal): Promise<{
+        revision: string;
+    }>;
+}
+export interface PublicWeb {
+    /** Host validates DNS addresses and every redirect; refuses private IPs, credentials and local services. */
+    fetchPublic(url: string, maxBytes: number, signal: AbortSignal): Promise<{
+        text: string;
+        url: string;
+    }>;
+}
+export interface ScopedMessaging {
+    /** Stages an intent only. The host owns later disclosure, enrollment, journaling and dispatch. */
+    stage(workspaceId: string, runId: string, operation: MessageOperation, signal: AbortSignal): Promise<{
+        intentId: string;
+    }>;
+}
+export type MessageOperation = Readonly<{
+    kind: "text";
+    text: string;
+    idempotencyKey: string;
+}> | Readonly<{
+    kind: "reaction";
+    messageId: string;
+    reaction: "love" | "like" | "dislike" | "laugh" | "emphasize" | "question";
+    idempotencyKey: string;
+}> | Readonly<{
+    kind: "attachment";
+    path: string;
+    caption: string;
+    idempotencyKey: string;
+}>;
+export declare const BROKER_TOOL_NAMES: readonly ["files.read", "files.write", "web.fetch", "messages.propose_text", "messages.propose_reaction", "messages.propose_attachment"];
+export type BrokerToolName = typeof BROKER_TOOL_NAMES[number];
+export interface ToolBroker {
+    readonly workspaceId: string;
+    readonly runId: string;
+    readonly tools: readonly BrokerToolName[];
+    invoke(name: unknown, input: unknown): Promise<unknown>;
+    revoke(): void;
+}
+/** One capability-bound broker per run. Input never selects another workspace or recipient. */
+export declare function createToolBroker(options: {
+    workspaceId: string;
+    runId: string;
+    files: WorkspaceFiles;
+    web: PublicWeb;
+    messaging: ScopedMessaging;
+    isActive: () => boolean;
+    signal?: AbortSignal;
+    allowedTools?: readonly BrokerToolName[];
+}): ToolBroker;
+export declare function relativeFile(value: unknown): string;
+/** First-pass URL syntax guard; the host transport must also enforce DNS and redirects. */
+export declare function publicHttpsUrl(value: unknown): string;