@openrig/cli 0.6.10 → 0.6.12

package/daemon/docs/reference/seat-delivery.md

@@ -0,0 +1,127 @@
+# Per-seat terminal delivery
+
+The existing typing guard supports three modes. Before draft-aware mode,
+automatic input either used the ordinary delivery path or was held unconditionally.
+Draft-aware adds an opt-in check for unfinished input without a second control or
+daemon-owned retry scheduler. Sibling seats keep their own mode.
+
+| Mode | Terminal input | When input is unavailable |
+|---|---|---|
+| `off` (default) | Existing delivery and prompt checks | Existing send result |
+| `draft-aware` | Paste into a recognized empty composer; check ownership again before Enter | Immediately retain the original message with the exact refusal reason and ID |
+| `hold` | No automatic terminal input, even at an empty prompt | Retain for inspection outside the pane |
+
+Runtime permissions are separate. Recipient and interactive-prompt checks still
+apply. `--raw`, `--force` and `--dangerously-interact` do not bypass the typing guard.
+Direct human input remains available.
+
+## Configure and inspect
+
+Run from a seat shell with `OPENRIG_SESSION_NAME` set; the daemon derives the
+audit actor from transport identity.
+
+~~~sh
+rig seat set-typing-guard dev-impl@my-rig --mode draft-aware \
+  --reason "preserve my unfinished input"
+rig seat status dev-impl@my-rig
+rig seat held-messages dev-impl@my-rig --json
+rig seat held-messages dev-impl@my-rig --id <outbox-id> --json
+rig seat retire-held-message dev-impl@my-rig <outbox-id> --reason "read outside the pane"
+~~~
+
+Use exactly one of `--mode off|draft-aware|hold` or the compatible
+`--enabled true|false`: true selects hold, false selects off. There are no
+retry settings or deadlines. Activation waits for an already-started seat operation
+to finish. The API may return HTTP 202 with `pending: true`; wait for
+`pending: false` before relying on the requested mode. Status reports desired
+and effective modes and retains the text `Typing guard: on (hold)` for hold.
+
+A held send immediately returns `outcome: "retained"`, `sent: false`,
+`outboxIds` and its exact reason, such as `draft_input_busy` or
+`draft_input_unknown`. No automatic retry is scheduled, including when the
+caller requested wait-for-idle. The caller can inspect or route the retained work
+and decide when to make a new request. Reusing the same delivery ID reads its
+original result; it does not replay that message. Changing modes, clearing a
+draft, or restarting the daemon also does not flush held records.
+
+Reading never sends. Retirement frees that record's active retention quota while
+preserving evidence; it does not deliver a message or close queue work.
+
+## Input evidence and outcomes
+
+The cursor-aware reader lives in `session-transport.ts` and shares the composer
+matchers with ordinary delivery. It recognizes framed Claude input and Codex input
+with a known footer. The visible input containing the cursor is checked independently
+of activity hooks, again after buffer preparation, and immediately before Enter.
+Copy mode, an unreadable capture and an unsupported layout cannot authorize input.
+
+The final check preserves authored whitespace: the cursor distinguishes trailing
+spaces from screen padding or omitted blank capture cells. A numbered message is
+recognized as this operation's own text only within its previously empty composer;
+a newly observed numbered menu is still refused. Human edits after paste stay
+visible and Enter is refused.
+
+Faint placeholders and autocomplete suffixes are display hints only when the
+capture preserves their styling. Typing the same words and moving the cursor to
+the start still counts as a draft. Current footer and indentation anchor the
+Claude frame, so quoted prompt/frame examples inside a draft do not become proof
+of empty input.
+
+A large paste can appear as several labels plus a literal tail. The existing
+`hasExpectedStagedText` check validates the tail and the labels' combined source
+boundary. That complete rendering must be observed after this operation's paste
+and remain unchanged before Enter. Labels alone do not prove arbitrary content.
+
+| Delivery state | Meaning |
+|---|---|
+| `sending` | The original IDs have an unresolved write attempt |
+| `held` | No input was written; the original message remains retained or has been retired |
+| `complete` | Transport execution succeeded, including render verification if requested; native consumption is not asserted |
+| `indeterminate` | Input may have occurred or requested render verification failed; no automatic replay |
+
+Migration `100_typing_guard_modes` extends the existing guard/audit rows and
+adds receipt metadata to the original outbox rows; it creates no tables, retry
+indexes or executable requests. Combined wakes retain each original ID and body.
+A held queue wake stays on the existing queue recovery path. Interrupted writes
+become indeterminate at startup regardless of which recovery component runs first.
+
+The existing retention limits apply: 100 records and 8 MiB per seat, with a 1 MiB
+message limit. New admissions refuse at capacity; already-committed queue intent
+remains durable even if concurrent activation exceeds the limit.
+
+## Rollback and lifecycle
+
+Persisted legacy guard bits are on for both hold and draft-aware, so an older
+daemon holds messages instead of typing into a protected seat. On re-upgrade,
+the most recent guard audit row and change timestamp determine whether the saved
+mode is still authoritative. A later boolean write by the older daemon takes
+precedence, including a same-value on-to-on write in the same clock tick.
+Without a later setting change, the draft-aware mode survives re-upgrade.
+Held and uncertain deliveries are never replayed by this reconciliation.
+
+Current API `desired` and `effective` booleans continue to describe hold-all;
+mode fields describe draft-aware protection. Storage's fail-safe legacy bits
+are deliberately broader.
+
+With hold, writing lifecycle operations refuse before effects. With draft-aware,
+an active seat requires an explicit switch to off before writing lifecycle work.
+Fresh startup is exempt only after creating a new pane or successfully respawning
+a dead pane within the same lifecycle operation. Adopting or rebinding an existing
+pane grants no such exemption.
+
+Terminal capture is observational, not an atomic editor API. A direct tmux writer
+can still act between the last observation and paste. The resulting changed input
+refuses Enter and is not replayed. Unsupported provider layouts remain held.
+Use off when that tradeoff is unsuitable.
+
+HTTP configuration uses `POST /api/seat/set-typing-guard/:seatRef` with
+`{mode, reason}` or `{enabled, reason}`. Status and held-message routes are
+unchanged; no RigSpec field is required.
+
+## Verification scope
+
+Regression tests exercise rollback/re-upgrade, same-value legacy writes, exact
+retained outcomes, restart without replay, unchanged IDs/bodies, trailing spaces,
+numbered bodies, real-menu refusals and multi-placeholder ownership. Native tests
+use private real tmux panes with scripted editable composers. These verify the
+transport mechanics; they are not live Claude/Codex provider sessions.

package/daemon/docs/reference/slack-app-setup.md

@@ -30,8 +30,13 @@ been confirmed against a real creation run. Slack's form may ask for something t
 not fill in; if so, follow the form.
 
 1. Open the link from `rig slack manifest --url` in a browser.
+   > **Note on Slack's manifest dialog:** If opening the link results in an empty manifest `{}`
+   > or Slack reports an error translating the manifest, copy the output of `rig slack manifest`
+   > (run without flags) and paste it directly into the **YAML** tab in Slack's "Create an app from
+   > an app manifest" dialog.
 2. Sign in to Slack if asked, pick the workspace, review the prefilled manifest, and click
-   **Create**.
+   **Next**, then **Create**. (If **Create** stays disabled, go **Back** and check that a
+   development workspace is selected and the manifest step shows no error).
 3. Under **Socket Mode**, confirm it is enabled. Enable it if it is not.
 4. Under **Basic Information → App-Level Tokens**, generate a token with the
    `connections:write` scope and copy it (it starts with `xapp-`).
@@ -63,10 +68,10 @@ groups:
   a member of, and reading channel details.
   `rig slack verify` checks these.
 - **Feature scopes**: `files:read` (download attachments people send), `files:write` (upload
-  attachments to Slack), `app_mentions:read` (receive @-mentions of the app), and `reactions:read`
-  (receive emoji reactions). `rig slack verify` warns when one of these is missing (if Slack returns
-  the granted scopes) but does not require them, so a READY from verify does not prove attachments,
-  mentions or reactions will work.
+  attachments to Slack), `app_mentions:read` (receive @-mentions of the app), `reactions:read`
+  (receive emoji reactions), and `users:read` (identify a named bot, below). `rig slack verify` warns
+  when one of these is missing (if Slack returns the granted scopes) but does not require them, so a
+  READY from verify does not prove attachments, mentions, reactions or named bots will work.
 
 If a feature scope was not granted, the effect differs by feature:
 
