@mutmutco/opencode-mmi 2.56.0 → 2.58.0

package/dist/index.d.ts

@@ -8,7 +8,9 @@ type Config = {
         description?: string;
         agent?: string;
     }>;
+    agent?: Record<string, Record<string, unknown>>;
     permission?: Record<string, unknown> | string;
+    shell?: string;
 };
 type HookOutput = {
     env?: Record<string, string>;
@@ -21,6 +23,7 @@ type ToolInput = {
 type MmiOptions = {
     skillsPath?: string;
     commandAgent?: string;
+    platform?: NodeJS.Platform | string;
 };
 declare function beforeTool(input: ToolInput, output: HookOutput): Promise<void>;
 declare function shellEnv(_input: unknown, output: HookOutput): Promise<void>;

package/dist/index.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const WORKFLOW_SKILLS = [
     'mmi',
@@ -17,6 +18,8 @@ const WORKFLOW_SKILLS = [
 ];
 const DEFAULT_SKILLS_PATH = fileURLToPath(new URL('../skills', import.meta.url));
 const DEFAULT_COMMAND_AGENT = 'build';
+const OVERLORD_CONSULT_AGENT = 'mmi-overlord-consult';
+const OVERLORD_IMPLEMENT_AGENT = 'mmi-overlord-implement';
 // The adapter knows its own version at load (it IS the installed npm package), which is the reliable
 // "installed opencode plugin version" signal doctor reads back via MMI_OPENCODE_PLUGIN_VERSION. Resolve
 // the package's own package.json relative to this compiled module; on any failure return undefined so the
@@ -40,6 +43,76 @@ function addSkillPermission(cfg) {
         cfg.permission.skill = cfg.permission.skill ?? { '*': 'allow' };
     }
 }
+function nativeShell(platform) {
+    if (platform === 'win32')
+        return 'pwsh';
+    if (platform === 'darwin')
+        return 'zsh';
+    return 'bash';
+}
+function isLegacyWindowsPowerShell(shell) {
+    return Boolean(shell && /(?:^|[\\/])powershell(?:\.exe)?$/i.test(shell.trim()));
+}
+function ensureNativeShell(cfg, platform) {
+    if (!cfg.shell || (platform === 'win32' && isLegacyWindowsPowerShell(cfg.shell))) {
+        cfg.shell = nativeShell(platform);
+    }
+}
+function ensureOverlordAgents(cfg) {
+    cfg.agent = cfg.agent ?? {};
+    cfg.agent[OVERLORD_CONSULT_AGENT] = {
+        description: 'MMI Overlord read-only consultation servant.',
+        mode: 'primary',
+        permission: {
+            read: 'allow',
+            list: 'allow',
+            glob: 'allow',
+            grep: 'allow',
+            lsp: 'allow',
+            edit: 'deny',
+            bash: 'deny',
+            task: 'deny',
+            external_directory: 'deny',
+            todowrite: 'deny',
+            question: 'deny',
+            webfetch: 'ask',
+            websearch: 'ask',
+            skill: { '*': 'allow' },
+        },
+    };
+    cfg.agent[OVERLORD_IMPLEMENT_AGENT] = {
+        description: 'MMI Overlord bounded implementation servant.',
+        mode: 'primary',
+        permission: {
+            read: 'allow',
+            list: 'allow',
+            glob: 'allow',
+            grep: 'allow',
+            lsp: 'allow',
+            edit: 'allow',
+            bash: {
+                '*': 'ask',
+                'git status*': 'allow',
+                'git diff*': 'allow',
+                'git show*': 'allow',
+                'git log*': 'allow',
+                'rg *': 'allow',
+                'npm test*': 'allow',
+                'npm run test*': 'allow',
+                'npm --prefix * test*': 'allow',
+                'npm --prefix * run typecheck*': 'allow',
+                'node *': 'allow',
+            },
+            task: 'deny',
+            external_directory: 'deny',
+            todowrite: 'allow',
+            question: 'ask',
+            webfetch: 'ask',
+            websearch: 'ask',
+            skill: { '*': 'allow' },
+        },
+    };
+}
 function uniqueAppend(values, value) {
     return Array.from(new Set([...(values ?? []), value]));
 }
@@ -69,6 +142,8 @@ function ensureConfig(cfg, options) {
         };
     }
     addSkillPermission(cfg);
+    ensureNativeShell(cfg, options.platform);
+    ensureOverlordAgents(cfg);
 }
 function normalizeToolName(name) {
     return String(name ?? '').trim().toLowerCase();
@@ -85,6 +160,15 @@ function isRealEnvPath(filePath) {
         return false;
     return true;
 }
+function normalizePathForCompare(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+}
+function isInsidePath(root, filePath) {
+    const resolved = isAbsolute(filePath) ? filePath : resolve(root, filePath);
+    const rootNorm = normalizePathForCompare(root);
+    const pathNorm = normalizePathForCompare(resolved);
+    return pathNorm === rootNorm || pathNorm.startsWith(`${rootNorm}/`);
+}
 function stripQuoted(command) {
     return command.replace(/'[^']*'/g, ' ').replace(/"[^"]*"/g, ' ');
 }
@@ -175,9 +259,44 @@ function shellBlockReason(command) {
     }
     return undefined;
 }
