@openrig/cli 0.6.11 → 0.6.13

package/daemon/docs/reference/sdlc-conventions.md

@@ -37,7 +37,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
 | **PRODUCT / MISSION PREPARATION** | **The product-management pass** — the layer above planning, run by the advisor/PM seat before planners touch a mission. The build is a lossy compression pipeline (PM intent → planner spec → builder code); nothing leaks downward by proximity, so this pass grounds in the raw sources, synthesizes ONE scope of record, presents owner decisions decision-ready, mints slices at plan time, deposits the full design contract INLINE in each design-bearing spec (owner words verbatim, settled decisions, evidence, shape of done, anti-goals), routes the complete reading list and internet-research assignments from the spec itself, frames each slice's planning-dial rung with its reason, and rereads every spec as the narrow downstream reader. The measuring stick: SPEC.md alone, plus what it explicitly routes to, reproduces the intent in a reader with none of the author's context. Full reference: `product-management-pass.md`. |
 | **PLAN** | **The planning dial** — planning rigor is a spectrum chosen per piece: P0 mini-requirements and pointers (simple, reversible work) · P1 an authored spec with a proof contract (the default) · P2 plus a research round before the spec freezes, run BEFORE build dispatch · P3 plus an adversarial pass by a non-author, judged against product goals, landing amendments with proof-contract teeth · P4 plus a blind from-scratch design diffed against priors before proceeding. Dial up by what the piece is, exactly as build care is priced below. Full reference: `planning-dial.md`. |
 | **BUILD** | **Part A, the simple flow** (below — the default) · **product-journey components** — a mission-selectable menu for greenfield work, drift recovery, public journey probes, one evidence-gated look at the layer below, minimal repair, independent QA/review, integration, and installed smoke; compose only what the work needs in mission/slice YAML, never as a new mode or mandatory pipeline. Full reference: `product-journey-sdlc.md` · **the wave model** — slices build in parallel in disjoint file territories, an integrator merges serially, and independent review fires once per wave (two reviewers with different vantages, never the writers; fix rounds re-earn verdicts at one final revision; per-slice discipline stays failing-test-first and verify-by-effect). The wave IS the care dial: what shares a wave decides how much review each piece gets · **Part B, the rigorous overlay** (below — only when assigned). These combine: a wave can carry one Part-B piece. Full wave reference: `wave-sdlc.md`. |
-| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE; when the slice's `slice.yaml` carries `execution.depends_on`, that list takes precedence); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live in `mission.yaml` `arrangement.waves` (`{id, slices, review_model?}`; a slice may also name its wave in `slice.yaml` `execution.wave`). Only when the mission has no `mission.yaml`, or it is malformed, does the view fall back to the legacy form: the newest queue row tagged `format:wave-map-v1` and `mission:<mission>` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. Existing batons are never rewritten. |
+| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE; when the slice's `slice.yaml` carries `execution.depends_on`, that list takes precedence); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live in `mission.yaml` `arrangement.waves` (`{id, slices, review_model?}`; a slice may also name its wave in `slice.yaml` `execution.wave`). Only when the mission has no `mission.yaml`, or it is malformed, does the view fall back to the legacy form: the newest queue row tagged `format:wave-map-v1` and `mission:<mission>` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. **Lanes:** Q1 lists each in-progress row as a lane; a row parked on `external:<what>` also appears as a waiting lane, marked `waiting: {on}`. `external:` records an outside dependency (a review, a decision, a capacity limit, a lifecycle step); it does not mean an outside party owns all the work, or that the parked seat is the slice's builder. The views show it as a waiting row (the seat, the blocker, a link to the row), not as the slice's assignment. It yields to an in-progress lane on the same slice, and it is not counted in `lanes_live`, so `q1_lanes` can be longer than `lanes_live`. Rows parked on a qitem, a human seat, or a `fold:`/`auth:` gate are not lanes. Existing batons are never rewritten. |
 | **RELEASE** | The release ceremony conventions (publication identity, honest release notes) and the CAPABILITY-DELTA LIFECYCLE LAW: each release's delta is authored at the fence and bound to the exact candidate, then reconciled to the published cut. Expiry requires both the canon header naming the absorbed delta and a distinct successor delta existing; a draft header alone is insufficient. Verify the actual boundary event and stop citing an expired delta. Full statement: `release-boundary.md` §6. |
 | **BOUNDARY** | **The release boundary** — housekeeping run once per fence so the next release starts clean: seats reset or re-primed per their continuity needs, memory distilled (keep what changed a decision recently), every queue swept by destination and dispositioned, substrate torn down, boards frozen as records, a clean-box baseline captured. A checklist of judgment guides, not gates. Full reference: `release-boundary.md`. |
 
