tickmarkr 2.6.5 → 2.6.7

package/skills/tickmarkr-auto/SKILL.md

@@ -113,16 +113,25 @@ For `resume`, use the same host-owned split form with `tickmarkr resume <runId>`
 in the process table to the host PTY; verify no agent session is an ancestor. If an agent is
 an ancestor, stop that launch and relaunch through the host split before continuing.
 
-Start `tickmarkr beat <tier> --seat <seat> --loop` as a DETACHED background process, one per
-(tier, seat), from the repository root. Use setsid plus nohup (or the host's equivalent detached
-session facility), redirect output to a file, and record a pidfile under the repository's state
-dir. Verify ppid 1 and no agent-session ancestor. Never put beats in a harness background task
-or a visible tab. The lifecycle must be idempotent: start checks the pidfile against the live
-process payload and returns an "already running" no-op for the same (repo, tier, seat); status
-checks that payload and beat freshness; stop sends `--stand-down` for the same tier and seat,
-verifies the loop exits within one interval, then removes its pidfile. A stale or reused pid
-must never be killed without matching its live payload. Include a run-end stop item for every
-beat started, also on failure, park or handoff; verify DISARMED and remove retired beat files.
+Detached beats are product-owned, one per (tier, seat), from the repository root, through the
+shipped lifecycle verbs — never a hand-rolled setsid plus nohup wrapper, pidfile or shell loop:
+
+```bash
+cd <repo> && tickmarkr beat start <tier> --seat <seat>
+cd <repo> && tickmarkr beat status <tier> --seat <seat>
+cd <repo> && tickmarkr beat stop <tier> --seat <seat>
+```
+
+`start` launches the `--loop` child in its own session, logs to `<state-dir>/supervision/<tier>.log`,
+records its pid, birth, argv and cwd, and exits 0 only after it reads back that exact child's own
+advancing beat. A repeat start for the same (tier, seat) is an "already running" no-op; a stale,
+dead, foreign, reused-pid, unreadable or busy tier is a nonzero refusal that changes nothing.
+Verify ppid 1 is never proof on its own — an orphan of a dying session shows it too; `status`
+is the check: it reads the recorded process identity and beat freshness, writes nothing, and exits
+nonzero for STALE, MISMATCH or UNREADABLE. `stop` signals only that recorded pid after its
+generation and identity still match, and reads back DISARMED. Never put beats in a harness
+background task or a visible tab. Include a run-end `beat stop` item for every beat started, also
+on failure, park or handoff, and require its DISARMED read-back.
 
 Keep only watchers that must WAKE the seat in the harness. Re-arm them on each wake and at
 their harness cap; daemon and beat lifetimes must not depend on that cap.

package/skills/tickmarkr-loop/SKILL.md

@@ -108,16 +108,25 @@ For `resume`, use the same host-owned split form with `tickmarkr resume <runId>`
 in the process table to the host PTY; verify no agent session is an ancestor. If an agent is
 an ancestor, stop that launch and relaunch through the host split before continuing.
 
-Start `tickmarkr beat <tier> --seat <seat> --loop` as a DETACHED background process, one per
-(tier, seat), from the repository root. Use setsid plus nohup (or the host's equivalent detached
-session facility), redirect output to a file, and record a pidfile under the repository's state
-dir. Verify ppid 1 and no agent-session ancestor. Never put beats in a harness background task
-or a visible tab. The lifecycle must be idempotent: start checks the pidfile against the live
-process payload and returns an "already running" no-op for the same (repo, tier, seat); status
-checks that payload and beat freshness; stop sends `--stand-down` for the same tier and seat,
-verifies the loop exits within one interval, then removes its pidfile. A stale or reused pid
-must never be killed without matching its live payload. Include a run-end stop item for every
-beat started, also on failure, park or handoff; verify DISARMED and remove retired beat files.
+Detached beats are product-owned, one per (tier, seat), from the repository root, through the
+shipped lifecycle verbs — never a hand-rolled setsid plus nohup wrapper, pidfile or shell loop:
+
+```bash
+cd <repo> && tickmarkr beat start <tier> --seat <seat>
+cd <repo> && tickmarkr beat status <tier> --seat <seat>
+cd <repo> && tickmarkr beat stop <tier> --seat <seat>
+```
+
+`start` launches the `--loop` child in its own session, logs to `<state-dir>/supervision/<tier>.log`,
+records its pid, birth, argv and cwd, and exits 0 only after it reads back that exact child's own
+advancing beat. A repeat start for the same (tier, seat) is an "already running" no-op; a stale,
+dead, foreign, reused-pid, unreadable or busy tier is a nonzero refusal that changes nothing.
+Verify ppid 1 is never proof on its own — an orphan of a dying session shows it too; `status`
+is the check: it reads the recorded process identity and beat freshness, writes nothing, and exits
+nonzero for STALE, MISMATCH or UNREADABLE. `stop` signals only that recorded pid after its
+generation and identity still match, and reads back DISARMED. Never put beats in a harness
+background task or a visible tab. Include a run-end `beat stop` item for every beat started, also
+on failure, park or handoff, and require its DISARMED read-back.
 
 Keep only watchers that must WAKE the seat in the harness. Re-arm them on each wake and at
 their harness cap; daemon and beat lifetimes must not depend on that cap.

