@on-par/factory-cli 0.9.3 → 0.9.5-next.1

package/dist/cli/doctor.js

@@ -1,9 +1,17 @@
 // packages/cli/src/cli/doctor.ts — `factory doctor` environment preflight
+import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { detectSandboxRuntime } from '@on-par/factory-core';
+import { findConfigSchemaErrors, isHarnessCliPresent, isTemplateToken, lintFactoryConfig, listBuiltInCheckers, } from '@on-par/factory-core/internal';
 import { MIN_NODE_MAJOR } from '../node-version.js';
-import { CLAUDE_CODE_URL, GITHUB_TOKENS_URL } from './first-run.js';
+import { availableAgentClis, CLAUDE_CODE_URL, CODEX_CLI_URL, GITHUB_TOKENS_URL } from './first-run.js';
+/** Section for rows about repo-configured command harnesses (#2691). */
+export const COMMAND_HARNESS_SECTION = 'Command harness';
+/** Repo wired-up rows, sectioned only inside a git repo (#2557). */
+export const REPO_SECTION = 'Repo';
 export const NOT_IN_REPO_HINT = 'cd into your repo, then run factory doctor again';
+/** Detail for every repo wired-up row when doctor runs outside a git repository (#2554). */
+export const NOT_IN_REPO_SKIP_DETAIL = `skipped: not inside a git repository; ${NOT_IN_REPO_HINT}`;
 export function hasSandboxRuntime(platform, commandAvailable) {
     return detectSandboxRuntime(platform, commandAvailable) !== 'none';
 }
