@mutmutco/opencode-mmi 2.55.0 → 2.57.0

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, Hub open-session discovery, bounded polling, and a GitHub proof issue. Use instead of send_message or ad-hoc Slack MCP.
 ---
 
 # /coop — agent coordination
 
-Opt-in **multi-agent alignment** when parallel agents (different worktrees, IDEs, PCs, or repos) must handshake before merging or continuing.
+Join-or-create coordination for humans, backed by join-or-start primitives for 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
 
@@ -16,24 +17,96 @@ Opt-in **multi-agent alignment** when parallel agents (different worktrees, IDEs
 ## When not to use
 
 - Serial merge train → use `wave land`
-- Session transfer → use `/handoff`
-- General Slack chat → not chatops; `#mmi-agents` + `COOP_*` protocol only
+- Session transfer → `jervaise` can use `/handoff`; everyone else uses the issue/PR handoff record
+- General Slack chat → not chatops; `#mmi-agents` is only for the `COOP_*` protocol
 
-## Quick start
+## Human flow
 
-**Coordinator** (creates issue + posts `COOP_START`):
+When the human types `/coop`, make the command feel like a small wizard.
+
+1. Run discovery:
+
+```bash
+mmi-cli coop pending
+mmi-cli coop open
+```
+
+2. Show joinable sessions by category:
+
+- Invited to me
+- My agents
+- This repo
+- Internal / other repos
+
+3. Ask whether to join one or create one.
+
+4. If joining:
+
+```bash
+mmi-cli coop join <sessionCode-or-coopId>
+mmi-cli coop wait <sessionCode-or-coopId>
+```
+
+5. If creating, ask the topic first.
+
+6. Then ask the target:
+
+- Own agents
+- A specific human / their agents
+- Open internal session
+
+7. Start the session with topic and target metadata:
+
+```bash
+mmi-cli coop start --repo mutmutco/MyRepo --topic "<topic>" --target own-agents --message-file tmp/coop-open.md
+mmi-cli coop start --repo mutmutco/MyRepo --topic "<topic>" --target user --target-users oguz-mut --message-file tmp/coop-open.md
+mmi-cli coop start --repo mutmutco/MyRepo --topic "<topic>" --target internal --message-file tmp/coop-open.md
+```
+
+8. Tell the human the returned session code.
+
+9. For a specific target human, offer to DM them through the MMI Future Slack app. If they approve and a Slack target is known, run:
+
+```bash
+mmi-cli coop invite <coopId> --target-user oguz-mut --dm --slack-user U123
+```
+
+If no Slack user id or DM channel is available, still post the visible invite:
+
+```bash
+mmi-cli coop invite <coopId> --target-user oguz-mut
+```
+
+10. Enter bounded wait:
+
+```bash
+mmi-cli coop wait <coopId>
+```
+
+## CLI primitives
+
+**Check pending and open sessions first:**
+
+```bash
+mmi-cli coop pending
+mmi-cli coop open
+```
+
+**Join an open session when one matches:**
 
 ```bash
-mmi-cli coop start --repo mutmutco/MyRepo --message-file tmp/coop-open.md
+mmi-cli coop join <coopId>
+mmi-cli coop wait <coopId>
 ```
 
-**Joiner**:
+**Start only when no relevant session is open:**
 
 ```bash
-mmi-cli coop join <coopId> [--cloud]
+mmi-cli coop start --repo mutmutco/MyRepo --topic "<topic>" --target internal --message-file tmp/coop-open.md
+mmi-cli coop wait <coopId>
 ```
 
-**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
@@ -41,28 +114,32 @@ mmi-cli coop say <coopId> --phase ACK --message-file tmp/ack.md
 mmi-cli coop say <coopId> --phase SHOOK --message-file tmp/shook.md
 ```
 
-**End** (coordinator, after user confirms):
+`SHOOK` ends the coop session. Use `COOP_END` / `coop end` for explicit abort or close:
 
 ```bash
 mmi-cli coop end <coopId>
 ```
 
-## Wake (primary path)
+## Bounded wait
 
-Hub dispatches wake on every coop message targeting joiners:
+Use `mmi-cli coop wait <coopId>` after join/start/say. It polls after `1m`, `2m`, `3m`, `5m`, `10m`, and `30m`, prints only new messages, then stops waiting.
 
-1. **SessionStart** — `coop pending` banner + detached `coop deliver`
-2. **Cursor cloud** — when joiner used `--cloud`
-3. **Slack Events** — inbound `#mmi-agents` coop messages re-trigger wake
+Timeout does **not** close the session. The coop remains open and can be joined later.
 
-**Do not** rely on `coop watch` unless wake is broken — it is degraded poll only.
+`coop watch` remains an unbounded manual diagnostic only.
 
 ## 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
+- Check open sessions before starting a new one
+- For humans, `/coop` is join-or-create: list categories first, ask topic/target only when creating
+- A returned `sessionCode` is the human-shareable join code
+- Specific-human creation stores `targetLogins` so the invite appears under "Invited to me"
+- DM invites are opt-in; visible `#mmi-agents` invite is always available
+- `SHOOK` and `COOP_END` close the session; `ACK` and `COUNTER` keep it open
 
 ## Reference
 

package/skills/grind/SKILL.md

@@ -17,6 +17,8 @@ Two kinds of work, one loop:
 
 **Shared doctrine:** Read `skills/_shared/doctrine.md` at session start and on resume. Fusion, parallelism, panel economics, flat fan-out, classifier-denied spawns, worktree hygiene, saga resume, enforcement matrix — single source; do not duplicate here.
 
+**Continuity access:** Saga and North Star are Jervaise-only. If the current login is not `jervaise`, skip all `saga`, `northstar`, `plan`, and `/handoff` steps; keep durable state in the board issue, PR body/comments, verification logs, and final report.
+
 Flags:
 - `--explore` — brainstorm and judge approaches before building (use for open-ended,
   "find a better/faster way" work). Without it, run the convergent loop.
@@ -86,10 +88,11 @@ Flags:
   - Perform the fix, **verify empirically** (run the command whose output the acceptance pins — no diff
     to panel), close the issue, and **file any durable-prevention enhancement** as a separate item.
   - Terminal-done layer 1 is the live command output; layer 3 is the close, not a merge.
-- **Resumable.** After every phase: (1) silent one-line `mmi-cli saga note "<audit>"`; (2) `mmi-cli saga snapshot set --kind grind …` (or `--json-file`) — see **## Saga keep (resume snapshot)**. On resume, `mmi-cli saga snapshot show --kind grind` first; never reconstruct from collapsed chat history.
+- **Resumable.** For `jervaise`, after every phase: (1) silent one-line `mmi-cli saga note "<audit>"`; (2) `mmi-cli saga snapshot set --kind grind …` (or `--json-file`) — see **## Saga keep (resume snapshot)**. For everyone else, write the same phase evidence to the issue/PR record. On resume, corroborate against git, GitHub, and the board; never reconstruct from collapsed chat history.
 - **Announce routing.** At phase transitions (after Phase 0a′ / model selection, before Gate 1 under
-  interactive, and at equivalent points under `--auto`), **announce explicitly** in user-visible text
-  **and** mirror the same facts in a silent `mmi-cli saga note`:
+  interactive, and at equivalent points under `--auto`), **announce explicitly** in user-visible text.
+  For `jervaise`, also mirror the same facts in a silent `mmi-cli saga note`; for every other login,
+  mirror them in the run output/report only (saga is Jervaise-only):
   - **Ultra mode** when explicit `--ultra` YOLO is active (distinct from auto-ultra verify uplift).
   - **Explore mode** when `--explore` or auto-framed explore is selected.
   - **Routing tier** (Budget / Balanced / Paranoid / Ultra verify routing).