@@ -78,8 +83,10 @@ If a feature scope was not granted, the effect differs by feature:
   Only `rig slack verify` warns that the scope is missing; nothing reports the missing events.
 - **Reactions** (`reactions:read`): Slack does not deliver `reaction_added` events, so a reaction
   on an ask doesn't reach the asking agent. A reply in the ask's thread still does.
+- **Named bots** (`users:read`): Slack refuses the bot lookup, so a named bot's posts are not
+  delivered, and the daemon log names the refusal. Nothing else changes.
 
-So after installing, compare the granted scopes Slack shows for the app with all seven scopes that
+So after installing, compare the granted scopes Slack shows for the app with all eight scopes that
 `rig slack manifest --json` lists.
 
 The app subscribes to messages in public channels it is a member of (`message.channels`), to
@@ -161,25 +168,147 @@ rig slack channel-map remove pr@my-rig
   is left to the retry of retained posts.
 - **Replies and new messages.** A reply in an item's thread reaches that item's seat, in any
   channel. To answer it in the same thread, the seat sends `rig queue create --human-intent update
-  --reply-to <the inbound reply's row>`. A message the human starts (or a reply in a thread OpenRig does not know) goes to
-  the connector's inbound destination, whichever channel it is in. Missed-message recovery
-  (below) covers the default channel only.
+  --summary "<subject>" --reply-to <the inbound reply's row>`.
+  - **A new message a person starts in a rig's channel** goes to that rig's representative, the
+    seat the rest of its rig reports to (its one `delegates_to` root). To send it to another seat,
+    name it: `rig slack channel-map set my-rig C0EXAMPLE1 --inbound lead@my-rig`. A rig entry on the
+    connector's default channel only sends that rig's posts there: new messages in the default
+    channel still go to the inbound destination, unless the entry names `--inbound`.
+  - **Every other new message,** in the default channel or a seat's channel, goes to the
+    connector's inbound destination, as does a reply in a thread OpenRig doesn't know, or a rig's
+    channel whose representative can't be found.
+  - **Answers come back to where the person asked.** A person's new message is the root of its
+    answer: when the seat it reached replies with `--reply-to` that message's row, the answer and
+    later updates land in the person's thread, in the channel they used.
+  - Missed-message recovery (below) covers the default channel only.
 
 Invite the app to every mapped channel (`/invite @OpenRig`). `rig slack verify` checks
 membership in the default channel and every mapped channel, and reports NOT ready until the
-app is in all of them. A saved change reaches a running connector when it next rewires:
-`rig slack disable` then `rig slack enable`, or a daemon restart. The TUI's Connections page
-says whether the running configuration matches the file.
+app is in all of them. A saved change reaches a running connector when it next rewires, which a
+daemon restart does (`rig daemon stop`, then `rig daemon start`). `rig slack disable --reason
+"<why>"` then `rig slack enable` rewires too, but alerts still waiting to be posted when it's
+re-enabled are treated as already seen and aren't posted. Only an earlier post that failed or
+didn't finish still posts: an alert whose row is still open, a decision-resolved notice, or a digest. The TUI's Connections page says whether the running
+configuration matches the file.
 
 The map is stored as `channelMap` in `slack-connector.json`, as a list of `{ "match", "channel" }`
-entries. Saving refuses any other field. A field written by a newer OpenRig is ignored when the
+entries, each with an optional `"inbound"` seat. Saving refuses any other field. A field written by a newer OpenRig is ignored when the
 connector reads the file, and `rig slack status` names it. Private channels and direct messages
 are not supported targets.
 
