feat(harness-state): add v3 reader foundation

agent-identity: dev3.direct.omp.9exwnk6h
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.1.7
agent-runtime: OMP 18.1.7
tooling-profile: dotfiles@931583a

Author: schickling-assistant

INVARIANTS.md

@@ -137,3 +137,72 @@ declared native driver is expected to publish it. Telemetry repeats only the
 closed axes on
 metrics and `span.label`; raw versions and identities remain trace/log-only,
 and prompt/message/path content never enters the record or labels.
+
+## Amendment 2: the fault axis is a third record version with one shared disposition
+
+Accepted by Johannes on 2026-09-05 for the harness-state v3 foundation.
+
+The original decision put activity, `blockedOn`, and `inputBuffer` in one
+record and left everything else to prose in `reason`. That is what broke: an
+authentication rejection, an exhausted quota, a throttle, and a human
+permission prompt all arrive as some combination of `active`, `blockedOn`, and
+a `reason` word, so every consumer that wants to know "does this seat need a
+person, and to do what" ends up parsing prose or inventing its own rules. The
+amendment separates the axes and moves the fold into st2.
+
+**Condition becomes its own axis, in a new record version.** Because a version
+suffix is this record family's read contract, changing what the record says
+reserves the next version rather than widening the current one:
+`st2.harness-state.v3` carries a tagged `condition ∈ clear | fault`, where a
+fault names a closed category, an open provider-namespaced code, a recovery
+class, and its own semantic observation time. The overloaded `blockedOn` is
+replaced by a tagged ask axis that speaks only about actual human prompts. A
+fault is not an ask — a throttled provider asks nobody anything — and where
+both hold, remediation is primary while the ask stays visible. Versions 1 and 2
+project their condition as EXPLICITLY absent: their legacy words never infer a
+fault, and absence is never `clear`.
+
+**st2 owns normalization and publishes one derived disposition.** Three closed
+axes — a state, how soon a human is needed, and what that human would do first
+— from one pure function, exposed on the roster, the catalog graph, and Doctor.
+Consumers read it; none re-derives it. The raw axes ride beside it, so nothing
+is hidden by the fold and a consumer that disagrees can see its inputs. A
+native-driver diagnostic failure contributes through the same function — it is
+a fault the harness could not report itself — and, as Amendment 1 established,
+still never changes delivery. Ended and record-level indeterminate never page.
+
+**Two clocks, deliberately.** The heartbeat proves only that a writer still
+holds evidence; it never moves a fault's observation time or its recovery
+deadline. Attention is derived at read time, so an `automatic` recovery past
+its own deadline becomes an untyped, unknown-recovery fault that pages until an
+explicit paired clear, a terminal record, a new claim, or a new incarnation
+replaces it. Without that separation a seat could heartbeat its way out of an
+overdue recovery forever.
+
+**Options considered and rejected.** Widening version 1/2 in place: rejected,
+because the version suffix is the read contract and a pinned reader would
+decode new words with old meanings. A separate fault record beside
+`harness-state`: rejected for the same reason Amendment 1 chose one diagnostic
+snapshot — two files make every consumer choose precedence independently, and
+condition and activity are observations of one thing by one owner. Free-form
+provider strings promoted to a routable field: rejected, since the whole point
+is that consumers stop branching on prose; provider vocabulary is kept in the
+open `code` under a closed category. Each consumer deriving its own urgency:
+rejected, because two derivations are how one consumer starts paging for what
+another ignores.
+
+**Consequences.** Reader-first, again: this version reads, strictly validates,
+and projects version 3 while the single writer-selection point stays on version
+2, and version 3 activation replaces that point rather than adding a second
+selector. The ownership envelope is version-independent, so a version 2 claim
+refuses a version 3 record instead of overwriting a meaning it cannot read, and
+an undecodable record's ownership sequence still carries forward. Every
+projected row carries the exact version its record declared, which makes the
+migration's drain gate positive. The roster wire grows the appended version 3
+axes plus a row-level `disposition`; the pinned literals and the stable-roster
+invariant wording change deliberately in the same change. Per-provider
+mappings, the writer cutover, and what a recovery deadline should be are open
+(`DQ-H7`, `DQ-H8`). A conversation reference — identity and capability only,
+with a finite verification bound and no conversation content — ships in the
+same version, because a consumer that can see a fault will ask which
+conversation it belongs to.

