vibecoding-devtools 1.0.2 → 1.1.0

package/README.md

@@ -10,12 +10,12 @@ instalados das fontes oficiais.
 ## Instalação
 
 ```bash
-npx vibecoding-devtools@1.0.2 install    # instala pelo painel
-npx vibecoding-devtools@1.0.2 update     # reutiliza as escolhas salvas
-npx vibecoding-devtools@1.0.2 uninstall  # remove só o que o kit instalou
+npx vibecoding-devtools@1.1.0 install    # instala pelo painel
+npx vibecoding-devtools@1.1.0 update     # reutiliza as escolhas salvas
+npx vibecoding-devtools@1.1.0 uninstall  # remove só o que o kit instalou
 ```
 
-Alternativa pelo GitHub: `npx github:Or4cu1o/vibecoding-devtools#v1.0.2 install` (aceita os mesmos comandos).
+Alternativa pelo GitHub: `npx github:Or4cu1o/vibecoding-devtools#v1.1.0 install` (aceita os mesmos comandos).
 
 Requer Node 22+ e git. O instalador detecta Claude Code, Codex e Antigravity, mostra o plano e só grava depois da
 confirmação. Use `--dry-run` para apenas conferir o plano. Detalhes no [guia do instalador](docs/installer.md).
@@ -28,7 +28,8 @@ confirmação. Use `--dry-run` para apenas conferir o plano. Detalhes no [guia d
 | [`skills/`](skills/) | triagem de risco, revisão de segurança e operação do Maestri |
 | [`templates/`](templates/) | `AGENTS.md` e `CLAUDE.md` para projetos, e `.coderabbit.yaml` |
 | [Hooks](hooks/README.md) | `secret-scan`, `maestri-protocol` e `full-suite` implementados |
-| [`docs/`](docs/) | instalação, compatibilidade e justificativas das regras |
+| [`team/`](team/README.md) | equipe de 13 agentes para o Maestri (roles, notas, partitura `vibecoding-devtools`), instalada com `npx vibecoding-devtools team` |
+| [`docs/`](docs/) | instalação, compatibilidade, Maestri em máquina remota e justificativas das regras |
 
 O `secret-scan` verifica segredos com gitleaks antes de commits. O `maestri-protocol` valida mensagens e exige o pacote
 Maestri. O `full-suite` aplica um bloqueio contornável a suítes completas em repositórios com CI; para uma execução

package/hooks/maestri-protocol.mjs

@@ -6,9 +6,10 @@ const reason = 'Maestri message must use a valid protocol header or end with the
 export function validMessage(message) {
   const text = message.replace(/\r\n/g, '\n');
   if (text.startsWith('~')) return header.test(text.split('\n')[0]);
-  // Match the skill footer at the end, including its report-back instruction.
-  const footer = text.match(/(?:^|\n)ref: ([^\n]+)\nWhen done, load the maestri-protocol skill and report back with:\nmaestri ask "([^"\n]+)" "~ ([^|\n]+?) \| STATUS \| ([^|\n]+?) \| one-line summary"\nSTATUS is one of DONE, PENDING, BLOCKED, ERROR, ACK\. Details go on the following lines\.\s*$/);
-  return Boolean(footer && footer[1] === footer[4]);
+  // Match the skill footer at the end, including its report-back instruction. Its quotes may be double or single,
+  // each pair matching, so a prompt already wrapped in double quotes can carry the footer unescaped.
+  const footer = text.match(/(?:^|\n)ref: ([^\n]+)\nWhen done, load the maestri-protocol skill and report back with:\nmaestri ask (["'])((?:(?!\2)[^\n])+)\2 (["'])~ ([^|\n]+?) \| STATUS \| ([^|\n]+?) \| one-line summary\4\nSTATUS is one of DONE, PENDING, BLOCKED, ERROR, ACK\. Details go on the following lines\.\s*$/);
+  return Boolean(footer && footer[1] === footer[6]);
 }
 
 function messages(words) {

package/installer/cli.mjs

@@ -10,9 +10,12 @@ import { readState, hashContent } from './state.mjs';
 import { parseFlags, choicesFromFlags, panel, confirmExecution, Cancellation } from './panel.mjs';
 import * as thirdPartyApi from './third-party.mjs';
 import { jsonMergeSituation } from './json-merge.mjs';
+import { envListSituation } from './env-list.mjs';
 import { CODEX_HOOK_APPROVAL } from './hooks.mjs';
+import { teamMain } from './team.mjs';
 
 export const HELP = `Usage: vibecoding-devtools [install|update|detect|uninstall] [flags]
+       vibecoding-devtools team [--roles-only] [--update-roles] [--dry-run]   (Maestri team; see team --help)
 Default command: install. Without a TTY: use --yes to apply or --dry-run to preview.
 Update reuses saved install choices; explicit flags override them. Run install first if no choices are saved.
 Update removes unchanged kit-owned items absent from the new plan; edited and third-party items are retained.
@@ -76,6 +79,10 @@ export function summarizePlan(plan, { home, force = false } = {}) {
       const previous = state.items.find((i) => i.type === action.type && i.destination === action.destination);
       return { ...action, situation: jsonMergeSituation(current, action, previous) };
     }
+    if (action.type === 'env-list') {
+      const previous = state.items.find((i) => i.type === action.type && i.destination === action.destination);
+      return { ...action, situation: envListSituation(current, action, previous) };
+    }
     let desired;
     if (action.type === 'block') {
       const text = current?.toString('utf8') ?? '';
@@ -148,6 +155,7 @@ export async function main(argv = process.argv.slice(2), options = {}) {
     isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY), out = console.log, err = console.error,
     detect = detectAll, choose = panel, confirm = confirmExecution, prepareThirdParty: prepare, thirdParty = thirdPartyApi,
     planBuilder = buildPlan, apply = execute, remove = uninstall } = options;
+  if (argv[0] === 'team') return teamMain(argv.slice(1), { kit, out, err, home });
   let flags;
   let warnings = [];
   let errorCode = 2;

package/installer/codex-maestri.rules

@@ -0,0 +1,13 @@
+# vibecoding-devtools: Maestri commands Codex agents run outside the sandbox without a human prompt.
+# Installed globally as ~/.codex/rules/vibecoding-devtools-maestri.rules when the Maestri pack is selected.
+prefix_rule(pattern = ["maestri", "ask"], decision = "allow")
+prefix_rule(pattern = ["maestri", "check"], decision = "allow")
+prefix_rule(pattern = ["maestri", "list"], decision = "allow")
+prefix_rule(pattern = ["maestri", "recall"], decision = "allow")
+prefix_rule(pattern = ["maestri", "floor", "status"], decision = "allow")
+prefix_rule(pattern = ["maestri", "note", "read"], decision = "allow")
+prefix_rule(pattern = ["maestri", "note", "edit"], decision = "allow")
+prefix_rule(pattern = ["maestri", "portal"], decision = "allow")
+prefix_rule(pattern = ["maestri", "portal", "close"], decision = "forbidden")
+prefix_rule(pattern = ["maestri", "note", "delete"], decision = "forbidden")
+prefix_rule(pattern = ["maestri", "dismiss"], decision = "forbidden")

package/installer/env-list.mjs

@@ -0,0 +1,70 @@
+// Kit values inside one comma-separated string of a JSON settings file's `env` object, such as
+// GATEGUARD_EXEMPT_GLOBS in ~/.claude/settings.json. The rest of the file stays byte for byte; the value keeps the
+// user's entries and spacing (the string is written back with JSON escaping, so escapes such as \u002f decode).
+import { isUtf8 } from 'node:buffer';
+import { append, parse, property, removeChild } from './json-merge.mjs';
+
+function validate(action) {
+  if (typeof action.key !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(action.key) || !Array.isArray(action.values)
+    || !action.values.length || action.values.some((v) => typeof v !== 'string' || !v.trim() || v.includes(','))) {
+    throw new Error('Invalid env list action');
+  }
+}
+
+function locate(text, key) {
+  const root = parse(text);
+  const env = property(root, 'env');
+  if (env && env.node.kind !== 'object') throw new Error('env must be a JSON object');
+  const entry = env && property(env.node, key);
+  if (entry && typeof entry.node.value !== 'string') throw new Error(`env.${key} must be a string`);
+  return { root, env, entry };
+}
+
+// `record` is the state item of an earlier install: its values, the ones the user already had (`preexisting`, never
+// removed) and the containers the kit created. Install adds the missing values and drops values an earlier kit
+// version added and this one no longer lists; remove drops the kit's values.
+export function envListMerge(current, action, record = null, { remove = false } = {}) {
+  validate(action);
+  if (current !== null && !isUtf8(current)) throw new Error('Settings file is not valid UTF-8');
+  const text = current === null ? '{}\n' : current.toString('utf8');
+  const { root, env, entry } = locate(text, action.key);
+  // Raw segments keep the user's spacing; values compare trimmed.
+  const parts = entry ? entry.node.value.split(',') : [];
+  const list = parts.map((v) => v.trim()).filter(Boolean);
+  // A value the user had before the kit first listed it stays theirs, including values a later kit version adds.
+  const preexisting = [...new Set([...(record?.preexisting ?? []),
+    ...action.values.filter((v) => list.includes(v) && !(record?.values ?? []).includes(v))])];
+  const createdPaths = record?.createdPaths ?? [...(entry ? [] : [['env', action.key]]), ...(env ? [] : [['env']])];
+  const wanted = remove ? [] : action.values;
+  const dropped = new Set([...(record?.values ?? []), ...(remove ? action.values : [])]
+    .filter((v) => !preexisting.includes(v) && !wanted.includes(v)));
+  const added = wanted.filter((v) => !list.includes(v));
+  const result = { preexisting, createdPaths };
+  if (!added.length && !list.some((v) => dropped.has(v))) return { ...result, same: true, content: current };
+
+  const kept = parts.filter((v) => !dropped.has(v.trim()));
+  const next = [...(kept.some((v) => v.trim()) ? kept : []), ...added];
+  const created = (keys) => createdPaths.some((p) => p.join('\0') === keys.join('\0'));
+  const joined = next.join(',');
+  let out;
+  if (next.length && entry) out = text.slice(0, entry.node.start) + JSON.stringify(joined) + text.slice(entry.node.end);
+  else if (next.length) {
+    out = env ? append(text, env.node, action.key, joined) : append(text, root, 'env', { [action.key]: joined });
+  } else if (created(['env', action.key])) {
+    out = removeChild(text, env.node, entry);
+    const rest = parse(out);
+    const after = property(rest, 'env');
+    if (created(['env']) && !after.node.children.length) out = removeChild(out, rest, after);
+  } else out = text.slice(0, entry.node.start) + '""' + text.slice(entry.node.end);
+  return { ...result, same: false, content: Buffer.from(out) };
+}
+
+// Same bytes with another value list in the state is an update: the state must stop owning values the kit dropped.
+export const envListStale = (record, action) => JSON.stringify(record?.values) !== JSON.stringify(action.values);
+
+export function envListSituation(current, action, previous) {
+  try {
+    if (envListMerge(current, action, previous).same && !(previous && envListStale(previous, action))) return 'same';
+    return previous ? 'update' : 'new';
+  } catch { return 'conflict'; }
+}

package/installer/execute.mjs

@@ -5,6 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { isUtf8 } from 'node:buffer';
 import { readState, saveState, hashContent, writeAtomic, withLock, kitVersion } from './state.mjs';
 import { mergeJson, jsonMergeSnapshot } from './json-merge.mjs';
+import { envListMerge, envListStale } from './env-list.mjs';
 
 export const START = '<!-- vibecoding-devtools:start -->';
 export const END = '<!-- vibecoding-devtools:end -->';
@@ -17,6 +18,7 @@ const marker = (item) => item.type === 'block' ? item.marker ?? START : null;
 const identity = (item) => item.type === 'command'
   ? JSON.stringify([item.type, item.cmd, item.args, item.cwd, item.cli, item.owner])
   : JSON.stringify([item.type, path.resolve(item.destination), marker(item)]);
+const emptyObject = (bytes) => Object.keys(JSON.parse(bytes.toString('utf8').replace(/^\uFEFF/, ''))).length === 0;
 const confirmed = ({ pending, operation, previous, hashBefore, diskHash, ...item }) => item;
 
 function checkPath(destination) {
@@ -206,8 +208,8 @@ export function execute(plan, { dryRun = false, force = false, home = os.homedir
         });
         return;
       }
-      if (!['copy', 'write', 'block', 'json-merge'].includes(action.type)) throw new Error(`Unknown type: ${action.type}`);
-      if (!['copy', 'json-merge'].includes(action.type) && typeof action.content !== 'string'
+      if (!['copy', 'write', 'block', 'json-merge', 'env-list'].includes(action.type)) throw new Error(`Unknown type: ${action.type}`);
+      if (!['copy', 'json-merge', 'env-list'].includes(action.type) && typeof action.content !== 'string'
         && !(action.type === 'write' && Buffer.isBuffer(action.content))) throw new Error('Action requires text content');
       const destination = path.resolve(action.destination);
       checkPath(destination);
@@ -248,6 +250,18 @@ export function execute(plan, { dryRun = false, force = false, home = os.homedir
         extra = { hash: merged.after.hash, format: action.format, scriptPaths: action.scriptPaths,
           scriptReferences: action.scriptReferences,
           created: previous?.created ?? !st, createdPaths: previous?.createdPaths ?? merged.createdPaths };
+      } else if (action.type === 'env-list') {
+        let merged;
+        try { merged = envListMerge(current, action, previous); }
+        catch (e) { conflict(action, e.message); return; }
+        if (merged.same && !(previous && envListStale(previous, action))) {
+          r.actions.push({ ...action, status: 'same' });
+          return;
+        }
+        // Same bytes still record the current values, so uninstall never takes a value the kit no longer lists.
+        content = merged.same ? current : merged.content;
+        extra = { key: action.key, values: action.values, preexisting: merged.preexisting,
+          created: previous?.created ?? !st, createdPaths: merged.createdPaths };
       } else if (action.type === 'block') {
         const text = current ? utf8(current) : '';
         if (text === null) { conflict(action, 'File is not valid UTF-8'); return; }
@@ -329,7 +343,9 @@ function runtimeRegistration(item, context) {
 
 function removeItems(context, r, items, home) {
   const dryRun = r.dryRun;
-  const isRegistration = (item) => ['block', 'json-merge'].includes(item.type);
+  // Env lists share settings.json with hook registrations; removing them first lets the item that created the file
+  // delete it once it is empty.
+  const isRegistration = (item) => ['block', 'json-merge', 'env-list'].includes(item.type);
   const order = [...items].reverse().sort((a, b) => Number(isRegistration(b)) - Number(isRegistration(a)));
   const { virtualFiles } = context;
   for (const item of order) {
@@ -360,7 +376,14 @@ function removeItems(context, r, items, home) {
         if (!snapshot.count) { context.forget(item); r.actions.push({ ...item, status: 'missing' }); continue; }
         if (snapshot.hash !== item.hash) { r.warnings.push({ item, reason: 'Modified JSON entries; retained' }); continue; }
         remaining = mergeJson(current, item, { remove: true }).content;
-        if (item.created && Object.keys(JSON.parse(remaining.toString('utf8').replace(/^\uFEFF/, ''))).length === 0) remaining = null;
+        if (item.created && emptyObject(remaining)) remaining = null;
+      } else if (item.type === 'env-list') {
+        let merged;
+        try { merged = envListMerge(current, item, item, { remove: true }); }
+        catch (e) { r.warnings.push({ item, reason: `${e.message}; retained` }); continue; }
+        if (merged.same) { context.forget(item); r.actions.push({ ...item, status: 'missing' }); continue; }
+        remaining = merged.content;
+        if (item.created && emptyObject(remaining)) remaining = null;
       } else if (item.type === 'block') {
         const text = utf8(current);
         if (text === null) { r.warnings.push({ item, reason: 'File is not valid UTF-8; retained' }); continue; }

package/installer/json-merge.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { hashContent } from './state.mjs';
 
 // Keep source ranges so edits never reserialize unrelated settings or hooks.
-function parse(text) {
+export function parse(text) {
   JSON.parse(text.replace(/^\uFEFF/, ''));
   let offset = text.charCodeAt(0) === 0xFEFF ? 1 : 0;
   const whitespace = () => { while (/\s/.test(text[offset] ?? '') && offset < text.length) offset++; };
@@ -53,7 +53,7 @@ function parse(text) {
   return root;
 }
 
-const property = (node, key) => node.children.find((child) => child.key === key);
+export const property = (node, key) => node.children.find((child) => child.key === key);
 const normalizePath = (file) => file.replace(/\\/g, '/');
 function ownsHook(hook, action) {
   if (!hook || typeof hook !== 'object') return false;
@@ -115,7 +115,7 @@ export function jsonMergeSnapshot(current, action) {
   return { hash: hashContent(JSON.stringify(entries.map((entry) => entry.fingerprint))), count: entries.length };
 }
 
-function removeChild(text, parent, entry) {
+export function removeChild(text, parent, entry) {
   const index = parent.children.indexOf(entry);
   const next = parent.children[index + 1];
   const previous = parent.children[index - 1];
@@ -150,7 +150,7 @@ function removeEmptyContainers(text, paths) {
   return text;
 }
 
-function append(text, parent, key, value) {
+export function append(text, parent, key, value) {
   const eol = text.includes('\r\n') ? '\r\n' : '\n';
   const unit = text.match(/\n([ \t]+)"/)?.[1] ?? '  ';
   const lineStart = text.lastIndexOf('\n', parent.start) + 1;

package/installer/plan.mjs

@@ -1,11 +1,13 @@
 // Read-only planning performs no writes, network calls, execution or real-home access.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { isUtf8 } from "node:buffer";
 import { readState, hashContent } from "./state.mjs";
 import { convertAntigravityRule, readFrontmatter, buildCodexBlock } from "./convert.mjs";
 import { hookActions } from './hooks.mjs';
 import { jsonMergeSituation } from './json-merge.mjs';
+import { envListSituation } from './env-list.mjs';
 
 const CLIS = ["claude", "codex", "agy"];
 const uniqueList = (items = []) => [...new Set(items)].sort();
@@ -84,6 +86,7 @@ function situationOf(action, items) {
   let previous = items.find((item) => item.type === action.type && samePath(item.destination, action.destination));
   if (previous?.pending && previous.hashBefore === hashContent(current)) previous = previous.previous;
   if (action.type === 'json-merge') return jsonMergeSituation(current, action, previous);
+  if (action.type === 'env-list') return envListSituation(current, action, previous);
   if (action.type === "block") {
     if (!isUtf8(current)) return "conflict";
     const block = extractBlock(current.toString("utf8"));
@@ -135,11 +138,25 @@ export function reconcileUpdate(plan, { home }) {
     item.type === 'block' ? item.marker ?? START : null]);
   const wanted = new Set(actions.filter((a) => a.destination).map(key));
   const removals = state.items.filter((item) => item.owner === 'kit'
-    && ['copy', 'write', 'block', 'json-merge'].includes(item.type) && !wanted.has(key(item)))
+    && ['copy', 'write', 'block', 'json-merge', 'env-list'].includes(item.type) && !wanted.has(key(item)))
     .map((item) => ({ ...item, operation: 'remove', situation: 'remove' }));
   return Object.assign([...removals, ...actions], { warnings: plan.warnings, preparation: plan.preparation });
 }
 
+// ECC's GateGuard asks for facts before the first edit of each file. These trees have no import value and agents
+// write to them all the time: Claude Code's temp directory (scratchpad), its auto memory and the Maestri role folders.
+// The temp directory follows CLAUDE_CODE_TMPDIR as Claude Code documents it: <dir>/claude-<uid> on Unix,
+// <dir>/claude on Windows, with /tmp or the system temp directory as <dir>.
+export function gateguardExemptions({ home, maestri, env = process.env, platform = process.platform,
+  uid = process.getuid?.() }) {
+  const slash = (file) => file.replace(/\\/g, "/").replace(/\/+$/, "");
+  const windows = platform === "win32";
+  const base = slash(env.CLAUDE_CODE_TMPDIR || (windows ? os.tmpdir() : "/tmp"));
+  const temp = windows ? `${base}/claude` : uid == null ? null : `${base}/claude-${uid}`;
+  return [...(temp ? [`${temp}/**`] : []), `${slash(home)}/.claude/projects/*/memory/**`,
+    ...(maestri ? ["**/.maestri/**"] : [])];
+}
+
 export function buildPlan(choices, detection, paths) {
   const { home, kit, ecc, project } = paths;
   if (!home || !kit) throw new Error("paths.home and paths.kit are required");
@@ -206,6 +223,12 @@ export function buildPlan(choices, detection, paths) {
         add("copy", "kit", cli, path.join(kit, "skills", skill.name),
           path.join(destinationSkills, skill.name), null, `Kit skill: ${skill.name}`);
       }
+      // Agents message each other through the maestri CLI, which runs outside Codex's sandbox. The rules go to the
+      // user layer in either scope so every workspace's agents get them.
+      if (cli === "codex" && choices.maestri) {
+        add("copy", "kit", cli, path.join(kit, "installer", "codex-maestri.rules"),
+          path.join(home, ".codex", "rules", "vibecoding-devtools-maestri.rules"), null, "Maestri command rules for Codex");
+      }
     }
     if (eccClis.includes(cli)) {
       const packages = uniqueList(["common", ...(cli === "claude" ? ["web"] : []),
@@ -249,6 +272,13 @@ export function buildPlan(choices, detection, paths) {
     }
   }
   actions.push(...hookActions(choices, { home, kit, project }));
+  // Any ECC on Claude: the ECC plugin brings GateGuard even with the kit's ECC hooks off. The paths are this machine's,
+  // so they go to the user settings in either scope, never to a project's file.
+  if (eccClis.includes("claude")) {
+    actions.push({ type: "env-list", owner: "kit", cli: "claude", destination: path.join(home, ".claude", "settings.json"),
+      key: "GATEGUARD_EXEMPT_GLOBS", values: gateguardExemptions({ home, maestri: choices.maestri }),
+      description: "GateGuard exemptions for scratch, memory and Maestri files" });
+  }
   const plan = actions.map((action) => ({ ...action, situation: situationOf(action, state.items) }));
   if (warnings.length) plan.warnings = warnings;
   return plan;

package/installer/team-checks.mjs

@@ -0,0 +1,86 @@
+// Read-only prerequisites of the team install: the CLIs, the models the launch commands name, and ECC in Claude Code.
+// Everything that touches the machine goes through `tools`, so tests inject fakes instead of running real CLIs.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { findIn, pathDirectories } from './detect.mjs';
+
+const binaryOf = (command) => command.trim().split(/\s+/)[0];
+const modelOf = (command) => command.match(/(?:^|\s)(?:--model|-m)[ =](\S+)/)?.[1];
+
+// The commands the install launches: presets, and agents that carry their own command instead of a preset.
+const launchCommands = (manifest) => [
+  ...manifest.presets.map((p) => ({ label: `preset "${p.name}"`, command: p.command })),
+  ...manifest.agents.filter((a) => a.command).map((a) => ({ label: `agent "${a.name}"`, command: a.command })),
+];
+
+// Model ids a CLI lists: `codex debug models` prints JSON with `slug`; `agy models` prints `<id>\t<name>` lines.
+const MODEL_LISTS = {
+  codex: { source: 'codex debug models', read: (tools) => JSON.parse(tools.codexModels()).models.map((m) => m.slug) },
+  agy: { source: 'agy models', read: (tools) => tools.agyModels().split('\n').filter((l) => l.includes('\t'))
+    .map((l) => l.split(/\s+/)[0]) },
+};
+
+const attempt = (what, fn) => {
+  try {
+    return { value: fn() };
+  } catch (e) {
+    return { problem: `could not run ${what}: ${(e.stderr?.toString().trim() || e.message).split('\n')[0]}` };
+  }
+};
+
+// Missing items, all together; an empty list means the run may start. `rolesOnly` creates roles and launches nothing,
+// so it needs only the maestri binary.
+export function missingPrerequisites(manifest, tools, { maestri = 'maestri', rolesOnly = false } = {}) {
+  const launches = rolesOnly ? [] : launchCommands(manifest);
+  const bins = [...new Set([maestri, ...launches.map((l) => binaryOf(l.command))])];
+  const absent = new Set(bins.filter((bin) => !tools.onPath(bin)));
+  const problems = [...absent].map((bin) => `${bin} is not on PATH`);
+
+  const catalogs = new Map();
+  for (const { label, command } of launches) {
+    const bin = binaryOf(command);
+    const model = modelOf(command);
+    if (absent.has(bin) || !model || !MODEL_LISTS[bin]) continue;
+    if (!catalogs.has(bin)) {
+      const { source, read } = MODEL_LISTS[bin];
+      catalogs.set(bin, attempt(source, () => new Set(read(tools))));
+    }
+    const { value, problem } = catalogs.get(bin);
+    if (problem) {
+      if (!problems.includes(problem)) problems.push(problem);
+    } else if (!value.has(model)) {
+      problems.push(`${label}: model "${model}" is not in ${MODEL_LISTS[bin].source}`);
+    }
+  }
+
+  if (bins.includes('claude') && !absent.has('claude')) {
+    const { value, problem } = attempt('claude plugin list', () => tools.claudePlugins());
+    if (problem) problems.push(problem);
+    else if (!/\becc@/.test(value)) {
+      problems.push('ECC is not installed in Claude Code (claude plugin list shows no ecc@): '
+        + 'the Team Maestro role uses /ecc:plan');
+    }
+  }
+  return problems;
+}
+
+// A path as given, or a name found on PATH (PATHEXT on Windows).
+function onPath(bin, env, platform) {
+  if (/[\\/]/.test(bin)) return fs.existsSync(bin);
+  try {
+    return Boolean(findIn(bin, pathDirectories(env), { env, platform }));
+  } catch {
+    return false;
+  }
+}
+
+const BIG_OUTPUT = 64 * 1024 * 1024;
+const runCli = (bin, args) => execFileSync(bin, args,
+  { encoding: 'utf8', maxBuffer: BIG_OUTPUT, stdio: ['ignore', 'pipe', 'pipe'] });
+
+export const realTools = ({ env = process.env, platform = process.platform } = {}) => ({
+  onPath: (bin) => onPath(bin, env, platform),
+  codexModels: () => runCli('codex', ['debug', 'models']),
+  agyModels: () => runCli('agy', ['models']),
+  claudePlugins: () => runCli('claude', ['plugin', 'list']),
+});