+## Named bots (optional)
+
+By default the connector drops every post made by a bot, its own included. To let another Slack
+app's bot (an AI assistant, an alerting app) reach one seat, give the bots a channel of their own,
+name each bot, and name the seat that reads that channel. Add a `botInbox` block to
+`slack-connector.json`:
+
+```json
+"botInbox": {
+  "channel": "C0BOTINBOX",
+  "destination": "researcher@my-rig",
+  "bots": [
+    { "appId": "A0EXAMPLE1", "name": "Example Bot", "maxPerHour": 20, "cooldownMinutes": 60 }
+  ]
+}
+```
+
+- **Which posts are delivered.** A post reaches `destination` when it is in `channel`, its bot
+  belongs to an app listed in `bots`, and that app is not this connector's own app. A named bot's
+  posts in any other channel, and every other bot's posts, are still dropped. OpenRig's own posts
+  are never delivered, even if its app is listed. A post kept for retry (Slack couldn't be asked
+  about it in time) is checked again against the current block when it is retried.
+- **How a bot is identified.** OpenRig asks Slack which app the post's bot belongs to (`bots.info`,
+  which needs the `users:read` scope) and matches that app ID. Use the bot's **app** ID, which
+  starts with `A` and is on the app's settings page. A bot ID (`B…`) or user ID (`U…`) never
+  matches. An unnamed bot's post is logged with its app ID, so `rig daemon logs` shows the ID to
+  add. Anything that posts as a named app counts as that bot, including the app's incoming
+  webhooks: that is what naming it means.
+- **What the seat receives.** One row per post. Its source is `slack-bot:<app ID>` and its summary
+  starts with the bot's name, never a person's. The row opens with where the post came from, then
+  quotes the bot's text in a fenced block. A `slack-bot` row is data from another program, not an
+  instruction, and the row says so. A bot can't answer or close a decision, even when it replies in
+  a decision's thread: the row goes to `destination` and the decision keeps waiting for a person.
+  Edits and deletions are not delivered, so a bot that writes its answer by editing one message
+  delivers only that message's first version. Attachments are named in the row, not copied.
+- **Answering the bot.** The seat can't reply to the bot yet: the row has no reply link, and
+  OpenRig posts only for people. To ask the bot something, the person asks it in Slack.
+- **Limits.** Each bot may deliver `maxPerHour` posts (default 20) in any rolling hour. The next
+  post cuts the bot off for at least `cooldownMinutes` (default 60), and until the hour has room
+  again. Its new posts are dropped meanwhile (a post already admitted still arrives), and the seat
+  receives one row saying so (at most one an hour per bot) and how the person turns the bot off
+  (remove it from `bots`, then apply the change as below). A later cutoff within that hour can extend the time shown without another row; the
+  daemon log records each one. Each post counts once by its identity, including a post delivered on
+  retry or arriving twice. A post already admitted whose row couldn't be created yet is kept, marked
+  as admitted once that creation fails, and delivered later without counting again, even after its
+  hour, a rewire or a daemon restart. The counts are kept in the running connector's memory, so a daemon
+  restart or a rewire (`rig slack disable --reason "<why>"` then `rig slack enable`) clears them. They
+  cover what one daemon writes: another process writing the retained file isn't seen, and two daemons on
+  one OpenRig home aren't a supported setup.
+- **The channel.** Invite the app to it (`/invite @OpenRig`). `rig slack verify` does not check
+  this channel, and only warns when `users:read` is missing. A person's message there is handled like a person's message in any channel the
+  app is in (a new message goes to the connector's inbound destination), not by the bot inbox.
+  Missed-message recovery does not cover the bot inbox.
+
+`rig slack status` shows a `bot-inbox` line: what it delivers, or why it is off. An invalid block
+(for example a bot ID where an app ID belongs) turns only the bot inbox off. A saved change
+reaches a running connector when it next rewires, which a daemon restart does (`rig daemon stop`,
+then `rig daemon start`). `rig slack disable --reason "<why>"` then `rig slack enable` rewires too,
+but alerts still waiting to be posted when it's re-enabled are treated as already seen and aren't
+posted. Only an earlier post that failed or didn't finish still posts: an alert whose row is still
+open, a decision-resolved notice, or a digest.
+
+## One app across machines (optional)
+
+Slack delivers each event of an app to one of its connections, so one app can serve several
+OpenRig machines only if one machine, the hub, holds the connection and relays each other machine's
+channels to it. Each machine still decides who its messages reach, keeps its own threads and
+decisions, and posts its own replies.
+
+- **On the hub:** the bot token and the app-level token, as usual, plus `forwardChannels` in
+  `slack-connector.json`, one entry per channel another machine owns:
+
+  ```json
+  "forwardChannels": [
+    { "channel": "C0EXAMPLE3", "host": "vps04" },
+    { "channel": "C0EXAMPLE4", "host": "vps04" }
+  ]
+  ```
+
+  `host` is that machine's id in the hub's host registry (`rig host list`). It needs an http
+  entry, which `rig host pair` writes with that machine's token; the hub sends it with each relay,
+  and the machine checks it when it has `OPENRIG_AUTH_BEARER_TOKEN` set.
+- **What the receiving machine trusts:** a relayed event comes from whoever holds that machine's
+  daemon token (or, with no token set, anything that can reach its daemon), not from Slack directly, and nothing checks Slack's own signature on it. The
+  machine still looks up the sender in its own list of people, but on a relayed event that's no
+  proof a person just typed or clicked it in Slack: it trusts the caller for where the event came
+  from.
+- **On every other machine:** the same app's bot token only, with no app-level token, so it opens
+  no connection of its own. Set its default `channel` to its own channel and, for a rig's channel,
+  a channel map entry. Its connector is enabled as usual. Its `rig slack status` reports
+  `relayedInbound`: that it can take relayed events, and how many have arrived since it started.
+  It also retries its own kept events every five minutes, including any it kept before it stopped
+  holding a connection of its own, so those still land.
+- **What happens to a message:** the hub relays the event, a reaction or a button click untouched
+  to the machine that owns the channel. That machine handles it exactly as if it had received it:
+  who may send, where it goes, its thread and its decisions. If the relay fails (the machine is
+  down or its registry entry is wrong), the hub keeps it and retries every five minutes, after its
+  own kept events and clicks; `rig slack status` counts it in the dead-letter backlog. A machine
+  that's down costs one attempt per retry: its other relays wait for the next one. A relay the
+  machine keeps refusing is kept and retried with no limit, because dropping it would lose a
+  person's message.
+- **Who answered:** every post ends `from <seat> on <machine>`, using the machine's host id (set
+  it with `host.name`).
+- **The hub's own channels** are handled on the hub, as before. A channel can be relayed to one
+  machine only, and never the hub's own default channel.
+- **Not covered yet:** `rig slack verify` on the hub doesn't check the app's membership in relayed
+  channels, and missed-message recovery covers the hub's default channel only.
+
 ## Reconnect recovery and status
 