docs/vrs/.decisions/0006-observed-harness-state-is-a-driver-written-catalog-record.md

@@ -77,3 +77,28 @@ hypotheses.
   (`src/opencode_session.rs::captured_permission_grant_pair_enters_and_exits_blocked`,
   `::captured_question_reply_pair_enters_and_exits_blocked`); the raw frames
   and commands are in `.experiments/2026-08-23-opencode-surface.md`.
+- **DQ-H7 Version 3 producers and the writer cutover.** The fault axis is
+  specified, read, strictly validated, and projected, and the shared
+  disposition is derived from it; no producer emits it yet and the
+  writer-selection point stays on version 2. Two things remain open. First,
+  the per-provider mapping: which typed signal each driver projects into
+  which closed category, code, and recovery — the same evidence rule the
+  activity projection follows (a driver publishes what it positively
+  observes, never prose), and the same measurement burden, since a category
+  is only worth routing on if the provider's signal really means it.
+  Second, the cutover order: the version 3 writer may activate only where
+  every reader of that catalog already accepts version 3, and the one-way
+  claim fence plus the version-independent ownership envelope are what make
+  a mixed fleet safe in the meantime — a version 2 writer refuses a version
+  3 record instead of overwriting a meaning it cannot read. Resolves by:
+  per-driver capture evidence for the mappings, then flipping the single
+  writer-selection point.
+- **DQ-H8 What a `nextObservationDueMs` should be.** The overdue rule is
+  specified and proved, but nothing yet establishes what deadline a producer
+  should publish for a given automatic recovery — a provider's stated retry
+  window, a measured one, or a conservative multiple of it. Too short pages
+  for faults that were going to clear; too long delays a page indefinitely,
+  which is the failure the rule exists to prevent. The field is optional
+  precisely so a producer that cannot justify a number withholds it, and a
+  fault with no deadline never becomes overdue. Resolves by: measured retry
+  behavior per provider, or an explicit decision to page on a fixed bound.

docs/vrs/05-harness-state/open-questions.md

@@ -204,6 +204,86 @@ authorizes or changes delivery.
   reached its ordinary end — clears it; an unclassified failure leaves a
   standing rejection standing. Delivery semantics are unchanged.
 
