copperhead 0.9.0 → 0.11.0

package/src/config.ts

@@ -2,9 +2,32 @@ import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 
+/**
+ * Optional `legibility` block: checker thresholds and per-family severity
+ * overrides (`off` disables a family). Unknown keys and invalid values are
+ * ignored by the checker's own sanitizer, so a config typo cannot crash a run.
+ */
+export interface LegibilityUserConfig {
+  thresholds?: {
+    gridPitch?: number;
+    minPitch?: number;
+    utilization?: number;
+    maxWireLength?: number;
+    familyCap?: number;
+  };
+  severity?: Record<string, 'error' | 'advisory' | 'off'>;
+  /** Scorer tuning: per-metric weights and the known-good composite floor. */
+  score?: {
+    weights?: Record<string, number>;
+    floor?: number;
+  };
+}
+
 export interface CopperheadConfig {
   schematic: string | null;
   board: string | null;
+  /** Schematic legibility checker thresholds and severity overrides. */
+  legibility?: LegibilityUserConfig;
   docs: string;
   model: string | null;
   maxTurns: number;
@@ -12,9 +35,20 @@ export interface CopperheadConfig {
   stageMaxTurns?: Record<string, number>;
   maxRepairCycles: number;
   budgets: Record<string, number>;
-  /** Per-turn watchdog (ms). A provider turn exceeding this is aborted and
-   * retried, so a hung call can't stall the run forever. <=0 disables it. */
+  /** Per-turn inactivity watchdog (ms). A provider turn that goes this long
+   * without a response or any streamed progress is treated as hung: aborted and
+   * retried, so a hung call can't stall the run forever. A streaming provider
+   * restarts it on every progress event, so a long turn that keeps producing
+   * output is not killed; a provider that reports no progress gets it as a
+   * whole-turn deadline. <=0 disables it. */
   turnTimeoutMs: number;
+  /** Hard cap (ms) on one provider turn that is producing output, however much
+   * progress it reports. A turn that hits it is too large, not hung, so it fails
+   * without a retry: resending the identical request would only run into the cap
+   * again. It is never shorter than turnTimeoutMs, and a turn that has reported
+   * no progress is judged by turnTimeoutMs alone. <=0 disables it; when unset it
+   * defaults to 3600000, or to disabled when turnTimeoutMs is disabled. */
+  turnMaxMs: number;
   /** How often (ms) to emit a liveness heartbeat while a provider turn is in
    * flight, so a slow large-output turn is distinguishable from a hung one
    * (5.1). Fires only after the first interval, so quick turns stay silent.
@@ -56,13 +90,17 @@ export const DEFAULTS: Omit<CopperheadConfig, 'schematic' | 'board'> = {
   maxTurns: 40,
   maxRepairCycles: 5,
   budgets: {},
-  // 10 min. A single large capture turn (a full lib_symbols + instances edit,
-  // ~40k output tokens) on the claude-code provider legitimately runs several
-  // minutes; the old 5-min deadline killed those mid-flight and, because the
-  // watchdog budget is spent per stage, could fail a stage that was only slow,
-  // not hung. 10 min clears the largest observed turns while still catching a
-  // genuinely stuck subprocess.
+  // 10 min without a response or progress. A single large capture turn (a full
+  // lib_symbols + instances edit, ~40k output tokens) on the claude-code
+  // provider legitimately runs several minutes; the old 5-min whole-turn
+  // deadline killed those mid-flight. Some turns run past 10 min too, so the
+  // deadline restarts on every streamed progress event: it bounds a silent
+  // stretch, not the turn's length. A provider that cannot stream still gets it
+  // as a whole-turn deadline, so no turn that finished in time before times out now.
   turnTimeoutMs: 600000,
+  // 60 min: the backstop for a turn that keeps streaming. Far past the largest
+  // observed turns, while a runaway generation still ends in bounded time.
+  turnMaxMs: 3600000,
   // 30s: within one interval an operator knows a turn is alive, and a full
   // 10-min turn emits ~20 lines — enough to distinguish slow from hung without
   // flooding the log. Quick turns (< 30s) emit nothing.
@@ -96,6 +134,15 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
     maxRepairCycles: raw.maxRepairCycles ?? DEFAULTS.maxRepairCycles,
     budgets: raw.budgets ?? {},
     turnTimeoutMs: typeof raw.turnTimeoutMs === 'number' ? raw.turnTimeoutMs : DEFAULTS.turnTimeoutMs,
+    // A repo that switched the turn watchdog off gets no default cap either:
+    // before the cap existed that meant no deadline at all, and a default must
+    // not quietly bring one back. An explicit turnMaxMs still applies.
+    turnMaxMs:
+      typeof raw.turnMaxMs === 'number'
+        ? raw.turnMaxMs
+        : typeof raw.turnTimeoutMs === 'number' && raw.turnTimeoutMs <= 0
+          ? 0
+          : DEFAULTS.turnMaxMs,
     heartbeatMs: typeof raw.heartbeatMs === 'number' ? raw.heartbeatMs : DEFAULTS.heartbeatMs,
     maxStageRetries:
       Number.isInteger(raw.maxStageRetries) && (raw.maxStageRetries as number) >= 0
@@ -106,6 +153,7 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
     ...(typeof raw.apiKeyEnv === 'string' && raw.apiKeyEnv.trim() ? { apiKeyEnv: raw.apiKeyEnv.trim() } : {}),
     ...(raw.generatedHashes ? { generatedHashes: raw.generatedHashes } : {}),
     ...(raw.origin === 'create' || raw.origin === 'init' ? { origin: raw.origin } : {}),
+    ...(raw.legibility && typeof raw.legibility === 'object' ? { legibility: raw.legibility } : {}),
   };
 }
 

package/src/kicad/bootstrap.ts

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs';
-import { writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { configPath, loadConfig, type CopperheadConfig } from '../config.js';
+import { CREATE_ORIGIN } from './fab.js';
 
 /**
  * The create pipeline starts from a brief with no KiCad files, but the agent
@@ -37,8 +38,8 @@ function uuidFrom(seed: string): string {
 function emptySchematic(rootUuid: string): string {
   return `(kicad_sch
 	(version 20231120)
-	(generator "eeschema")
-	(generator_version "8.0")
+	(generator "copperhead-draft")
+	(generator_version "0")
 	(uuid "${rootUuid}")
 	(paper "A4")
 	(lib_symbols)
@@ -147,9 +148,25 @@ function projectFile(slug: string, rootUuid: string): string {
 }
 
 async function persist(repoRoot: string, config: CopperheadConfig): Promise<void> {
+  await mkdir(path.dirname(configPath(repoRoot)), { recursive: true });
   await writeFile(configPath(repoRoot), JSON.stringify(config, null, 2) + '\n', 'utf8');
 }
 
+/**
+ * Stamp the config as create-produced (`origin: "create"`). The marker is what
+ * scopes the legibility finish gate (`isCreateProducedRepo` feeds the
+ * obligations ledger) and the fab release gate — a gate hung on a marker
+ * nothing writes is silently inert, so `runCreate` stamps it up front and
+ * `bootstrapKicadProject` re-stamps on every (re-)scaffold, covering the
+ * rollback path that deletes an uncommitted config.
+ */
+export async function markCreateOrigin(repoRoot: string): Promise<void> {
+  const config = await loadConfig(repoRoot);
+  if (config.origin === CREATE_ORIGIN) return;
+  config.origin = CREATE_ORIGIN;
+  await persist(repoRoot, config);
+}
+
 /**
  * Ensure a KiCad project exists and is wired into config. No-op (returns null)
  * when config already points at a schematic on disk. If project files exist but
@@ -160,6 +177,10 @@ async function persist(repoRoot: string, config: CopperheadConfig): Promise<void
 export async function bootstrapKicadProject(repoRoot: string, brief: string): Promise<string | null> {
   const config = await loadConfig(repoRoot);
   if (config.schematic && existsSync(path.join(repoRoot, config.schematic))) return null;
+  // Only `create` scaffolds through here, so the repo is create-produced by
+  // definition; stamping on every scaffold keeps the marker alive across the
+  // rollback-then-rescaffold path (git clean deletes an uncommitted config).
+  config.origin = CREATE_ORIGIN;
 
   const slug = projectSlug(brief);
   const schRel = `${slug}.kicad_sch`;

package/src/kicad/cli.ts

@@ -1,5 +1,5 @@
 import { execa, ExecaError } from 'execa';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
@@ -7,14 +7,29 @@ import { normalizeReport, type CheckReport } from './report.js';
 import { PreflightError, isNotFoundError } from '../util/preflight.js';
 
 export class KicadCliMissingError extends PreflightError {
-  constructor() {
+  constructor(platform = process.platform) {
+    const isWin = platform === 'win32';
+    const isMac = platform === 'darwin';
+
+    const locationHint = isWin
+      ? 'ensure kicad-cli.exe is on PATH (typically in C:\\Program Files\\KiCad\\<version>\\bin)'
+      : isMac
+        ? 'ensure the kicad-cli binary is on PATH (on macOS it ships inside KiCad.app/Contents/MacOS)'
+        : 'ensure the kicad-cli binary is on PATH (typically /usr/bin/kicad-cli)';
+
+    const envHint = isWin
+      ? 'or set COPPERHEAD_KICAD_CLI="C:\\Program Files\\KiCad\\10.0\\bin\\kicad-cli.exe"'
+      : isMac
+        ? 'or set COPPERHEAD_KICAD_CLI=/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli'
+        : 'or set COPPERHEAD_KICAD_CLI=/usr/bin/kicad-cli';
+
     super(
       'kicad-cli not found on PATH',
       'copperhead verifies every mutation with kicad-cli ERC/DRC; without it no edit can be checked, so no run can start',
       [
         'install KiCad ≥ 8: https://www.kicad.org/download/',
-        'ensure the kicad-cli binary is on PATH (on macOS it ships inside KiCad.app/Contents/MacOS)',
-        'or set COPPERHEAD_KICAD_CLI=/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
+        locationHint,
+        envHint,
         'confirm with "kicad-cli version", then rerun',
       ],
     );
@@ -28,15 +43,32 @@ export class KicadCliMissingError extends PreflightError {
  * seen and rejected, so telling the user to set it would be nonsense.
  */
 export class KicadCliBadOverrideError extends PreflightError {
-  constructor(configured: string) {
+  constructor(configured: string, platform = process.platform) {
+    const isWin = platform === 'win32';
+    const isMac = platform === 'darwin';
+
+    const checkHint = isWin
+      ? `check the path in PowerShell: Test-Path "${configured}"`
+      : `check the path: ls -l "${configured}"`;
+
+    const locationHint = isWin
+      ? 'on Windows the binary typically lives at C:\\Program Files\\KiCad\\<version>\\bin\\kicad-cli.exe'
+      : isMac
+        ? 'on macOS the binary lives at /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli'
+        : 'on Linux the binary typically lives at /usr/bin/kicad-cli';
+
+    const confirmHint = isWin
+      ? 'confirm with "& $env:COPPERHEAD_KICAD_CLI version", then rerun'
+      : 'confirm with "$COPPERHEAD_KICAD_CLI" version, then rerun';
+
     super(
       `COPPERHEAD_KICAD_CLI points to a path that does not exist: ${configured}`,
       'the override wins over PATH, so falling back silently would run a different binary than the one you named and make the failure impossible to diagnose',
       [
-        `check the path: ls -l "${configured}"`,
-        'on macOS the binary lives at /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
+        checkHint,
+        locationHint,
         'or unset COPPERHEAD_KICAD_CLI to fall back to PATH',
-        'confirm with "$COPPERHEAD_KICAD_CLI version", then rerun',
+        confirmHint,
       ],
     );
     this.name = 'KicadCliBadOverrideError';
@@ -44,20 +76,89 @@ export class KicadCliBadOverrideError extends PreflightError {
 }
 
 /** Well-known install locations when `kicad-cli` is not on PATH (macOS app bundle). */
-const FALLBACK_BINARIES = [
+const MACOS_FALLBACK_BINARIES = [
   '/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli',
   '/Applications/KiCad-10.0/KiCad.app/Contents/MacOS/kicad-cli',
   '/Applications/KiCad-9.0/KiCad.app/Contents/MacOS/kicad-cli',
   '/Applications/KiCad-8.0/KiCad.app/Contents/MacOS/kicad-cli',
 ];
 
-let fallbackBinaries: readonly string[] = FALLBACK_BINARIES;
+/**
+ * Minimum KiCad major version accepted for ERC/DRC and candidate discovery.
+ * Re-used by doctor.ts to ensure CLI discovery and environment preflight
+ * enforce the same version floor.
+ */
+export const MIN_KICAD_MAJOR = 8;
+
+const DEFAULT_WIN_ROOTS = [
+  process.env.ProgramFiles ? path.join(process.env.ProgramFiles, 'KiCad') : 'C:/Program Files/KiCad',
+  'C:/Program Files/KiCad',
+  'C:/Program Files (x86)/KiCad',
+];
+
+/**
+ * Return default fallback candidate paths for macOS and Windows standard KiCad installations.
+ * On Windows, version-numbered directories (e.g. 10.0, 9.0, 8.0) under the KiCad root
+ * are probed in descending numerical order, mirroring symlib.ts.
+ */
+export function defaultFallbackBinaries(winRoots: readonly string[] = DEFAULT_WIN_ROOTS): string[] {
+  const candidates: string[] = [...MACOS_FALLBACK_BINARIES];
+  const seenRoots = new Set<string>();
+
+  for (const winRoot of winRoots) {
+    const normalized = path.normalize(winRoot).toLowerCase();
+    if (seenRoots.has(normalized)) continue;
+    seenRoots.add(normalized);
+
+    if (!existsSync(winRoot)) continue;
+    try {
+      const entries = readdirSync(winRoot, { withFileTypes: true });
+      const versions = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        // Only include versions that meet the minimum supported KiCad major.
+        // This prevents a stale KiCad 7.x install from silently becoming the
+        // ERC/DRC binary while doctor correctly reports FAIL for it.
+        .filter((name) => {
+          const major = Number(name.split('.')[0]);
+          return Number.isFinite(major) && major >= MIN_KICAD_MAJOR;
+        })
+        .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+
+      for (const version of versions) {
+        candidates.push(
+          path.join(winRoot, version, 'bin', 'kicad-cli.exe'),
+          path.join(winRoot, version, 'bin', 'kicad-cli.cmd'),
+          path.join(winRoot, version, 'bin', 'kicad-cli.bat'),
+          path.join(winRoot, version, 'bin', 'kicad-cli'),
+        );
+      }
+    } catch {
+      // not readable / not a directory; versioned candidates unavailable, but
+      // the unversioned bin/ fallback below is still worth probing.
+    }
+    // Unversioned fallback: pushed unconditionally so a readdirSync failure
+    // (e.g. ENOTDIR) on the root itself doesn't also suppress this probe.
+    candidates.push(
+      path.join(winRoot, 'bin', 'kicad-cli.exe'),
+      path.join(winRoot, 'bin', 'kicad-cli.cmd'),
+      path.join(winRoot, 'bin', 'kicad-cli.bat'),
+      path.join(winRoot, 'bin', 'kicad-cli'),
+    );
+  }
+
+  return candidates;
+}
+
+let fallbackBinariesOverride: readonly string[] | null = null;
+let fallbackWinRootsOverride: readonly string[] | null = null;
 
 let cachedBinary: string | null | undefined;
 
 /**
  * Resolve the kicad-cli executable: `COPPERHEAD_KICAD_CLI` > PATH name
- * (`kicad-cli`). On PATH miss, `runKicad` falls back to macOS KiCad.app paths.
+ * (`kicad-cli`). On PATH miss, `runKicad` falls back to macOS KiCad.app paths
+ * and Windows standard installation paths.
  */
 export function resolveKicadCli(): string {
   if (cachedBinary !== undefined) {
@@ -88,7 +189,7 @@ function envOverride(): string | null {
 }
 
 /**
- * After ENOENT on PATH, retry with a known macOS install path.
+ * After ENOENT on PATH, retry with known install paths (macOS app bundles, Windows standard paths).
  *
  * Deliberately does not re-read `COPPERHEAD_KICAD_CLI`: this is reached only
  * when resolveKicadCli() cached the bare PATH name, which in turn happens only
@@ -96,7 +197,9 @@ function envOverride(): string | null {
  * override re-check here could never fire.
  */
 function fallbackAfterMissing(): string {
-  for (const candidate of fallbackBinaries) {
+  const candidates =
+    fallbackBinariesOverride ?? defaultFallbackBinaries(fallbackWinRootsOverride ?? undefined);
+  for (const candidate of candidates) {
     if (existsSync(candidate)) {
       cachedBinary = candidate;
       return candidate;
@@ -133,13 +236,21 @@ export function resetKicadCliCache(): void {
 }
 
 /**
- * Test helper: point the app-bundle probe at fixture paths, or call with no
- * argument to restore the real list. Without this the fallback branch is only
- * exercisable on a macOS host that happens to have KiCad installed, which
- * makes the outcome depend on the developer's machine.
+ * Test helper: point the app-bundle / binary probe at fixture paths, or call with no
+ * argument to restore the default dynamic list.
  */
 export function setKicadFallbackBinaries(paths?: readonly string[]): void {
-  fallbackBinaries = paths ?? FALLBACK_BINARIES;
+  fallbackBinariesOverride = paths ?? null;
+  fallbackWinRootsOverride = null;
+}
+
+/**
+ * Test helper: point the Windows installation discovery probe at fixture roots, or call
+ * with no argument to restore the default search roots.
+ */
+export function setKicadFallbackWinRoots(roots?: readonly string[]): void {
+  fallbackWinRootsOverride = roots ?? null;
+  fallbackBinariesOverride = null;
 }
 
 export async function kicadCliVersion(): Promise<string> {

package/src/kicad/dossier.ts

@@ -0,0 +1,217 @@
+/**
+ * The stage-4 entry pin dossier: every BOM part resolved against the installed
+ * KiCad libraries, rendered as a prompt block, so the schematic agent starts
+ * with the pin facts it would otherwise spend turns reconstructing.
+ *
+ * The BOM is frozen when stage 4 starts, which makes this computable before the
+ * first agent turn — the same insight `symbolAvailabilityFacts` applies at
+ * recovery time, moved to entry. Like that block, coverage is stated rather
+ * than implied: parts past the size cap are named as NOT INCLUDED, parts a
+ * probe error skipped are named as UNRESOLVED, and parts whose only name is
+ * too short to search are named as NOT SEARCHED — never silently dropped,
+ * because absence from the dossier must never read as absence from the
+ * libraries.
+ *
+ * Advisory only. It changes prompt content, not gates: a missing BOM, an
+ * unreadable library, or any error degrades to an empty string and the stage
+ * runs exactly as it did before this block existed.
+ */
+
+import { parseBomTable } from '../memory/bom-table.js';
+import {
+  resolveLibrarySymbol,
+  searchInstalledSymbols,
+  listInstalledLibraries,
+  comparePinNumbers,
+  type LibPin,
+} from './symlib.js';
+
+/** R/C/L refdes (with optional multi-part suffix like R12A) draw from their
+ * canonical `Device:*` symbols; a two-pin table per resistor is noise. */
+const PASSIVE_REFDES = /^[RCL]\d+[A-Za-z]?$/i;
+
+/** `1=PE2/bidirectional 2(passive) …` — name omitted when the library leaves
+ * the pin unnamed (`~` or empty), since `1=~/passive` reads as line noise. */
+function pinTable(pins: LibPin[]): string {
+  return [...pins]
+    .sort((a, b) => comparePinNumbers(a.number, b.number))
+    .map((p) => {
+      const name = p.name === '~' ? '' : p.name;
+      return name ? `${p.number}=${name}/${p.type}` : `${p.number}(${p.type})`;
+    })
+    .join(' ');
+}
+
+/** Render `prefix + as many names as fit + suffix` within `budget` chars; the
+ * tail that does not fit becomes "…and N more". The budget is a hard bound:
+ * when even the minimal form exceeds it, the string is truncated outright, so
+ * the trailer can never blow the size cap it exists to disclose. */
+function boundedList(prefix: string, names: string[], suffix: string, budget: number): string {
+  let line = '';
+  let shown = 0;
+  for (let i = 0; i < names.length; i++) {
+    const sep = shown === 0 ? '' : '; ';
+    const tail = `…and ${names.length - i} more`;
+    const candidate = `${line}${sep}${names[i]}`;
+    // Reserve room for the worst-case continuation marker after this name.
+    if (prefix.length + candidate.length + tail.length + 2 + suffix.length > budget) break;
+    line = candidate;
+    shown++;
+  }
+  const rest = names.length - shown;
+  const full =
+    rest === 0
+      ? `${prefix}${line}${suffix}`
+      : `${prefix}${line ? `${line}; ` : ''}…and ${rest} more${suffix}`;
+  if (full.length <= budget) return full;
+  return full.slice(0, Math.max(1, budget - 1)) + '…';
+}
+
+export interface DossierOptions {
+  /** candidate lib_ids fetched per part */
+  searchCap?: number;
+  /** bound on the complete rendered block, disclosure lines included */
+  maxChars?: number;
+}
+
+/**
+ * Render the dossier block from BOM markdown. Returns `''` when there is
+ * nothing to say (no rows survive the passive filter, no search dirs, or any
+ * error) — the caller injects nothing rather than an empty heading.
+ */
+export async function bomSymbolDossier(
+  bomMd: string,
+  dirs: string[],
+  opts: DossierOptions = {},
+): Promise<string> {
+  const searchCap = opts.searchCap ?? 3;
+  const maxChars = opts.maxChars ?? 24_000;
+  try {
+    if (!dirs.length) return '';
+    // No readable library at all must yield no dossier, not a page of
+    // NO-INSTALLED-SYMBOL lines: a false absence claim in a machine-verified
+    // block is the exact failure mode this file exists to prevent (I15).
+    if (!(await listInstalledLibraries(dirs)).size) return '';
+    // Group refdes by primary query so a part used five times renders once.
+    // The MPN is the stronger name when present; the stage-3 scaffold's
+    // UNVERIFIED flag word is not part of it. The Value is kept as a fallback
+    // query, searched only when the MPN finds nothing — a bogus MPN over a
+    // resolvable Value must not read as NO INSTALLED SYMBOL.
+    const byQuery = new Map<string, { refs: string[]; fallback?: string }>();
+    const unsearchable: string[] = [];
+    for (const row of parseBomTable(bomMd)) {
+      if (PASSIVE_REFDES.test(row.refdes)) continue;
+      const mpn = (row.mpn ?? '').replace(/^UNVERIFIED[:\s]*/i, '').trim();
+      const value = (row.value ?? '').trim();
+      const query = mpn || value;
+      if (query.length < 3) {
+        // Disclosed, not dropped: a crystal named "8M" was never searched, and
+        // silence here would read as "checked" under a machine-verified label.
+        unsearchable.push(`${row.refdes} (${query || 'no name'})`);
+        continue;
+      }
+      const entry = byQuery.get(query) ?? { refs: [] };
+      entry.refs.push(row.refdes);
+      if (mpn && value.length >= 3 && value !== mpn) entry.fallback = value;
+      byQuery.set(query, entry);
+    }
+    if (!byQuery.size && !unsearchable.length) return '';
+
+    const lines: string[] = [];
+    const overflow: string[] = [];
+    const errored: string[] = [];
+    // Reserve room for the disclosure trailers up front, so the complete
+    // rendered block — disclosures included — stays within maxChars.
+    const TRAILER_BUDGET = Math.min(1200, Math.floor(maxChars / 4));
+    const bodyBudget = maxChars - TRAILER_BUDGET;
+    let spent = 0;
+    // Once a line fails to fit, later parts skip their library scans entirely:
+    // the cap bounds the work, not just the rendered output. (Lines have a
+    // floor of ~60 chars, so a later part fitting where this one did not is
+    // rare enough not to pay a full scan hoping for it.)
+    let bodyFull = false;
+    for (const [query, { refs, fallback }] of byQuery) {
+      const who = `${refs.join(', ')} (${query})`;
+      if (bodyFull) {
+        overflow.push(who);
+        continue;
+      }
+      let line: string;
+      try {
+        let hits = await searchInstalledSymbols(query, dirs, searchCap);
+        let matchedBy = '';
+        if (!hits.length && fallback) {
+          hits = await searchInstalledSymbols(fallback, dirs, searchCap);
+          if (hits.length) matchedBy = ` (matched by Value "${fallback}")`;
+        }
+        const top = hits[0];
+        if (!top) {
+          line = `- ${who}: NO INSTALLED SYMBOL matches — not capturable as named; substitute a part whose symbol exists (search_symbols to find one)`;
+        } else {
+          const r = await resolveLibrarySymbol(top, dirs);
+          if (r.status !== 'ok') {
+            // A hit that fails to re-resolve is a library race or parse quirk;
+            // report the candidates without claiming pins we could not read.
+            line = `- ${who}: candidates ${hits.join(', ')} — pins unreadable here; confirm with symbol_pins`;
+          } else {
+            const multi = r.units >= 2 ? ` — MULTI-UNIT (${r.units} units): the drafting engine places each unit separately under this refdes` : '';
+            const also = hits.length > 1 ? `\n  also installed: ${hits.slice(1).join(', ')}` : '';
+            line = `- ${who}: ${top}${matchedBy} — ${r.pins.length} pin(s): ${pinTable(r.pins)}${multi}${also}`;
+          }
+        }
+      } catch {
+        errored.push(who); // one failed probe must not sink the block
+        continue;
+      }
+      if (spent + line.length > bodyBudget) {
+        overflow.push(who);
+        bodyFull = true;
+        continue;
+      }
+      spent += line.length;
+      lines.push(line);
+    }
+    if (!lines.length && !overflow.length && !errored.length && !unsearchable.length) return '';
+    // Distinct disclosures: a probe error is not a size decision, an
+    // unsearchable name is neither, and labeling any of them "size cap" would
+    // misreport why coverage is missing. Each trailer shares the reserved
+    // budget so the complete block stays within maxChars.
+    const trailers: [string, string[], string][] = [];
+    if (errored.length) {
+      trailers.push([
+        '- UNRESOLVED (probe error): ',
+        errored,
+        ' — the probe failed for these; an error says nothing about availability, call symbol_pins for each.',
+      ]);
+    }
+    if (unsearchable.length) {
+      trailers.push([
+        '- NOT SEARCHED (name shorter than 3 chars): ',
+        unsearchable,
+        ' — too short to search reliably; nothing here says whether these resolve. Give them an MPN, or verify by hand.',
+      ]);
+    }
+    if (overflow.length) {
+      trailers.push([
+        `- NOT INCLUDED (size cap ${maxChars} chars): `,
+        overflow,
+        ' — call symbol_pins for each; nothing above says whether these resolve.',
+      ]);
+    }
+    // Allocate from what is actually left of maxChars (body lines plus the
+    // newlines join() will add), splitting the remainder across the trailers
+    // still to render — a fixed per-trailer share of the reserve could exceed
+    // the whole-block bound when the shares themselves cannot fit.
+    let used = lines.reduce((a, l) => a + l.length + 1, 0);
+    for (let i = 0; i < trailers.length; i++) {
+      const [prefix, names, suffix] = trailers[i]!;
+      const budget = Math.floor((maxChars - used) / (trailers.length - i));
+      const rendered = boundedList(prefix, names, suffix, budget);
+      lines.push(rendered);
+      used += rendered.length + 1;
+    }
+    return lines.join('\n');
+  } catch {
+    return '';
+  }
+}