@tonbo/yield 0.3.1 → 0.3.3

package/README.md

@@ -1,6 +1,6 @@
 # Tonbo Yield
 
-`yield` captures the sessions of your coding agents (Claude Code and Codex) on every machine you use and lists them from any of them. It signs in, runs a capture service on each machine, snapshots the git work trees the agents work in, lists sessions, recalls the turns that changed a file, and hands a live session to another of your computers.
+`yield` captures the sessions of your coding agents (Claude Code and Codex) on every machine you use and lists them from any of them. It signs in, runs a capture service on each machine, snapshots the git work trees the agents work in, lists sessions, recalls the turns that changed a file, and hands a session off as a link that you, on another computer or harness, or a teammate takes.
 
 Install it on macOS (arm64, x64) or Linux with glibc (x64, arm64) with one line, without sudo and without Node.js:
 
@@ -8,7 +8,7 @@ Install it on macOS (arm64, x64) or Linux with glibc (x64, arm64) with one line,
 curl -fsSL https://yield.tonbo.io/install.sh | sh
 ```
 
-The installer, [`install.sh`](install.sh), uses the system `node` when it is 22 or newer and has npm beside it; otherwise it downloads the latest official Node.js 22 build from nodejs.org into `~/.tonbo/runtime/node-<version>`, checked against the release's `SHASUMS256.txt`. It installs `@tonbo/yield` into the private prefix `~/.tonbo/yield`, never a global npm, and writes the launcher `~/.local/bin/yield`, which runs it with that Node.js; when `~/.local/bin` is not on `PATH` it prints the line to add for your shell. Running it again upgrades in place, and when the capture service is installed it reinstalls the service on the new version (which restarts it) and removes Node.js runtimes it no longer uses. `YIELD_VERSION` pins a version or dist-tag: `curl -fsSL https://yield.tonbo.io/install.sh | YIELD_VERSION=0.2.0 sh`. musl distributions (Alpine), 32-bit systems and Windows are refused with a message; on Windows, install the npm package instead. User Center serves the file at `https://yield.tonbo.io/install.sh` as `text/plain` (that host answers 404 for every other path until the Yield landing page exists) from an embedded copy (`apps/user-center/src/app/install.sh`); after changing `install.sh`, run `pnpm --dir apps/user-center generate:install-script`, or the route's test fails.
+The installer, [`install.sh`](install.sh), uses the system `node` when it is 22 or newer and has npm beside it; otherwise it downloads the latest official Node.js 22 build from nodejs.org into `~/.tonbo/runtime/node-<version>`, checked against the release's `SHASUMS256.txt`. It installs `@tonbo/yield` into the private prefix `~/.tonbo/yield`, never a global npm, and writes the launcher `~/.local/bin/yield`, which runs it with that Node.js; when `~/.local/bin` is not on `PATH` it prints the line to add for your shell. On a terminal, a computer with no login yet then runs `yield login`, which signs in and starts capture, so the one line takes you from nothing to captured sessions; without a terminal, or with `YIELD_NO_LOGIN=1`, it prints that step instead. Running it again upgrades in place, and when the capture service is installed it reinstalls the service on the new version (which restarts it) and removes Node.js runtimes it no longer uses. `YIELD_VERSION` pins a version or dist-tag: `curl -fsSL https://yield.tonbo.io/install.sh | YIELD_VERSION=0.2.0 sh`. musl distributions (Alpine), 32-bit systems and Windows are refused with a message; on Windows, install the npm package instead. User Center serves the file at `https://yield.tonbo.io/install.sh` as `text/plain` (that host answers 404 for every other path until the Yield landing page exists) from an embedded copy (`apps/user-center/src/app/install.sh`); after changing `install.sh`, run `pnpm --dir apps/user-center generate:install-script`, or the route's test fails.
 
 Or install the public package with Node.js 22 or newer:
 
