@sailorbridge/client 0.2.5 → 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:
 
@@ -92,7 +124,7 @@ sailorbridge workflow
 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 LEASE_TOKEN
+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 --tag PLAN-REVIEW --body-file ./plan.txt
 sailorbridge mailbox send --to-agents captain --tag REPORT --body-file ./report.txt
@@ -167,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
@@ -188,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
@@ -229,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
@@ -289,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,
@@ -303,9 +371,17 @@ 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.
 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`.
+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
@@ -405,6 +481,19 @@ 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 |