@mutmutco/opencode-mmi 2.55.0 → 2.57.0

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

@@ -0,0 +1,62 @@
+# Native Fugu API Engine
+
+Overlord servants run through the Sakana Fugu API using the OpenAI-compatible chat-completions surface.
+
+Defaults:
+
+- Base URL: `https://api.sakana.ai/v1`
+- Normal model: `fugu`
+- Ultra model: `fugu-ultra`
+- API key: `SAKANA_API_KEY`, or `MMI_OVERLORD_LLM_API_KEY`
+- Request timeout: `MMI_OVERLORD_LLM_TIMEOUT_MS`, clamped between 5 seconds and 10 minutes, defaulting to 90 seconds
+
+Optional overrides:
+
+- `MMI_OVERLORD_LLM_BASE_URL`
+- `MMI_OVERLORD_LLM_MODEL`
+- `MMI_OVERLORD_LLM_ULTRA_MODEL`
+
+## Preflight
+
+Before launching servants, probe `GET /models` with the configured key and base URL.
+
+Startup is blocked unless the probe proves both configured models are available.
+
+Do not print the API key.
+
+## Conversation State
+
+Each servant owns one stored conversation:
+
+- one system message with the servant identity and Overlord constraints
+- the startup assignment as a user message
+- every captured assistant response
+- future redirects appended as user messages
+
+The run registry records the model, request id when available, and conversation length.
+
+## Redirects
+
+`mmi-cli overlord send <target> <message>` calls `/chat/completions` for the target servant or each servant in `all`.
+
+The command returns only after the API response is captured or a bounded failure is recorded.
+
+If a request times out, errors, or returns no assistant text:
+
+- mark the servant `blocked`
+- mark the message `failed`
+- write the failure to the ledger
+
+## Ledger
+
+Append one ledger event for startup and one per redirect response.
+
+Include only operational metadata:
+
+- servant slot id
+- model
+- request id
+- response text
+- error text
+
+Never include API keys or provider secrets.

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

@@ -4,9 +4,9 @@ An ACK creates a lease, not permanent proof.
 
 Readiness requires:
 
-- Current readable handle.
-- Current writable handle.
-- Proven submit mode.
+- Current Fugu API conversation state.
+- Configured model for the servant role.
+- Stored system/user/assistant messages.
 - Matching run id and run token.
 - Recent useful signal or bounded liveness response.
 
@@ -15,13 +15,13 @@ Stale ACK-only readiness is forbidden.
 Awaiting-human:
 
 - Servants remain leased.
-- Controller heartbeat stays active.
+- Run registry remains current.
 - Status rehydrates state and checks liveness.
-- If background liveness is unsupported, mark `suspended-awaiting-human` and require a rehydrate pass before work resumes.
+- If background liveness is unsupported, preserve conversation state and require a rehydrate pass before work resumes.
 
-Lost servant:
+Blocked servant:
 
-- Mark the slot lost/unresponsive.
-- Preserve bounded journal.
-- Attempt recovery only when handles can be proven.
+- Mark the slot `blocked`.
+- Preserve bounded journal and conversation state.
+- Attempt recovery only when the API key, model, and conversation can be proven.
 - Otherwise spawn a replacement in the same role slot with a compact handoff.

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

@@ -10,7 +10,8 @@ Detect:
 
 Rules:
 
-- PowerShell/pwsh: use PowerShell syntax and native Windows paths.
+- Windows `pwsh`: use modern PowerShell syntax and native Windows paths.
+- Legacy Windows PowerShell (`powershell.exe`) is not an acceptable host shell for Overlord; use `pwsh`.
 - 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.

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

@@ -6,22 +6,15 @@ Minimum fields:
 
 - `runId`
 - `runToken`
-- `repo`
 - `worktree`
-- `branch`
-- `human`
-- `surface`
-- `hostPlatform`
-- `shellAdapter`
+- `engine`
+- `provider`
 - `state`
 - `createdAt`
 - `updatedAt`
-- `controllerPid`
-- `controllerFingerprint`
-- `lastControllerHeartbeatAt`
 - `statePath`
 - `journalDir`
-- `todoSnapshot`
+- `ledgerPath`
 - `servants[]`
 - `messages[]`
 - `ownedResources[]`
@@ -33,15 +26,17 @@ Servant fields:
 - `role`
 - `model`
 - `profile`
-- `state`
-- `pid`
-- `runToken`
-- `fingerprint`
+- `state` (includes `blocked` when an API request fails or returns no assistant text)
 - `composerSubmitMode`
+- `llmModel`
+- `llmRequestId`
+- `llmMessages`
 - `lastAckAt`
 - `lastLivenessCheckAt`
 - `lastUsefulSignalAt`
 - `journalPath`
+- `eventJournalPath`
+- `scopeToken` (optional non-secret attribution token bound to run id, servant slot, profile, and assignment scope)
 - `assignment`
 - `handoff`
 
@@ -51,7 +46,14 @@ Message fields:
 - `target`
 - `text`
 - `createdAt`
-- `deliveredAt`
+- `state` (`queued` | `started` | `completed` | `partial` | `failed`)
+- `queuedAt`
+- `startedAt`
+- `completedAt`
+- `failedAt`
+- `responseText`
+- `failureReason`
+- `servantResults[]`
 
 Owned resource fields:
 

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