+function overlordScopeBlockReason(tool, args) {
+    const profile = process.env.MMI_OVERLORD_SERVANT_PROFILE;
+    if (!profile)
+        return undefined;
+    const worktree = process.env.MMI_OVERLORD_WORKTREE;
+    if (!worktree)
+        return 'Overlord servant scope missing MMI_OVERLORD_WORKTREE; refusing tool call.';
+    const mutatingTool = tool === 'write' || tool === 'edit' || tool === 'apply_patch';
+    if (mutatingTool && profile === 'consultation') {
+        return 'Overlord consultation servants are read-only; edits are coordinator-owned.';
+    }
+    const filePath = toolFilePath(args);
+    if (mutatingTool && !filePath)
+        return 'Overlord servant edit target path is missing; refusing tool call.';
+    if (mutatingTool && !isInsidePath(worktree, filePath)) {
+        return `Overlord servant edit outside assigned worktree is refused: ${filePath}`;
+    }
+    if (tool === 'bash') {
+        const command = stripQuoted(String(args.command ?? '')).trim();
+        if (profile === 'consultation')
+            return 'Overlord consultation servants cannot run shell commands; the coordinator supplies bounded evidence.';
+        if (/\bmmi-cli\s+(?:stage|pr|rcand|release|hotfix)\b/i.test(command))
+            return 'Overlord servants cannot own stage, PR, promotion, release, or hotfix commands.';
+        if (/\bgh\s+pr\s+(?:create|merge|close|reopen|ready|review)\b/i.test(command))
+            return 'Overlord servants cannot own PR lifecycle commands.';
+        if (/\b(?:playwright|chrome|chromium|msedge)\b/i.test(command))
+            return 'Overlord servants cannot own browser or Playwright resources.';
+        if (/\b(?:vite|next|npm\s+run\s+(?:dev|start|preview))\b/i.test(command))
+            return 'Overlord servants cannot own shared dev servers.';
+    }
+    return undefined;
+}
 async function beforeTool(input, output) {
     const args = (output.args ?? {});
     const tool = normalizeToolName(input.tool);
+    const overlordReason = overlordScopeBlockReason(tool, args);
+    if (overlordReason)
+        throw new Error(overlordReason);
     if ((tool === 'write' || tool === 'edit' || tool === 'apply_patch') && isRealEnvPath(toolFilePath(args))) {
         throw new Error('Vault only: do not edit or write .env files. Use /secrets for runtime config.');
     }
@@ -196,12 +315,13 @@ async function shellEnv(_input, output) {
 }
 async function compacting(_input, output) {
     output.context = output.context ?? [];
-    output.context.push('MMI continuity: preserve issue/PR refs, saga and North Star anchors, blockers, decisions, verification state, and NEXT.');
+    output.context.push('MMI continuity: preserve issue/PR refs, blockers, decisions, verification state, and NEXT. Saga/North Star anchors are Jervaise-only.');
 }
 async function MmiOpenCodePlugin(_ctx, rawOptions) {
     const options = {
         skillsPath: rawOptions?.skillsPath ?? DEFAULT_SKILLS_PATH,
         commandAgent: rawOptions?.commandAgent ?? DEFAULT_COMMAND_AGENT,
+        platform: rawOptions?.platform ?? process.platform,
     };
     return {
         config: (cfg) => ensureConfig(cfg, options),

package/package.json

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

package/skills/_shared/doctrine.md

@@ -19,14 +19,14 @@ Hard rules:
 - **Verifier (or judge) is never the builder.** Hard lenses run at verifier tier minimum.
 - When the host exposes multiple vendors, prefer maximum spread on each fusion round. Document any gap honestly — never claim fusion ran cross-vendor when only one vendor was available.
 - Invoking `/grind`, `/grind --auto`, or `/build` authorizes the planner, verifier, judge, and synthesizer panels those skills require, within their normal bounds. On Codex, use `multi_agent_v1` for standard panels when that tool is available.
-- A single-vendor host degrades gracefully: different temperatures or repeat passes; still run the synthesizer. Note degradation in saga and halt/end-of-grind reports.
+- A single-vendor host degrades gracefully: different temperatures or repeat passes; still run the synthesizer. For `jervaise`, note degradation in saga and halt/end-of-grind reports; for every other login, note it in the halt/end-of-grind report and the issue/PR record (saga is Jervaise-only).
 
 Use fusion on the hard parts — plan choices, ambiguous specs, security-critical surfaces, verification rounds at checkpoints. Do not spend fusion tokens on trivial slices.
 
 ## Panel evidence contract
 
 - Use the host's multi-agent panel mechanism when it is available. Degrade only when the tool is unavailable, a spawn is denied/null, or the user explicitly disables delegation/panels.
-- State degraded fallback explicitly in saga notes and final reports. A degraded round is evidence with a ceiling, not a normal clean panel.
+- State degraded fallback explicitly: for `jervaise` in saga notes + final reports; for every other login in the final report + issue/PR record (saga is Jervaise-only). A degraded round is evidence with a ceiling, not a normal clean panel.
 - `mmi-cli verify synthesize` is a reconciliation helper for real verifier lane JSON. It must not replace an available host panel, and it must not be fed empty input or controller-authored all-pass stubs.
 - Two stable clean rounds count only when the required verifier process actually produced the lens outputs. Empty, missing, or self-authored pass JSON is invalid fresh-eyes evidence.
 
@@ -56,9 +56,9 @@ Both `/grind` and `/build` self-select one of four effort tiers — **`light` ·
 
 **Prefer the lightest model that clears the bar.** Reach for a heavier model only when the work needs it — a hard plan, an ambiguous spec, a security-critical lens, a failing verify round. Routine builder turns, mechanical edits, and light-tier slices run on a lighter model. Reserve top-tier models for fusion planners, hard lenses, and `ultra`-tier sites. Spending a frontier model on a one-liner is waste, not rigor.
 
-**Fusion single-API models (opencode `fugu` / `fugu-ultra`, `codex-fugu`):** these already integrate multiple models behind one API, so the cross-vendor panel the skills would otherwise spawn is **built into the model**. On a fusion model:
+**Fusion single-API models (opencode `fugu` / `fugu-ultra`):** these already integrate multiple models behind one API, so the cross-vendor panel the skills would otherwise spawn is **built into the model**. On a fusion model:
 
-- **Cap the tier at `light`** — never run higher (`capTierForModel` in `build-policy.ts`). For now only `fugu`, `fugu-ultra` (opencode) and `codex-fugu` are fusion models.
+- **Cap the tier at `light`** — never run higher (`capTierForModel` in `build-policy.ts`). For now only OpenCode `fugu` and `fugu-ultra` are fusion models.
 - **Give them the most straightforward method** — single straight-through pass, **no** multi-agent planner/lens fan-out. The fusion is internal; an external panel is redundant cost.
 - Detect by active model id, or let the opencode plugin pass the signal explicitly when it lands.
 
@@ -74,7 +74,7 @@ Claude Code **2.1.181** hard-caps subagents at **5 levels of nesting depth**; fo
 
 Concrete ownership: only the top-level orchestrator (the skill invoker) launches fusion planners and verify lenses. Sub-agents return JSON or markdown; they do **not** spawn their own sub-panels unless the skill explicitly says otherwise for that one role.
 
-**Sub-agent continuation is host-scoped (#1943/#1956).** `SendMessage` can continue a previously-spawned agent only on hosts that expose it to the top-level orchestrator; it is **not** in a sub-agent's toolset, and Claude Code has surfaced misleading Agent-tool footers for a continuation tool that is not callable there. So a sub-agent never messages or continues a peer. It **returns its result** and the orchestrator either uses a host-exposed continuation tool or re-spawns a fresh sub-agent with a compact handoff packet: issue/PR refs, branch/worktree, changed files, objective, what passed/failed, and exact NEXT. Cross-agent / cross-PC coordination is **`/coop`**, never `SendMessage` or ad-hoc messaging. Keep this narration out of user-facing output — a one-line `saga note` at most.
+**Sub-agent continuation is host-scoped (#1943/#1956).** `SendMessage` can continue a previously-spawned agent only on hosts that expose it to the top-level orchestrator; it is **not** in a sub-agent's toolset, and Claude Code has surfaced misleading Agent-tool footers for a continuation tool that is not callable there. So a sub-agent never messages or continues a peer. It **returns its result** and the orchestrator either uses a host-exposed continuation tool or re-spawns a fresh sub-agent with a compact handoff packet: issue/PR refs, branch/worktree, changed files, objective, what passed/failed, and exact NEXT. Cross-agent / cross-PC coordination is **`/coop`**, never `SendMessage` or ad-hoc messaging. Keep this narration out of user-facing output — for `jervaise`, a one-line `saga note` at most; for every other login, keep it out of user-facing output entirely (saga is Jervaise-only).
 
 ## Classifier-denied spawn handling
 
@@ -83,7 +83,7 @@ Claude Code **2.1.178**: in auto mode, subagent spawns are evaluated by a classi
 **Degraded round — not clean:**
 
 - A denied, null, or missing planner/lens/research sub-agent is a **gap**, not a pass.
-- Log the gap: `mmi-cli saga note "spawn-denied role=<planner|lens|research> round=<n>"`.
+- Log the gap: for `jervaise`, `mmi-cli saga note "spawn-denied role=<planner|lens|research> round=<n>"`; for every other login, record the gap in the halt/end-of-grind report + issue/PR record (saga is Jervaise-only).
 - Surface gaps in halt reports, end-of-grind summaries, and build halt reports.
 - A round with any denied/null spawn does **not** count toward **two synthesis-stable clean rounds**.
 - When aggregating parallel results, use explicit null handling — `.filter(Boolean)` alone is insufficient unless paired with a gap count check; a denied spawn must never inflate a clean count.
@@ -147,7 +147,7 @@ Org-wide session doctrine lives in **`AGENTS.md` § Session workflow** — grind
 - Branch from latest `origin/development` into `../mmi-worktrees/<branch>` — **never edit the main checkout** during grind/build runs.
 - If a generic/native worktree helper would create `.claude/worktrees/`, `.worktrees/`, or another non-Hub path, skip it for MMI org repos and use `mmi-cli worktree create` / `setup`.
 - One worktree per grind/build run until integration boundary; multi-worktree waves merge via `mmi-cli wave land`.
-- Return to the main checkout mid-run only for a new unrelated branch, real base drift, final integrated validation, cleanup after merge, explicit user request, or a broken/unsafe worktree. Otherwise keep implementation, verification, commits, PR prep, saga, and North Star updates in the active worktree.
+- Return to the main checkout mid-run only for a new unrelated branch, real base drift, final integrated validation, cleanup after merge, explicit user request, or a broken/unsafe worktree. Otherwise keep implementation, verification, commits, PR prep, and any allowed continuity updates in the active worktree.
 - A local `/stage` belongs to the active worktree that started it. Do not disrupt a running stage for git bookkeeping alone. Before moving to a different worktree, stop/destroy the stage and recreate it from the new worktree, or warn first when the user's intent is unclear. Linked worktrees share stage state through the git common dir, so a new worktree can still stop the previous local stage.
 - Give each worktree its **own** `node_modules` via clean `npm ci` — never symlink/junction into the main checkout's `node_modules` (junctions can be followed by teardown and destroy the main checkout).
 - **Cross-platform lockfile — validate on the CI OS, not the build OS (#1840).** When a build/grind on **Windows** regenerates `package-lock.json` (any `npm install` — e.g. adding a workspace or devDep), npm 11 **prunes Linux-only optional deps** (`@emnapi/*`, the `@node-rs/argon2` / `@tailwindcss/oxide` `*-wasm32-wasi` fallbacks). Local `npm ci` + the gate then pass on Windows while the Linux CI runner's `npm ci` dies `EUSAGE` (`Missing: @emnapi/core@… from lock file`) in ~11s — **local-OS green never proves a cross-platform lockfile.** Before merge, regenerate **and** validate the lock in a Linux container matching CI's Node (`node:24` at present): `docker run --rm -v "${PWD}:/app" -w /app node:<ci-node> npm install --package-lock-only --ignore-scripts`, then validate with `node_modules`-shadowed anonymous volumes — `docker run --rm -v "${PWD}:/app" -v /app/node_modules -w /app node:<ci-node> sh -c "npm ci && npm run check"`. The container lock is a win32+linux+wasm **superset** that satisfies Linux CI (local Windows `npm ci` may then reject it on an npm-minor mismatch — CI is the gate).
@@ -168,11 +168,13 @@ Until repro proves otherwise:
 
 ## Saga snapshot / resume
 
-Loop memory composes with saga HEAD — enforced via **`mmi-cli saga snapshot`**.
+Loop memory composes with saga HEAD for `jervaise` — enforced via **`mmi-cli saga snapshot`**.
 
-- **Read-first on resume:** `mmi-cli saga snapshot show --kind <grind|build>` (`--json` for machine use). Reconcile with diff + `PanelReport` — never collapsed chat.
-- **Write-last each phase:** one-line `mmi-cli saga note "<audit>"` **plus** `mmi-cli saga snapshot set --kind <grind|build>` (or `--json-file`).
-- **Hygiene:** bounded summary only; one-line phase notes = append-only trail beneath HEAD.
+- **For `jervaise`:**
+  - **Read-first on resume:** `mmi-cli saga snapshot show --kind <grind|build>` (`--json` for machine use). Reconcile with diff + `PanelReport` — never collapsed chat.
+  - **Write-last each phase:** one-line `mmi-cli saga note "<audit>"` **plus** `mmi-cli saga snapshot set --kind <grind|build>` (or `--json-file`).
+  - **Hygiene:** bounded summary only; one-line phase notes = append-only trail beneath HEAD.
+- **For every other login:** skip Saga/North Star commands (they are Jervaise-only); use the issue/PR record + git history as the durable resume surface — re-read the issue body and the merged PRs, not a continuity snapshot.
 
 Grind schema: `skills/grind/templates/saga-snapshot.md`. Build uses `--kind build`.
 

package/skills/bootstrap/SKILL.md

@@ -223,10 +223,10 @@ known. Going forward the thin Lambda adds each new issue to that project on `iss
 `Status: Todo`.
 
 **Register the project for cloud agents.** The same registry META row carries `{name, slug, projectId,
-wikiRepo, repos[]}`; do not append to a committed `projects.json`. This is what makes `wiki-keeper` run for
-the project (the launcher fans one run per registered project, generating its wiki + refreshing its board).
-`kb-keeper`, `saga-keeper`, and `northstar-keeper` are org-wide and need no per-project entry. If attaching this repo to an
-existing project, merge this repo into that project's `repos[]` instead of creating a new project.
+wikiRepo, repos[]}`; do not append to a committed `projects.json`. Repo wikis and doc freshness are owned by
+the repo itself. Saga/North Star maintenance and KB sync are Hub workflows, not per-project agents. If
+attaching this repo to an existing project, merge this repo into that project's `repos[]` instead of creating a
+new project.
 
 ## Step 4 — vault tiers + deploy substrate
 
@@ -338,7 +338,7 @@ collaborator list + the per-branch allowlist are the record — no separate rost
   `.claude/settings.local.json` is local-only.
 - **Reserve the spine filenames.** `AGENTS.md` / `CLAUDE.md` are the org spine — never repo-specific. Seed
   `.cursor/rules/<repo-slug>.mdc` (frontmatter `alwaysApply: true`) with repo-specific agent guidance (what
-  the repo is, services/deps, build/test, conventions). Include the saga startup pattern for non-Claude
+  the repo is, services/deps, build/test, conventions). For `jervaise`, include the saga startup pattern for non-Claude
   agents: `mmi-cli saga health --json`, `mmi-cli saga show`, then explicit `mmi-cli saga note` at handoff or
   meaningful checkpoints. This gives Cursor's setup agent a home so it does not hijack `AGENTS.md`; Cursor
   cloud agents read `.cursor/rules` automatically.

package/skills/build/SKILL.md

@@ -7,7 +7,9 @@ description: Drive a milestone from a finished foundation to merged PRs, autonom
 
 **Shared doctrine:** Read `skills/_shared/doctrine.md` at session start and on resume. Fusion, parallelism, flat fan-out, classifier-denied spawns, blocker tiers, worktree hygiene, #1595 verify+commit, enforcement matrix — single source; do not duplicate here.
 
-You own a milestone or capability from a finished foundation to merged PRs, autonomously. Auto is the default mode and the framing interview is the one routine human touchpoint. After the interview locks decisions to the board and the North Star, you run gateless: fan out parallel sites, raise the effort tier per part, fuse cross-vendor planners on the hard parts, verify in nested sub-loops, and auto-merge each PR into `development` until the frontier is exhausted or a hard-decision blocker parks a site.
+You own a milestone or capability from a finished foundation to merged PRs, autonomously. Auto is the default mode and the framing interview is the one routine human touchpoint. After the interview locks decisions to the board, and to North Star only when the current login is `jervaise`, you run gateless: fan out parallel sites, raise the effort tier per part, fuse cross-vendor planners on the hard parts, verify in nested sub-loops, and auto-merge each PR into `development` until the frontier is exhausted or a hard-decision blocker parks a site.
+
+**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 halt report.
 
 ## Core idea
 
@@ -61,9 +63,9 @@ Heuristics:
 
 **Flags force a tier:** `--light`, `--standard`, `--deep`, `--ultra` override auto-selection for the whole run (explicit override always wins, per `pickEffortTier`).
 
-**Fusion-model cap:** on opencode `fugu` / `fugu-ultra` or `codex-fugu`, cap at `light` and run the straightforward single-pass method — no planner/lens fan-out. See doctrine § Model economy.
+**Fusion-model cap:** on OpenCode `fugu` / `fugu-ultra`, cap at `light` and run the straightforward single-pass method — no planner/lens fan-out. See doctrine § Model economy.
 
-**Announce + log every tier choice.** Print the tier, the signals that drove it, and a one-line "why" before construction starts; `mmi-cli saga note "build tier=<tier> site=<slug> signals=<…> reason=<…>"`. The heuristics are encoded testably in `build-policy.ts` (fixtures lock signals -> tier/parallelism/planner-count/reasoning).
+**Announce + log every tier choice.** Print the tier, the signals that drove it, and a one-line "why" before construction starts. For `jervaise`, `mmi-cli saga note "build tier=<tier> site=<slug> signals=<…> reason=<…>"`; for every other login, record the tier choice in the issue/PR record (saga is Jervaise-only). The heuristics are encoded testably in `build-policy.ts` (fixtures lock signals -> tier/parallelism/planner-count/reasoning).
 
 The tier is the **concurrency ceiling** and the **verification depth floor** for that site. **Fill the cap** — batch independent sites up to it rather than serializing (doctrine § Parallelism). The tier raises the ceiling; it does not lower the parallel bias.
 
@@ -93,28 +95,30 @@ Cover:
 
 **Lock the decisions in:**
 
-1. `mmi-cli northstar push <slug>` with the milestone body + criteria.
+1. For `jervaise`, `mmi-cli northstar push <slug>` with the milestone body + criteria. For everyone else, put the criteria in the issue/PR record.
 2. File or update the umbrella issue for the milestone and any known child issues; **batch-claim everything build will work in ONE call** — `mmi-cli board claim <ref> <ref> … --for <login>` (dedupes + claims in parallel; never one-by-one). (Set urgency with `--priority` — the board Priority **field**, never a `priority:*` label; #416.)
-3. `mmi-cli saga note "build framing: milestone=<…> criteria=<…> out-of-scope=<…> hard-decisions=<…>"`.
-4. **Cost estimate (measure-first).** Run `mmi-cli build estimate` (or `build tier` + mental math) and print the worst-case **agent-call proxy** + ceiling. If projected exceed → lower tier or halt-and-report before going gateless; log `saga note "build cost-estimate units=<n> ceiling=<n> action=<ok|lower-tier|halt>"`. Phase 0 may override `CAMPAIGN_ITERATION_CAP` (~15 orients default) with explicit human approval — log to saga.
-5. Initialize the **in-hand North Star** from `templates/campaign-northstar.md` via `northstar push` — this is campaign SSOT; saga is session handoff.
+3. For `jervaise`, `mmi-cli saga note "build framing: milestone=<…> criteria=<…> out-of-scope=<…> hard-decisions=<…>"`.
+4. **Cost estimate (measure-first).** Run `mmi-cli build estimate` (or `build tier` + mental math) and print the worst-case **agent-call proxy** + ceiling. If projected exceed → lower tier or halt-and-report before going gateless; for `jervaise`, log `saga note "build cost-estimate units=<n> ceiling=<n> action=<ok|lower-tier|halt>"`. Phase 0 may override `CAMPAIGN_ITERATION_CAP` (~15 orients default) with explicit human approval.
+5. For `jervaise`, initialize the **in-hand North Star** from `templates/campaign-northstar.md` via `northstar push` — this is campaign SSOT; saga is session handoff. For everyone else, use the issue/PR as campaign SSOT.
 
 After Phase 0 the loop runs gateless. If the milestone genuinely shifts mid-run, re-interview — do not let the loop redefine the milestone on its own.
 
 ## Loop memory — North Star in hand
 
-**Two-store rule:** North Star (`plans/<slug>.md`) = campaign position; saga = session audit trail. Halt report = projection of the in-hand North Star, not a third source of truth.
+**Two-store rule for `jervaise`:** North Star (`plans/<slug>.md`) = campaign position; saga = session audit trail. Halt report = projection of the in-hand North Star, not a third source of truth. For everyone else, the issue/PR record carries campaign position and audit trail.
 
 The North Star is **campaign working memory**, not a doc read once. **Read → act → write-back** every state transition:
 
-- **Read first:** L0 orient starts with `mmi-cli northstar show <slug>` (or `northstar relevant`), then `mmi-cli saga snapshot show --kind build` for session handoff.
-- **Write last:** after site enter/exit, tier choice, park, solvable-clear, merge, re-frame — `mmi-cli northstar push <slug>` with the canonical structure in `templates/campaign-northstar.md`, then `mmi-cli saga snapshot set --kind build` for session handoff.
+- **For `jervaise`:**
+  - **Read first:** L0 orient starts with `mmi-cli northstar show <slug>` (or `northstar relevant`), then `mmi-cli saga snapshot show --kind build` for session handoff.
+  - **Write last:** after site enter/exit, tier choice, park, solvable-clear, merge, re-frame — `mmi-cli northstar push <slug>` with the canonical structure in `templates/campaign-northstar.md`, then `mmi-cli saga snapshot set --kind build` for session handoff.
+- **For every other login:** campaign position lives in the issue/PR record — re-read the milestone issue + linked PRs at orient, and write state transitions back as issue comments / PR descriptions (saga + North Star are Jervaise-only).
 
 Canonical sections: Milestone + slug; Criteria; Done last turn / In progress / Blocked / Next frontier; Tier ledger; Verification ceiling per site.
 
 **Hygiene:** short + structured. If state outgrows a scannable snapshot, graduate or split the milestone — do not grow the file.
 
-**Re-frame:** North Star edit first, then `saga note --decision`, then continue. When a halt fires (iteration cap, cost ceiling, hard-decision), record the reason in Blocked / Next frontier before the halt report.
+**Re-frame:** for `jervaise`, North Star edit first, then `saga note --decision`, then continue; for every other login, edit the milestone issue first, then note the decision in the issue/PR record. When a halt fires (iteration cap, cost ceiling, hard-decision), record the reason in Blocked / Next frontier before the halt report.
 
 **Re-interview triggers** (always pause for these; never let the loop absorb them):
 
@@ -129,7 +133,7 @@ Build is loops inside loops. **Every loop must improve understanding** of the pr
 
 The nesting:
 
-- **L0 — Campaign loop (frontier).** Read the in-hand North Star **first**; orient on board + research; select the unblocked frontier; pick a site; construct; learn; write North Star back; re-orient. Runs until **externally confirmed** frontier exhaustion or a halt condition (iteration cap, cost ceiling, hard-decision). Default **~15** L0 orients (`CAMPAIGN_ITERATION_CAP`); on cap without external exhaustion → halt-and-report (honest halt ≠ failure).
+- **L0 — Campaign loop (frontier).** For `jervaise`, read the in-hand North Star **first**; for every other login, re-read the milestone issue + linked PRs. Orient on board + research; select the unblocked frontier; pick a site; construct; learn; write the campaign position back (North Star for `jervaise`, issue/PR record for everyone else); re-orient. Runs until **externally confirmed** frontier exhaustion or a halt condition (iteration cap, cost ceiling, hard-decision). Default **~15** L0 orients (`CAMPAIGN_ITERATION_CAP`); on cap without external exhaustion → halt-and-report (honest halt ≠ failure).
 - **L1 — Site loop (slice -> merge).** For one site: plan, build, checkpoint-verify in sub-loops, fix, re-verify, open PR, watch CI, merge into `development`, then tick the site's line in the milestone umbrella (`mmi-cli issue check <umbrella> --item "<text>"`; native sub-issues auto-tick on close) so it doesn't read 0% after slices shipped (#1796). Each L1 turn rolls back into L0.
 - **L2 — Checkpoint verification sub-loops.** Inside a site, at each meaningful increment (not just at the end), spin a verification sub-loop. The effort tier sets how many checkpoints and how deep each one runs.
 - **L3 — Fusion-panel rounds.** Inside a checkpoint, use the host multi-agent panel mechanism when available, then run parallel lenses -> synthesizer -> triage; repeat until **two consecutive synthesis-stable clean rounds** (identical blocker `id` sets; an empty blocker set counts as stable). Degraded fallback follows shared doctrine and must be reported. Empty or controller-authored all-pass lens stubs are invalid evidence. Each blocker/clean verdict must cite an **objective signal** when one exists (failing test, typecheck error, sandbox repro, cited source) — not bare judgment. **Terminal done hierarchy:** (1) repo checks / CI green, (2) two stable clean rounds, (3) merge authority — never skip layer 1.
@@ -146,17 +150,18 @@ packages, plugin bundles, seeds) need a **consumer-path checkpoint**, not just a
 **Worktree tests:** see shared doctrine — tests must run with `cwd` set to the worktree; orchestrator reproduces subagent green before merge.
 
 **Stay in the active worktree.** For a coherent build site or same-repo wave, keep implementation,
-verification, commits, PR prep, saga, and North Star updates in the selected feature worktree until
-the site/wave reaches its integration boundary. Do not bounce to the main checkout for routine status,
-fast-forward, or reorientation work. Switch mid-run only for a new unrelated branch, real base drift,
+verification, commits, PR prep, and (for `jervaise`) saga + North Star updates in the selected feature
+worktree until the site/wave reaches its integration boundary. For every other login, the issue/PR
+record carries campaign position — keep that current instead. Do not bounce to the main checkout for
+routine status, fast-forward, or reorientation work. Switch mid-run only for a new unrelated branch, real base drift,
 final integrated validation, cleanup after merge, explicit user request, or a broken/unsafe worktree.
 Keep any local `/stage` attached to the active worktree; do not disrupt it for git bookkeeping alone.
 
 **Delegated verify+commit:** see shared doctrine § Delegated verify+commit (#1595).
 
-**Re-framing rule:** when L0 orient detects that the problem has shifted under you (a dependency landed differently, a spec was wrong, a downstream effect was missed), **North Star edit first**, then `saga note --decision`, then update the board, then continue. Never let the loop quietly redefine the milestone.
+**Re-framing rule:** when L0 orient detects that the problem has shifted under you (a dependency landed differently, a spec was wrong, a downstream effect was missed), **North Star edit first** (or, for non-`jervaise`, the milestone issue first), then for `jervaise` `saga note --decision`, then update the board, then continue. Never let the loop quietly redefine the milestone.
 
-**Ralph Wiggum guard:** distrust the loop's own "I'm done" signal. **Frontier exhausted** requires external confirmation: in-hand North Star shows empty next frontier, no open unblocked board claims, no in-flight PRs for this milestone, no unresolved parked sites — checked via `mmi-cli board` / `gh` and `mmi-cli build frontier`, not self-belief. Same orient picture twice = stall signal (counts toward stale orients).
+**Ralph Wiggum guard:** distrust the loop's own "I'm done" signal. **Frontier exhausted** requires external confirmation: for `jervaise`, the in-hand North Star shows an empty next frontier; for every other login, the milestone issue shows no open unblocked sub-items. Either way, no open unblocked board claims, no in-flight PRs for this milestone, no unresolved parked sites — checked via `mmi-cli board` / `gh` and `mmi-cli build frontier`, not self-belief. Same orient picture twice = stall signal (counts toward stale orients).
 
 ## Research is first-class
 
@@ -164,7 +169,7 @@ When a decision needs grounding — an API contract, a third-party behavior, a s
 
 - Research is **not a detour from building** — it is part of building.
 - Default research budget: 3 queries per spike, hard cap on round trips, allow/deny lists honored (no benchmark-leak domains in verify-time search).
-- Saga-log every spike: `mmi-cli saga note "build research spike=<…> sources=<…> conclusion=<…>"`.
+- Saga-log every spike (for `jervaise`): `mmi-cli saga note "build research spike=<…> sources=<…> conclusion=<…>"`. For every other login, record the spike conclusion in the issue/PR record (saga is Jervaise-only).
 
 ## Authority + guardrails
 
@@ -174,8 +179,8 @@ Non-negotiable, in priority order:
 - **No-CI repos (#1432).** Run `mmi-cli pr ci-policy --json` before polling. When `policy` is `no-ci`, local verify satisfies terminal layer 1 — merge after local verify. **`(Recommended)` `mmi-cli pr land <n>`** runs the full path. After land, that branch's worktree + branch cleanup is automatic (#1606); for serialized same-repo waves, do not land every issue separately if the active shared worktree is meant to continue. When the user explicitly wants the linked worktree/stage to continue across a same-session batch boundary, use `mmi-cli pr land <n> --preserve-worktree` and clean up the local branch/worktree/stage at the batch end (#1888).
 - **Worktree / node_modules:** see shared doctrine.
 - **Claim `--for <login>`.** Resolve the human from `mmi-cli whoami` or the session banner. Never claim as the bot.
-- **Saga note every phase.** Drop a one-line `mmi-cli saga note "<…>"` after Phase 0, each L0 orient, each tier choice, each L1 site enters/exits, every parked site, and at the halt report.
-- **North Star in hand each L0 turn.** `mmi-cli northstar show <slug>` first; `mmi-cli saga snapshot show --kind build` for handoff; write back via `northstar push` + `saga snapshot set --kind build`.
+- **Saga note every phase (for `jervaise`).** Drop a one-line `mmi-cli saga note "<…>"` after Phase 0, each L0 orient, each tier choice, each L1 site enters/exits, every parked site, and at the halt report. For every other login, record these transitions in the issue/PR record (saga is Jervaise-only).
+- **North Star in hand each L0 turn (for `jervaise`).** `mmi-cli northstar show <slug>` first; `mmi-cli saga snapshot show --kind build` for handoff; write back via `northstar push` + `saga snapshot set --kind build`. For every other login, re-read the milestone issue + linked PRs at each orient (North Star is Jervaise-only).
 - **Two-tier vault only.** `/secrets` — never env files. Harness: `vault-edit-gate.mjs` on Claude Code (see enforcement matrix).
 - **No self-escalation.** Privileged ops → board issue for master.
 - **No fabrication.** Source-of-truth links, paths, CLI flags only.

package/skills/build/references/loops.md

@@ -10,4 +10,4 @@ file holds the per-level "deepened understanding" tests and the distribution-chu
 - **L2** — the checkpoint exposed something the plan missed (a coupling, a contract, a perf cliff, a failure mode). A checkpoint that just confirms "no blockers found" without surfacing one new fact is suspect — widen the next L2.
 - **L3** — the fusion-panel round produced a `PanelReport` whose `consensus`, `contradictions`, `blind_spots`, and `unique_insights` actually move the model of the change. Two clean rounds with identical empty blocker sets prove stability; two clean rounds with the same shallow lens write-ups prove only that the panel is asleep.
 
-**Distribution chunks need consumer verification.** When any site, slice, or task ships an artifact consumed outside its source repo — shadcn registry items, npm packages, generated plugin bundles, scaffold seeds, or any publish/install surface — an in-repo build is not enough. Add a checkpoint that simulates the consumer path (`shadcn add`, `npm pack` + install, scaffold into a scratch app, or equivalent) and typechecks/runs the consumer. If a full simulation is unavailable, do both of these before merge: research the installer's rewrite/resolution rules, and verify every runtime dependency is declared, including CSS/token/theme layers. Log the exact consumer lens and its ceiling in the saga.
+**Distribution chunks need consumer verification.** When any site, slice, or task ships an artifact consumed outside its source repo — shadcn registry items, npm packages, generated plugin bundles, scaffold seeds, or any publish/install surface — an in-repo build is not enough. Add a checkpoint that simulates the consumer path (`shadcn add`, `npm pack` + install, scaffold into a scratch app, or equivalent) and typechecks/runs the consumer. If a full simulation is unavailable, do both of these before merge: research the installer's rewrite/resolution rules, and verify every runtime dependency is declared, including CSS/token/theme layers. For `jervaise`, log the exact consumer lens and its ceiling in the saga; for every other login, log it in the issue/PR record (saga is Jervaise-only).

package/skills/build/references/worked-example.md

@@ -4,8 +4,8 @@ Illustrative walkthrough of how the `/build` loop chews through one real milesto
 autopilot. The slice names and issue refs are illustrative; the real ones belong to the milestone's
 own North Star.
 
-- **Phase 0 — Framing.** Lock the milestone: "ship the Katip v1.0 pipeline body end-to-end on top of the finished foundation." Criteria: every slice green to `development`; vocab pack landed; live-Recall integration scoped (not done). Hard-decision territory: slice-B (`#192`) depends on `#156` ratify + a live-Recall field that needs a human call. North Star push; saga note; out-of-scope = the live-Recall integration itself.
-- **L0 orient (first turn).** Read North Star, scan the board for unblocked items, run a brief research spike on the `#156` ratify state. Inventory: slice-F machinery is the foundation; slices C/D/E run on default choices; vocab pack is parallel-safe; slice-B is blocked on a hard decision.
+- **Phase 0 — Framing.** Lock the milestone: "ship the Katip v1.0 pipeline body end-to-end on top of the finished foundation." Criteria: every slice green to `development`; vocab pack landed; live-Recall integration scoped (not done). Hard-decision territory: slice-B (`#192`) depends on `#156` ratify + a live-Recall field that needs a human call. For `jervaise`: North Star push + saga note; for every other login, record the framing in the issue/PR record (saga + North Star are Jervaise-only). Out-of-scope = the live-Recall integration itself.
+- **L0 orient (first turn).** For `jervaise`, read the in-hand North Star (`northstar show`); for every other login, re-read the milestone issue + linked PRs. Scan the board for unblocked items, run a brief research spike on the `#156` ratify state. Inventory: slice-F machinery is the foundation; slices C/D/E run on default choices; vocab pack is parallel-safe; slice-B is blocked on a hard decision.
 - **Partition the frontier (buildability + effort tier).** Three groups fall out:
   - **Group 1 — foundational, buildable.** owner_email machinery, `#159`, slice-F machinery. Effort tier **deep**: foundational, one wrong call cascades.
   - **Group 2 — slices on default choices, buildable.** Slices C, D, E. Effort tier **standard**: bounded risk, real but not architectural.

package/skills/build/templates/campaign-northstar.md

@@ -1,5 +1,7 @@
 # Campaign North Star — in-hand template
 
+**Jervaise-only artifact.** This template is for `jervaise` (saga + North Star are Jervaise-only continuity tools). For every other login, campaign position lives in the issue/PR record — do not use this template or `mmi-cli northstar`.
+
 Short, structured campaign working memory. Keep scannable; if this outgrows one screen, graduate or split the milestone.
 
 ```markdown

package/skills/coop/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: coop
-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.
+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
 
-Slack-first coordination for parallel agents in different worktrees, IDEs, PCs, or repos.
+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
@@ -17,21 +17,93 @@ Slack-first coordination for parallel agents in different worktrees, IDEs, PCs,
 ## When not to use
 
 - Serial merge train → use `wave land`
-- Session transfer → use `/handoff`
+- 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 proof issue + posts `COOP_START` in `#mmi-agents`):
+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** (joins the `#mmi-agents` coordination chat):
+**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 and information exchange** (substance in `#mmi-agents`; GitHub gets proof/context only):
@@ -42,21 +114,19 @@ 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
 
@@ -64,7 +134,12 @@ Hub dispatches wake on every coop message targeting joiners:
 - 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