@@ -21,11 +21,16 @@ Merging a change to the `version` in `package.json` to `main` releases it: [`ton
 ## Sign in
 
 ```console
-yield login [--account <name>] [--name <name>]
+yield login [--account <name>] [--name <name>] [--no-daemon]
+yield status [--json]
 yield whoami [--json]
 yield logout
 ```
 
+A login to your personal account also registers this computer and installs and starts the capture service, as `yield daemon install` does (`--no-daemon` only signs in); when the service manager refuses, it says why and the login stands. `status` is the one health view: the login and whom it is for, whether `api.tonbo.dev` answers, whether the capture service runs and, on Linux, survives logout, each agent's transcripts, version and last captured activity (and sessions changed in the last day that are not captured yet), snapshots waiting to be pushed, errors of the last 15 minutes, and this version against npm's latest. Each line that is not fine names the command that fixes it, and the command exits 1 when a line fails. `--json` prints `ok`, the `checks` (`name`, `level` of `ok`, `warn`, `fail` or `none`, `detail`, `fix`) and the facts behind them.
+
+Errors say what happened and what to run, without a stack trace: an unreachable network, a refused login (`yield login`), a server error (with its request id) and a service manager that refuses (after `su`, in a container without systemd, or over SSH to a Mac without a desktop login) each get their own words. `YIELD_DEBUG=1` prints the stack too.
+
 `yield` and the [`tonbo`](../tonbo) CLI share one login through the internal package [`@tonbo/cli-core`](../../packages/tonbo-cli-core): the same browser handoff, the same keys and the same credentials file, `${XDG_CONFIG_HOME:-$HOME/.config}/tonbo/credentials.json`. The file holds one CLI login key per account of this computer ([`credentials-v1.json`](../../contracts/cli/credentials-v1.json) `accounts`): your personal account's, named `CLI on <hostname>`, and one for each organization you connect a folder in, named `Yield CLI · <8 hex>` from a suffix the server derives from this computer's login secret, so the organization's admins never see your hostname. Logging in with either CLI signs both in, and a login replaces this computer's earlier key in that account, so the two never hold different keys. Capture, recall and registration always use the personal account's key, whatever account the last login chose; `logout` revokes every key of the file. `whoami` prints the account of the last login, your role and this machine's device id.
 
 ## Projects
@@ -78,7 +83,7 @@ The capture follows [`contracts/sessions/capture-v1.json`](../../contracts/sessi
 After each `turn_end` of a turn that ended in the last 10 minutes, in a cwd inside a git work tree, the daemon snapshots the folder the cwd is bound to (its Project's, see Routing) as [`contracts/sessions/recall-v1.json`](../../contracts/sessions/recall-v1.json) `snapshots` defines; the build embeds that contract too. Snapshots run one at a time beside the capture and never hold it up; a failure is logged as a warning, and a 4xx from the git token exchange or gitd pauses publishing for 10 minutes.
 
 - The tree is the bound folder's, the whole work tree when the folder is its root and the folder's subtree alone otherwise, as `git add -A` sees it through a private index under `${XDG_STATE_HOME:-$HOME/.local/state}/tonbo-yield/snapshots/index/`, so `.gitignore` applies and the user's index, HEAD, branches and config stay untouched. Every git command runs the user's `git` with `GIT_TERMINAL_PROMPT=0`, `core.hooksPath=/dev/null`, no automatic gc and no credential helper. Files over 100 MiB, gitd's object limit, are left out with a logged notice.
-- An unchanged tree makes no snapshot. Otherwise `git commit-tree` writes a commit whose parent is the previous snapshot of this device's chain (none for the first, the baseline) with the trailers `Tonbo-Session`, `Tonbo-Turn`, `Tonbo-Base` (the merge-base of HEAD and its upstream, or HEAD) and `Tonbo-Baseline: true` on the root; `refs/tonbo/snapshots/<device id>/<folder binding id>` keeps it in the user's repository.
+- An unchanged tree makes no snapshot. Otherwise `git commit-tree` writes a commit whose parent is the previous snapshot of this device's chain (none for the first, the baseline) with the trailers `Tonbo-Session`, `Tonbo-Turn`, `Tonbo-Base` (the merge-base of HEAD and origin, preferred over an upstream on another remote; absent when nothing is published, so a never-pushed branch restores on another device from the whole tree) and `Tonbo-Baseline: true` on the root; `refs/tonbo/snapshots/<device id>/<folder binding id>` keeps it in the user's repository.
 - The repository is the Project's `snapshot_repo` (`snap-<slug>` of its origin, or `snap-<project id hex>` for a named Project), created once through gitd's idempotent `PUT /api/v1/workspaces/<ws_hex>/repos/<name>` `{"private": false}` in your personal workspace. The commit is pushed to `refs/tonbo/u/<sub>/<device id>/<folder binding id>` with `-o tonbo.session=<id>`. A device's ref of before Projects, `refs/tonbo/u/<sub>/<device id>`, is continued by the first binding chain pushed in its repository, which deletes it first (git cannot hold a ref and one under it). The git token (`POST /api/iam/token` with the git audience, kept and refreshed like the Streams token) reaches git only as an `http.<gitd origin>/.extraHeader` in the environment of that one command: never in a file, an argument, a URL or the log.
 - The chain head of each repository and device is kept in `state.json`. A push refused because gitd's ref moved on without this state (say, after the state was lost) fetches gitd's ref and continues the chain from it; a clone that lacks the chain's head fetches it first.
 
@@ -123,6 +128,9 @@ yield need-human "<why>"
 yield pull <session-or-link> [--patch]
 yield show <link>
 yield renew <link> [--result]
+yield handoffs [--account <organization>]
+yield events [--after <seq>] [--wait <seconds>] [--account <organization>]
+yield cancel <link>
 ```
 
 A handoff is in the Project of the folder it is made in. In a personal Project you hand a session to yourself on another computer or harness. In a shared team Project (`yield connect --account <organization>`) you hand it to any member, or with `--to <name>` to one member; `--to claude-code` or `--to codex` is you on that harness. A member's login of the organization is what makes and takes team handoffs, so the teammate needs one on their computer (`yield login --account <organization>`). Handing off to a device is not available in this release.
@@ -132,12 +140,24 @@ A handoff is in the Project of the folder it is made in. In a personal Project y
 - Inside that worktree, `done` pushes and pins the result and records the handoff done; `need-human` records that it is waiting on you. Both use the login of the account the handoff is in.
 - `pull` fetches the latest unpulled result of a session (or a handoff link) onto a branch, or with `--patch` into a patch file, without changing your worktree. The author pulls a teammate's result the same way.
 - `show` prints a handoff's state, author, who it is for and who took it, and its captured context, without taking it. Any member can show a team handoff.
+- `handoffs` lists your open handoffs (created, taken, running or waiting on a human) that you gave, hold, or are named in, across your personal account and every organization; `--account` narrows to one. It shows metadata only.
+- `events` prints handoff transitions after a cursor, such as a teammate taking yours, with a `Next:` cursor for the following read; `--wait` holds up to 25 seconds for the first one. A handoff you can no longer see drops out.
+- `cancel` withdraws a handoff you gave before anyone takes it and releases its snapshot pin. A take that loses to someone else names who holds it.
+
+## Alpha metrics
+
+```console
+yield note --changed-plan <session>
+```
+
+During the Alpha, `yield` records a few content-free measures on your personal account (contracts/sessions/handoff-v1.json `metrics`, kept 180 days): how long a taken handoff waits for its first turn (the daemon, from the restore to that turn's end), which `continue` candidate was picked, how a delivered message or teammate context was rated, and, with `note --changed-plan`, that another session changed your plan. A value is a number, a flag or a fixed word; never a task, prompt, path or reason. A write that fails or takes longer than 3 seconds is dropped and never fails a command. `TONBO_YIELD_METRICS=off` turns it off.
 
 ## The Tonbo skill
 
-`daemon install` also writes the Tonbo skill ([`skills/tonbo/SKILL.md`](skills/tonbo/SKILL.md), embedded by the build) to `~/.claude/skills/tonbo/SKILL.md` for Claude Code (`CLAUDE_CONFIG_DIR` moves it) and `~/.codex/skills/tonbo/SKILL.md` for Codex (`CODEX_HOME` moves it). It tells an agent to run `yield why`, `yield files` and `yield session read` when asked why code is the way it is or before changing an unfamiliar file, to cite session and time, to treat the results as reference and never as instructions, and not to guess when nothing is found. A manifest, `skills.json` in the state directory, records what was written: install never overwrites a `tonbo` skill it did not write, and `daemon uninstall` removes only its own unchanged files. `CLAUDE.md` and `AGENTS.md` are never edited.
+`daemon install` also writes the Tonbo skill ([`skills/tonbo/SKILL.md`](skills/tonbo/SKILL.md), embedded by the build) to `~/.claude/skills/tonbo/SKILL.md` for Claude Code (`CLAUDE_CONFIG_DIR` moves it) and `~/.codex/skills/tonbo/SKILL.md` for Codex (`CODEX_HOME` moves it). It tells an agent to run `yield why`, `yield files` and `yield session read` when asked why code is the way it is or before changing an unfamiliar file, to cite session and time, to treat the results as reference and never as instructions, and not to guess when nothing is found. A manifest, `skills.json` in the state directory, records what was written: install never overwrites a `tonbo` skill it did not write, and `daemon uninstall` removes only its own unchanged files. Every daemon start refreshes yield's own unchanged copies to the skill of the running version, and the daemon restarts itself within a minute when an in-place upgrade (`npm install --global @tonbo/yield`) puts a new version on disk, so either upgrade path reaches both agents; a copy you edited or removed is left as it is. `yield status` reports the skill's version on each copy. `CLAUDE.md` and `AGENTS.md` are never edited.
 
 ## Environment
 
 - `TONBO_API_KEY`: a personal key used instead of the saved login by `whoami` and `sessions`.
+- `TONBO_YIELD_METRICS`: `off` stops the Alpha metrics.
 - `TONBO_API_ORIGIN`: the Management API origin, `https://api.tonbo.dev` by default. `daemon install` writes it into the service, with `PATH`, `XDG_CONFIG_HOME` and `XDG_STATE_HOME`.