+### Must separate what is wrong from what is being asked
+
+- **OHS-R17 Condition is its own axis:** The record carries a tagged
+  `condition ∈ clear | fault`, published under its own record version so the
+  meaning of a version's bytes stays decidable from those bytes. A fault
+  carries a CLOSED `category ∈ authentication | account | quota | rateLimit |
+  provider | context | configuration | policy | harness` — closed because
+  consumers route on it — an OPEN, provider-namespaced `code` for diagnostic
+  granularity, a `recovery ∈ automatic | human | terminal | unknown`, and its
+  own semantic observation time. Provider prose is diagnostic only; no
+  consumer branches on it. A category word outside the closed set leaves the
+  fault UNTYPED and still routed by its recovery: neither borrowing a
+  neighbouring category nor discarding the whole observation is acceptable,
+  because the first invents a claim and the second makes a real fault stop
+  being reported. Versions without the axis project it as EXPLICITLY absent —
+  never `clear`, and no fault is inferred from their legacy words.
+- **OHS-R18 An ask is an actual human prompt:** The ask axis is tagged so
+  `none`, `pending` with its kind, and `unknown` are three distinct
+  statements, and it speaks only about prompts. A fault is not an ask: a
+  throttled provider asks nobody anything. Where a fault and an ask coexist,
+  remediation is primary and the ask remains visible on the raw axis.
+- **OHS-R19 Strict edges, typed indeterminacy:** A record whose OBSERVATION
+  axes contradict each other is not a weaker observation; it is not an
+  observation. Every rejection carries its own reason word — a `clear`
+  bearing fault evidence, a fault missing recovery or its observation time, a
+  recovery deadline on a recovery this version recognizes as non-automatic,
+  an inverted deadline, an ask that names a kind while claiming none — so an
+  operator can tell a producer bug from a stale seat and one bug from
+  another. Rejection is scoped to what the contradiction actually damages:
+  strictness must not destroy evidence. A deadline beside an UNRECOGNIZED
+  recovery word is kept, because that class may be automatic in a version
+  the reader predates and rejecting it would turn a fault that pages into a
+  non-paging row; and a badly stated conversation reference degrades only
+  that axis, because a broken side-channel is not evidence about the harness.
+  Indeterminacy is exposed TYPED, carrying that word and the age of the
+  evidence it was derived from when the bytes carried a usable stamp; the
+  legacy scalar reason remains a projection of the same single value and is
+  never derived independently.
+- **OHS-R20 Two clocks:** Transport freshness and semantic observation are
+  separate. The heartbeat proves only that a writer still holds evidence; it
+  never moves a fault's observation time or its recovery deadline, and
+  attention is derived at READ time. An `automatic` recovery past its own
+  deadline becomes an untyped, unknown-recovery fault that pages until an
+  explicit paired clear, a terminal record, a new claim, or a new incarnation
+  replaces it — a recovery that missed its own deadline is no longer evidence
+  of anything automatic.
+- **OHS-R21 One shared disposition:** st2 owns normalization and publishes
+  ONE derived disposition — exactly three closed axes: a state, how soon a
+  human is needed, and what that human would do first — from one pure
+  function, exposed on the roster, the catalog graph, and Doctor. Consumers
+  read it; none re-derives urgency, because two independent derivations are
+  how one consumer starts paging for what another ignores. Raw activity, the
+  actual human ask, the condition, and recovery stay orthogonal and ride
+  beside it, so a consumer that disagrees can see exactly what was folded.
+  Ended and record-level indeterminate never page. A native-driver diagnostic
+  failure contributes through the same function — it is a fault the harness
+  could not report itself — and still never changes delivery.
+- **OHS-R22 Conversation reference is identity and capability:** The
+  conversation bridge is tagged `linked | unavailable | unsupported`, and a
+  linked reference carries the driver's namespace, the provider's opaque
+  conversation identity, the runtime incarnation, an explicit history
+  mutability claim with the evidence for it, and a FINITE verification bound
+  so a consumer ages the claim instead of trusting it forever. A record that
+  states nothing about a conversation claims no capability, which is distinct
+  from `unsupported`. Conversation content stays out of the record entirely.
+  A `linked` reference that is not fully stated is not trusted and not
+  discarded either: it degrades to `unavailable` carrying st2's own closed
+  rejection word — never provider prose — and the observation's activity,
+  condition, and ask axes stand untouched.
+- **OHS-R23 Reader-first activation with a positive drain gate:** A record
+  version is read, strictly validated, and projected before any writer emits
+  it, and exactly one writer-selection point decides which version this build
+  writes. Every projected row carries the EXACT version its record declared,
+  including versions the build cannot interpret, so a migration's drain gate
+  is positive — "every row reads the new version" is checkable, while "no row
+  is still the old one" is not checkable from any absence. The ownership
+  envelope is version-independent, so a claim honors the schema fence and the
+  ownership sequence of a record whose meaning it cannot read rather than
+  treating those bytes as an empty seat.
+
 ## Evidence
 
 The measurements are #268's, taken 2026-08-16/17 on one host and carried with