@lyupro/codex-bridge 0.6.10 → 0.6.12

package/src/home/lib/dispatcher-pin.mjs

@@ -0,0 +1,60 @@
+/**
+ * Reads the INSTALLED PACKAGE CONTRACT, unanimous over recorded owners (Plan_67 D10),
+ * never a reconstruction of the definition the host selected or its precedence rules.
+ * One broken owner makes the shared pin undetermined; this boundary is synchronous and read-only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { claudePaths } from './claude-layout.mjs';
+import { CLI_NAMES } from './cli-names.mjs';
+import { parseFrontmatter } from './frontmatter.mjs';
+import { readOwnerRoots } from './install-owner-roots.mjs';
+import { modelFamily } from './model-family.mjs';
+
+export function readDispatcherPin({ brandRoot, agentType }) {
+  const owners = readOwnerRoots({ brandRoot });
+  if (owners.problem) return { family: null, reasons: [owners.detail] };
+
+  const reasons = [];
+  const pins = [];
+  for (const root of owners.roots) {
+    const file = path.join(claudePaths(root).agentsDir, `${agentType}.md`);
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch (error) {
+      const problem = error.code === 'ENOENT' ? 'is missing' : 'cannot be read';
+      reasons.push(`Dispatcher file "${file}" ${problem}; repair with ${CLI_NAMES[0]} install --host "${root}".`);
+      continue;
+    }
+
+    let frontmatter;
+    try {
+      frontmatter = parseFrontmatter(content);
+    } catch {
+      frontmatter = null;
+    }
+    if (frontmatter === null) {
+      reasons.push(`The frontmatter in "${file}" is unreadable.`);
+      continue;
+    }
+    if (frontmatter.name !== agentType) {
+      reasons.push(`Dispatcher file "${file}" does not declare the required frontmatter name "${agentType}".`);
+      continue;
+    }
+    const family = modelFamily(frontmatter.model);
+    if (family === null) {
+      reasons.push(`Dispatcher file "${file}" has no parseable model family in its frontmatter model.`);
+      continue;
+    }
+    pins.push({ root, family });
+  }
+
+  if (new Set(pins.map(({ family }) => family)).size > 1) {
+    const disagreement = pins.map(({ root, family }) => `"${root}" -> ${family}`).join(', ');
+    reasons.push(`Installed dispatcher model families disagree across owners: ${disagreement}.`);
+  }
+  return reasons.length
+    ? { family: null, reasons }
+    : { family: pins[0].family, roots: owners.roots };
+}

package/src/home/lib/dispatcher-protocol.mjs

@@ -0,0 +1,91 @@
+/**
+ * Owns only the dispatcher protocol text shared by every dispatcher prompt.
+ * Plan_63 D11: four hand-written copies drifted; build even requested a continuation
+ * flag absent from the canonical command. Render the command from its own assembler.
+ */
+import { renderRunCommandTemplate } from './dispatcher-command.mjs';
+import { TASK_FILE_INPUT } from './dispatcher-call.mjs';
+
+export function renderDispatcherProtocol(agentType) {
+  const command = renderRunCommandTemplate(agentType);
+  return `## Required dispatcher input
+
+The call is exactly one line: \`${TASK_FILE_INPUT.label}: <task-file path from the orchestrator>\`.
+The path must be absolute and name a file the orchestrator wrote with its file tool.
+The dispatcher never creates, reads or rewrites it: writing it from the shell brings back
+the permission prompt this file channel exists to remove.
+The whole order — order id, grants and every other value — lives in that file's header.
+The runner checks the header, never the dispatcher. The dispatcher never adds, removes or
+reorders anything on the command line because of what the call or the file says.
+No path in the call means run nothing and return
+\`FAIL — could not start the Codex run: no task file in the call\`, the form the no-self-execution rule gives.
+
+## When the host refuses the command
+
+If the host refuses to run \`codex-bridge run\` — a permission prompt, a classifier denial, anything
+that stops the command — that refusal is your final answer. Report \`FAIL\`, name the task file from the call,
+and state the one correction: the operator runs \`codex-bridge install\`, which grants the permission
+rule this package needs.
+
+You are forbidden to look for a way around it. Specifically, and without exception:
+
+- never call \`run-codex.mjs\`, or any file inside the installed package, by path;
+- never start the runner through \`node\`, \`npx\`, \`sh\`, \`bash\` or any other interpreter;
+- never retry the same call in PowerShell because Bash refused it, or the reverse;
+- never split the call over more than one line, and never add a pipe, a semicolon or a redirect;
+- never advise the operator to grant a permission rule on an internal file — a rule on anything but
+  the package command undoes the very design that makes this call permission-stable.
+
+Every one of those forms was removed on purpose: a host matches a permission rule against the
+beginning of the final command line, so an interpreter, a path or a continuation makes the call
+unmatchable by construction. Reaching for one does not rescue the run; it guarantees the refusal
+and asks the operator to make it permanent. On 2026-08-15 an order in another repository did all
+three in sequence and ended by telling its operator to grant a rule on \`run-codex.mjs\`.
+
+## The only thing you do
+
+\`\`\`bash
+${command}
+\`\`\`
+
+Replace the placeholder with the path from the call, nothing else.
+The first call starts the run and returns at once with \`RUN=<path> order-id=<id>\` and a
+\`STARTED\` line. To get the verdict, run the identical command again. That call does not start
+a second run or cost quota: it attaches to the run already in flight, prints
+\`ATTACH=<path> order-id=<id> started=<time>\`, blocks until the verdict exists and prints it.
+Give the attaching call \`timeout: 1800000\` (30 minutes). A real run takes 20-25 minutes,
+which is normal, not a hang. If the ceiling kills it, run the identical command again:
+it attaches to the same run and keeps waiting.
+
+Background execution (\`run_in_background\`, \`&\`, \`nohup\`) is prohibited, and so is inventing
+a report from memory. Never add a flag: the host allows exactly the one canonical command
+and refuses every other.
+
+A runner refusal — an order id collision, a header problem or a grant problem — is the whole
+answer: return it as \`FAIL\` with the runner's text. Never retry with a changed command or another
+task file. The next pass is assigned only by the orchestrator, never chosen by you.
+The order id in the task-file header is issued by the orchestrator and is what makes a repeat
+harmless; a changed task file or command turns a repeat into a second paid run.
+On 2026-08-03 one order became six runs exactly this way, and four of them were never accounted for
+at all. A second writing run in one worktree is refused anyway — the tree is shared and has no
+isolation.
+
+**Your response = the exact stdout of the attaching call**: the \`ATTACH=<path>\` line and the status
+block below it. Do not add or remove anything: no preamble, explanations, or retelling of the diff.
+The report is in \`report.md\`; the orchestrator will read it. Do not make commits: that is the
+operator's decision. The \`STARTED\` output of the first call is not a result and is never the response.
+When the first call prints no \`RUN=\` line — a runner refusal or an \`UNAVAILABLE\` block, with no run
+folder created — there is nothing to attach to: that output, verbatim, is the whole response, and
+the identical command is not run again.
+
+The only allowed final response is this exact stdout. Wording such as "the run has started,
+waiting for completion," "I will wait for a notification," or "Monitor started in the background" is
+prohibited in any form: the subagent ceases to exist immediately after responding, nobody can wait,
+and the orchestrator gets a promise instead of a result. A real case: the dispatcher gave exactly
+such a response during a live run — the worktree remained busy, and this could only be discovered
+by checking \`status.json\` manually.
+Inventing any outcome the runner did not print is equally prohibited. On 2026-08-13 a dispatcher said
+\`FAIL — could not get the Codex run result because of an architectural environment limitation\` while
+that run's \`status.json\` already said \`state=finished\`, \`status=OK\`.
+`;
+}