@@ -11,13 +19,298 @@ export function hasSandboxRuntime(platform, commandAvailable) {
  *  or null when cmdDoctor should resolve the policy as before (#2383). */
 export function sandboxAuthSkipDetail(opts) {
     if (!opts.runtimeAvailable)
-        return 'skipped — no sandbox runtime (sandbox-exec/firejail) on this host';
+        return 'skipped: no sandbox runtime (sandbox-exec/firejail) on this host';
     if (!opts.hostOk)
-        return 'skipped — host claude auth was not verified';
+        return 'skipped: host claude auth was not verified';
     if (!opts.inRepo)
-        return `skipped — not inside a git repository; ${NOT_IN_REPO_HINT}`;
+        return NOT_IN_REPO_SKIP_DETAIL;
     return null;
 }
+/** Sign-in method reported by `codex login status`, or null when it shows no login. Never returns
+ *  any part of a credential: only a fixed label is derived from the status text. */
+export function codexAuthMethod(statusOutput) {
+    if (statusOutput === null)
+        return null;
+    const text = statusOutput.toLowerCase();
+    if (!text.includes('logged in') || text.includes('not logged in'))
+        return null;
+    if (text.includes('chatgpt'))
+        return 'ChatGPT';
+    if (text.includes('api key'))
+        return 'API key';
+    if (text.includes('access token'))
+        return 'access token';
+    return 'unknown method';
+}
+const GIT_AUTH_CHECK = 'git auth';
+/** Non-interactive read-only probe of origin. `credential.interactive=never` turns off Git
+ *  Credential Manager UI and an empty `core.askPass` turns off configured askpass programs;
+ *  stored credentials from any helper still work. */
+export const GIT_AUTH_PROBE_CMD = 'git -c credential.interactive=never -c core.askPass= ls-remote --quiet origin HEAD';
+/** GIT_TERMINAL_PROMPT=0 makes git fail instead of asking on the terminal; empty GIT_ASKPASS
+ *  and SSH_ASKPASS turn off askpass programs and ssh's GUI askpass; GCM_INTERACTIVE=never
+ *  turns off Git Credential Manager prompts. */
+export const GIT_AUTH_PROBE_ENV = {
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_ASKPASS: '',
+    SSH_ASKPASS: '',
+    GCM_INTERACTIVE: 'never',
+};
+/** Bounds the probe, e.g. an ssh key passphrase prompt that waits on /dev/tty. */
+export const GIT_AUTH_PROBE_TIMEOUT_MS = 15_000;
+/** Remedy shown only when the git-auth probe fails: wires git's credential helper to gh. */
+export const GIT_AUTH_FIX = 'run `gh auth setup-git` so git uses your gh credentials, then re-run `factory doctor`';
+/** Git-auth check (#2482, #2483): skipped, never failing, outside a git repository or without
+ *  an origin remote. Otherwise runs a non-interactive `git ls-remote` against origin and fails
+ *  when it cannot authenticate. The detail never echoes the origin URL, which may hold a token. */
+export function gitAuthCheck(repoRoot, tryExec) {
+    if (repoRoot === null) {
+        return {
+            name: GIT_AUTH_CHECK,
+            ok: true,
+            optional: true,
+            detail: NOT_IN_REPO_SKIP_DETAIL,
+        };
+    }
+    const origin = tryExec('git remote get-url origin');
+    if (!origin) {
+        return { name: GIT_AUTH_CHECK, ok: true, optional: true, detail: 'skipped: no origin remote configured' };
+    }
+    // An empty string is exit 0 with no HEAD ref (an empty repo): still authenticated.
+    const probe = tryExec(GIT_AUTH_PROBE_CMD, { env: { ...GIT_AUTH_PROBE_ENV }, timeoutMs: GIT_AUTH_PROBE_TIMEOUT_MS });
+    if (probe === null) {
+        return {
+            name: GIT_AUTH_CHECK,
+            ok: false,
+            detail: 'git could not authenticate to origin non-interactively (prompting disabled)',
+            fix: GIT_AUTH_FIX,
+            next: 'gh auth setup-git',
+        };
+    }
+    return { name: GIT_AUTH_CHECK, ok: true, detail: 'git can authenticate to origin non-interactively' };
+}
+/** One doctor section per built-in harness (#2555), in display order. */
+export const HARNESS_SETUP = [
+    {
+        section: 'Claude Code',
+        harnessId: 'claude-cli',
+        cli: 'claude',
+        install: 'npm install -g @anthropic-ai/claude-code',
+        login: 'claude /login',
+        envKeys: ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'],
+    },
+    {
+        section: 'Codex',
+        harnessId: 'codex-cli',
+        cli: 'codex',
+        install: 'npm install -g @openai/codex',
+        login: 'codex login',
+        envKeys: ['CODEX_API_KEY'],
+    },
+    {
+        section: 'OpenCode',
+        harnessId: 'opencode',
+        cli: 'opencode',
+        install: 'npm install -g opencode-ai',
+        login: 'opencode auth login',
+        envKeys: ['OPENCODE_API_KEY'],
+    },
+];
+/** One optional `<cli> installed` row per harness, with the CLI version when found and the install command when not (#2555). */
+export function harnessInstallChecks(commandAvailable, tryExec) {
+    return HARNESS_SETUP.map(({ section, cli, install }) => {
+        const name = `${cli} installed`;
+        if (!commandAvailable(cli)) {
+            return {
+                name,
+                section,
+                ok: false,
+                optional: true,
+                detail: `${cli} not found on PATH, ${cli} routes unavailable`,
+                fix: `install ${section}: ${install}`,
+            };
+        }
+        const version = tryExec(`${cli} --version`)?.trim().split('\n')[0]?.trim();
+        return {
+            name,
+            section,
+            ok: true,
+            optional: true,
+            detail: version ? `found on PATH (${version})` : 'found on PATH (version unknown)',
+        };
+    });
+}
+const SIGN_IN_EVIDENCE = {
+    claude: 'no ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN or stored login',
+    codex: 'no CODEX_API_KEY or codex login; API billing: codex login --with-api-key; headless: codex login --device-auth',
+    opencode: 'no OPENCODE_API_KEY or stored auth login',
+};
+function safe(fn) {
+    if (!fn)
+        return false;
+    try {
+        return fn();
+    }
+    catch {
+        return false;
+    }
+}
+/** One `<cli> signed in` row per installed harness CLI (#2556, #2631), judged only from local evidence: an env key,
+ *  stored credentials, or `codex login status`. Never runs inference and never prints a secret. */
+export function harnessSignInChecks(probes) {
+    const { commandAvailable, envPresent, tryExec } = probes;
+    const found = availableAgentClis(commandAvailable);
+    return HARNESS_SETUP.filter(({ harnessId }) => isHarnessCliPresent(harnessId, commandAvailable)).map(({ section, cli, login, envKeys }) => {
+        const name = `${cli} signed in`;
+        const fix = `sign in to ${section}: ${login}`;
+        if (cli === 'codex') {
+            const key = envKeys.find((k) => envPresent(k));
+            if (key)
+                return { name, section, ok: true, detail: `signed in (${key} set)` };
+            const method = codexAuthMethod(tryExec('codex login status 2>&1'));
+            const session = method === 'ChatGPT' ? (probes.codexSessionState?.() ?? 'unknown') : 'unknown';
+            if (session === 'unusable') {
+                return {
+                    name,
+                    section,
+                    ok: false,
+                    optional: found.length > 1,
+                    detail: 'ChatGPT session in auth.json is unusable (unreadable, or no valid access token and no refresh token)',
+                    fix,
+                    next: login,
+                };
+            }
+            if (session === 'refresh-pending') {
+                return {
+                    name,
+                    section,
+                    ok: true,
+                    detail: 'logged in with ChatGPT; access token expired, codex refreshes it on the next run (run `codex login` if that run fails with 401)',
+                };
+            }
+            if (method) {
+                return {
+                    name,
+                    section,
+                    ok: true,
+                    detail: method === 'ChatGPT'
+                        ? 'logged in with ChatGPT; runs draw on your ChatGPT plan limits (manage usage in ChatGPT settings)'
+                        : `logged in with ${method}`,
+                };
+            }
+        }
+        else {
+            const key = envKeys.find((k) => envPresent(k));
+            if (key)
+                return { name, section, ok: true, detail: `signed in (${key} set)` };
+            if (cli === 'claude' && safe(probes.claudeLoggedIn)) {
+                return { name, section, ok: true, detail: 'signed in (stored Claude Code login found)' };
+            }
+            if (cli === 'opencode' && safe(probes.opencodeLoggedIn)) {
+                return { name, section, ok: true, detail: 'signed in (stored opencode auth login found)' };
+            }
+        }
+        return {
+            name,
+            section,
+            ok: false,
+            // Required only when this is the sole agent: then nothing else can run.
+            optional: found.length > 1,
+            detail: `unverified: no sign-in evidence (${SIGN_IN_EVIDENCE[cli]})`,
+            fix,
+            next: login,
+        };
+    });
+}
+function safeList(fn) {
+    if (!fn)
+        return [];
+    try {
+        return fn();
+    }
+    catch {
+        return [];
+    }
+}
+/** The executable (first token) of a command template, or null when it cannot be parsed safely (#2691).
+ *  Guards `isCommandAvailable`, which interpolates into `command -v` unescaped. */
+export function commandExecutable(command) {
+    const tokens = command.trim().split(/\s+/);
+    while (tokens.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[0]))
+        tokens.shift();
+    let token = tokens[0];
+    if (!token)
+        return null;
+    const quoted = /^(['"])(.*)\1$/.exec(token);
+    if (quoted)
+        token = quoted[2];
+    return /^[\w./@+~-]+$/.test(token) ? token : null;
+}
+/** Declared, agentic command harnesses that at least one repo `models.registry` entry uses (#2691). */
+export function repoCommandHarnesses(harnesses, registry) {
+    const used = new Set(Object.values(registry ?? {}).map((def) => def.harness));
+    return Object.entries(harnesses ?? {})
+        .filter(([id, decl]) => decl.agentic === true && used.has(id))
+        .map(([id, decl]) => ({ harness: id, command: decl.command, executable: commandExecutable(decl.command) }));
+}
+/** One optional `command harness <id>` row per configured command harness (#2691). */
+export function commandHarnessChecks(harnesses, commandAvailable) {
+    return harnesses.map((h) => {
+        const name = `command harness ${h.harness}`;
+        if (h.executable !== null && commandAvailable(h.executable)) {
+            return {
+                name,
+                section: COMMAND_HARNESS_SECTION,
+                optional: true,
+                ok: true,
+                detail: `${h.executable} found on PATH (command: ${h.command})`,
+            };
+        }
+        return {
+            name,
+            section: COMMAND_HARNESS_SECTION,
+            optional: true,
+            ok: false,
+            detail: `configured command \`${h.command}\`: ${h.executable === null ? 'cannot parse an executable from it' : `${h.executable} not found on PATH`}`,
+            fix: installFix(h),
+        };
+    });
+}
+function installFix(h) {
+    return `install ${h.executable ?? 'the agent CLI'} on PATH or fix "command" for harness ${h.harness} in the models config harnesses section`;
+}
+/** Coding agent prerequisites: at least one agent CLI is required; each CLI is then reported
+ *  on its own optional line, with sign-in reported separately from installation (#1269, #2422, #2555, #2556).
+ *  A repo-configured command harness whose executable is on PATH also counts as a coding agent (#2691). */
+export function agentCliChecks(probes) {
+    const { commandAvailable, tryExec } = probes;
+    const found = availableAgentClis(commandAvailable);
+    const configured = safeList(probes.commandHarnesses);
+    const runnable = configured.filter((h) => h.executable !== null && commandAvailable(h.executable));
+    const agents = [...found, ...runnable.map((h) => `${h.harness} (command harness)`)];
+    const describe = (h) => `command harness ${h.harness} runs \`${h.command}\`, but ${h.executable ?? 'its executable'} is not on PATH`;
+    const missingRow = configured.length === 0
+        ? {
+            name: 'coding agent',
+            ok: false,
+            detail: 'no coding agent CLI on PATH (claude, codex or opencode)',
+            fix: `install Claude Code (${CLAUDE_CODE_URL}) or the Codex CLI (${CODEX_CLI_URL})`,
+            next: HARNESS_SETUP[0].install,
+        }
+        : {
+            name: 'coding agent',
+            ok: false,
+            detail: `no coding agent CLI on PATH (claude, codex or opencode); ${configured.map(describe).join('; ')}`,
+            fix: installFix(configured[0]),
+        };
+    const checks = [
+        agents.length > 0 ? { name: 'coding agent', ok: true, detail: `found ${agents.join(', ')}` } : missingRow,
+    ];
+    checks.push(...harnessInstallChecks(commandAvailable, tryExec));
+    checks.push(...commandHarnessChecks(configured, commandAvailable));
+    checks.push(...harnessSignInChecks(probes));
+    return checks;
+}
 export function runDoctorChecks(probes) {
     const { commandAvailable, envPresent, tryExec, pathExists, distFreshness } = probes;
     const checks = [];
@@ -28,37 +321,40 @@ export function runDoctorChecks(probes) {
             name: 'git repository',
             ok: false,
             optional: true,
-            detail: 'not inside a git repository — repo checks skipped',
+            detail: 'not inside a git repository; repo checks skipped',
             fix: NOT_IN_REPO_HINT,
         });
-    const userName = tryExec('git config user.name');
-    const userEmail = tryExec('git config user.email');
-    if (userName && userEmail) {
-        checks.push({ name: 'git identity', ok: true, detail: `${userName} <${userEmail}>` });
+    const repoSection = repoRoot === null ? {} : { section: REPO_SECTION };
+    if (repoRoot === null) {
+        checks.push({ name: 'git identity', ok: false, optional: true, detail: NOT_IN_REPO_SKIP_DETAIL });
     }
     else {
-        const missing = [!userName && 'user.name', !userEmail && 'user.email'].filter(Boolean).join(' and ');
-        checks.push({
-            name: 'git identity',
-            ok: false,
-            detail: `${missing} not set`,
-            fix: 'git config --global user.name "Your Name" && git config --global user.email you@example.com',
-        });
+        const userName = tryExec('git config user.name');
+        const userEmail = tryExec('git config user.email');
+        if (userName && userEmail) {
+            checks.push({ name: 'git identity', ok: true, detail: `${userName} <${userEmail}>`, ...repoSection });
+        }
+        else {
+            const missing = [!userName && 'user.name', !userEmail && 'user.email'].filter(Boolean).join(' and ');
+            checks.push({
+                name: 'git identity',
+                ok: false,
+                detail: `${missing} not set`,
+                next: !userName
+                    ? 'git config --global user.name "Your Name"'
+                    : 'git config --global user.email you@example.com',
+                ...repoSection,
+            });
+        }
     }
-    checks.push(commandAvailable('claude')
-        ? { name: 'claude CLI', ok: true, detail: 'found on PATH' }
-        : {
-            name: 'claude CLI',
-            ok: false,
-            detail: 'not found on PATH',
-            fix: `install Claude Code first: ${CLAUDE_CODE_URL}`,
-        });
+    checks.push(...agentCliChecks(probes));
     if (!commandAvailable('gh')) {
         checks.push({
             name: 'gh auth',
             ok: false,
             detail: 'gh CLI not found on PATH',
-            fix: 'install GitHub CLI and run `gh auth login`',
+            fix: 'install GitHub CLI: https://cli.github.com',
+            next: 'gh auth login',
         });
     }
     else if (tryExec('gh auth status') === null) {
@@ -66,12 +362,13 @@ export function runDoctorChecks(probes) {
             name: 'gh auth',
             ok: false,
             detail: 'gh is not authenticated',
-            fix: 'install GitHub CLI and run `gh auth login`',
+            next: 'gh auth login',
         });
     }
     else {
         checks.push({ name: 'gh auth', ok: true, detail: 'authenticated' });
     }
+    checks.push({ ...gitAuthCheck(repoRoot, tryExec), ...repoSection });
     if (envPresent('GITHUB_TOKEN')) {
         checks.push({ name: 'GitHub token', ok: true, detail: 'GITHUB_TOKEN set' });
     }
@@ -89,6 +386,7 @@ export function runDoctorChecks(probes) {
                 ok: false,
                 detail: 'no GITHUB_TOKEN, GH_TOKEN, or gh auth token',
                 fix: `create a token at ${GITHUB_TOKENS_URL} and export it`,
+                next: 'gh auth login',
             });
         }
     }
