@jmanuelcorral/openteam 0.9.1 → 0.9.2

package/README.es.md

@@ -819,7 +819,7 @@ Consulta [docs/compatibility.md](docs/compatibility.md). Resumen verificado el `
 
 | Superficie | Versión / contrato |
 | --- | --- |
-| openteam | `0.9.1`; versión actual del paquete |
+| openteam | `0.9.2`; versión actual del paquete |
 | `@opencode-ai/plugin` | `1.18.19` |
 | `@opencode-ai/sdk` | `1.18.19` |
 | Hook de routing | `chat.message`; no `chat.params` para cambiar modelo |

package/README.md

@@ -700,7 +700,7 @@ See [docs/compatibility.md](docs/compatibility.md). Verified summary as of `2026
 
 | Surface | Version / contract |
 | --- | --- |
-| openteam | `0.9.1`; current package version |
+| openteam | `0.9.2`; current package version |
 | `@opencode-ai/plugin` | `1.18.19` |
 | `@opencode-ai/sdk` | `1.18.19` |
 | Routing hook | `chat.message`; not `chat.params` for model changes |

package/dist/cli.js

@@ -205,7 +205,7 @@ var LEGACY_TEAM_ROLE_ALIASES = {
   basher: "routing-cost",
   linus: "tester"
 };
-var KNOWN_NON_WORKER_ROLE_IDS = ["openteam"];
+var KNOWN_NON_WORKER_ROLE_IDS = ["orchestrator", "openteam"];
 function isKnownNonWorkerRole(roleID) {
   return KNOWN_NON_WORKER_ROLE_IDS.includes(roleID);
 }
