@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/tests/fm-wake-daemon-lifecycle-e2e.test.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# tests/fm-wake-daemon-lifecycle-e2e.test.sh - the watcher + supervise-daemon
+# lifecycle, end to end, over one shared state root and a shimmed tmux:
+#
+#   routine status -> self-handled, queued
+#   terminal status written while the watcher is DOWN -> caught on restart (catch-up)
+#   drain queued records -> exactly ONE captain-relevant digest is buffered
+#   housekeeping catch-all scan -> NO duplicate digest
+#   buffered digest flushes to the supervisor pane as exactly ONE submission
+#   stale working-pane: transient (self + marker) -> persistent (escalates once,
+#     clears its marker) -> resumed/busy (clears without escalating)
+#
+# This proves the operator-visible routing/queueing/dedupe behavior through real
+# fm-watch.sh runs plus the daemon's own functions. The captain-relevant
+# status-phrase matrix and the lock-primitive races stay as focused units
+# (fm-daemon.test.sh, fm-watcher-lock.test.sh) - an e2e cannot deterministically
+# cover a race, and the phrase list is a product contract worth a dedicated test.
+set -u
+
+# shellcheck source=tests/wake-helpers.sh
+. "$(dirname "${BASH_SOURCE[0]}")/wake-helpers.sh"
+
+WATCH="$ROOT/bin/fm-watch.sh"
+DRAIN="$ROOT/bin/fm-wake-drain.sh"
+DAEMON="$ROOT/bin/fm-supervise-daemon.sh"
+
+# Source the daemon's pure functions (its main loop is guarded out under sourcing).
+if [ -z "${FM_TEST_DAEMON_SOURCED:-}" ]; then
+  export FM_TEST_DAEMON_SOURCED=1
+  # shellcheck source=/dev/null
+  . "$DAEMON"
+fi
+
+TMP_ROOT=$(fm_test_tmproot fm-wake-daemon-e2e)
+
+# Run the daemon-managed watcher once: under the supervise-daemon (away mode) the
+# watcher is one-shot - it exits with a single reason line on EVERY wake and the
+# daemon does the triage. This e2e exercises exactly that path, so it runs with
+# state/.afk present (which the daemon owns) to keep the watcher one-shot; the
+# always-on standalone triage is covered by fm-watch-triage.test.sh. fakebin
+# shadows tmux. Echoes nothing; the caller reads $out.
+run_watcher_once() {
+  local state=$1 fakebin=$2 out=$3
+  mkdir -p "$state"
+  date '+%s' > "$state/.afk"
+  PATH="$fakebin:$PATH" FM_STATE_OVERRIDE="$state" FM_POLL=1 FM_SIGNAL_GRACE=1 \
+    FM_CHECK_INTERVAL=999999 FM_HEARTBEAT=999999 "$WATCH" > "$out" &
+  wait_for_exit "$!" 50
+}
+
+ack_handled_wakes() {  # <state> <drain-stderr>
+  local state=$1 drain_err=$2 sequence generation
+  sequence=$(sed -n 's/^WAKE_ACK_REQUIRED:.*--ack-through \([0-9][0-9]*\) --recovery-generation [A-Za-z0-9._-][A-Za-z0-9._-]*$/\1/p' "$drain_err")
+  generation=$(sed -n 's/^WAKE_ACK_REQUIRED:.*--ack-through [0-9][0-9]* --recovery-generation \([A-Za-z0-9._-][A-Za-z0-9._-]*\)$/\1/p' "$drain_err")
+  [ -n "$sequence" ] && [ -n "$generation" ] || return 1
+  FM_STATE_OVERRIDE="$state" "$DRAIN" --ack-through "$sequence" \
+    --recovery-generation "$generation"
+}
+
+# --- Phase 1: routine self-handled, queued; terminal caught after restart ---
+test_routine_then_terminal_after_restart() {
+  local dir state fakebin out drain_out drain_err status_file
+  dir=$(make_supercase wd-lifecycle)
+  state="$dir/state"
+  fakebin="$dir/fakebin"
+  out="$dir/watch.out"
+  drain_out="$dir/drain.out"
+  drain_err="$dir/drain.err"
+  status_file="$state/task-w1.status"
+
+  # A routine status fires a signal; the watcher queues it and exits.
+  printf 'working: building\n' > "$status_file"
+  run_watcher_once "$state" "$fakebin" "$out" || fail "watcher did not exit for the routine signal"
+  grep -F "signal: $status_file" "$out" >/dev/null || fail "watcher did not report the routine signal"
+
+  # Drain it and route through the daemon: a routine status self-handles.
+  FM_STATE_OVERRIDE="$state" "$DRAIN" > "$drain_out" 2> "$drain_err" \
+    || fail "drain after routine signal failed"
+  grep "$(printf '\tsignal\t')" "$drain_out" | grep -F "$status_file" >/dev/null \
+    || fail "routine signal was not queued"
+  FM_STATE_OVERRIDE="$state" handle_wake "signal: $status_file" "$state"
+  ack_handled_wakes "$state" "$drain_err" || fail "routine wake acknowledgement failed"
+  [ ! -s "$state/.subsuper-escalations" ] || fail "routine status was escalated by the daemon"
+
+  # The watcher is now DOWN (one-shot exit). A terminal status lands while it is
+  # down; the next watcher run must catch it up (losslessness across restart).
+  printf 'done: PR https://example.test/pr/900\n' >> "$status_file"
+  : > "$out"
+  run_watcher_once "$state" "$fakebin" "$out" || fail "restarted watcher did not exit for the terminal signal"
+  grep -F "signal: $status_file" "$out" >/dev/null || fail "terminal signal written while watcher down was not caught on restart"
+
+  # Drain and route the terminal: exactly ONE digest is buffered.
+  : > "$drain_out"
+  FM_STATE_OVERRIDE="$state" "$DRAIN" > "$drain_out" 2> "$drain_err" \
+    || fail "drain after terminal signal failed"
+  FM_STATE_OVERRIDE="$state" handle_wake "signal: $status_file" "$state"
+  ack_handled_wakes "$state" "$drain_err" || fail "terminal wake acknowledgement failed"
+  [ -s "$state/.subsuper-escalations" ] || fail "captain-relevant terminal status was not buffered"
+  [ "$(wc -l < "$state/.subsuper-escalations" | tr -d ' ')" -eq 1 ] \
+    || fail "expected exactly one buffered digest after the terminal signal"
+
+  # The catch-all heartbeat scan must NOT re-escalate the same status (no dup).
+  FM_STATE_OVERRIDE="$state" housekeeping "$state"
+  [ "$(wc -l < "$state/.subsuper-escalations" | tr -d ' ')" -eq 1 ] \
+    || fail "catch-all scan duplicated the already-buffered digest"
+
+  # With afk active, the buffered digest flushes to the supervisor pane as ONE
+  # submission (one typed line + one Enter), then the buffer clears.
+  local sent
+  sent="$dir/sent.log"; : > "$sent"
+  printf '❯\n' > "$dir/pane.txt"
+  afk_enter "$state"
+  PATH="$fakebin:$PATH" FM_FAKE_TMUX_PANE_ALIVE=1 FM_FAKE_TMUX_SENT="$sent" \
+    FM_FAKE_TMUX_CAPTURE="$dir/pane.txt" FM_ESCALATE_BATCH_SECS=0 escalate_flush "$state" \
+    || fail "escalate_flush failed for the buffered digest"
+  [ "$(grep -c '\[ENTER\]' "$sent")" -eq 1 ] || fail "buffered digest was not submitted exactly once"
+  [ ! -s "$state/.subsuper-escalations" ] || fail "buffer not cleared after a successful flush"
+  pass "lifecycle: routine self-handles, terminal survives a watcher restart, buffers once, no dup, injects once"
+}
+
+# --- Phase 2: stale working-pane transient -> persistent -> resumed ----------
+test_stale_pane_transient_persistent_resume() {
+  local dir state fakebin win key resumed_gen
+  dir=$(make_supercase wd-stale)
+  state="$dir/state"
+  fakebin="$dir/fakebin"
+  win="sess:fm-stale-w2"
+  key=$(printf '%s' "stale-w2" | tr ':/.' '___')
+  printf 'working: compiling\n' > "$state/stale-w2.status"
+
+  # Transient: first stale observation self-handles and records a marker.
+  stale_marker_record "$win" "$state"
+  case "$(FM_STATE_OVERRIDE="$state" classify_stale "$win" "$state")" in
+    self\|*) : ;;
+    *) fail "transient stale did not self-handle" ;;
+  esac
+  [ -e "$state/.subsuper-stale-$key" ] || fail "transient stale did not record a persistence marker"
+
+  # Persistent: the marker ages past the threshold and the pane is still idle, so
+  # housekeeping escalates exactly once and clears the marker.
+  printf 'idle prompt $\n' > "$dir/pane.txt"
+  echo $(( $(date +%s) - 500 )) > "$state/.subsuper-stale-$key"
+  : > "$state/.subsuper-escalations" 2>/dev/null || true
+  PATH="$fakebin:$PATH" FM_FAKE_TMUX_WINDOW="$win" FM_FAKE_TMUX_CAPTURE="$dir/pane.txt" \
+    FM_STATE_OVERRIDE="$state" FM_STALE_ESCALATE_SECS=240 housekeeping "$state" \
+    2>"$dir/housekeeping.err"
+  [ ! -s "$dir/housekeeping.err" ] \
+    || fail "missing task metadata leaked a raw read error: $(cat "$dir/housekeeping.err")"
+  [ -s "$state/.subsuper-escalations" ] || fail "persistent stale did not escalate"
+  [ ! -e "$state/.subsuper-stale-$key" ] || fail "stale marker not cleared after escalation"
+
+  # Resumed: a fresh transient marker but the crew is provably working again ->
+  # housekeeping clears the marker without escalating. The proof is the crew's
+  # own semantic busy-state record (bin/fm-busy-lib.sh), not rendered pane text.
+  stale_marker_record "$win" "$state"
+  echo $(( $(date +%s) - 500 )) > "$state/.subsuper-stale-$key"
+  printf 'Working...\n' > "$dir/pane.txt"
+  fm_write_meta "$state/stale-w2.meta" "window=$win" "worktree=$dir/wt" "kind=ship" "harness=pi"
+  resumed_gen=$("$ROOT/bin/fm-busy-event.sh" arm "$state" stale-w2)
+  "$ROOT/bin/fm-busy-event.sh" apply "$state" stale-w2 busy --gen "$resumed_gen" \
+    --source pi-ext --event agent-start
+  : > "$state/.subsuper-escalations"
+  PATH="$fakebin:$PATH" FM_FAKE_TMUX_WINDOW="$win" FM_FAKE_TMUX_CAPTURE="$dir/pane.txt" \
+    FM_STATE_OVERRIDE="$state" FM_STALE_ESCALATE_SECS=240 housekeeping "$state"
+  [ ! -e "$state/.subsuper-stale-$key" ] || fail "resumed stale marker was not cleared"
+  [ ! -s "$state/.subsuper-escalations" ] || fail "resumed (busy) stale was escalated"
+  pass "lifecycle: stale pane transient self-handles, persistent escalates once and clears, resumed clears quietly"
+}
+
+test_routine_then_terminal_after_restart
+test_stale_pane_transient_persistent_resume