@@ -105,11 +403,11 @@ export function runDoctorChecks(probes) {
             name: 'git worktree clean',
             ok: false,
             optional: true,
-            detail: `skipped — not a git repository; ${NOT_IN_REPO_HINT}`,
+            detail: NOT_IN_REPO_SKIP_DETAIL,
         });
     }
     else if (tryExec('git status --porcelain') === '') {
-        checks.push({ name: 'git worktree clean', ok: true, detail: 'clean' });
+        checks.push({ name: 'git worktree clean', ok: true, detail: 'clean', ...repoSection });
     }
     else {
         checks.push({
@@ -118,6 +416,7 @@ export function runDoctorChecks(probes) {
             optional: true,
             detail: 'uncommitted changes present',
             fix: 'commit or stash changes before running the factory',
+            ...repoSection,
         });
     }
     const sandboxRuntime = detectSandboxRuntime(probes.platform ?? process.platform, commandAvailable);
@@ -127,14 +426,14 @@ export function runDoctorChecks(probes) {
             ok: true,
             optional: true,
             detail: sandboxRuntime === 'none'
-                ? 'codex CLI found — no sandbox runtime, so codex runs with danger-full-access'
+                ? 'codex CLI found; no sandbox runtime, so codex runs with danger-full-access'
                 : 'codex CLI found (sandboxed builds available)',
         }
         : {
             name: 'codex sandbox',
             ok: false,
             optional: true,
-            detail: 'codex CLI not found — codex build routes unavailable',
+            detail: 'codex CLI not found; codex build routes unavailable',
             fix: 'install the codex CLI, or rely on claude routes',
         });
     checks.push(sandboxRuntime !== 'none'
@@ -143,7 +442,7 @@ export function runDoctorChecks(probes) {
             name: 'sandbox runtime',
             ok: false,
             optional: true,
-            detail: 'no sandbox-exec (macOS) or firejail (Linux) on PATH — agents will run uncontained',
+            detail: 'no sandbox-exec (macOS) or firejail (Linux) on PATH; agents will run uncontained',
             fix: 'install firejail (Linux) or run on macOS; see README Safety',
         });
     if (repoRoot === null) {
@@ -151,19 +450,19 @@ export function runDoctorChecks(probes) {
             name: '.factory initialized',
             ok: false,
             optional: true,
-            detail: `skipped — not a git repository; ${NOT_IN_REPO_HINT}`,
+            detail: NOT_IN_REPO_SKIP_DETAIL,
         });
     }
     else if (pathExists(resolve(repoRoot, '.factory'))) {
-        checks.push({ name: '.factory initialized', ok: true, optional: true, detail: '.factory/ present' });
+        checks.push({ name: '.factory initialized', ok: true, detail: '.factory/ present', ...repoSection });
     }
     else {
         checks.push({
             name: '.factory initialized',
             ok: false,
-            optional: true,
             detail: '.factory/ missing',
-            fix: 'run `factory init`',
+            next: 'factory init',
+            ...repoSection,
         });
     }
     if (distFreshness) {
@@ -175,16 +474,32 @@ export function runDoctorChecks(probes) {
                 ok: false,
                 detail,
                 fix: "run 'npm run build' at the monorepo root",
+                next: 'npm run build',
             });
     }
     return checks;
 }
