feat(bin): wake firstmate when a monitored PR goes conflicting

[sbracewell64]

Intent

Extend firstmate's armed PR merge monitoring so a monitored open pull request that becomes conflicted wakes firstmate within one poll cycle, instead of waiting for long-cadence rechecks or a maintainer bot's comment. Captain-ordered 2026-07-31; the cost evidence is PR 1267 overtaken six times in a day and PR 1284 sitting conflicted for an hour until a human noticed a bot comment.

Deliberate design decisions, all reviewed and approved by firstmate before implementation, so they are choices rather than oversights:

1. The conflict signal deliberately rides the EXISTING byte-static validated poll (bin/fm-pr-poll.sh + the private state/.pr-poll sidecar and its hash/inode registration), never a new ad-hoc executable check. Extending within that shape was an explicit constraint.

2. The poll's single GitHub request now selects state,mergeable,headRefOid instead of state alone, so conflict detection adds ZERO extra forge calls. This was a hard cost constraint and there is a test asserting exactly one 'pr view' call per poll.

3. GraphQL 'mergeable' (CONFLICTING) is read rather than 'mergeStateStatus' (DIRTY), even though the task text named mergeable_state=dirty. Reason: the two agree on a conflict, but mergeStateStatus rides a preview header and is likelier to be absent on GitHub Enterprise Server, and its non-conflict values (UNSTABLE) also report failing or pending checks, which is a different signal this poll must stay silent about. This is intentional, not a misreading of the requirement.

4. 'merged' is decided first and alone, so merged and closed pull requests emit byte-identical results to before, and their retirement records are untouched. Preserving those paths exactly was an acceptance criterion.

5. Deliberately NO retry when GitHub briefly reports mergeability as UNKNOWN while recomputing after a base push. Firstmate explicitly ruled on this: GitHub recomputes on the base push, so a sweep arriving minutes later normally reads a settled value, and one extra cycle on a rare race is cheaper than adding an API call and a timing dependency to a static security-sensitive program. The limitation is documented in docs/architecture.md rather than engineered around. Do not flag the missing retry as a gap.

6. Dedupe is keyed on the PR head commit, held in a new watcher marker state/.pr-dirty-, with an FM_PR_DIRTY_RESURFACE_SECS=3600 backstop. The head is the key BECAUSE poll silence is ambiguous - clean, unknown, closed, and every error look identical - so silence can never clear the key, while a changed head does mean the branch moved and went conflicting again. This asymmetry is the whole point of the design; a reviewer may be tempted to 'simplify' it to clearing on silence, which would re-wake after every transient network error.

7. GitLab is deliberately untouched and keeps merge-only detection: plain 'glab mr view' field output carries no conflict field, and reading one would need a JSON processor firstmate deliberately does not depend on. This mirrors the existing precedent that a GitLab task records no pr_head. Not an omission.

8. Changing the poll's bytes intentionally retires every currently-armed check. This is the established upgrade path, not a regression: migration_needed in bin/fm-pr-check-migrate.sh is content-based, so the next --checks-safe run (which both bootstrap and watcher start already perform) quarantines stale copies and rebuilds each poll from the recorded pr=. Homes see one PR_CHECK_MIGRATION line and lose no armed watch.

9. One clause was added to AGENTS.md section 8's existing check: bullet naming the conflicted-PR result and the rebase response. Firstmate explicitly approved this one-clause growth of always-loaded doctrine because the captain ruled that conflict resolution is fully delegated to workers. Kept to one clause, no new line, per AGENTS.md size discipline.

10. The worker-side standing rule ('workers rebase autonomously on any cleanly-reconcilable conflict') is deliberately OUT OF SCOPE here and is being filed as its own task against the brief scaffold. Do not flag its absence from bin/fm-brief.sh.

