@sailorbridge/client 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,411 @@
+# SailorBridge Client
+
+Standalone Node/TypeScript client for SailorBridge: a relay HTTP client, a debug
+CLI, a worker host runtime, and a tmux supervisor that owns one local Claude or
+Codex agent process and reports monitor state to the relay. Host pairing login
+stores a host-scoped relay key for subsequent local host commands.
+
+## Install
+
+```bash
+npm install -g @sailorbridge/client
+sailorbridge --help
+```
+
+When installing globally on Linux or macOS, make sure your npm global prefix is
+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.
+
+For a managed host daemon, use the compiled single-binary path instead of a
+Node-based global install. Build or download the native `sailorbridge` binary,
+then log in once — `login` installs and starts the user service itself:
+
+```bash
+bun run build:binary
+./bin/sailorbridge login
+./bin/sailorbridge host service status
+```
+
+The service runs `sailorbridge host run` from the binary and reads the
+host-scoped credential file. The unit/plist never embeds bearer tokens. After
+the binary is built or installed, the managed host runtime does not require
+Node, Bun, or Python on `PATH`.
+
+## Quickstart
+
+Configure relay credentials:
+
+```bash
+export SAILORBRIDGE_RELAY_URL=http://127.0.0.1:8765
+export SAILORBRIDGE_TOKEN=...
+export SAILORBRIDGE_AGENT_NAME=session_agent
+export SAILORBRIDGE_CAPTAIN_ID=100
+export SAILORBRIDGE_SESSION=session
+export SAILORBRIDGE_HOST_ID="$(hostname)"
+export SAILORBRIDGE_HOST_DISPLAY_NAME="$(hostname)"
+```
+
+Or pair this machine through the product API:
+
+```bash
+sailorbridge login
+```
+
+`login` connects to `https://www.sailorbridge.com`. The command prints a short
+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.
+
+Common commands:
+
+```bash
+sailorbridge --help
+sailorbridge login
+sailorbridge workflow
+sailorbridge mailbox peek "$SAILORBRIDGE_AGENT_NAME"
+sailorbridge mailbox ack MESSAGE_ID --lease-token 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 enrollment --session ab --agent ab_hand --roles operator
+sailorbridge host register
+sailorbridge host consume --once --dry-run-start
+sailorbridge host service install --binary /opt/sailorbridge/bin/sailorbridge
+sailorbridge host service status
+sailorbridge worker serve --worker dev-1 --workdir "$PWD"
+sailorbridge supervise --agent ab_hand --cli codex --cwd "$PWD" --i-own-this-agent
+```
+
+The package ships only the built CLI/runtime files under `dist/src/` plus this
+README. It deliberately does not publish `src/`, `tests/`, or `dist/tests/`.
+Create a release tarball with `npm run pack:staged`; it stages the current build without
+mutating the live `dist/` symlink.
+Publish that staged tarball with `npm publish sailorbridge-client-<version>.tgz`;
+do not run `npm publish` directly from this package.
+
+## Development
+
+```bash
+bun install
+bun run check
+```
+
+Building requires Perl with `Fcntl::flock` (available on supported Linux and macOS hosts).
+Builds retain immutable releases for at least one hour so in-flight readers remain
+loadable; older non-current releases are reclaimed.
+
+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"
+```
+
+Build a native standalone binary for the current host:
+
+```bash
+bun run build:binary
+./bin/sailorbridge --help
+```
+
+`build:binary` defaults to the native Bun compile target. Release automation can
+pass `--target` through `scripts/build-binary.mjs` for the supported matrix:
+
+```text
+linux-x64   -> bun-linux-x64
+linux-arm64 -> bun-linux-arm64
+darwin-x64  -> bun-darwin-x64
+darwin-arm64 -> bun-darwin-arm64
+```
+
+## Configuration
+
+Preferred environment:
+
+```bash
+SAILORBRIDGE_RELAY_URL=http://127.0.0.1:8765
+SAILORBRIDGE_TOKEN=...
+SAILORBRIDGE_AGENT_NAME=session_agent
+SAILORBRIDGE_CAPTAIN_ID=100
+SAILORBRIDGE_SESSION=session
+SAILORBRIDGE_HOST_ID=mac
+SAILORBRIDGE_HOST_DISPLAY_NAME="Mac"
+SAILORBRIDGE_HOST_WORKSPACES=~/project-a:~/project-b
+SAILORBRIDGE_API_URL=https://www.sailorbridge.com
+SAILORBRIDGE_CREDENTIALS_FILE=~/.sailorbridge/credentials.json
+SAILORBRIDGE_WORKER_NAME=dev-1
+SAILORBRIDGE_WORKDIR=~/sailorbridge-workdir
+SAILORBRIDGE_MAX_CONCURRENCY=1
+```
+
+`SAILORBRIDGE_CAPTAIN_ID` is optional for current descriptors but, when present,
+must be a numeric string. It is diagnostic identity metadata; routing still uses
+the short `SAILORBRIDGE_AGENT_NAME`.
+
+`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
+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
+`.agent/tmp/` resolves out of bounds or is not a git repository. Set
+`SAILORBRIDGE_SCRATCH_SWEEP_ENABLED=0` (or `false`/`no`/`off`) to disable it;
+it is on by default.
+
+`sailorbridge worker serve` runs the TypeScript host worker against the relay
+without importing the Python worker package. It registers the configured worker
+name, long-polls `/pull`, executes jobs inside `SAILORBRIDGE_WORKDIR`, posts
+results with the relay lease token, and streams stdout/stderr for stream jobs.
+Use `--worker`, `--workdir`, and `--max-concurrency` or the matching
+`SAILORBRIDGE_WORKER_NAME`, `SAILORBRIDGE_WORKDIR`, and
+`SAILORBRIDGE_MAX_CONCURRENCY` environment variables. `SAILORBRIDGE_MODE=readonly`
+blocks mutating job kinds locally.
+
+`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
+(`key_scope: "host"` plus `host_id`) and is used as a fallback when
+`SAILORBRIDGE_RELAY_URL` or `SAILORBRIDGE_TOKEN` are not set. Raw host keys are
+written to the credentials file only. Data commands default to
+`--format plain`; login's plain success output prints the host id, credential
+path, and service status. Explicit `--format json` prints key id and host
+metadata, not the token.
+
+`sailorbridge login` installs this service automatically; it exits 3 when
+pairing succeeded but the install did not, and states that the host remains
+offline and cannot receive console tasks before naming the command to run by hand.
+Pass `--no-service` (or set `SAILORBRIDGE_NO_SERVICE=1`) to pair only — the
+opt-out for containers, WSL, and CI images without a service manager.
+Re-running `login` refreshes the definition and restarts the daemon so it always
+runs with the arguments on disk. A markerless legacy definition is taken over
+only when its parsed executable and arguments identify `sailorbridge host run`:
+the old daemon is stopped/unloaded and the definition is renamed to a
+`.sb-legacy-<UTC timestamp>` archive before reinstall. Foreign definitions,
+symlinks, and definitions serving another host remain rejected; move a foreign
+file aside or pass `--service-name` to install a scoped
+`sailorbridge-host-<suffix>` unit.
+`sailorbridge host service install|uninstall|status` manages the long-running
+host daemon as a per-user service afterwards. Linux uses user systemd with
+`Restart=on-failure`; macOS uses a user LaunchAgent with `KeepAlive`. The service
+definition points at a credentials file and a binary path; it does not inline
+tokens. Linux `status` detects whether linger is enabled. If boot persistence is
+not active, `install` and `status` print the exact
+`sudo loginctl enable-linger <user>` command for the user to run, but never run
+sudo automatically. macOS LaunchAgents have no linger equivalent.
+
+## Relay Contract
+
+This client reimplements the relay HTTP contract in TypeScript. It does not
+import the Python SailorBridge engine, SailorBridge Site, or SailorAgent code. Key creation uses
+the observed relay contract `roles: string[]`; the legacy singular `role` field
+is deprecated and intentionally not sent.
+
+Client host commands implement the P5a relay contract from `engine/PROTOCOL.md`:
+registering or heartbeating a host, listing captain-scoped hosts, and claiming a
+single `agent_start_request`. Host-paired credentials are limited to their bound
+host id and cannot list sibling hosts. In P5a, `sailorbridge host consume` requires
+`--once --dry-run-start`; it validates and transitions a claimed request but does
+not launch an engine process. `sailorbridge host run` is the real long-running
+host daemon: it claims console start requests, redeems an agent credential,
+prepares the workspace, and starts the supervised agent.
+On daemon restart it asks the product API for every still-active member owned by
+the host, rotates the agent credential, and rebuilds the exact relay-reported
+tmux target before it resumes polling new start requests. Workers started by the
+same daemon are restored from the same durable ledger. Console **Relaunch** also
+queues a new host start, so it does not depend on the old supervisor still polling.
+Host-started Claude and Codex agents get terse-output defaults and Claude output
+hygiene hooks to reduce routine token spend without lowering reasoning effort or
+verification requirements.
+Before launching an agent, the host must already be logged in to that engine:
+Codex uses `$CODEX_HOME/auth.json` when set, otherwise `~/.codex/auth.json`;
+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.
+
+Worker commands implement the relay worker contract from `engine/PROTOCOL.md`:
+register, heartbeat, pull, stream upload, and result posting. Worker HTTP uses
+bounded connect/read-idle timeouts for liveness and leaves result uploads without
+a total timeout cap.
+
+Mailbox claim is a destructive operation on the relay; `mailbox peek` is the
+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.
+
+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
+`--description-file` flag treats `-` as stdin; `task create --description -` is the
+same stdin shorthand, as is positional `reply` body `-`. Non-empty piped input
+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`
+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.
+
+Plaintext bearer tokens are never printed by default. Enrollment descriptors
+contain a plaintext token and are printed only when the caller explicitly runs
+the enrollment command.
+
+## Driver Contract
+
+Phase 1 exposes only the tmux transport for Claude and Codex agents. SDK,
+headless, and PTY driver code remains in the package for a later release, but
+the public CLI and host-start surfaces fail fast if callers request those
+transports or request postponed engines such as opencode, copilot, or a custom
+CLI id. There is no silent downgrade to tmux or PTY.
+
+The client provides a shared `AgentDriver` interface. The public Phase 1 path is
+the tmux backend; all drivers share the same transport-level contract: `start`,
+`send`, `on`, `resume`, `isAlive`, and `stop`.
+
+The tmux driver creates a dedicated tmux session by default and only destroys
+sessions it created. Existing-session mode can send or interrupt, but it does
+not launch a process because environment secrets must not be typed into an
+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.
+
+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
+instantiate them. The pinned SDK versions are:
+
+- `@anthropic-ai/claude-agent-sdk@0.3.168`
+- `@openai/codex-sdk@0.137.0`
+
+Anthropic's public Claude Code SDK docs still reference
+`@anthropic-ai/claude-code` in some places; the implementation is grounded in
+the `@anthropic-ai/claude-agent-sdk@0.3.168` npm package declarations. Unit
+tests use injected fake SDK facades to verify our event mapping and option
+assembly; they do not prove live provider behavior. Real SDK smoke tests exist
+but are skipped by default. Set `SAILORBRIDGE_REAL_SDK_SMOKE=1` to run them.
+
+Productized supervisors default to unattended execution so a BYO agent does not
+stop on local permission prompts: Claude uses `bypassPermissions` and Codex uses
+`danger-full-access` plus `approvalPolicy: "never"` / `yolo`. Explicit
+`--permission-mode`, `--sandbox-mode`, `--approval-policy`, or `--yolo false`
+opt back into a more interactive or constrained launch; the tmux transport
+translates those flags into first-party CLI argv. An explicit `-- COMMAND...`
+is always used verbatim; combining it with safety flags fails fast because those
+flags would not be applied to the verbatim argv. `--yolo true` is also mutually
+exclusive with explicit Codex sandbox or approval-policy constraints.
+
+SDK capabilities, PTY support, opencode/copilot adapters, and custom CLI ids are
+deferred to the next release. Their implementation files may exist in this
+package, but Phase 1 help, docs, and validation do not expose them as supported
+product surface.
+
+Mailbox consumption, `CLEAR`, and `WORKFLOW-REFRESH` handling are supervisor
+responsibilities (see Supervisor Contract). The driver only manages transport
+lifecycle, liveness inspection, and text delivery.
+
+## Supervisor Contract
+
+The TypeScript supervisor owns one local agent process,
+chooses a transport, leases that agent's mailbox, and reports only real
+session/profile changes back to the relay.
+
+Ownership is exclusive: do not run this supervisor and the Python SailorBridge
+listener against the same `agent_name`. A single agent inbox and runtime control
+channel must have one owner, otherwise mailbox leases can be stolen. Use
+`sailorbridge supervise` only for agents not already driven by another
+listener/supervisor.
+
+Default transport selection:
+
+| CLI | Default transport | Default command |
+| --- | --- | --- |
+| `claude` | `tmux` | `claude` |
+| `codex` | `tmux` | `codex` |
+
+`claude`/`codex` default to `tmux` so the agent runs the real first-party CLI
+(covered by the captain's Claude/Codex subscription and attachable). When `tmux`
+is the resolved transport and no `--tmux-session` is given, host-started agents
+use readable names such as `sb-<team>-<role>`; same-host collisions try the
+default name, then the captain number, then the agent name, followed by numeric
+suffixes `-1` through `-100`. If every candidate is occupied, startup fails
+explicitly. Direct `sailorbridge supervise` has no team/role context, so it
+falls back to a readable `sb-<agent>` name.
+`--tmux-session` overrides all derived names.
+
+When `tmux` is the resolved transport but no `tmux` binary is found, the client
+fails fast or asks before installing it:
+
+- **default path** (no `--transport`) → resolves to tmux and fails
+  fast with a platform install hint.
+- **explicit `--transport tmux`** on an interactive TTY → prompts: `[1]` install
+  tmux (macOS `brew` / Linux `apt-get`/`dnf`/`pacman`, asking for confirmation
+  and showing the exact command — including `sudo` — before running it),
+  or `[2]` cancel.
+- **explicit `--transport tmux`** without a TTY (e.g. CI) → fails fast with the
+  platform install hint. It never installs silently or downgrades the transport.
+
+`--transport tmux` launches through the tmux driver, using an explicit
+`--tmux-session` when given or otherwise deriving the readable default described
+above; pass `--tmux-session` for direct-supervise collision control. It is the
+attach/mirror option because tmux reports `attach: true`. Explicit
+`--transport auto` is rejected so the public surface stays tmux-only; `sdk`,
+`headless`, and `pty` fail fast as next-release transports.
+
+Supervisor relaunch decisions are based only on local process liveness:
+`driver.on("exit")` or `isAlive().processAlive === false`. Reply liveness is
+not reported as relay presence and never triggers relaunch by itself.
+
+`CLEAR` and `WORKFLOW-REFRESH` are monitor-handled control messages. They are
+claimed and acknowledged by the supervisor after successful control cue delivery;
+they are not normal work prompts. For the current tmux transport, `CLEAR` sends
+`/clear`. Future SDK transports must expose a real session reset or document
+their best-effort semantics before they become public.
+
+The supervisor owns mailbox leases for its agent and long-polls with
+`wait=true` and `peek=false`. Delivery is serial and control-first. If driver
+delivery fails, the message is not acknowledged so the relay lease can expire and
+requeue it. Surface telemetry is observability-only;
+acknowledgement and driver delivery failures remain real errors. Shutdown
+aborts the in-flight long poll and never acknowledges a partially delivered
+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
+```
+
+`--i-own-this-agent` is required as a runtime collision guard. For tmux launches,
+the built-in Claude/Codex default commands include the matching no-prompt flags
+unless explicit safety flags request a constrained command. Explicit command argv
+is used verbatim and cannot be combined with safety flags.
+The runtime fetches the relay monitor record before start/relaunch and uses
+`session_handle` only when `should_resume` is true and the selected driver
+reports `resume: true`. After every successful start/rebuild it patches the
+driver's live handle back to the relay; for tmux this is the final
+collision-resolved session name consumed by roster `tmux_session_name`.
+
+The liveness loop no longer patches relay presence. Relaunch is attempted only from `driver.on("exit")` or
+`isAlive().processAlive === false`, with capped exponential backoff and a
+give-up state after repeated failures. `replyAlive` never causes a relaunch by itself.