@sailorbridge/client 0.2.0 → 0.2.1

package/README.md

@@ -73,6 +73,9 @@ 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 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
 ```
@@ -140,9 +143,13 @@ 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_CAPTAIN_ID` is required by `worker list`, `worker run`, and
+`worker job`; it must be a numeric string. `worker list` and `worker run` also
+require `SAILORBRIDGE_SESSION` so an unbound admin credential cannot
+accidentally discover workers across teams. A paired host credential can
+supply the captain id, but it does not contain a session, so list/run still
+need `SAILORBRIDGE_SESSION`. Agent routing uses the separate
+`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,
@@ -171,6 +178,21 @@ Use `--worker`, `--workdir`, and `--max-concurrency` or the matching
 `SAILORBRIDGE_MAX_CONCURRENCY` environment variables. `SAILORBRIDGE_MODE=readonly`
 blocks mutating job kinds locally.
 
+`sailorbridge worker list [--format plain|json]` discovers registered workers
+in the current team. Plain output shows at most 20 and points to JSON for the
+complete response. `sailorbridge worker run [--detach] --worker NAME
+[--timeout SEC] [--format plain|json] -- ARGV...` submits one `bash` job and
+preserves `ARGV` as an array end to end; `--format` after `--` belongs to the
+remote argv. The timeout is the remote execution budget; synchronous mode
+waits that budget plus a 30-second queue/result grace for the persisted
+terminal result. Plain output writes remote stdout/stderr to the matching local
+streams. A remote negative signal code remains exact in JSON; plain output
+states that code and uses the conventional local status `128 + signal`. For
+long work, `--detach` returns the submit response immediately; `sailorbridge
+worker job ID [--format plain|json]` reports queued/running or the terminal
+result. Worker jobs are infrastructure execution, not product tasks; their
+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
@@ -233,10 +255,11 @@ Claude uses `$CLAUDE_CONFIG_DIR/.credentials.json` when set, otherwise
 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.
+Worker commands implement both sides of the relay worker contract from
+`engine/PROTOCOL.md`: register, heartbeat, pull, stream upload, result posting,
+session-scoped worker listing, direct `bash` submission, and terminal result
+reads. 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