Tests are colocated in tests/fm-pr-check-security.test.sh per repo convention and exercise behavior through the real poll and the real watcher, never implementation source bytes: the dirty-transition wake, dedupe across repeated sweeps, a new head re-waking, resurface-window expiry, clean/closed silence, unchanged merged retirement, teardown marker cleanup, one-call cost, malformed forge rows, and GitLab never emitting a conflict. The fake gh fixture was updated to answer the new field selection as a tab-separated row.

Verification already performed: full tests/fm-pr-check-security.test.sh green (38 passed); adjacent suites green (109 passed across teardown, watch-triage, wake-queue, pr-merge, watch-checkpoint, guard-stale-banner); bin/fm-lint.sh clean at pinned ShellCheck 0.11.0; bin/fm-doc-audience-check.sh clean; the suite was additionally proven hermetic with sentinel gh/glab/gh-axi shims ahead of the real binaries on the test BASE_PATH (zero escapes); and the poll was verified live against real PRs 1378 and 1330 (conflicted, emitted 'dirty '), 1368 (mergeable, silent), 1358 (merged, emitted 'merged'), and a nonexistent PR (silent).

What Changed

• bin/fm-pr-poll.sh now selects state,mergeable,headRefOid in its single gh pr view request and emits dirty <head> for an OPEN GitHub pull request the forge reports as CONFLICTING, keeping conflict detection at zero extra forge calls; merged is still decided first and alone, so merged and closed pull requests emit byte-identical results, and malformed or unexpected forge output stays silent. GitLab keeps merge-only detection.
• bin/fm-watch.sh dedupes conflict wakes per episode with a new state/.pr-dirty-<id> marker keyed on the reported head commit, backstopped by FM_PR_DIRTY_RESURFACE_SECS (3600s default); the marker is written only after fm_wake_append succeeds — the review pass moved that record after the enqueue so a failed queue append re-surfaces the conflict instead of swallowing it. The wake reason carries the PR URL so the worker can be steered to rebase, and a merged result clears the marker. bin/fm-teardown.sh removes the marker with the other PR-poll artifacts.
• Docs and tests: docs/architecture.md documents the conflict path, the head-keyed dedupe, the transient-UNKNOWN silence, and the GitLab carve-out; docs/configuration.md documents the new knob; AGENTS.md gains one clause on the conflicted-PR check result plus the new .pr-dirty-* watcher-internal entry, and the "merge poll" wording in AGENTS.md/docs/scripts.md was broadened to "PR poll". tests/fm-pr-check-security.test.sh grows to 40 checks covering the dirty-transition wake, dedupe and new-head re-wake, resurface expiry, one-call cost, wake-queue-failure recovery, and teardown cleanup.

Risk Assessment

✅ Low: The conflict signal rides the existing single-call validated poll with merged and closed paths preserved byte-identically, the only prior defect (dedupe marker written before the wake was durably enqueued) is now fixed to match the watcher's own enqueue-then-mark invariant and is covered by a regression test using an already-proven queue-failure fixture, and the remaining new state is one watcher-internal marker cleaned up on merge and teardown.

Testing

Ran the colocated tests/fm-pr-check-security.test.sh (40 checks green, covering the four new conflict tests) and the adjacent tests/fm-teardown.test.sh (33 green) for the modified teardown path, then drove the real arm → poll → watcher → wake-drain chain end to end to capture what firstmate actually sees: a conflicting PR surfaces one dirty <head> <url> wake in the same sweep, the same unrebased head stays silent on the next sweep, a moved head wakes again, and merged still emits its unchanged merged reason while retiring the poll and its conflict marker — all at exactly one gh pr view call per poll. Also demonstrated the documented upgrade path, where a home armed on the previous poll bytes is rebuilt by --checks-safe with one PR_CHECK_MIGRATION line and keeps its watch. No visual artifact applies: this change is a bash watcher and CLI with no rendered surface, so the reviewer-visible evidence is the wake-queue transcript. All checks passed and scratch homes were removed; the worktree is clean.

Evidence: End-to-end conflicted-PR wake transcript (arm → poll → watcher → wake-drain)