@@ -8648,22 +8648,70 @@ function buildOrchestratorAgent(frontier, options = {}) {
     "1. When you create the team for the first time, **choose a thematic universe**",
     "   (e.g. a film, series, comic or mythology). If the user has a preference,",
     "   ask them for it; if not, propose one and move forward without blocking work.",
-    "2. Give each subagent the **name of a character** from that universe; the",
-    "   file name (`.opencode/agent/<name>.md`) is its alias for",
+    "2. Give each subagent an `agentName`: the **name of a character** from that universe;",
+    "   the file name (`.opencode/agent/<agentName>.md`) is its alias for",
     "   `@mention`, and its role is clear from the `description`.",
-    `3. **Register the cast** in \`${OPENTEAM_ROSTER_PATH}\` (universe + table`,
-    "   name → role → model) so that the names **persist** across sessions.",
-    "   This file goes **outside** `.opencode/agent/` (otherwise opencode would load it",
-    "   as a phantom agent). Always reuse the same cast; do not re-cast",
-    "   without reason.",
+    "3. Give each entry a `roleID`: the stable functional routing key. `roleID` is",
+    "   **not** the themed name. Worked example: C-3PO as the scribe is",
+    '   `{ "roleID": "scribe", "agentName": "c3po" }`, never',
+    '   `{ "roleID": "c3po", "agentName": "c3po" }`.',
+    "4. Prefer existing curated `roleID` keys when they fit:",
+    "   `architect`, `integration`, `tester`, `reviewer`, `local-runtime`,",
+    "   `routing-cost` (plus the guaranteed `orchestrator`, `guardian`,",
+    "   `scribe`, `ralph`). The roleID space is open: use free-form project",
+    "   roleIDs only when no curated role fits.",
+    `5. **Register the cast** in \`${OPENTEAM_ROSTER_PATH}\` so the names persist`,
+    "   across sessions. This file goes **outside** `.opencode/agent/` (otherwise",
+    "   opencode would load it as a phantom agent). Always reuse the same cast;",
+    "   do not re-cast without reason.",
+    "",
+    "## Roster file format",
+    "",
+    "Write the roster as Markdown with exactly one fenced `json` block matching",
+    "`{ universe, entries: [{ roleID, agentName }] }`. Do not write a table.",
+    "Minimal parseable example:",
+    "",
+    "# openteam roster",
+    "",
+    "Universe: star-wars",
+    "",
+    "```json",
+    "{",
+    '  "universe": "star-wars",',
+    '  "entries": [',
+    "    {",
+    '      "roleID": "orchestrator",',
+    '      "agentName": "openteam"',
+    "    },",
+    "    {",
+    '      "roleID": "guardian",',
+    '      "agentName": "leia"',
+    "    },",
+    "    {",
+    '      "roleID": "scribe",',
+    '      "agentName": "c3po"',
+    "    },",
+    "    {",
+    '      "roleID": "ralph",',
+    '      "agentName": "r2d2"',
+    "    },",
+    "    {",
+    '      "roleID": "tester",',
+    '      "agentName": "rex"',
+    "    }",
+    "  ]",
+    "}",
+    "```",
     "",
     "## How to create the team when it does not exist",
     "",
     "1. Analyze the goal and explore the repository (`read`/`glob`/`grep`).",
     "2. Break the request into tasks and design the **minimal team** needed:",
-    "   define only the roles the work requires (e.g. architect, backend,",
-    "   frontend, reviewer, tester, docs). Do not invent roles you will not use.",
-    "3. Create each subagent **on demand** by writing `.opencode/agent/<name>.md`:",
+    "   define only the roles the work requires. Reuse curated roleIDs such as",
+    "   `architect`, `integration`, `reviewer`, `tester`, `local-runtime` and",
+    "   `routing-cost`; use custom roleIDs for uncovered project specialties.",
+    "   Do not invent roles you will not use.",
+    "3. Create each subagent **on demand** by writing `.opencode/agent/<agentName>.md`:",
     "   - Frontmatter: `description` (required, include role and universe),",
     "     `mode: subagent`, `temperature`, `permission` with the minimum needed,",
     "     and `model` **optional**.",
@@ -8684,8 +8732,10 @@ function buildOrchestratorAgent(frontier, options = {}) {
     "",
     "## Standard team roles",
     "",
-    "Besides the project-specific roles, include these standard roles",
-    "(create them on demand, with their universe name) when they add value:",
+    "Every roster MUST include these guaranteed canonical roleIDs exactly:",
+    "`orchestrator`, `guardian`, `scribe`, and `ralph`. Map `orchestrator` to",
+    "agentName `openteam` (the primary agent). Create the `guardian`, `scribe`,",
+    "and `ralph` subagent files on demand with their themed `agentName` values:",
     "",
     "- **scribe** — the team's silent memory. Records decisions and",
     "  learnings in a shared log (`.opencode/openteam/decisions.md`) without",
@@ -9896,16 +9946,165 @@ var RosterSchema = z17.object({
   universe: z17.string().min(1),
   entries: z17.array(RosterEntrySchema)
 }).strict();
+var ROSTER_JSON_FENCE = /```json\s*([\s\S]*?)```/;
+
+class RosterParseError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RosterParseError";
+    this.code = code;
+  }
+}
+function parseRoster(text2) {
+  const result = parseRosterResult(text2);
+  if (!result.ok) {
+    throw result.error;
+  }
+  return result.roster;
+}
+function parseRosterResult(text2) {
+  const match = ROSTER_JSON_FENCE.exec(text2);
+  if (match === null || match[1] === undefined) {
+    return {
+      ok: false,
+      error: new RosterParseError("missing-json-block", "openteam roster: no JSON block found in roster file")
+    };
+  }
+  let data;
+  try {
+    data = JSON.parse(match[1]);
+  } catch (error) {
+    return {
+      ok: false,
+      error: new RosterParseError("malformed-json", `openteam roster: malformed JSON in roster file: ${String(error)}`)
+    };
+  }
+  const parsed = RosterSchema.safeParse(data);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: new RosterParseError("invalid-roster-schema", `openteam roster: invalid roster schema: ${parsed.error.message}`)
+    };
+  }
+  return { ok: true, roster: parsed.data };
+}
 var GUARANTEED_ROLE_IDS = [
   "orchestrator",
   "guardian",
   "scribe",
   "ralph"
 ];
+var GUARANTEED_ROLE_DEFAULT_AGENT_NAMES = {
+  orchestrator: "openteam",
+  guardian: "guardian",
+  scribe: "scribe",
+  ralph: "ralph"
+};
+function defaultAgentNameForGuaranteedRole(roleID) {
+  return GUARANTEED_ROLE_DEFAULT_AGENT_NAMES[roleID];
+}
+function isGuaranteedRoleID(roleID) {
+  return GUARANTEED_ROLE_IDS.includes(roleID);
+}
 function missingGuaranteedRoles(roster) {
   const present = new Set(roster.entries.map((entry) => entry.roleID));
   return GUARANTEED_ROLE_IDS.filter((roleID) => !present.has(roleID));
 }
