@mcptoolshop/style-dataset-lab 3.2.0 → 3.4.0

package/lib/canon-build/build.js

@@ -91,12 +91,34 @@ export async function runBuild(opts) {
   const entries = [];
   const schemaChangeTriggersFullRebuild = await detectSchemaChange(projectRoot, schemas, full);
 
+  // Entity ids must be unique across the ENTIRE canon tree, not just within
+  // one schema's subdirectory: they key prompts/<id>.j2, context/<id>.md, and
+  // manifest.per_entity_hashes, all of which are flat maps keyed by id alone.
+  // Two entries sharing an id (e.g. a forgotten `id:` edit after cloning an
+  // existing file) would silently overwrite each other's prompt/context
+  // output and collide in the manifest (last write wins), while
+  // dataset/all.jsonl would keep rows for both under the one id — so a row
+  // permanently points at the wrong entry's content. Catch this at discovery
+  // time, before any output is written.
+  const seenIds = new Map(); // id -> first-seen filePath
+
   for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
     const dir = join(config.canon_root, subdir);
     const loaded = await loadCanonEntriesInDir(dir);
     for (const entry of loaded) {
       const id = entryId(entry);
       if (only && !only.includes(id)) continue;
+      if (seenIds.has(id)) {
+        throw inputError(
+          'CANON_DUPLICATE_ENTITY_ID',
+          `Duplicate canon entity id "${id}": both ${seenIds.get(id)} and ${entry.filePath} ` +
+            `resolve to this id.`,
+          `Give one of these entries a unique "id:" field in its frontmatter. IDs must be ` +
+            `unique across the whole canon tree — they key prompts/, context/, and ` +
+            `manifest.per_entity_hashes, all flat maps with no per-schema namespacing.`,
+        );
+      }
+      seenIds.set(id, entry.filePath);
       entries.push({ entry, schemaName, id });
     }
   }
