Skip to content

Commit 0e18ec0

Browse files
schicklingclaude
andcommitted
docs(vrs): written claims in the contract, and an honestly scoped cross-check
OHS-T04/OHS-R07 no longer overclaim: the probe narrows the ungraceful window only for provably dead sessions (pidfile present, process gone), pty kill's pidfile removal is named, and the relaunch-time written claim is what supersedes what the probe cannot prove. The ownership bullet carries the written-claim semantics. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 3c565fc commit 0e18ec0

2 files changed

Lines changed: 33 additions & 18 deletions

File tree

docs/vrs/05-harness-state/requirements.md

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,13 @@ path reads this record.
5757
truthful about dwell time. `transitions` and `sinceMs` keep a later history
5858
additive.
5959
- **OHS-T04 Ungraceful-death windows:** SIGKILL cannot be caught, so an
60-
external forced kill — and nothing else — can leave a live-state record
61-
whose writer is gone. Same-host readers close that window with the liveness
62-
cross-check (OHS-R07); cross-host readers wait out the staleness horizon.
60+
external forced kill can leave a live-state record whose writer is gone.
61+
Same-host readers narrow that window with the liveness cross-check
62+
(OHS-R07) where the session is PROVABLY dead — pidfile present, process
63+
gone — while `pty kill` removes the pidfile and leaves the probe
64+
indeterminate for the rest of the window; the next session's written
65+
ownership claim supersedes the orphan at relaunch, and cross-host readers
66+
wait out the staleness horizon.
6367

6468
## Requirements
6569

@@ -115,10 +119,13 @@ path reads this record.
115119
and a terminal record is never re-stamped.
116120
- **OHS-R07 Liveness cross-check:** The record names the pty session whose
117121
liveness vouches for its live states. A same-host reader that positively
118-
proves that session dead reads the record as `unknown` even while fresh; an
119-
indeterminate probe (unreadable registry) downgrades nothing — unprovable
120-
evidence is never reported as death. A fresh `ended` survives the check: a
121-
terminal record is supposed to outlive its writer.
122+
proves that session dead — its pidfile present, its process gone — reads
123+
the record as `unknown` even while fresh; an indeterminate probe (an
124+
unreadable registry, or a pidfile `pty kill` already removed) downgrades
125+
nothing — unprovable evidence is never reported as death. The check is a
126+
narrowing, not a closure: what it cannot prove, the relaunch-time written
127+
claim supersedes and the staleness horizon bounds. A fresh `ended`
128+
survives the check: a terminal record is supposed to outlive its writer.
122129
- **OHS-R08 All-harness coverage:** Codex, Claude, pi, and OpenCode each ship
123130
a producer. pi's is evented through the injected extension (the positive
124131
idle signal root `DQ2` asks for). OpenCode reaches driver parity first —

docs/vrs/05-harness-state/spec.md

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -74,17 +74,25 @@ Field rules, matching `src/harness_state.rs`:
7474
`human` (`none` otherwise; unrecognized words decode indeterminate) — the
7575
axis consumers filter on, so nothing branches on diagnostic `reason`.
7676
- `incarnation` is the writing session's token and `seq` its monotonic
77-
ownership sequence: ownership — coalescing, heartbeat eligibility, terminal
78-
suppression — is token equality, and only a session claim advances the
79-
sequence (to the on-disk value plus one), which gives ownership a
80-
direction: a straggler from a superseded session is refused in live and
81-
terminal paths alike. Sibling writer processes of one session share the
82-
claimer's exported token and sequence; records from writers predating
83-
either field decode with an empty token and sequence zero, which no
84-
session owns and any claim supersedes. Every landed write carries a
85-
strictly monotonic per-record stamp (never inherited from beyond the
86-
future-skew trust bound) so it stays byte-distinct even against a
87-
same-millisecond predecessor.
77+
ownership sequence. A claim is a WRITTEN act under the record lock: the
78+
session starting up writes an exitless `ended (superseded)` takeover
79+
record carrying its token and the on-disk sequence plus one — racing
80+
claimers therefore mint distinct sequences, and a predecessor's
81+
still-fresh live record is superseded at relaunch, where the
82+
pty-name-based probe cannot tell sessions apart; the seat reads
83+
`ended (superseded)` until the session's first real observation. Ownership
84+
— coalescing, heartbeat eligibility, terminal suppression (which applies
85+
only to exit-bearing terminal records, never the claim placeholder) — is
86+
token equality with the claim's direction: a straggler whose claim is
87+
below the on-disk sequence is refused in live and terminal paths alike,
88+
and a token-only writer never claims — it adopts its own session's
89+
records, starts virgin ones, and is refused against foreign tokens.
90+
Sibling writer processes of one session share the claimer's exported
91+
token and sequence; records predating either field decode with an empty
92+
token and sequence zero, which no session owns and any claim supersedes.
93+
Every landed write carries a strictly monotonic per-record stamp (never
94+
inherited from beyond the future-skew trust bound) so it stays
95+
byte-distinct even against a same-millisecond predecessor.
8896
- `reason` is diagnostic only; no consumer branches on it.
8997
- `sinceMs` is when the current state was entered and survives heartbeat
9098
re-stamps; `writtenAtMs` is the heartbeat. `transitions` is a monotonic

0 commit comments

Comments
 (0)