@sailorbridge/client 0.2.4 → 0.2.6

package/README.md

@@ -17,6 +17,11 @@ writable and its `bin` directory is on `PATH`. Prefer a user-owned Node install
 from tools such as nvm/asdf over `sudo npm install -g`. Linux and macOS are the
 supported targets; Windows packaging support is deferred.
 
+The host service records the PATH of the shell that installed it, because no
+systemd user unit or launchd agent inherits one. After changing where your tools
+live — an nvm/asdf version switch, a new Homebrew prefix — re-run
+`sailorbridge host service install` so the service picks up the new PATH.
+
 Upgrade an npm-installed client and reload a running managed host daemon in one
 step:
 
@@ -80,7 +85,34 @@ sailorbridge login
 host pairing code, waits for console/mobile approval, writes a 0600 credentials
 file at `~/.sailorbridge/credentials.json`, and then installs and starts the
 host service so the console can start workers and agents on this machine without
-a second command.
+a second command. A pending pairing is also stored with mode 0600: restarting
+`login` within the 10-minute code lifetime resumes the same code. Transient
+429/5xx/network failures use capped exponential backoff until that deadline;
+an expired/rejected code or 401/403 fails immediately and tells you to run
+`sailorbridge login` for a new code.
+
+Before pairing, `login` asks what the host is for and prints one preflight
+checklist for that answer, so a missing prerequisite surfaces while the user is
+still at the keyboard instead of when their first member fails to start:
+
+| Requirement | Dev-pair host | Worker-only host |
+| --- | --- | --- |
+| Node.js >= 20 | required | required |
+| `git` executable | required | not used |
+| tmux | required | not used |
+| `claude` or `codex` CLI, logged in | required (either one) | not used |
+
+Pass `--worker-only` (or `SAILORBRIDGE_WORKER_ONLY=1`) to skip the dev-pair
+items; an interactive login asks once, and a non-interactive login checks the
+full dev-pair list. The login preflight checks that git is installed but does
+not inspect the current directory; the repository is named when a team is
+created. Workers advertise `podman`, `git`, `kubectl`,
+`perf` and `bpftrace` as capabilities when present; none are required.
+
+A failing item never blocks pairing — the report prints the exact command that
+fixes it. tmux can be installed with consent (the exact command is shown first);
+engine CLIs and their logins are always left to the user, since the credential
+is theirs.
 
 Common commands:
 
@@ -89,10 +121,13 @@ sailorbridge --help
 sailorbridge login
 sailorbridge upgrade
 sailorbridge workflow
-sailorbridge mailbox peek "$SAILORBRIDGE_AGENT_NAME"
-sailorbridge mailbox ack MESSAGE_ID --lease-token LEASE_TOKEN
+sailorbridge mailbox peek
+sailorbridge mailbox claim
+sailorbridge reply --in-reply-to MESSAGE_ID REPLY --body-file ./reply.txt
+sailorbridge mailbox ack MESSAGE_ID --lease-token-file ./lease-token
 printf '%s\n' 'hello $USER `date` $(pwd)' | sailorbridge mailbox send --to-agents ab_hand --tag BTW
-sailorbridge mailbox send --to-roles reviewer --session ab --tag PLAN-REVIEW --body-file ./plan.txt
+sailorbridge mailbox send --to-roles reviewer --tag PLAN-REVIEW --body-file ./plan.txt
+sailorbridge mailbox send --to-agents captain --tag REPORT --body-file ./report.txt
 sailorbridge enrollment --session ab --agent ab_hand --roles operator
 sailorbridge host register
 sailorbridge host consume --once --dry-run-start
@@ -101,8 +136,8 @@ sailorbridge host service status
 sailorbridge worker list
 sailorbridge worker run --worker dev-1 -- uname -s
 sailorbridge worker job JOB_ID
-sailorbridge worker serve --worker dev-1 --workdir "$PWD"
-sailorbridge supervise --agent ab_hand --cli codex --cwd "$PWD" --i-own-this-agent
+sailorbridge worker serve
+sailorbridge supervise --cli codex --cwd "$PWD" --i-own-this-agent
 ```
 
 `worker list`, `worker run`, and `worker job` are member-runtime commands;
@@ -132,7 +167,7 @@ The package installs a `sailorbridge` bin after build:
 ```bash
 bun run build
 node dist/src/cli.js workflow