@@ -166,9 +188,17 @@ export async function runBuild(opts) {
       || entry.frontmatter.reference_plate_uri
       || null;
 
-    // Build the row
+    // Build the row. `id` is the RESOLVED id (frontmatter.id, falling back to
+    // the filename stem — see entryId() in load-entry.js), which is what the
+    // prompts/<id>.j2 and context/<id>.md files below are actually named
+    // with. canonEntryToRow() (lib/rows.js) reads `entry.id` for entity_id —
+    // passing the raw entry.frontmatter would leave entity_id undefined for
+    // any entry that relies on the filename-stem fallback (no explicit
+    // `id:` field), and serializeRow() drops undefined fields entirely, so
+    // the row would orphan itself from its own correctly-named prompt/context
+    // files. Overlay the resolved id so the row always carries it.
     const row = canonEntryToRow({
-      entry: entry.frontmatter,
+      entry: { ...entry.frontmatter, id },
       schemaKind: rendered.schemaKind,
       assetPath: refPath,
       lane,
@@ -212,104 +242,127 @@ export async function runBuild(opts) {
   }
 
   // Write to staging, then atomic rename.
+  //
+  // M2: everything from here through the rename is wrapped in try/catch.
+  // Before this fix, a throw ANYWHERE in this block (most notably
+  // readFreezeStatus() below, which throws CANON_FREEZE_STATUS_INVALID on a
+  // malformed freeze.status) left `stagingDir` — by then already populated
+  // with dataset/prompts/context — orphaned on disk forever: the only
+  // cleanup is the `rm(stagingDir, ...)` at the top of THIS function, and
+  // that runs against a NEW `${generatedFromDir}.tmp-${process.pid}` path on
+  // the next invocation (a different pid), so it can never match the
+  // orphan. The catch below removes the in-progress staging directory
+  // before rethrowing, and does not touch anything once rename() has
+  // succeeded (stagingDir no longer exists at that point, so the block
+  // exits normally and the catch never runs).
   await rm(stagingDir, { recursive: true, force: true });
-  await mkdir(join(stagingDir, 'dataset'), { recursive: true });
-  await mkdir(join(stagingDir, 'prompts'), { recursive: true });
-  await mkdir(join(stagingDir, 'context'), { recursive: true });
-
-  // Write prompts + context
-  for (const { entry } of entries) {
-    const r = entry._rendered;
-    const id = entry._id;
-    await writeFile(join(stagingDir, 'prompts', `${id}.j2`), r.prompt, 'utf-8');
-    await writeFile(join(stagingDir, 'context', `${id}.md`), r.context, 'utf-8');
-  }
+  // Declared here (not inside the try block) because they're read again
+  // after it, in writeLatestSchemaVersions() and the return value below.
+  let frozenEntriesHashes = {};
+  let drift = [];
+  let manifest;
+  try {
+    await mkdir(join(stagingDir, 'dataset'), { recursive: true });
+    await mkdir(join(stagingDir, 'prompts'), { recursive: true });
+    await mkdir(join(stagingDir, 'context'), { recursive: true });
+
+    // Write prompts + context
+    for (const { entry } of entries) {
+      const r = entry._rendered;
+      const id = entry._id;
+      await writeFile(join(stagingDir, 'prompts', `${id}.j2`), r.prompt, 'utf-8');
+      await writeFile(join(stagingDir, 'context', `${id}.md`), r.context, 'utf-8');
+    }
 
-  // Write dataset.jsonl (all + per-lane-per-partition)
-  const allLines = rows.map((r) => serializeRow(r)).join('\n') + (rows.length ? '\n' : '');
-  await writeFile(join(stagingDir, 'dataset', 'all.jsonl'), allLines, 'utf-8');
+    // Write dataset.jsonl (all + per-lane-per-partition)
+    const allLines = rows.map((r) => serializeRow(r)).join('\n') + (rows.length ? '\n' : '');
+    await writeFile(join(stagingDir, 'dataset', 'all.jsonl'), allLines, 'utf-8');
 
-  // Group by (lane × partition)
-  const byLaneAndPartition = {};
-  for (const row of rows) {
-    const key = `${row.lane}-${row.partition}`;
-    if (!byLaneAndPartition[key]) byLaneAndPartition[key] = [];
-    byLaneAndPartition[key].push(row);
-  }
-  for (const [key, laneRows] of Object.entries(byLaneAndPartition)) {
-    const content = laneRows.map((r) => serializeRow(r)).join('\n') + '\n';
-    await writeFile(join(stagingDir, 'dataset', `${key}.jsonl`), content, 'utf-8');
-  }
+    // Group by (lane × partition)
+    const byLaneAndPartition = {};
+    for (const row of rows) {
+      const key = `${row.lane}-${row.partition}`;
+      if (!byLaneAndPartition[key]) byLaneAndPartition[key] = [];
+      byLaneAndPartition[key].push(row);
+    }
+    for (const [key, laneRows] of Object.entries(byLaneAndPartition)) {
+      const content = laneRows.map((r) => serializeRow(r)).join('\n') + '\n';
+      await writeFile(join(stagingDir, 'dataset', `${key}.jsonl`), content, 'utf-8');
+    }
 
-  // Freeze drift pass — stamp frozen_entries_hashes (D1 witness chain).
-  // For every entry with a non-auto freeze status, compute the watch-hash
-  // of its currently-watched fields. Drift is computed by later builds or
-  // the `sdlab canon drift` command by diffing their hash against this.
-  const frozenEntriesHashes = {};
-  const drift = [];
-  const priorManifest = await loadPreviousManifest(projectRoot, outputDir);
-  for (const { entry, schemaName, id } of entries) {
-    const status = readFreezeStatus(entry.frontmatter);
-    if (status === 'auto') continue;
-    const watchFields = resolveWatchFields(entry.frontmatter, schemaName, config);
-    const watchHash = computeWatchHash(
-      entry.frontmatter,
-      watchFields,
-      schemas[schemaName].version,
-    );
-    frozenEntriesHashes[id] = {
-      status,
-      watch_hash: watchHash,
-      watch_fields: watchFields,
-      locked_at_build: entry.frontmatter.freeze?.locked_at_build || null,
-    };
-    // Compute drift against prior build's stamp, if any.
-    const priorHash = priorManifest?.frozen_entries_hashes?.[id]?.watch_hash;
-    if (priorHash && priorHash !== watchHash) {
-      drift.push({
-        entity_id: id,
-        schema_kind: schemaName.replace('.schema.json', ''),
+    // Freeze drift pass — stamp frozen_entries_hashes (D1 witness chain).
+    // For every entry with a non-auto freeze status, compute the watch-hash
+    // of its currently-watched fields. Drift is computed by later builds or
+    // the `sdlab canon drift` command by diffing their hash against this.
+    const priorManifest = await loadPreviousManifest(projectRoot, outputDir);
+    for (const { entry, schemaName, id } of entries) {
+      const status = readFreezeStatus(entry.frontmatter);
+      if (status === 'auto') continue;
+      const watchFields = resolveWatchFields(entry.frontmatter, schemaName, config);
+      const watchHash = computeWatchHash(
+        entry.frontmatter,
+        watchFields,
+        schemas[schemaName].version,
+      );
+      frozenEntriesHashes[id] = {
         status,
-        prior_hash: priorHash,
-        current_hash: watchHash,
-      });
+        watch_hash: watchHash,
+        watch_fields: watchFields,
+        locked_at_build: entry.frontmatter.freeze?.locked_at_build || null,
+      };
+      // Compute drift against prior build's stamp, if any.
+      const priorHash = priorManifest?.frozen_entries_hashes?.[id]?.watch_hash;
+      if (priorHash && priorHash !== watchHash) {
+        drift.push({
+          entity_id: id,
+          schema_kind: schemaName.replace('.schema.json', ''),
+          status,
+          prior_hash: priorHash,
+          current_hash: watchHash,
+        });
+      }
     }
-  }
 
-  // Write manifest
-  const manifest = {
-    schema_version: BUILD_SCHEMA_VERSION,
-    row_schema_version: ROW_SCHEMA_VERSION,
-    generated_from: generatedFrom,
-    built_at: new Date().toISOString(),
-    project_id: config.project_id,
-    schema_versions: Object.fromEntries(
-      Object.entries(schemas).map(([k, v]) => [k, v.version])
-    ),
-    build_config_hash: buildConfigHash,
-    project_config_fingerprint: projectFingerprint,
-    per_entity_hashes: Object.fromEntries(entries.map(({ entry, id }) => [id, entry._entryHash])),
-    frozen_entries_hashes: frozenEntriesHashes,
-    drift_against_prior: drift,
-    stats: {
-      entities_total: entries.length,
-      entities_cached: cached,
-      entities_rebuilt: rebuilt,
-      dataset_rows: rows.length,
-      frozen_entries: Object.keys(frozenEntriesHashes).length,
-      drifted_entries: drift.length,
-      schema_change_full_rebuild: schemaChangeTriggersFullRebuild,
-    },
-  };
-  await writeFile(
-    join(stagingDir, 'manifest.json'),
-    JSON.stringify(manifest, null, 2) + '\n',
-    'utf-8'
-  );
-
-  // Atomic swap: remove old output, rename staging → output.
-  await rm(outputDir, { recursive: true, force: true });
-  await rename(stagingDir, outputDir);
+    // Write manifest
+    manifest = {
+      schema_version: BUILD_SCHEMA_VERSION,
+      row_schema_version: ROW_SCHEMA_VERSION,
+      generated_from: generatedFrom,
+      built_at: new Date().toISOString(),
+      project_id: config.project_id,
+      schema_versions: Object.fromEntries(
+        Object.entries(schemas).map(([k, v]) => [k, v.version])
+      ),
+      build_config_hash: buildConfigHash,
+      project_config_fingerprint: projectFingerprint,
+      per_entity_hashes: Object.fromEntries(entries.map(({ entry, id }) => [id, entry._entryHash])),
+      frozen_entries_hashes: frozenEntriesHashes,
+      drift_against_prior: drift,
+      stats: {
+        entities_total: entries.length,
+        entities_cached: cached,
+        entities_rebuilt: rebuilt,
+        dataset_rows: rows.length,
+        frozen_entries: Object.keys(frozenEntriesHashes).length,
+        drifted_entries: drift.length,
+        schema_change_full_rebuild: schemaChangeTriggersFullRebuild,
+      },
+    };
+    await writeFile(
+      join(stagingDir, 'manifest.json'),
+      JSON.stringify(manifest, null, 2) + '\n',
+      'utf-8'
+    );
+
+    // Atomic swap: remove old output, rename staging → output.
+    await rm(outputDir, { recursive: true, force: true });
+    await rename(stagingDir, outputDir);
+  } catch (err) {
+    try {
+      await rm(stagingDir, { recursive: true, force: true });
+    } catch { /* best-effort cleanup — surface the original error below regardless */ }
+    throw err;
+  }
 
   // Update the "latest" schema-version snapshot for change detection next run.
   await writeLatestSchemaVersions(projectRoot, manifest.schema_versions);

package/lib/captions.js

@@ -31,6 +31,8 @@
  *     language outperforms booru-style tags on Flux
  */
 
+import { inputError } from './errors.js';
+
 /**
  * Derive the style trigger token from a profile.
  *
@@ -75,6 +77,9 @@ export function buildCaption(record, lane, group, profile) {
     case 'flux-natural-language':
       return buildFluxNaturalLanguageCaption(record, lane, group, profile);
 
+    case 'subject-natural-language':
+      return buildSubjectNaturalLanguageCaption(record, lane, group, profile);
+
     case 'legacy':
     default:
       return buildLegacyCaption(record, lane, group, profile);
@@ -171,6 +176,58 @@ function buildStructuredMetadataCaption(record, lane, group, profile) {
  * This strategy is the floor — on-contract Flux captions from the fields
  * we have. Expand the canon schema first, then enrich this strategy.
  */
+/**
+ * Subject natural-language caption.
+ *
+ * Same trigger-first prose shape as `flux-natural-language`, but the scene
+ * text comes from `record.canon.subject` — an authored, style-free content
+ * line — instead of `judgment.explanation`.
+ *
+ * Why this exists: `judgment.explanation` is a CURATION field. On projects
+ * where curation notes record rulings ("Director ruling 2026-07-30: pool
+ * look approved...") rather than scene descriptions, the two existing clean
+ * strategies would bake review metadata into every caption. That is the same
+ * class of defect as legacy prompt-bleed, just from a different field.
+ *
+ * `canon.subject` must carry CONTENT ONLY — no style vocabulary ("painterly
+ * gouache", "sixteen-bit palette"), because style must attach to the trigger.
+ * Style words in the subject teach the model to depend on the phrase instead
+ * of the token.
+ *
+ * Shape: `<trigger> style, <subject>.`
+ *
+ * FAILS LOUD when no subject is present — it does NOT fall back to
+ * `flux-natural-language`. That fallback used to read `judgment.explanation`
+ * for the scene segment, which silently re-introduces exactly the prompt-bleed
+ * antipattern this strategy exists to prevent, just sourced from a curation
+ * field instead of `provenance.prompt`. A record selected for this strategy
+ * with no `canon.subject` is a data-authoring gap, not a degrade-gracefully
+ * case: it must be fixed upstream (populate `canon.subject`) or the record
+ * excluded, never silently captioned from review metadata.
+ */
+function buildSubjectNaturalLanguageCaption(record, lane, group, profile) {
+  const subject = record?.canon?.subject;
+  if (typeof subject !== 'string' || subject.trim().length === 0) {
+    const id = record?.id || '(unknown id)';
+    throw inputError(
+      'CAPTION_SUBJECT_MISSING',
+      `Record "${id}" uses caption_strategy "subject-natural-language" but has no ` +
+        `canon.subject (content-only description). Refusing to caption from another field.`,
+      `Populate canon.subject on record "${id}" with a style-free content line (no ` +
+        `"painterly"/"gouache"/palette vocabulary — that belongs to the trigger, not the ` +
+        `subject). Do not let this silently fall back to judgment.explanation, which is a ` +
+        `curation field and may contain review rulings, not scene content.`,
+    );
+  }
+
+  const segments = [];
+  const trigger = deriveStyleTrigger(profile);
+  if (trigger) segments.push(`${trigger} style`);
+  segments.push(subject.trim().replace(/\.$/, ''));
+
+  return segments.join(', ');
+}
+
 function buildFluxNaturalLanguageCaption(record, lane, group, profile) {
   const segments = [];
 

package/lib/card.js

@@ -24,6 +24,36 @@ export async function generateCard(projectRoot, snapshotId, splitId) {
   const audit = await loadSplitAudit(projectRoot, splitId);
   const included = await loadSnapshotIncluded(projectRoot, snapshotId);
 
+  // SDL-C2b: the split audit may carry a second, independent leakage
+  // signal (stem_collision_check) and a family_resolution guess-share
+  // counter. Older on-disk audits (pre-SDL-C2b) won't have either field —
+  // default them so old splits/exports keep loading, but never let a
+  // missing field silently masquerade as "clean".
+  //
+  // F1: defaulting a MISSING stem_collision_check to {passed:true} is safe
+  // for the structural leakageStructurallyClean computation below (it makes
+  // the old audit behave as if the check were absent from the AND, not as
+  // if it had run and passed) — but that default must never be allowed to
+  // read as "the cross-check ran and found nothing". stemCheckRan tracks
+  // whether the field was actually present on disk, independent of the
+  // defaulted value, so leakageVerified (and the label it drives) can tell
+  // "verified clean" apart from "never checked".
+  const stemCheckRan = audit.stem_collision_check != null;
+  const stemCheck = audit.stem_collision_check || { passed: true, issues: [] };
+  const familyResolution = audit.family_resolution || null;
+  const meaningfulGuessShare = familyResolution?.meaningful_guess_share === true;
+  // Only both structural checks passing AND the guess-share being immaterial
+  // earns the "None (verified)" claim — see renderMarkdown's leakageLabel.
+  const leakageStructurallyClean = audit.leakage_check.passed && stemCheck.passed;
+  // F1: "verified" additionally requires the cross-check to have actually
+  // RUN. An audit that predates SDL-C2b (no stem_collision_check key at
+  // all — e.g. projects/tallow-fen/splits/split-20260609-201631-4586)
+  // never had the cross-check executed; the comment two lines above this
+  // one says "never let a missing field silently masquerade as 'clean'" —
+  // requiring stemCheckRan here is what actually enforces that, instead of
+  // just asserting it.
+  const leakageVerified = leakageStructurallyClean && !meaningfulGuessShare && stemCheckRan;
+
   const json = {
     dataset_name: `${config.meta.name}-visual`,
     version: config.meta.version || '1.0.0',
@@ -53,7 +83,20 @@ export async function generateCard(projectRoot, snapshotId, splitId) {
         test: split.profile.test_ratio,
       },
       counts: split.counts,
-      leakage_free: audit.leakage_check.passed,
+      // SDL-C2b: leakage_free now reflects BOTH the original leakage_check
+      // AND the independent stem_collision_check — a finding on either one
+      // means leakage_free is false. leakage_verified additionally requires
+      // the guessed-family share to be immaterial; see leakageLabel below
+      // for why these are kept distinct rather than collapsed into one flag.
+      leakage_free: leakageStructurallyClean,
+      leakage_verified: leakageVerified,
+      stem_collision_check_passed: stemCheck.passed,
+      // F1: distinct from stem_collision_check_passed above — a legacy
+      // audit that never ran the cross-check also reads as "passed" (the
+      // default), so leakageLabel needs this separate flag to tell "ran and
+      // passed" apart from "never ran".
+      stem_collision_check_ran: stemCheckRan,
+      family_resolution: familyResolution,
     },
     lane_balance: audit.lane_balance,
     constitution: {
@@ -77,6 +120,35 @@ function pct(numerator, denominator) {
   return `${(numerator / denominator * 100).toFixed(1)}%`;
 }
 
+/**
+ * SDL-C2b / F1: four-state subject-leakage label. The card must never print
+ * "None (verified)" when either leakage check found something, when a
+ * meaningful share of families were guessed (id-stripping fallback) rather
+ * than authored, OR when the subject-stem cross-check never ran at all
+ * (a legacy pre-SDL-C2b audit) — printing "verified" in any of those cases
+ * would be exactly the silent-guessing / unrun-check-reads-as-passed
+ * failure mode SDL-C2 / F1 were found under. Each state renders distinct
+ * text so a downstream script grepping for the literal string "verified"
+ * cannot match anything but the fully-verified case.
+ */
+function leakageLabel(card) {
+  if (!card.split.leakage_free) return 'DETECTED';
+  if (!card.split.stem_collision_check_ran) {
+    // F1: the split predates the subject-stem cross-check entirely — only
+    // the original leakage_check ever ran. This must render distinctly
+    // from "None (verified)" even though leakage_check itself passed.
+    return 'None (leakage_check only — predates the subject-stem cross-check)';
+  }
+  if (!card.split.leakage_verified) {
+    const fr = card.split.family_resolution;
+    const pctGuessed = fr ? Math.round(fr.guessed_family_ratio * 100) : null;
+    return `UNVERIFIED — ${pctGuessed != null ? pctGuessed + '% of' : 'some'} subject families were ` +
+      `inferred from record ID (no authored identity.subject_name/lineage); confirm manually before ` +
+      `treating this split as leakage-free`;
+  }
+  return 'None (verified)';
+}
+
 function renderMarkdown(card, config) {
   const lines = [];
   const add = (s = '') => lines.push(s);
@@ -112,7 +184,7 @@ function renderMarkdown(card, config) {
   add(`- **Split ID:** \`${card.split.id}\``);
   add(`- **Strategy:** ${card.split.strategy}`);
   add(`- **Seed:** ${card.split.seed}`);
-  add(`- **Subject leakage:** ${card.split.leakage_free ? 'None (verified)' : 'DETECTED'}`);
+  add(`- **Subject leakage:** ${leakageLabel(card)}`);
   add();
 
   add('| Partition | Records | % |');

package/lib/comfyui.js

@@ -16,36 +16,114 @@ const HEARTBEAT_MS = 15_000; // emit a heartbeat at most every 15s
 // than hang until MAX_POLL_MS.
 const UNKNOWN_STATUS_BAIL_POLLS = 30; // ~30s of unrecognized shape
 
+// SDL-H8: per-REQUEST timeout, distinct from the per-CALL poll budget
+// (timeoutMs/MAX_POLL_MS above, which only bounds the interval *between*
+// requests). Without this, a ComfyUI that accepts the TCP connection and
+// never responds hangs `await fetch()` forever — a hang never rejects, so
+// no retry/catch logic anywhere downstream ever fires. Configurable via env
+// so operators can widen it for a slow/remote ComfyUI without a code change.
+const DEFAULT_REQUEST_TIMEOUT_MS = Number(process.env.SDLAB_COMFY_REQUEST_TIMEOUT_MS) || 30_000;
+
+/**
+ * fetch() with a hard per-request timeout via AbortController. Guarantees
+ * the returned promise always settles (resolve or reject) within
+ * `timeoutMs`, even against a server that accepts the connection and then
+ * never responds. On timeout, rejects with a plain Error (not a raw
+ * AbortError/DOMException) naming the URL and elapsed time, so it reads
+ * like any other network failure to callers' existing catch/retry logic.
+ *
+ * @param {string} url
+ * @param {RequestInit} [init]
+ * @param {number} [timeoutMs]
+ * @returns {Promise<Response>}
+ */
+async function fetchWithTimeout(url, init = {}, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const start = Date.now();
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (err?.name === 'AbortError') {
+      const elapsedSec = ((Date.now() - start) / 1000).toFixed(1);
+      throw new Error(
+        `ComfyUI request timed out after ${elapsedSec}s (limit ${(timeoutMs / 1000).toFixed(1)}s): ${url}`
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
- * Check if ComfyUI is reachable.
+ * B04: comfyHealth() used to collapse EVERY failure mode into a bare
+ * `false` via `catch { return false }` with no bound error. A 503 while a
+ * custom node loads, a refused connection, a DNS typo, and a genuine
+ * timeout all produced the identical "ComfyUI not reachable — start
+ * ComfyUI" message downstream — factually wrong for the 503 (ComfyUI IS
+ * reachable and running) and useless for the others (starting ComfyUI does
+ * not fix a DNS typo).
+ *
+ * Check if ComfyUI is reachable, WITH a reason when it isn't.
+ *
  * @param {string} [comfyUrl]
- * @returns {Promise<boolean>}
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<{ok: boolean, reason: string|null}>} reason is one of
+ *   'timeout' | 'refused' | 'dns' | 'http-<status>' | 'unknown' | null (when ok)
  */
-export async function comfyHealth(comfyUrl = DEFAULT_URL) {
+export async function comfyHealthDetailed(comfyUrl = DEFAULT_URL, opts = {}) {
   try {
-    const res = await fetch(`${comfyUrl}/system_stats`);
-    return res.ok;
-  } catch {
-    return false;
+    const res = await fetchWithTimeout(`${comfyUrl}/system_stats`, {}, opts.timeoutMs);
+    if (res.ok) return { ok: true, reason: null };
+    return { ok: false, reason: `http-${res.status}` };
+  } catch (err) {
+    if (/timed out/i.test(err?.message || '')) return { ok: false, reason: 'timeout' };
+    const code = err?.cause?.code || err?.code;
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return { ok: false, reason: 'dns' };
+    if (code === 'ECONNREFUSED' || code === 'ECONNRESET') return { ok: false, reason: 'refused' };
+    return { ok: false, reason: 'unknown' };
   }
 }
 
+/**
+ * Check if ComfyUI is reachable. Thin plain-boolean wrapper over
+ * comfyHealthDetailed() — kept as a SEPARATE, unchanged-signature export
+ * because 5 scripts (generate.js, generate-identity.js,
+ * generate-controlnet.js, generate-ipadapter.js, painterly.js) already call
+ * `if (!(await comfyHealth(...)))`; returning a richer object here would
+ * make every one of those checks permanently truthy (an object is always
+ * truthy) and silently disable their offline handling.
+ *
+ * @param {string} [comfyUrl]
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function comfyHealth(comfyUrl = DEFAULT_URL, opts = {}) {
+  const { ok } = await comfyHealthDetailed(comfyUrl, opts);
+  return ok;
+}
+
 /**
  * Submit a workflow and poll until complete.
  * @param {Object} workflow — ComfyUI prompt graph
  * @param {string} [comfyUrl]
- * @param {{ clientPrefix?: string, timeoutMs?: number }} [opts]
+ * @param {{ clientPrefix?: string, timeoutMs?: number, requestTimeoutMs?: number }} [opts]
+ *   `timeoutMs` bounds the OVERALL poll loop (unchanged, default 10 min).
+ *   `requestTimeoutMs` (SDL-H8) bounds each INDIVIDUAL fetch — the submit
+ *   POST and every /history poll — so a server that never responds can't
+ *   hang the whole call forever.
  * @returns {Promise<Object>} — history entry
  */
 export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {}) {
-  const { clientPrefix = 'sdl', timeoutMs = MAX_POLL_MS } = opts;
+  const { clientPrefix = 'sdl', timeoutMs = MAX_POLL_MS, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS } = opts;
   const clientId = `${clientPrefix}-${Date.now()}`;
 
-  const res = await fetch(`${comfyUrl}/prompt`, {
+  const res = await fetchWithTimeout(`${comfyUrl}/prompt`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ prompt: workflow, client_id: clientId }),
-  });
+  }, requestTimeoutMs);
 
   if (!res.ok) {
     const text = await res.text();
@@ -72,7 +150,10 @@ export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {})
     await new Promise(r => setTimeout(r, 1000));
     let histRes;
     try {
-      histRes = await fetch(`${comfyUrl}/history/${promptId}`);
+      // SDL-H8: bounded so a server that accepts the connection and never
+      // responds lands in this catch (as an AbortError → clear timeout
+      // Error) instead of hanging `await fetch()` forever.
+      histRes = await fetchWithTimeout(`${comfyUrl}/history/${promptId}`, {}, requestTimeoutMs);
     } catch (err) {
       consecutiveHistoryFailures++;
       if (consecutiveHistoryFailures >= MAX_CONSECUTIVE_HISTORY_FAILURES) {
@@ -91,8 +172,23 @@ export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {})
       }
       continue;
     }
+    // SDL-L3: histRes.json() used to sit outside the retry block above, so
+    // a 200-OK non-JSON body (e.g. a proxy error page) threw a raw
+    // SyntaxError here, uncaught, permanently failing the image the
+    // adjacent 5-strike tolerance would otherwise have recovered from.
+    let history;
+    try {
+      history = await histRes.json();
+    } catch (err) {
+      consecutiveHistoryFailures++;
+      if (consecutiveHistoryFailures >= MAX_CONSECUTIVE_HISTORY_FAILURES) {
+        throw new Error(
+          `ComfyUI history endpoint returned an unparseable response ${MAX_CONSECUTIVE_HISTORY_FAILURES} times in a row for prompt ${promptId}: ${err.message}`
+        );
+      }
+      continue;
+    }
     consecutiveHistoryFailures = 0;
-    const history = await histRes.json();
     const entry = history[promptId];
 
     // PB-001: emit heartbeats so the user knows the pipeline isn't hung.
@@ -159,9 +255,10 @@ export async function submitAndWait(workflow, comfyUrl = DEFAULT_URL, opts = {})
  * @param {string} [subfolder]
  * @param {string} [comfyUrl]
  * @param {string} [type='output']
+ * @param {{timeoutMs?: number}} [opts]
  * @returns {Promise<Buffer>}
  */
-export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL, type = 'output') {
+export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL, type = 'output', opts = {}) {
   const ALLOWED_TYPES = ['output', 'input', 'temp'];
   if (!ALLOWED_TYPES.includes(type)) {
     throw new Error(`Invalid ComfyUI image type "${type}" — must be one of: ${ALLOWED_TYPES.join(', ')}`);
@@ -170,7 +267,7 @@ export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL,
     throw new Error(`Invalid comfyUrl "${comfyUrl}" — must start with http:// or https://`);
   }
   const url = `${comfyUrl}/view?filename=${encodeURIComponent(filename)}&subfolder=${encodeURIComponent(subfolder || '')}&type=${encodeURIComponent(type)}`;
-  const res = await fetch(url);
+  const res = await fetchWithTimeout(url, {}, opts.timeoutMs);
   if (!res.ok) throw new Error(`Download failed: ${res.status}`);
   return Buffer.from(await res.arrayBuffer());
 }
@@ -180,18 +277,19 @@ export async function downloadImage(filename, subfolder, comfyUrl = DEFAULT_URL,
  * @param {string} filePath — local file to upload
  * @param {string} filename — name to assign in ComfyUI
  * @param {string} [comfyUrl]
+ * @param {{timeoutMs?: number}} [opts]
  * @returns {Promise<string>} — assigned name from ComfyUI
  */
-export async function uploadImage(filePath, filename, comfyUrl = DEFAULT_URL) {
+export async function uploadImage(filePath, filename, comfyUrl = DEFAULT_URL, opts = {}) {
   const data = await readFile(filePath);
   const formData = new FormData();
   formData.append('image', new Blob([data], { type: 'image/png' }), filename);
   formData.append('overwrite', 'true');
 
-  const res = await fetch(`${comfyUrl}/upload/image`, {
+  const res = await fetchWithTimeout(`${comfyUrl}/upload/image`, {
     method: 'POST',
     body: formData,
-  });
+  }, opts.timeoutMs);
 
   if (!res.ok) {
     const text = await res.text();