fix(omp): make task-inbox doorbell handshake truthful by dnth · Pull Request #141 · dnth/firstmate

dnth · 2026-09-13T12:51:10Z

Intent

Make the OMP task-inbox doorbell handshake observable and truthful: today a partially failed activate() leaves state/.omp-ready present with no state/.omp-doorbell-ready marker and no diagnostic, so every fm-send reports 'omp-native-refused session-pid=unreadable' and owned redelivery can never succeed. Required change: (1) touch .omp-ready only after activate() succeeds; (2) on activate failure, journal the reason durably (state/.omp-doorbell-failed with the error text) and keep retiring cleanly; (3) make fm-send's refusal message name the concrete missing marker / failure journal so firstmate sees WHY instead of 'unreadable'; (4) spawn-time verification: fm-spawn.sh waits (bounded) for .omp-doorbell-ready after .omp-ready and reports a clear spawn failure if it never appears. Tests: extension unit tests for activate success/failure marker behaviour; bash tests for spawn-time wait and the improved refusal text. Accepted Firstmate requirements: deterministic default failure-journal derivation from the ready marker (caller-neutral .omp-doorbell-failed. fallback when no marker configured); the bounded doorbell wait applies to every launch emitting the generated extension including secondmate OMP launches, while raw OMP launches without the generated template remain exempt; drain-time send failures (synchronous and asynchronous sendMessage rejections) journal 'drain' and retire the marker, and initial async sends are included in activation success so a rejection cannot leave .omp-ready published; existing PR #136 doorbell/turn-proof tests are preserved including test_requester_window_tracks_turn_grace_and_acked_suppresses and uncorrelated turn_start expectations. Firstmate-Validation-Generation: e9d3c7781595d3a306320cb18dca0177

What Changed

Updated the generated OMP extension handshake so .omp-ready is published only after successful activation; activation and drain failures are durably journaled, owned markers retire cleanly, and initial async sends participate in activation success.
Added a bounded .omp-doorbell-ready wait and clear failure reporting to template-based OMP spawns, including secondmate launches, while leaving raw OMP launches exempt.
Improved native OMP refusal diagnostics to identify the missing, unreadable, or unproven marker or its failure journal, with expanded coverage for activation, redelivery, relaunch, dispatch, and secondmate paths.

Risk Assessment

⚠️ Medium: The changes satisfy the stated handshake, journaling, refusal-diagnostics, bounded-wait, and async-drain requirements; no concrete source defect was substantiated, though the concurrency and lifecycle logic is materially complex.

Testing

The focused executable tests covering activation success/failure journaling, refusal diagnostics, bounded OMP spawn waits, and secondmate extension handling passed. The required live OMP worker check was attempted but blocked by the no-mistakes gate-worktree fleet guard, so live scenarios remain untested.

Live validation: ⚠️ inconclusive - 0 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
Start a generated OMP worker and observe truthful readiness: .omp-ready appears only after successful doorbell activation and .omp-doorbell-ready is present.	⏸️ untested	no	The real OMP worker harness could not run because `fm-send.sh` refused fleet lifecycle from this no-mistakes gate worktree. Provide a normal checkout/worktree (or equivalent fleet-driving authority) a…
Force OMP activation failure and verify no false ready marker, durable .omp-doorbell-failed journal, and clean retirement.	⏸️ untested	no	The real worker could not be launched in this gate worktree due the fleet lifecycle guard. Re-run outside the gate worktree with fleet-driving authority.
Send to an OMP session with missing/failed doorbell binding and verify fm-send names the concrete marker or failure journal instead of 'session-pid=unreadable'.	⏸️ untested	no	A real running session was unavailable because the live harness was refused by the no-mistakes gate-worktree guard. Provide a normal runtime environment and rerun the live test.
Spawn generated-extension OMP workers (including secondmates) and verify bounded wait for .omp-doorbell-ready; raw OMP launches remain exempt.	⏸️ untested	no	Fleet spawn lifecycle is blocked from this gate worktree. Run the live spawn harness from a regular checkout/worktree with permission to create endpoints and workers.

Evidence: Doorbell targeted tests

ok - OMP extension drains canonical counted requests and safely retires signal readiness
ok - OMP extension requires turn proof and re-drives a deferred triggerTurn through the user channel
ok - OMP doorbell driven by external turn notifications proves turns and unlatches on turn_end
ok - OMP extension activation reports failures, journals their reasons, and retires cleanly
ok - doorbell routing keeps OMP on its native adapter and preserves the non-OMP composer branch
ok - OMP pending retries revalidate identity while ambiguous claims suppress resend
ok - fm-send and both tmux/Herdr adapters preserve task-bound OMP programmatic doorbells
ok - fm-send: an OMP steer is received natively over tmux and Herdr with no composer transport
ok - fm-send: refused and unacknowledged OMP steers stay bounded, durable and non-resend-inviting
ok - fm-send: an unproven OMP session binding is refused, never redirected to the terminal
ok - requester ack window tracks the turn grace and an acked receipt suppresses the re-ring

Evidence: Spawn doorbell targeted tests

ok - no --model/--effort records defaults and types the claude launch instructions
ok - relative home overrides ignore CDPATH and become absolute before spawn launch construction
ok - FM_HOME defaults resolve relative paths and preserve absolute spellings
ok - generated OMP worker extension gates .omp-ready on doorbell activation and journals the failure
ok - OMP spawn bounded-waits on .omp-doorbell-ready and fails loudly on absence or journaled failure
ok - OMP secondmates trust exact primary and fleet extensions while inspecting staged code

- Outcome: ⚠️ 2 warnings across 1 run (6m5s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed (7) ✅

🚨 .omp/extensions/lib/fm-task-inbox-doorbell.ts:390 - The activation wait snapshots activationSends once at line 389. A request arriving while that snapshot is pending can start a second asynchronous sendMessage; that promise is added after the snapshot and is not awaited. If the first send resolves, activate() returns true and the generated extension touches .omp-ready; when the late send rejects, its handler only journals and retires the doorbell marker, leaving .omp-ready behind. This recreates the false-ready invariant during concurrent initial drain activity. Keep activation from resolving until all sends initiated during activation have settled, or otherwise propagate any later rejection before readiness is published.

🔧 Fix applied.
1 warning still open:

⚠️ bin/fm-task-inbox-lib.sh:252 - fm_task_inbox_omp_doorbell_state() reports doorbell-binding-unproven=<marker> whenever the marker is valid but the native request fails for another reason. For example, if <marker>.requests is missing during teardown/race, fm_omp_task_doorbell_request() returns 1, the refusal path reaches this helper, and fm-send claims the session binding is unproven even though the binding is valid and the request directory is the concrete failure. Add a state check for the request directory (and any similarly distinguishable request-write failure) so the refusal names the actual missing artifact instead of a false cause.