-node dist/src/cli.js mailbox peek "$SAILORBRIDGE_AGENT_NAME"
+node dist/src/cli.js mailbox peek
 ```
 
 Build a native standalone binary for the current host:
@@ -164,7 +199,7 @@ SAILORBRIDGE_CAPTAIN_ID=100
 SAILORBRIDGE_SESSION=session
 SAILORBRIDGE_HOST_ID=mac
 SAILORBRIDGE_HOST_DISPLAY_NAME="Mac"
-SAILORBRIDGE_HOST_WORKSPACES=~/project-a:~/project-b
+SAILORBRIDGE_HOST_CONFIG_FILE=~/.sailorbridge/host-config.json
 SAILORBRIDGE_API_URL=https://www.sailorbridge.com
 SAILORBRIDGE_CREDENTIALS_FILE=~/.sailorbridge/credentials.json
 SAILORBRIDGE_WORKER_NAME=dev-1
@@ -185,14 +220,42 @@ the token, captain id, and session. Agent routing uses the separate
 `SAILORBRIDGE_HOST_ID` and `SAILORBRIDGE_HOST_DISPLAY_NAME` identify the
 captain-scoped local host for Tier 6 console start-request polling. When omitted,
 host commands default both values from the OS hostname.
-`SAILORBRIDGE_HOST_WORKSPACES` is an explicit opt-in inventory list for host
-daemon reporting, split by the platform path delimiter (`:` on Linux/macOS). The
-daemon reports only those declared git workspaces, including `remote.origin.url`
-and the current branch, so the console can queue an isolated clone from that
-origin. It does not scan home directories.
-
-Every 6 hours the host daemon also runs a scratch sweep over each declared
-workspace, reaping `<root>/.agent/tmp/` (a git-ignored scratch directory): it
+A host keeps no list of "its" repositories: a repository belongs to a team, and
+its absolute path on the host is named per team (`create ... --repo-path`, or the
+path field in the console's team wizard). The daemon never scans or reports the
+directories on a host.
+
+`SAILORBRIDGE_HOST_CONFIG_FILE` redirects the local host config
+(`~/.sailorbridge/host-config.json` by default) that `host account` writes and
+the daemon reads.
+
+## Running members on more than one engine account
+
+By default every member on a host uses that host's own engine directory
+(`CLAUDE_CONFIG_DIR`/`CODEX_HOME`, else `~/.claude`/`~/.codex`) — one account,
+zero configuration. To run members on several logins, register each login
+directory under a name of your choosing and point members at it:
+
+```bash
+sailorbridge host account add C1 ~/.claude-accounts/C1
+sailorbridge host account add C2 ~/.claude-accounts/C2
+sailorbridge host account set alice C1
+sailorbridge host account set bob C2
+sailorbridge host account list
+```
+
+`add` refuses a directory that holds no engine credential, so an account nothing
+could start on is rejected while you are still at the keyboard. A member with no
+pointer keeps using the host default directory. Moving a member is
+`host account set MEMBER ACCOUNT` (or `default` to clear it); it takes effect on
+that member's **next start or relaunch**, because the engine reads its credential
+at boot. Members sharing an account share one physical credential file, so a
+token refresh in any of their sessions is visible to all of them. SailorBridge
+stores only the pointer — the credential never enters product storage, logs, or
+the relay, and the console shows the account NAME read-only.
+
+Every 6 hours the host daemon also runs a scratch sweep over each member
+worktree it owns, reaping `<root>/.agent/tmp/` (a git-ignored scratch directory): it
 deletes git-untracked files older than 7 days, then evicts oldest-first until the
 directory total is under 512 MiB. It only ever touches untracked files inside that
 directory, never follows symlinks, and skips (with a log) any workspace whose
@@ -226,7 +289,9 @@ status never completes a SailorBridge task lifecycle.
 
 `sailorbridge login` creates a host pairing against
 `https://www.sailorbridge.com`. The command displays the one-time code and
-polls until approval. The stored credential contains a host-scoped relay key
+polls until approval. Deploy-time 429/5xx/network interruptions do not replace
+an unexpired code, and restarting the command resumes its pending pairing.
+The stored credential contains a host-scoped relay key
 (`key_scope: "host"` plus `host_id`) and is used as a fallback when
 `SAILORBRIDGE_RELAY_URL` or `SAILORBRIDGE_TOKEN` are not set. Worker data
 commands reject this host-scoped fallback before any relay request. Raw host
@@ -286,6 +351,12 @@ Claude uses `$CLAUDE_CONFIG_DIR/.credentials.json` when set, otherwise
 `~/.claude/.credentials.json`.
 The per-agent sandbox links to that single host auth file; missing engine auth
 fails fast instead of starting a CLI that will prompt for credentials.
+The host daemon also reads the default Claude subscription OAuth credential
+once per day to list provider model metadata. It sends one `GET /v1/models`
+request with a 10-second timeout and no retry, then reports model ids only to
+the relay. The OAuth token stays in the provider request header and never
+enters relay payloads, logs, errors, or argv. API-key-only and Codex-only hosts
+skip this probe; Codex has no machine-readable subscription catalog source.
 
 Worker commands implement both sides of the relay worker contract from
 `engine/PROTOCOL.md`: register, heartbeat, pull, stream upload, result posting,
@@ -298,11 +369,19 @@ non-destructive command. Add `--lease` to a claim only to include rows already
 leased by this client. A supervisor peek leaves workflow-obligation messages
 queued and claimable after it surfaces the body-free doorbell. The bound agent's
 first `mailbox claim` leases them, then the agent completes the required action.
