Skip to content

feat: adopt existing cmux workspaces for supervision#261

Open
ss251 wants to merge 6 commits into
kunchenguid:mainfrom
ss251:fm/adopt-existing-session
Open

feat: adopt existing cmux workspaces for supervision#261
ss251 wants to merge 6 commits into
kunchenguid:mainfrom
ss251:fm/adopt-existing-session

Conversation

@ss251

@ss251 ss251 commented Jul 5, 2026

Copy link
Copy Markdown

Intent

Add an fm-adopt command so firstmate can supervise an already-running cmux workspace (kind=adopted) without spawning a new worktree or branch; peek/send/watcher work on it and teardown un-registers it without ever closing the workspace. Implements issue #260. cmux-only, experimental, supervise-only.

What Changed

  • Added bin/fm-adopt.sh and tests for registering an existing cmux workspace as kind=adopted so firstmate can supervise it without spawning a new worktree, branch, or process.
  • Wired adopted cmux targets into session-start, crew-state, watcher, backend, and teardown paths, including duplicate-window protection and liveness checks that do not depend on readable screen output.
  • Documented the adopted-session workflow and constraints across the operator docs, script reference, architecture/configuration notes, and cmux backend guide.

Risk Assessment

✅ Low: Captain, the change is scoped to cmux adoption paths and the shared watch/peek/send/teardown integrations look consistent with the intended supervise-only behavior.

Testing

  • ⏭️ Test - skipped

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 2 issues found → auto-fixed ✅
  • ⚠️ bin/fm-adopt.sh:79 - fm-adopt only rejects an existing task id, but it never rejects an existing window=<workspace>:<surface> already registered under another id. The watcher and window_to_task resolve a window to the first matching meta file, so double-adopting a surface or adopting a firstmate-spawned cmux task can make stale handling, peek/send ownership, and teardown bookkeeping attach to the wrong task or skip stale wakes entirely. After resolving T, scan state/*.meta for the same window= and refuse it.
  • ⚠️ bin/fm-adopt.sh:98 - Adoption accepts a live cmux surface based on list-panes, but fm-crew-state.sh later treats non-tmux liveness as fm_backend_capture, which for cmux calls read-screen. The cmux adapter documents that read-screen fails on fresh never-written surfaces, so an adopted live workspace can immediately report backend target gone. Use fm_backend_target_exists for the adopted cmux liveness probe before falling through to busy/log classification.

🔧 Fix: Harden adopted cmux supervision
✅ Re-checked - no issues remain.

⏭️ **Test** - skipped

Step was skipped.

✅ **Document** - passed

✅ No issues found.

⏭️ **Lint** - skipped

Step was skipped.

✅ **Push** - passed

✅ No issues found.

ss251 added 6 commits July 5, 2026 05:08
Register an already-running cmux workspace as a kind=adopted task with
no worktree and no branch. Teardown un-registers without ever closing
the workspace, the watcher exempts it from stale-pane wakes, and
peek/send target it by pure UUID so the human's title is preserved.
cmux-only and experimental; supervise-only (no delivery mode or PR).

Refs kunchenguid#260
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant