feat: add Devin CLI harness support

[codeatspeed]

Intent

Add Devin CLI as a fully supported and empirically verified Firstmate harness alongside Claude Code, Codex, Pi, OpenCode, and Grok. Support primary sessions, crewmates, scouts, and secondmates with detection, unattended permission and workspace-trust handling, model selection, compositional task-local hooks that preserve repository Devin configuration and safety hooks, process liveness, bounded foreground supervision, dispatch validation, teardown cleanup, documentation, and regression coverage. Use conservative foreground checkpoints because Devin background completion auto-wake behavior has not been verified. Preserve all fixes from prior no-mistakes review, test, documentation, and lint rounds.

What Changed

Captain, this branch:

• Adds Devin CLI as a supported harness for primary sessions, crewmates, scouts, and secondmates, including detection, model selection, unattended launches, and liveness handling.
• Integrates Devin safety and turn-end hooks while preserving user and repository configuration, with bounded foreground checkpoint supervision.
• Documents Devin workflows and adds regression coverage for detection, spawning, configuration layering, hooks, supervision, and recovery behavior.

Risk Assessment

✅ Low: Captain, this is a bounded harness addition with documented config layering, consistent supervision behavior, cleanup and liveness integration, and focused regression coverage.

Testing

The successful full-suite baseline was supplemented with controlled CLI-level Devin validation covering detection, autonomous and trust-free spawning, model selection, task-hook composition without modifying user or repository configuration, safety-hook blocking, invalid-config recovery, foreground supervision, process liveness, and secondmate behavior; reviewer-visible transcripts were captured, no UI screenshot was applicable because this is a terminal-only integration, and all checks passed.

Evidence: Devin focused validation transcript

$ command -v devin
/Users/muralinunna/.local/bin/devin

$ bash tests/fm-devin-harness.test.sh
ok - fm-harness detects the verified Devin launch marker
ok - tracked Devin primary hooks wire both seatbelts and the turn-end guard
ok - tracked Devin PreToolUse adapter blocks unsafe watcher commands with stderr-only output
ok - fm-spawn composes user config with one task hook and leaves repository config native
ok - invalid Devin user configs leave endpoints and worktrees recoverable
ok - fm-lock recognizes Devin harness processes

$ bash tests/fm-supervision-instructions.test.sh
ok - renderer prints exactly the selected harness block
ok - renderer falls back to unknown.md for unverified harness names
ok - renderer includes read-only, afk, and effective x-mode current-state stanzas
ok - renderer repair-line mode is harness-aware and honors conditional state
ok - grok supervision is Claude-shaped background notify with passive Stop-hook backstop
ok - grok rendered command sources the effective x-mode config
ok - devin supervision uses bounded foreground checkpoints
ok - pi supervision snippet renders the effective extension path