@@ -83,6 +83,25 @@ truth is reconciled to main. Continuous integration to main and a
 release-line fold followed by one explicit merge are both valid; leaving the
 choice implicit is not.
 
+A candidate that merges by squash or rebase is never an ancestor of that ref, so
+ancestry alone cannot read it as merged. A `merged:<pr-number>` tag on a queue row
+bound to the slice (the `slice:` tag, like `candidate:`) is a recorded report of a
+merge, not a verified one: `rig view show execution` shows it on the "merged" rung
+(`folded`) as `merge_report` (`pr`, `row`, `recorded_at`, `linked`) and in the basis
+text, and `recorded_at` is when the row recorded the merge, not when it happened.
+A report never changes the merged answer by itself: without a candidate, with an
+unresolvable candidate, with an unusable declared integration ref or with no
+repository context, the answer, next-up and dependent slices stay as ancestry gives
+them. A row that carries a `merged:` tag is a report, not a build, so it never picks
+which commit counts as built: that stays the newest `candidate:<sha>` tag on a row
+without a `merged:` tag. A report is `linked: true` when its own row's `candidate:<sha>`
+resolves, through the repository context, to that built commit, and `linked: false`
+otherwise (no candidate on the row, or a different commit). The answer changes only
+for a linked report when ancestry answered false (not an ancestor): then the rung
+reads merged and the basis says so. A linked report never turns an answer ancestry
+could not give into merged. The report never changes which commit counts as built
+or reviewed.
+
 **The heavier flow — proof contracts, plan-lock, C1 drops, proof-lock — is PART B and is not in
 force unless assigned.**
 
@@ -117,6 +136,14 @@ Legacy `README.md`, `IMPLEMENTATION-PRD.md`, and pre-convention trees remain
 readable indefinitely. New scaffolds do not create or mirror them, and repair
 is additive: it never deletes, renames, or rewrites legacy bytes.
 
+A slice's frontmatter carries `stage:` (`wip`, `provisional`, `established`,
+`canonical`, or the exits `superseded` and `retired`) and `verified:`
+(`<date> against <source>`). Set them with `rig scope slice stage <slice> <stage>`
+and `rig scope slice verified <slice> --against <source>`; no approval stamp
+changes either. `rig scope` reads an `established` or `canonical` slice whose
+`verified:` is missing, has no source, names a tool-scaffolded placeholder, or is
+older than 90 days as `provisional`.
+
 When the owning scope selects `proofPolicy.judges`, use `rig proof judge` to
 record an attributed accept, reject or withdraw decision on a contract item,
 and `rig proof show` to read derived readiness up through slice, mission and
@@ -138,6 +165,17 @@ commit. Evidence capture (`proof add`), policy acceptance, higher outcome
 judgment and publication are distinct. This optional component does not select
 Part B or add a mandatory review gate.
 