@@ -105,7 +108,7 @@ Flags:
 
 ## Saga keep (resume snapshot)
 
-Grind-specific snapshot wiring — shared resume rules in `skills/_shared/doctrine.md`. Schema: `templates/saga-snapshot.md`. Use `--kind grind` for show/set. CLI maps snapshot fields → HEAD primitives (`next`, `anchor`, checklist) — no parallel store.
+**Jervaise-only.** Grind-specific snapshot wiring — shared resume rules in `skills/_shared/doctrine.md`. Schema: `templates/saga-snapshot.md`. Use `--kind grind` for show/set. CLI maps snapshot fields → HEAD primitives (`next`, `anchor`, checklist) — no parallel store. For every other login, the issue/PR record + git history is the resume surface — do not run saga/North Star commands.
 
 ## Gates — how every gate (and decision point) is presented
 Hosts collapse mid-turn text: anything you printed between tool calls may be invisible when
@@ -134,8 +137,9 @@ the user reaches the gate. So:
 ## Phase 0a′ — Classify & route
 
 Runs immediately after the grindability check, **before** Phase 0a model questions. (`--auto`:
-apply silently for classification; still **announce** routing per **Hard rules — Announce routing**;
-`saga note "grind class=X routing=Y ultra=Z reason=…"`.)
+apply silently for classification; still **announce** routing per **Hard rules — Announce routing**.
+For `jervaise`, `saga note "grind class=X routing=Y ultra=Z reason=…"`; for every other login,
+announce in the run output/report only — saga is Jervaise-only.)
 
 Read the issue **type label** (`bug` / `feature` / `task`), **priority**, **title/body**,
 **labels** (e.g. `security`), known **files touched**, and flags (`--explore`, `--ultra`, `--auto`).