=== 2. sweep with the PR still mergeable === --- poll output --- --- forge calls made by that poll --- gh pr view kunchenguid#1284 --json state,mergeable,headRefOid -q [.state,.mergeable,.headRefOid]|@tsv --- what firstmate reads on wake (fm-wake-drain.sh) --- (no wake - firstmate is not disturbed) --- conflict episode marker --- (none) === 3. sweep after the PR was overtaken and went CONFLICTING === --- poll output --- dirty 1111111122222222333333334444444455555555 --- forge calls made by that poll --- gh pr view kunchenguid#1284 --json state,mergeable,headRefOid -q [.state,.mergeable,.headRefOid]|@tsv --- what firstmate reads on wake (fm-wake-drain.sh) --- 1785505195 1 check .../state/task-a.check.sh check: .../task-a.check.sh: dirty 1111111122222222333333334444444455555555 kunchenguid#1284 conflict episode marker --- state/.pr-dirty-task-a = 1111111122222222333333334444444455555555 === 4. next sweep, same unrebased conflict (dedupe) === --- poll output --- dirty 1111111122222222333333334444444455555555 --- what firstmate reads on wake (fm-wake-drain.sh) --- (no wake - firstmate is not disturbed) === 5. sweep after the branch moved and conflicted again at a new head === --- what firstmate reads on wake (fm-wake-drain.sh) --- 1785505207 2 check .../task-a.check.sh check: .../task-a.check.sh: dirty 6666666677777777888888889999999900000000 https://github.com/kunchenguid/firstmate/pull/1284

=== 6. sweep after the PR merged === --- poll output --- merged --- what firstmate reads on wake (fm-wake-drain.sh) --- 1785505208 3 check .../task-a.check.sh check: .../task-a.check.sh: merged --- conflict episode marker --- (none) === 7. armed poll artifacts after merge retirement === task-a.meta

=== 1. arm the merge watch on an open PR (fm-pr-check.sh) ===
●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
●  WATCHER DOWN - SUPERVISION IS OFF
●  1 task(s) in flight, but no watcher has a fresh beacon (last beat: never, grace 300s).
●  Trust the emitted supervision protocol for this harness; do not use shell & for watcher repair.
●  This is a supervision warning only; the guarded operation WILL still run.
●  repair missing watcher supervision with bin/fm-watch-arm.sh as its own Claude Code background task, never shell &.
●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
armed: state/task-a.check.sh
armed poll sidecar: github https://github.com/kunchenguid/firstmate/pull/1284 github.com kunchenguid/firstmate 1284 

=== 2. sweep with the PR still mergeable ===
--- poll output (what the watcher check prints) ---
--- forge calls made by that poll ---
  gh pr view https://github.com/kunchenguid/firstmate/pull/1284 --json state,mergeable,headRefOid -q [.state,.mergeable,.headRefOid]|@tsv
--- what firstmate reads on wake (fm-wake-drain.sh) ---
  (no wake - firstmate is not disturbed)
--- conflict episode marker ---
  (none)

=== 3. sweep after the PR was overtaken and went CONFLICTING ===
--- poll output (what the watcher check prints) ---
  dirty 1111111122222222333333334444444455555555
--- forge calls made by that poll ---
  gh pr view https://github.com/kunchenguid/firstmate/pull/1284 --json state,mergeable,headRefOid -q [.state,.mergeable,.headRefOid]|@tsv
--- what firstmate reads on wake (fm-wake-drain.sh) ---
  1785505195	1	check	/tmp/fm-e2e-conflict/home/state/task-a.check.sh	check: /tmp/fm-e2e-conflict/home/state/task-a.check.sh: dirty 1111111122222222333333334444444455555555 https://github.com/kunchenguid/firstmate/pull/1284
--- conflict episode marker ---
  state/.pr-dirty-task-a = 1111111122222222333333334444444455555555

=== 4. next sweep, same unrebased conflict (dedupe) ===
--- poll output (what the watcher check prints) ---
  dirty 1111111122222222333333334444444455555555