-export function formatDoctorChecks(checks) {
+/** Row icon (#2550): ❌ only for a failure (counted in "N failed"), ➖ for a skipped row, ⚠️ for an optional warning. */
+export function doctorCheckIcon(check) {
+    if (!check.ok && !check.optional)
+        return '❌';
+    if (/^skipped\b/.test(check.detail))
+        return '➖';
+    return check.ok ? '✅' : '⚠️';
+}
+/** Outside a repo the models hint is skipped because `factory models --doctor` needs a repo (#2472). */
+export function formatDoctorChecks(checks, opts = {}) {
     const lines = ['== factory doctor =='];
     let passed = 0;
     let failed = 0;
     let warnings = 0;
-    for (const check of checks) {
+    const sections = [...new Set(checks.flatMap((c) => (c.section === undefined ? [] : [c.section])))];
+    const ordered = [
+        ...checks.filter((c) => c.section === undefined),
+        ...sections.flatMap((s) => checks.filter((c) => c.section === s)),
+    ];
+    let currentSection;
+    for (const check of ordered) {
         if (check.ok) {
             passed++;
         }
@@ -194,15 +509,24 @@ export function formatDoctorChecks(checks) {
         else {
             failed++;
         }
-        const icon = check.ok ? '✅' : '❌';
-        lines.push(`  ${icon} ${check.name} — ${check.detail}`);
+        if (check.section !== undefined && check.section !== currentSection) {
+            lines.push(`-- ${check.section} --`);
+        }
+        currentSection = check.section;
+        const icon = doctorCheckIcon(check);
+        lines.push(`  ${icon} ${check.name} - ${check.detail}`);
         if (!check.ok && check.fix) {
             lines.push(`       fix: ${check.fix}`);
         }
+        if (!check.ok && check.next) {
+            lines.push(`       next: ${check.next}`);
+        }
     }
     lines.push(`${passed} passed, ${failed} failed, ${warnings} warnings`);
     lines.push('');
-    lines.push('Model reachability: factory models --doctor');
+    lines.push(opts.inRepo === false
+        ? `Model reachability: ${NOT_IN_REPO_SKIP_DETAIL}`
+        : 'Model reachability: factory models --doctor');
     return lines.join('\n');
 }
 export function doctorFailed(checks) {
@@ -230,15 +554,15 @@ export function claudeKeychainCheck(probe) {
         return {
             name: 'claude keychain (macOS)',
             ok: false,
-            detail: `security find-generic-password -s '${service}'${profile} failed inside tmux (SecKeychainSearchCopyNext) — Claude OAuth refresh will fail with local_auth`,
-            fix: 'run the factory from a context with login-keychain access — a LaunchAgent in the gui domain (launchctl bootstrap gui/$(id -u) …) or a login Terminal, not a raw tmux pane — see docs/runbooks/macos-keychain-launchagent.md',
+            detail: `security find-generic-password -s '${service}'${profile} failed inside tmux (SecKeychainSearchCopyNext); Claude OAuth refresh will fail with local_auth`,
+            fix: 'run the factory from a context with login-keychain access, such as a LaunchAgent in the gui domain (launchctl bootstrap gui/$(id -u) …) or a login Terminal, not a raw tmux pane; see docs/runbooks/macos-keychain-launchagent.md',
         };
     }
     return {
         name: 'claude keychain (macOS)',
         ok: false,
         optional: true,
-        detail: `security find-generic-password -s '${service}'${profile} failed — either never logged in, or this launch context cannot read the login keychain`,
+        detail: `security find-generic-password -s '${service}'${profile} failed; either never logged in, or this launch context cannot read the login keychain`,
         fix: `run ${loginFix(probe)} and complete /login (or export ANTHROPIC_API_KEY); if already logged in, see docs/runbooks/macos-keychain-launchagent.md`,
     };
 }
@@ -248,7 +572,7 @@ export function keychainPreflightError(probe) {
     if (probe.status !== 'unreadable' || !probe.inTmux)
         return null;
     const service = probe.service ?? DEFAULT_KEYCHAIN_SERVICE;
-    return `Claude Code credentials are not readable from this tmux session (security find-generic-password -s '${service}' failed / SecKeychainSearchCopyNext). OAuth refresh will fail and every claimed issue would spuriously park as local_auth. Launch the factory from a context with login-keychain access — a LaunchAgent in the gui domain (launchctl bootstrap gui/$(id -u) …) or a login Terminal — or export ANTHROPIC_API_KEY. See docs/runbooks/macos-keychain-launchagent.md.`;
+    return `Claude Code credentials are not readable from this tmux session (security find-generic-password -s '${service}' failed / SecKeychainSearchCopyNext). OAuth refresh will fail and every claimed issue would spuriously park as local_auth. Launch the factory from a context with login-keychain access, such as a LaunchAgent in the gui domain (launchctl bootstrap gui/$(id -u) …) or a login Terminal, or export ANTHROPIC_API_KEY. See docs/runbooks/macos-keychain-launchagent.md.`;
 }
 const HOST_AUTH_CHECK = 'claude auth (host)';
 const SANDBOX_AUTH_CHECK = 'claude auth (sandboxed)';
@@ -277,7 +601,7 @@ export function sandboxClaudeAuthChecks(result) {
         sandboxed = {
             name: SANDBOX_AUTH_CHECK,
             ok: false,
-            detail: `${result.sandboxDetail} — host claude auth is healthy, so the sandbox is blocking Claude credential refresh`,
+            detail: `${result.sandboxDetail}; host claude auth is healthy, so the sandbox is blocking Claude credential refresh`,
             fix: 'check the sandbox write allowlist (~/.claude.json*, $CLAUDE_CONFIG_DIR when set, ~/Library/Keychains); as a stopgap run with FACTORY_SANDBOX=0',
         };
     }
@@ -286,12 +610,27 @@ export function sandboxClaudeAuthChecks(result) {
             name: SANDBOX_AUTH_CHECK,
             ok: false,
             optional: true,
-            detail: `${result.sandboxDetail} — host claude auth is not healthy either, so this is not attributable to the sandbox`,
+            detail: `${result.sandboxDetail}; host claude auth is not healthy either, so this is not attributable to the sandbox`,
             fix: 'fix host claude auth first, then re-run `factory doctor`',
         };
     }
     return [host, sandboxed];
 }
+const AGENT_AUTH_CHECKS = new Set([...HARNESS_SETUP.map(({ cli }) => `${cli} signed in`), HOST_AUTH_CHECK]);
+/** #2496: doctor fails on agent sign-in only when no installed agent is signed in. A logged-out
+ *  agent is a warning while another one is signed in, and a hard failure when none is. Skipped
+ *  probes (optional passes, e.g. a `<cli> signed in` row for a CLI not on PATH) never count as signed in. */
+export function reconcileAgentAuthChecks(checks) {
+    const auth = checks.filter((c) => AGENT_AUTH_CHECKS.has(c.name));
+    const anySignedIn = auth.some((c) => c.ok && c.optional !== true);
+    return checks.map((c) => {
+        if (!AGENT_AUTH_CHECKS.has(c.name) || c.ok)
+            return c;
+        return anySignedIn
+            ? { ...c, optional: true, detail: `${c.detail} (another agent is signed in, so runs can still proceed)` }
+            : { ...c, optional: false };
+    });
+}
 export function leaseChecks(rows) {
     if (rows.length === 0) {
         return [{ name: 'port leases', ok: true, optional: true, detail: 'no active leases' }];
@@ -302,7 +641,7 @@ export function leaseChecks(rows) {
                 name: `port lease :${row.port}`,
                 ok: true,
                 optional: true,
-                detail: `${row.worktreeId} — port ${row.port}, pid ${row.pid}, live`,
+                detail: `${row.worktreeId}: port ${row.port}, pid ${row.pid}, live`,
             };
         }
         const squatted = row.portSquatted ? '; port still in use by another process' : '';
@@ -310,7 +649,7 @@ export function leaseChecks(rows) {
             name: `port lease :${row.port}`,
             ok: false,
             optional: true,
-            detail: `${row.worktreeId} — port ${row.port}, pid ${row.pid}, stale (${row.reason})${squatted}`,
+            detail: `${row.worktreeId}: port ${row.port}, pid ${row.pid}, stale (${row.reason})${squatted}`,
             fix: 'run `factory doctor --reconcile` to reclaim stale leases',
         };
     });
@@ -349,7 +688,7 @@ export function eventLogCheck(integrity) {
         ok: false,
         optional: true,
         detail: `${integrity.unparseable} of ${integrity.total} lines unparseable (${pct}%)`,
-        fix: 'historical corruption from pre-lock parallel writes; appends are now serialized — metrics over this file carry this error bar',
+        fix: 'historical corruption from pre-lock parallel writes; appends are now serialized; metrics over this file carry this error bar',
     };
 }
 export function orphanContainerChecks(names) {
@@ -380,7 +719,7 @@ export function formatContainerReconcileReport(reaped) {
     return reaped
         .map((r) => r.removed
         ? `reconcile: removed container ${r.name}`
-        : `reconcile: failed to remove container ${r.name} — ${r.detail}`)
+        : `reconcile: failed to remove container ${r.name}: ${r.detail}`)
         .join('\n');
 }
 export function formatMicroVmReconcileReport(reaped) {
@@ -389,7 +728,7 @@ export function formatMicroVmReconcileReport(reaped) {
     return reaped
         .map((r) => r.removed
         ? `reconcile: removed sbx VM ${r.name} (sbx rm --force)`
-        : `reconcile: failed to remove sbx VM ${r.name} — ${r.detail}`)
+        : `reconcile: failed to remove sbx VM ${r.name}: ${r.detail}`)
         .join('\n');
 }
 export function formatReconcileReport(reaped) {
@@ -416,7 +755,7 @@ export function formatClaimReconcileReport(released) {
     return released
         .map((c) => c.released
         ? `reconcile: released issue #${c.issue} back to factory:queued (lease expired at ${c.expiresAt})`
-        : `reconcile: failed to release issue #${c.issue} (lease expired at ${c.expiresAt}) — ${c.detail ?? 'unknown error'}`)
+        : `reconcile: failed to release issue #${c.issue} (lease expired at ${c.expiresAt}): ${c.detail ?? 'unknown error'}`)
         .join('\n');
 }
 const GREEN_PR_CHECK = 'green PRs awaiting merge';
@@ -430,7 +769,7 @@ export function unmergedGreenPrChecks(result) {
                 name: GREEN_PR_CHECK,
                 ok: false,
                 optional: true,
-                detail: `scan failed — ${result.detail}`,
+                detail: `scan failed: ${result.detail}`,
                 fix: 'check `gh auth status` and network access, then re-run `factory doctor`',
             },
         ];
@@ -442,8 +781,8 @@ export function unmergedGreenPrChecks(result) {
         name: `green PR #${row.number}`,
         ok: false,
         optional: true,
-        detail: `${row.issue === null ? 'owning issue unknown' : `issue #${row.issue}`} — green and ready on ${row.branch}, open ${row.ageHours}h, not merged`,
-        fix: `review and merge #${row.number} (or close it) — the factory never auto-merges an orphaned PR`,
+        detail: `${row.issue === null ? 'owning issue unknown' : `issue #${row.issue}`}: green and ready on ${row.branch}, open ${row.ageHours}h, not merged`,
+        fix: `review and merge #${row.number} (or close it); the factory never auto-merges an orphaned PR`,
     }));
 }
 /** One doctor check per user-declared harness, from its `probe` result. */
@@ -456,7 +795,7 @@ export function declaredHarnessChecks(probes) {
             return {
                 name,
                 ok: false,
-                detail: `unavailable — probe \`${p.probe}\` failed: ${p.detail}`,
+                detail: `unavailable: probe \`${p.probe}\` failed: ${p.detail}`,
                 fix: 'install the agent CLI on PATH or fix the "probe" command in the models config harnesses section',
             };
         }
