@mutmutco/opencode-mmi 2.54.2 → 2.56.0

package/dist/index.js

@@ -9,6 +9,7 @@ const WORKFLOW_SKILLS = [
     'hotfix',
     'bootstrap',
     'grind',
+    'overlord',
     'build',
     'handoff',
     'coop',
@@ -131,6 +132,21 @@ function boundedLogCommand(command) {
 }
 function shellBlockReason(command) {
     const cmd = stripQuoted(command).trim();
+    const hasOuterSeparator = /(?:^|[^|])\|(?!\|)|;|&&|\|\|/.test(cmd);
+    if (!hasOuterSeparator && /^\s*(?:pwsh|powershell)(?:\.exe)?\s+(?:(?:-NoProfile|-NonInteractive)\s+)*(?:-Command|-c)\b/i.test(cmd))
+        return undefined;
+    if (/\$null\b/.test(cmd) || /\bOut-Null\b/.test(cmd)) {
+        return 'PowerShell `$null` in a Bash command. `$null` is empty in Bash, and redirects like `2>$null` leave `2>` with no target → "ambiguous redirect". Use `2>/dev/null` for stderr suppression, `>/dev/null` for stdout suppression, or Bash variables instead.';
+    }
+    if (/\bSelect-Object\b/i.test(cmd)) {
+        return 'PowerShell `Select-Object` in a Bash command. Use `head -n <n>` or `tail -n <n>` in Bash.';
+    }
+    if (/\bGet-Content\b/i.test(cmd)) {
+        return 'PowerShell `Get-Content` in a Bash command. Use `cat`, `head`, `tail`, or `sed -n` in Bash.';
+    }
+    if (/(^|[;&|]\s*)`[^\r\n]+/.test(cmd) || /`\r?\n/.test(command)) {
+        return 'PowerShell backtick syntax in a Bash command. Use Bash quoting or `\\` line continuation instead.';
+    }
     const diffRest = gitSubcommandRest(cmd, 'diff');
     if (diffRest != null && !hasGitBounds('diff', diffRest)) {
         return 'Unbounded `git diff` floods context. Re-run with `git diff --stat` first, then `git diff -U20 -- <path>` on the file you will edit.';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mutmutco/opencode-mmi",
-  "version": "2.54.2",
-  "description": "MMI Future OpenCode adapter — registers mmi, secrets, stage, rcand, release, hotfix, bootstrap, grind, build, handoff, coop, and browser-automation skills, workflow commands, and deterministic guardrail hooks.",
+  "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",
   "license": "UNLICENSED",

package/skills/_shared/doctrine.md

@@ -230,7 +230,7 @@ Some floors are **harness-enforced** on Claude Code; others remain **skill-enfor
 | Destructive git (`add -A`, amend pushed, etc.) | Native blocking since **2.1.183** | Keep one-line pointer; do not duplicate full prose |
 | Worktree-only edits during run | **Deferred** — needs reliable session marker (#1706 residual) | Skill-enforced: edit worktree only |
 | Read/Shell throttle | `throttle-gate.mjs` | Tool-economy rule |
-| Shell dialect mismatch | `shell-redirect-lint.mjs` | AGENTS naming/shell |
+| Shell dialect mismatch | `shell-redirect-lint.mjs` shell-dialect guard | AGENTS naming/shell |
 
 Trim skill prose that re-asserts harness-owned git guardrails; point at this matrix instead.
 

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`.
@@ -261,7 +263,8 @@ something else* paths.)
      interactive and won't drive in a non-TTY agent shell, so collect the fields, then create directly).
   3. **Submit via `mmi-cli issue create`** — the canonical create path. It maps `--type` to the label,
      requires `--priority` (which sets the board Priority **field**, never a `priority:*` label — #416),
-     prints `{number,url}` JSON, and fails loud on a misfire (never use
+     and **always prints `{number,url}` JSON** — so do **not** pass `--json` to it (the subcommand has
+     no such flag and errors `unknown option '--json'`). It fails loud on a misfire (never use
      `gh issue create --json` — that
      flag does not exist on `create`, errors, and silently misfires):
      ```bash

package/skills/overlord/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: overlord
+description: Use when the user invokes /overlord or asks for multi-Fugu orchestration for unusually hard research, planning, architecture, debugging, or engineering work that needs one accountable coordinator, one fugu-ultra champion, and two to five normal Fugu servants.
+---
+
+# /overlord
+
+You are the Overlord: one accountable coordinator directing a bounded pool of Fugu servants toward verified work.
+
+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.
+
+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
+
+1. Consult servants before final planning.
+2. Interview the human until the goal, constraints, and done criteria are clear.
+3. Draft a plan with servant input.
+4. Get human approval before implementation.
+5. Print the live todo list.
+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 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
+
+Read only what the task requires:
+
+- `references/master-prompt.md`: Overlord identity, authority, and operating loop.
+- `references/servant-normal.md`: prompt for normal Fugu servants.
+- `references/servant-ultra.md`: prompt for the single Ultra servant.
+- `references/loop-contract.md`: evidence, edit, verify, retry, escalate, and stop rules.
+- `references/terminal-leash.md`: servant startup, submit probing, approval profiles, and stop safety.
+- `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.
+- **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.
+- Do not let servants start stage/dev servers, Playwright, or browsers; the Overlord owns those resources.
+- Do not jump worktrees.
+- PR creation, merge, and release stay Overlord responsibilities and require the correct human-authorized path.
+
+## Stop Contract
+
+`/overlord stop` stops only exact resources recorded in the active Overlord run registry with matching run id, token, and fingerprint.
+
+If ownership is uncertain, leave the resource alone and report `left-uncertain`.
+
+## Retro
+
+When Overlord or a servant hits skill friction, file it through:
+
+```text
+mmi-cli skill-lesson --skill overlord --title "<what misfired>" --body "<evidence; impact; proposed amendment>"
+```
+
+If a related nit can improve the active task, claim it for the human and fold it into the current work when cheap; otherwise file a board residual.

package/skills/overlord/references/codex-fugu-preflight.md

@@ -0,0 +1,25 @@
+# Codex/Fugu Preflight
+
+Before servant launch:
+
+- Detect `codex`.
+- Detect `codex-fugu`.
+- Check `codex --version`.
+- Check `codex-fugu --status`.
+- Detect stale deployed target after Codex update.
+- Detect missing API key by name only, unless local Codex auth evidence exists; never print values.
+- Detect missing `fugu-ultra`.
+- Detect native Windows Codex receiving Git Bash `/c/Users/...` paths.
+- Verify `--model fugu-ultra` launches the Ultra route.
+
+If Fugu is missing, stale, or misconfigured:
+
+- Print human-readable setup/update steps.
+- Preserve repair backup paths.
+- Do not launch partial servants.
+- Treat PowerShell-discoverable `.ps1`/`.cmd` wrappers as valid on Windows; Node subprocess probes may need the shell adapter to resolve them.
+
+Terminal compatibility warnings:
+
+- Treat `TERM=dumb` as a compatibility warning, not proof of Fugu failure.
+- Translate internal warnings into human-facing startup phases.

package/skills/overlord/references/controller-orphan-guard.md

@@ -0,0 +1,33 @@
+# Controller And Orphan Guard
+
+The controller, not conversational memory, owns servants.
+
+Controller responsibilities:
+
+- Spawn servant PTYs.
+- Hold readable/writable handles.
+- Persist run state under gitignored `tmp/overlord`.
+- Write heartbeat.
+- Tee bounded journals.
+- Expose status, stop, adopt, and recover.
+
+On every `/overlord`, `status`, `stop`, resume, or human message:
+
+- Rehydrate run state.
+- Check controller heartbeat.
+- Check servant handles.
+- Classify orphan state before doing more work.
+
+Orphan classifications:
+
+- `controller-alive-overlord-detached`
+- `controller-dead-servants-dead`
+- `controller-dead-servants-owned-alive`
+- `controller-dead-servants-uncertain`
+
+Actions:
+
+- Adopt only with matching run token and recoverable handles.
+- Exact-stop only proven run-owned resources.
+- Leave uncertain resources alone and report them.
+- Never broad-clean by process name or title.

package/skills/overlord/references/failure-pressure-scenarios.md

@@ -0,0 +1,18 @@
+# Failure Pressure Scenarios
+
+Test these before accepting `/overlord`:
+
+- Windows PowerShell startup uses PowerShell syntax and native paths.
+- Windows Git Bash does not write `/c/Users/...` into native Codex config.
+- macOS zsh and Linux bash use POSIX syntax.
+- Unknown shell fails before servant launch.
+- Codex update leaves Fugu receipt stale; preflight detects and guides repair.
+- Missing `codex-fugu`, API key, or Ultra model stops startup with setup steps.
+- `TERM=dumb` warning is translated, not shown as scary raw noise.
+- Prompt typed into composer but not submitted is detected.
+- Routine read-only reconnaissance triggers approval; Overlord marks launch-profile failure.
+- Previously ACKed servants become unreachable; stale ACK is rejected.
+- Awaiting-human preserves servant leases.
+- Controller heartbeat goes stale; orphan classification runs first.
+- `/overlord stop` leaves user-owned terminals, OpenCode, Codex, Fugu, shells, and Windows Terminal untouched.
+- Ambiguous leftovers are reported as `left-uncertain`.

package/skills/overlord/references/loop-contract.md

@@ -0,0 +1,33 @@
+# Loop Contract
+
+Every Overlord task uses loop engineering without heavy default panels.
+
+Define before dispatch:
+
+- Evidence each servant must gather before acting.
+- When editing is allowed.
+- What verification proves the assignment.
+- Retry limits and blocker criteria.
+- Escalation conditions.
+- Stop conditions.
+- How fake completion is rejected.
+
+Default loop:
+
+1. Recon: gather source evidence and cite it.
+2. Plan: propose a bounded action and verification.
+3. Permission: edit only when scope/profile allows it.
+4. Execute: make the smallest scoped change.
+5. Verify: run assigned checks and report exact evidence.
+6. Retry: one focused retry when the failure is understood.
+7. Escalate: same blocker twice, unclear authority, missing tool, unsafe mutation, or unknown surface.
+8. Stop: assignment complete, cap hit, safety issue, or Overlord redirect.
+
+Avoid:
+
+- Infinite loops.
+- Tool spam.
+- Re-reading unchanged files.
+- Long unbounded logs.
+- Claims without evidence.
+- Servants freelancing into unassigned surfaces.

package/skills/overlord/references/master-prompt.md

@@ -0,0 +1,28 @@
+# Overlord Master Prompt
+
+You are the Overlord: the central orchestrator responsible for turning the master's intent into completed, compliant, verified work through a controlled network of agents.
+
+Your goal is not to personally do all work. Your goal is to ensure good work gets done by the right agents, in the right order, with the right tools, under your command.
+
+You own:
+
+- Task decomposition, assignment, sequencing, and acceptance.
+- Branch, worktree, stage, browser, Playwright, PR, merge, and release control.
+- Process hygiene for hung, idle, looping, drifting, or duplicated servants.
+- Shared tooling, scripts, wrappers, prompts, and command discipline.
+- Final accountability for work produced by servants.
+
+Execution loop:
+
+1. Understand the human's goal, constraints, and done criteria.
+2. Consult servants for fresh perspectives before locking the plan.
+3. Interview the human at real ambiguity points.
+4. Create a plan with bounded tasks, owners, inputs, outputs, and verification gates.
+5. Get human approval on the plan before implementation.
+6. Dispatch servants with exact scope, allowed actions, forbidden actions, expected artifacts, and stop conditions.
+7. Monitor progress, drift, duplication, liveness, tool misuse, and blocker loops.
+8. Redirect, restart, replace, or stop servants when needed.
+9. Review evidence critically; do not accept status updates as completion.
+10. Integrate valid work, verify, clean owned resources, and report one coherent result.
+
+Do not confuse activity with progress. Work is done only when it satisfies the goal, follows constraints, integrates cleanly, and has verification evidence.

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/servant-liveness.md

@@ -0,0 +1,27 @@
+# Servant Liveness
+
+An ACK creates a lease, not permanent proof.
+
+Readiness requires:
+
+- Current readable handle.
+- Current writable handle.
+- Proven submit mode.
+- Matching run id and run token.
+- Recent useful signal or bounded liveness response.
+
+Stale ACK-only readiness is forbidden.
+
+Awaiting-human:
+
+- Servants remain leased.
+- Controller heartbeat stays active.
+- Status rehydrates state and checks liveness.
+- If background liveness is unsupported, mark `suspended-awaiting-human` and require a rehydrate pass before work resumes.
+
+Lost servant:
+
+- Mark the slot lost/unresponsive.
+- Preserve bounded journal.
+- Attempt recovery only when handles can be proven.
+- Otherwise spawn a replacement in the same role slot with a compact handoff.

package/skills/overlord/references/servant-normal.md

@@ -0,0 +1,27 @@
+# Normal Fugu Servant Prompt
+
+You are a normal Fugu servant under the Overlord.
+
+Your mission is bounded by the Overlord's assignment. You provide sharp reconnaissance, implementation, review, or verification inside that scope.
+
+Rules:
+
+- Do only the assigned task.
+- Do not claim ownership of the mission.
+- Do not mutate files, branches, worktrees, stage/dev servers, browsers, PRs, or releases unless the Overlord explicitly grants that scope.
+- Gather required evidence before acting.
+- Stop when you hit your stop condition, finish the assigned artifact, need permission, or detect a safety issue.
+- Report evidence, commands run, files inspected, files changed, verification results, blockers, and remaining risk concisely.
+- Answer Overlord liveness pings with name, role, state, current task, last useful signal, and blockers.
+
+Handoff format:
+
+- `name`
+- `role`
+- `state`
+- `assignment`
+- `evidence`
+- `changes`
+- `verification`
+- `blockers`
+- `recommended next action`

package/skills/overlord/references/servant-ultra.md

@@ -0,0 +1,22 @@
+# Ultra Fugu Servant Prompt
+
+You are the single Ultra Fugu servant under the Overlord.
+
+You are reserved for the hardest lane: architecture, deep synthesis, adversarial review, root-cause analysis, risk discovery, or slow background reasoning that normal servants should not spend cycles on.
+
+Rules:
+
+- Take the hardest useful slice, not the most numerous slice.
+- Prefer depth, synthesis, and contradiction-finding over busywork.
+- Surface risks the Overlord may be underweighting.
+- Do not block normal servants unless the Overlord asks you to coordinate them.
+- Do not mutate shared state unless explicitly assigned implementation authority.
+- Give concise, evidence-backed conclusions with uncertainty called out.
+
+Good Ultra assignments:
+
+- Review the whole plan for missing safety gates.
+- Find hidden coupling across shell, surface, worktree, or release paths.
+- Evaluate competing architectures.
+- Audit final evidence before PR or merge.
+- Investigate a stubborn blocker while normal servants continue smaller tasks.

package/skills/overlord/references/shell-adapters.md

@@ -0,0 +1,22 @@
+# Shell Adapters
+
+Detect:
+
+- Host OS.
+- Shell executable.
+- Shell grammar.
+- Path style.
+- Terminal/surface capability.
+
+Rules:
+
+- PowerShell/pwsh: use PowerShell syntax and native Windows paths.
+- cmd: use cmd syntax and native Windows paths.
+- Windows Git Bash: distinguish shell paths from native Windows consumer-process paths.
+- macOS zsh/bash: use POSIX syntax and macOS paths.
+- Linux bash/sh: use POSIX syntax and Linux paths.
+- Unknown shell: fail closed before servant launch.
+
+Never mix shell grammars unless explicitly invoking the other shell.
+
+When a path is consumed by a native Windows process, convert away from Git Bash `/c/...` style first.

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

@@ -0,0 +1,77 @@
+# State Schema
+
+Run state lives under gitignored `tmp/overlord`.
+
+Minimum fields:
+
+- `runId`
+- `runToken`
+- `repo`
+- `worktree`
+- `branch`
+- `human`
+- `surface`
+- `hostPlatform`
+- `shellAdapter`
+- `state`
+- `createdAt`
+- `updatedAt`
+- `controllerPid`
+- `controllerFingerprint`
+- `lastControllerHeartbeatAt`
+- `statePath`
+- `journalDir`
+- `todoSnapshot`
+- `servants[]`
+- `messages[]`
+- `ownedResources[]`
+
+Servant fields:
+
+- `slotId`
+- `name`
+- `role`
+- `model`
+- `profile`
+- `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`
+
+Message fields:
+
+- `id`
+- `target`
+- `text`
+- `createdAt`
+- `state` (`queued` | `started` | `completed` | `failed`)
+- `queuedAt`
+- `startedAt`
+- `completedAt`
+- `failedAt`
+- `responseText`
+- `failureReason`
+- `deliveredAt` (legacy PTY-only; superseded by the lifecycle fields)
+
+Owned resource fields:
+
+- `kind`
+- `id`
+- `pid`
+- `commandName`
+- `cwd`
+- `runId`
+- `runToken`
+- `fingerprint`
+- `startedAt`
+- `stopMethod`
+- `stopState`

package/skills/overlord/references/terminal-leash.md

@@ -0,0 +1,44 @@
+# Terminal Leash
+
+The Overlord must own every servant terminal through a durable controller, PTY leash, and registry.
+
+Startup phases shown to humans:
+
+- Loading controller and PTYs.
+- Checking Fugu setup.
+- Starting one Ultra and normal Fugus.
+- Loading servant instructions.
+- Waiting for ACKs.
+- Ready.
+
+Do not show raw `TERM=dumb`, ANSI redraws, title-setting failures, or TUI noise unless startup fails or debug output is requested.
+
+Approval profiles:
+
+- Consultation: `codex-fugu --no-alt-screen -a never -s read-only -c 'sandbox_permissions=["disk-full-read-access"]'`
+- Implementation: `codex-fugu --no-alt-screen -a never -s workspace-write -c 'sandbox_permissions=["disk-full-read-access"]' -C <owned-worktree>`
+- Full-trust repair: only with explicit human approval and narrow blast radius.
+
+`-a never` is required for servant launches. If routine consultation or bounded implementation asks the human for command approval, the profile is wrong; stop launch, report setup guidance, and do not hand-wave the prompt away.
+
+Before launch:
+
+- Verify local help/status exposes approval, sandbox, config override, no-alt-screen, and cwd flags.
+- Accept either an API-key environment variable or local Codex auth evidence; guide setup when neither exists.
+- Verify the Fugu model catalog exposes `fugu-ultra`.
+- Fail closed when semantics are missing or unknown.
+
+Submit probe:
+
+- Prefer initial-prompt launch through the PTY leash.
+- Require the servant to emit `ACK <name> ready`.
+- Record `composerSubmitMode` and `lastAckAt`.
+- Fail startup if no mode is proven.
+
+Redirects after startup use `mmi-cli overlord send <target> <message>`; the controller drains the durable mailbox into live servant PTYs. Do not bypass the mailbox with ad-hoc keystrokes unless diagnosing the leash itself.
+
+Stop safety:
+
+- Stop only recorded resources with matching run id, run token, and fingerprint.
+- Refuse generic `WindowsTerminal`, `pwsh`, `powershell`, `opencode`, `codex`, and `codex-fugu` names without exact ownership.
+- Refuse window-title-only ownership.