--- forge calls made by that poll ---
  gh pr view https://github.com/kunchenguid/firstmate/pull/1284 --json state,mergeable,headRefOid -q [.state,.mergeable,.headRefOid]|@tsv
--- what firstmate reads on wake (fm-wake-drain.sh) ---
  (no wake - firstmate is not disturbed)
--- conflict episode marker ---
  state/.pr-dirty-task-a = 1111111122222222333333334444444455555555

=== 5. sweep after the branch moved and conflicted again at a new head ===
--- poll output (what the watcher check prints) ---
  dirty 6666666677777777888888889999999900000000
--- forge calls made by that poll ---
  gh pr view https://github.com/kunchenguid/firstmate/pull/1284 --json state,mergeable,headRefOid -q [.state,.mergeable,.headRefOid]|@tsv
--- what firstmate reads on wake (fm-wake-drain.sh) ---
  1785505207	2	check	/tmp/fm-e2e-conflict/home/state/task-a.check.sh	check: /tmp/fm-e2e-conflict/home/state/task-a.check.sh: dirty 6666666677777777888888889999999900000000 https://github.com/kunchenguid/firstmate/pull/1284
--- conflict episode marker ---
  state/.pr-dirty-task-a = 6666666677777777888888889999999900000000

=== 6. sweep after the PR merged ===
--- poll output (what the watcher check prints) ---
  merged
--- forge calls made by that poll ---
  gh pr view https://github.com/kunchenguid/firstmate/pull/1284 --json state,mergeable,headRefOid -q [.state,.mergeable,.headRefOid]|@tsv
--- what firstmate reads on wake (fm-wake-drain.sh) ---
  1785505208	3	check	/tmp/fm-e2e-conflict/home/state/task-a.check.sh	check: /tmp/fm-e2e-conflict/home/state/task-a.check.sh: merged
--- conflict episode marker ---
  (none)

=== 7. armed poll artifacts after merge retirement ===
  task-a.meta

Evidence: Upgrade-path transcript: previously-armed poll rebuilt by --checks-safe, no watch lost

=== 1. home armed on the PREVIOUS poll bytes === armed check matches previous release bytes: yes conflict result from the stale poll: ^ empty: the old poll cannot report conflicts === 2. next --checks-safe run (what bootstrap / watcher start performs) === PR_CHECK_MIGRATION: canonical polls rebuilt and armed; resume supervision for this home === 3. armed watch after the upgrade === still armed: yes rebuilt from current poll bytes: yes sidecar: github kunchenguid#1267 github.com kunchenguid/firstmate 1267 conflict result from the rebuilt poll: dirty abcdef0123456789abcdef0123456789abcdef01 merged result from the rebuilt poll: merged

=== 1. home armed on the PREVIOUS poll bytes ===
armed check matches previous release bytes: yes
conflict result from the stale poll: 
  ^ empty: the old poll cannot report conflicts

=== 2. next --checks-safe run (what bootstrap / watcher start performs) ===
  PR_CHECK_MIGRATION: canonical polls rebuilt and armed; resume supervision for this home

=== 3. armed watch after the upgrade ===
still armed: yes
rebuilt from current poll bytes: yes
sidecar: github https://github.com/kunchenguid/firstmate/pull/1267 github.com kunchenguid/firstmate 1267 
conflict result from the rebuilt poll: dirty abcdef0123456789abcdef0123456789abcdef01
merged result from the rebuilt poll: merged

Evidence: Scenario driver: conflicted-PR end-to-end

#!/usr/bin/env bash
# End-to-end: a monitored open PR goes conflicting -> firstmate is woken within
# one poll cycle. Uses the real fm-pr-check.sh (arm), fm-pr-poll.sh (poll),
# fm-watch.sh (watcher) and fm-wake-drain.sh (what firstmate reads at wake).
set -u
ROOT=$1
DIR=$2
rm -rf "$DIR"; mkdir -p "$DIR/home/state" "$DIR/home/data" "$DIR/home/config" "$DIR/fakebin"
BASE_PATH=/usr/bin:/bin:/usr/sbin:/sbin
URL=https://github.com/kunchenguid/firstmate/pull/1284
HEAD_A=1111111122222222333333334444444455555555
HEAD_B=6666666677777777888888889999999900000000