-Direct workflow messages are acknowledged with the lease token returned by the
-claim. Durable task sources are acknowledged by their successful task
-transition, while task terminal replies and `UNPARKED` are auto-acked after
-delivery. Ordinary and control messages keep their existing acknowledgement
-behavior.
+Plain claims expose every lease token. `HUMAN` and `MAIL` stay leased so
+`reply --in-reply-to` can infer the sender and atomically record the reply plus
+source ACK; untagged peer mail is shown and handled as `MAIL`. If the exact
+source cannot be reclaimed, the CLI identifies whether it is missing, settled,
+addressed to another agent, or a transcript-only row and prints the next action.
+`--no-ack` leaves the source leased. Other direct workflow messages
+retain their manual ACK or durable-transition settlement.
+ACK lease tokens must stay out of argv: store the surfaced token in a private
+file and use `mailbox ack MESSAGE_ID --lease-token-file PATH`, or pipe exactly
+the token to `mailbox ack MESSAGE_ID --lease-token-file -`. Empty input, a TTY,
+duplicate token sources, and piped input unused by a file path are rejected.
+`--lease-token TOKEN` is deprecated for one release and exists only for
+compatibility.
 
 Mailbox send is footgun-free by construction: message bodies are read only from
 piped stdin or `--body-file`, never from positional argv. Every `--body-file` and
@@ -312,8 +391,9 @@ that another selected source would discard is rejected instead of silently
 ignored; commands without a stdin contract reject it before any relay request.
 This prevents the local
 shell from expanding `$VARS`, backticks, or `$()` before the client starts. A
-single `--to-agents A` sends directly to that agent even when `--session` is also
-present. Multiple explicit agents use the session mailbox endpoint. `--to-agents`
+single `--to-agents A` sends directly to that agent, except reserved `captain`,
+which uses the session transcript endpoint. Multiple explicit agents use the
+session mailbox endpoint. `--to-agents`
 is mutually exclusive with `--to-roles` and `--to-host`; combine roles and host
 when filtering registered agents. An empty pipe sends an empty string body; an
 interactive TTY with no pipe fails fast instead of waiting for typed input.
@@ -341,10 +421,10 @@ interactive pane. Host-started agents use readable session names such as
 `sb-<team>-<role>` and append the captain number only when that default already
 exists on the host.
 
-Tmux launch environment is passed through tmux process mechanisms (`-e` and the
-child process environment), never as `KEY=value command` text typed into the
-pane. That still has the normal short-lived process-list exposure of command
-arguments; cleaner secret delivery belongs to a later transport release.
+Tmux launch environment is handed directly to the new pane through a private,
+one-shot FIFO. The pane imports it immediately before `exec`; bearer values
+never enter tmux argv, the tmux environment store, pane input, or a regular
+credential file.
 
 SDK drivers are optional implementation code and are release-gated from the
 public Phase 1 CLI. A base install or tmux-only caller does not need to
@@ -391,6 +471,29 @@ channel must have one owner, otherwise mailbox leases can be stolen. Use
 `sailorbridge supervise` only for agents not already driven by another
 listener/supervisor.
 
+Context auto-checkpoint (tmux transport, claude/codex): the supervisor reads
+the context percentage from the pane every ~20s and, at or above the agent's
+configured `context_checkpoint_percent` (console setting; `0` disables,
+default 75), posts one self-addressed `SAVE-CONTEXT`. The mailbox loop then
+cues the `save_ctx` skill, waits for `SAVE-CONTEXT-DONE`, and replays
+`/clear` plus the `resume_ctx` cue. Threshold changes made in the console
+take effect live through the `reload_context_autopilot` resolve command.
+Semantics match the engine listener's autopilot (same thresholds, same
+armed-below/fire-once water-mark).
+
+Idle pre-save (tmux transport, claude by default): the same loop watches for a
+member that has gone quiet. Once the pane is visibly idle and the newest real
+mailbox activity is older than `idle_presave_min` (console setting; `0`
+disables, empty takes the engine default — claude 50 minutes, codex off) but
+still younger than the engine's prompt-cache TTL, the supervisor re-samples pane
+and activity and then posts one `SAVE-CONTEXT` carrying
+`source=listener-idle-presave`. That checkpoint is **ACK-only**: the handoff is
+written, but nothing clears, resumes, or relaunches — a member that merely sat
+idle keeps its live context. One archive per span of activity, a 30-minute
+cooldown after each attempt, and every unknown (capture failure, busy pane,
+missing or future activity timestamps) is a no-op. Tables are pinned against the
+engine listener by `tooling/e2e/idle-presave-parity.test.ts`.
+
 Default transport selection:
 
 | CLI | Default transport | Default command |
@@ -448,7 +551,7 @@ message. Persistent relay errors back off instead of spinning.
 The CLI entrypoint is explicit about ownership:
 
 ```bash
-sailorbridge supervise --agent A --cli codex --cwd /repo --i-own-this-agent
+sailorbridge supervise --cli codex --cwd /repo --i-own-this-agent
 ```
 
 `--i-own-this-agent` is required as a runtime collision guard. For tmux launches,