done-done-axi 0.6.3 → 0.6.4

package/dist/lint.js

@@ -1,6 +1,7 @@
 // `done-done lint`: the deterministic merge gate on a worker's claim. It reads the newest "## Checks" block of a PR body
 // or report file and fails an unproven, reused or oversized claim. No judge, no model; the repo config only switches on
-// the two optional size rules (checks.upstream_catch_up, checks.moved_from) and extra generated paths (checks.generated_paths).
+// the two optional size rules (checks.upstream_catch_up, checks.moved_from) and extra generated paths (checks.generated_paths);
+// files the target repo marks generated in .gitattributes are not counted either.
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
@@ -8,6 +9,26 @@ import { basename, dirname, isAbsolute, join, matchesGlob, resolve } from 'node:
 // Third-party, legal text and committed build output are not reviewable code.
 const GENERATED = /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|go\.sum|[^/]*\.lock)$|(^|\/)vendor\/|(^|\/)dist\/|(^|\/)(LICENSE|LICENSES|NOTICE|COPYING)[^/]*$/;
 const generatedBy = (globs = []) => (p) => GENERATED.test(p) || globs.some((g) => matchesGlob(p, g));
+// A target repo's own .gitattributes marks generated files: linguist-generated, linguist-generated=true or -diff. The last matching line wins;
+// linguist-generated=false and an unset attribute mean not generated. A pattern with no slash matches the basename, like git.
+function attrGenerated(attrs) {
+    const rules = attrs.split('\n').map((l) => l.trim().split(/\s+/)).filter((w) => w[0] && !w[0].startsWith('#') && w.length > 1);
+    return (p) => {
+        let gen = false;
+        for (const [pat, ...as] of rules) {
+            const glob = pat.replace(/^\//, '');
+            if (!matchesGlob(glob.includes('/') ? p : basename(p), glob.endsWith('/') ? `${glob}**` : glob))
+                continue;
+            for (const a of as) {
+                if (/^(linguist-generated(=true)?|-diff)$/.test(a))
+                    gen = true;
+                else if (/^(linguist-generated=false|-linguist-generated|!linguist-generated)$/.test(a))
+                    gen = false;
+            }
+        }
+        return gen;
+    };
+}
 export const SIZE_LIMIT = 1000;
 const FIX_TITLE = /^(fix|bugfix|hotfix)\b/i;
 const NOT_APPLICABLE = /^n\/?a\b/i;
@@ -70,7 +91,8 @@ function movedLines(run, nwo, body, paths, isGenerated) {
 const sha256 = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
 // src: a PR URL or a report file; ev: the folder the evidence names are relative to; dir: where the hash store and log live.
 export function lint(src, ev, dir, rules = {}, run = gh) {
-    const isGenerated = generatedBy(rules.generated_paths);
+    const byConfig = generatedBy(rules.generated_paths);
+    let isGenerated = byConfig;
     let warn = ''; // set for a PR that touches src/ with no journeys/ file; it only softens a PASS
     const log = (v) => {
         if (v.ok && warn)
@@ -95,6 +117,12 @@ export function lint(src, ev, dir, rules = {}, run = gh) {
         const author = pr.author?.login ?? '';
         if (/^(app\/)?(dependabot|renovate)(\[bot\])?$/.test(author))
             return log({ ok: true, why: 'bot', head });
+        const nwo = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\//.exec(src)?.[1];
+        const attrs = nwo && [head, pr.baseRefOid].map((ref) => ref && run('api', '-H', 'Accept: application/vnd.github.raw', `repos/${nwo}/contents/.gitattributes?ref=${ref}`)).find((a) => a && a.status === 0);
+        if (attrs) {
+            const byAttr = attrGenerated(attrs.stdout);
+            isGenerated = (p) => byConfig(p) || byAttr(p);
+        }
         const paths = (pr.files ?? []).map((f) => f.path ?? '');
         if (paths.some((p) => p.startsWith('src/')) && !paths.some((p) => p.startsWith('journeys/')))
             warn = 'the diff changes src/ and no journeys/ file: run the journey, commit it, then open the PR';
@@ -103,7 +131,6 @@ export function lint(src, ev, dir, rules = {}, run = gh) {
             const d = run('pr', 'diff', src);
             if (!d.status) {
                 let net = netLines(d.stdout, isGenerated);
-                const nwo = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\//.exec(src)?.[1];
                 if (nwo && rules.upstream_catch_up && total(net) >= SIZE_LIMIT)
                     net = without(net, upstreamDelta(run, nwo, head, pr.baseRefOid ?? '', isGenerated));
                 if (nwo && rules.moved_from && total(net) >= SIZE_LIMIT)

package/docs/examples/statechart-pilot/PaneAttach.tla

@@ -0,0 +1,151 @@
+------------------------------ MODULE PaneAttach ------------------------------
+(* Two Herdr panes, one shared tree refresh and one attach, as muxr v0.2.9 runs  *)
+(* them on @byokit/herdr 0.16.1. Pane A closes; pane B survives and is the pane  *)
+(* the user opens. Each action names the code it stands for; see README.md.      *)
+EXTENDS FiniteSets
+
+CONSTANTS
+    Matched,     \* reply-id shapes socket.js counts as a refusal of its own watch
+    DrainsQueue  \* runBootstrap starts the queued follow-up (FALSE: broken variant)
+
+Panes   == {"A", "B"}
+Callers == {"R", "U"}  \* R: any other refresh caller; U: the user's attach to B
+\* Herdr answers a watch on a closed pane with id "<id>:sub:0:probe" (muxr PR 1006).
+RefusalShape == "subProbe"
+
+VARIABLES
+    alive,        \* Herdr: the pane exists
+    closedEvt,    \* A's pane_closed event is on its way to the kit's event socket
+    booting,      \* kit.js `booting`
+    queued,       \* kit.js `queued`
+    phase,        \* runBootstrap: "idle", "reading" (snapshot in flight), "acks"
+    waiters,      \* kit.js `waiters`
+    nextWaiters,  \* kit.js `nextWaiters`
+    watch,        \* per-pane status watch socket
+    ready,        \* that watch's `ready` promise
+    refusal,      \* Herdr has refused this pane's watch (the pane is gone for good)
+    caller        \* each refresh() caller
+
+vars == <<alive, closedEvt, booting, queued, phase, waiters, nextWaiters,
+          watch, ready, refusal, caller>>
+
+TypeOK ==
+    /\ alive \in [Panes -> BOOLEAN]
+    /\ closedEvt \in BOOLEAN /\ booting \in BOOLEAN /\ queued \in BOOLEAN
+    /\ phase \in {"idle", "reading", "acks"}
+    /\ waiters \subseteq Callers /\ nextWaiters \subseteq Callers
+    /\ watch \in [Panes -> {"none", "opening", "retry", "open", "stopped"}]
+    /\ ready \in [Panes -> {"none", "pending", "ok", "refused"}]
+    /\ refusal \in [Panes -> BOOLEAN]
+    /\ caller \in [Callers -> {"idle", "waiting", "done"}]
+
+\* The kit has started: its first bootstrap landed and both watches acked.
+Init ==
+    /\ alive = [p \in Panes |-> TRUE]
+    /\ closedEvt = FALSE /\ booting = FALSE /\ queued = FALSE /\ phase = "idle"
+    /\ waiters = {} /\ nextWaiters = {}
+    /\ watch = [p \in Panes |-> "open"]
+    /\ ready = [p \in Panes |-> "ok"]
+    /\ refusal = [p \in Panes |-> FALSE]
+    /\ caller = [c \in Callers |-> "idle"]
+
+\* runBootstrap -> bootstrap sends `session.snapshot` (kit.js:523-530, 363-371).
+StartBoot == booting' = TRUE /\ phase' = "reading"
+
+\* kit.refresh() (kit.js:694-706). U reaches it through open -> resolvePane ->
+\* refreshSnapshot -> client.kit.refresh() (herdrSessionSource.ts:2606, 1878-1897, 1578-1583).
+Refresh(c) ==
+    /\ caller[c] = "idle"
+    /\ caller' = [caller EXCEPT ![c] = "waiting"]
+    /\ IF booting
+         THEN /\ queued' = TRUE /\ nextWaiters' = nextWaiters \cup {c}
+              /\ UNCHANGED <<waiters, booting, phase>>
+         ELSE /\ waiters' = waiters \cup {c} /\ StartBoot
+              /\ UNCHANGED <<queued, nextWaiters>>
+    /\ UNCHANGED <<alive, closedEvt, watch, ready, refusal>>
+
+\* Pane A closes. Herdr closes an acked watch's socket, which re-dials after 2 s
+\* (socket.js:115-121); a watch still opening is answered by HerdrAnswer.
+CloseA ==
+    /\ alive["A"]
+    /\ alive' = [alive EXCEPT !["A"] = FALSE]
+    /\ closedEvt' = TRUE
+    /\ watch' = IF watch["A"] = "open" THEN [watch EXCEPT !["A"] = "retry"] ELSE watch
+    /\ UNCHANGED <<booting, queued, phase, waiters, nextWaiters, ready, refusal, caller>>
+
+\* A structural event queues a bootstrap, or a follow-up while one runs (kit.js:582-597, 562-568).
+ClosedEventLands ==
+    /\ closedEvt
+    /\ closedEvt' = FALSE
+    /\ IF booting
+         THEN queued' = TRUE /\ UNCHANGED <<booting, phase>>
+         ELSE StartBoot /\ UNCHANGED queued
+    /\ UNCHANGED <<alive, waiters, nextWaiters, watch, ready, refusal, caller>>
+
+\* The snapshot lands: stop the old status watches, open one per agent pane in it
+\* (kit.js:409-414, 440-447; openStatusWatch kit.js:496-514).
+SnapshotLands ==
+    /\ phase = "reading"
+    /\ phase' = "acks"
+    /\ watch' = [p \in Panes |-> IF alive[p] THEN "opening"
+                                 ELSE IF watch[p] = "none" THEN "none" ELSE "stopped"]
+    /\ ready' = [p \in Panes |-> IF alive[p] THEN "pending" ELSE "none"]
+    /\ UNCHANGED <<alive, closedEvt, booting, queued, waiters, nextWaiters, refusal, caller>>
+
+\* Herdr answers one `events.subscribe` (socket.js:94-112). A live pane acks. A closed
+\* pane is refused, then Herdr closes the socket: a matched refusal settles `ready` false
+\* and stops; an unmatched one is ignored and the close handler re-dials (socket.js:115-121).
+HerdrAnswer(p) ==
+    /\ watch[p] = "opening"
+    /\ IF alive[p]
+         THEN /\ watch' = [watch EXCEPT ![p] = "open"]
+              /\ ready' = IF ready[p] = "pending" THEN [ready EXCEPT ![p] = "ok"] ELSE ready
+              /\ UNCHANGED refusal
+         ELSE /\ refusal' = [refusal EXCEPT ![p] = TRUE]
+              /\ IF RefusalShape \in Matched
+                   THEN /\ watch' = [watch EXCEPT ![p] = "stopped"]
+                        /\ ready' = IF ready[p] = "pending" THEN [ready EXCEPT ![p] = "refused"] ELSE ready
+                   ELSE /\ watch' = [watch EXCEPT ![p] = "retry"] /\ UNCHANGED ready
+    /\ UNCHANGED <<alive, closedEvt, booting, queued, phase, waiters, nextWaiters, caller>>
+
+\* later(open, backoff) dials a fresh watch with a new id (socket.js:88-92, 120-124).
+Retry(p) ==
+    /\ watch[p] = "retry"
+    /\ watch' = [watch EXCEPT ![p] = "opening"]
+    /\ UNCHANGED <<alive, closedEvt, booting, queued, phase, waiters, nextWaiters, ready, refusal, caller>>
+
+\* Every watch this bootstrap opened has settled (Promise.allSettled, kit.js:446-447), so
+\* runBootstrap's statusWatchReady() returns: answer the waiters and start the queued
+\* follow-up for nextWaiters (kit.js:531-557). An answered attach finds B in the tree.
+AcksSettle ==
+    /\ phase = "acks"
+    /\ \A p \in Panes : ready[p] # "pending"
+    /\ caller' = [c \in Callers |-> IF c \in waiters THEN "done" ELSE caller[c]]
+    /\ IF queued /\ DrainsQueue
+         THEN /\ queued' = FALSE /\ waiters' = nextWaiters /\ nextWaiters' = {}
+              /\ StartBoot
+         ELSE /\ waiters' = {} /\ booting' = FALSE /\ phase' = "idle"
+              /\ UNCHANGED <<queued, nextWaiters>>
+    /\ UNCHANGED <<alive, closedEvt, watch, ready, refusal>>
+
+KitStep == ClosedEventLands \/ SnapshotLands \/ AcksSettle
+           \/ \E p \in Panes : HerdrAnswer(p) \/ Retry(p)
+
+Next == KitStep \/ CloseA \/ \E c \in Callers : Refresh(c)
+
+\* Herdr answers every request and the kit's timers fire: weak fairness on the kit and
+\* Herdr's replies. Pane closes and user actions get none; they may never happen.
+Spec == Init /\ [][Next]_vars
+        /\ WF_vars(ClosedEventLands) /\ WF_vars(SnapshotLands) /\ WF_vars(AcksSettle)
+        /\ \A p \in Panes : WF_vars(HerdrAnswer(p)) /\ WF_vars(Retry(p))
+
+\* Property 1: after a final refusal, its watch settles (stops for good).
+WatchSettles == \A p \in Panes : refusal[p] ~> (watch[p] = "stopped")
+
+\* Property 2: an attach to the surviving pane B eventually answers. This model has no
+\* failure path (no outage, no snapshot error), so an answer here is a success.
+AttachAnswers == (caller["U"] = "waiting") ~> (caller["U"] = "done")
+
+\* Witness: violated exactly when some run opens B, so the properties are not vacuous.
+NeverAttached == caller["U"] # "done"
+=============================================================================

package/docs/examples/statechart-pilot/README.md

@@ -0,0 +1,109 @@
+# Pane-attach race: a statechart pilot
+
+A small statechart and an executable model of one real bug: in muxr v0.2.9, a pane that closes before its status watch opens leaves the shared Herdr tree read waiting forever, so opening a pane that is still alive hangs. A pinned model checker finds that path on the old code, and the path is written below as the steps a user takes.
+
+**This is supporting evidence only. It is not proof that muxr works or fails.** Real-product replay: **not checked**. No Herdr lifecycle command was run and muxr was not touched. The journey entry that a real replay would follow is [pane-attach-race.md](pane-attach-race.md). It is written in the format of muxr's project skill and is waiting for an isolated Herdr lab.
+
+Files: [PaneAttach.tla](PaneAttach.tla) (model and properties), [check.mjs](check.mjs) (repeatable check), [pane-attach-race.md](pane-attach-race.md) (project-skill journey entry).
+
+## The code it models
+
+| Model action | Real code (muxr tag `v0.2.9`, `@byokit/herdr` 0.16.1 as published on npm) |
+|---|---|
+| `Refresh(U)`: the user opens pane B | `open` → `resolvePane` → `refreshSnapshot` → `client.kit.refresh()` (`apps/host/src/agent/infrastructure/herdrSessionSource.ts:2606, 1878-1897, 1578-1583`) |
+| `Refresh(c)` joins a running read or starts one | `HerdrKit.refresh()` (`dist/kit.js:694-706`) |
+| `StartBoot` / `SnapshotLands` | `runBootstrap` → `bootstrap` sends `session.snapshot`, stops the old status watches and opens one per agent pane (`dist/kit.js:523-530, 363-371, 409-414, 440-447`; `openStatusWatch` `dist/kit.js:496-514`) |
+| `CloseA`, then `ClosedEventLands` | a structural event queues a bootstrap, or a follow-up while one runs (`dist/kit.js:582-597, 562-568`); Herdr closing an acked watch's socket re-dials it (`dist/socket.js:115-121`) |
+| `HerdrAnswer(p)` | the watch's frame handler. Only an error whose id is `''` or exactly the watch's id counts as a refusal (`dist/socket.js:94-112`). Herdr refuses a watch on a closed pane with id `<id>:sub:0:probe` (the record in muxr PR 1006) |
+| `Retry(p)` | `later(open, backoff)` dials a new watch with a new id (`dist/socket.js:88-92, 120-124`) |
+| `AcksSettle` | `Promise.allSettled` over the watches' `ready` promises; `runBootstrap` then answers its waiters and starts the queued follow-up (`dist/kit.js:446-447, 531-557`) |
+
+Source identity: muxr `v0.2.9` is commit `3b8321f897f984ee1bf186177bf89ebfd812de2d`, whose `apps/host/package.json` pins `@byokit/herdr` `0.16.1`. The kit tarball `herdr-0.16.1.tgz` has sha256 `407fc6fce982fd61e5f1a77f60b0516c51ef6bf6963998f8ac80330d6bc2f2c9` (gitHead `39be7f88b7b13b7a9f32fbc1a1d74567016198b0`). Its `dist/socket.js` has sha256 `525d439da77312880dc170f9bf8f186bb0a295fb3d7210372ab19eda44700a90` and its `dist/kit.js` has sha256 `e4e6eb848e3043e97f4c95c485390a963879df67feb7f57a3f188828960f8597`.
+
+## Statechart
+
+One tree read in the kit:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Reading: refresh() or a pane event
+    Reading --> Reading: refresh() while reading, queued as a follow-up
+    Reading --> AwaitingWatches: snapshot lands, one watch opened per agent pane
+    AwaitingWatches --> Idle: every watch settled, waiters answered
+    AwaitingWatches --> Reading: every watch settled, queued follow-up starts
+```
+
+One pane's status watch:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Opening
+    Opening --> Open: Herdr accepts (pane alive), ready = true
+    Opening --> Stopped: refusal with an empty id or the watch's own id, ready = false
+    Opening --> Redial: refusal with id ...sub:0:probe, ignored in 0.16.1
+    Open --> Redial: Herdr closes the socket (pane closed)
+    Redial --> Opening: re-dial with a new id
+    Open --> Stopped: the next snapshot stops old watches
+```
+
+The bad loop is `Opening → Redial → Opening`, entered while the tree read waits in `AwaitingWatches`. The watch's `ready` never settles, so the tree read never leaves `AwaitingWatches`. Every `refresh()` waits behind it, and so does every pane open.
+
+## Properties
+
+1. **After a final refusal, its watch settles** (`WatchSettles`): once Herdr refuses a pane's watch, which happens only after the pane has closed for good, that watch eventually stops.
+2. **Opening a surviving pane eventually answers** (`AttachAnswers`): once the user opens pane B, the open eventually finishes. This model has no outage or snapshot error, so the only answer is success. Explicit failure paths are outside its scope.
+
+`NeverAttached` is a witness. It is violated exactly when some run opens B, which shows the properties are not passing trivially.
+
+## Results
+
+Run on 22 October 2026 with `node docs/examples/statechart-pilot/check.mjs <tla2tools.jar> <out-dir>`, which exited 0:
+
+| Run | Kit behaviour | Checks | Expected | Got | Distinct states |
+|---|---|---|---|---|---|
+| `old-watch` | 0.16.1 matcher (`''` or `<id>`) | `WatchSettles` | violated | violated | 460 |
+| `old-attach` | 0.16.1 matcher | `AttachAnswers` | violated | violated | 460 |
+| `old-witness` | 0.16.1 matcher | `NeverAttached` | violated (B can open) | violated | 97 |
+| `fixed` | also matches `<id>:` ids (the kit fix named in PR 1006) | both | hold | hold | 399 |
+| `fixed-witness` | corrected matcher | `NeverAttached` | violated (B can open) | violated | 93 |
+| `broken-attach` | corrected matcher, but `runBootstrap` never starts the queued follow-up | `AttachAnswers` | violated | violated | 435 |
+| `broken-watch` | the same broken variant | `WatchSettles` | holds | holds | 435 |
+
+The broken variant is caught by the attach property, which was not written for it. The watch property still holds for that variant, so the two properties check different things.
+
+### The counterexample, as user steps (`old-attach`)
+
+1. Umer opens agent B on the phone. The host asks the kit to re-read the Herdr tree.
+2. Something else re-reads the tree at the same moment, such as another open. It queues behind the first read.
+3. The tree comes back listing agents A and B. The kit opens a status watch for each and waits for both.
+4. Agent A's pane closes before Herdr has accepted A's watch.
+5. Herdr accepts B's watch.
+6. Herdr refuses A's watch with id `<id>:sub:0:probe` and closes the socket. The kit does not see that id as a refusal, logs nothing, and dials A's watch again.
+7. Each new dial gets the same refusal, forever.
+
+What Umer sees: B stays on "connecting" even though B is alive. Every later open queues behind the same tree read. Only stopping the kit (a host restart) rejects the waiting opens. `old-watch` reaches the same loop one read later: the first tree read lands, and the queued follow-up read is the one that hangs.
+
+## Model report
+
+- Checker: TLC2 Version 2.19 of 08 August 2024 (rev: 5a47802), from [tla2tools.jar v1.7.4](https://github.com/tlaplus/tlaplus/releases/tag/v1.7.4). Its sha256 is `936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88` and its sha1 `bee4a54f3ee3d4afc347c3240ec2d9e93b075104` matches the release notes. `check.mjs` refuses any other jar. It ran on OpenJDK 21.0.2 with `-workers 1 -deadlock`: v1.7.4's liveness check is only sound with one worker (tlaplus issue 971), and finished runs are allowed to stop.
+- Model `PaneAttach.tla` sha256: `47caab3c3d5eb0fe34841ae841e93cafb51873b67e861fdd1d1e63aee3e7e739`.
+- Properties (sha256 of each definition's text): `WatchSettles` `7b79e33aa012dad92414f12b13df535f87fb3ee4facee03b6b07d1695cf373a0`, `AttachAnswers` `40e9a75d27e47f467113ddc84428528769d192a80c73fa112891eb5e8b0da678`, `NeverAttached` `ab58eddaa46974dcbc9273bc1698e06255a1e04c74f44c5f22e501e1b71f122c`.
+- Source commit: muxr `3b8321f897f984ee1bf186177bf89ebfd812de2d` (`v0.2.9`) with `@byokit/herdr` 0.16.1 (identity above).
+- Bounds: two panes (A may close, B never closes), one other refresh caller and one open of B, each made once. Every open and dial of a watch is modelled, with no retry cap, because the watch loop is finite in state. A full search finds every reachable state; no depth limit is used.
+- Assumptions:
+  - Herdr answers every request and the kit's timers fire. This is weak fairness on the kit and Herdr steps. The refusal is a delivered answer, not a lost packet, so a network that never answers is not mistaken for this bug.
+  - Closing a pane and the user's actions get no fairness; they may never happen.
+  - A closed pane never comes back.
+  - A snapshot shows the panes alive when it lands. A pane closing between Herdr's read and the reply landing is the same race as closing just after it lands.
+  - The `<id>:sub:0:probe` refusal shape comes from the record in muxr PR 1006, not from a Herdr run here.
+  - Not modelled: Herdr outages, snapshot errors, the event socket reconnecting, `kit.stop()`, and the 20-second refresh bound and kit restart that PR 1006 adds to the host. Whether that host recovery repairs the property is a separate check and is not claimed here.
+
+## Rerun it
+
+```bash
+curl -fLo tla2tools.jar https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar
+node docs/examples/statechart-pilot/check.mjs tla2tools.jar <out-dir>
+```
+
+Each run's TLC transcript, counterexamples included, and `model-report.json` with every hash land in `<out-dir>`. The command exits 1 when any run differs from the expected result above. When the kit or `herdrSessionSource.ts` changes, re-read the cited lines, update the model to match the code, and rerun. If the code no longer matches a row in the code-map table, the model is stale and its results do not apply.

package/docs/examples/statechart-pilot/check.mjs

@@ -0,0 +1,72 @@
+// Model check for the pane-attach race pilot: runs the pinned TLC on PaneAttach.tla for the old kit, the corrected
+// kit, a deliberately broken variant and two reachability witnesses, and fails unless each gives its expected result.
+// Usage: node docs/examples/statechart-pilot/check.mjs <tla2tools.jar> <out-dir>. Needs java on PATH; writes one TLC
+// transcript per run and model-report.json into <out-dir>. This is supporting evidence, never real-product proof.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// tla2tools.jar from https://github.com/tlaplus/tlaplus/releases/tag/v1.7.4 (sha1 bee4a54f… as its release notes list).
+const TLC_SHA256 = '936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88';
+const OLD = '{"exact", "empty"}'; // socket.js:95: frame.id === '' || frame.id === id
+const FIXED = '{"exact", "empty", "subProbe"}'; // the kit fix PR 1006 names: match "<id>:" ids too
+const RUNS = [
+  { name: 'old-watch', matched: OLD, drains: 'TRUE', check: 'PROPERTY WatchSettles', expect: 'violated' },
+  { name: 'old-attach', matched: OLD, drains: 'TRUE', check: 'PROPERTY AttachAnswers', expect: 'violated' },
+  { name: 'old-witness', matched: OLD, drains: 'TRUE', check: 'INVARIANT NeverAttached', expect: 'violated' },
+  { name: 'fixed', matched: FIXED, drains: 'TRUE', check: 'PROPERTY WatchSettles AttachAnswers', expect: 'holds' },
+  { name: 'fixed-witness', matched: FIXED, drains: 'TRUE', check: 'INVARIANT NeverAttached', expect: 'violated' },
+  // Broken variant: the corrected kit, but runBootstrap never starts the queued follow-up (kit.js:550-555).
+  { name: 'broken-attach', matched: FIXED, drains: 'FALSE', check: 'PROPERTY AttachAnswers', expect: 'violated' },
+  { name: 'broken-watch', matched: FIXED, drains: 'FALSE', check: 'PROPERTY WatchSettles', expect: 'holds' },
+];
+
+const [jar, outArg] = process.argv.slice(2);
+if (!jar || !outArg) {
+  console.error('usage: node docs/examples/statechart-pilot/check.mjs <tla2tools.jar> <out-dir>');
+  process.exit(2);
+}
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+const jarHash = sha256(readFileSync(jar));
+if (jarHash !== TLC_SHA256) {
+  console.error(`check: ${jar} has sha256 ${jarHash}, not the pinned TLC v1.7.4 ${TLC_SHA256}`);
+  process.exit(2);
+}
+const here = dirname(fileURLToPath(import.meta.url));
+const model = readFileSync(join(here, 'PaneAttach.tla'), 'utf8');
+const definition = (name) => model.match(new RegExp(`^${name} ==.*(?:\\n[ \\t].*)*`, 'm'))[0];
+const out = resolve(outArg);
+mkdirSync(out, { recursive: true });
+const work = mkdtempSync(join(tmpdir(), 'dd-paneattach-'));
+const report = {
+  tool: '', java: spawnSync('java', ['-version'], { encoding: 'utf8' }).stderr.split('\n')[0], tla2tools_sha256: jarHash,
+  model_sha256: sha256(model),
+  properties: Object.fromEntries(['WatchSettles', 'AttachAnswers', 'NeverAttached'].map((p) => [p, sha256(definition(p))])),
+  runs: [],
+};
+let failed = false;
+try {
+  copyFileSync(join(here, 'PaneAttach.tla'), join(work, 'PaneAttach.tla'));
+  for (const run of RUNS) {
+    const cfg = `SPECIFICATION Spec\nCONSTANTS\n  Matched = ${run.matched}\n  DrainsQueue = ${run.drains}\nINVARIANT TypeOK\n${run.check}\n`;
+    writeFileSync(join(work, `${run.name}.cfg`), cfg);
+    // One worker: TLC 1.7.4 liveness checking is only sound single-threaded (tlaplus issue 971).
+    const r = spawnSync('java', ['-cp', resolve(jar), 'tlc2.TLC', '-workers', '1', '-deadlock', '-cleanup',
+      '-metadir', join(work, `${run.name}.states`), '-config', `${run.name}.cfg`, 'PaneAttach.tla'], { cwd: work, encoding: 'utf8' });
+    const text = r.stdout + r.stderr;
+    writeFileSync(join(out, `${run.name}.txt`), `${cfg}\n${text}`);
+    report.tool ||= text.match(/TLC2 Version [^\n]*/)?.[0] ?? '';
+    const got = /No error has been found/.test(text) ? 'holds' : /(Temporal properties were violated|Invariant \w+ is violated)/.test(text) ? 'violated' : 'error';
+    const states = text.match(/(\d+) distinct states found/)?.[1];
+    report.runs.push({ ...run, cfg_sha256: sha256(cfg), got, distinct_states: Number(states), exit: r.status });
+    console.log(`${got === run.expect ? 'ok  ' : 'FAIL'} ${run.name}: expected ${run.expect}, got ${got} (${states} distinct states)`);
+    if (got !== run.expect) failed = true;
+  }
+} finally {
+  rmSync(work, { recursive: true, force: true });
+}
+writeFileSync(join(out, 'model-report.json'), `${JSON.stringify(report, null, 2)}\n`);
+process.exit(failed ? 1 : 0);

package/docs/examples/statechart-pilot/pane-attach-race.md

@@ -0,0 +1,37 @@
+# A pane that closes before its watch opens never stops other panes opening
+
+A journey entry in the format of muxr's project skill (`.agents/skills/done-done-verify-pockit/features/`). It turns the model checker's counterexample in [README.md](README.md) into a journey on the real product. The entry lives here until muxr's verification owner replays it in an isolated Herdr lab and moves it into muxr's skill.
+
+**Real-product replay: not checked.** The model results are supporting evidence only. They never count as proof that this journey passes or fails.
+
+## Sub-features
+
+- While a tree read waits on the status watches, an agent pane closes before Herdr accepts its watch. Opening a different, live agent still finishes: the terminal opens, or the phone shows an explicit error. It never stays on "connecting".
+- Later opens after that moment answer at normal speed, without a host restart.
+
+## How to get to it (user POV)
+
+- On a busy computer, agents come and go. Open any live agent on the phone right as another agent finishes. The terminal opens.
+
+## Driving it with the private stack
+
+Needs a separately authorized, isolated Herdr lab session. Never drive the captain's live Herdr.
+
+1. Start a lab host against a named lab Herdr session with two agent panes, A and B, and pair a lab phone client (Umer).
+2. Hold A's `pane.agent_status_changed` subscribe at a socket proxy so the kit's tree read waits for A's watch, then close pane A. This is step 4 of the counterexample.
+3. Release the subscribe. Herdr answers `{"id":"<id>:sub:0:probe","error":{"code":"pane_not_found"}}` and closes the socket.
+4. Open B from the phone, type a short line, and read it back in the terminal.
+5. Open B a second time.
+
+Pass: steps 4 and 5 each open the terminal and show the typed line, or show an explicit failure on the phone, within 60 seconds. Fail: either open is still on "connecting" after 60 seconds.
+
+PR 1006's `scripts/diagnostics/application/checkHerdrVanishedWatch.mjs` already holds a subscribe at a proxy, according to that PR's record. It checks the host client's tree read, not the phone, so it covers steps 1-3 only.
+
+## Evidence
+
+- A phone screenshot after step 4 and after step 5.
+- The host journal for the run, plus a proxy log showing A's refusal frame and its id.
+- `steps.json` naming the muxr version, the starting state (two agents, A held), the steps above and what Umer sees at the end.
+- Kept separately as supporting evidence: the model report from `node docs/examples/statechart-pilot/check.mjs` in done-done, at the muxr and kit commits that were driven.
+
+On muxr v0.2.9 with `@byokit/herdr` 0.16.1, the model predicts step 4 hangs. With the kit's refusal-id fix, the model predicts both opens answer. Neither prediction has been checked on the real product.

package/docs/reference.md

@@ -238,6 +238,7 @@ journeys:
   - `checks.upstream_catch_up: true`: in a fork, lines the parent repo already shipped are not authored here, so lint subtracts the changes between the PR's base and the merge base with the parent's default branch. A PR that merges in no new upstream commit loses nothing.
   - `checks.moved_from: true`: a line in the PR body `moved-from: <owner>/<repo>@<ref> <dst-prefix>=<src-prefix>` (more `dst=src` pairs may follow) cancels added lines that match, byte for byte after trimming, the file at the same path under `<src-prefix>` in that repo at `<ref>`. The source repo must have the PR's owner; authored lines still count.
   - `checks.generated_paths: ["gen/**", "*.snap"]`: globs for the repo's own generated files, counted as generated beside the built-in ones above, so they stay out of the size count. Default none, so results do not change. Like the two rules above it applies to a PR URL, never a report file.
+  - `.gitattributes` in the target repo: a file it marks `linguist-generated`, `linguist-generated=true` or `-diff` is counted as generated too, with no config. `linguist-generated=false` and an unset attribute are not; the last matching line wins. `lint` reads the file at the PR head (else its base) and, like the rules above, only for a PR URL.
 
 ### Base-ref before
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "done-done-axi",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "license": "Apache-2.0",
   "description": "Proof that the real product works before a task is called done: commit-bound evidence runs and evidence checks.",
   "type": "module",