@openrig/cli 0.6.5 → 0.6.7

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

@@ -1,8 +1,8 @@
 # SDLC conventions — the markdown control plane
 
 > **Source of truth:** this repo document is the living SSOT for the SDLC
-> conventions. Scaffold templates, the advisory scope audit, the
-> `mission-slice-sop` skill, and the shipped bootstrap overlay all point HERE —
+> conventions. Scaffold templates, the advisory scope audit and the
+> `mission-slice-sop` skill all point HERE —
 > they must not restate this document in full (restatement is how drift is born).
 
 OpenRig is a software factory the human steers from a high altitude. The human
@@ -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); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live on a durable queue row tagged `wave-map` + `format:wave-map-v1` 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`. 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`. |
 
@@ -46,7 +46,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
 > planning dial — `planning-dial.md` · the product-journey component catalog —
 > `product-journey-sdlc.md` · the wave model — `wave-sdlc.md` · the release
 > boundary (including the capability-delta lifecycle law) — `release-boundary.md` ·
-> the mission install — `mission-install.md` (lands with its own slice). The
+> the mission install — `mission-install.md`. The
 > summaries above remain the one-glance description; this document remains the SSOT
 > pointer for the whole menu.
 
@@ -76,8 +76,10 @@ The authority lookup is `product-journey-sdlc.md#resolve-the-selected-path`.
 Bring work with evidence that its promised user outcome actually works.
 
 For a release mission, `mission.yaml` also names the Git strategy before build
-work starts: the branch/ref that is cumulative integration truth, its base, and
-when that truth is reconciled to main. Continuous integration to main and a
+work starts: the branch/ref that is cumulative integration truth
+(`arrangement.source.integration_ref`, the ref `rig view show execution` tests
+a candidate's folding against; `main` when unset), its base, and when that
+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.
 
@@ -99,17 +101,17 @@ Each slice directory carries:
     (numbered list). This is the human operator's first structured catchpoint;
     approval starts here.
   - **`## Proof contract`** — a checkbox list of promised deliverables (see
-    §3). The UI's DELIVERED section pairs each item with its proof.
+    B1). The UI's DELIVERED section pairs each item with its proof.
 - **`PROGRESS.md`** — the slice's current delivery state and retained outcome
   log. Record material changes with links to proof; historical checkboxes are
   testimony, not current acceptance authority. For a selected proof policy,
-  `rig proof show <slice>` derives current readiness from the proof contract
+  `rig proof show <mission>/slices/<slice>` derives current readiness from the proof contract
   and attributed judgments. In-process steps stay in the working agent's
   own todo tool.
 - **`PROOF.md`** — the retained proof summary, explicitly paired to the
   `SPEC.md` proof contract.
 - **`proof/`** — the proof-artifact directory. Curated canonical evidence
-  lands here via `rig proof` with valid C1 headers (§5).
+  lands here via `rig proof` with valid C1 headers (B3).
 
 Legacy `README.md`, `IMPLEMENTATION-PRD.md`, and pre-convention trees remain
 readable indefinitely. New scaffolds do not create or mirror them, and repair
@@ -128,7 +130,9 @@ Part B or add a mandatory review gate.
 
 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 (the projection degrades to a muted "—", never invents content) —
+renders (a missing Intent or Delivered source shows a muted "—", missing
+mini-requirements show "Not compliant · mini-requirements not authored";
+nothing is invented) —
 but it does not carry its weight in review.
 
 ## A3. Honesty rails (public surfaces + cited hashes)
@@ -209,24 +213,31 @@ are losslessness checks on the decompression from intent to delivery, not
 paperwork. Scaffolding emits the sections; it must never mint ceremony.
 ## A6. The audit (advisory, fail-open — always)
 
-`rig scope audit` (and the advisory rows in `rig workspace validate` /
-`doctor`) checks these conventions: the section headings present, the proof
-contract well-formed, `proof/` artifacts carrying valid C1 headers, UI slices
-referencing a mockup. Every finding **records and advises — it never blocks a
-write path and never changes exit semantics into a gate**. Unknown is
+`rig scope audit --mission <name>` (and the advisory `sdlc_convention_sections`
+row in `rig workspace doctor`) checks these conventions: the section headings
+present, the proof contract well-formed, `proof/` artifacts carrying valid C1
+headers, UI slices referencing a mockup. Convention findings are low or info
+severity, except an invalid C1 header on a `proof/` artifact, which is medium.
+All of them **record and advise — they never block a write path and never
+change the exit code**. (`rig scope audit` exits 1 only on high-severity
+structural findings, such as a missing `PROGRESS.md` or id.) Unknown is
 reported as unknown, not failure.
 ## A7. Where the knowledge lives (the four pointers)
 
 - **This document** — the SSOT.
-- **Scaffold**: `rig scope slice create` emits `SPEC.md` + `PROGRESS.md` +
-  `PROOF.md` + `proof/` for every template kind; `rig scope mission create`
-  emits an intent-bearing `SPEC.md` + `NOTES.md`. Core emits only this
+- **Scaffold**: `rig scope slice create` emits `SPEC.md` + `slice.yaml` +
+  `PROGRESS.md` + `PROOF.md` + `proof/` for every template kind (and registers
+  the slice in `mission.yaml` when that manifest exists; legacy missions
+  without one remain supported); `rig scope mission create` emits an
+  intent-bearing `SPEC.md` + `mission.yaml` + `PROGRESS.md` + `NOTES.md` +
+  `slices/` (plus `CAPABILITY-DELTA-v<version>.md` for a `release-X.Y.Z`
+  mission). Core emits only this
   mode-neutral shape; mode plugins add richer material through the extension
   seam rather than teaching core a mode.
 - **Skill**: `mission-slice-sop` teaches **Part A**, the light default. **Part B**
   is defined below and applies only when assigned — never self-selected.
-- **Bootstrap**: the shipped agent overlay points fresh seats at the skill
-  and this document at boot.
+- **Bootstrap**: the shipped `pm` rig culture points its seats at the skill
+  and this document; the generic `openrig-start.md` overlay no longer does.
 
 # PART B — THE RIGOROUS OVERLAY (assigned only)
 
@@ -266,7 +277,8 @@ deliverable, written as an observable outcome:
   that evidence it — that pairing is what the DELIVERED section renders, so
   the human never hunts through dozens of artifacts to find which one proves
   what.
-- **UI deliverables carry a planned mockup** (`plannedRef`): the planning
+- **UI deliverables carry a planned mockup** (`plannedRef`, written as an
+  inline image on the checkbox line, e.g. `- [ ] … ![mockup](mockups/review.png)`): the planning
   agent produces the mockup and attaches it to the locked set. A UI slice
   with no mockup in its locked set is an incomplete plan. Non-UI slices
   (backend, skills, markdown) have no mockup and no `plannedRef` — that is
@@ -283,14 +295,18 @@ append-only audit row land together):
 - **Plan-lock:** `rig scope slice approve <slice> --scope spec` — "the spec
   matches my intent; THIS artifact set is what gets built." Pins `SPEC.md`
   (and planned mockups, when present) out of everything else in the folder.
+  `--locked-artifacts "SPEC.md,…"` names the set explicitly instead; a
+  plan-lock on an unedited scaffold `SPEC.md` with nothing else to pin refuses.
 - **Proof-lock:** `rig scope slice approve <slice> --scope delivery`
-  (the default scope) — the terminal "this is done" sign-off; fires the
-  freeze.
+  (the default scope) — the terminal "this is done" sign-off. (It does not
+  render the frozen export; the approve result reports `freezeFired: false`.)
 
 Approval is freeze/sign-off — **never** proven-green. Proven-green requires a
-recorded verdict (a C1 proof artifact, §5); presence of an approval stamp does
+recorded verdict (a C1 proof artifact, B3); presence of an approval stamp does
 not assert the work was proven. `--on-behalf-of` records delegation honestly
-(the actor stays the real invoking session).
+(the actor stays the real invoking session). A second approve of the same
+scope refuses; `--re-approve --reason "<why>"` supersedes the stamp and keeps
+the prior one in the audit log.
 
 ## B3. Proof drops and the C1 header (closed sets)
 
