@mutmutco/opencode-mmi 2.55.0 → 2.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/opencode-mmi",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "description": "MMI Future OpenCode adapter — registers mmi, secrets, stage, rcand, release, hotfix, bootstrap, grind, overlord, build, handoff, coop, and browser-automation skills, workflow commands, and deterministic guardrail hooks.",
   "type": "module",
   "main": "./dist/index.js",

package/skills/coop/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: coop
-description: Cross-repo, cross-PC multi-agent coordination — coordinator + joiners, GitHub issue handshake, #mmi-agents bus, Hub wake. Use instead of send_message or ad-hoc Slack MCP in unsupervised mode.
+description: Cross-repo, cross-PC multi-agent coordination through the #mmi-agents Slack channel, with a GitHub proof issue and Hub wake. Use instead of send_message or ad-hoc Slack MCP in unsupervised mode.
 ---
 
 # /coop — agent coordination
 
-Opt-in **multi-agent alignment** when parallel agents (different worktrees, IDEs, PCs, or repos) must handshake before merging or continuing.
+Slack-first coordination for parallel agents in different worktrees, IDEs, PCs, or repos.
+`#mmi-agents` is the live coordination surface. The GitHub issue is the proof/context record.
 
 ## When to use
 
@@ -17,23 +18,23 @@ Opt-in **multi-agent alignment** when parallel agents (different worktrees, IDEs
 
 - Serial merge train → use `wave land`
 - Session transfer → use `/handoff`
-- General Slack chat → not chatops; `#mmi-agents` + `COOP_*` protocol only
+- General Slack chat → not chatops; `#mmi-agents` is only for the `COOP_*` protocol
 
 ## Quick start
 
-**Coordinator** (creates issue + posts `COOP_START`):
+**Coordinator** (creates proof issue + posts `COOP_START` in `#mmi-agents`):
 
 ```bash
 mmi-cli coop start --repo mutmutco/MyRepo --message-file tmp/coop-open.md
 ```
 
-**Joiner**:
+**Joiner** (joins the `#mmi-agents` coordination chat):
 
 ```bash
 mmi-cli coop join <coopId> [--cloud]
 ```
 
-**Handshake** (substance on the **GitHub issue**; Slack gets stubs):
+**Handshake and information exchange** (substance in `#mmi-agents`; GitHub gets proof/context only):
 
 ```bash
 mmi-cli coop say <coopId> --phase HANDSHAKE_OPEN --message-file tmp/proposal.md
@@ -60,7 +61,8 @@ Hub dispatches wake on every coop message targeting joiners:
 ## Rules
 
 - **Never** use Claude `send_message` or harness-specific live chat for org coordination
-- **Substance on GitHub issue**; keep Slack stubs short
+- Use `#mmi-agents` for the live handshake, questions, counters, constraints, and shared facts
+- Use the GitHub issue for start context, proof links, decisions reached, and final outcome
 - Any **mutmutco org member** with a Hub session may join
 - Coordinator drives until `SHOOK` or explicit abort
 

package/skills/grind/references/auto.md

@@ -18,6 +18,15 @@ unchanged.
 Read every issue (title, body, labels, linked code). First drop any **not-grindable** issue (per
 the Hard rule) — unclaimed, no branch/PR, just a line in the final report. Partition the rest into
 execution groups — **mode per group, not one global mode.** No override flags; you always decide.
+
+**Pre-claim executable-set cap (#2118).** Before any `board claim`, estimate the grouped set against
+this run's tier/caps. If the full requested set is heterogeneous enough that the run would predictably
+hit cap/stuck — mixed unrelated subsystems, milestone-scale epics beside small bugs, or more groups than
+the tier can execute within the bounded loop — shrink the executable set **before claiming**. Claim only
+the first coherent batch/parallel wave that fits the cap. Leave later groups unclaimed and report them as
+`queued-not-claimed` in the final report, or file/link a follow-up queue issue when the input did not
+already have separate issues. Never move a whole board slice to In Progress merely because the user said
+`--auto all`; ownership should reflect work actually entering this bounded run.
 - **Batch** → one shared worktree/branch → one PR that `Closes` every issue in the group. Stay
   there until PR/integration; don't bounce to main for routine re-sync. For issues
   that are facets of one change (same files/module, no independent value).
@@ -35,8 +44,9 @@ artifact counts as a shared file:** when 2+ items rebuild the same checked-in bu
 retest step for every follow-on PR, never treating the conflict as a surprise. A real set may mix
 modes (e.g.
 `{950,951}` batched, `{952}` parallel, `{953}` serialized after `952`). **Concurrency bound:**
-at most **3 grind loops run at once**; the rest queue. Claim every **partitioned** (grindable)
-issue `--for <login>` before its work, in every mode — never the not-grindable ones already dropped.
+at most **3 grind loops run at once**; the rest queue. Claim every **partitioned + executable** (grindable,
+inside this run's pre-claim cap) issue `--for <login>` before its work, in every mode — never the
+not-grindable ones already dropped, and never the `queued-not-claimed` groups deferred by the pre-claim cap.
 If `/stage` is running, keep it attached to the active worktree; don't restart it for git
 bookkeeping. If a new worktree is truly needed, stop/destroy/recreate stage there, or warn
 first when intent is unclear.

package/skills/mmi/SKILL.md

@@ -25,31 +25,33 @@ it on every move). Closed/finished items auto-archive after they go quiet; archi
      for identity — `viewer` is for work items only (Step 1).
    - Known login → `👋 Welcome back, @<login> — pulling up your board…`
    - `source: unknown` → generic `👋 Welcome back — pulling up your board…`
-2. **Run doctor preflight synchronously before `board read` when a heal may be needed (#1871).** A healthy
-   setup stays **completely silent and fast** — no background task, no "setup looks good" line. When the
-   CLI or plugin is behind, the dev must see the wait **up front**, not after a silent multi-minute gap.
+2. **Keep the board fast: read first, run doctor only when evidence says it can change this render (#2112).**
+   The normal happy path is identity → board read. Do **not** block the board on `doctor --preflight` just to
+   check freshness. Run doctor synchronously only after a hard signal that the current setup may be broken:
+   `mmi-cli` is missing, `board read` reports missing auth/project scope, the command surface is absent, or a
+   cached/session-start health line explicitly says a heal is needed.
 
 ```bash
-mmi-cli doctor --preflight   # silent when healthy; upfront ↻ notice + eager heal when version/plugin update needed
-mmi-cli board read --json    # Step 1 — only after preflight (or greet-first on the all-green path)
+mmi-cli board read --json    # Step 1 — first useful render on the happy path
+mmi-cli doctor --preflight   # only after a hard setup signal, or in the background after the render if needed
 ```
 
 `doctor --preflight` detects a stale npm global, plugin clone, or installed-plugin record and runs the
-same self-heal as interactive `doctor` — but prints `↻ Updating mmi tooling, one moment…` **before** the
-wait and a clear `↻ MMI tooling updated — …` line when done (reload/restart guidance included). A behind
-npm global runs `npm install -g @mutmutco/cli@latest` (effective next invocation); a behind plugin clone
-fast-forwards (effective next session). On a Claude surface it also self-heals a **stale or duplicate
-installed plugin** — it drives `claude plugin marketplace remove mmi` → `claude plugin marketplace remove
-mutmutco` → `claude plugin marketplace add mutmutco/MMI-Hub` → `claude plugin install mmi@mutmutco` (a
-fresh reinstall, never `claude plugin update`, which nests into itself past MAX_PATH on Windows and wipes
-the marketplace clone, #1126), collapses duplicate `mmi@mutmutco` rows in
-`~/.claude/plugins/installed_plugins.json` to one user-scope entry, and quarantines stale MMI-only cache
-dirs under Claude/Codex plugin caches while preserving the active/released version. Plugin updates still
-take effect after a reload: **restart Claude Code / run `/reload-plugins`** (native), or **reopen the
-workspace** (VS Code extension).
-
-- **All green** → `doctor --preflight` prints nothing; proceed straight to `board read`.
-- **Stale tooling** → relay the `↻` lines from stderr to the dev, then `board read`.
+same self-heal as interactive `doctor` — but it belongs off the critical board path unless it has proof it
+must heal. When it does run and prints `↻ Updating mmi tooling, one moment…`, relay that before waiting;
+when it prints `↻ MMI tooling updated — …`, relay the reload/restart guidance. A behind npm global runs
+`npm install -g @mutmutco/cli@latest` (effective next invocation); a behind plugin clone fast-forwards
+(effective next session). On a Claude surface it also self-heals a **stale or duplicate installed plugin** —
+it drives `claude plugin marketplace remove mmi` → `claude plugin marketplace remove mutmutco` → `claude
+plugin marketplace add mutmutco/MMI-Hub` → `claude plugin install mmi@mutmutco` (a fresh reinstall, never
+`claude plugin update`, which nests into itself past MAX_PATH on Windows and wipes the marketplace clone,
+#1126), collapses duplicate `mmi@mutmutco` rows in `~/.claude/plugins/installed_plugins.json` to one
+user-scope entry, and quarantines stale MMI-only cache dirs under Claude/Codex plugin caches while
+preserving the active/released version. Plugin updates still take effect after a reload: **restart Claude
+Code / run `/reload-plugins`** (native), or **reopen the workspace** (VS Code extension).
+
+- **Fast path** → `whoami` then `board read`; no foreground doctor.
+- **Hard setup signal** → run `doctor --preflight`, relay `↻` lines, then retry `board read` when appropriate.
 - **`mmi-cli: command not found`** → plugin PATH provisioning has not applied, or the standalone CLI is not installed.
   In Claude Code, reopen the session; if it persists, install the MMI plugin:
   `/plugin marketplace add mutmutco/MMI-Hub` → `/plugin install mmi@mutmutco` → `/reload-plugins`.

package/skills/overlord/SKILL.md

@@ -11,7 +11,7 @@ Default pool: 3 servants total: one `fugu-ultra` and two normal `fugu` servants.
 
 Allowed range: `--3` through `--6`. Exactly one servant is Ultra in every run.
 
-First supported engine: `codex-fugu` through the Overlord controller's PTY leash.
+Supported engines: `codex-fugu` through the PTY leash and OpenCode/Fugu through session-backed `opencode run --session` routing. OpenCode is preferred when available because it exposes parseable JSON events, session ids, and completion state.
 
 ## Start Contract
 
@@ -23,7 +23,7 @@ First supported engine: `codex-fugu` through the Overlord controller's PTY leash
 6. Own worktrees, stage/dev servers, Playwright, browsers, PRs, merges, and cleanup.
 7. Keep servants leased until `/overlord stop`, `mmi-cli overlord stop`, or explicit controlled shutdown.
 
-CLI startup persists a gitignored run registry at `tmp/overlord/runs.json`, starts a durable controller, and lets the controller spawn servant PTYs. `mmi-cli overlord send <target> <message>` queues redirects into that registry so the controller can deliver them to live servant PTYs. The launch profile uses `-a never` plus explicit sandbox settings so routine servant tool calls do not bounce approval prompts back to the human.
+CLI startup persists a gitignored run registry at `tmp/overlord/runs.json`, starts a durable controller, and lets the controller spawn servant PTYs or OpenCode sessions. `mmi-cli overlord send <target> <message>` queues redirects into that registry so the controller can route them to live servants. On OpenCode, redirects use `opencode run --session <session-id> -m sakana/fugu --format json <message>` and advance a real message lifecycle (`queuedAt`, `startedAt`, `completedAt`, `failedAt`) from JSON events. The launch profile uses `-a never` plus explicit sandbox settings where the engine supports them so routine servant tool calls do not bounce approval prompts back to the human.
 
 ## Reference Loading
 
@@ -37,16 +37,21 @@ Read only what the task requires:
 - `references/servant-liveness.md`: liveness lease and awaiting-human behavior.
 - `references/controller-orphan-guard.md`: abrupt close, stale heartbeat, adoption, exact stop, and uncertainty.
 - `references/codex-fugu-preflight.md`: setup, update, model, API key, and Windows/Git Bash path checks.
+- `references/opencode-fugu-engine.md`: OpenCode preflight, JSON event parsing, session-backed mailbox, ledger, and liveness model.
 - `references/shell-adapters.md`: PowerShell, cmd, Git Bash, macOS zsh/bash, Linux bash/sh, and unknown-shell rules.
 - `references/state-schema.md`: durable run-state fields.
 - `references/failure-pressure-scenarios.md`: tests and lessons from the first Overlord design run.
 
 ## Hard Rules
 
+- **Fugu only — never a sub-agent fallback.** Overlord servants are Fugu (`fugu-ultra` + `fugu`) driven through the Overlord controller. Never satisfy an Overlord run with platform sub-agents, `multi_agent_v1`, generic workers, or any non-Fugu agent pool — not as a primary path and not as a fallback when the Fugu controller is missing or inactive. If the Fugu controller cannot start, is inactive, or cannot prove readable/writable handles, stop and report `blocked: fugu-controller-unavailable` with diagnosis; do not simulate Overlord with other agents.
 - Do not spawn servants on an unreadable or undrivable surface.
-- Launch servants with explicit no-approval and sandbox profiles.
-- Treat routine approval prompts as launch-profile failures.
+- **Probe the engine before launch.** Run the Codex/Fugu (or OpenCode) preflight + `--help`/status probe before any servant launch; never launch into an unprobed surface.
+- Codex/Fugu PTY servants launch with explicit `-a never` (no-approval) and an appropriate `-s` sandbox profile — read-only for consultation, workspace-write only in an owned worktree. OpenCode servants use `opencode run --format json --session` and rely on the OpenCode session mailbox instead of PTY submit probing.
+- **Any routine approval prompt during startup, planning, or assigned work is a launch-profile failure** — record and recover it, never hand-wave it away or train the human to approve routine commands. Consultation servants get read-only plus the disk-read permission ordinary host config reads need, or the Overlord performs those reads itself.
 - Probe submit behavior before sending real prompts.
+- **Delivery is not execution.** `mmi-cli overlord send` records a `queued`/`started` lifecycle, not completion. A redirect counts as delivered only when the servant journal shows the assignment left the composer and produced a new useful signal. If text remains at the `›` composer prompt after a bounded interval, mark the servant `delivery-stuck-composer` and the message `failed` — never report it as ready or delivered.
+- **No handoff after delivery = stalled, not ready.** When a servant stays `ready` but produces no non-TUI output after a bounded handoff-expected interval, mark it `stalled-after-delivery`; do not keep reporting it as ready.
 - Never rely on stale ACKs as liveness proof.
 - Never broad-kill by process name, title, shell name, or model command.
 - Never let servants mutate shared state without assigned ownership.

package/skills/overlord/references/opencode-fugu-engine.md

@@ -0,0 +1,104 @@
+# OpenCode Fugu engine
+
+OpenCode is the preferred Fugu engine when it is installed and exposes the required models.
+
+## Preflight
+
+Before servant launch, verify:
+
+- `opencode` is on PATH
+- `opencode --version` returns a version
+- `opencode models` lists `sakana/fugu` and `sakana/fugu-ultra`
+- `opencode run -m sakana/fugu --format json "ACK probe"` emits parseable JSON events
+- the event stream includes a session id, text, step start/finish, and a finish reason
+
+Fail closed if any required fact is missing.
+
+## Session-backed servants
+
+Start or resume servants through session ids.
+
+Use normal servants with:
+
+```text
+opencode run --session <session-id> -m sakana/fugu --format json <message>
+```
+
+Use the Ultra servant with:
+
+```text
+opencode run --session <session-id> -m sakana/fugu-ultra --format json <message>
+```
+
+Record these facts in the run registry:
+
+- `engine`
+- `provider`
+- `model`
+- `opencodeSessionId`
+- `opencodeVersion`
+- `eventJournalPath`
+- `lastEventAt`
+- `lastMessageCompletedAt`
+
+## Mailbox lifecycle
+
+A mailbox message is not complete when text is written.
+
+Track:
+
+- `queuedAt`
+- `startedAt`
+- `completedAt`
+- `failedAt`
+- `ackText`
+- `responseText`
+- `eventJournalPath`
+
+`send` returns success only after a servant response is captured or a bounded failure is recorded.
+
+## Ledger and artifacts
+
+Append servant outputs to:
+
+```text
+tmp/overlord/<runId>/ledger.jsonl
+```
+
+Artifact records are references, not side channels:
+
+- `artifactId`
+- `ownerSlotId`
+- `kind`
+- `version`
+- `path`
+- `status`
+- `dependsOn`
+
+The coordinator routes artifact refs between servants.
+
+Servants do not directly own PRs, merges, releases, browser sessions, Playwright, shared stage servers, or cross-servant worktrees.
+
+## Liveness
+
+Use JSON events as liveness signals.
+
+Distinguish:
+
+- idle
+- running
+- blocked
+- failed
+- lost
+
+A ready servant that receives work but produces no non-TUI output before the bounded handoff interval is `stalled-after-delivery`.
+
+A message pasted into a composer but not submitted is `delivery-stuck-composer`.
+
+## Stop and resume
+
+Stop only exact run-owned OpenCode resources.
+
+Prefer headless `opencode run --session` calls so fewer live PTYs need process ownership.
+
+Resume from registry session ids, event journals, and the ledger.

package/skills/overlord/references/state-schema.md

@@ -33,15 +33,17 @@ Servant fields:
 - `role`
 - `model`
 - `profile`
-- `state`
+- `state` (includes `stalled-after-delivery` for elapsed handoff windows, and `delivery-stuck-composer` when a redirect is pasted but unsubmitted)
 - `pid`
 - `runToken`
 - `fingerprint`
 - `composerSubmitMode`
+- `opencodeSessionId`
 - `lastAckAt`
 - `lastLivenessCheckAt`
 - `lastUsefulSignalAt`
 - `journalPath`
+- `eventJournalPath`
 - `assignment`
 - `handoff`
 
@@ -51,7 +53,14 @@ Message fields:
 - `target`
 - `text`
 - `createdAt`
-- `deliveredAt`
+- `state` (`queued` | `started` | `completed` | `failed`)
+- `queuedAt`
+- `startedAt`
+- `completedAt`
+- `failedAt`
+- `responseText`
+- `failureReason`
+- `deliveredAt` (legacy PTY-only; superseded by the lifecycle fields)
 
 Owned resource fields: