@tonbo/yield 0.1.1 → 0.1.3

package/README.md

@@ -5,10 +5,10 @@
 Install it on macOS (arm64, x64) or Linux with glibc (x64, arm64) with one line, without sudo and without Node.js:
 
 ```console
-curl -fsSL https://tonbo.dev/install.sh | sh
+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://tonbo.dev/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 `/install.sh` as `text/plain` 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. 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:
 
@@ -26,7 +26,16 @@ yield whoami [--json]
 yield logout
 ```
 
-`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 personal key named `CLI on <hostname>` and the same credentials file, `${XDG_CONFIG_HOME:-$HOME/.config}/tonbo/credentials.json`. Logging in with either CLI signs both in, and a login replaces the host's earlier key, so the two never hold different keys. `whoami` prints the account, your role and this machine's device id.
+`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
+
+```console
+yield connect [folder] [--name <name> | --project <id>] [--account <name>] [--json]
+yield disconnect [folder]
+```
+
+`connect` binds a folder of this computer to a Project ([ADR-0016](../../apps/user-center/docs/decisions/adr-0016-org-git-workspaces.md) W-18) through `POST /v1/projects/connect`. Without a folder it binds the root of the git work tree you are in, or else the current directory. A git work tree joins the Project of its origin, made when the account has none, so every clone of one origin, on any computer, shares it; a work tree without an origin gets a Project named after its folder. A folder outside git is connected only by naming a new Project (`--name`) or joining one (`--project`). Without `--account` the Project is in your personal account; `--account <name>` binds it to that organization's Project, which needs this computer registered (`yield login`), and logs this computer in to the organization first when it has no login there, without changing the account `tonbo` acts in. A folder connected in another account moves: it is disconnected there first. The folder is named only by a random id kept in `${XDG_STATE_HOME:-$HOME/.local/state}/tonbo-yield/folders.json`; its path never leaves the computer. `disconnect` removes the folder's binding (`DELETE /v1/projects/bindings/<id>`) and leaves the Project. `yield ps` and `yield daemon status` name the current folder's Project. A folder that is not connected stays in your personal account, as before.
 
 ## The device id
 
@@ -57,10 +66,10 @@ The capture follows [`contracts/sessions/capture-v1.json`](../../contracts/sessi
 
 - It discovers the account's store once an hour through `GET /v1/sessions/store` and again whenever the store refuses a request. An account without a store (409 `sessions_store_unavailable`: no active git workspace Agent) is reported by `daemon status` and `sessions` as needing an account owner to enable git, and the daemon asks again every 10 minutes.
 - Streams does not accept the personal key itself: the client exchanges it at `POST <console origin>/api/iam/token` for a ten-minute Streams access token (`@tonbo/cli-core` `AccessTokens`), keeps it in memory, replaces it a minute before it expires, and exchanges again once after a Streams 401. A refused exchange asks for `yield login`; a 429 or 5xx is retried with backoff while the offsets stay.
-- It watches `~/.claude/projects` and `~/.codex/sessions` and rescans them every two seconds; a missing root is fine. Each file is read from its saved byte offset, and only complete lines count.
+- It watches `~/.claude/projects` and `~/.codex/sessions` and rescans them every two seconds; a missing root is fine. Each file is read from its saved byte offset, and only complete lines count. Each pass takes the most recently written files first and sends at most 8 batches of each, so a long backfill never holds back a live session, new files or state reports; the next pass starts at once while lines are left.
 - Each line, except the contract's excluded types, becomes one record of the stream `session.<session id>`. Consecutive lines go in one append request (at most the contract's `max_batch_lines` and `max_batch_bytes`), which ends early at a line that causes an inbox record. Each request carries `Producer-Id: yield/<device id>`, `Producer-Epoch` and `Producer-Seq`, the request's ordinal within the epoch; the batch's seq and byte range are saved before it is sent, so a resend after a crash is the identical batch and is answered as a duplicate. The record carries the line as written, without redaction; a line that is not JSON is uploaded as it is too.
 - When a session is first seen it appends `session_start` to `proc.inbox`, and at each turn end `turn_end` with the cwd, git root, branch, the paths written since the previous turn end (at most 50, relative to the git root inside it) and `stream_offset`, the session stream's `Stream-Next-Offset` after the turn's last record (the append's answer, or the stream's tail when a resent batch is answered as a duplicate).