package/.agents/tests/fm-wake-drain-open-decisions-cursor.test.sh

@@ -0,0 +1,356 @@
+#!/usr/bin/env bash
+# tests/fm-wake-drain-open-decisions-cursor.test.sh - end-to-end behavior tests
+# for the incremental, cursor-backed OPEN DECISIONS scan
+# (fm-classify-lib.sh's status_open_decisions_incremental /
+# scan_open_decisions_incremental, wired into bin/fm-wake-drain.sh). These drive
+# the REAL drain script across MANY successive invocations over a status log
+# that keeps growing, and assert both the printed output and a bounded-cost
+# property, not the fold's own source text. tests/fm-wake-drain-open-decisions.test.sh
+# already covers the fold's single-drain correctness; this file covers the
+# cursor's cross-drain persistence and cost bound.
+set -u
+
+# shellcheck source=tests/wake-helpers.sh
+. "$(dirname "${BASH_SOURCE[0]}")/wake-helpers.sh"
+
+DRAIN="$ROOT/bin/fm-wake-drain.sh"
+
+TMP_ROOT=$(fm_test_tmproot fm-wake-drain-open-decisions-cursor-tests)
+
+# Append <count> harmless filler lines (routine working: notes, never a
+# needs-decision/blocked/resolved verb) to <file> and print the exact number of
+# bytes appended, so a test can assert the read-probe's byte count against a
+# known ground truth rather than an approximation.
+append_filler() {  # <file> <count>
+  local file=$1 count=$2 i=0 before after
+  before=$(LC_ALL=C wc -c < "$file" 2>/dev/null | tr -d '[:space:]')
+  [ -n "$before" ] || before=0
+  while [ "$i" -lt "$count" ]; do
+    printf 'working: routine filler padding line %04d of growing status log\n' "$i" >> "$file"
+    i=$((i + 1))
+  done
+  after=$(LC_ALL=C wc -c < "$file" 2>/dev/null | tr -d '[:space:]')
+  printf '%s\n' "$((after - before))"
+}
+
+# The byte count the read-probe recorded for <file> on its MOST RECENT
+# incremental fold call (last matching line in the probe log).
+last_probe_bytes() {  # <probe-file> <status-file>
+  grep -F "$(printf '%s\t' "$2")" "$1" 2>/dev/null | tail -1 | cut -f2
+}
+
+test_buried_decision_survives_many_growing_drains_and_resolution_clears_it() {
+  local dir state out probe status bootstrap_bytes total_size round increment_bytes probe_bytes
+  dir=$(make_case cursor-lifecycle)
+  state="$dir/state"
+  out="$dir/drain.out"
+  probe="$dir/probe.tsv"
+  status="$state/task1.status"
+  : > "$probe"
+
+  # Open a keyed decision, buried under an initial filler round big enough to
+  # make a full-file rescan cost visibly more than a small incremental one.
+  printf 'needs-decision [key=api-shape]: pick REST or RPC\n' > "$status"
+  append_filler "$status" 400 >/dev/null
+
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "first drain over a large buried decision failed"
+  grep -F 'task1' "$out" | grep -F '[key=api-shape]' | grep -F 'pick REST or RPC' >/dev/null \
+    || fail "the buried decision did not surface on the bootstrap drain"
+  bootstrap_bytes=$(last_probe_bytes "$probe" "$status")
+  [ -n "$bootstrap_bytes" ] && [ "$bootstrap_bytes" -gt 0 ] \
+    || fail "the bootstrap drain recorded no incremental read at all"
+
+  # Many further drains, each appending only a SMALL increment while the total
+  # log keeps growing large. The buried decision must resurface on EVERY one of
+  # them (never dropped just because it is old or buried under more appends),
+  # and each drain's read-probe byte count must match ONLY that round's small
+  # increment - never the ever-growing total file size - proving the read cost
+  # is bounded by new appends, not by total log size.
+  for round in 1 2 3 4 5; do
+    increment_bytes=$(append_filler "$status" 20)
+    FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+      || fail "drain $round over a growing log failed"
+    grep -F 'task1' "$out" | grep -F '[key=api-shape]' | grep -F 'pick REST or RPC' >/dev/null \
+      || fail "the buried decision was dropped on growth round $round"
+    probe_bytes=$(last_probe_bytes "$probe" "$status")
+    [ "$probe_bytes" = "$increment_bytes" ] \
+      || fail "round $round read $probe_bytes bytes, expected exactly this round's $increment_bytes-byte increment (cost is not bounded)"
+  done
+  total_size=$(LC_ALL=C wc -c < "$status" | tr -d '[:space:]')
+  [ "$total_size" -gt "$bootstrap_bytes" ] \
+    || fail "test setup error: the log never grew past its bootstrap size"
+
+  # Now resolve it. The very next drain's own read (a small increment) must
+  # clear it - not by rescanning the whole now-large file, but by folding the
+  # small resolved line into the still-persisted open set.
+  increment_bytes=$(printf 'resolved [key=api-shape]: went with REST\n' | tee -a "$status" | LC_ALL=C wc -c | tr -d '[:space:]')
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "resolution drain failed"
+  if grep -F 'OPEN DECISIONS' "$out" >/dev/null; then
+    fail "the resolved decision still printed as open right after resolution: $(cat "$out")"
+  fi
+  probe_bytes=$(last_probe_bytes "$probe" "$status")
+  [ "$probe_bytes" = "$increment_bytes" ] \
+    || fail "the resolution drain read $probe_bytes bytes, expected exactly the $increment_bytes-byte resolved line (cost is not bounded)"
+
+  # Grow the log again after resolution: the decision must stay cleared (a
+  # closed decision is not resurrected by unrelated later growth), and the read
+  # cost for this final round must still be bounded to that round's increment.
+  increment_bytes=$(append_filler "$status" 20)
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "post-resolution growth drain failed"
+  if grep -F 'OPEN DECISIONS' "$out" >/dev/null; then
+    fail "a resolved decision reappeared after later unrelated growth: $(cat "$out")"
+  fi
+  probe_bytes=$(last_probe_bytes "$probe" "$status")
+  [ "$probe_bytes" = "$increment_bytes" ] \
+    || fail "the post-resolution drain read $probe_bytes bytes, expected exactly the $increment_bytes-byte increment (cost is not bounded)"
+
+  pass "a buried decision survives many growing drains with bounded read cost, and resolution durably clears it at bounded cost too"
+}
+
+test_truncated_log_falls_back_to_a_full_refold_not_a_dropped_decision() {
+  local dir state out probe status rewritten_bytes probe_bytes
+  dir=$(make_case cursor-truncation)
+  state="$dir/state"
+  out="$dir/drain.out"
+  probe="$dir/probe.tsv"
+  status="$state/task2.status"
+  : > "$probe"
+
+  printf 'needs-decision [key=migration]: pick the rollout plan\n' > "$status"
+  append_filler "$status" 100 >/dev/null
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "initial drain before truncation failed"
+  grep -F 'task2' "$out" | grep -F '[key=migration]' >/dev/null \
+    || fail "the decision did not surface before truncation"
+
+  # Simulate a rewritten/truncated log (shrunk below the persisted cursor
+  # offset): the decision is re-opened by a fresh needs-decision line in the
+  # rewritten content, and the incremental scan must fall back to a full
+  # re-fold of the new, smaller file rather than trusting a now-invalid cursor.
+  printf 'needs-decision [key=migration]: rewritten after truncation\n' > "$status"
+  rewritten_bytes=$(LC_ALL=C wc -c < "$status" | tr -d '[:space:]')
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "post-truncation drain failed"
+  grep -F 'task2' "$out" | grep -F '[key=migration]' | grep -F 'rewritten after truncation' >/dev/null \
+    || fail "the rewritten decision after truncation did not surface"
+  probe_bytes=$(last_probe_bytes "$probe" "$status")
+  [ "$probe_bytes" = "$rewritten_bytes" ] \
+    || fail "post-truncation drain read $probe_bytes bytes, expected a full re-fold of the $rewritten_bytes-byte rewritten file"
+
+  pass "a truncated/rewritten log falls back to a full re-fold instead of dropping or misreading the decision"
+}
+
+test_same_size_rewrite_is_detected_via_inode_identity() {
+  local dir state out probe status new_bytes probe_bytes
+  dir=$(make_case cursor-rotation)
+  state="$dir/state"
+  out="$dir/drain.out"
+  probe="$dir/probe.tsv"
+  status="$state/task3.status"
+  : > "$probe"
+
+  printf 'needs-decision [key=migration]: pick the rollout plan\n' > "$status"
+  append_filler "$status" 100 >/dev/null
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "initial drain before rotation failed"
+  grep -F 'task3' "$out" | grep -F '[key=migration]' >/dev/null \
+    || fail "the decision did not surface before rotation"
+
+  # Replace the file at the same path with a DIFFERENT file of the SAME byte
+  # size (mv gives the destination path a new inode) - a same-size rewrite,
+  # which a plain offset>size shrink check alone would NOT catch. The buried
+  # decision must still surface: the device+inode identity check must detect
+  # this as a rotation/recreation and fall back to a full re-fold.
+  new_bytes=$(LC_ALL=C wc -c < "$status" | tr -d '[:space:]')
+  printf 'needs-decision [key=migration]: rewritten via rotation\n' > "$dir/replacement"
+  padded=$(LC_ALL=C wc -c < "$dir/replacement" | tr -d '[:space:]')
+  pad=$((new_bytes - padded))
+  [ "$pad" -gt 0 ] && head -c "$pad" /dev/zero | tr '\0' 'x' >> "$dir/replacement"
+  mv "$dir/replacement" "$status"
+  [ "$(LC_ALL=C wc -c < "$status" | tr -d '[:space:]')" = "$new_bytes" ] \
+    || fail "test setup error: the rotated replacement is not the same size as the original"
+
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "post-rotation drain failed"
+  grep -F 'task3' "$out" | grep -F '[key=migration]' | grep -F 'rewritten via rotation' >/dev/null \
+    || fail "the same-size rotated file's decision did not surface (inode-identity check did not fire)"
+  probe_bytes=$(last_probe_bytes "$probe" "$status")
+  [ "$probe_bytes" = "$new_bytes" ] \
+    || fail "post-rotation drain read $probe_bytes bytes, expected a full re-fold of the $new_bytes-byte replacement"
+
+  pass "a same-size file rotation (new inode) is detected and falls back to a full re-fold"
+}
+
+test_read_failure_preserves_state_for_retry() {
+  local dir state reader statusfile cursor out before_cursor after_cursor
+  dir=$(make_case cursor-read-failure)
+  state="$dir/state"
+  reader="$dir/fail-reader"
+  statusfile="$state/task4.status"
+  cursor="$state/.task4.open-decisions-cursor"
+  out="$dir/drain.out"
+
+  printf 'needs-decision [key=x]: something important\n' > "$statusfile"
+  FM_STATE_OVERRIDE="$state" "$DRAIN" > "$out" \
+    || fail "bootstrap drain before the injected read failure failed"
+  grep -F 'task4' "$out" | grep -F '[key=x]' | grep -F 'something important' >/dev/null \
+    || fail "the decision did not surface on the bootstrap drain"
+  [ -s "$cursor" ] || fail "no cursor was persisted after the bootstrap drain"
+  before_cursor=$(LC_ALL=C cksum "$cursor")
+
+  printf 'working: more routine content\n' >> "$statusfile"
+  printf '#!/usr/bin/env bash\nexit 1\n' > "$reader"
+  chmod +x "$reader"
+
+  FM_STATE_OVERRIDE="$state" FM_STATUS_SPAN_READER="$reader" "$DRAIN" > "$out" \
+    || fail "wake drain failed instead of preserving state after the injected read failure"
+  [ ! -s "$out" ] \
+    || fail "the failed presentation read emitted a partial status presentation: $(command cat "$out")"
+  after_cursor=$(LC_ALL=C cksum "$cursor")
+  [ "$after_cursor" = "$before_cursor" ] \
+    || fail "the failed read advanced or rewrote the persisted cursor"
+
+  FM_STATE_OVERRIDE="$state" "$DRAIN" > "$out" \
+    || fail "wake drain did not recover after the injected read failure"
+  grep -F 'task4' "$out" | grep -F '[key=x]' | grep -F 'something important' >/dev/null \
+    || fail "the open decision disappeared when presentation reads recovered: $(command cat "$out")"
+
+  pass "a failed presentation read preserves status state for retry"
+}
+
+test_cursor_cache_read_failure_refolds_without_replaying_unread_status() {
+  local dir state fakebin statusfile cursor out probe real_cat status_bytes probe_bytes
+  dir=$(make_case cursor-cache-read-failure)
+  state="$dir/state"
+  fakebin="$dir/failbin"
+  mkdir -p "$fakebin"
+  statusfile="$state/task5.status"
+  cursor="$state/.task5.open-decisions-cursor"
+  out="$dir/drain.out"
+  probe="$dir/probe.tsv"
+  real_cat=$(command -v cat)
+
+  {
+    printf 'needs-decision [key=cache]: recover from authoritative status\n'
+    printf 'note: already handled informational status\n'
+  } > "$statusfile"
+  append_filler "$statusfile" 40 >/dev/null
+  FM_STATE_OVERRIDE="$state" "$DRAIN" > "$out" \
+    || fail "bootstrap drain before the cursor-cache read failure failed"
+  grep -F 'task5' "$out" | grep -F '[key=cache]' | grep -F 'authoritative status' >/dev/null \
+    || fail "the decision did not surface before the cursor-cache read failure"
+  grep -F 'task5 note: already handled informational status' "$out" >/dev/null \
+    || fail "the bootstrap drain did not surface the informational status"
+  [ -s "$cursor" ] || fail "no cursor was persisted before the cursor-cache read failure"
+
+  printf 'working: appended before cache failure\n' >> "$statusfile"
+  status_bytes=$(LC_ALL=C wc -c < "$statusfile" | tr -d '[:space:]')
+  : > "$probe"
+  cat > "$fakebin/cat" <<SH
+#!/usr/bin/env bash
+if [ "\$#" -eq 1 ] && [ "\$1" = "$cursor" ]; then
+  exit 1
+fi
+exec "$real_cat" "\$@"
+SH
+  chmod +x "$fakebin/cat"
+
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" PATH="$fakebin:$PATH" "$DRAIN" > "$out" \
+    || fail "wake drain failed instead of refolding after the cursor-cache read failure"
+  grep -F 'task5' "$out" | grep -F '[key=cache]' | grep -F 'authoritative status' >/dev/null \
+    || fail "the cursor-cache read failure hid the recurring open decision: $(command cat "$out")"
+  if grep -F 'UNREAD STATUS' "$out" >/dev/null \
+    || grep -F 'already handled informational status' "$out" >/dev/null; then
+    fail "the cursor-cache read failure replayed handled informational status as new: $(command cat "$out")"
+  fi
+  probe_bytes=$(last_probe_bytes "$probe" "$statusfile")
+  [ "$probe_bytes" = "$status_bytes" ] \
+    || fail "the cursor-cache read failure read $probe_bytes bytes, expected a full $status_bytes-byte authoritative refold"
+
+  pass "a cursor-cache read failure refolds decisions without replaying handled unread status"
+}
+
+test_pre_fix_cursor_refolds_corr_tagged_decision() {
+  local dir state status cursor out probe status_bytes ident probe_bytes
+  dir=$(make_case cursor-corr-tag-migration)
+  state="$dir/state"
+  status="$state/task7.status"
+  cursor="$state/.task7.open-decisions-cursor"
+  out="$dir/drain.out"
+  probe="$dir/probe.tsv"
+
+  printf 'needs-decision [corr=d448ea86afa4bf67] [key=loan-installment-cadence-amount]: pick the cadence\n' > "$status"
+  FM_STATE_OVERRIDE="$state" "$DRAIN" > "$out" \
+    || fail "bootstrap drain for the corr-tag cursor migration failed"
+  ident=$(sed -n 's/^ident=//p' "$cursor")
+  [ -n "$ident" ] || fail "bootstrap drain did not persist a file identity"
+  status_bytes=$(LC_ALL=C wc -c < "$status" | tr -d '[:space:]')
+  {
+    printf 'version=3\n'
+    printf 'offset=%s\n' "$status_bytes"
+    printf 'ident=%s\n' "$ident"
+  } > "$cursor"
+  : > "$probe"
+
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "drain failed while migrating the pre-fix corr-tag cursor"
+  grep -F 'task7 [key=loan-installment-cadence-amount] needs-decision: pick the cadence' "$out" >/dev/null \
+    || fail "the pre-fix cursor hid the corr-tagged decision after migration: $(cat "$out")"
+  probe_bytes=$(last_probe_bytes "$probe" "$status")
+  [ "$probe_bytes" = "$status_bytes" ] \
+    || fail "the pre-fix cursor read $probe_bytes bytes instead of refolding all $status_bytes authoritative bytes"
+
+  pass "a pre-fix cursor is rebuilt so a previously skipped corr-tagged decision surfaces"
+}
+
+test_previous_fold_cache_is_refolded_under_current_semantics() {
+  local dir state status cursor out probe status_bytes ident appended_bytes probe_bytes
+  dir=$(make_case cursor-fold-version)
+  state="$dir/state"
+  status="$state/task6.status"
+  cursor="$state/.task6.open-decisions-cursor"
+  out="$dir/drain.out"
+  probe="$dir/probe.tsv"
+
+  printf 'blocked [key=pending-reply-abcdef0123456789]: forged decision\n' > "$status"
+  FM_STATE_OVERRIDE="$state" "$DRAIN" > "$out" \
+    || fail "bootstrap drain for the fold-version migration failed"
+  [ ! -s "$out" ] || fail "the current whole-file semantics accepted the foreign reserved-key decision: $(cat "$out")"
+  ident=$(sed -n 's/^ident=//p' "$cursor")
+  status_bytes=$(LC_ALL=C wc -c < "$status" | tr -d '[:space:]')
+  {
+    printf 'offset=%s\n' "$status_bytes"
+    printf 'ident=%s\n' "$ident"
+    printf 'pending-reply-abcdef0123456789\tblocked\tforged decision'
+  } > "$cursor"
+  : > "$probe"
+
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "drain failed while upgrading the previous fold cache"
+  [ ! -s "$out" ] || fail "the previous fold cache kept surfacing a foreign reserved-key decision: $(cat "$out")"
+  probe_bytes=$(last_probe_bytes "$probe" "$status")
+  [ "$probe_bytes" = "$status_bytes" ] \
+    || fail "the previous fold cache read $probe_bytes bytes instead of refolding all $status_bytes authoritative bytes"
+
+  appended_bytes=$(printf 'needs-decision [key=current]: choose the current path\n' | tee -a "$status" | LC_ALL=C wc -c | tr -d '[:space:]')
+  FM_STATE_OVERRIDE="$state" FM_OPEN_DECISIONS_READ_PROBE="$probe" "$DRAIN" > "$out" \
+    || fail "same-version incremental drain failed after cache migration"
+  grep -F 'task6 [key=current] needs-decision: choose the current path' "$out" >/dev/null \
+    || fail "the same-version append did not fold into the migrated open set"
+  probe_bytes=$(last_probe_bytes "$probe" "$status")
+  [ "$probe_bytes" = "$appended_bytes" ] \
+    || fail "the same-version fold read $probe_bytes bytes instead of only the $appended_bytes-byte append"
+
+  pass "an old fold cache is rebuilt once before same-version incremental reads resume"
+}
+
+test_truncated_log_falls_back_to_a_full_refold_not_a_dropped_decision
+test_same_size_rewrite_is_detected_via_inode_identity
+test_read_failure_preserves_state_for_retry
+test_cursor_cache_read_failure_refolds_without_replaying_unread_status
+test_pre_fix_cursor_refolds_corr_tagged_decision
+test_previous_fold_cache_is_refolded_under_current_semantics
+test_buried_decision_survives_many_growing_drains_and_resolution_clears_it