stuck-crewmate-recovery
Skill2 starsChanged 35 days agoMITView on GitHub
Agent-only playbook for stuck or missing ordinary Firstmate direct reports. Use when the session-start digest reports an ordinary direct report's endpoint dead or its metadata has no window, or after a stale wake, looping pane, repeated confusion, an answered-by-brief question, an unresponsive crewmate, or a failed steer. Also use on the inverse case: a live crewmate reporting the no-mistakes pipeline dead, unreachable, or timed out. Reconciles recorded work before escalating from targeted inspection through safe relaunch or failure.
2 other projects use a version of this, 2 of them edited.
Adopted by
Most recently taken up by
- kunchenguid/firstmateedited, first seen Oct 8, 2026
- karanmrn/claude-skillsedited, first seen Jun 28, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 2
- kunchenguid/firstmate★ 8.9k76% same
- karanmrn/claude-skills★ 051% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository32 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- afkSkill
- agent-skill-trigger-indexSkill
- ahoySkill
- ask-user-authoritySkill
- away-quiet-supervisionSkill
- bearingsSkill
- bootstrap-diagnosticsSkill
- captain-hold-lifecycleSkill
- control-firstmateSkill
- decision-hold-lifecycleSkill
- diagnostic-reasoningSkill
- firstmate-codexappSkill
- firstmate-coding-guidelinesSkill
- firstmate-orcaSkill
- fmx-respondSkill
- harness-adaptersSkill
- operational-home-layoutSkill
- process-event-sourcesSkill
- project-managementSkill
- quietSkill
- quota-array-dispatchSkill
- scout-completionSkill
- secondmate-provisioningSkill
- session-start-recoverySkill
- ship-landingSkill
- stowSkill
- updatefirstmateSkill
- validation-supervisionSkill
- verify-firstmateSkill
- stowSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 7 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 18
Follow the crew-hosted Lavish board contract in docs/configuration.md when recovering a worker that hosts a board.
- Very specific: line 33
Treat the digest's endpoint result as a presence signal, not proof that the task's work or validation run is gone.
- Very specific: line 34
Read the targeted current state with bin/fm-crew-state.sh <id> before deciding to relaunch.
- Very specific: line 37
When no authoritative run accounts for the task, inspect only its recorded backend and worktree inventory.
- Very specific: line 38
Use treehouse status for treehouse-backed tmux, herdr, zellij, or cmux tasks, and use the recorded orca_worktree_id= and terminal= for Orca …
- Distinctive: line 39
Do not sweep another home's endpoints or infer ownership from a matching window label.
- Distinctive: line 41
Before relaunch, prove that no live agent still owns the recorded task and that the existing worktree remains available.
- Very specific: line 46
Do not work around either refusal by respawning - it means a live agent may still hold that worktree.
- Distinctive: line 48
Do not use a fresh generic spawn while the recorded worktree is unaccounted for, because allocating another worktree can split one task …
- Distinctive: line 49
If the worktree or ownership cannot be reconciled safely, leave all state intact and report the task failed or blocked with the conflicting …
- Distinctive: line 57
Read the two authoritative sources yourself before believing the claim:
- Distinctive: line 66
Never restart, stop, or update the shared daemon on a crewmate's claim.
- Distinctive: line 68
Only positive socket refusal or absence is a daemon-down finding.
- Very specific: line 75
If the crewmate is waiting on a question its brief already answers, answer in one line via FM_HOME=<this-firstmate-home> bin/fm-send.sh …
- Very specific: line 76
If the crewmate is confused or looping, interrupt with FM_HOME=<this-firstmate-home> bin/fm-control.sh <task-id> interrupt, then redirect …
- Very specific: line 77
If the crewmate is genuinely wedged after redirection, relaunch it with FM_HOME=<this-firstmate-home> bin/fm-control.sh <task-id> relaunch …
- Very specific: line 82
If a second relaunch fails too, write failed to the backlog and tell the captain the plain failure, preserved work, and consequence using …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
stuck-crewmate-recovery
Use this playbook when the session-start digest reports an ordinary direct report's endpoint dead or its metadata has no window, or when a direct report is stale, looping, repeatedly confused, asking a question its brief already answers, unresponsive, or when a steer failed to land.
A stale or dead-endpoint report for a worker whose pull request has already landed is not a recovery case: the work is finished, so close the task through ordinary teardown (AGENTS.md section 7 for firstmate, the landed-work rule in bin/fm-branch-prompt.sh for the supervision branch) instead of this playbook, never with --force.
Follow the crew-hosted Lavish board contract in docs/configuration.md when recovering a worker that hosts a board.
Interrupt, stop, and relaunch a worker through bin/fm-control.sh <task-id> interrupt|exit|relaunch, which resolves the recorded runtime itself, verifies each action, and never tears down or discards anything (docs/agent-control.md).
That plane covers workers running in this home; a remotely placed secondmate is refused by name and reconciled through secondmate-provisioning instead.
Load harness-adapters before a resume command or a harness-specific skill invocation, and whenever the adapter's own quirks matter.
The target window's harness is recorded as harness= in state/<id>.meta.
Session-start reconciliation for a dead ordinary direct report
This procedure covers ordinary kind=ship and kind=scout direct reports.
Load secondmate-provisioning instead for kind=secondmate recovery.
For a REMOTE secondmate, fm-crew-state and fm-peek read the actual remote endpoint over fm-on.sh, and fm-send reports a delivered-with-pending-confirmation steer as delivered (their headers own the contracts); an unknown-remote read or unreachable-host failure means the remote state could not be read, never that the mate is dead or the send failed.
Recover a genuinely stuck remote mate only through bin/fm-spawn.sh <id> --secondmate, never raw herdr pane close/kill surgery, which strands the endpoint binding.
Treat the digest's endpoint result as a presence signal, not proof that the task's work or validation run is gone.
Read the targeted current state with bin/fm-crew-state.sh <id> before deciding to relaunch.
A no-mistakes run matched to the crew's branch and current code remains authoritative when the endpoint is dead: handle a terminal or parked run through the normal lifecycle, and keep supervising an active run instead of creating a duplicate worker.
When no authoritative run accounts for the task, inspect only its recorded backend and worktree inventory.
Use treehouse status for treehouse-backed tmux, herdr, zellij, or cmux tasks, and use the recorded orca_worktree_id= and terminal= for Orca tasks.
Do not sweep another home's endpoints or infer ownership from a matching window label.
Before relaunch, prove that no live agent still owns the recorded task and that the existing worktree remains available.
Preserve its uncommitted changes and commits, keep the same task identity, and resume or relaunch the recorded harness in that existing worktree with the same brief plus a concise progress note.
A HERDR endpoint that is not merely idle but destroyed - a pane or workspace removed in Herdr churn - is recovered by that same relaunch, which creates one fresh endpoint in the existing worktree and rebinds the task's record to it; nothing special is needed, and the worktree is untouched (docs/agent-control.md "Reclaiming a task whose endpoint is gone").
That relaunch proves the endpoint is destroyed before it rebinds, so a Herdr server that was merely stopped is adopted back rather than duplicated.
On tmux there is no reclaim: a task record carries no socket identity for its endpoint, so a missing window cannot be told apart from one on a tmux server this seat cannot address, and both exit and relaunch refuse.
Do not work around either refusal by respawning - it means a live agent may still hold that worktree.
That reclaim is the owning home's operation only, and a secondmate is the one exception: recover it through bin/fm-spawn.sh <id> --secondmate as above.
Do not use a fresh generic spawn while the recorded worktree is unaccounted for, because allocating another worktree can split one task across two copies.
If the worktree or ownership cannot be reconciled safely, leave all state intact and report the task failed or blocked with the conflicting evidence.
A live crewmate claiming the pipeline is dead
This is the inverse of the dead-endpoint case above: the worker is alive and the pipeline it declares dead usually is too. A drive call blocks until the next gate or outcome, far longer than a harness lets one command run, and the daemon accepts a response immediately and runs the round in the background. So a crewmate's timed-out, killed, or errored drive call leaves it waiting on a read it never got, and the "the daemon is gone" conclusion it draws from that is a guess, not evidence.
Read the two authoritative sources yourself before believing the claim:
no-mistakes daemon statusfor the socket.no-mistakes axi status --run <id>for the run, orbin/fm-crew-state.sh <id>, which already folds this contradiction in and reports a non-socket daemon-or-timeoutblocked:line over a running or fixing run with fresh activity as superseded because the run is alive.
A refused connection or missing socket from daemon status is positive daemon-down evidence and must be escalated even if the persisted run record still says running or fixing; that record can be stale after the daemon exits.
Otherwise, if the run is still running or fixing with recent activity, the claim is wrong: steer the crewmate to reattach with no-mistakes axi run from its own worktree, which is safe and idempotent while the run still matches its HEAD, and tell it a timeout is not daemon death.
Nothing reaches the captain in that case.
Never restart, stop, or update the shared daemon on a crewmate's claim. It is one instance serving every lane and home, so a restart kills other lanes' in-flight runs. Only positive socket refusal or absence is a daemon-down finding; escalate that finding, or a failed run record that names a daemon error, to the captain.
Live-endpoint escalation
Escalate in order:
- Peek the pane, and check the task's steering inbox (
state/<id>.inbox/) for unhandled*.msgrecords - a stale wake naming an unread firstmate instruction means the worker never acknowledged a durable steer, and the record itself shows exactly what was intended. - If the crewmate is waiting on a question its brief already answers, answer in one line via
FM_HOME=<this-firstmate-home> bin/fm-send.shfrom an active firstmate session unlessFM_HOMEis already set to the active firstmate home. - If the crewmate is confused or looping, interrupt with
FM_HOME=<this-firstmate-home> bin/fm-control.sh <task-id> interrupt, then redirect with one corrective line throughfm-send. - If the crewmate is genuinely wedged after redirection, relaunch it with
FM_HOME=<this-firstmate-home> bin/fm-control.sh <task-id> relaunch --note '<progress so far>', which stops the agent, carries the brief plus that note into a replacement in the same local copy, and restores the prior record if the replacement cannot start. Pass--harness,--model, or--efforton that same command when the worker should come back on a different runtime. Genuine wedging means looping, unresponsive, repeating the same obstacle, or truly dead. A low context reading is not wedging; modern harnesses auto-compact and keep going. The worktree and commits persist, so relaunch is cheap. - If a second relaunch fails too, write
failedto the backlog and tell the captain the plain failure, preserved work, and consequence usingAGENTS.mdsection 9; do not mention metadata, harness, window, or worktree unless the path itself is needed for action.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