@@ -1,44 +1,47 @@
-# Terminal Leash
+# Session Leash
 
-The Overlord must own every servant terminal through a durable controller, PTY leash, and registry.
+The Overlord must own every servant conversation through a durable registry, model metadata, request ids when available, and a bounded message lifecycle.
+
+The native Fugu API is the supported Overlord engine.
 
 Startup phases shown to humans:
 
-- Loading controller and PTYs.
-- Checking Fugu setup.
+- Loading the run registry.
+- Checking the Fugu API key and base URL.
+- Checking `/models` for `fugu` and `fugu-ultra`.
 - Starting one Ultra and normal Fugus.
+- Recording model, request, and conversation state.
 - Loading servant instructions.
-- Waiting for ACKs.
+- Waiting for API-backed 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:
+Do not show raw provider response bodies, stack traces, or retry noise unless startup fails or debug output is requested.
 
-- 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.
+Servant access model:
 
-`-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.
+- Servants are API conversations, not shell sessions.
+- Servants do not receive direct tools, stage/dev servers, browsers, Playwright, PR rights, or release rights.
+- The Overlord performs tool use, checks, edits, and PR operations in the host session after judging servant advice.
+- Full-trust repair is never delegated to servants.
 
 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`.
+- Verify `SAKANA_API_KEY` or `MMI_OVERLORD_LLM_API_KEY` is available.
+- Verify the configured base URL, defaulting to `https://api.sakana.ai/v1`.
+- Verify `GET /models` exposes `fugu` and `fugu-ultra`, or the configured model overrides.
 - Fail closed when semantics are missing or unknown.
 
-Submit probe:
+Conversation 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.
+- Prefer initial-prompt launch through `/chat/completions`.
+- Require the servant to emit useful assistant text for its startup assignment.
+- Record `llmModel`, `llmRequestId` when available, `llmMessages`, `lastEventAt`, `lastAckAt`, and `composerSubmitMode=surface-api`.
+- Fail startup if no assistant text is captured.
 
-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.
+Redirects after startup use `mmi-cli overlord send <target> <message>`; the CLI appends to the servant conversation and records completion or bounded failure. Do not bypass the mailbox with ad-hoc provider calls 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 generic process, shell, terminal, or provider names without exact ownership.
 - Refuse window-title-only ownership.

package/skills/release/SKILL.md

@@ -182,24 +182,20 @@ Rejected → stop (nothing released).
 
 ## Step 4 — GitHub Release + start prod deploy (non-blocking)
 
-For `tenant-container` repos, publish the GitHub Release, dispatch the central tenant deploy, and dispatch
-the release-scoped wiki refresh (release events never leave the releasing repo, so the keeper must be
-dispatched centrally — #759):
+For `tenant-container` repos, publish the GitHub Release and dispatch the central tenant deploy. Repo-owned
+wiki publication is a separate explicit step only when the release task asks for it or the user authorizes it.
 ```bash
 gh release create "vX.Y.0" --target main --generate-notes --latest
 gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub \
   -f slug={slug} -f repo={owner}/{repo} -f ref=main -f stage=main
-gh workflow run cursor-agents.yml --repo mutmutco/MMI-Hub \
-  -f agent=wiki-keeper -f only_repo={owner}/{repo}   # wiki-keeper, scoped to the released repo
 gh run watch "$(gh run list --workflow tenant-deploy.yml --limit 1 --json databaseId -q '.[0].databaseId')" \
   --exit-status   # the central prod-deploy run — run this in the BACKGROUND (Bash run_in_background)
 ```
 
 For `hub-serverless` (MMI-Hub), publish the GitHub Release but do **not** dispatch `tenant-deploy.yml` or
-`cursor-agents.yml`: the release event auto-fires `deploy.yml` for prod, `publish.yml` for the plugin/CLI
-package, and `cursor-agents.yml` for the Hub-scoped wiki refresh. A missing `DEPLOY#main` registry row for
-MMI-Hub is expected, not a tenant stack repair task. Watch/report the release-triggered `deploy.yml` and
-`publish.yml` runs instead.
+repo wiki publication: the release event auto-fires `deploy.yml` for prod and `publish.yml` for the
+plugin/CLI package. A missing `DEPLOY#main` registry row for MMI-Hub is expected, not a tenant stack repair
+task. Watch/report the release-triggered `deploy.yml` and `publish.yml` runs instead.
 
 For other direct-track repos, the train dispatches nothing centrally: a `registry-publish` repo's release
 event fires its own `publish.yml` (npm / plugin marketplace); a `solo-container` repo deploys via its own

package/skills/stage/SKILL.md

@@ -62,7 +62,7 @@ All stage artifacts (build output, screenshots, Playwright traces, local DB file
 — never tracked.
 
 A local stage is bound to the worktree that started it. Concurrent worktrees on one machine each keep
-their own stage on separate ports — you do not need to stop one before starting another. Saga continuity
+their own stage on separate ports — you do not need to stop one before starting another. For `jervaise`, saga continuity
 keys on branch; use a distinct North Star slug per parallel grind or feature. Stage JSON/state records
 the starting `cwd` plus git branch/commit when available.
 

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

@@ -1,25 +0,0 @@
-# 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.