package/skills/tickmarkr-overseer/SKILL.md

@@ -326,16 +326,25 @@ For `resume`, use the same host-owned split form with `tickmarkr resume <runId>`
 in the process table to the host PTY; verify no agent session is an ancestor. If an agent is
 an ancestor, stop that launch and relaunch through the host split before continuing.
 
-Start `tickmarkr beat <tier> --seat <seat> --loop` as a DETACHED background process, one per
-(tier, seat), from the repository root. Use setsid plus nohup (or the host's equivalent detached
-session facility), redirect output to a file, and record a pidfile under the repository's state
-dir. Verify ppid 1 and no agent-session ancestor. Never put beats in a harness background task
-or a visible tab. The lifecycle must be idempotent: start checks the pidfile against the live
-process payload and returns an "already running" no-op for the same (repo, tier, seat); status
-checks that payload and beat freshness; stop sends `--stand-down` for the same tier and seat,
-verifies the loop exits within one interval, then removes its pidfile. A stale or reused pid
-must never be killed without matching its live payload. Include a run-end stop item for every
-beat started, also on failure, park or handoff; verify DISARMED and remove retired beat files.
+Detached beats are product-owned, one per (tier, seat), from the repository root, through the
+shipped lifecycle verbs — never a hand-rolled setsid plus nohup wrapper, pidfile or shell loop:
+
+```bash
+cd <repo> && tickmarkr beat start <tier> --seat <seat>
+cd <repo> && tickmarkr beat status <tier> --seat <seat>
+cd <repo> && tickmarkr beat stop <tier> --seat <seat>
+```
+
+`start` launches the `--loop` child in its own session, logs to `<state-dir>/supervision/<tier>.log`,
+records its pid, birth, argv and cwd, and exits 0 only after it reads back that exact child's own
+advancing beat. A repeat start for the same (tier, seat) is an "already running" no-op; a stale,
+dead, foreign, reused-pid, unreadable or busy tier is a nonzero refusal that changes nothing.
+Verify ppid 1 is never proof on its own — an orphan of a dying session shows it too; `status`
+is the check: it reads the recorded process identity and beat freshness, writes nothing, and exits
+nonzero for STALE, MISMATCH or UNREADABLE. `stop` signals only that recorded pid after its
+generation and identity still match, and reads back DISARMED. Never put beats in a harness
+background task or a visible tab. Include a run-end `beat stop` item for every beat started, also
+on failure, park or handoff, and require its DISARMED read-back.
 
 Keep only watchers that must WAKE the seat in the harness. Re-arm them on each wake and at
 their harness cap; daemon and beat lifetimes must not depend on that cap.
@@ -1166,14 +1175,14 @@ watching it. Two thirds of that line were constants, not measurements.
 
 The beat is one shipped command and it arms through two explicit verbs, `--new-arm` and `--loop` —
 never a bare invocation. `--loop` already implies `--new-arm`: it creates a durable arm and beats in
-this process every 10 seconds, exiting on its own within one interval after a stand-down. Run it from
-the repo root as a detached setsid+nohup process with a pidfile, following the idempotent
-start/stop/status lifecycle in Host-owned daemon and detached beats; never as a harness task or visible tab:
+this process every 10 seconds, exiting nonzero with its reason within one interval after a stand-down.
+Never launch it by hand: `beat start` runs it detached and owns it, following the start/stop/status
+lifecycle in Host-owned daemon and detached beats; never as a harness task or visible tab:
 
 ```bash
-# Payload for the detached start above; do not execute as a foreground or harness task.
-cd <repo> && tickmarkr beat overseer --seat <overseer-agent-or-pane> --loop
-cd <repo> && tickmarkr beat overseer --seat <overseer-agent-or-pane> --stand-down  # deliberately hand off; --loop exits
+# beat start owns the detached --loop child; do not execute the loop as a foreground or harness task.
+cd <repo> && tickmarkr beat start overseer --seat <overseer-agent-or-pane>
+cd <repo> && tickmarkr beat stop overseer --seat <overseer-agent-or-pane>  # deliberately hand off; reads back DISARMED
 ```
 
 **The legacy wrapper loop, `while :; do tickmarkr beat overseer --seat <pane>; sleep 10; done`, is the

package/skills/tickmarkr-overseer/scripts/classify-vitest-log.sh

@@ -1,11 +1,38 @@
 #!/bin/bash