$ bash tests/fm-secondmate-liveness.test.sh
ok - fm_backend_tmux_agent_alive: alive/dead/unknown classification
ok - fm_backend_herdr_agent_alive: dead/no-agent->dead, live->alive, unknown->unknown
ok - fm_backend_agent_alive: routes tmux/herdr correctly, unknown for an unverified backend
ok - sweep: a confirmed-dead secondmate endpoint is killed and respawned
ok - sweep: an already-live secondmate is left untouched (no kill, no respawn)
ok - sweep: a transient/unknown probe reading is reported but never acted on
ok - sweep: an unverified harness makes a dead-looking probe inconclusive
ok - sweep: idempotent by construction - a live secondmate is never re-touched on a later run
ok - sweep: skipped entirely under FM_BOOTSTRAP_DETECT_ONLY=1, exactly like the other mutating sweeps
ok - sweep: a silent no-op with no kind=secondmate meta present (a secondmate home's own natural scoping)
# all fm-secondmate-liveness tests passed

Evidence: Rendered Devin user-facing supervision and hook configuration

$ DEVIN_CLI=1 bin/fm-harness.sh
devin

$ FM_CODEX_WATCH_CHECKPOINT=7 bin/fm-supervision-instructions.sh --harness devin
================================================================================
SUPERVISION OPERATING INSTRUCTIONS - primary harness: devin
================================================================================
Current state:
- Lock: held by this session; this session owns normal supervision unless away mode says otherwise.
- Away mode: inactive.
- X mode: inactive; use the default watcher cadence.
- After every handled wake, resume this emitted harness protocol instead of following a hardcoded background-arm recipe.

Mode: Devin foreground checkpoint.

When this session owns supervision and away mode is not active:
1. Drain first with `bin/fm-wake-drain.sh`.
2. Source `/Users/muralinunna/.no-mistakes/worktrees/7a17be65de34/01KXF7YEPHGNP1MSHEVT0G6BAH/config/x-mode.env` first when X mode is active.
3. Run `bin/fm-watch-checkpoint.sh --seconds 7` as one foreground tool call.
4. Never bundle the checkpoint with unrelated commands.
5. Never use shell `&` for watcher supervision.
   A shell `&`, a truncating pipe, or bundling is denied automatically by the PreToolUse seatbelt registered in `.devin/config.json`.
6. When the checkpoint returns with `signal:`, `stale:`, `check:`, or `heartbeat`, drain queued wakes, handle them, then run one fresh checkpoint.
7. A timeout is only a bounded control return.
   If work remains in flight, run another checkpoint after handling user input and queued wakes.
8. Treat any failed checkpoint as an alarm and repair it before ending the turn.
9. Do not send idle progress while a checkpoint is running.

Devin has no verified background-task completion wake contract in Firstmate.
The bounded foreground checkpoint is the conservative supported mechanism, matching Codex's supervision shape while retaining Devin's native blocking Stop-hook backstop.


$ jq primary Devin hook summary
{
  "pretool_matcher": "exec",
  "pretool_commands": [
    "bash -lc 'root=$(pwd -P); [ -f \"$root/.devin/config.json\" ] && [ -x \"$root/bin/fm-arm-pretool-check.sh\" ] || exit 0; exec \"$root/bin/fm-arm-pretool-check.sh\" --claude'",
    "bash -lc 'root=$(pwd -P); [ -f \"$root/.devin/config.json\" ] && [ -x \"$root/bin/fm-cd-pretool-check.sh\" ] || exit 0; exec \"$root/bin/fm-cd-pretool-check.sh\" --claude'"
  ],
  "stop_command": "bash -lc 'root=$(pwd -P); [ -f \"$root/.devin/config.json\" ] && [ -x \"$root/bin/fm-turnend-guard.sh\" ] || exit 0; exec \"$root/bin/fm-turnend-guard.sh\"'"
}

- Outcome: 🔧 1 issue found → auto-fixed (2) ✅ across 3 runs (58m2s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

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

• 🚨 bin/fm-spawn.sh:1057 - Captain, devin --config overrides Devin’s user configuration, but the generated task config contains only the repository config plus Firstmate’s Stop hook. Every Devin crewmate can therefore lose user-level settings/hooks, while the repository config may also be applied twice because Devin loads it automatically. Confirm the CLI’s layering behavior and preserve both native config layers without duplication before merging.

🔧 Fix: Captain, preserve Devin config layering
1 warning still open:

• ⚠️ docs/supervision-protocols/devin.md:6 - The Devin session-start protocol hardcodes a 180-second checkpoint, while Devin's repair path uses FM_CODEX_WATCH_CHECKPOINT. When overridden, the same session receives contradictory supervision commands. Parameterize the rendered Devin snippet like Codex, or introduce a Devin-specific setting and use it consistently.

🔧 Fix: Captain, align Devin checkpoint override rendering
✅ Re-checked - no issues remain.

🔧 **Test** - 1 issue found → auto-fixed (2) ✅

• 🚨 tests failed with exit code 1
• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"

🔧 Fix: Captain, preserve Herdr lab failure status
1 error still open:

• 🚨 tests failed with exit code 1
• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"

🔧 Fix: Captain, release watcher lock on checkpoint timeout
✅ Re-checked - no issues remain.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• Baseline previously passed: command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"
• command -v devin
• bash tests/fm-devin-harness.test.sh
• bash tests/fm-supervision-instructions.test.sh
• bash tests/fm-secondmate-liveness.test.sh
• DEVIN_CLI=1 bin/fm-harness.sh
• FM_CODEX_WATCH_CHECKPOINT=7 bin/fm-supervision-instructions.sh --harness devin
• Inspected primary Devin hook wiring with jq against .devin/config.json
• git status --short

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 127)

🔧 Fix: Captain: verify clean ShellCheck lint
1 warning still open:

• ⚠️ linter found issues (exit code 127)

🔧 Fix: Captain, ShellCheck unavailable; no source changes made
1 warning still open:

• ⚠️ linter found issues (exit code 127)

🔧 Fix: Captain: lint blocked by missing ShellCheck 0.11.0
1 warning still open:

• ⚠️ linter found issues (exit code 127)

✅ **Push** - passed

✅ No issues found.