-The daemon scans available top-level messages in the configured channel after a
-Socket Mode connection and on its existing five-minute retry cadence. Recovered
+The daemon scans available top-level messages and replies broadcast with **Also send to
+channel** in the configured default channel after a Socket Mode connection and on its
+existing five-minute retry cadence. Broadcast replies keep their thread's routing. Recovered
 tasks say **Recovered after a gap** and show the original Slack posting time.
 They use the same sender admission, routing, attachment handling, fixed identity
 and dead-letter path as live messages. A durable dead letter is custody of a
@@ -204,8 +333,9 @@ When Slack reports a plan history limit, recovery still lands the available page
 and advances normally, retaining an older-history limitation in status across restarts.
 Missing bot credentials, history scope, membership, retention limits and API
 failures appear as recovery limitations. No additional scope is required to keep
-live delivery working. Thread-reply catch-up and dead-connection detection remain
-outside this recovery scope; global chronological order is not promised.
+live delivery working. Non-broadcast thread replies and other channels remain outside
+this recovery scope; global chronological order is not promised. This change does not
+replay intervals already checkpointed before broadcast-reply recovery was added.
 
 `rig slack status` retains local configuration checks and adds a bounded daemon
 snapshot: socket state/generation, last event, recovery interval/state/reason,

package/daemon/docs/reference/topology-naming.md

@@ -23,6 +23,15 @@ Runtime, model and account belong in configuration. Changing a provider does not
 change the role's name. Keep machine and instance identifiers stable rather than
 renaming them whenever their workload changes.
 
+What a seat runs has its own words:
+
+| Term | Meaning | Example |
+| --- | --- | --- |
+| Runtime | What a seat runs: a harness, a terminal, or the stub (a scripted stand-in used in tests). It's the rig spec's `runtime` field and the TUI's runtime column | `claude-code`, `codex`, `terminal` |
+| Harness | The agent software around a model | Claude Code, Codex, Pi |
+| Community harness | A harness an outside contributor maintains. It's installed as a preset under `$OPENRIG_HOME/community-harnesses/`, listed by `rig community-harness list`, and OpenRig doesn't test it | A preset's name in a member's `runtime` |
+| Terminal | A seat with no agent: a shell for infrastructure processes | `runtime: terminal` |
+
 ## How the software teams grow
 
 | Team | Logical seats |