cyberfleet 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberfleet",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Harness-agnostic, MCP-free inter-agent sessions and messaging over the filesystem",
   "keywords": [
     "agent",
@@ -38,7 +38,8 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "commander": "^15.0.0",
-    "cyberlegion": "^1.0.0",
+    "cyber-mux": "^0.12.0",
+    "cyberlegion": "^1.7.0",
     "tsdown": "^0.23.0",
     "tsx": "^4.22.3",
     "typescript": "^7.0.0",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "cyberfleet",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"description": "Fleet & crew personas over cyberlegion — Pod (ship's bridge), Operator (command center), Crimp (crew recruitment), and Mechanic (automaton building).",
 	"author": {
 		"name": "unional"

package/readme.md

@@ -26,8 +26,8 @@ npx cyberfleet@0.0.4 <command>
 npx cyberfleet missions
 npx cyberfleet missions --agents-root <path>
 
-# Select/focus a ship's session (tmux pane), or print its worktree path to cd into
-npx cyberfleet jump <peer>
+# Focus the one live unit a repo, branch, unit, or task names, or go back along the last jump
+npx cyberfleet jump <target> [--repo <name>] [--branch <name>]... [--mentions <n>]
 
 # Pause a ship's mission — a cyberfleet-level status marker only (NOT the SDD pause-mission checkpoint)
 npx cyberfleet pause <peer>
@@ -112,7 +112,8 @@ Under the automatons sit two CLIs — cold, deterministic mechanism with no judg
 **`cyberfleet`** is the thin fleet layer on top, and carries only what is fleet-specific:
 
 - `missions` — the Council view: ships × mission × gate × leash, derived from SDD state
-- `jump` — focus a ship's pane, or print its worktree path to `cd` into
+- `jump` — focus the one live unit a repo, branch, unit, or task names, or go `back`; on several
+  matches, a task ref, or free text it focuses nothing and returns what the `/jump` skill decides
 - `pause` — mark a ship's mission paused (a status marker only, not an SDD mission checkpoint)
 - `gate approve` — deliberately stubbed: a Council ratification can't be safely relayed through a
   CLI, so it refuses and tells you to ratify in-session

package/skills/close-sessions/README.md

@@ -0,0 +1,37 @@
+# close-sessions
+
+A mechanical sweep that closes every agent session whose work has landed, and keeps every session
+that might still have work. It has no persona and no judgment step, so it runs on a low-tier model.
+
+## When to use
+
+- The Council asks to close finished agent sessions, panes, or pods, clean up idle sessions, or tidy the fleet.
+
+Not for marking dead records only: that is `cyberlegion unit prune`, which this skill runs first. Not
+for retiring a pod's record: that belongs to the pod's Captain (`cyberfleet pod retire`).
+
+## What it does
+
+- Reads every unit with `cyberlegion unit who --all --format json`, and acts only on units in the
+  caller's current multiplexer session (records do not yet store the multiplexer session, cyberuni/cyberlegion#241, so
+  units whose pane `mux` matches the caller's). Other units are kept, since another session may resume them.
+- Fetches pull requests once per repository and matches branches locally, instead of one `gh` call per unit.
+- Classifies each unit by its worktree and its branch's pull requests. A unit is closable only when
+  every pull request from its branch is merged or closed and its `HEAD` is contained in a pull
+  request's head commit. Mechanical evidence decides first. A unit whose worktree was deleted is
+  closed only once its session has exited.
+- Lists a landed unit with leftover uncommitted files separately, with the files, and closes it
+  (discarding them) only when the Council names it.
+- Asks each live unit that passes the mechanical close one question by mail: "Do you have unfinished
+  work? Reply DONE or UNFINISHED: <reason>". A unit the multiplexer shows working is kept without
+  asking. UNFINISHED or no reply keeps the unit, with the reason listed. A reply never closes a unit
+  the evidence keeps. It never types into a pane or reads its screen, and needs no transcript or hook.
+- Keeps this session, standing owners, units with no worktree, and every session in a main
+  checkout (Captain, Coordinator, Operator, the Council's desk).
+- Shows the Council the close, ask, and keep groups, and asks about the close and ask groups
+  separately before closing anything.
+- Closes each confirmed unit with `cyberlegion unit close <id>`, adding `--force` only for a confirmed
+  unit with leftover files.
+
+This is the interim home for the sweep. The planned design moves the close into the Coordinator, at the
+moment a unit's last pull request lands, and leaves this sweep for the leftovers.

package/skills/close-sessions/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: close-sessions
+description: "Use this skill when the Council asks to close finished agent sessions, panes, or pods, clean up idle sessions, or tidy the fleet — it closes each unit whose worktree branch has landed and keeps everything else. Not for sweeping dead records only (`cyberlegion unit prune`), and not for retiring a Captain's pod record."
+model: haiku
+---
+
+# Close sessions
+
+Close every agent session whose work has landed, and keep every session that might still have work.
+This is a mechanical sweep: each step below is a command and a rule. The one question to a unit is
+mail, and its answer can only keep the unit.
+
+A unit is closable only when **all** of its work is visible on the host as finished: every pull
+request from its branch is merged or closed, and none of its commits are missing from those pull
+requests. Mechanical evidence always decides first; nothing a unit says can close one the evidence keeps.
+A live unit that passes that evidence is then asked one question (step 4), because the unit is the best
+judge of whether it has unfinished work. A unit whose work landed but whose worktree still has
+uncommitted files is shown to the Council with those files, and closed only if the Council says so.
+When a check cannot be run or reads unclear, keep the unit. Closing destroys the session, its inbox,
+and its worktree, and cannot be undone. Keeping a finished unit only costs a pane.
+
+Act only on units in the caller's current multiplexer session. Another session or multiplexer may
+resume those agents, and this skill cannot know.
+
+## 1. Resolve `cyberlegion`
+
+Take the first rung that resolves and whose `cyberlegion --version` is `1.6.0` or later:
+
+1. `cyberlegion` on `PATH`.
+2. The installed cyberlegion plugin: read `~/.claude/plugins/installed_plugins.json`, take the
+   `installPath` of its `cyberlegion@<marketplace>` entry, and run `node <installPath>/bin/cyberlegion.mjs`.
+3. `npx -y cyberlegion@1.6.0`.
+
+When no rung resolves, stop and tell the Council to install the `cyberlegion` plugin.
+
+## 2. Read the fleet
+
+1. `cyberlegion unit prune` marks units whose pane is gone as exited.
+2. `cyberlegion unit whoami` gives this session's own id and handle.
+3. Name the caller's multiplexer: `herdr` when `HERDR_ENV` is set, `tmux` when `TMUX` is set.
+   When neither is set, stop and tell the Council.
+4. `cyberlegion unit who --all --format json` lists every unit. Each record has `id`, `handle`,
+   `harness`, `status`, `cwd`, a pane, and `worktree` (`root` and `branch`). The pane is under `pane`
+   (`mux` and `id`), or, in records written by older versions, under the legacy `tmux` key. Read it from
+   whichever is present. The `conversation` field is optional, and this skill does not use it.
+5. Fetch pull requests once per repository, not once per unit. For each distinct repository among the
+   in-scope units, run inside one of its worktrees:
+   `gh pr list --state all --limit 1000 --json number,state,headRefOid,headRefName`.
+   Match each unit's branch to `headRefName` locally. Per-unit `gh` calls made a 400-unit sweep take
+   about 7 minutes.
+6. When the caller's multiplexer is `herdr`, read each live in-scope pane's state once, with
+   `herdr pane list` (or `herdr pane get <pane id>`). It reports `agent_status` from metadata. Never read a pane's screen.
+
+## 3. Classify each unit
+
+Apply these rules in order to each unit. The first rule that matches decides it.
+
+| # | Check | Result |
+| - | ----- | ------ |
+| 1 | `id` is this session's own id | keep: this session |
+| 2 | It is a standing owner (no pane, and no `harness` field or `harness` is `-`) | keep: standing owner |
+| 3 | Its pane is absent, or its `mux` (or legacy `tmux` key) is not the caller's multiplexer | keep: out of scope |
+| 4 | It has no `worktree` | keep: no worktree |
+| 5 | `worktree.root` does not exist on disk, and `status` is not `exited` | keep: worktree gone, session live |
+| 6 | `worktree.root` does not exist on disk, and `status` is `exited` | close: worktree gone, session ended |
+| 7 | Either `git -C <root> rev-parse --git-dir` or `git -C <root> rev-parse --git-common-dir` fails | keep: cannot read worktree |
+| 8 | Those two commands print the same path | keep: primary checkout |
+| 9 | The repository's pull request list (step 2.5) failed to load | keep: cannot read pull requests |
+| 10 | No pull request in that list has `headRefName` equal to the branch | keep: no pull request yet |
+| 11 | Any matching pull request has state `OPEN` | keep: pull request open |
+| 12 | `git -C <root> merge-base --is-ancestor HEAD <headRefOid>` exits non-zero for every matching pull request | keep: commits after the last pull request |
+| 13 | `git -C <root> status --porcelain --untracked-files=all` prints any line other than `?? .agents/cyberlegion/config.json` | ask: work landed, leftover files |
+| 14 | Anything else (every pull request is `MERGED` or `CLOSED`, `HEAD` is inside one of them, and the worktree is clean) | close: pull requests merged or closed |
+
+Rules 5 and 6 handle a worktree that was deleted from disk. Nothing is left on disk to check, so
+the session's own state decides: a live session may still be in use, and an exited one has nothing
+left to lose.
+
+Rule 3 is the scope rule. Records do not yet store the multiplexer session (cyberuni/cyberlegion#241),
+so scope is the multiplexer kind. A record with no pane, or with only the legacy `tmux` key while the caller is
+on herdr, is out of scope. herdr restores panes with the same ids and resumes Claude itself, so a
+unit on another herdr session may come back.
+
+Rule 8 keeps every session in a project's main checkout: a Captain, a Coordinator, the Operator, or
+the Council's own desk. Those are standing seats, not spawned units, so this skill never closes one.
+
+Rule 13 catches a unit whose work landed but left files behind: build output, scratch files, an edit it
+never committed. Those are often safe to drop, but only the Council can say, so the unit is listed
+with its files and closed only on the Council's word. The one line it skips is the marker cyberlegion
+stamps into every worktree it spawns; `cyberlegion unit close` sets that file aside too, so it never
+counts as leftover work.
+
+Rule 12 is the unpushed-work check. It compares the local `HEAD` with each pull request's head commit
+rather than with the remote branch, because the host usually deletes a branch once its pull request
+merges. One pull request containing `HEAD` is enough. A head commit missing locally makes that
+command exit non-zero; it counts like any other non-zero exit.
+
+Do not retry a failed command. A failure keeps the unit, and the next sweep checks it again.
+
+A held merge always keeps its unit, because a held pull request is still open (rule 11).
+
+`stopped` is not `exited`. A stopped unit was kept on purpose so it can be restarted.
+
+## 4. Ask the live units
+
+An **exited** unit's step-3 result stands: its session ended, so there is nobody to ask.
+
+For each **live** unit (`status` is not `exited`) that step 3 put in **close**:
+
+1. When the multiplexer shows it working, keep it: **keep: working**. On herdr that is `agent_status`
+   `working` or `blocked`. Skip the question.
+2. Otherwise mail it one structured question on a fresh thread:
+
+   ```sh
+   cyberlegion mail send --to <id> --thread close-<id>-<timestamp> --subject "Closing?" \
+     --body "Do you have unfinished work? Reply with: cyberlegion mail send --to <caller handle> --thread <thread> --body 'DONE' (or --body 'UNFINISHED: <reason>')"
+   ```
+
+   `<caller handle>` is the handle from `unit whoami`, and `<thread>` is the same thread id. A reply
+   sent without that thread never matches the wait.
+
+   Send the questions to all such units first. Then wait on each thread with
+   `cyberlegion mail await --thread <thread> --timeout <ms>`, giving each the remaining share of a
+   total budget of about 2 minutes (120000 ms), not 2 minutes per unit. `await` prints the reply and acks
+   it; it exits non-zero on timeout.
+3. Read the reply:
+   - `DONE` → the unit stays in **close**.
+   - `UNFINISHED: <reason>` → **keep: unit reports unfinished work**, and show the reason.
+   - No reply in time, or a reply that is neither → **keep: no answer**.
+
+A reply can only keep a unit. It never moves a unit from keep to close, and never overrides
+rule 13: a live unit that passed the mechanical close but has leftover files stays in **ask**, and is
+not mailed.
+
+Never type into a pane or read its screen. The mail is the only way this skill talks to a unit.
+
+## 5. Confirm with the Council
+
+Show the units in three groups: **close**, **ask**, then **keep**. Each row gives the unit id, the
+handle, the branch, the result, and the pull request numbers. Handles are not unique, so the id is what
+identifies a unit. Under each ask row, show what the Council needs to decide:
+
+- for leftover files (rule 13): the lines rule 13 counted, the first 10, then how many more;
+
+Then ask two questions, in this order:
+
+1. "Close these N units?" for the close group.
+2. "These M units have leftover files, listed above. Closing one deletes its worktree with those
+   files. Which should I close?"
+
+The Council may drop units from either list. A yes to the first question never covers the ask group.
+Close only the units the Council's answer names or covers. If an answer names a handle that more than
+one candidate shares, ask which id it means. If an answer is not a yes, close nothing from that group.
+
+## 6. Close
+
+For each confirmed unit, run `cyberlegion unit close <id>`. Add `--force` only for a unit that rule 13
+put in ask, which discards its leftover files.
+
+- Pass `--force` only for a rule-13 unit the Council confirmed in answer to the second question.
+  Never pass `--keep-worktree`.
+- If a close refuses (for example, a close-group worktree that became dirty since step 3), report the
+  refusal and move on. Do not retry it, add `--force`, or reach around it.
+- Never run `cyberfleet pod retire`. A pod's record belongs to its Captain, who retires it.
+- Mail a unit only with the step-4 question. Never type into a pane or read its screen.
+
+## 7. Report
+
+Lead with the count closed and the count kept (an ask-group unit the Council did not confirm counts as
+kept). List the closed handles. Then list the kept units grouped by result, so the Council can see which
+ones are waiting on a pull request, which reported unfinished work (with the reason), and which are
+out of scope.

package/skills/crimp/SKILL.md

@@ -50,7 +50,7 @@ and never re-implements the fleet registry — it only invokes them.
 Every `cyberlegion …` command in this skill runs whichever CLI resolves below, resolved afresh in each
 session and again after any plugin reload. Never hardcode a versioned
 `~/.claude/plugins/cache/…/<version>/` path: a reload installs a new version beside the old one, and a
-remembered path keeps running the old CLI. The pin is `1.1.0`. Take the first rung that
+remembered path keeps running the old CLI. The pin is `1.7.0`. Take the first rung that
 resolves and whose `cyberlegion --version` is at or above it; skip a rung that reports an older
 version:
 
@@ -58,11 +58,11 @@ version:
 2. The installed cyberlegion plugin: read `~/.claude/plugins/installed_plugins.json` now, take the
    `installPath` of its `cyberlegion@<marketplace>` entry, and run `node
    <installPath>/bin/cyberlegion.mjs`.
-3. `npx -y cyberlegion@1.1.0`.
+3. `npx -y cyberlegion@1.7.0`.
 
 When no rung resolves, stop and report it to the Council with the
 install hint: install the `cyberlegion` plugin beside this one, or `npm install -g
-cyberlegion@1.1.0`.
+cyberlegion@1.7.0`.
 
 ## Output
 

package/skills/jump/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: jump
+description: "Moves the attached view to the one pane working on a repo, a branch, a pod, a GitHub issue or pull request (`#123`, `color-map#123`), or a task described in words, and back along the last jump. Use when the Council runs /jump, or asks to go to, switch to, or show the pane working on one of these, or to go back to the pane the last jump came from (`/jump back`). Not for opening a new pane or spawning a pod, and not for messaging a unit."
+argument-hint: "[repo|branch|pod|task|back|<prose>]"
+---
+
+# Jump
+
+Move the attached view to the one pane working on what the argument names, or back along the last
+jump. `cyberfleet jump` does the matching and the focusing. This skill does the two steps the
+command leaves to it: the GitHub lookup for a task ref, and matching free text to a unit.
+
+The one rule above all others: **more than one match lists the candidates and stops.** Never pick
+one, not even the newest or the most likely.
+
+## Running `cyberfleet`
+
+This plugin ships the `cyberfleet` CLI, so its version always matches this skill. Run it from this
+skill's directory, with no install:
+
+```bash
+node <this skill's directory>/../../bin/cyberfleet.mjs jump <argument>
+```
+
+Every `cyberfleet jump …` below means that command. Add `--format json` to read the result as JSON;
+its `result` field names the kind.
+
+## 1. Run `cyberfleet jump <argument>`
+
+Claude Code appends the argument as `ARGUMENTS: <value>`; other runtimes pass the text after the
+skill name. With no argument, ask the Council where to jump and stop.
+
+Pass the argument as it came, quoted as one value. The command prints one result:
+
+| `result` | What it means | Next |
+| -------- | ------------- | ---- |
+| `jumped` | It focused one unit: its `id`, `handle`, and `pane` (`back` also gives `from`). | Step 4 |
+| `candidates` | More than one unit matched. Nothing was focused. | Step 4 |
+| `task` | A task ref: its `repo` name, `slug` (`<owner>/<repo>` from that checkout's `origin`), and `number`. Nothing was focused. | Step 2 |
+| `prose` | No exact match: the `words`, and the live units with `id`, `handle`, `branch`, `repo`, and `brief` (a path). Nothing was focused. | Step 3 |
+
+A non-zero exit is an error. Go to step 4 with it.
+
+The command already applies these rules, so do not repeat them by hand: it never focuses this
+session or lists it, it jumps past this session when this session was one of the matches, a bare
+word must exactly equal a unit's id, handle, branch, or repo name, and `back` follows the jump
+history for this pane.
+
+## 2. On `task`, look up the branches with `gh`
+
+A task is a GitHub issue or pull request; one number names exactly one of them. This step needs an
+authenticated `gh`. When `gh` is missing or not logged in, quote its error and stop.
+
+1. **Read what the number is.** `gh api repos/<slug>/issues/<number> --jq '.pull_request != null'`
+   prints `true` for a pull request and `false` for an issue. If it fails, quote the error and stop.
+2. **Find the branches.**
+   - A pull request: `gh pr view <number> -R <slug> --json headRefName --jq .headRefName`.
+   - An issue: `gh issue view <number> -R <slug> --json closedByPullRequestsReferences` lists the
+     linked pull requests. Read each one's `headRefName` as above, in that pull request's own
+     repository. An issue with no linked pull request has no branches.
+3. **Focus.** Run `cyberfleet jump --repo <repo> --branch <b>... --mentions <number>`, one `--branch`
+   per branch found, with the `repo` the `task` result gave. When no branch has a live unit,
+   `--mentions` falls back to a unit whose handle or brief names the number. Go to step 4 with what
+   it prints.
+
+## 3. On `prose`, match the words to one unit
+
+Match the `words` against each listed unit's handle, branch, repo name, and brief (read the brief
+file when the unit has one). A match is a unit the words plainly describe, not one they could be
+stretched to fit.
+
+- Exactly one: run `cyberfleet jump <id>` with that unit's id, and go to step 4 with what it prints.
+- More than one plausible unit: list them and stop.
+- None: say no live unit matches, and list the units so the Council can name one.
+
+## 4. Report the result
+
+- `jumped`: one line naming the unit's handle and id and the pane, then that `/jump back` returns.
+  After a `back` with no unit at the pane, name the pane alone.
+- `candidates`: one row per unit with its id, handle, branch, and repo name, then a line saying the
+  Council can narrow the argument (a repo, a branch, or an id). Do not jump.
+- An error: quote the command's error verbatim with its exit code. Do not retry with other flags,
+  prune, or reach the pane any other way.
+
+`/jump back` waits for this session's turn. When the Council uses `back` often, mention the tmux key
+(prefix+B) that cyber-mux's `setup-tmux` binds to `focus --back`.
+
+## Validate
+
+Before reporting, check the result against what the commands printed:
+
+- A reported jump comes from a `jumped` result, and names the `id`, `handle`, and `pane` it gave.
+- Every `cyberfleet jump` run after the first took an id from a result, or `--repo` with the
+  branches `gh` returned. None took a handle, and none was guessed.
+- A candidates report has at least two rows, each a unit from the `candidates` or `prose` result,
+  and no `cyberfleet jump` ran after the candidates were collected.
+- An error report quotes the command's error and exit code, and no other command ran after it.

package/skills/operator/SKILL.md

@@ -150,7 +150,7 @@ the Council's words with `unit nudge --message`, never reaches for an MCP messag
 Every `cyberlegion …` command in this skill runs whichever CLI resolves below, resolved afresh in each
 session and again after any plugin reload. Never hardcode a versioned
 `~/.claude/plugins/cache/…/<version>/` path: a reload installs a new version beside the old one, and a
-remembered path keeps running the old CLI. The pin is `1.1.0`. Take the first rung that
+remembered path keeps running the old CLI. The pin is `1.7.0`. Take the first rung that
 resolves and whose `cyberlegion --version` is at or above it; skip a rung that reports an older
 version:
 
@@ -158,11 +158,11 @@ version:
 2. The installed cyberlegion plugin: read `~/.claude/plugins/installed_plugins.json` now, take the
    `installPath` of its `cyberlegion@<marketplace>` entry, and run `node
    <installPath>/bin/cyberlegion.mjs`.
-3. `npx -y cyberlegion@1.1.0`.
+3. `npx -y cyberlegion@1.7.0`.
 
 When no rung resolves, stop and report it to the Council with the
 install hint: install the `cyberlegion` plugin beside this one, or `npm install -g
-cyberlegion@1.1.0`.
+cyberlegion@1.7.0`.
 
 ## Headless — the lifecycle loop
 

package/skills/pod/SKILL.md

@@ -153,7 +153,7 @@ leash state itself.
 Every `cyberlegion …` command in this skill runs whichever CLI resolves below, resolved afresh in each
 session and again after any plugin reload. Never hardcode a versioned
 `~/.claude/plugins/cache/…/<version>/` path: a reload installs a new version beside the old one, and a
-remembered path keeps running the old CLI. The pin is `1.1.0`. Take the first rung that
+remembered path keeps running the old CLI. The pin is `1.7.0`. Take the first rung that
 resolves and whose `cyberlegion --version` is at or above it; skip a rung that reports an older
 version:
 
@@ -161,11 +161,11 @@ version:
 2. The installed cyberlegion plugin: read `~/.claude/plugins/installed_plugins.json` now, take the
    `installPath` of its `cyberlegion@<marketplace>` entry, and run `node
    <installPath>/bin/cyberlegion.mjs`.
-3. `npx -y cyberlegion@1.1.0`.
+3. `npx -y cyberlegion@1.7.0`.
 
 When no rung resolves, stop and report it to the Council with the
 install hint: install the `cyberlegion` plugin beside this one, or `npm install -g
-cyberlegion@1.1.0`.
+cyberlegion@1.7.0`.
 
 ## Output