@@ -464,9 +803,107 @@ export function declaredHarnessChecks(probes) {
             name,
             ok: false,
             optional: true,
-            detail: 'unverified — no probe configured',
+            detail: 'unverified: no probe configured',
             fix: 'add a "probe" command (exit 0 = reachable) to the harness in the models config',
         };
     });
 }
+const REGISTRY_CHECK = 'models.registry';
+/** One failed check per models.registry entry whose harness is missing or unknown;
+ *  a single ok row when every entry is valid; nothing when there is no registry. */
+export function modelsRegistryChecks(configPath, registry, validHarnesses) {
+    const entries = Object.entries(registry ?? {});
+    if (entries.length === 0)
+        return [];
+    const failed = [];
+    for (const [id, def] of entries) {
+        const field = `models.registry.${id}.harness`;
+        const name = `${REGISTRY_CHECK} ${id}`;
+        if (def.harness === undefined || def.harness.trim() === '') {
+            failed.push({
+                name,
+                ok: false,
+                detail: `${configPath}: ${field} is missing`,
+                fix: `set "harness" to one of: ${validHarnesses.join(', ')}`,
+            });
+        }
+        else if (!validHarnesses.includes(def.harness)) {
+            failed.push({
+                name,
+                ok: false,
+                detail: `${configPath}: ${field} '${def.harness}' is not a known harness (valid harnesses: ${validHarnesses.join(', ')})`,
+                fix: 'use a built-in harness id or declare it under "harnesses" in the models config',
+            });
+        }
+    }
+    if (failed.length > 0)
+        return failed;
+    const n = entries.length;
+    return [{ name: REGISTRY_CHECK, ok: true, detail: `${n} entr${n === 1 ? 'y' : 'ies'} valid (${configPath})` }];
+}
+/** `config` rows from the shared pre-PLAN lint (#2612): one failing row per finding, so doctor fails exactly when
+ *  the run preflight would escalate or park. A single ok row when clean. Read-only. */
+export function configLintChecks(input, loadError) {
+    const schemaRows = (input.configFile ? findConfigSchemaErrors(input.configFile) : []).map((f) => ({
+        name: 'config',
+        ok: false,
+        section: REPO_SECTION,
+        detail: `${f.file}${f.line ? `:${f.line}` : ''}: schema error at '${f.path}': ${f.message}`,
+        fix: f.fix,
+    }));
+    if (loadError !== undefined) {
+        return [
+            {
+                name: 'config',
+                ok: false,
+                section: REPO_SECTION,
+                detail: loadError,
+                fix: 'fix the constitution frontmatter YAML',
+            },
+            ...schemaRows,
+        ];
+    }
+    const { findings } = lintFactoryConfig(input);
+    if (findings.length > 0) {
+        const names = [...listBuiltInCheckers().map((c) => c.name), 'custom_*'].join(', ');
+        const lintRows = findings.map((f) => {
+            const where = `${f.file}${f.line ? `:${f.line}` : ''}`;
+            if (f.rule === 'unknown-checker') {
+                const kind = isTemplateToken(f.token) ? 'placeholder' : 'unknown';
+                return {
+                    name: 'config',
+                    ok: false,
+                    section: REPO_SECTION,
+                    detail: `${where}: ${kind} checker '${f.token}'`,
+                    fix: `replace '${f.token}' with a real checker name (${names}) or delete the line`,
+                };
+            }
+            return {
+                name: 'config',
+                ok: false,
+                section: REPO_SECTION,
+                detail: `${where}: unfilled template token '${f.token}'`,
+                fix: `replace '${f.token}' with a real value`,
+            };
+        });
+        return [...lintRows, ...schemaRows];
+    }
+    if (schemaRows.length > 0)
+        return schemaRows;
+    const scanned = [];
+    if (input.constitution?.repoInstance)
+        scanned.push(input.constitution.repoInstance.relPath);
+    if (input.configFile && existsSync(input.configFile.absPath))
+        scanned.push(input.configFile.relPath);
+    return [
+        {
+            name: 'config',
+            ok: true,
+            section: REPO_SECTION,
+            detail: scanned.length > 0
+                ? `no unfilled placeholders, unknown checkers or schema errors in ${scanned.join(', ')}`
+                : 'no constitution or config file to scan',
+        },
+    ];
+}
 //# sourceMappingURL=doctor.js.map