# Stand-in forge CLI: answers exactly the field selection the poll asks for.
cat > "$DIR/fakebin/gh" <<'SH'
#!/usr/bin/env bash
printf 'gh %s\n' "$*" >> "$FM_TEST_GH_LOG"
case " $* " in
  *" state,mergeable,headRefOid "*)
    printf '%s\t%s\t%s\n' "${FM_TEST_GH_STATE:-OPEN}" "${FM_TEST_GH_MERGEABLE:-MERGEABLE}" "${FM_TEST_GH_HEAD:-0000000000000000000000000000000000000000}" ;;
  *" headRefOid "*) printf '%s\n' "${FM_TEST_GH_HEAD:-0000000000000000000000000000000000000000}" ;;
esac
SH
chmod +x "$DIR/fakebin/gh"

printf 'window=fm-task-a\nendpoint_task_id=task-a\nkind=ship\n' > "$DIR/home/state/task-a.meta"

banner() { printf '\n=== %s ===\n' "$*"; }

banner "1. arm the merge watch on an open PR (fm-pr-check.sh)"
FM_HOME="$DIR/home" FM_ROOT_OVERRIDE="$ROOT" FM_TEST_GH_LOG="$DIR/gh.log" \
  PATH="$DIR/fakebin:$BASE_PATH" "$ROOT/bin/fm-pr-check.sh" task-a "$URL"
printf 'armed poll sidecar: '; tr '\n' ' ' < "$DIR/home/state/task-a.pr-poll"; echo

sweep() { # <label> <state> <mergeable> <head>
  local label=$1
  rm -f "$DIR/home/state/.last-check"
  : > "$DIR/gh.log"
  banner "$label"
  printf -- '--- poll output (what the watcher check prints) ---\n'
  FM_TEST_GH_LOG="$DIR/gh.log" FM_TEST_GH_STATE=$2 FM_TEST_GH_MERGEABLE=$3 FM_TEST_GH_HEAD=$4 \
    PATH="$DIR/fakebin:$BASE_PATH" bash "$DIR/home/state/task-a.check.sh" | sed 's/^/  /'
  printf -- '--- forge calls made by that poll ---\n'
  sed 's/^/  /' "$DIR/gh.log"
  : > "$DIR/gh.log"
  perl -e 'my $pid=fork; die unless defined $pid; if(!$pid){exec @ARGV} local $SIG{ALRM}=sub{kill "TERM",$pid; waitpid $pid,0; exit 124}; alarm 12; waitpid $pid,0; alarm 0; exit($?>>8)' \
    env FM_HOME="$DIR/home" FM_ROOT_OVERRIDE="$ROOT" FM_CHECK_INTERVAL=0 FM_CHECK_TIMEOUT=5 \
      FM_POLL=0.02 FM_HEARTBEAT=999999 FM_SIGNAL_GRACE=0 FM_TEST_GH_LOG="$DIR/gh.log" \
      FM_TEST_GH_STATE=$2 FM_TEST_GH_MERGEABLE=$3 FM_TEST_GH_HEAD=$4 \
      PATH="$DIR/fakebin:$BASE_PATH" "$ROOT/bin/fm-watch.sh" >/dev/null 2>&1
  printf -- '--- what firstmate reads on wake (fm-wake-drain.sh) ---\n'
  out=$(FM_HOME="$DIR/home" FM_ROOT_OVERRIDE="$ROOT" PATH="$DIR/fakebin:$BASE_PATH" \
    "$ROOT/bin/fm-wake-drain.sh" 2>/dev/null)
  if [ -n "$out" ]; then printf '%s\n' "$out" | sed 's/^/  /'; else printf '  (no wake - firstmate is not disturbed)\n'; fi
  printf -- '--- conflict episode marker ---\n'
  if [ -e "$DIR/home/state/.pr-dirty-task-a" ]; then
    printf '  state/.pr-dirty-task-a = %s\n' "$(cat "$DIR/home/state/.pr-dirty-task-a")"
  else printf '  (none)\n'; fi
}