@@ -204,7 +208,7 @@ See `templates/synthesize-panel.md`.
 **Paranoid / Ultra hard-lens double-pass:** run `security` and `correctness` twice — different
 temperature or two different models — before Phase 2b.
 
-Log each verify round: `mmi-cli saga note "verify round N: routing=X ultra=Y"`.
+Log each verify round: for `jervaise`, `mmi-cli saga note "verify round N: routing=X ultra=Y"`; for every other login, log it in the run output/report (saga is Jervaise-only).
 
 ## Phase 0b — Frame  [GATE 1]
 (`--auto`: no gate — auto-decide explore-vs-convergent, in `--explore` auto-pick the judge's
@@ -220,8 +224,7 @@ planning shape — **parallel planners + verifier-tier judge** — before Gate 1
 2. Each planner returns: approach summary, risks, proposed success criteria, estimated complexity.
 3. **Judge agent** (verifier-tier model, **≠** any planner/builder) scores against the goal rubric;
    picks winner or synthesizes hybrid — synthesize-and-reconcile, not vote/debate.
-4. Winner + criteria written to issue body; North Star push; proceed to Gate 1 (interactive) or
-   Phase 1 (`--auto`). `mmi-cli saga note "multi-plan N=<n> winner=<summary>"`.
+4. Winner + criteria written to issue body; for `jervaise`, North Star push + `mmi-cli saga note "multi-plan N=<n> winner=<summary>"`; for every other login, record the winner + criteria in the issue/PR record (saga + North Star are Jervaise-only). Proceed to Gate 1 (interactive) or Phase 1 (`--auto`).
 
 **Skip multi-agent planning** for narrow bugs, low priority, or user "quick"/"small" — single
 planner + judge (or direct criteria framing) is enough.
@@ -249,7 +252,7 @@ planner outputs when both paths are active.
    **Vague or ambiguous body?** Read the full issue (body + comments), state the deliverable,
    and write criteria the user can confirm at Gate 1. Umbrella scope → child issues (`--parent`),
    one shippable unit per grind.
-   Write them into the issue body; push the criteria to North Star (`mmi-cli northstar push <slug>` —
+   Write them into the issue body. For `jervaise`, also push the criteria to North Star (`mmi-cli northstar push <slug>` —
    the default push queues a background sync and prints "queued": that is success, not a failure;
    `mmi-cli northstar status` checks it, `mmi-cli northstar sync` confirms durably).
 3. Present per **## Gates** (class, routing, ultra, criteria). **Wait for the user's go.**
@@ -260,8 +263,7 @@ planner outputs when both paths are active.
 2. Otherwise brainstorm **2-3 candidate approaches** (2 if the goal is clear, 3 if wide) on the
    builder model — or use **multi-agent planning** when auto-gated.
 3. Score with the **verifier-model judge** (or fusion panel judge); pick or synthesize a direction.
-4. Define a success target — numeric metric if stated, else judged rubric. File/claim, North Star
-   push. Present per **## Gates**. **Wait for the user's go.**
+4. Define a success target — numeric metric if stated, else judged rubric. File/claim; for `jervaise`, also push North Star. Present per **## Gates**. **Wait for the user's go.**
 
 ## Generative fusion path (auto-gated)
 
@@ -275,7 +277,7 @@ verifier-tier **judge** fuses into one markdown deliverable. For **research-clas
    any planner) synthesizes — not vote/debate.
 2. Judge output is a **fused markdown deliverable**: chosen approach, tradeoffs, criteria
    refinement, spike findings.
-3. Land in issue body + `mmi-cli northstar push <slug>`.
+3. Land in issue body; for `jervaise`, also `mmi-cli northstar push <slug>` (North Star is Jervaise-only).
 4. **Code-shipping explore:** fused doc feeds Phase 1; Phase 2 verify stays diff-pinned.
 5. **Research-only** (no code PR): fusion output is the primary artifact; stop after criteria met
    + Gate 2 (`--auto` report).
@@ -335,6 +337,8 @@ build that adds new modules/tests is invisible to lenses and can draw a false `c
 Stage first (`git -C <worktree> add -A && git -C <worktree> diff --cached -- ':!cli/dist' > tmp/grind-verify-<round>.patch`)
 or `git -C <worktree> add -N <new files>` before the diff (#2057).
 
+**Spawn lenses tool-restricted (#2137).** Under `isolation=worktree`, spawn each lens with a subagent type that has **no shell/git/repo-filesystem access** — never the default `general-purpose` (or any `*`-tool) agent. A tool-capable lens silently bypasses prompt-only pinning: a `general-purpose` requirements lens has ignored the embedded patch, run `git diff` against the worktree's PARENT checkout (a different branch), and returned a false `cannot-verify`. Pass the patch file as the lens's ONLY input and state it has zero repo/git/filesystem access; if it cannot judge from the patch, it returns `cannot-verify`. Where the host exposes no zero-shell agent type, keep the no-access framing in the prompt AND discard + re-run (patch-only) any lens whose transcript shows a repo/git read — prompt-only pinning is not structurally honored by tool-capable subagents.
+
 **Lens-prompt clauses → `references/verify.md`.** Every lens prompt MUST carry: the **verbatim-includes-test-files** rule, the **abstention** rule (`cannot-verify`, never a false "absent/missing" blocker), the **diff-shape** clause (a referenced-but-undefined symbol is pre-existing — never flag it), and the **worktree-isolation** clause (patch-only, deny repo FS, stale-checkout warning). The exact wording lives in `references/verify.md` — load it before spawning lenses.
 
 Under **Paranoid** or **Ultra**, run **hard lenses twice** before Phase 2b.
@@ -382,7 +386,9 @@ The synthesizer returns a **`PanelReport`** — structured reconciliation of len
 
 A verify round **fails if `PanelReport.blockers` is non-empty**. If synthesis errors or returns
 invalid JSON, **degrade gracefully**: union raw lens `blockers` (manual dedupe by file+line+title),
-`saga note` the degradation, and continue Phase 3 — synthesis is an uplift, not a hard dependency.
+then for `jervaise` `saga note` the degradation and continue Phase 3; for every other login, note the
+degradation in the run output/report and continue (saga is Jervaise-only). Synthesis is an uplift,
+not a hard dependency.
 Optional CLI path: `mmi-cli verify panel` plans lens jobs; pipe lens JSON to `mmi-cli verify synthesize`
 for deterministic blocker dedupe before the host synthesizer enriches consensus/contradictions.
 Real verifier lanes only. Empty or controller-authored all-pass stubs are invalid evidence and do
@@ -453,7 +459,8 @@ See shared doctrine § Self-learning + retro. Grind-specific examples: gate mess
 ## End-of-grind summary
 
 At grind completion (PR opened + interactive stop, or `--auto` terminate/merge report), emit a **very
-brief** summary block — user-visible and mirrored in `mmi-cli saga note`:
+brief** summary block in user-visible text. For `jervaise`, also mirror it in `mmi-cli saga note`
+(saga is Jervaise-only); for every other login, the user-visible summary is the record:
 
 - **Tier + modes:** chosen tier (`light`/`standard`/`deep`/`ultra`); `--explore`, auto-ultra (verify uplift), `--auto` if applied.
 - **Models used:** builder / verifier / third / synthesizer / judge (host slot names).

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.
@@ -63,8 +73,7 @@ report. Never pretend cross-vendor ultra ran when it did not.
 Auto-decide explore-vs-convergent from the ask (open-ended → explore; `--explore` forces it on).
 Run **multi-agent planning + judge** when auto-gated (always under explicit `--ultra`). In explore,
 brainstorm + judge or **generative fusion** when auto-gated — **auto-pick the winning approach** —
-no wait. File/claim the item(s), write the criteria, push to North Star, then go straight to Phase 1.
-`saga note` multi-plan winner, tool policy, and fusion path when active.
+no wait. File/claim the item(s), write the criteria, then for `jervaise` push to North Star + `saga note` multi-plan winner, tool policy, and fusion path when active; for every other login, record the criteria + winner in the issue/PR record (saga + North Star are Jervaise-only). Then go straight to Phase 1.
 
 ## Phase 4 — PR → CI-merge loop (replaces Gate 2)
 

package/skills/grind/references/routing.md

@@ -5,7 +5,7 @@ Loaded on demand from `SKILL.md` § Phase 0a′. The class table + the effort-ti
 ## Auto-ultra detection
 
 **auto-ultra = true** (verify-panel uplift **only** — not whole-loop YOLO) when **any** of
-(log first match in saga):
+(for `jervaise`, log first match in saga; for every other login, in the run output/report):
 
 1. ~~User passed **`--ultra`**.~~ **Explicit `--ultra` is separate** — see **Flags** and
    **§ Explicit `--ultra` vs auto-ultra**; it is **not** auto-ultra.
@@ -13,7 +13,7 @@ Loaded on demand from `SKILL.md` § Phase 0a′. The class table + the effort-ti
 3. **`--explore`** + stated numeric SLA/metric with high blast radius.
 4. **Architectural / cross-cutting** scope (multi-module, public API break, migration).
 5. **Escalation:** after **2 failed verify rounds** on default routing, escalate to auto-ultra for round 3+
-   (once per grind; saga note). Interactive: announce; `--auto`: silent.
+   (once per grind; for `jervaise`, `saga note` the escalation; for every other login, note it in the run output/report — saga is Jervaise-only). Interactive: announce; `--auto`: silent.
 
 **auto-ultra = false** (stay 2-model): docs/prose-only diffs; priority `low`; narrow bug with clear repro;
 user says "quick" / "small" in the prompt (explicit user instruction wins).
@@ -70,7 +70,6 @@ When the user passes **explicit `--ultra`**, select **higher reasoning effort**
 exposes it (e.g. elevated thinking/reasoning tier on supported models). Apply to builder, verifier,
 third, synthesizer, and judge roles when the host offers per-model reasoning knobs.
 
-- **Announce** when elevated reasoning is selected — model + level — in the routing announcement block
-  and `mmi-cli saga note "reasoning=<model>:<level> …"`.
+- **Announce** when elevated reasoning is selected — model + level — in the routing announcement block; for `jervaise`, also `mmi-cli saga note "reasoning=<model>:<level> …"` (saga is Jervaise-only).
 - **Fallback:** when the host has no reasoning-effort knob, use the strongest available model tier and
   note the gap in the announcement — do not block the grind.

package/skills/grind/references/verify.md

@@ -24,10 +24,12 @@ diff-shape clause:
 This prevents diff-absent symbols from becoming ship-stoppers at the lens; Phase 2b's absence-claims
 drop rule remains the backstop.
 
-**Worktree isolation (#1621, #1895).** Phase 2: `isolation=worktree` — other checkouts may be stale.
+**Worktree isolation (#1621, #1895, #2137).** Phase 2: `isolation=worktree` — other checkouts may be stale.
 **Orchestrator MUST:** patch-only input; deny repo FS tools on lenses; stale-checkout clause in every lens prompt; re-run Phase 2 if a transcript shows disk reads — never triage disk-sourced blockers.
 Abstention + diff-shape rules above still apply; `cannot-verify` beats false absence.
 
+**Deny repo FS tools structurally, not just by prompt (#2137).** Spawn lenses with a subagent type that has no Bash/git/repo-filesystem access; never spawn a lens as a `general-purpose` / `*`-tool agent under `isolation=worktree`. A tool-capable lens has ignored the embedded patch and run `git diff` on the worktree's parent checkout (on another branch), returning a false `cannot-verify` describing a diff that is not under review. When the host cannot restrict tools, the prompt must forbid all repo/git/file access and the orchestrator discards any blocker whose evidence came from a disk/git read, re-running patch-only — prompt-only pinning is not reliably honored by tool-capable subagents.
+
 ## Tool-enabled lenses (default expectation on applicable lenses)
 
 When an objective signal exists, hard lenses must anchor to it — failing test, typecheck error,
@@ -58,7 +60,7 @@ while Phase 2b synthesizer stays **tool-free** (lens JSON + diff stat only).
 
 **Hygiene:** configurable allow/deny domain lists (org/repo-level) — exclude benchmark-leak
 domains (e.g. Stack Overflow, issue mirrors) from verify search. Default deny list in
-`cli/src/grind-policy.ts`. **Per-lens budget:** hard cap (3 queries/lens/round); `saga note` on exceed.
+`cli/src/grind-policy.ts`. **Per-lens budget:** hard cap (3 queries/lens/round); on exceed, for `jervaise` `saga note` it, for every other login note it in the run output/report (saga is Jervaise-only).
 
 **Diff-pinning preserved:** tools supplement — never replace — the pinned patch. Under
 `isolation=worktree`, repo FS tools stay forbidden even under ultra; cite builder test output from
@@ -73,7 +75,7 @@ full re-panel) before Phase 3 triage — at most once per round.
 
 **`contradictions`:** if the disagreement is **criteria/spec ambiguity** (lenses read the spec
 differently), stop and escalate to the human per **## Gates** — do not guess. If one lens is
-clearly wrong against consensus + diff, note it in the saga and triage real blockers only.
+clearly wrong against consensus + diff, note it (for `jervaise` in the saga; for every other login in the run output/report — saga is Jervaise-only) and triage real blockers only.
 
 **Absence-claims (#1621, #1895, #2057).** Drop "missing/absent/unimplemented/not fixed" blockers
 contradicted by the pinned patch or green builder tests. Drop blockers when lens logs show repo

package/skills/grind/templates/saga-snapshot.md

@@ -1,5 +1,7 @@
 # Grind saga keep — resume snapshot
 
+**Jervaise-only artifact.** `mmi-cli saga snapshot` is a Jervaise-only continuity tool. For every other login, the issue/PR record + git history is the resume surface — do not use this template or `mmi-cli saga`.
+
 Enforced via **`mmi-cli saga snapshot`** (maps to saga HEAD — no parallel store). Checklist uses namespaced prefixes: `gs-open:`, `gs-resolved:`, `gs-ceiling:`.
 
 ## Read-first on resume

package/skills/grind/templates/synthesize-panel.md

@@ -100,5 +100,5 @@ The grind loop uses this report as follows:
 If the synthesizer returns invalid JSON or errors:
 
 1. Fall back to **raw lens blockers** — union all lens `blockers`, manual dedupe by file+line+title.
-2. `mmi-cli saga note "phase 2b: synthesize degraded, raw lens triage"`.
+2. For `jervaise`, `mmi-cli saga note "phase 2b: synthesize degraded, raw lens triage"`; for every other login, note the degradation in the run output/report (saga is Jervaise-only).
 3. Continue Phase 3 — synthesis is an uplift, not a hard dependency.

package/skills/handoff/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: handoff
-description: Record or claim an explicit session handoff in the saga + North Star system that SessionStart resumes — open a handoff to leave work for a future session, accept a pending one, or cancel your own. Use when the user says "handoff" or "/handoff", asks to hand off work, leave a checkpoint for the next session, or claim a prior handoff, or invokes /handoff.
+description: Jervaise-only. Record or claim an explicit session handoff in the saga + North Star system that SessionStart resumes — open a handoff to leave work for a future session, accept a pending one, or cancel your own. Use when Jervaise says "handoff" or "/handoff", asks to hand off work, leave a checkpoint for the next session, or claim a prior handoff, or invokes /handoff.
 ---
 
 # /handoff — explicit saga handoff lifecycle
 
-Use when the user says `handoff` or `/handoff`, or asks to leave work for a future session or claim a prior handoff. This skill records an explicit handoff in the same saga + North Star system that SessionStart resumes.
+This is a Jervaise-only continuity skill. If any other developer asks for a handoff, do not open or claim one; use the board, issue, or PR as the handoff record instead.
+
+Use when Jervaise says `handoff` or `/handoff`, or asks to leave work for a future session or claim a prior handoff. This skill records an explicit handoff in the same saga + North Star system that SessionStart resumes.
 
 ## Start
 

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.
+Active engine: native OpenAI-compatible Fugu API calls against the Sakana endpoint. It uses `SAKANA_API_KEY` or `MMI_OVERLORD_LLM_API_KEY`, records model/request/conversation state in the run registry, and does not depend on Codex-Fugu or OpenCode session routing.
 
 ## 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` and starts API-backed Fugu conversations. `mmi-cli overlord send <target> <message>` appends to each servant's stored conversation, calls `/chat/completions`, captures the assistant text, and advances a real message lifecycle (`queued`, `started`, `completed`, `partial`, `failed`) from the API result.
 
 ## Reference Loading
 
@@ -33,20 +33,25 @@ Read only what the task requires:
 - `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/terminal-leash.md`: servant startup, API conversation routing, shell-surface boundaries, 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/controller-orphan-guard.md`: abrupt close, stale sessions, adoption, exact stop, and uncertainty.
+- `references/fugu-api-engine.md`: native API preflight, conversation persistence, ledger, request timeouts, 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
 
-- 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.
+- **Fugu only — never a substitute pool.** Overlord servants are Fugu (`fugu-ultra` + `fugu`) driven through the native Fugu API. Never satisfy an Overlord run with platform sub-agents, `multi_agent_v1`, generic workers, Codex-Fugu, OpenCode sessions, or any non-Fugu agent pool. If the Fugu API cannot prove the required endpoint, key, and models, stop and report the setup failure; do not simulate Overlord with other agents.
+- Do not spawn servants on an unreadable or undrivable engine.
+- **Probe the native Fugu API before launch.** Verify the API key, base URL, `/models`, `fugu`, and `fugu-ultra` before any servant launch.
+- API servants keep a stored system/user/assistant conversation per servant and use bounded `/chat/completions` calls for startup and redirects.
+- When the Overlord itself uses shell tools, it must use the native current shell for the host: `pwsh` on Windows, `zsh` on macOS, and `bash` on Linux/Unix. Windows `powershell.exe` is not an acceptable Overlord default.
+- **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 the API path before sending real prompts.
+- **Delivery is not execution.** `mmi-cli overlord send` is complete only when the API returns captured servant text or a bounded failure. If the request times out, errors, or returns no assistant text, mark the servant `blocked` 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/controller-orphan-guard.md

@@ -1,33 +1,30 @@
-# Controller And Orphan Guard
+# Run Registry And Orphan Guard
 
-The controller, not conversational memory, owns servants.
+The run registry, not conversational memory, owns servants.
 
-Controller responsibilities:
+Registry responsibilities:
 
-- Spawn servant PTYs.
-- Hold readable/writable handles.
+- Record Fugu API servant conversations.
 - Persist run state under gitignored `tmp/overlord`.
-- Write heartbeat.
-- Tee bounded journals.
+- Tee bounded ledger and event 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.
+- Check model metadata, conversation history, request ids, and last useful signal.
 - 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`
+- `overlord-conversations-live`
+- `conversations-blocked`
+- `resources-owned-alive`
+- `resources-uncertain`
 
 Actions:
 
-- Adopt only with matching run token and recoverable handles.
+- Adopt only with a matching run token and recoverable conversation state.
 - Exact-stop only proven run-owned resources.
 - Leave uncertain resources alone and report them.
-- Never broad-clean by process name or title.
+- Never broad-clean by process name, title, shell name, or provider name.

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

@@ -2,17 +2,17 @@
 
 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.
+- Windows host work uses modern PowerShell (`pwsh`) syntax and native paths.
+- macOS zsh and Linux bash use POSIX syntax for host work.
+- Missing `SAKANA_API_KEY` and `MMI_OVERLORD_LLM_API_KEY` stops startup with setup steps.
+- A bad Fugu API base URL stops startup with setup steps.
+- `GET /models` returning an error stops startup with setup steps.
+- Missing `fugu` or `fugu-ultra` stops startup with setup steps.
+- Startup `/chat/completions` timeout marks the servant `blocked`.
+- Startup API success with no assistant text marks the servant `blocked`.
+- `send all` records one completed or failed result per targeted servant.
+- A redirect timeout marks the message `failed` and does not claim delivery.
+- Previously ACKed servants with failed follow-up requests become `blocked`; stale ACK is rejected.
+- Awaiting-human preserves servant conversation state.
+- `/overlord stop` leaves user-owned terminals, shells, and unrelated provider processes untouched.
 - Ambiguous leftovers are reported as `left-uncertain`.