+The project readiness that `rig proof show --project` reports counts only
+missions whose `mission.yaml` carries `metadata.status: active` or
+`metadata.status: release-candidate`. `rig scope mission create` writes
+`metadata.status: planned`, for ordinary and release missions alike, so creating
+a mission does not change the project's readiness. A `planned` mission stays
+outside the rollup, even after its slices are accepted, until someone changes
+its status to `active` (or `release-candidate` for a release that is ready to
+judge). Nothing changes the status automatically. Missions created before this
+default carry no status and are not counted either; add the line by hand to
+include them.
+
 The three sections project into the UI's one review structure: a vertical
 stack of **INTENT → PLAN → DELIVERED**. A slice missing a section still
 renders (a missing Intent or Delivered source shows a muted "—", missing

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,58 +168,209 @@ 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.
+- **Missed messages:** each machine recovers the channels it owns: the hub its own channels, and
+  every other machine its default channel and its channel map's (the hub never recovers a channel
+  it relays). See [Reconnect recovery and status](#reconnect-recovery-and-status).
+- **Not covered yet:** `rig slack verify` on the hub doesn't check the app's membership in relayed
+  channels.
+
 ## Reconnect recovery and status
 
 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.
+channel** in the channels this machine owns: its default channel and its channel map's, except a
+channel it relays to another machine. It also scans replies in the threads it tracks in those
+channels whose root was posted, or which closed, within the last seven days. A root's age is its
+Slack posting time, so rebuilding the thread map doesn't make an old thread eligible again. An old
+thread that closed within seven days is scanned from its root, so this isn't a seven-day history
+limit. Missed replies in older open threads aren't caught up; live delivery is unchanged.
+
+The hub scans after a Socket Mode connection and on its existing five-minute retry cadence. A
+machine the hub relays to scans every five minutes, and recovers only the channels it owns that the
+hub has relayed it an event for. Each such channel's coverage starts when its first relayed event
+arrives, and is kept across restarts, so a restart needs no new event. A channel the machine no
+longer owns isn't scanned, and a machine nothing is relayed to never reads its channels' history.
+
+Broadcast replies keep their thread's routing. Recovered tasks say **Recovered after a gap** and
+show the original Slack posting time. A recovered thread reply lands as a reply in its thread,
+marked late, and never answers a decision, even one still open: the seat reads it and decides. A
+recovered broadcast reply does the same in every channel except the default channel of the machine
+that holds the Socket Mode connection, where it behaves as before; a relayed machine's default
+channel counts as newly covered. A dead-lettered recovered reply keeps that mark when it's retried.
 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
 failed delivery, not successful delivery.
 
 Recovery keeps a per-channel checkpoint across reconnects, restarts and channel
-switches. On upgrade it initializes once from the newest retained accepted
-channel landing; without such evidence it starts at feature adoption. **Older
-history is unknown.** New live messages never move the recovery checkpoint. A
+switches. For the hub's default channel it initializes once from the newest retained accepted
+channel landing; without such evidence it starts at feature adoption. Every other channel starts
+when recovery first adopts it. **Older history is unknown.** A tracked thread's checkpoint starts
+at its root, so its first scan reads the whole thread; replies that already landed are recognized
+and not delivered twice. New live messages never move the recovery checkpoint. A
 partial scan resumes its saved interval; only an exhausted interval advances the
-covered boundary. Each new interval ends five seconds before the local clock to
+covered boundary. The checkpoint moves past a message once it landed, was a duplicate, was
+dead-lettered, was refused because its sender isn't admitted, or was skipped as a kind inbound
+doesn't take (a bot's post, an edit or join, an empty message). Each new interval ends five seconds before the local clock to
 allow recent messages to become visible; larger clock skew or visibility lag is
 not covered by that margin. A corrupt or unreadable checkpoint leaves recovery unavailable
 and preserves the existing file; live inbound continues.
 
-Each pass admits at most four pages, 100 entries and 15 seconds of work, with a
-five-second history-request ceiling. Work already started on a message, such as
+Each pass admits at most four history calls, 100 entries and 15 seconds of work, with a
+five-second request ceiling. Channels and threads take turns within that one budget, so with many
+tracked threads each thread is scanned every few passes; `rig slack status` shows how far behind
+the oldest waiting thread is. Work already started on a message, such as
 an attachment transfer, is not cancelled by these limits or by a stop, and a new
-pass waits for it to finish. Rate limits retain Slack's Retry-After across restart.
+pass waits for it to finish. Rate limits retain Slack's Retry-After across restart, and hold back
+only the method Slack limited (channel history or thread replies).
 Transport and server failures use a five-second backoff unless Slack supplies Retry-After.
 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. 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.
+failures appear as recovery limitations. A tracked thread Slack can't find stays incomplete in
+status, with no further call, until its thread mapping changes or the daemon restarts or rewires
+the connector; that isn't proof the thread was deleted. No additional scope is required to keep
+live delivery working. Threads nobody tracks, older open threads, threads closed more than seven
+days ago 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,
+snapshot: socket state/generation, last event, recovery interval/state/reason for each
+channel, a thread line (tracked, scanned, waiting and why any are backing off or incomplete),
 retry time and accepted/dead-lettered recovery counts since the connector last
-started (they reset when it is enabled or disabled, and when the daemon restarts).
+started, including threads that have since left the window (they reset when it is enabled or disabled, and when the daemon restarts).
 It also reports the durable dead-letter backlog: the retained records for inbound messages,
 reactions and click answers that await retry, counted from both dead-letter files so the number
 survives a restart, and shown as unknown with a reason (and no count) when a file cannot be read.

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 |