cyberfleet 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberfleet",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Harness-agnostic, MCP-free inter-agent sessions and messaging over the filesystem",
   "keywords": [
     "agent",
@@ -38,7 +38,7 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "commander": "^15.0.0",
-    "cyberlegion": "^1.0.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.7.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/skills/close-sessions/README.md

@@ -0,0 +1,32 @@
+# 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`.
+- 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. 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.
+- Reads each close candidate's Claude Code transcript. A unit active in the last hour is kept. A unit
+  the Council typed into is listed with its last exchange and closed only when the Council names it,
+  so a conversation still in progress is never cut off.
+- 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,166 @@
+---
+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, with no judgment call in it.
+
+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. 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. So is a unit the Council was talking
+with, since that conversation may not be finished. 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.
+
+## 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.
+3. `cyberlegion unit who --all --format json` lists every unit. Each record has `id`, `handle`,
+   `harness`, `status`, `pane`, `cwd`, `conversation`, and `worktree` (`root` and `branch`).
+
+## 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 | It has no `worktree` | keep: no worktree |
+| 4 | `worktree.root` does not exist on disk, and `status` is not `exited` | keep: worktree gone, session live |
+| 5 | `worktree.root` does not exist on disk, and `status` is `exited` | close: worktree gone, session ended |
+| 6 | Either `git -C <root> rev-parse --git-dir` or `git -C <root> rev-parse --git-common-dir` fails | keep: cannot read worktree |
+| 7 | Those two commands print the same path | keep: primary checkout |
+| 8 | `gh pr list --head <branch> --state all --json number,state,headRefOid` fails, run inside `<root>` | keep: cannot read pull requests |
+| 9 | That list is empty | keep: no pull request yet |
+| 10 | Any pull request in it has state `OPEN` | keep: pull request open |
+| 11 | `git -C <root> merge-base --is-ancestor HEAD <headRefOid>` exits non-zero for every pull request in the list | keep: commits after the last pull request |
+| 12 | `git -C <root> status --porcelain --untracked-files=all` prints any line other than `?? .agents/cyberlegion/config.json` | ask: work landed, leftover files |
+| 13 | 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 4 and 5 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 7 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 12 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 11 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 10).
+
+## 4. Check the conversation
+
+A unit's pull requests can land while the Council is still talking with it: a question the unit asked
+is unanswered, or a decision lives only in its conversation. Closing ends that conversation. Run these
+checks on every unit that step 3 put in close or ask. The first rule that matches decides it.
+
+| # | Check | Result |
+| - | ----- | ------ |
+| C1 | `harness` is not `claude` | ask: conversation not checked |
+| C2 | No transcript is found (below), and `status` is `exited` | no change |
+| C3 | No transcript is found, and `status` is not `exited` | ask: conversation not found |
+| C4 | The transcript was modified in the last 60 minutes | keep: conversation active |
+| C5 | The Council-turns command (below) prints anything | ask: the Council talked to it |
+| C6 | Anything else | no change |
+
+**Find the transcript.** It is `~/.claude/projects/*/<conversation>.jsonl`, where `<conversation>` is
+the unit's `conversation` field. When the unit has no `conversation`, or that matches no file, no
+transcript is found. Do not substitute another file from the same folder: a worktree is reused by
+many units, so the newest transcript there often belongs to a different one.
+
+`stopped` is not `exited`. A stopped unit was kept on purpose so it can be restarted.
+
+**Council turns** are the turns a person typed into the session, apart from the spawn brief and the
+mail doorbell. A slash command the Council ran counts. Print them with:
+
+```sh
+jq -rR 'fromjson? | select(.type=="user" and .origin.kind=="human" and (.isMeta|not))
+  | .message.content
+  | if type=="string" then . else ([.[]? | select(.type=="text") | .text] | join(" ")) end
+  | select(length>0)
+  | select(startswith("Read your brief at")|not)
+  | select(startswith("You have unread mail")|not)
+  | .[0:200]' <transcript>
+```
+
+Print the unit's last reply with:
+
+```sh
+jq -rR 'fromjson? | select(.type=="assistant")
+  | [.message.content[]? | select(.type=="text") | .text] | join(" ")
+  | select(length>0)' <transcript> | tail -n 3
+```
+
+C2 lets an exited unit with no transcript keep its step-3 result: its session ended and no
+conversation is left on disk, so closing it loses nothing more. C4 keeps a unit that is working or
+being talked to right now. C5 sends every unit the Council spoke to back to the Council, because only
+the Council knows whether that conversation finished.
+
+## 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 12): the lines rule 12 counted, the first 10, then how many more;
+- for the Council talked to it (C5): its last 3 Council turns and the last 3 lines of its last reply.
+
+A unit can have both. Then ask two questions, in this order:
+
+1. "Close these N units?" for the close group.
+2. "These M units need your look before closing: their leftover files or their last exchange with
+   you are listed above. Closing one ends its conversation and deletes its worktree, with any
+   leftover 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 12
+put in ask, which discards its leftover files.
+
+- Pass `--force` only for a rule-12 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.
+- Never nudge, mail, or read the screen of a unit to decide whether it is finished.
+
+## 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, each with its transcript path when step 4 found one: closing does not
+delete the transcript, so the conversation can still be read. Then list the kept units
+grouped by result, so the Council can see which ones are waiting on a pull request and which ones are
+waiting on them.

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,144 @@
+---
+name: jump
+description: "Use this skill when the Council runs /jump, or asks to go to, switch to, or show the pane working on a repo, a branch, a pod, an issue or pull request (`#123`, `color-map#123`), or a task described in words — and 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. Every jump goes through the `cyberlegion` CLI, so cyber-mux records where the view came from
+and `back` can return there.
+
+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. A jump to the wrong pane interrupts the Council's
+attention in the wrong place, and the Council can always narrow the argument.
+
+## Resolving `cyberlegion`
+
+Every `cyberlegion …` command below runs whichever CLI resolves here, 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.7.0`, the first release with
+`unit focus --repo` and `--branch`. Take the first rung that resolves and whose
+`cyberlegion --version` is at or above it; skip a rung that reports an older version:
+
+1. `cyberlegion` on `PATH`.
+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.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.7.0`.
+
+## Resolving `cyber-mux`
+
+Only `back` needs `cyber-mux` directly; every other form reaches it through `cyberlegion`. Resolve it
+the same way, afresh each time. The pin is `0.11.0`, the first release with `focus --back`. Take the
+first rung that resolves and whose `cyber-mux --version` is at or above it:
+
+1. `cyber-mux` on `PATH`.
+2. The installed cyber-mux plugin: read `~/.claude/plugins/installed_plugins.json` now, take the
+   `installPath` of its `cyber-mux@<marketplace>` entry, and run `node <installPath>/bin/cyber-mux.mjs`.
+3. `npx -y cyber-mux@0.11.0`.
+
+When no rung resolves, stop and report it with the install hint: install the `cyber-mux` plugin, or
+`npm install -g cyber-mux@0.11.0`.
+
+## 1. Read the argument
+
+Claude Code appends it as `ARGUMENTS: <value>`; other runtimes pass the text after the skill name.
+With no argument, ask the Council where to jump and stop.
+
+The argument may start with a form word that forces the form: `repo <name>`, `branch <name>`,
+`pod <handle>`, or `task <ref>`. Use one when a bare argument was ambiguous across forms. Without
+one, decide the form in this order:
+
+| # | Argument | Form |
+| - | -------- | ---- |
+| 1 | exactly `back` | Back |
+| 2 | `#123`, `123`, or `<repo>#123` | Task |
+| 3 | one word that exactly equals a live unit's id, handle, branch, or repo name | Repo, branch, or pod |
+| 4 | anything else | Prose |
+
+## 2. Read the fleet
+
+Every form except Back starts from the same list:
+
+- `cyberlegion unit who --format json` lists the live units. Each record has `id`, `handle`,
+  `status`, `pane`, `cwd`, `brief` (a path to the unit's brief file, when it was spawned with one),
+  and `worktree` (`root`, `branch`, and `primaryRoot`).
+- A unit's **repo name** is the folder name of `worktree.primaryRoot`, or of `cwd` when it has no
+  `primaryRoot`. This is the rule `unit focus --repo` uses, so the skill and the CLI agree.
+- `cyberlegion unit whoami` gives this session's own id, when it has one. Leave this session out of
+  every candidate list the skill builds itself: a jump to the pane you are in does nothing.
+
+## 3. Jump
+
+### Back
+
+Run `cyber-mux focus --back` from this session's shell. It follows cyber-mux's record of the pane the
+last jump into this pane came from. Report its result. If it fails (for example, `no jump into <pane>`),
+quote the error and its next-step hint verbatim and stop; never jump somewhere else instead.
+
+`/jump back` waits for this session's turn, so in a busy agent's pane it is slow. The tmux key that
+cyber-mux's `setup-tmux` binds to `focus --back` is the fast path; mention it when the Council uses
+`back` often.
+
+### Repo, branch, or pod
+
+Collect the live units the word matches exactly, and note which field each matched:
+
+- repo name → `cyberlegion unit focus --repo <name>`
+- branch → `cyberlegion unit focus --branch <name>`
+- id or handle → the pod form: `cyberlegion unit focus <id>`, using the matched unit's id. Handles
+  are not unique, so never pass the handle itself.
+
+If every match is in one field, run that field's command. `unit focus --repo` and `--branch` fail on
+their own when more than one unit matches, listing each candidate. If the word matches in more than
+one field, or names more than one unit by handle, list the candidates and stop.
+
+### Task
+
+A task is an issue or pull request ref. GitHub numbers issues and pull requests in one sequence, so a
+ref names one of them.
+
+1. **Find the repo.**
+   - `#123` or `123`: the caller's own repo. Its name is the folder name of the primary checkout
+     (`dirname "$(git rev-parse --path-format=absolute --git-common-dir)"`), and its `<owner>/<repo>`
+     comes from `git remote get-url origin`.
+   - `color-map#123`: the live units whose repo name is `color-map`. Read `<owner>/<repo>` from
+     `git -C <primaryRoot or cwd> remote get-url origin` of those checkouts. No unit with that repo
+     name: fail naming it. Checkouts whose `origin` remotes disagree: list them and stop.
+     The org is needed only for the `gh` lookup.
+2. **Read what the number is.** `gh api repos/<owner>/<repo>/issues/<n> --jq '.pull_request != null'`
+   prints `true` for a pull request and `false` for an issue. If it fails, quote the error and stop.
+3. **Find the branches.**
+   - A pull request: `gh pr view <n> -R <owner>/<repo> --json headRefName --jq .headRefName`.
+   - An issue: `gh issue view <n> -R <owner>/<repo> --json closedByPullRequestsReferences` lists the
+     linked pull requests, each with its `number` and `repository`. Read each one's `headRefName` as
+     above, in that pull request's own repository.
+4. **Focus the branch.** Keep the branches a live unit is on. Exactly one: run
+   `cyberlegion unit focus --repo <name> --branch <branch>`, where `<name>` is that pull request's
+   repository name. More than one: list them and stop.
+5. **Fall back.** When no branch has a live unit, look for a live unit in that repo whose handle or
+   brief names the number: a handle that ends in `-123`, or a brief file that mentions `#123`,
+   `<repo>#123`, or `/issues/123` or `/pull/123` on that repo. Exactly one: run
+   `cyberlegion unit focus <id>`. More than one: list them and stop. None: fail naming the ref and
+   the branches tried.
+
+### Prose
+
+Match the words against each live unit's handle, branch, repo name, and brief (read the brief file
+when the record has one). A match is a unit the words plainly describe, not one they could be
+stretched to fit. Exactly one: run `cyberlegion unit focus <id>`. More than one: list them and stop.
+None: say no live unit matches, and list the units so the Council can name one.
+
+## 4. Report
+
+- A jump: one line naming the unit's handle and id and the pane, then that `/jump back` returns.
+- Candidates: one row per unit with its id, handle, branch, and repo name, then a line saying the
+  Council can narrow the argument (a form word, a repo, or an id). Do not jump.
+- A failure: quote the CLI's error verbatim with its exit code. Do not retry with other flags, prune,
+  or reach the pane any other way.

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