firstmate: Skill for Claude Code

process-event-sources

Load this before arming a long-polling source, before registering a deterministic condition->action watch, whenever a check: wake carries procevent <adapter> <source-id> <sequence>, and whenever the watcher headlines a process-event source stranded or process-event source failed to start wake.

The runner exists so a blocking external process never holds firstmate's conversational turn. Firstmate registers a source, keeps working, and is woken when that process completes.

Arming a source

Use the adapter, not the generic runner, for a real source. Before either Lavish arm form below, open the artifact with lavish-axi so its saved session can route the listener; the operating contract owns the prerequisite and refusal boundary. For a Lavish review artifact firstmate owns:

bin/fm-procevent-lavish.sh arm <artifact.html>

A worker-owned board uses bin/fm-procevent-lavish.sh arm <artifact.html> --for <task-id> and re-arms with its reply after each nonterminal round; the existing handled marker is the acknowledgement. Arm it once, then re-arm only when a round is actually waiting: arming again with nothing to acknowledge is refused. A terminal round is never re-armed: the board stays yours until you acknowledge it with bin/fm-procevent.sh handled <source-id> <sequence>, which retires it, and until then retire refuses the board too. Never arm a board that a live task hosts; follow the crew-hosted Lavish board contract for reply acceptance and older-version limits.

Registering a source is not the same fact as listening to it. Lavish arm waits until this registration's listener is confirmed running and does not report ready without that evidence; other adapters still record the source for the watcher's next reconcile. When an earlier registration's listener still holds the board as the confirm window ends, Lavish arm prints still-listening instead of armed; that listener keeps serving the board, and the new registration takes effect only after you retire the source and arm it again. After arming by hand, confirm bin/fm-procevent.sh list reports that source as live, and run bin/fm-procevent.sh reconcile when it does not. Reconcile reports every launch that did not prove it took its claim within the confirm window as failed= and exits non-zero, so a source that cannot be started says so instead of looking armed, and it wakes you once per failure episode about it because the watcher discards that count; start does not fix that - if the source stays unowned, run start attached to read the runner's refusal, then check the source command and adapter binary the registration names, and if a later reconcile finds the source owned the episode closes on its own. A source list reports as orphaned is one reconcile will not relaunch, because something may still be polling it; reconcile wakes you once about it, and that wake's payload says which of two recoveries applies. If the claim's recorded pid is alive under a different identity, bin/fm-procevent.sh start <source-id> takes the source back once you have checked nothing is still polling it - provided the dead generation's reservation records can still be tidied; otherwise it refuses with cannot claim source. If the runner itself died and its process group survives, start reports already owned and takes nothing back: verify whether the dead runner's polling child is still attached to the source, and once that group is empty the next reconcile reclaims the source on its own. Nothing signals that group automatically.