-# classify-vitest-log.sh <log> — the ONE strict Vitest log classifier (OBS-1184). The public CI
-# wrapper (scripts/run-ci-vitest.sh) and grade-ci.sh both call it, so the badge and the grade cannot
-# disagree. Reads a raw Vitest log or a gh job log (gh's "job<TAB>step<TAB>timestamp " prefix and ANSI
-# styling — the raw ESC byte and gh's `^[` rendering of it — are stripped) and prints ONE line:
-#   VITEST_LOG verdict=<CLEAN|RPC_ONLY|RED> reason=<why> summaries=S passed=P skipped=K failed=F
-#     timedout=T unhandled=U runner_rpc_timeouts=R coverage_misses=C signals=G terminal_errors=E
-# unhandled counts the unhandled errors that are NOT runner RPC timeouts. Exit 0 CLEAN or RPC_ONLY, 1 RED.
+# classify-vitest-log.sh <log> [expected-files] — the ONE strict Vitest log classifier
+# (OBS-1184). The public CI wrapper (scripts/run-ci-vitest.sh) and grade-ci.sh both call it, so the badge
+# and the grade cannot disagree. Reads a raw Vitest log or a gh job log (gh's "job<TAB>step<TAB>timestamp "
+# prefix and ANSI styling — the raw ESC byte and gh's `^[` rendering of it — are stripped) and prints ONE line:
+#   VITEST_LOG verdict=<CLEAN|RPC_ONLY|RED|INFRA_KILLED> reason=<why> summaries=S passed=P skipped=K failed=F
+#     timedout=T unhandled=U runner_rpc_timeouts=R coverage_misses=C signals=G terminal_errors=E runner_kills=X
+# unhandled counts the unhandled errors that are NOT runner RPC timeouts. Exit 0 CLEAN or RPC_ONLY, 1 RED,
+# 3 INFRA_KILLED.
+#
+# INFRA_KILLED (D-897): the GitHub runner's own shutdown or cancellation annotation ("##[error]The runner
+# has received a shutdown signal…" / "##[error]The operation was canceled.") with no failed or timed-out
+# test and no coverage-threshold miss. It is never green and never passes a gate — the proof was not
+# finished — but it is not a test red either. Those failures dominate a kill (RED); a kill excuses only
+# the cut-off or short log it leaves behind (runner_kills counts the annotations either way). A failure
+# the reporter already printed before the kill cut its summary off counts too: a dot-reporter "x" (its
+# stream has no newline, so a test's "stdout | …"/"stderr | …" header may finish the same line), a
+# default-reporter "×" or failed module record "❯ file (N tests…)" (❯ marks a failed module even with
+# no failed test — a collect or hook error), a " FAIL " badge or the "Failed Tests/Suites N" banner (only
+# beside a kill — without one, the complete summaries' own counts decide). Only one printed after the last
+# complete summary counts: a complete summary's own counts settle every line before it. Test output never
+# counts: a console block runs from its header until the reporter speaks again — a dot run, a ⎯ banner or
+# a default-reporter module record (✓/❯/↓ file (N tests…)) right after a blank line, or the next summary —
+# so blank lines inside a test's output do not end it.
+# ponytail: a test that prints, after a blank line of its own, a line the reporter could have printed is
+# indistinguishable from the reporter; only that deliberate forgery escapes the block.
+#
+# The declared contract (D-893), when a caller supplies one: expected-files is the number of test files
+# the run must collect — the summaries' "(N)" totals must sum to it exactly. The caller derives it from
+# the declared projects' own candidate-tree discovery, so a never-started declared project is a short
+# count: project presence comes from that discovery, never from log text a test can print. A short count
+# is RED reason=partial: a complete summary of the projects that happened to start proves nothing about
+# the one that did not. With or without a contract, a summary whose finished files (failed + passed +
+# skipped + todo) fall short of its own "(N)" is RED reason=partial too: Vitest's total counts the queued
+# and running files an abort left unfinished.
 #
 # RED unless every Vitest summary is complete (Test Files, Tests and Duration lines, and every
 # "Unhandled Errors" block closed by the summary that follows it — a cut-off log is RED), with no
@@ -29,21 +56,28 @@
 set -u
 
 log=${1:?log path required}
-fields='summaries=0 passed=0 skipped=0 failed=0 timedout=0 unhandled=0 runner_rpc_timeouts=0 coverage_misses=0 signals=0 terminal_errors=0'
+fields='summaries=0 passed=0 skipped=0 failed=0 timedout=0 unhandled=0 runner_rpc_timeouts=0 coverage_misses=0 signals=0 terminal_errors=0 runner_kills=0'
 if [ ! -s "$log" ] || [ ! -r "$log" ]; then
   echo "VITEST_LOG verdict=RED reason=unreadable $fields"
   exit 1
 fi
 
 esc=$(printf '\033')