sweep "2. sweep with the PR still mergeable" OPEN MERGEABLE "$HEAD_A"
sweep "3. sweep after the PR was overtaken and went CONFLICTING" OPEN CONFLICTING "$HEAD_A"
sweep "4. next sweep, same unrebased conflict (dedupe)" OPEN CONFLICTING "$HEAD_A"
sweep "5. sweep after the branch moved and conflicted again at a new head" OPEN CONFLICTING "$HEAD_B"
sweep "6. sweep after the PR merged" MERGED CONFLICTING "$HEAD_B"
banner "7. armed poll artifacts after merge retirement"
ls "$DIR/home/state" | grep -E 'task-a|pr-dirty' | sed 's/^/  /' || printf '  (all task-a poll artifacts retired)\n'

Evidence: Scenario driver: upgrade path

#!/usr/bin/env bash
# End-to-end upgrade path: a home whose PR poll was armed with the PREVIOUS
# fm-pr-poll.sh bytes must, on the next --checks-safe run (which bootstrap and
# watcher start both perform), rebuild the poll from the recorded pr= and keep
# watching - now with conflict reporting - rather than lose the armed watch.
set -u
ROOT=$1
DIR=$2
OLD_POLL=$3
rm -rf "$DIR"; mkdir -p "$DIR/home/state" "$DIR/home/data" "$DIR/home/config" "$DIR/fakebin"
BASE_PATH=/usr/bin:/bin:/usr/sbin:/sbin
URL=https://github.com/kunchenguid/firstmate/pull/1267
HEAD=abcdef0123456789abcdef0123456789abcdef01
cat > "$DIR/fakebin/gh" <<'SH'
#!/usr/bin/env bash
case " $* " in
  *" state,mergeable,headRefOid "*)
    printf '%s\t%s\t%s\n' "${FM_TEST_GH_STATE:-OPEN}" "${FM_TEST_GH_MERGEABLE:-MERGEABLE}" "${FM_TEST_GH_HEAD:-0000000000000000000000000000000000000000}" ;;
  *" headRefOid "*) printf '%s\n' "${FM_TEST_GH_HEAD:-0000000000000000000000000000000000000000}" ;;
esac
SH
chmod +x "$DIR/fakebin/gh"
printf 'window=fm-task-a\nendpoint_task_id=task-a\nkind=ship\npr=%s\n' "$URL" > "$DIR/home/state/task-a.meta"

banner() { printf '\n=== %s ===\n' "$*"; }
banner "1. home armed on the PREVIOUS poll bytes"
FM_HOME="$DIR/home" FM_ROOT_OVERRIDE="$ROOT" PATH="$DIR/fakebin:$BASE_PATH" \
  "$ROOT/bin/fm-pr-check.sh" task-a "$URL" >/dev/null 2>&1
cp "$OLD_POLL" "$DIR/home/state/task-a.check.sh"
chmod 0600 "$DIR/home/state/task-a.check.sh"
printf 'armed check matches previous release bytes: %s\n' \
  "$(cmp -s "$DIR/home/state/task-a.check.sh" "$OLD_POLL" && echo yes || echo no)"
printf 'conflict result from the stale poll: %s\n' \
  "$(FM_TEST_GH_STATE=OPEN FM_TEST_GH_MERGEABLE=CONFLICTING FM_TEST_GH_HEAD=$HEAD \
     PATH="$DIR/fakebin:$BASE_PATH" bash "$DIR/home/state/task-a.check.sh" || true)"
printf '  ^ empty: the old poll cannot report conflicts\n'