@@ -323,9 +339,11 @@ that it LOOKED at the evidence. `--media` names the curated media files
 (relative to the slice's `proof/` dir — co-located, never absolute) this
 drop stands behind; the composer projects them into the DELIVERED items'
 proof set. Validation happens at drop time; the audit
-(§6) backstops artifacts that arrived by other paths. **Hand-placing files
-in `proof/` without a drop is the anti-pattern**: the deliverable stays
-unpaired and `unverified` in the DELIVERED view — always attach media via
+(A6) backstops artifacts that arrived by other paths. **Hand-placing files
+in `proof/` without a drop is the anti-pattern**: media alone pairs with
+nothing, so a deliverable with no covering proof artifact (one whose
+`evidences` names it) shows as `missing` in the DELIVERED view, or as current
+acceptance absent under a selected proof policy — always attach media via
 `--media` on a drop.
 
 ## B4. Role contracts (what makes the structure self-enforcing)

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

@@ -44,9 +44,15 @@ not fill in; if so, follow the form.
    SLACK_APP_TOKEN=xapp-...
    ```
 
-8. Run `rig slack setup --channel <channel-id> --secrets-env-file <path>`, then
-   `rig slack verify`, then `rig slack enable`.
-9. Invite the bot to the channel you configured (`/invite @OpenRig` in that channel).
+8. Invite the bot to the channel you will use (`/invite @OpenRig` in that channel).
+   `rig slack verify` reports NOT ready until the app is a member.
+9. Register yourself as the human the connector delivers to, with a Slack binding that names
+   your Slack user ID (`rig gateway human add`; its `--help` shows the binding format).
+   Messages from Slack users who are not registered are not delivered. `rig slack enable`
+   needs a readable human registry: on a fresh install with no registry, or with an invalid
+   one, it is refused.
+10. Run `rig slack setup --channel <channel-id> --secrets-env-file <path>`, then
+    `rig slack verify`, then `rig slack enable`.
 
 ## What the app asks for
 
@@ -57,9 +63,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), and `app_mentions:read` (receive @-mentions of the app). `rig slack verify`
-  does **not** check these, so a READY from verify does not prove attachments or mentions will
-  work.
+  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.
 
 If a feature scope was not granted, the effect differs by feature:
 
@@ -67,14 +74,24 @@ If a feature scope was not granted, the effect differs by feature:
   message with an attachment that could not be downloaded is still delivered, with the failed
   file named in it. A post whose attachment could not be uploaded still delivers its text, and
   the failure appears only in the daemon log (`rig daemon logs`).
-- **Mentions** (`app_mentions:read`): Slack does not deliver `app_mention` events to the app, and
-  nothing in OpenRig reports that they are missing.
+- **Mentions** (`app_mentions:read`): Slack does not deliver `app_mention` events to the app.
+  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.
 
-So after installing, compare the granted scopes Slack shows for the app with all six scopes that
+So after installing, compare the granted scopes Slack shows for the app with all seven scopes that
 `rig slack manifest --json` lists.
 
-The app subscribes to messages in public channels it is a member of (`message.channels`) and to
-mentions of the app (`app_mention`). It does not request direct-message or private-channel access.
+The app subscribes to messages in public channels it is a member of (`message.channels`), to
+mentions of the app (`app_mention`), and to emoji reactions (`reaction_added`). It does not request
+direct-message or private-channel access.
+
+A reaction added to an ask reaches the agent that asked, as a note naming who reacted and with
+which emoji; the agent decides what it means. Every message OpenRig posted for the ask counts:
+its first message, a long ask's numbered parts, and an ask posted as a reply in a thread. A
+reaction on any other message, including a person's reply in the thread, is ignored. An app created from an older manifest has neither the `reactions:read` scope nor the
+`reaction_added` event: add both under **OAuth & Permissions** and **Event Subscriptions**, then
+reinstall the app to the workspace.
 
 The manifest also turns on **Interactivity**, so the human can answer a decision's structured
 questions by clicking a button (`rig queue create --human-questions-file`). In Socket Mode the
@@ -94,3 +111,87 @@ part of OpenRig.
 
 - `rig slack status` shows what is still missing, without contacting Slack.
 - `rig slack verify` checks the granted baseline scopes and channel membership with Slack.
+
+## One channel per rig or seat (optional)
+
+By default every human-bound item posts to the one channel from `rig slack setup --channel`.
+To follow each rig separately, post a rig's items, or a single seat's, to its own channel:
+
+```bash
+rig slack channel-map set my-rig C0EXAMPLE1
+rig slack channel-map set pr@my-rig C0EXAMPLE2
+rig slack channel-map list
+rig slack channel-map remove pr@my-rig
+```
+
+- **Which channel an item posts to.** The item's seat is matched exactly first (`pr@my-rig`),
+  then its rig (`my-rig`). Anything unmapped posts to the default channel, so a config
+  without a map behaves exactly as before. Aggregate delivery digests have no single seat and
+  always post to the default channel.
+- **Threads.** Updates, `--reply-to` and later notifications for an item stay in its thread.
+  With a map configured, if a seat's channel has changed since the thread was opened, the
+  next post opens a new thread in the seat's current channel, and `--reply-to` records the
+  fallback as `root-other-channel`. With no map, threads behave exactly as before: an item's
+  next notification reuses its open thread in whatever channel that thread was posted in.
+- **Changing the map.** A change applies to new posts. A post already in flight (one being
+  retried after a failure or an unconfirmed send) finishes in the channel and thread it started
+  in, and its retry checks that channel first so it is not posted twice. This includes adding
+  the first map: a post first tried before any map existed finishes in the default channel.
+  Without a map, OpenRig records nothing about a post's channel, so if the default channel
+  changes while a post is being retried, the retry goes to the new default channel (as it always
+  has); that also applies to a post first tried before the map was added.
+- **Replies and new messages.** A reply in an item's thread reaches that item's seat, in any
+  channel. 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.
+
+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.
+
+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
+connector reads the file, and `rig slack status` names it. Private channels and direct messages
+are not supported targets.
+
+## 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
+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
+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
+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
+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
+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.
+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. Thread-reply catch-up and dead-connection detection remain
+outside this recovery scope; global chronological order is not promised.
+
+`rig slack status` retains local configuration checks and adds a bounded daemon
+snapshot: socket state/generation, last event, recovery interval/state/reason,
+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).
+Human-readable coverage and pending bounds use ISO timestamps; JSON keeps Slack timestamps.
+The status read calls no Slack API and starts no scan. If the daemon cannot be
+observed, local configuration remains visible and live state is unknown. A
+connected socket or valid configuration alone does not prove end-to-end delivery.

package/daemon/docs/reference/stream-classifier-worker.md

@@ -61,12 +61,19 @@ The smaller of `--limit` and the configured request maximum bounds the wake.
 Unknown answers remain null; a wholly unknown answer abstains. Invalid model,
 provider, answer keys, choices, probabilities or response bytes reject the whole
 answer. Probability sums retain the strict 0.001 tolerance; there is no rounding
-repair or partial salvage. Unavailable/invalid provider work stops that run with
-no classification write. Inspect the returned attempt state: terminal abstentions
+repair or partial salvage. Unavailable/invalid provider work, Ctrl-C or SIGTERM
+stops that run with no classification write; when the classifier returns that
+outcome, the item in hand is recorded as an abstention, final for that classifier
+version, taxonomy version and evidence epoch. The worker's own deadline (the lesser
+of the request timeout and the time left before the next lease heartbeat) is
+different: when it fires
+first, the attempt is recorded as `error` with a retry time, or `exhausted` once the
+retry budget is spent, not as an abstention. Inspect the returned attempt state: terminal abstentions
 are not reopened, and failed/unknown daemon writes must be reconciled through the
 existing ledger. Never change the evidence epoch merely to retry an experiment.
 
-Disable is checked before each call and before applying its result. A separate
+Disable, a changed `--max-requests` or `--timeout-ms`, or an unreadable configuration
+is checked before each call and before applying its result, and stops the run. A separate
 disable command cannot cancel an already forwarded remote request; its late
 result is discarded, with the existing deadline bounding the wait. Ctrl-C or
 SIGTERM requests immediate cancellation of the foreground run. An uncooperative
@@ -169,7 +176,8 @@ source churn can require repeated preparation and is not a throughput claim.
 Each wake processes at most `--limit` items (1–100; default 20), starting with the
 oldest eligible work rather than relying on a lossy notification cursor. Durable
 terminal attempts stay excluded. A new candidate version does **not** authorize
-another pass: only an owner-selected evidence epoch changes that attempt identity.
+another pass: only a new classifier version, taxonomy version or owner-selected
+evidence epoch changes that attempt identity.
 Retain the candidates output beside the decisions and result so its version is
 reproducible. The CLI does not keep a second local ledger.
 
@@ -197,6 +205,9 @@ capture. Retained-no-write is a separate event, never delivery evidence.
 
 Activation requires explicitly supplied `OPENRIG_SHADOW_CAPTURE` JSON at a later
 authorized daemon start. Absence or invalid configuration leaves capture disabled.
+Daemon start checks only that `destination` is an absolute normalized path and the
+numeric ceilings; the private-directory checks and exclusive file creation happen
+at the first drain, and a failure there stops the sink.
 This document supplies no live destination or activation instruction. Required
 fields and engineering ceilings are:
 
@@ -218,8 +229,9 @@ observation; explicit production configuration supplies each value.
 
 `rig project shadow-status` only inspects configuration/counters.
 `rig project shadow-drain` asks the existing HTTP service to drain up to 64 rows;
-it requires an actor and never enables capture. No background drain timer is added.
-`rig project shadow-stop` disables new enqueueing immediately, finishes any active
+it requires an actor (outside a managed seat, name one with `--actor <name>`)
+and never enables capture. No background drain timer is added.
+`rig project shadow-stop` (which needs an actor the same way) disables new enqueueing immediately, finishes any active
 drain and the finite retained queue, then closes the sink. Repeated stop is
 idempotent; it cannot enable capture or delete the existing archive. Existing
 quota and sink-failure losses remain counted. A slow disk can leave stop pending;
@@ -236,8 +248,9 @@ start another writer. Overflow drops new observations. Capacity exhaustion stops
 the sink. Errors stop writes, count losses and preserve any partial file; failed
 batches are not replayed. `reservedRecords/Bytes` include attempted writes, while
 `completedRecords/Bytes` count successful appends. `drained` means removed from
-the observer, not necessarily persisted. Queue count drops, byte-bound drops,
-record errors, missing/unavailable captures and sink failures remain separate.
+the observer, not necessarily persisted. Queue drops (count-bound and byte-bound
+together in `dropped`; `droppedBytes` adds the bytes of byte-bound drops), record
+errors, missing/unavailable captures and sink failures remain separate.
 
 Live collection, private destination/retention selection, corpus labels, hosted
 calibration, native placement, package/install proof and independent visible /

package/daemon/docs/reference/telemetry.md

@@ -0,0 +1,114 @@
+# Finite telemetry metadata
+
+`rig telemetry` reads one bounded page of retained history from the daemon. It is
+useful for collectors and operators that need a cursor without reading OpenRig's
+private SQLite schema. It neither watches nor automatically drains history.
+
+```sh
+rig telemetry events --json
+rig telemetry events --start retained --node NODE_ID --limit 128 --json
+rig telemetry events --start retained --rig RIG_ID --json
+rig telemetry events --cursor CURSOR --node NODE_ID --json
+rig telemetry transitions --start retained --qitem QUEUE_ITEM_ID --json
+rig telemetry tenures NODE_ID --json
+```
+
+Events and transitions initially return an empty checkpoint at the current high
+watermark, with `historical_events_not_read` or `historical_transitions_not_read`.
+Use `--start retained` to request the retained past. Tenures start with the newest
+32 records for the immutable node ID, with a descending continuation when needed.
+An empty match set can still have more source records: check `page.hasMore` and
+`page.nextCursor`. The cursor binds the stream and filters; retain the same filter
+options when continuing. Do not use `--start` with `--cursor`.
+
+## HTTP and envelope
+
+These reads use the daemon's existing browser/access boundary:
+
+| GET path | Query parameters |
+| --- | --- |
+| `/api/telemetry/v1/events` | `cursor`, `limit`, `start=latest\|retained`, `nodeId`, `rigId` |
+| `/api/telemetry/v1/queue-transitions` | `cursor`, `limit`, `start=latest\|retained`, `qitemId` |
+| `/api/telemetry/v1/nodes/:nodeId/tenures` | `cursor`, `limit` |
+
+The envelope contains `schemaVersion: 1`, `stream`, `observedAt`, `source`, `rows`,
+`page`, and `coverage`. Integer IDs are **decimal strings**, including values larger
+than JavaScript's safe integer range. `--json` preserves the complete envelope.
+
+- Events: `seq`, `rigId`, `nodeId`, `type`, `originalTimestamp`, `createdAt`.
+- Transitions: original `transitionId`, `qitemId`, `state`, `actorSession`,
+  `identityProvenance`, `closureReason`, `closureTarget`, `originalTimestamp`, `createdAt`.
+- Tenures: `nodeId`, `generationOrdinal`, `generationUuid`, `kind`,
+  `nativeSessionIdAtBoot`, `originalTimestamp`, `bootAt`.
+
+Normalized `createdAt` and `bootAt` are explicit UTC or null with a named gap.
+SQLite timestamps without a timezone are interpreted as UTC. Original timestamps
+remain available. Streams have separate sequences; their IDs do not establish
+cross-stream causal ordering. Event type alone establishes no readiness, activity,
+or native-exit verdict. Repeated same-state transitions remain separate records.
+Null boot identity stays unknown, and a tenure has no inferred end time. Historical
+records are never joined to today's owner or node name.
+
+`page` reports the requested boundary (`requestedAfter` or `requestedBefore`),
+`lastScanned`, fixed `through`, `retainedHighWatermark`, `hasMore`, `nextCursor`,
+`restartCursor`, and `fetched`, `scanned`, `filtered`, `withheld`, `returned`,
+`capReason`. New writes above a window's `through` wait until that window is
+complete. A complete ascending checkpoint opens another finite window on its next
+use. Descending tenure history ends with a null continuation.
+Its cursor also retains the first observed lower ordinal, so disappearance of that
+older range produces a named gap even when some records remain on the final page.
+
+## Bounds and privacy
+
+The default/max source page is 128 rows; tenures default to 32. Sparse filters run
+**after** that bound, so matching nothing still advances over scanned records.
+Transitions fetch at most 128 candidates from each of the active/archive tables
+in one read snapshot, then process at most 128 distinct ordered IDs. Equal
+projected duplicates collapse; conflicting IDs are withheld with a named gap.
+Physical `fetched` can therefore exceed logical `scanned`.
+
+Responses are at most 128 KiB, with a 4 KiB projected-record cap. SQL guards bound
+fields before fetching them: identifiers 256 bytes, timestamps/enums 128 bytes,
+and actor/closure references 512 bytes. Oversized fields become null with an
+`oversized_field` gap, and non-text values become null with an `invalid_type` gap;
+they are never truncated into a different identity. A record
+whose JSON escaping still exceeds 4 KiB is withheld and counted. A response-byte
+stop leaves the next unprocessed record for the continuation. Gap details are
+capped at 32; `gapCount` and `gapDetailsTruncated` preserve the count. Cursor input
+is limited to 2 KiB. These are work/size bounds, not a disk-latency guarantee.
+
+No event payload, transition note, queue body/summary, transcript, command, path,
+or environment is selected. Operational IDs, native conversation IDs and actor
+addresses are intentional metadata; they can still identify people or seats.
+This interface does not make that metadata public or anonymous.
+
+## Unknown history and errors
+
+`coverage.historyCompleteness` is always `unknown`. Coverage status is
+`retained_window`, `partial`, or `unavailable`; a retained window does not prove
+that older history exists or is complete. `retainedMinimum` and named gaps expose
+missing retained identifiers with unknown cause, never inferred downtime. Missing
+tenure history cannot distinguish node deletion from never-recorded history.
+
+`source` contains `hostId`, `bootEpoch`, and **`sequenceSpaceId: null`**. A daemon
+boot epoch is not durable store identity. On a boot change or observed watermark
+regression, the API returns no old-window rows, a named unavailable-history gap,
+and (for ascending streams) a separate fresh `restartCursor`. Record that gap
+before explicitly adopting the fresh checkpoint. Tenures may be requested fresh
+without a cursor. Do not silently reset to zero or conflate existing collector
+source identity, native-tail cursors and these cursors. An arbitrary in-place
+database restore/copy without an observable regression is not detected.
+
+After **every daemon restart**, a following collector cannot continue its old
+cursor. To recover available retained history, record the boot gap and start a new
+read with `start=retained`, accepting possible overlap with previously read records.
+Alternatively, adopting `restartCursor` observes only new records after the fresh
+high watermark; it does not recover the missed interval. Neither choice proves
+continuity across the restart while `sequenceSpaceId` remains null.
+
+Malformed cursors/options return HTTP 400 `telemetry_invalid_request`.
+Schema/read/source failures return HTTP 503 `telemetry_read_unavailable`, never a
+successful empty history. The CLI preserves the error body in JSON mode and exits
+1 for request errors, 2 for unavailable reads. Existing SSE and usage APIs retain
+their behavior. Collector deployment, exporters and durable store epochs are
+separate work.