-awk -v esc="$esc" '
+awk -v esc="$esc" -v expected="${2:-}" '
   function num(s, word) { return match(s, "[0-9]+ " word) ? substr(s, RSTART, RLENGTH) + 0 : 0 }
   function close_block() { rpc += (found < cap ? found : cap); armed = 0; pending = 0 }
   {
     line = $0
     gsub(/\^\[\[[0-9;]*m/, "", line); gsub(esc "\\[[0-9;]*m", "", line)
     sub(/^[^\t]*\t[^\t]*\t[0-9T:.-]+Z[ ]?/, "", line)
+    if (line ~ /^[ \t]*(·|x|\*|-)*(stdout|stderr) \| /) {
+      if (line ~ /^[ \t]*(·|\*|-)*x/) reported++
+      console = 1
+    } else if (after_blank && line ~ /^[ \t]*((·|x|\*|-)*(·|x)(·|x|\*|-)*|(⎯)+( .* (⎯)+)?|(✓|❯|↓) .* [(][0-9]+ tests?( [|] [0-9]+ (failed|skipped))*[)].*)[ \t]*$/) console = 0
+    if (!console && line ~ /^[ \t]*((·|\*|-)*x(·|x|\*|-)*|× .*|❯ .* [(][0-9]+ tests?( [|] [0-9]+ (failed|skipped))*[)].*|FAIL[ \t].*|(⎯)+ Failed (Tests|Suites) [0-9]+ (⎯)+)[ \t]*$/) reported++
+    after_blank = line !~ /[^ \t]/
   }
+  line ~ /^##\[error\](The runner has received a shutdown signal|The operation was cancell?ed)/ { kills++ }
   # The Vitest timeout message carries its millisecond count; a test that PRINTS a fingerprint normalized
   # to #ms (the daemon OBS-1106 notifications) is output, not a timed-out test. A real timeout also fails
   # its test, so the summary failed count still reds it.
@@ -59,13 +93,17 @@ awk -v esc="$esc" '
   }
   line ~ /^[ \t]*Test Files[ \t]/ {
     if (armed) close_block()
-    summaries++; in_summary = 1; saw_tests = 0
+    summaries++; in_summary = 1; saw_tests = 0; console = 0
     failed += num(line, "failed"); passed += num(line, "passed"); skipped += num(line, "skipped")
+    finished = num(line, "failed") + num(line, "passed") + num(line, "skipped") + num(line, "todo")
+    total = match(line, /\([0-9]+\)[ \t]*$/) ? substr(line, RSTART + 1) + 0 : -1
+    if (total >= 0) collected += total
+    if (finished != total) unfinished++
     next
   }
   in_summary && line ~ /^[ \t]*Tests[ \t]/ { saw_tests = 1; failed_tests += num(line, "failed"); next }
   in_summary && line ~ /^[ \t]*Errors[ \t]+[0-9]+ error/ { summary_errors += num(line, "error"); next }
-  in_summary && line ~ /^[ \t]*Duration[ \t]/ { if (saw_tests) complete++; in_summary = 0; next }
+  in_summary && line ~ /^[ \t]*Duration[ \t]/ { if (saw_tests) { complete++; reported = 0 }; in_summary = 0; next }
   armed && line ~ /^(⎯)+ Unhandled Error (⎯)+[ \t]*$/ { pending = 1; next }
   line ~ /^(⎯)+ (Unhandled|Startup|Collect) Error (⎯)+[ \t]*$/ { terminal++; next }
   pending && line ~ /[^ \t]/ { pending = 0; if (line ~ /^Error: \[vitest-worker\]: Timeout calling "[A-Za-z]+"[ \t]*$/) found++ }
@@ -73,19 +111,23 @@ awk -v esc="$esc" '
     unhandled = tally + untallied
     if (summary_errors > unhandled) unhandled = summary_errors
     other = unhandled - rpc
-    if (summaries == 0) reason = "no-summary"
+    partial = unfinished || (expected != "" && collected != expected + 0)
+    # a kill always names a class: the failure that dominates it, or the kill itself
+    if (kills) reason = (failed || failed_tests || reported) ? "failed" : timedout ? "timed-out" : coverage ? "coverage-threshold" : "runner-shutdown"
+    else if (summaries == 0) reason = "no-summary"
     else if (complete != summaries || opening || armed) reason = "truncated"
     else if (failed || failed_tests) reason = "failed"
     else if (timedout) reason = "timed-out"
+    else if (partial) reason = "partial"
     else if (coverage) reason = "coverage-threshold"
     else if (signals) reason = "signal"
     else if (terminal) reason = "terminal-error"
     else if (other > 0) reason = "unhandled-error"
     else if (tally + untallied != summary_errors) reason = "unhandled-mismatch"
-    verdict = reason != "" ? "RED" : (unhandled > 0 ? "RPC_ONLY" : "CLEAN")
+    verdict = reason == "runner-shutdown" ? "INFRA_KILLED" : (reason != "" ? "RED" : (unhandled > 0 ? "RPC_ONLY" : "CLEAN"))
     if (reason == "") reason = "none"
-    printf "VITEST_LOG verdict=%s reason=%s summaries=%d passed=%d skipped=%d failed=%d timedout=%d unhandled=%d runner_rpc_timeouts=%d coverage_misses=%d signals=%d terminal_errors=%d\n", \
-      verdict, reason, summaries, passed, skipped, failed, timedout, other, rpc, coverage, signals, terminal
-    exit (verdict == "RED")
+    printf "VITEST_LOG verdict=%s reason=%s summaries=%d passed=%d skipped=%d failed=%d timedout=%d unhandled=%d runner_rpc_timeouts=%d coverage_misses=%d signals=%d terminal_errors=%d runner_kills=%d\n", \
+      verdict, reason, summaries, passed, skipped, failed, timedout, other, rpc, coverage, signals, terminal, kills
+    exit (verdict == "INFRA_KILLED" ? 3 : verdict == "RED")
   }
 ' "$log"