banner "2. next --checks-safe run (what bootstrap / watcher start performs)"
FM_HOME="$DIR/home" FM_ROOT_OVERRIDE="$ROOT" PATH="$DIR/fakebin:$BASE_PATH" \
  "$ROOT/bin/fm-pr-check-migrate.sh" --checks-safe 2>&1 | sed 's/^/  /'

banner "3. armed watch after the upgrade"
printf 'still armed: %s\n' "$([ -f "$DIR/home/state/task-a.check.sh" ] && echo yes || echo no)"
printf 'rebuilt from current poll bytes: %s\n' \
  "$(cmp -s "$DIR/home/state/task-a.check.sh" "$ROOT/bin/fm-pr-poll.sh" && echo yes || echo no)"
printf 'sidecar: '; tr '\n' ' ' < "$DIR/home/state/task-a.pr-poll"; echo
printf 'conflict result from the rebuilt poll: %s\n' \
  "$(FM_TEST_GH_STATE=OPEN FM_TEST_GH_MERGEABLE=CONFLICTING FM_TEST_GH_HEAD=$HEAD \
     PATH="$DIR/fakebin:$BASE_PATH" bash "$DIR/home/state/task-a.check.sh")"
printf 'merged result from the rebuilt poll: %s\n' \
  "$(FM_TEST_GH_STATE=MERGED PATH="$DIR/fakebin:$BASE_PATH" bash "$DIR/home/state/task-a.check.sh")"

Evidence: tests/fm-pr-check-security.test.sh run log

ok - raw-byte parser accepts canonical URLs and rejects the complete adversarial matrix
ok - GitLab merge requests are followed on any instance and never wake falsely
ok - validated merged polls notify once and retire before the next watcher cycle
ok - merged poll retirement preserves every persistent secondmate lifecycle artifact
ok - queue, receipt, and every fixed-path removal crash point recover without loss or repeated execution
ok - open/red, closed-unmerged, malformed, and forge errors remain armed until an exact merged transition
ok - replacement, nonterminal, tampered, and custom results receive no deletion authority
ok - queue failure and untrusted receipts preserve canonical poll evidence
ok - GitHub and GitLab exact merged results share one retirement path
ok - PR and teardown entrypoints reject invalid arguments before every side effect
ok - valid direct and merge flows record exact metadata and reject multiline head metadata
ok - rejected metacharacter bytes remain inert at generation and watcher time
ok - static poll is silent except for one merged line on a mergeable pull request and remains watcher-bounded
ok - conflict reporting emits one dirty line for an open conflicting pull request and nothing else
ok - a conflicted pull request wakes once per episode and leaves clean, closed, and merged outcomes unchanged
ok - a conflict lost to a wake queue failure re-surfaces on the next sweep
ok - teardown retires the conflict episode marker with the rest of the poll
ok - interrupted atomic preparation cleans private temporaries and publishes nothing
ok - concurrent watchers observe only complete private poll publications
ok - post-rename poll validation faults revoke both names and allow a clean retry
ok - migration creates and validates private state before watcher exclusion
ok - migration pauses older watchers and acquires exclusion before its first scan or marker
ok - poll, marker, diagnostic, and quarantine paths refuse symlinks and directories
ok - marker and diagnostic rename errors and signals fail closed and recover durably on retry
ok - post-rename marker, diagnostic, and obligation faults are revoked and reconstructed on retry
ok - quarantine type and mode faults fail closed and recover only when a retry can validate them
ok - canonical and ambiguous failure obligations block every retry until all task artifacts are repaired
●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
●  WATCHER DOWN - SUPERVISION IS OFF
●  1 task(s) in flight, but no watcher has a fresh beacon (last beat: never, grace 300s).
●  Trust the emitted supervision protocol for this harness; do not use shell & for watcher repair.
●  This is a supervision warning only; the guarded operation WILL still run.
●  repair missing watcher supervision with bin/fm-watch-arm.sh as its own Claude Code background task, never shell &.
●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ok - ambiguous migration recovery accepts an explicitly validated replacement poll
ok - ambiguous repair rejects copied, metadata- or task-mismatched, forged, and partial poll publications
ok - all live, marker, diagnostic, X, custom-check, obligation, and teardown boundaries require single-link files
ok - canonical publication failure remains incomplete until a later clean retry rebuilds the poll
ok - legacy reserved obligations and delimiter-bearing task IDs retry without ambiguity
ok - migration never executes legacy checks, preserves X mode, quarantines ambiguity, and is idempotent
ok - historical X shims migrate only from the exact single-link mode-0755 identity
ok - direct registration refreshes authenticated v1 X shims across marker states
ok - bootstrap runs the non-executing migration at the locked session boundary
ok - bootstrap isolates incomplete poll migration from unrelated recovery sweeps
ok - watcher signals promptly stop custom checks and clean private state
ok - returned custom check descendants are drained on installed and fallback timeout paths
ok - teardown removes safe poll artifacts and refuses quarantine-directory symlinks without traversal

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅

• ⚠️ bin/fm-watch.sh:814 - pr_dirty_wake_due() records the dedupe marker (line 566) before the wake is enqueued, but fm_wake_append at line 817 exits the watcher on failure. If the queue append fails (lock failure, full/read-only disk), the conflict wake is lost while state/.pr-dirty-<id> already holds that head, so the restarted watcher suppresses the same conflict for up to FM_PR_DIRTY_RESURFACE_SECS (1h by default) — the exact failure mode the design's own comment guards against in the other direction ("a marker that cannot be written surfaces rather than suppresses"). Every other wake path in this file inverts the order deliberately: fm-watch.sh:305 appends then clears .stale-since-, :427 appends then writes .stale-/.paused-, :874 appends for all pending signals and only then advances .seen- markers, with scan_signals' comment at line 456 stating the invariant explicitly ("a watcher killed mid-cycle never swallows a signal"). Fix by splitting the decision from the record: have pr_dirty_wake_due only compare marker content and age, and write the marker after fm_wake_append succeeds, alongside the existing rm -f at line 819.

🔧 Fix: record PR conflict episode only after wake enqueued
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-pr-check-security.test.sh — 40 checks green, including test_static_poll_conflict_contract, test_conflicted_pr_wakes_once_per_conflict_episode, test_conflict_episode_survives_wake_queue_failure, test_teardown_removes_conflict_episode_marker
• bash tests/fm-teardown.test.sh — 33 checks green (adjacent suite for the modified bin/fm-teardown.sh)
• Manual end-to-end scenario: real bin/fm-pr-check.sh arms a watch, real bin/fm-watch.sh sweeps against a stand-in gh returning OPEN/MERGEABLE, OPEN/CONFLICTING (same head twice, then a new head), and MERGED, with real bin/fm-wake-drain.sh printing the wake firstmate consumes after each sweep
• Per-sweep forge-call log asserted to contain exactly one gh pr view ... --json state,mergeable,headRefOid invocation
• Manual upgrade-path scenario: poll armed with the base-commit fm-pr-poll.sh bytes, then bin/fm-pr-check-migrate.sh --checks-safe run to show the rebuilt, still-armed poll now reporting conflicts

🔧 **Document** - 1 issue found → auto-fixed ✅

• ℹ️ AGENTS.md:318 - AGENTS.md:318 and the docs/scripts.md fm-pr-check.sh row still call the armed artifact "the watcher's merge poll" / "a static merge poll", which now under-describes it (it also reports conflicts). I deliberately left both: docs/architecture.md is the authoritative owner of the conflict behavior and already states it, the poll's own scripts.md row was updated, and growing AGENTS.md further would violate its size discipline and this change's stated one-clause budget. Flagging as a judgment call in case you prefer the name broadened to "PR poll" in those two spots.

🔧 Fix: rename merge poll to PR poll in armed-check docs
✅ Re-checked - no issues remain.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.