@mutmutco/opencode-mmi 2.54.1 → 2.55.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.1",
-  "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.55.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/mmi/SKILL.md

@@ -261,7 +261,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,71 @@
+---
+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.
+
+First supported engine: `codex-fugu` through the Overlord controller's PTY leash.
+
+## 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. `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.
+
+## 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/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
+
+- 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 submit behavior before sending real prompts.
+- 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/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,68 @@
+# 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`
+- `pid`
+- `runToken`
+- `fingerprint`
+- `composerSubmitMode`
+- `lastAckAt`
+- `lastLivenessCheckAt`
+- `lastUsefulSignalAt`
+- `journalPath`
+- `assignment`
+- `handoff`
+
+Message fields:
+
+- `id`
+- `target`
+- `text`
+- `createdAt`
+- `deliveredAt`
+
+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.