package/skills/tickmarkr-overseer/scripts/grade-ci.sh

@@ -1,7 +1,9 @@
 #!/bin/bash
 # grade-ci.sh <run-id> <expected-count> [tag] — grade both public CI jobs from their JOB LOGS.
 # Grade only at run-end. A missing/in-progress/empty log is UNREADABLE, never evidence of green.
-# Tri-state: exit 0 GREEN, 1 RED, 2 UNREADABLE. UNREADABLE dominates a mixed result.
+# Exit 0 GREEN, 1 RED, 2 UNREADABLE, 3 INFRA_KILLED: a job the GitHub runner shut down or cancelled with
+# no failed or timed-out test (the classifier's class, D-897) — never green, never a pass, only unproven.
+# UNREADABLE dominates a mixed result, then RED: a failure anywhere dominates a kill.
 set -u
 
 run=${1:?run id required}
@@ -14,7 +16,8 @@ mkdir -p "$out_dir" || { echo "UNREADABLE: cannot create log directory $out_dir"
 
 verdict=0
 mark_unreadable() { verdict=2; }
-mark_red() { [ "$verdict" -eq 0 ] && verdict=1; }
+mark_red() { [ "$verdict" -eq 2 ] || verdict=1; }
+mark_killed() { [ "$verdict" -ne 0 ] || verdict=3; }
 field() { printf '%s\n' "$classified" | sed -n "s/^VITEST_LOG.* $1=\([^ ]*\).*/\1/p"; }
 
 jobs=$(gh run view "$run" --repo "$repo" --json jobs \
@@ -52,10 +55,12 @@ while IFS=$'\t' read -r id name status conclusion; do
   # (scripts/run-ci-vitest.sh), so the badge and this grade cannot disagree. Its rules — complete
   # summaries, failed/timed-out tests, coverage-threshold misses, and the RPC-timeout-only exception
   # to "any unhandled error is RED" (OBS-1058) — live in classify-vitest-log.sh, stated once there.
-  classified=$(bash "$here/classify-vitest-log.sh" "$log" 2>&1)
+  # The expected count is the job's declared file contract: both steps' summaries must collect it all.
+  classified=$(bash "$here/classify-vitest-log.sh" "$log" "$expected" 2>&1)
   log_verdict=$(field verdict)
   passed=$(field passed); skipped=$(field skipped); failed=$(field failed); timedout=$(field timedout)
   unhandled=$(field unhandled); rpc=$(field runner_rpc_timeouts); coverage=$(field coverage_misses)
+  kills=$(field runner_kills)
   errors=$(grep -oE '##\[error\].*' "$log" | sort | uniq -c | sed 's/^ *//' | tr '\n' ';')
   # The commands' own outcomes stand, as in the wrapper: GREEN needs a success conclusion with no step
   # exit annotation, or a failure explained ONLY by steps that exited exactly 1 on a log of their own
@@ -81,8 +86,16 @@ while IFS=$'\t' read -r id name status conclusion; do
     done <<< "$exits"
   fi
 
-  echo "$name: oracle=[${oracle:-MISSING}] files=[$(printf '%s' "$files" | tr '\n' '|')] passed=$passed skipped=$skipped failed=$failed timedout=$timedout unhandled=$unhandled runner_rpc_timeouts=$rpc coverage_misses=$coverage log=[$(field reason)] outcome=[$outcome] errors=[$errors]"
-  if [ -z "$oracle" ] || [ -z "$files" ] || [ -z "$log_verdict" ]; then
+  echo "$name: oracle=[${oracle:-MISSING}] files=[$(printf '%s' "$files" | tr '\n' '|')] passed=$passed skipped=$skipped failed=$failed timedout=$timedout unhandled=$unhandled runner_rpc_timeouts=$rpc coverage_misses=$coverage runner_kills=${kills:-?} log=[$(field reason)] outcome=[$outcome] errors=[$errors]"
+  # A killed runner skips the count step, so its missing oracle is the kill's, not an unreadable log:
+  # INFRA_KILLED unless a step's own failing exit or a failed/timed-out test dominates it (then RED).
+  if [ "$log_verdict" = INFRA_KILLED ] && [ "${outcome#exit-}" = "$outcome" ]; then
+    echo "$name: INFRA_KILLED"
+    mark_killed
+  elif [ "${kills:-0}" -gt 0 ] 2>/dev/null; then
+    echo "$name: RED"
+    mark_red
+  elif [ -z "$oracle" ] || [ -z "$files" ] || [ -z "$log_verdict" ]; then
     echo "$name: UNREADABLE"
     mark_unreadable
   elif [ "$oracle" = "COUNT_ORACLE GREEN expected=$expected actual=$expected" ] \
@@ -104,5 +117,5 @@ if [ "$seen_macos" -ne 1 ]; then
   mark_unreadable
 fi
 
-echo "VERDICT rc=$verdict (0=all GREEN 1=RED 2=UNREADABLE)"
+echo "VERDICT rc=$verdict (0=all GREEN 1=RED 2=UNREADABLE 3=INFRA_KILLED)"
 exit "$verdict"

package/skills/tickmarkr-overseer/scripts/watch-parks.sh

@@ -18,79 +18,136 @@
 # a self-criticism — the one sentence nobody audits, including its writer. The gap is real and the watcher
 # is justified by the ABSENCE OF COVERAGE, not by that number. See OBS-435.
 #
-# Prints ONE wake reason and exits. Re-arm after every wake.
+# Prints ONE wake reason, ending with its `CURSOR <run> <line>` receipt, and exits. Re-arm after every
+# wake WITH that receipt: it is the acknowledgment, and only the rows it covers are suppressed.
 #
-# usage: watch-parks.sh <runs-dir> [poll-s] [cap-s]
-#   Tracks the NEWEST run directory, so it follows a resume or a fresh run without being re-aimed.
+# usage: watch-parks.sh <runs-dir> [poll-s] [cap-s] [--since-run <run-id> --since-line <n>]
+#   Tracks the NEWEST run (the latestRunId rule: lexical run-id order, journal present), so it follows a
+#   resume or a fresh run without being re-aimed.
+#
+# ── THE CURSOR (D-829) — what replaced arm-time seeding ────────────────────────────────────────────────
+# Earlier versions seeded on the journal AS ARMED — a park count, then a line baseline. Both read "already
+# in the file when I started" as "already ruled", and the gap between a wake and its re-arm is exactly
+# where that is false: a park appended while the seat was busy ruling the last one was seeded as history
+# and never reported, released or not. The seat's own acknowledgment is the only honest baseline, so the
+# START read happens before any sleep. The closed cursor inputs:
+#   same-run acknowledged  receipt run == newest run: complete rows at lines <= n are suppressed, no others
+#   gap park               a task-human row after n is reported at START
+#   later-release          a gap park released before the re-arm is STILL reported — this answers "which
+#                          parks has the seat not seen", never "which parks are still open"
+#   new-run                newest run != receipt run (or no receipt): the receipt resets to line 0
+#   empty-run              no run has a journal yet: the receipt is `CURSOR none 0`, and re-arming with
+#                          `--since-run none --since-line 0` is the same as no receipt, so the first run
+#                          that appears is read from line 0
+#   torn tail              a final line without its newline is not a row: never reported, never counted, so
+#                          the cursor never advances past it and its completed form is reported later
+# A receipt line beyond its run's complete lines is not this journal's acknowledgment: refused (exit 65),
+# because silently suppressing rows on a mismatched receipt is the failure this file exists to prevent.
+# A journal that cannot be read is not an empty scan: exit 66, no receipt, no WATCH_CAP_REACHED. Nor is a
+# runs dir or run directory that cannot be listed or searched: discovery skips only ABSENCE (no runs dir
+# yet, a run with no journal yet), because falling back to an older run hides the newest run's parks. Any
+# other reader failure, or reader output whose last line is not a receipt, is an error too — never
+# "nothing new".
+#
+# A `run-end` after the cursor wakes too (the milestone verdict is a decision), and a park wake reports a
+# run-end in the same range, so a returned cursor never covers a row the seat was not shown.
 
 set -u
-RUNS="${1:?runs dir required (e.g. .tickmarkr/runs)}"
-POLL="${2:-45}"
-CAP="${3:-28800}"
+POS=() SINCE_RUN="" SINCE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --since-run) SINCE_RUN="${2-}"; shift; [ $# -gt 0 ] && shift ;;
+    --since-line) SINCE="${2-}"; shift; [ $# -gt 0 ] && shift ;;
+    *) POS+=("$1"); shift ;;
+  esac
+done
+RUNS="${POS[0]:?runs dir required (e.g. .tickmarkr/runs)}"
+POLL="${POS[1]:-45}"
+CAP="${POS[2]:-28800}"
+# The receipt is both halves or neither: a line without its run cannot be bound to a journal. Run ids follow
+# parseRunId (src/run/journal.ts): run- then an alphanumeric, then alphanumerics, `_` or `-`.
+if [ -n "$SINCE_RUN$SINCE" ] && ! [[ ( "$SINCE_RUN" =~ ^run-[A-Za-z0-9][A-Za-z0-9_-]*$ && "$SINCE" =~ ^[0-9]+$ ) || ( "$SINCE_RUN" = none && "$SINCE" = 0 ) ]]; then
+  echo "watch-parks.sh: the receipt is --since-run <run-id> --since-line <n> together, got run='$SINCE_RUN' line='$SINCE'" >&2
+  exit 64
+fi
 
-# `grep -c` EXITS 1 WHEN THE COUNT IS ZERO, while still printing `0`. So the idiom
-# `n=$(grep -c PAT f || echo 0)` yields the two-line string "0\n0", and every later `[ "$n" -gt … ]`
-# dies with `integer expression expected` and evaluates FALSE. Found 2026-08-07 by a positive control,
-# not by use: this watcher fired correctly all day because it was always armed on a journal that ALREADY
-# held a park, which is the branch where grep exits 0. **Armed at the start of a run — zero parks — it
-# could never report the first park, which is the one it exists for.** A guard whose failure is silence
-# needs a control; this one had shipped without one.
-count_parks() {
-  local c
-  c=$(grep -c '"event":"task-human"' "$1" 2>/dev/null || true)
-  printf '%s' "${c:-0}"
+# ONE JSON reader for every scan, START and poll alike. It applies the journal reader's rule
+# (src/run/journal.ts parseJournalText: skip blanks, drop an unparseable line, keep each row's PHYSICAL
+# line) to the newline-terminated lines only. argv: runs dir, receipt run, receipt line. Prints the wake, if
+# any, then always `CURSOR <run> <last complete line>` (the receipt unchanged while no run has a journal).
+# Exit 0 = scanned (a wake is any line before the receipt), 65 = refused receipt, 66 = failed read. It sets exitCode rather than calling exit, so a
+# wake larger than the pipe buffer drains before node quits (a 1,500-park wake was cut off mid-list).
+# It reports rows; it never refolds which parks are still open — that is the decision fold's job.
+READER='
+process.exitCode = (() => {
+const fs = require("fs"), { join } = require("path");
+const [runs, sinceRun, sinceLine] = process.argv.slice(1);
+const fail = (what, e) => { console.error(`watch-parks.sh: cannot read ${what}: ${e.code ?? e.message}`); return 66; };
+// Discovery: newest run id first, skipping only a journal that is ABSENT (ENOENT/ENOTDIR). EACCES on an
+// unsearchable run directory, or ELOOP, is a failed read, never a fall-back to an older run.
+let ids = [];
+try { ids = fs.readdirSync(runs).filter((d) => d.startsWith("run-")).sort().reverse(); } catch (e) {
+  if (e.code !== "ENOENT") return fail(runs, e);
 }
-
-newest_journal() {
-  local d
-  d=$(ls -t "$RUNS" 2>/dev/null | grep '^run-' | head -1)
-  [ -n "$d" ] && [ -f "$RUNS/$d/journal.jsonl" ] && printf '%s' "$RUNS/$d/journal.jsonl"
+let run, file;
+for (const id of ids) {
+  const f = join(runs, id, "journal.jsonl");
+  try { fs.statSync(f); } catch (e) {
+    if (e.code === "ENOENT" || e.code === "ENOTDIR") continue;
+    return fail(f, e);
+  }
+  [run, file] = [id, f];
+  break;
 }
+if (!run) { console.log(`CURSOR ${sinceRun || "none"} ${sinceLine || 0}`); return 0; }
+const since = run === sinceRun ? Number(sinceLine) : 0;
+let text;
+try { text = fs.readFileSync(file, "utf8"); } catch (e) { return fail(file, e); }
+const lines = text.split("\n");
+const complete = lines.length - 1; // the last element is "" or a torn tail: never a complete line
+if (since > complete) {
+  console.error(`watch-parks.sh: receipt ${run} line ${since} is beyond its ${complete} complete lines — not an acknowledgment of this journal`);
+  return 65;
+}
+const parks = [], ends = [];
+for (let n = since + 1; n <= complete; n++) {
+  let row;
+  try { row = JSON.parse(lines[n - 1]); } catch { continue; }
+  if (row?.event === "task-human") parks.push([n, row]);
+  else if (row?.event === "run-end") ends.push([n, row]);
+}
+const out = [];
+if (parks.length) {
+  out.push(`PARK ${parks.length} new — ${run}`);
+  for (const [n, row] of parks) out.push(`  ${row.taskId}: ${String(row.data?.reason ?? "").replace(/\s+/g, " ").slice(0, 160)}`, `    park ${n}@${row.ts}`);
+  out.push("  a park waits for a RULING and nothing else releases it — read the gate evidence, then rule");
+}
+if (ends.length) {
+  out.push(`RUN_END ${run} tipVerify=${ends.at(-1)[1].data?.tipVerify ?? "unknown"}`);
+  out.push("  read tipVerify as a FIELD; a failing verify is a DIFFERENT event with no pass field");
+}
+out.push(`CURSOR ${run} ${complete}`);
+console.log(out.join("\n"));
+return 0;
+})();
+'
 
-# Seed on the CURRENT park count so we wake on the next one, not on history already ruled.
-J=$(newest_journal)
-seen=0
-[ -n "${J:-}" ] && seen=$(count_parks "$J")
-seen_run="${J:-}"
-
-# ...and seed a LINE POSITION, because the park counter is not enough (evidence rule 30).
-# `run-end` is a HISTORICAL RECORD once written. A whole-file grep for it finds the PREVIOUS run-end
-# on every resume, and on any re-arm after a run has ended — so the watcher exits in its first poll,
-# a supervisor re-execs it into the same instant exit, and the process table shows coverage that does
-# not exist. Measured 2026-08-07: re-arming this watcher after run 264's run-end would have done
-# exactly that. Only lines appended AFTER arming are evidence about now.
-base=0
-[ -n "${J:-}" ] && base=$(wc -l < "$J" 2>/dev/null || echo 0)
-since_arm() { tail -n +$((base + 1)) "$1" 2>/dev/null; }
+# Sets `last` to the scan, which always ends in its receipt, and returns 0; any nonzero is a failed read.
+CURSOR_RE='^CURSOR (run-[A-Za-z0-9][A-Za-z0-9_-]* [0-9]+|none 0)$'
+scan() {
+  last=$(node -e "$READER" "$RUNS" "$SINCE_RUN" "$SINCE") || return
+  [[ "${last##*$'\n'}" =~ $CURSOR_RE ]] || { echo "watch-parks.sh: reader output ended without a receipt" >&2; return 70; }
+}
 
-elapsed=0
-while [ "$elapsed" -lt "$CAP" ]; do
+elapsed=0 last=""
+while :; do
+  scan || { rc=$?; echo "WATCH_ERROR — journal scan failed (status $rc); no receipt, no coverage until re-armed" >&2; exit "$rc"; }
+  # Only a wake prints lines before its receipt.
+  [[ "$last" == *$'\n'* ]] && { printf '%s\n' "$last"; exit 0; }
+  [ "$elapsed" -ge "$CAP" ] && break
   sleep "$POLL"
   elapsed=$((elapsed + POLL))
-
-  J=$(newest_journal)
-  [ -z "${J:-}" ] && continue
-
-  # A new run resets the baseline — its parks AND its whole journal are unseen by definition.
-  if [ "$J" != "$seen_run" ]; then seen=0; seen_run="$J"; base=0; fi
-
-  now=$(count_parks "$J")
-  if [ "$now" -gt "$seen" ]; then
-    echo "PARK $((now - seen)) new — $(basename "$(dirname "$J")")"
-    grep '"event":"task-human"' "$J" 2>/dev/null | tail -n "$((now - seen))" \
-      | sed -n 's/.*"taskId":"\([^"]*\)".*"reason":"\([^"]\{0,160\}\).*/  \1: \2/p'
-    echo "  a park waits for a RULING and nothing else releases it — read the gate evidence, then rule"
-    exit 0
-  fi
-
-  # A run that ended is also this seat's business: the milestone verdict is a decision.
-  # Scoped to lines appended since arming — see the `base` comment above.
-  if since_arm "$J" | grep -q '"event":"run-end"'; then
-    tv=$(since_arm "$J" | grep '"event":"run-end"' | tail -1 | sed -n 's/.*"tipVerify":"\([a-z]*\)".*/\1/p')
-    echo "RUN_END $(basename "$(dirname "$J")") tipVerify=${tv:-unknown}"
-    echo "  read tipVerify as a FIELD; a failing verify is a DIFFERENT event with no pass field"
-    exit 0
-  fi
 done
 
-echo "WATCH_CAP_REACHED — no new park or run-end in ${CAP}s (newest: $(basename "$(dirname "${J:-none/none}")"))"
+echo "WATCH_CAP_REACHED — no new park or run-end in ${CAP}s"
+printf '%s\n' "$last"