-- On every pass it decides each live session's state, `running`, `waiting`, `idle` or `ended` (capture-v1 `sources.<source>.state`; [Yield session state](../../docs/design/yield-session-state.md)), and appends `session_state` to `proc.inbox` when the state or the turn changes, and while a turn runs, when it has written new paths, at most every 10 seconds. Claude Code's live-process registry (`~/.claude/sessions/<pid>.json`) gives a Claude session's liveness and status; a running `codex` process whose working directory is the session's cwd keeps a Codex session live; otherwise a session's turn decides `running` or `idle`, and a session whose liveness cannot be told ends after 30 quiet minutes. A session first seen already ended is not reported.
+- On every pass it decides each live session's state, `running`, `waiting`, `idle` or `ended` (capture-v1 `sources.<source>.state`; [Yield session state](../../docs/design/yield-session-state.md)), and appends `session_state` to `proc.inbox` when the state or the turn changes, and while a turn runs, when it has written new paths, at most every 10 seconds. Claude Code's live-process registry (`~/.claude/sessions/<pid>.json`) gives a Claude session's liveness and status; a running `codex` process whose working directory is the session's cwd keeps a Codex session live; otherwise a session's turn decides `running` or `idle`, and a session whose liveness cannot be told ends after 30 quiet minutes. A Claude session missing from the registry counts as ended only once its file has been quiet for a minute, since `claude -p` writes its transcript before its registry entry and removes the entry as it exits. A session that ends with its turn open (`claude -p` writes no `turn_duration`) has that turn's `turn_end` appended with its written paths. A session first seen already ended is not reported, but its open turn is still closed.
 - The state, `${XDG_STATE_HOME:-$HOME/.local/state}/tonbo-yield/state.json`, keeps each file's offset with its producer, sequence and epoch, and is replaced atomically. The source files are the offline queue: while the store is unreachable the offset stays and the upload is retried with backoff, honoring `Retry-After`. A new epoch starts from seq 0, saved before it is used, when Streams has forgotten the producer (idle for 7 days) or is ahead of a lost local state.
 - The first run also captures the session files changed in the last 14 days (`--since` sets the bound); older files are recorded as skipped until they change again.
 
@@ -82,7 +91,7 @@ yield ps [--all] [--limit <sessions>] [--json]
 yield sessions [--limit <records>] [--json]
 ```
 
-`ps` reads the catalog, recall's `GET /sessions` without `repo`, which the git-ingester keeps in the workspace's index from `proc.inbox`. It prints your sessions on every device, most recent activity first: the state and since when, the device (`this computer` for this one), the agent, the git root or cwd, the session and the files it recently wrote (the turn in progress's first). Ended sessions are left out unless `--all`; a session no client reported a state for shows `ended` once it is 30 minutes quiet, and `unknown` before.
+`ps` reads the catalog, recall's `GET /sessions` without `repo`, which the git-ingester keeps in the workspace's index from `proc.inbox`. It prints your sessions on every device, most recent activity first: the state and since when, the device (`this computer` for this one), the agent, the git root or cwd, the session and the files it recently wrote (the turn in progress's first). Exact paths come first; a path only a shell command appears to have written (`printf > file`, `tee`) is marked `(inferred)`. Ended sessions are left out unless `--all`; a session no client reported a state for shows `ended` once it is 30 minutes quiet, and `unknown` before.
 
 `sessions` reads `proc.inbox` itself and prints one row per session among its newest records (200 by default): the last activity, the device (`this machine` for this one), the source, the git root or cwd, the branch and the turn ends seen. `ps` supersedes it; it stays until the first-run end-to-end check (`e2e/src/yield-first-run-e2e.mjs`) reads `ps`, once the index serves personal workspaces (ADR-0016 PR 4).