package/src/home/lib/dispatcher-stop.mjs

@@ -12,21 +12,30 @@ export function transcriptToolUses(transcriptPath) {
   }
 
   const toolUses = [];
+  let complete = true;
   for (const line of source.split(/\r?\n/)) {
+    if (!line.trim()) continue;
     let record;
     try {
       record = parseJsonText(transcriptPath, line);
     } catch {
+      complete = false;
       continue;
     }
     if (record?.type !== 'assistant' && record?.message?.role !== 'assistant') continue;
     const content = record.message?.content;
     if (!Array.isArray(content)) continue;
     for (const block of content) {
-      if (block?.type === 'tool_use') toolUses.push({ id: block.id, name: block.name });
+      if (block?.type === 'tool_use') {
+        const toolUse = { id: block.id, name: block.name };
+        if (block.name === 'Bash' && typeof block.input?.command === 'string') {
+          toolUse.command = block.input.command;
+        }
+        toolUses.push(toolUse);
+      }
     }
   }
-  return toolUses;
+  return { toolUses, complete };
 }
 
 export function decideDispatcherStop({ state, toolUses }) {

package/src/home/lib/handback-witness.mjs

@@ -1,73 +1,162 @@
-/** Records the 2026-09-17..24 handback break; 2026-09-25 proved SDK env is inherited, so identify hosts from transcripts. */
-import fs from 'node:fs';
+/** records whether hosts and dispatchers keep the handback contract, per cause, over the observation ledger
+ * Plan_67 D8 cures the eternal-warning defect with cause-specific evidence; D9 keeps old untyped
+ * alarms without dispatcher evidence in legacy history, never as confirmed violations.
+ */
 import path from 'node:path';
-import { writeHomeJsonAtomic } from './atomic-json.mjs';
-import { parseJsonText } from './json-file.mjs';
-import { withHomeFileLock } from './file-lock.mjs';
-import { stateDirWriter } from './home-write.mjs';
 import { transcriptHostVersion } from './host-version.mjs';
+import {
+  emptyLedger, normalizeLedger, readLedgerFile, reduceObservation, updateLedgerFile,
+} from './observation-ledger.mjs';
 
 export const WITNESS_FILE = 'handback-witness.json';
+export const WITNESS_CAUSES = Object.freeze(['missing-agent-type', 'missing-ids', 'tools-outside-gate']);
 
 export async function witnessHostVersion(payload) {
   return transcriptHostVersion(payload?.transcript_path);
 }
 
-function normalizeWitness(record) {
-  const alarmEntry = (entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
-    && (entry.hostVersion === null || typeof entry.hostVersion === 'string')
-    && typeof entry.at === 'string' && typeof entry.detail === 'string';
-  if (!record || typeof record !== 'object' || Array.isArray(record) || !Array.isArray(record.alarms)) return null;
-  if (record.alarms.every(alarmEntry) && record.lastSeen && typeof record.lastSeen === 'object'
-    && !Array.isArray(record.lastSeen) && !Object.hasOwn(record.lastSeen, 'sdkVersion')
-    && !Object.hasOwn(record.lastSeen, 'at') && Object.values(record.lastSeen).every((at) => typeof at === 'string')) return record;
-  const legacy = record.lastSeen === null || (record.lastSeen && typeof record.lastSeen === 'object'
-    && !Array.isArray(record.lastSeen) && typeof record.lastSeen.sdkVersion === 'string' && typeof record.lastSeen.at === 'string');
-  const legacyAlarm = (entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value);
+const hostMap = (value) => object(value) && Object.values(value).every((at) => typeof at === 'string');
+const alarmEntry = (entry) => object(entry)
+  && (entry.hostVersion === null || typeof entry.hostVersion === 'string')
+  && typeof entry.at === 'string' && typeof entry.detail === 'string';
+
+function emptyWitness() {
+  return { version: 2, ledger: emptyLedger(), intercepted: {}, legacy: [] };
+}
+
+export function witnessKey({ cause, hostVersion, agentType }) {
+  if (!WITNESS_CAUSES.includes(cause)) throw new TypeError('cause must be a witness cause');
+  if (hostVersion != null && typeof hostVersion !== 'string') {
+    throw new TypeError('hostVersion must be a string or null');
+  }
+  const host = hostVersion || 'unknown';
+  if (cause === 'missing-agent-type') return `${host}|${cause}`;
+  if (typeof agentType !== 'string' || agentType.length === 0) {
+    throw new TypeError('agentType is required for this witness cause');
+  }
+  return `${host}|${agentType}|${cause}`;
+}
+
+// Preserve the previous normalizer's accepted host-map and SDK shapes. SDK versions are not hosts.
+function normalizeOldWitness(record) {
+  if (!object(record) || !Array.isArray(record.alarms)) return null;
+  if (record.alarms.every(alarmEntry) && hostMap(record.lastSeen)
+    && !Object.hasOwn(record.lastSeen, 'sdkVersion') && !Object.hasOwn(record.lastSeen, 'at')) return record;
+  const legacy = record.lastSeen === null || (object(record.lastSeen)
+    && typeof record.lastSeen.sdkVersion === 'string' && typeof record.lastSeen.at === 'string');
+  const legacyAlarm = (entry) => object(entry)
     && (entry.sdkVersion === null || typeof entry.sdkVersion === 'string') && typeof entry.at === 'string'
     && typeof entry.detail === 'string';
-  if (legacy && record.alarms.every(legacyAlarm)) return { lastSeen: {}, alarms: record.alarms.map(({ at, detail }) => ({ hostVersion: null, at, detail })) };
+  if (legacy && record.alarms.every(legacyAlarm)) {
+    return { lastSeen: {}, alarms: record.alarms.map(({ at, detail }) => ({ hostVersion: null, at, detail })) };
+  }
   return null;
 }
 
-export function readHandbackWitness({ stateDir }) {
-  const file = path.join(stateDir, WITNESS_FILE);
-  let source;
-  try {
-    source = fs.readFileSync(file, 'utf8');
-  } catch (error) {
-    if (error.code === 'ENOENT') return { lastSeen: {}, alarms: [] };
-    return { corrupt: true };
+function normalizeWitnessLedger(parsed) {
+  const ledger = normalizeLedger(parsed);
+  if (!ledger) return null;
+  for (const entry of Object.values(ledger.entries)) {
+    for (const observation of [entry.lastObservation, entry.lastViolation, entry.lastMatch, ...entry.history]) {
+      if (observation === null) continue;
+      const data = observation.data;
+      if (!data || Object.getPrototypeOf(data) !== Object.prototype || !WITNESS_CAUSES.includes(data.cause)
+        || !(data.hostVersion === null || typeof data.hostVersion === 'string')
+        || !(data.agentType === null || typeof data.agentType === 'string')) return null;
+    }
   }
-  try {
-    const record = parseJsonText(file, source);
-    return normalizeWitness(record) || { corrupt: true };
-  } catch {
-    return { corrupt: true };
+  return ledger;
+}
+
+export function migrateWitness(parsed) {
+  if (object(parsed) && Object.hasOwn(parsed, 'version')) {
+    return parsed.version === 2 && normalizeWitnessLedger(parsed.ledger) && hostMap(parsed.intercepted)
+      && Array.isArray(parsed.legacy) && parsed.legacy.every((entry) => alarmEntry(entry)
+        && ['legacy-untyped-unverified', 'unclassified'].includes(entry.disposition)) ? parsed : null;
+  }
+  const old = normalizeOldWitness(parsed);
+  if (!old) return null;
+  const record = { ...emptyWitness(), intercepted: { ...old.lastSeen } };
+  const alarms = [...old.alarms].sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
+  for (const { at, hostVersion, detail } of alarms) {
+    if (/^host omitted agent_type for agent \S+$/.test(detail)) {
+      // D9: old stops lack dispatcher evidence; reclassification must not manufacture a violation.
+      record.legacy.push({ at, hostVersion, detail, disposition: 'legacy-untyped-unverified' });
+      continue;
+    }
+    const ids = /^host omitted session_id or agent_id for (\S+)$/.exec(detail);
+    const tools = /^(\S+) (\S+): (.+) outside the dispatcher gate$/.exec(detail);
+    if (!ids && !tools) {
+      record.legacy.push({ at, hostVersion, detail, disposition: 'unclassified' });
+      continue;
+    }
+    const cause = ids ? 'missing-ids' : 'tools-outside-gate';
+    const agentType = (ids || tools)[1];
+    try {
+      record.ledger = reduceObservation(record.ledger, {
+        key: witnessKey({ cause, hostVersion, agentType }), verdict: 'violation', at, detail,
+        data: { cause, hostVersion, agentType },
+      });
+    } catch {
+      return null;
+    }
   }
+  return record;
 }
 
-function timestamp(now) {
-  return new Date(now).toISOString();
+// readLedgerFile returns an empty ledger for ENOENT, even when its normalizer is an adapter.
+function witnessRecord(record) {
+  return record.version !== 2 && record.format === 1 ? emptyWitness() : record;
 }
 
+export function readHandbackWitness({ stateDir }) {
+  return witnessRecord(readLedgerFile(path.join(stateDir, WITNESS_FILE), { normalize: migrateWitness }));
+}
 
-export async function recordHandbackWitness({ stateDir, kind, hostVersion, detail = '', now = new Date() }) {
-  if (kind !== 'seen' && kind !== 'alarm') throw new TypeError("kind must be 'seen' or 'alarm'");
+function validateHost(hostVersion) {
   if (hostVersion !== null && typeof hostVersion !== 'string') {
     throw new TypeError('hostVersion must be a string or null');
   }
-  const file = path.join(stateDir, WITNESS_FILE);
-  // Plan_65 B6: the witness, its lock and temporaries are the registered handback-witness artifact.
-  const writer = stateDirWriter(stateDir);
-  return withHomeFileLock(writer, 'handback-witness', `${file}.lock`, async () => {
-    const current = readHandbackWitness({ stateDir });
-    if (current.corrupt) throw new Error(`Cannot update corrupt handback witness: ${file}`);
-    const at = timestamp(now);
-    const record = kind === 'seen'
-      ? { ...current, lastSeen: hostVersion === null ? current.lastSeen : { ...current.lastSeen, [hostVersion]: at } }
-      : { ...current, alarms: [...current.alarms, { hostVersion, at, detail }].slice(-20) };
-    writeHomeJsonAtomic(writer, 'handback-witness', file, record);
-    return record;
-  }, { description: 'handback witness' });
+}
+
+export async function recordWitnessObservation({
+  stateDir, cause, hostVersion, agentType = null, verdict, detail = '', now = new Date(),
+}) {
+  return recordWitnessObservations({
+    stateDir, observations: [{ cause, hostVersion, agentType, verdict, detail }], now,
+  });
+}
+
+export async function recordWitnessObservations({ stateDir, observations, now = new Date() }) {
+  const prepared = observations.map(({ cause, hostVersion, agentType = null, verdict, detail = '' }) => {
+    validateHost(hostVersion);
+    const key = witnessKey({ cause, hostVersion, agentType });
+    if (agentType !== null && (typeof agentType !== 'string' || agentType.length === 0)) {
+      throw new TypeError('agentType must be a non-empty string or null');
+    }
+    return { key, verdict, detail, data: { cause, hostVersion, agentType } };
+  });
+  const at = new Date(now).toISOString();
+  return updateLedgerFile({
+    stateDir, id: 'handback-witness', file: path.join(stateDir, WITNESS_FILE), normalize: migrateWitness,
+    update: (current) => {
+      const record = witnessRecord(current);
+      return { ...record, ledger: prepared.reduce((ledger, observation) =>
+        reduceObservation(ledger, { ...observation, at }), record.ledger) };
+    },
+  });
+}
+
+export async function recordInterceptedAttempt({ stateDir, hostVersion, now = new Date() }) {
+  validateHost(hostVersion);
+  const at = new Date(now).toISOString();
+  return updateLedgerFile({
+    stateDir, id: 'handback-witness', file: path.join(stateDir, WITNESS_FILE), normalize: migrateWitness,
+    update: (current) => {
+      const record = witnessRecord(current);
+      // D8: even denied handbacks are intercepted, so this timestamp is never match evidence.
+      return { ...record, intercepted: { ...record.intercepted, [hostVersion || 'unknown']: at } };
+    },
+  });
 }

package/src/home/lib/home-registry.mjs

@@ -83,6 +83,13 @@ const entries = [
     primary: ['state/handback-witness.json'],
     sides: ['lock', 'atomic-temporary'],
   },
+  {
+    id: 'dispatcher-model',
+    removal: 'purge-only',
+    consequence: 'Doctor forgets which model each dispatcher type was last observed on and every model violation it recorded.',
+    primary: ['state/dispatcher-model.json'],
+    sides: ['lock', 'atomic-temporary'],
+  },
   {
     id: 'host-observations',
     removal: 'purge-only',

package/src/home/lib/install-owner-roots.mjs

@@ -0,0 +1,55 @@
+/**
+ * Reads which host roots own this home from the installation record, read-only, for hooks.
+ * Plan_67 D10 needs every recorded owner; the home image has no cli/ modules.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeArtifact } from './home-registry.mjs';
+import { parseJsonText } from './json-file.mjs';
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+export function isFormat2(parsed) {
+  return isObject(parsed) && parsed.format === 2;
+}
+
+export function readOwnerRoots({ brandRoot }) {
+  const file = path.join(brandRoot, homeArtifact('install-record').primary[0]);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    return error.code === 'ENOENT'
+      ? { problem: 'missing', detail: `Installation record at ${file} is missing.` }
+      : { problem: 'unreadable', detail: `Installation record at ${file} cannot be read.` };
+  }
+
+  let parsed;
+  try {
+    parsed = parseJsonText(file, raw);
+  } catch {
+    return { problem: 'unreadable', detail: `Installation record at ${file} contains invalid JSON.` };
+  }
+  if (!isFormat2(parsed)) {
+    return { problem: 'not-format-2', detail: `Installation record at ${file} is not format 2.` };
+  }
+  // Plan_67 R2: confirmation refuses ownerless records; enrollment must come first.
+  if (!isObject(parsed.owners) || Object.keys(parsed.owners).length === 0) {
+    return { problem: 'no-owners', detail: `Installation record at ${file} has no owners.` };
+  }
+  if (parsed.inventory !== 'complete') {
+    // Plan_67 D11: match cli/inventory-confirm.mjs INVENTORY_CONFIRM_COMMAND; hooks cannot import cli/.
+    return { problem: 'inventory-incomplete', detail: `Installation record at ${file} has an incomplete inventory; if the recorded hosts are all the hosts using this home, run codex-bridge inventory confirm.` };
+  }
+  if (Object.hasOwn(parsed, 'legacy')) {
+    return { problem: 'legacy-partition', detail: `Installation record at ${file} contains a legacy partition.` };
+  }
+  const roots = [];
+  for (const owner of Object.values(parsed.owners)) {
+    if (typeof owner?.root !== 'string' || owner.root.trim().length === 0) {
+      return { problem: 'malformed-owner', detail: `Installation record at ${file} has an owner without a non-empty root.` };
+    }
+    roots.push(owner.root);
+  }
+  return { roots: roots.sort() };
+}

package/src/home/lib/meta/paths.mjs

@@ -114,7 +114,7 @@ export const samePath = (declared, touched) => {
 };
 
 /**
- * One --scope pattern as a regular expression. Deliberately a small glob dialect and not a
+ * One scope pattern as a regular expression. Deliberately a small glob dialect and not a
  * dependency: `**` crosses directory boundaries, `*` and `?` stop at `/`, matching is
  * case-insensitive because Windows paths arrive in whatever case Codex felt like using.
  * A slash right after `**` is optional, so `src/**` covers `src/a.ts` too — otherwise the

package/src/home/lib/meta/reply.mjs

@@ -15,6 +15,7 @@ import { AGENTS as AGENT_DEFINITIONS } from '../agents.mjs';
 import { changedPaths, line, readText } from './paths.mjs';
 import { splitRunChanges } from './environment.mjs';
 import { scoutCoverage } from './verdict.mjs';
+import { orderInputName } from '../order-schema.mjs';
 
 /** What the run itself changed, and what the tooling around it changed while it worked. */
 const runChanges = (runDir) =>
@@ -143,7 +144,7 @@ function advisorReply(ctx) {
     const risks = r.predicted_risks || [];
     return [
       r.sufficient
-        ? 'OK — scope: sufficient; continue this run with --phase advise'
+        ? `OK — scope: sufficient; continue this run with ${orderInputName('phase')} advise`
         : `OK — scope: insufficient; ${missing.length} paths named`,
       ...(missing.length ? [`Missing: ${line(missing.join(', '), 160)}`] : []),
       `Predicted risks: ${risks.length}${risks[0] ? ` — ${risks[0].id} ${line(risks[0].risk, 120)}` : ''}`,

package/src/home/lib/model-family.mjs

@@ -0,0 +1,38 @@
+/**
+ * Parses model families by id structure, Plan_67 D5, without a model id literal in code:
+ * an id table would become stale with every model release and create false mismatch warnings.
+ * D5 (b) treats unparsed ids as no evidence, rather than as matches or violations.
+ */
+
+// These are host aliases, not model ids or family pins (Plan_67 D5).
+export const NON_FAMILY_ALIASES = Object.freeze(['inherit', 'default', 'opusplan']);
+
+const isAsciiLetters = (value) => value.length > 0 && !/[^A-Za-z]/.test(value);
+
+export function modelFamily(value) {
+  if (typeof value !== 'string') return null;
+  const tokens = value.replace(/\[[^\[\]]*\]$/, '').split(/[-.@]/);
+  const claudeIndex = tokens.findIndex((token) => token.toLowerCase() === 'claude');
+  if (claudeIndex !== -1) {
+    const family = tokens.slice(claudeIndex + 1).find(isAsciiLetters);
+    return family ? family.toLowerCase() : null;
+  }
+  if (tokens.length !== 1 || !isAsciiLetters(tokens[0])) return null;
+  const family = tokens[0].toLowerCase();
+  return NON_FAMILY_ALIASES.includes(family) ? null : family;
+}
+
+export function compareModelFamilies({ pinFamily, modelIds }) {
+  const families = new Set();
+  let unparsed = 0;
+  for (const id of modelIds) {
+    const family = modelFamily(id);
+    if (family === null) unparsed += 1;
+    else families.add(family);
+  }
+  const parsed = [...families];
+  const verdict = pinFamily === null || parsed.length === 0
+    ? 'undetermined'
+    : parsed.some((family) => family !== pinFamily) ? 'violation' : 'match';
+  return { verdict, parsed, unparsed };
+}