@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

package/src/runtime/mask.js

@@ -8,7 +8,7 @@
  * the project store. Masking only narrows what a statement or an excerpt can carry.
  *
  * Two profiles. The line profile is for one-line statements and failure messages; the body profile
- * is for report bodies and excerpts and runs every line rule plus the body-only rules 7 to 9.
+ * is for report bodies and excerpts and runs every line rule plus the body-only rules 7 to 9 and 14 to 17.
  * Rules run in the table's order. Normalisation (rules 10 to 13) is a separate step applied to
  * failure messages only, after masking.
  *
@@ -36,7 +36,9 @@ const TOKEN_SHAPES = [
   /xox[abprs]-[A-Za-z0-9-]{10,}/g,
   /npm_[A-Za-z0-9]{24,}/g,
   /AIza[0-9A-Za-z_-]{35}/g,
-  /eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
+  // Left-anchored (DEC-069): without it every `eyJ` inside a long dotless run starts a scan to the
+  // run's end, which makes masking one line quadratic in its length.
+  /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
 ];
 
 const PEM = /-----BEGIN [^\n-]*-----(?:[\s\S]*?-----END [^\n-]*-----|[\s\S]*$)/g;
@@ -52,13 +54,107 @@ const KEY_VALUE_BODY = new RegExp(`(${KEY_NAME}["']?[ \\t]*[=:][ \\t]*)("[^"\\r\
 const AUTH_HEADER = /((?:Proxy-)?Authorization:)[ \t]*([^\r\n]*)/gi;
 const SECRET_FLAG = /(--(?:password|passwd|token|secret|api-key|client-secret)(?:=|[ \t]+))("[^"\r\n]*"|'[^'\r\n]*'|[^\s"']+)/gi;
 
+// Rules 14 to 17 (body profile only, FU-ht8b3r). Command shapes that carry a secret without a key
+// word: `curl -u user:pw` (also glued, `-uuser:pw`), `mysql -psecret` (value glued to the flag; a bare
+// `-p` prompts and carries none), and the phrase `password hunter2`. The flags are masked by one
+// left-to-right scan (rules 14 and 15, `maskCommandFlags`) that knows which command it is in, so every
+// flag of a command is masked and `sort -u`, `git push -u` and `mysql -P 3306` stay as written.
+// A command word counts only at command position (see `maskCommandFlags`), and quoted text is scanned,
+// not skipped. Alternatives, in order: a quote, a command break (`|`, `;`, `&`, parentheses, a
+// backtick, a line end), curl's `--user` and `-u` (the short one may be glued to its value), mysql's
+// `-p` glued to its value, any other word.
+const COMMAND_SCAN = /(?<quote>["'])|(?<brk>[|;&()`\r\n])|(?<=[ \t])(?:(?<long>--user)(?:=|[ \t]+)|(?<short>-u)(?:=|[ \t]*)(?=[^\s|;&]))|(?<=[ \t])(?<pass>-p)(?=[^\s|;&-])|(?<word>[^\s|;&()`"']+)/g;
+// The closing quote of a quoted span, on the same line.
+const QUOTE_CLOSE                         = { '"': /[^"\r\n]*"/y, "'": /[^'\r\n]*'/y };
+// A word that is the command: bare or as a path (never a URL, which holds `:`).
+const COMMAND_WORD = /^(?:(?:\.{0,2}|~)?\/(?:[^\s:]*\/)?)?(?:(curl)|(mysql(?:dump|admin|pump|import)?))$/;
+// Words after which the next word is the command: wrappers, remote and container runners, shell keywords.
+const WRAPPER_WORDS = new Set(['sudo', 'doas', 'su', 'env', 'exec', 'nohup', 'time', 'timeout', 'nice', 'ionice', 'xargs', 'watch',
+  'command', 'builtin', 'eval', 'setsid', 'stdbuf', 'flock', 'chroot', 'ssh', 'docker', 'podman', 'kubectl', 'sh', 'bash', 'zsh', 'dash', 'ksh',
+  'if', 'then', 'else', 'elif', 'do', 'while', 'until', '!', '{']);
+// A first word that does not use up the command position: a prompt mark, a variable assignment or a
+// label such as `Running:`.
+const PROMPT_OR_ASSIGNMENT = /^(?:[$#%>+]+|[A-Za-z_][A-Za-z0-9_]*=[^=]*|[A-Za-z][A-Za-z0-9_-]*:)$/;
+// A flag value: quoted, or unquoted up to a space, quote or command break.
+const COMMAND_FLAG_VALUE = /"[^"\r\n]*"|'[^'\r\n]*'|[^\s"'|;&]+/y;
+// The value after the phrase must hold a non-letter, as in rule 4, so ordinary prose ("the password is
+// required") survives; a plain-letter value after a bare `password ` is a known gap, and so is a
+// password of one to three digits (`reset password 2 times` is prose).
+const PASSWORD_PHRASE = /(?<![A-Za-z0-9_.-])((?:password|passwd)[ \t]+)(?!<masked>|[=:])([^\s,;&"'`)\]}]+)/gi;
+// Another user's home directory (the running user's is rule 0). `Shared` is not a person and `runner`
+// is the CI runner account (`/Users/runner/work/...`), so neither is masked.
+const OTHER_USER_HOME = /(?<![A-Za-z0-9_.-])\/Users\/(?!(?:Shared|runner)(?![^/\s"'`<>:;,()[\]{}])|<)[^/\s"'`<>:;,()[\]{}]+/g;
+
+/**
+ * Rules 14 and 15. Scans left to right and masks the value of every `-u`/`--user` of a curl command
+ * and every `-p<value>` of a mysql command. A command word (`curl`, `mysql*`) is the command of its
+ * segment only at command position: the first word of the text, of a line or of a segment after a
+ * break (`|`, `;`, `&`, a parenthesis, a backtick), of a quoted span, or after a wrapper word
+ * (`sudo`, `env`, `ssh`, `docker`, `sh`, `bash`, ...) at the start of the segment. A word that holds `:`
+ * (a URL) or is followed by more of its token (`mysql-8`) is not the command. A segment has one
+ * command. Quoted text is scanned: its start is a command position, and a break inside it ends only
+ * the command inside it, so `curl -H "a|b" -u x:y` keeps its command. One pass; every step consumes
+ * at least one character and a closing quote is searched on its own line, so the cost is linear.
+ */
+function maskCommandFlags(text        )         {
+  let out = '';
+  let copied = 0;
+  let command                          = null;
+  let atStart = true;       // the next word is the first of its segment
+  let wrapped = false;      // the segment began with a wrapper word
+  const spans                                                                                                 = [];
+  COMMAND_SCAN.lastIndex = 0;
+  let found                        ;
+  while ((found = COMMAND_SCAN.exec(text)) !== null) {
+    const groups = found.groups || {};
+    const end = found.index + found[0].length;
+    if (groups.quote) {
+      const top = spans[spans.length - 1];
+      if (top && top.quote === groups.quote) {
+        spans.pop();
+        ({ command, atStart, wrapped } = top);
+        atStart = false;
+      } else {
+        const close = QUOTE_CLOSE[groups.quote];
+        close.lastIndex = end;
+        if (close.test(text)) {
+          spans.push({ quote: groups.quote, command, atStart, wrapped });
+          command = null; atStart = true; wrapped = false;
+        }
+      }
+    } else if (groups.brk) {
+      if (!(groups.brk === '&' && /[<>]/.test(text[found.index - 1] || ''))) { command = null; atStart = true; wrapped = false; }
+    } else if (groups.word) {
+      const word = groups.word;
+      if (atStart && PROMPT_OR_ASSIGNMENT.test(word)) continue;
+      const named = COMMAND_WORD.exec(word);
+      if (command === null && (atStart || wrapped) && named) command = named[1] ? 'curl' : 'mysql';
+      else if (atStart) wrapped = WRAPPER_WORDS.has(word.slice(word.lastIndexOf('/') + 1));
+      atStart = false;
+    } else if (((groups.long || groups.short) && command === 'curl') || (groups.pass && command === 'mysql')) {
+      atStart = false;
+      COMMAND_FLAG_VALUE.lastIndex = end;
+      const value = COMMAND_FLAG_VALUE.exec(text);
+      if (value && !isMasked(value[0]) && !(command === 'mysql' && value[0].startsWith(MASKED))) {
+        out += text.slice(copied, end) + MASKED;
+        copied = end + value[0].length;
+        COMMAND_SCAN.lastIndex = copied;
+      }
+    } else {
+      atStart = false;                // another command's flag: rescan what follows it
+      COMMAND_SCAN.lastIndex = end;
+    }
+  }
+  return out + text.slice(copied);
+}
+
 function escapeRegExp(text        )         { return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
 
 /** The home directory to abbreviate: an absolute path other than the file system root. */
 function homeOf(options      )                {
   const raw = options && 'home' in options ? options.home : process.env.HOME;
-  if (typeof raw !== 'string' || !raw.startsWith('/')) return null;
-  const home = raw.replace(/\/+$/, '');
+  if (typeof raw !== 'string' || !(raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw))) return null;
+  const home = raw.replace(/[\\/]+$/, '');
   return home.length > 1 ? home : null;
 }
 
@@ -89,6 +185,30 @@ function mask40(run        , before                    )         {
     looksLikeSecretRun(value, 1) && !isPathRun(value, index === 0 ? before : run[index - 1]) ? MASKED : value));
 }
 
+const TS_TYPE_NAMES                      = new Set([
+  'string', 'number', 'boolean', 'any', 'unknown', 'void',
+  'never', 'null', 'undefined', 'symbol', 'bigint',
+]);
+
+function isCodePreserved(head        , value        , offset        , fullString        )          {
+  if (value.startsWith('"') || value.startsWith("'")) return false;
+  const isColon = /:[ \t]*$/.test(head);
+  if (isColon) {
+    const baseType = value.replace(/\[\s*\]?$|\[$/, '');
+    if (TS_TYPE_NAMES.has(baseType)) return true;
+    if (/^[A-Z]|^\[/.test(value)) return true;
+    if (/^(?:new\s|[A-Za-z0-9_$]+\s*\(|[A-Za-z0-9_$]+\.[A-Za-z0-9_$]+)/.test(value)) return true;
+  }
+  const isEquals = /=[ \t]*$/.test(head);
+  if (isEquals) {
+    const before = fullString.slice(Math.max(0, offset - 30), offset);
+    if (/(?:const|let|var|readonly)\s+$/.test(before)) return true;
+    if (/\bnew\s|[A-Za-z0-9_$]+\.[A-Za-z0-9_$]+|\(/.test(value)) return true;
+    if (/^[\[{]/.test(value)) return true;
+  }
+  return false;
+}
+
 function isMasked(value        )          { return value.replace(/^["']|["']$/g, '') === MASKED; }
 
 function count(text        , token        )         { return text.split(token).length - 1; }
@@ -119,8 +239,8 @@ function mask(text     , profile                 , options      = {})
   // 3. Bearer tokens and URL credentials.
   out = out.replace(BEARER, `$1$2${MASKED}`).replace(URL_CREDENTIALS, `://${MASKED}@`);
   // 4. Key=value, unquoted, when the value is not plain letters.
-  out = out.replace(KEY_VALUE_LINE, (match        , key        , separator        , value        ) => (
-    isMasked(value) || value.startsWith(MASKED) || !/[^A-Za-z]/.test(value) ? match : `${key}${separator}${MASKED}`));
+  out = out.replace(KEY_VALUE_LINE, (match        , key        , separator        , value        , offset        , fullString        ) => (
+    isMasked(value) || value.startsWith(MASKED) || !/[^A-Za-z]/.test(value) || isCodePreserved(key + separator, value, offset, fullString) ? match : `${key}${separator}${MASKED}`));
   // 5. Long secret-looking runs that are not paths.
   out = out.replace(LONG_RUN, (run        , offset        ) => (
     looksLikeSecretRun(run, 2) && !isPathRun(run, out[offset - 1]) ? MASKED : mask40(run, out[offset - 1])));
@@ -129,8 +249,9 @@ function mask(text     , profile                 , options      = {})
 
   if (profile === 'body') {
     // 7. Key and value, quoted or not, whatever the value looks like.
-    out = out.replace(KEY_VALUE_BODY, (match        , head        , value        ) => {
+    out = out.replace(KEY_VALUE_BODY, (match        , head        , value        , offset        , fullString        ) => {
       if (isMasked(value) || value.startsWith(MASKED)) return match;
+      if (isCodePreserved(head, value, offset, fullString)) return match;
       const quote = value[0] === '"' || value[0] === "'" ? value[0] : '';
       return `${head}${quote}${MASKED}${quote}`;
     });
@@ -138,6 +259,12 @@ function mask(text     , profile                 , options      = {})
     out = out.replace(AUTH_HEADER, (match        , name        , rest        ) => (rest === '' || rest === MASKED ? match : `${name} ${MASKED}`));
     // 9. Secret-bearing command-line flags.
     out = out.replace(SECRET_FLAG, (match        , flag        , value        ) => (isMasked(value) ? match : `${flag}${MASKED}`));
+    // 14 and 15. `curl -u user:pw`, `curl --user user:pw`, `curl -uuser:pw` and `mysql -psecret`, every flag of a command.
+    out = maskCommandFlags(out);
+    // 16. `password hunter2`: the key word, a space and a value with a non-letter in it.
+    out = out.replace(PASSWORD_PHRASE, (match        , head        , value        ) => (/[^A-Za-z]/.test(value) && !/^[0-9]{1,3}$/.test(value) ? `${head}${MASKED}` : match));
+    // 17. Another user's home directory: `/Users/<name>` becomes `/Users/<masked>`.
+    out = out.replace(OTHER_USER_HOME, `/Users/${MASKED}`);
   }
 
   const masked = Math.max(0, [MASKED, EMAIL, IP].reduce((sum, token) => sum + count(out, token) - count(input, token), 0));

package/src/runtime/mcp-consultations.js

@@ -164,11 +164,33 @@ function knownServerIds(registry     )              {
   return ids;
 }
 
+const MANIFEST_PATTERNS = Object.freeze([
+  /(?:^|[\\/])package(?:-lock)?\.json$/,
+  /(?:^|[\\/])pnpm-lock\.yaml$/,
+  /(?:^|[\\/])yarn\.lock$/,
+  /(?:^|[\\/])Cargo\.(?:toml|lock)$/,
+  /(?:^|[\\/])go\.(?:mod|sum)$/,
+  /(?:^|[\\/])requirements.*\.txt$/,
+  /(?:^|[\\/])pyproject\.toml$/,
+  /(?:^|[\\/])poetry\.lock$/,
+  /(?:^|[\\/])Gemfile(?:\.lock)?$/,
+  /(?:^|[\\/])composer\.(?:json|lock)$/,
+  /(?:^|[\\/])build\.gradle(?:\.kts)?$/,
+  /(?:^|[\\/])pom\.xml$/,
+  /(?:^|[\\/])Package\.swift$/,
+  /(?:^|[\\/])Podfile(?:\.lock)?$/,
+]);
+
+function touchesManifest(files           )          {
+  if (!Array.isArray(files) || files.length === 0) return false;
+  return files.some((f) => MANIFEST_PATTERNS.some((pattern) => pattern.test(f)));
+}
+
 /**
  * Servers a stage run names (IC-001 meaning). Sorted.
- * @param {{registry: object, skill: string, stageId?: string, taskId?: string, requests?: {list: Function}}} input
+ * @param {{registry: object, skill: string, stageId?: string, taskId?: string, requests?: {list: Function}, taskClass?: string, diffFiles?: string[]}} input
  */
-function namedServers({ registry, skill, stageId, taskId, requests }     )           {
+function namedServers({ registry, skill, stageId, taskId, requests, taskClass, diffFiles }     )           {
   let researchRequested                     ;
   const hasRequest = ()          => {
     if (researchRequested === undefined) {
@@ -178,12 +200,21 @@ function namedServers({ registry, skill, stageId, taskId, requests }     )
     }
     return researchRequested;
   };
+
+  const isDependencyChange = taskClass === 'dependency-change';
+  const hasManifestDiff = touchesManifest(diffFiles);
+
   const named = new Set        ();
   for (const server of registry?.mcp || []) {
     for (const step of server.steps || []) {
-      if (step.expectedWhen === 'research-request') {
-        if (hasRequest()) named.add(server.id);
-      } else if (step.skill === skill) {
+      if (step.skill !== skill) continue;
+      if (!step.expectedWhen) {
+        named.add(server.id);
+      } else if (step.expectedWhen === 'research-request' && hasRequest()) {
+        named.add(server.id);
+      } else if (step.expectedWhen === 'dependency-change' && isDependencyChange) {
+        named.add(server.id);
+      } else if (step.expectedWhen === 'manifest-review' && hasManifestDiff) {
         named.add(server.id);
       }
     }
@@ -213,13 +244,14 @@ const bySortKey = (a     , b     )         => (a < b ? -1 : a > b ? 1 : 0);
 function resolveConsultations({
   taskId = null, stageId = null, skill, flags, registry, ledger, requests,
   briefRecords = [], readReport, reach, addCommand, harnessName, since = null,
+  taskClass = null, diffFiles = [],
 }      = {})                                                                         {
   const warnings        = [];
   const notices        = [];
   const evidenceToAdd        = [];
   const registered = new Set((registry?.mcp || []).map((server     ) => server.id));
   const known = knownServerIds(registry);
-  const named = namedServers({ registry, skill, stageId, taskId, requests });
+  const named = namedServers({ registry, skill, stageId, taskId, requests, taskClass, diffFiles });
 
   // Rule 1: flags.
   const parsedFlags = parseMcpOutcomeFlags(flags);
@@ -408,5 +440,7 @@ module.exports = {
   parseMcpOutcomeFlags,
   parseToolsUsed,
   namedServers,
+  touchesManifest,
+  MANIFEST_PATTERNS,
   resolveConsultations,
 };

package/src/runtime/model-router.js

@@ -39,22 +39,58 @@ function availableProviderIds({ fsImpl = fs }                   = {})
     .map(([id]) => id);
 }
 
+function normalizeFamilyList(value     )           {
+  const values = Array.isArray(value) ? value : [value];
+  return [...new Set(values.flatMap((entry) => String(entry ?? '').split(',').map((family) => family.trim().toLowerCase()).filter(Boolean)))];
+}
+
+// families is a hand-kept stopgap; the model-facts registry (roadmap row 105) supersedes it and this field is removed then.
+/** An unknown family is not evidence that a provider can review outside the author's family. */
+function familyInfo(families     , excludedFamilies             )                                                                                               {
+  const declared = Array.isArray(families) ? families : [];
+  const hasUnknown = declared.length === 0
+    || declared.some((family) => typeof family !== 'string' || !/^[a-z][a-z0-9-]*$/.test(family) || family === 'unknown');
+  const overlapsAuthor = declared.some((family) => typeof family === 'string'
+    && family !== 'unknown' && /^[a-z][a-z0-9-]*$/.test(family) && excludedFamilies.has(family));
+  const familyRelation = overlapsAuthor ? 'overlaps-author' : hasUnknown ? 'unverified' : 'cross-family';
+  const sameFamily = declared.length > 0 && declared.every((family) => typeof family === 'string' && excludedFamilies.has(family));
+  return {
+    families: [...declared],
+    familyVerified: familyRelation === 'cross-family',
+    familyRelation,
+    sameFamily,
+  };
+}
+
 /**
  * Resolve one role to ranked candidates.
  * Ordering: available first, then preferred-tier match, then fallback-tier match, registry order
- * breaking ties. `exclude` drops provider ids entirely (e.g. the implementer when the role is
- * review with require:different-family) and is reported back rather than hidden.
+ * breaking ties. `exclude` drops provider ids entirely; `excludeFamilies` drops providers whose
+ * complete, known catalogue is within the excluded model families. Unknown catalogues are kept
+ * unverified rather than being presented as cross-family.
  * Availability unknown stays null — absence of evidence is not reported as absent.
  */
-function resolveModelRole({ registry, roleId, isAvailable = null, exclude = [] }      = {})      {
+function resolveModelRole({ registry, roleId, isAvailable = null, exclude = [], excludeFamilies }      = {})      {
   const role = (registry.modelRoles || []).find((entry     ) => entry.id === roleId);
   if (!role) {
     throw new Error(`Unknown model role '${roleId}'; valid: ${(registry.modelRoles || []).map((r     ) => r.id).join(', ')}`);
   }
   const excluded = new Set(exclude);
+  const familyMode = excludeFamilies !== undefined && excludeFamilies !== null;
+  const normalizedFamilies = familyMode ? normalizeFamilyList(excludeFamilies) : [];
+  if (familyMode && normalizedFamilies.length === 0) {
+    throw new Error('--exclude-family requires at least one family name');
+  }
+  const excludedFamilies = new Set(normalizedFamilies);
   const candidates        = [];
+  const familyExcluded           = [];
   for (const [index, provider] of (registry.modelProviders || []).entries()) {
     if (excluded.has(provider.id)) continue;
+    const family = familyInfo(provider.families, excludedFamilies);
+    if (familyMode && family.sameFamily) {
+      familyExcluded.push(provider.id);
+      continue;
+    }
     const tiers = provider.tiers ?? [];
     candidates.push({
       id: provider.id,
@@ -64,6 +100,7 @@ function resolveModelRole({ registry, roleId, isAvailable = null, exclude = [] }
       available: isAvailable ? Boolean(isAvailable(provider.id)) : null,
       servesPreferredTier: role.prefer ? tiers.includes(role.prefer) : null,
       servesFallbackTier: role.fallback ? tiers.includes(role.fallback) : null,
+      ...(familyMode ? { families: family.families, familyRelation: family.familyRelation, familyVerified: family.familyVerified } : {}),
       _index: index,
     });
   }
@@ -79,12 +116,19 @@ function resolveModelRole({ registry, roleId, isAvailable = null, exclude = [] }
     return 0;
   });
   for (const candidate of candidates) delete candidate._index;
-  return {
+  const result      = {
     roleId,
     policy: { prefer: role.prefer ?? null, fallback: role.fallback ?? null, require: role.require ?? null },
     candidates,
     excluded: [...excluded],
   };
+  // Keep the established result shape byte-for-byte for callers that do not request family
+  // filtering. Family metadata is included whenever that comparison is requested.
+  if (familyMode) {
+    result.excludedFamilies = [...excludedFamilies];
+    result.familyExcluded = familyExcluded;
+  }
+  return result;
 }
 
 /**
@@ -118,7 +162,7 @@ function resolveRetrievalSlot({ registry, slotId, isAvailable = null }      = {}
 
 /** CLI handler for `doflow model-role`. Read-only advisory routing; exits 1 on an unknown role
  * because a silently-empty candidate list would read as "no providers" rather than "bad input". */
-function handleModelRoleCommand({ role, exclude, json = false, repoRoot }      = {})                     {
+function handleModelRoleCommand({ role, exclude, excludeFamilies, json = false, repoRoot }      = {})                     {
   if (!role) return usageError('model-role', '--role is required (one of the roles in core/registry/models.json)', json);
   const registry = (() => {
     try { return loadRegistry({ repoRoot: repoRoot || REPO_ROOT }); }
@@ -127,20 +171,48 @@ function handleModelRoleCommand({ role, exclude, json = false, repoRoot }      =
   if (!registry) return undefined;
   const available = new Set(availableProviderIds());
   try {
+    const excludedProviderIds = Array.isArray(exclude) ? exclude : String(exclude ?? '').split(',').map((s        ) => s.trim()).filter(Boolean);
+    const requestedFamilies = excludeFamilies === undefined || excludeFamilies === null ? null : normalizeFamilyList(excludeFamilies);
+    if (requestedFamilies !== null) {
+      const knownFamilies = [...new Set((registry.modelProviders || []).flatMap((provider     ) => provider.families || []))]
+        .filter((family)                   => typeof family === 'string' && family !== 'unknown').sort();
+      const knownSet = new Set(knownFamilies);
+      const unknownFamilies = requestedFamilies.filter((family) => !knownSet.has(family));
+      if (requestedFamilies.length === 0) {
+        return usageError('model-role', `--exclude-family requires at least one family name; known families: ${knownFamilies.join(', ') || '(none)'}`, json);
+      }
+      if (requestedFamilies.includes('unknown')) {
+        return usageError('model-role', `unknown cannot be excluded because it names missing knowledge; known families: ${knownFamilies.join(', ') || '(none)'}`, json);
+      }
+      if (unknownFamilies.length) {
+        return usageError('model-role', `unknown family name${unknownFamilies.length === 1 ? '' : 's'}: ${unknownFamilies.join(', ')}; known families: ${knownFamilies.join(', ') || '(none)'}`, json);
+      }
+    }
     const resolution = resolveModelRole({
       registry,
       roleId: role,
       isAvailable: (providerId        ) => available.has(providerId),
-      exclude: Array.isArray(exclude) ? exclude : String(exclude ?? '').split(',').map((s        ) => s.trim()).filter(Boolean),
+      exclude: excludedProviderIds,
+      ...(requestedFamilies === null ? {} : { excludeFamilies: requestedFamilies }),
     });
     if (json) console.log(JSON.stringify(resolution, null, 2));
     else {
       console.log(`Role '${resolution.roleId}' — prefer:${resolution.policy.prefer ?? '—'} fallback:${resolution.policy.fallback ?? '—'} require:${resolution.policy.require ?? '—'}`);
       for (const candidate of resolution.candidates) {
         const availability = candidate.available === null ? '?' : candidate.available ? 'yes' : 'no';
-        console.log(`  ${candidate.available ? '*' : ' '} ${candidate.id} (${candidate.kind}, via ${candidate.backendCli ?? 'hosted'}) available=${availability}${resolution.policy.prefer && candidate.servesPreferredTier ? ` serves ${resolution.policy.prefer}` : ''}`);
+        const familyStatus = requestedFamilies === null ? ''
+          : ` ${candidate.familyRelation}`;
+        console.log(`  ${candidate.available ? '*' : ' '} ${candidate.id} (${candidate.kind}, via ${candidate.backendCli ?? 'hosted'}) available=${availability}${resolution.policy.prefer && candidate.servesPreferredTier ? ` serves ${resolution.policy.prefer}` : ''}${familyStatus}`);
       }
       if (resolution.excluded.length) console.log(`Excluded: ${resolution.excluded.join(', ')}`);
+      if (requestedFamilies !== null) {
+        const familySet = new Set(requestedFamilies);
+        const providerExcluded = new Set(excludedProviderIds);
+        const sameFamily = (registry.modelProviders || []).filter((provider     ) => !providerExcluded.has(provider.id)
+          && familyInfo(provider.families, familySet).sameFamily);
+        for (const provider of sameFamily) console.log(`  ${provider.id} same-family (excluded)`);
+        if (resolution.excludedFamilies.length) console.log(`Excluded families: ${resolution.excludedFamilies.join(', ')}`);
+      }
     }
     return finishRuntime(0);
   } catch (error     ) {

package/src/runtime/models/catalogue.js

@@ -0,0 +1,191 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { PROBES, HARNESS_IDS } = require('../worker/probes/index.js');
+const { configHome } = require('../config-home.js');
+
+                                                                              
+                                                                     
+                                                            
+
+                               
+             
+                       
+                  
+ 
+
+                               
+                                        
+                   
+ 
+
+                                    
+                    
+                 
+                     
+                         
+                         
+                             
+                             
+                                 
+                                     
+                       
+                       
+ 
+
+                                                
+
+                                    
+                  
+                   
+                                             
+ 
+
+function getProjectCataloguePath(projectRoot        )         {
+  return path.join(projectRoot, '.doflow', 'state', 'models', 'catalogue.json');
+}
+
+function getUserCataloguePath(homeDir         , env      = process.env)         {
+  if (homeDir) {
+    return path.join(homeDir, '.config', 'doflow', 'state', 'models-observed.json');
+  }
+  const { dir } = configHome(env);
+  const baseDir = dir || path.join(os.homedir(), '.config', 'doflow');
+  return path.join(baseDir, 'state', 'models-observed.json');
+}
+
+function resolveProjectRoot(projectRoot         , fsImpl      = fs)                {
+  if (projectRoot) return path.resolve(projectRoot);
+  try {
+    const { projectRoot: findRoot } = require('../lifecycle/root.js');
+    const root = findRoot(process.cwd());
+    if (root && fsImpl.existsSync(path.join(root, '.doflow'))) return root;
+  } catch {
+    // fallback
+  }
+  if (fsImpl.existsSync(path.join(process.cwd(), '.doflow'))) {
+    return process.cwd();
+  }
+  return null;
+}
+
+function readCatalogue(
+  projectRoot         ,
+  options                                                = {}
+)                           {
+  const fsImpl = options.fsImpl || fs;
+  const root = projectRoot ? path.resolve(projectRoot) : resolveProjectRoot(undefined, fsImpl);
+
+  if (root) {
+    const projPath = getProjectCataloguePath(root);
+    if (fsImpl.existsSync(projPath)) {
+      try {
+        const raw = fsImpl.readFileSync(projPath, 'utf8');
+        return JSON.parse(raw);
+      } catch (err     ) {
+        if (err instanceof SyntaxError) {
+          const corrupt = `${projPath}.corrupt-${Date.now()}`;
+          try {
+            fsImpl.renameSync(projPath, corrupt);
+          } catch {
+            // best-effort
+          }
+          return null;
+        }
+        return null;
+      }
+    }
+  }
+
+  // Fallback to user cache
+  const userPath = getUserCataloguePath(options.homeDir, options.env);
+  if (fsImpl.existsSync(userPath)) {
+    try {
+      const raw = fsImpl.readFileSync(userPath, 'utf8');
+      return JSON.parse(raw);
+    } catch (err     ) {
+      if (err instanceof SyntaxError) {
+        const corrupt = `${userPath}.corrupt-${Date.now()}`;
+        try {
+          fsImpl.renameSync(userPath, corrupt);
+        } catch {
+          // best-effort
+        }
+        return null;
+      }
+      return null;
+    }
+  }
+
+  return null;
+}
+
+function writeCatalogue(
+  catalogue                   ,
+  projectRoot         ,
+  options                                                = {}
+)       {
+  const fsImpl = options.fsImpl || fs;
+  const root = projectRoot ? path.resolve(projectRoot) : resolveProjectRoot(undefined, fsImpl);
+  const targetPath = root ? getProjectCataloguePath(root) : getUserCataloguePath(options.homeDir, options.env);
+
+  const targetDir = path.dirname(targetPath);
+  fsImpl.mkdirSync(targetDir, { recursive: true });
+
+  const tmpPath = `${targetPath}.${process.pid}.${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`;
+  fsImpl.writeFileSync(tmpPath, JSON.stringify(catalogue, null, 2), 'utf8');
+  fsImpl.renameSync(tmpPath, targetPath);
+}
+
+async function syncHarness(
+  harnessId        ,
+  options                                                                                                              = {}
+)                             {
+  const probe = PROBES[harnessId];
+  if (!probe) {
+    return {
+      harnessId,
+      binary: harnessId,
+      installed: false,
+      version: null,
+      loginState: 'unsupported',
+      reloginHint: null,
+      detectedMode: 'unverified',
+      derivedBilling: 'unknown',
+      offeredModels: [],
+      lastSyncedAt: new Date().toISOString(),
+    };
+  }
+
+  return await probe(options);
+}
+
+async function syncAllHarnesses(
+  options                                                                                                              = {}
+)                             {
+  const results                                    = {};
+  for (const id of HARNESS_IDS) {
+    results[id] = await syncHarness(id, options);
+  }
+
+  const catalogue                    = {
+    version: 1,
+    syncedAt: new Date().toISOString(),
+    harnesses: results,
+  };
+
+  writeCatalogue(catalogue, options.projectRoot, options);
+  return catalogue;
+}
+
+module.exports = {
+  getProjectCataloguePath,
+  getUserCataloguePath,
+  readCatalogue,
+  writeCatalogue,
+  syncHarness,
+  syncAllHarnesses,
+};