+function isRoleProfileLike(value) {
+  return typeof value === "object" && value !== null && "roleID" in value && "defaultTier" in value;
+}
+function configuredRolesFromAuditInput(input) {
+  if ("configuredRoles" in input && !isRoleProfileLike(input.configuredRoles)) {
+    return input.configuredRoles;
+  }
+  return input;
+}
+function auditRoster(rosterOrText, configuredRolesOrOptions = {}) {
+  const configuredRoles = configuredRolesFromAuditInput(configuredRolesOrOptions);
+  if (typeof rosterOrText === "string") {
+    const parsed = parseRosterResult(rosterOrText);
+    if (!parsed.ok) {
+      return {
+        findings: [
+          {
+            kind: "unparseable-roster",
+            roleID: "roster",
+            code: parsed.error.code,
+            message: parsed.error.message
+          }
+        ],
+        hasAllGuaranteedRoles: false,
+        missingGuaranteedRoleIDs: [],
+        unprofiledRoleEntries: [],
+        misassignedGuaranteedRoleEntries: []
+      };
+    }
+    return auditParsedRoster(parsed.roster, configuredRoles);
+  }
+  return auditParsedRoster(rosterOrText, configuredRoles);
+}
+function auditParsedRoster(roster, configuredRoles) {
+  const missingGuaranteedRoleIDs = missingGuaranteedRoles(roster);
+  const missing = new Set(missingGuaranteedRoleIDs);
+  const findings = missingGuaranteedRoleIDs.map((roleID) => ({
+    kind: "missing-guaranteed-role",
+    roleID
+  }));
+  const unprofiledRoleEntries = [];
+  const misassignedGuaranteedRoleEntries = [];
+  roster.entries.forEach((entry) => {
+    const profile = getRoleProfile(entry.roleID, configuredRoles);
+    if (profile === undefined && !isKnownNonWorkerRole(entry.roleID)) {
+      unprofiledRoleEntries.push({
+        roleID: entry.roleID,
+        agentName: entry.agentName,
+        severity: "info"
+      });
+      findings.push({
+        kind: "unresolved-role-profile",
+        roleID: entry.roleID,
+        agentName: entry.agentName
+      });
+    }
+    if (isGuaranteedRoleID(entry.agentName) && entry.roleID !== entry.agentName && missing.has(entry.agentName)) {
+      misassignedGuaranteedRoleEntries.push({
+        roleID: entry.roleID,
+        agentName: entry.agentName,
+        missingRoleID: entry.agentName,
+        reason: "agentNameMatchesMissingGuaranteedRole"
+      });
+      findings.push({
+        kind: "non-canonical-role-id",
+        roleID: entry.roleID,
+        agentName: entry.agentName,
+        canonicalRoleID: entry.agentName
+      });
+      return;
+    }
+    if (profile !== undefined && isGuaranteedRoleID(profile.roleID) && profile.roleID !== entry.roleID && missing.has(profile.roleID)) {
+      misassignedGuaranteedRoleEntries.push({
+        roleID: entry.roleID,
+        agentName: entry.agentName,
+        missingRoleID: profile.roleID,
+        reason: "roleIDResolvesToMissingGuaranteedRole"
+      });
+      findings.push({
+        kind: "non-canonical-role-id",
+        roleID: entry.roleID,
+        agentName: entry.agentName,
+        canonicalRoleID: profile.roleID
+      });
+    }
+  });
+  return {
+    findings,
+    hasAllGuaranteedRoles: missingGuaranteedRoleIDs.length === 0,
+    missingGuaranteedRoleIDs,
+    unprofiledRoleEntries,
+    misassignedGuaranteedRoleEntries
+  };
+}
 function enforceGuaranteedRoles(roster) {
   const missing = missingGuaranteedRoles(roster);
   if (missing.length === 0) {
@@ -9913,7 +10112,7 @@ function enforceGuaranteedRoles(roster) {
   }
   const added = missing.map((roleID) => ({
     roleID,
-    agentName: roleID
+    agentName: defaultAgentNameForGuaranteedRole(roleID)
   }));
   return { universe: roster.universe, entries: [...roster.entries, ...added] };
 }
@@ -10346,6 +10545,77 @@ function diagnosticsSection(diagnostics) {
   lines.push("    note: plugin diagnostics are bounded classes recorded instead of writing to the opencode TUI console.");
   return lines;
 }
+function rosterEntryText(entry) {
+  return entry.agentName === undefined ? `"${entry.roleID}"` : `"${entry.roleID}" (agentName "${entry.agentName}")`;
+}
+function canonicalRoleID(entry) {
+  return entry.canonicalRoleID ?? entry.missingRoleID;
+}
+function legacyRosterFindings(audit) {
+  const findings = [];
+  for (const roleID of audit.missingGuaranteedRoleIDs ?? []) {
+    findings.push({ kind: "missing-guaranteed-role", roleID });
+  }
+  for (const entry of audit.misassignedGuaranteedRoleEntries ?? []) {
+    const canonical2 = canonicalRoleID(entry);
+    findings.push({
+      kind: "non-canonical-role-id",
+      roleID: entry.roleID,
+      ...entry.agentName !== undefined ? { agentName: entry.agentName } : {},
+      ...canonical2 !== undefined ? { canonicalRoleID: canonical2 } : {}
+    });
+  }
+  for (const entry of audit.unprofiledRoleEntries ?? []) {
+    findings.push({
+      kind: "unresolved-role-profile",
+      roleID: entry.roleID,
+      ...entry.agentName !== undefined ? { agentName: entry.agentName } : {}
+    });
+  }
+  return findings;
+}
+function rosterHealthSection(audit, loadError, rosterRoleCount) {
+  const auditFindings = audit?.findings ?? legacyRosterFindings(audit ?? {});
+  const unparseable = auditFindings.find((finding) => finding.kind === "unparseable-roster");
+  const unparseableMessage = loadError ?? unparseable?.message;
+  if (unparseableMessage !== undefined) {
+    return [
+      "  roster health:",
+      `    ✗ unparseable roster: ${OPENTEAM_ROSTER_PATH} — ${unparseableMessage}`,
+      "      problem: the roster is present but is not machine-readable by openteam.",
+      "      remedy: keep any human notes outside the JSON fence, add one fenced `json` block containing `{ universe, entries: [{ roleID, agentName }] }`, then re-run `openteam doctor`."
+    ];
+  }
+  if (audit === undefined) {
+    return [];
+  }
+  const missing = auditFindings.filter((finding) => finding.kind === "missing-guaranteed-role").map((finding) => finding.roleID);
+  const misassigned = auditFindings.filter((finding) => finding.kind === "non-canonical-role-id");
+  const unprofiled = auditFindings.filter((finding) => finding.kind === "unresolved-role-profile");
+  if (missing.length === 0 && misassigned.length === 0 && unprofiled.length === 0) {
+    return rosterRoleCount === undefined ? [] : [
+      "  roster health:",
+      `    ✓ ${OPENTEAM_ROSTER_PATH} read (${rosterRoleCount} roles); guaranteed roles present.`
+    ];
+  }
+  const lines = ["  roster health:"];
+  if (missing.length > 0) {
+    lines.push(`    ✗ missing guaranteed roleID(s): ${missing.join(", ")}`);
+    lines.push(`      remedy: edit ${OPENTEAM_ROSTER_PATH}'s JSON block to add these canonical roleIDs with their themed agentName values; keep roleID canonical, e.g. { "roleID": "scribe", "agentName": "c3po" }.`);
+  }
+  for (const entry of misassigned) {
+    const canonical2 = canonicalRoleID(entry);
+    const target = canonical2 === undefined ? "the canonical functional roleID" : `"${canonical2}"`;
+    lines.push(`    ⚠ non-canonical roleID ${rosterEntryText(entry)}`);
+    lines.push(`      remedy: change roleID to ${target} and keep the themed name in agentName.`);
+  }
+  if (unprofiled.length > 0) {
+    const roleIDs = unprofiled.map((entry) => entry.roleID).join(", ");
+    lines.push(`    · unprofiled roleID(s): ${roleIDs}`);
+    lines.push("      remedy: if intentional project roles, no action is required; for curated routing, change roleID to a TEAM_ROLES key or add a profile under orchestrator.roles in .opencode/openteam.json.");
+  }
+  return lines;
+}
 function agentModelsSection(diagnostics, searchedPaths) {
   const lines = ["  agent models:"];
   if (diagnostics.length === 0) {
@@ -10384,6 +10654,7 @@ function renderDoctor(input) {
   if (input.diagnostics !== undefined) {
     lines.push(...diagnosticsSection(input.diagnostics));
   }
+  lines.push(...rosterHealthSection(input.rosterAudit, input.rosterLoadError, input.rosterRoleCount));
   if (input.otelBackend !== undefined) {
     const otel = input.otelBackend;
     lines.push("  opentelemetry:");
@@ -12609,13 +12880,23 @@ async function guaranteedAgentStatuses(runtime) {
   }
   return statuses;
 }
+function rosterPlanSummary(rosterFile) {
+  switch (rosterFile.status) {
+    case "loaded":
+      return `${rosterFile.roster.universe} (${rosterFile.roster.entries.length} roles)`;
+    case "absent":
+      return "none yet — one would be generated on the first real run";
+    case "invalid":
+      return `${rosterFile.path} is present but unparseable — run 'openteam doctor'`;
+  }
+}
 function renderLoopPlan(plan2) {
   const { flags } = plan2;
   const budget = flags.budgetUsd !== undefined ? `$${flags.budgetUsd}` : "unbounded";
   const freshContext = flags.freshContext ? "on (pure Ralph pattern)" : "off";
   const budgetStop = flags.budgetUsd !== undefined ? ", budget" : "";
   const redTestsStop = flags.stopOnRedTests ? ", red tests" : "";
-  const rosterSummary = plan2.roster !== undefined ? `${plan2.roster.universe} (${plan2.roster.entries.length} roles)` : "none yet — one would be generated on the first real run";
+  const rosterSummary = rosterPlanSummary(plan2.rosterFile);
   const lines = [
     "openteam loop — plan (dry run, nothing dispatched):",
     `  backlog:       ${flags.backlogPath} (${plan2.uncheckedCount} unchecked item(s))`,
@@ -12659,14 +12940,14 @@ ${LOOP_HELP}` };
   const backlogText = await runtime.readBacklog(flags.backlogPath) ?? "";
   const items = parseBacklog2(backlogText);
   const unchecked = uncheckedBacklogItems(items);
-  const roster = await runtime.loadRoster();
+  const rosterFile = await runtime.loadRosterFile();
   const guaranteed = await guaranteedAgentStatuses(runtime);
   const plannedIterations = Math.max(0, Math.min(flags.maxIterations, unchecked.length));
   const plan2 = {
     flags,
     uncheckedCount: unchecked.length,
     plannedIterations,
-    roster,
+    rosterFile,
     guaranteed
   };
   if (flags.dryRun) {
@@ -12744,13 +13025,15 @@ async function runCli(argv, deps) {
     if (command === "doctor") {
       const config = await deps.loadConfig(configPath, configResolution);
       let opencodeConfigError;
+      let rosterLoadError;
       const [
         snapshots,
         records,
         diagnostics,
         cacheEntries,
         agentFiles,
-        opencodeConfig
+        opencodeConfig,
+        roster
       ] = await Promise.all([
         deps.probe(config),
         deps.readTelemetry(telemetryPath),
@@ -12762,7 +13045,11 @@ async function runCli(argv, deps) {
         deps.readOpencodeConfig(opencodeConfigPaths).catch((err) => {
           opencodeConfigError = err instanceof Error ? err.message : String(err);
           return;
-        })
+        }),
+        deps.loadRosterForDoctor !== undefined ? deps.loadRosterForDoctor().catch((err) => {
+          rosterLoadError = err instanceof Error ? err.message : String(err);
+          return;
+        }) : Promise.resolve(undefined)
       ]);
       const defaultModel = defaultModelFromOpencode(opencodeConfig);
       const agentModels = diagnoseAgentModels(agentFiles, {
@@ -12777,6 +13064,18 @@ async function runCli(argv, deps) {
         backend: "opentelemetry",
         connectionEnv: "APPLICATIONINSIGHTS_CONNECTION_STRING"
       }, (name) => process.env[name]);
+      let rosterAudit;
+      let rosterRoleCount;
+      if (roster !== undefined && deps.auditRoster !== undefined) {
+        if (typeof roster !== "string") {
+          rosterRoleCount = roster.entries.length;
+        }
+        try {
+          rosterAudit = deps.auditRoster(roster, config.orchestrator?.roles);
+        } catch (err) {
+          rosterLoadError = err instanceof Error ? err.message : String(err);
+        }
+      }
       return {
         exitCode: 0,
         stdout: renderDoctor({
@@ -12786,6 +13085,9 @@ async function runCli(argv, deps) {
           telemetryRecords: records.length,
           agentModels,
           opencodeConfigPaths,
+          ...rosterAudit !== undefined ? { rosterAudit } : {},
+          ...rosterRoleCount !== undefined ? { rosterRoleCount } : {},
+          ...rosterLoadError !== undefined ? { rosterLoadError } : {},
           ...diagnostics !== undefined && diagnostics.length > 0 ? { diagnostics } : {},
           ...opencodeConfigError !== undefined ? { opencodeConfigError } : {},
           ...cacheEntries !== undefined ? { cacheEntries, cliVersion: deps.version } : {},
@@ -14349,7 +14651,6 @@ async function* linesFromReadable(readable) {
 }
 
 // src/orchestrator/rosterPersistence.ts
-var ROSTER_JSON_FENCE = /```json\s*([\s\S]*?)```/;
 function serializeRoster(roster) {
   const data = { universe: roster.universe, entries: roster.entries };
   const json = JSON.stringify(data, null, 2);
@@ -14362,38 +14663,41 @@ ${json}
 \`\`\`
 `;
 }
-function parseRoster(text2) {
-  const match = ROSTER_JSON_FENCE.exec(text2);
-  if (match === null || match[1] === undefined) {
-    throw new Error("openteam roster: no JSON block found in roster file");
-  }
-  let data;
-  try {
-    data = JSON.parse(match[1]);
-  } catch (error) {
-    throw new Error(`openteam roster: malformed JSON in roster file: ${String(error)}`);
-  }
-  return RosterSchema.parse(data);
-}
 async function persistRoster(storage, roster, path4 = OPENTEAM_ROSTER_PATH) {
   await storage.write(path4, serializeRoster(roster));
   return path4;
 }
-async function loadRoster(storage, path4 = OPENTEAM_ROSTER_PATH) {
+async function loadRosterFile(storage, path4 = OPENTEAM_ROSTER_PATH) {
   const content = await storage.read(path4);
   if (content === undefined) {
-    return;
+    return { status: "absent", path: path4 };
+  }
+  const parsed = parseRosterResult(content);
+  if (!parsed.ok) {
+    return { status: "invalid", path: path4, error: parsed.error };
   }
-  return parseRoster(content);
+  return {
+    status: "loaded",
+    path: path4,
+    roster: enforceGuaranteedRoles(parsed.roster)
+  };
 }
 async function loadOrGenerateRoster(storage, generate, path4 = OPENTEAM_ROSTER_PATH) {
-  const existing = await loadRoster(storage, path4);
-  if (existing !== undefined) {
-    return { roster: existing, regenerated: false };
+  const existing = await loadRosterFile(storage, path4);
+  if (existing.status === "loaded") {
+    return { roster: existing.roster, regenerated: false };
+  }
+  const roster = enforceGuaranteedRoles(await generate());
+  if (existing.status === "absent") {
+    await persistRoster(storage, roster, path4);
+    return { roster, regenerated: true };
   }
-  const roster = await generate();
-  await persistRoster(storage, roster, path4);
-  return { roster, regenerated: true };
+  return {
+    roster,
+    regenerated: true,
+    recoveredFromInvalidPersisted: true,
+    invalidPersistedRosterError: existing.error.message
+  };
 }
 
 // src/plugin/orchestrateTool.ts
@@ -14649,7 +14953,7 @@ async function buildMemoryRuntimeFromConfig(config, deps, options = {}) {
 // package.json
 var package_default = {
   name: "@jmanuelcorral/openteam",
-  version: "0.9.1",
+  version: "0.9.2",
   packageManager: "bun@1.3.14",
   description: "Cost-aware, local-first routing plugin for opencode with cheapest-capable frontier fallback and multi-agent orchestration.",
   license: "MIT",
@@ -14774,6 +15078,18 @@ function createGitLastCommit(exec) {
 var execFileAsync2 = promisify2(execFile2);
 var AGENT_DIR2 = dirname5(ORCHESTRATOR_AGENT_PATH);
 var storage = createFsStorageProvider(process.cwd());
+async function readStoredRosterForDoctor() {
+  const content = await storage.read(OPENTEAM_ROSTER_PATH);
+  if (content === undefined) {
+    return;
+  }
+  try {
+    return parseRoster(content);
+  } catch {
+    return content;
+  }
+}
+var auditStoredRosterForDoctor = (roster, configuredRoles) => typeof roster === "string" ? auditRoster(roster, configuredRoles) : auditRoster(roster, configuredRoles);
 var migratePort = createMigrateAdapter(process.cwd());
 var nodeExec2 = async (command, args) => {
   try {
@@ -14952,6 +15268,8 @@ var deps = {
   cachePort: realCacheAdapter,
   purge: createCliPurgeRuntime(),
   loopRuntime: createCliLoopRuntime(),
+  loadRosterForDoctor: readStoredRosterForDoctor,
+  auditRoster: auditStoredRosterForDoctor,
   version: PACKAGE_VERSION
 };
 function createCliPurgeRuntime() {
@@ -15021,7 +15339,7 @@ function createCliLoopRuntime() {
   const agentFileExists = (agentName) => storage.exists(`${AGENT_DIR2}/${agentName}.md`);
   const generate = () => generateRoster("openteam initial roster", fallbackRosterSource);
   return {
-    loadRoster: () => loadRoster(storage),
+    loadRosterFile: () => loadRosterFile(storage),
     loadOrGenerateRoster: async () => (await loadOrGenerateRoster(storage, generate)).roster,
     agentFileExists,
     readBacklog: (path4) => storage.read(path4),

package/dist/commands/dispatch.d.ts

@@ -4,12 +4,14 @@ import type { LegacyLayoutFinding } from "../config/legacyPaths";
 import type { OpenTeamConfig } from "../config/schema";
 import type { LocalRuntimeSnapshot } from "../local/types";
 import type { ActiveIngressCapability, GraphIngress, IngressPolicy } from "../orchestrator/graphIngress";
+import { type AgentRoleProfile } from "../orchestrator/roles";
 import { type Roster } from "../orchestrator/roster";
+import type { RosterFileLoadResult } from "../orchestrator/rosterPersistence";
 import { type WorktreeObservation, type WorktreeReconcileAction } from "../orchestrator/worktreeReconciler";
 import type { CostRecord } from "../telemetry/types";
 import { type AgentFile } from "./agents";
 import type { CachePort } from "./clearCache";
-import { type DoctorDiagnostic } from "./doctor";
+import { type DoctorDiagnostic, type DoctorRosterAudit } from "./doctor";
 import { type GraphHealthSnapshot } from "./graph";
 import { type PurgeRuntime } from "./purge";
 export type CliDeps = {
@@ -22,6 +24,18 @@ export type CliDeps = {
      * older composition roots still run; when absent, doctor omits the section.
      */
     readDiagnostics?: () => Promise<DoctorDiagnostic[]>;
+    /**
+     * Reads the persisted roster for `openteam doctor`. This may be raw Markdown:
+     * the pure audit seam classifies unparseable table-only rosters without
+     * throwing, preserving the human-authored file while doctor reports a remedy.
+     */
+    loadRosterForDoctor?: () => Promise<Roster | string | undefined>;
+    /**
+     * Pure roster audit seam from `src/orchestrator/roster.ts`. Doctor receives the
+     * structured result and only renders it; audit logic stays in the roster
+     * boundary.
+     */
+    auditRoster?: (roster: Roster | string, configuredRoles?: Readonly<Record<string, AgentRoleProfile>>) => DoctorRosterAudit;
     /**
      * Reads and deep-merges all candidate opencode config files (later entries in
      * `paths` have lower precedence). Returns `undefined` when none of the paths
@@ -197,8 +211,8 @@ export type LoopRunResult = {
  * implementation (see `src/cli.ts`); tests inject a deterministic fake.
  */
 export type LoopRuntime = {
-    /** Reads the persisted roster WITHOUT contacting a model. `undefined` = none. */
-    loadRoster(): Promise<Roster | undefined>;
+    /** Reads the persisted roster status WITHOUT contacting a model. */
+    loadRosterFile(): Promise<RosterFileLoadResult>;
     /** Reuses the persisted roster, or generates + persists one (may call a model). */
     loadOrGenerateRoster(): Promise<Roster>;
     /** Whether `.opencode/agent/<agentName>.md` exists in the workspace. */
@@ -215,7 +229,7 @@ export type LoopPlan = {
     readonly flags: LoopFlags;
     readonly uncheckedCount: number;
     readonly plannedIterations: number;
-    readonly roster: Roster | undefined;
+    readonly rosterFile: RosterFileLoadResult;
     readonly guaranteed: readonly GuaranteedAgentStatus[];
 };
 /** Renders the loop plan for `--dry-run`. Pure. */