@mcptoolshop/style-dataset-lab 3.3.0 → 3.4.0

package/README.zh.md

@@ -27,8 +27,15 @@ sdlab init my-project --domain character-design
 
 # Generate candidates via ComfyUI, then review them
 sdlab generate inputs/prompts/wave1.json --project my-project
+sdlab sheet outputs/candidates --project my-project   # HTML contact sheet to triage
 sdlab curate <id> approved "Strong silhouette, correct faction palette"
 
+# Already have images? Bring them in without generating anything
+sdlab ingest ~/renders/wave1 --project my-project
+
+# Measure what the pixels actually are — palette and texture, as numbers
+sdlab measure outputs/candidates --project my-project
+
 # Bind approved work to constitution rules
 # (`sdlab bind` is a shorter alias for `canon-bind`)
 sdlab canon-bind --project my-project
@@ -60,7 +67,7 @@ sdlab reingest selected --selection selection_2026-04-16_001
 
 ## 规范创作
 
-在数据集流水线运行之前，“sdlab canon *”命名空间会将你的项目的规范实体存储转换为三个投影，这些投影是训练和生产实际使用的——并且锁定那些不应发生变化的项目。
+Before the dataset pipeline runs, the `sdlab canon *` namespace turns your project's canon entity store into the three projections training and production actually consume — and locks the entries that must not drift.
 
 ```bash
 # Build three projections from the canon entity store:
@@ -76,7 +83,7 @@ sdlab canon freeze kael_maren --project my-project --reason "prologue portrait l
 sdlab canon drift --project my-project
 ```
 
-“canon build”（构建规范）是基于内容的——它的输出由一个“canon_sha”标识并进行缓存，因此未更改的规范可以立即重建。“canon freeze”（冻结规范）会针对特定的构建记录每次冻结操作，并将结果附加到“freeze-events.jsonl”审计跟踪中： “frozen”（已冻结）条目完全拒绝重新生成，“soft-advisory”（软提示）条目默认情况下拒绝（通过使用“--i-know”选项可以绕过）。“canon drift”（规范漂移）会重新计算每个受监控条目的哈希值，并标记自上次干净构建以来发生更改的任何内容。
+`canon build` 是基于内容的——它的输出由一个 `canon_sha` 确定，并进行缓存，因此未更改的规范可以立即重建。`canon freeze` 会针对特定的构建记录每次冻结状态，并将结果附加到 `freeze-events.jsonl` 审计跟踪中：`frozen` 条目会直接拒绝重新生成，`soft-advisory` 条目默认情况下会拒绝（通过 `--i-know` 可以绕过）。`canon drift` 会重新计算每个已监视条目的哈希值，并标记自上次完整构建以来发生更改的任何内容。
 
 完整的流程在手册中：[构建规范](handbook/canon-build/)、[冻结规范](handbook/canon-freeze/)和[双 LoRA 堆叠](handbook/two-lora-stacking/)。
 
@@ -90,7 +97,7 @@ sdlab canon drift --project my-project
 | **Split** | 训练/验证/测试分区，其中主题系列不会跨越边界。 |
 | **Export package** | 自包含数据集：清单、元数据、图像、分割、数据集卡、校验和。 |
 | **Eval pack** | 考虑规范的测试任务：车道覆盖率、禁止漂移、锚点/黄金标准、主题连续性。 |
-| **Training package** | 通过适配器（“diffusers-lora”、“generic-image-caption”）实现的，可用于训练器的布局。相同的真实数据，不同的格式。 |
+| **Training package** | 通过适配器实现训练器友好的布局（`diffusers-lora`、`generic-image-caption`）。相同的真相，不同的格式。 |
 | **Eval scorecard** | 根据评估包对生成的输出进行评分后的每个任务的通过/失败结果。 |
 | **Implementation pack** | 提示示例、已知错误、连续性测试和重新导入指南。 |
 
@@ -117,8 +124,8 @@ sdlab canon drift --project my-project
 
 这不是一个演示流水线。两个真实的风格 LoRA 都通过它完成了端到端的流程——相同的规范 → 策划 → 训练 → 发布循环，位于策划频谱的两端。
 
-- **[Tallow Fen](handbook/case-study-tallow-fen/)**（生物设计）——一个从头开始构建的奇幻生物典籍规范，在 293 个策划记录中，大约有 **34% 的批准率**（169 个被拒绝——审核严格）。发布了 `tallow_fen_style_v3.safetensors`，权重为 1.5，用于 `qwen-image`。
-- **[Rustline](handbook/case-study-rustline/)**（概念设计）——密集、预先构建的规范，在 180 个记录中，大约有 **96% 的批准率**。发布了 `rustline_v3ckpt_1500.safetensors`，权重为 1.0，用于 `qwen-image`，并在后续项目中被第二个项目重用。
+- **[Tallow Fen](handbook/case-study-tallow-fen/)**（生物设计）——一个从头开始构建的生物图鉴规范，在 293 个精选记录中获得约 **34% 的认可度**（169 个被拒绝——审核非常严格）。以 `tallow_fen_style_v3.safetensors` @ 1.5 的形式发布到 `qwen-image`。
+- **[Rustline](handbook/case-study-rustline/)**（概念设计）——一个密集、预先构建的规范，在 180 个记录中获得约 **96% 的认可度**。以 `rustline_v3ckpt_1500.safetensors` @ 1.0 的形式发布到 `qwen-image`，并在第二个项目中重复使用。
 
 相同的流水线，两种生产配置：策划审核是真实的（它会严格拒绝开放主题），并且严谨的规范可以产生很高的接受率。
 
@@ -162,13 +169,16 @@ projects/my-project/
 
 这些不是理想化的，而是强制执行的。
 
-- **快照是不可变的。** 配置指纹（SHA-256）证明没有任何更改。
-- **分割可以防止数据泄露。** 主题组（按身份、血统或 ID 后缀划分）永远不会跨越分区边界。
-- **清单是冻结的合同。** 导出哈希 + 配置指纹。如果发生任何更改，请创建一个新的。
-- **运行会固定其确切的图。** 每次生成都会记录 `comfy_workflow_sha` + 模型/LoRA 内容哈希 + 种子策略，因此一个批次可以完全重现——在 JS 和 Python 运行器中都是相同的。模型哈希是可选的（`--hash-models`），并且绝不会被伪造。
-- **没有模型会验证自己的输出。** 评估会记录 `judged_by_model` 和 `generator_model`；如果它们曾经是同一个模型，则会发出警告。
-- **适配器不能改变真相。** 不同的布局，相同的数据。没有添加、删除或重新分类。
-- **生成的输出通过审核后重新进入。** 没有绕过。像其他所有内容一样进行策划和绑定。
+- **快照是不可变的。** 配置指纹（SHA-256）证明没有任何更改。ID 是原子性地声明的，因此两个并发运行不能相互交错到一个目录中。
+- **分割可以防止泄漏——并且验证这一点的代码是独立的。** 主题系列（按身份、血统或规范化的 ID 词干）永远不会跨越分区边界，并且第二个检查会从头开始重新推导主题身份，而不是重新读取分割本身使用的映射。数据集卡仅在两个检查都运行并通过时声明“泄漏：无（已验证）”；如果分割早于第二次检查，则会明确说明这一点。
+- **清单是冻结的协议。** 导出哈希 + 配置指纹，并且 `validate` 会重新计算 `checksums.txt` 列出的每个文件——因此，替换完成导出中的图像会被捕获，包括对于在进行此检查之前创建的清单。
+- **运行会固定其确切的图。** 每个生成都会记录 `comfy_workflow_sha` + 模型/LoRA 内容哈希 + 种子策略，因此可以逐字节地重现一个批次。JS 和 Python 运行器通过一个测试来确保它们具有完全相同的哈希值，该测试会同时启动两者。模型哈希是可选的（`--hash-models`），并且绝不会伪造——如果无法解析某个文件，则会记录 `sha256: null` 并附带说明。
+- **没有模型会验证自己的输出。** 判断会记录 `judged_by_model` 和 `generator_model`；如果它们曾经是同一个模型，则会发出警告。
+- **判断会说明是谁做出的判断。** `eligibility audit` 会区分某人编写的判断和批量脚本生成的判断，因此描述一个类别而不是图像的理由不能被视为审核。
+- **测量不是结论。** `sdlab measure` 将数字附加到记录中。它绝不会设置判断、拟合或认可——并且如果某个图像没有定义度量值，则会记录 `null` 而不是一个合理的数字。
+- **适配器无法更改真相。** 不同的布局，相同的记录。没有添加、删除或重新分类。
+- **生成的输出会通过审核重新进入。** 没有绕过。像其他内容一样进行审核和绑定。外部生成的图像以相同的方式通过 `sdlab ingest` 进入，未经审核。
+- **失败是可见的。** 缺少记录、无法放置的图像或无法构建的标题会导致导出或训练包停止，而不是悄悄地缩小它。
 
 ## 星际货运
 
@@ -184,7 +194,7 @@ sdlab split build --project star-freight       # zero subject leakage
 
 ## 下游格式
 
-`sdlab` 拥有数据集。格式转换由 [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 处理：TRL、LLaVA、Qwen2-VL、JSONL、Parquet 等。`repo-dataset` 进行渲染；它不会决定是否包含。
+`sdlab` 拥有数据集。格式转换由 [`repo-dataset`](https://github.com/mcp-tool-shop-org/repo-dataset) 处理：TRL、LLaVA、Qwen2-VL、JSONL、Parquet 等。`repo-dataset` 进行渲染；它绝不会决定是否包含。
 
 ## 安装
 
@@ -209,7 +219,7 @@ sdlab project doctor --project test
 sdlab snapshot create --dry-run --project star-freight
 ```
 
-`sdlab project doctor` 会验证每个项目配置（宪法、通道、评分标准、术语），并在不触及 GPU 的情况下报告资格。任何会更改生成状态的命令都接受 `--dry-run`，以便首先预览效果。
+`sdlab project doctor` validates every project config (constitution, lanes, rubric, terminology) and reports eligibility without touching the GPU. Any command that mutates generated state accepts `--dry-run` to preview the effect first.
 
 如果您忘记了 `--project`，CLI 将回退到在 `projects/` 下找到的第一个项目并打印警告——明确传递 `--project` 以使其停止发出警告。
 
@@ -233,26 +243,26 @@ sdlab batch generate --resume batch_2026-04-22_001 --project my-project
 
 常见的失败模式和解决方法：
 
-**任何 `sdlab generate` / `sdlab run generate` / `sdlab batch generate` 上的 `ECONNREFUSED 127.0.0.1:8188`**
-ComfyUI 没有运行。启动 ComfyUI（`python main.py --listen 127.0.0.1 --port 8188`），并使用 `curl http://127.0.0.1:8188/system_stats` 进行确认。要指向不同的主机/端口，请设置 `COMFY_URL=http://host:port`。
+**`ECONNREFUSED 127.0.0.1:8188` 在任何 `sdlab generate` / `sdlab run generate` / `sdlab batch generate` 上**
+ComfyUI 没有运行。启动 ComfyUI（`python main.py --listen 127.0.0.1 --port 8188`）并通过 `curl http://127.0.0.1:8188/system_stats` 进行确认。要指向不同的主机/端口，请设置 `COMFY_URL=http://host:port`。
 
 **`missing checkpoint` / `LoRA weight not found`**
-您的工作流程配置文件指定了一个不在 ComfyUI 的 `models/checkpoints/` 或 `models/loras/` 文件夹中的模型文件。打开 `projects/<project>/workflows/profiles/<profile>.json`，找到 `checkpoint` 或 `lora` 字段，然后下载引用的权重或将其替换为您已有的权重。重新运行 `sdlab project doctor --project <project>` 以确认修复。
+您的工作流程配置文件指定了一个不在 ComfyUI 的 `models/checkpoints/` 或 `models/loras/` 文件夹中的模型文件。打开 `projects/<project>/workflows/profiles/<profile>.json`，找到 `checkpoint` 或 `lora` 字段，然后下载引用的权重或将其替换为您已经拥有的权重。重新运行 `sdlab project doctor --project <project>` 以确认修复。
 
 **`sdlab project doctor` 错误**
 Doctor 返回结构化的错误代码。常见的错误：
-- `E_PROJECT_NOT_FOUND`——项目目录在 `projects/` 下不存在。检查拼写。
+- `E_PROJECT_NOT_FOUND`——项目目录不存在于 `projects/` 下。检查拼写。
 - `E_CONFIG_INVALID`——五个 JSON 配置文件中的一个未能通过模式验证。`hint` 字段指定了错误的 文件和字段。
-- `E_RECORD_DRIFT`——记录的配置指纹不再与其来源匹配。如提示所述，重新策划或重新绑定。
+- `E_RECORD_DRIFT`——某个记录的配置指纹不再与其来源匹配。如提示所述，重新审核或重新绑定。
 
 **`No --project specified, falling back to <name>`**
 一个软警告。明确传递 `--project <name>` 以选择正确的项目并停止发出警告。
 
-**绘画风格 / VRAM 内存不足问题**
-请参阅 `docs/internal/HANDOFF.md`，了解有关绘画风格降噪调整说明。简而言之：降低降噪强度、减少批处理大小或在工作流程配置文件中切换到较小的检查点。
+**Painterly / VRAM out-of-memory issues**
+See `docs/internal/HANDOFF.md` for the painterly denoise tuning notes. In short: lower the denoise strength, reduce batch size, or switch to a smaller checkpoint in your workflow profile.
 
-**报告错误**
-在 https://github.com/mcp-tool-shop-org/style-dataset-lab/issues 上提交问题，并提供您的 sdlab 版本（`sdlab --version`）、Node 版本（`node -v`）、完整的命令以及结构化的错误输出。一个错误报告模板会预填充这些字段。
+**Reporting bugs**
+File an issue at https://github.com/mcp-tool-shop-org/style-dataset-lab/issues with your sdlab version (`sdlab --version`), Node version (`node -v`), the full command, and the structured error output. A bug-report template prefills the fields.
 
 ## 安全性
 

package/bin/sdlab.js

@@ -18,6 +18,21 @@ const COMMANDS = {
   'generate:controlnet': '../scripts/generate-controlnet.js',
   'generate:ipadapter':  '../scripts/generate-ipadapter.js',
   'curate':              '../scripts/curate.js',
+  // Bring images that were generated OUTSIDE sdlab into the pipeline. The
+  // documented production loop (brief→run→critique→batch→select→reingest) has
+  // never run on any project in this repo — real generation happens in
+  // external Python against Comfy Cloud, and until now those images had no
+  // CLI path in. `reingest generated` needs a trained LoRA's manifest;
+  // `reingest selected` needs a selection only the loop can mint.
+  'ingest':              '../scripts/ingest.js',
+  // Contact sheet over ANY directory of candidates. The renderer already
+  // existed (lib/batch-sheet-render.js) but was reachable only via
+  // `batch sheet`, which needs a batch manifest nothing has ever produced —
+  // so five hand-rolled PIL contact-sheet scripts grew up in projects/ instead.
+  'sheet':               '../scripts/sheet.js',
+  // Deterministic pixel measurement. Nothing in this tool opened an image
+  // before this: critique scores brief TEXT, not pixels.
+  'measure':             '../scripts/measure.js',
   'compare':             '../scripts/compare.js',
   'bind':                '../scripts/canon-bind.js',
   'canon-bind':          '../scripts/canon-bind.js',
@@ -362,7 +377,10 @@ function printHelp() {
   console.log('  generate:identity    Generate named-subject identity images');
   console.log('  generate:controlnet  ControlNet-guided structural generation');
   console.log('  generate:ipadapter   IP-Adapter reference-guided generation');
+  console.log('  ingest <dir>         Ingest externally-generated images as candidates');
   console.log('  curate               Move candidate to approved/rejected/borderline');
+  console.log('  sheet [<dir>]        Render an HTML contact sheet for visual review');
+  console.log('  measure <target>     Measure candidate pixels (palette, texture)');
   console.log('  compare              Record pairwise A-vs-B comparison');
   console.log('  canon-bind           Bind approved records to constitution rules');
   console.log('                       ("bind" is a short alias for canon-bind)');
@@ -445,15 +463,19 @@ function printHelp() {
   console.log('Examples:');
   console.log('  sdlab init my-project --domain character-design');
   console.log('  sdlab generate --help');
-  console.log('  sdlab snapshot create --project star-freight');
-  console.log('  sdlab split build --dry-run --project star-freight');
-  console.log('  sdlab training-package build --debug --project star-freight');
+  console.log('  sdlab snapshot create --project my-project');
+  console.log('  sdlab split build --dry-run --project my-project');
+  console.log('  sdlab training-package build --debug --project my-project');
 }
 
 // All top-level command tokens users can type (including two-word heads).
 function allKnownCommands() {
   const oneWord = Object.keys(COMMANDS);
-  const heads = ['project', 'workflow', 'brief', 'run', 'critique', 'refine', 'batch', 'select', 'selection'];
+  // SDL-L8: 'canon' is a real two-word namespace (see CANON_COMMANDS / the
+  // `namespaces` table in main()) but was missing from this list, so a typo
+  // like "sdlab cannon build" had no candidate to suggest against — every
+  // other namespace head got a "Did you mean ...?" hint, canon did not.
+  const heads = ['project', 'workflow', 'brief', 'run', 'critique', 'refine', 'batch', 'select', 'selection', 'canon'];
   return [...new Set([...oneWord, ...heads])];
 }
 
@@ -529,6 +551,31 @@ async function main() {
     }
   }
 
+  // SDL-L2: a bare or invalid namespace verb ("sdlab workflow", "sdlab batch
+  // bogus"). These heads only exist as two-word commands — falling through to
+  // the generic COMMANDS[command] lookup below used to hand `command` itself
+  // to findClosest() against a corpus that includes that same head, so the
+  // suggester matched itself at distance 0 and printed "Unknown command:
+  // workflow" / 'Did you mean "workflow"?' — a hint that echoes the very
+  // thing the user just typed. List the real subcommands instead.
+  for (const { head, table } of namespaces) {
+    if (command === head) {
+      const subs = Object.keys(table);
+      if (!args[1] || args[1] === '--help' || args[1] === '-h') {
+        console.log(`sdlab ${head} <${subs.join('|')}>\n`);
+        console.log('Subcommands:');
+        for (const s of subs) console.log(`  ${s}`);
+        console.log(`\nRun "sdlab ${head} <subcommand> --help" for details.`);
+        return;
+      }
+      const suggestion = findClosest(args[1], subs);
+      const hint = suggestion
+        ? `Did you mean "sdlab ${head} ${suggestion}"?`
+        : `Try: ${subs.map(s => `sdlab ${head} ${s}`).join(', ')}`;
+      throw inputError('INPUT_UNKNOWN_SUBCOMMAND', `Unknown ${head} subcommand: ${args[1]}`, hint);
+    }
+  }
+
   // "critique" — bare or "critique show"
   if (command === 'critique') {
     if (args[1] && CRITIQUE_COMMANDS[args[1]]) {

package/lib/adapters/ai-toolkit.js

@@ -22,6 +22,8 @@ import YAML from 'yaml';
 import { deriveStyleTrigger } from '../captions.js';
 import { groupRowsByPartition } from '../rows.js';
 import { inputError } from '../errors.js';
+import { assertSafeAssetPath, assertSafeId } from '../export.js';
+import { warn } from '../log.js';
 
 /**
  * Build training package in ai-toolkit format from canonical rows.
@@ -38,6 +40,11 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
   const partitioned = groupRowsByPartition(rows || []);
 
   let imageCount = 0;
+  // SDL-C5: per-row failure accounting (export.js DB-002 shape) — see
+  // generic-image-caption.js for the full rationale. A caught copy/symlink
+  // error must not silently drop the image, caption sidecar, AND metadata
+  // row together with zero logging.
+  const imagesFailed = [];
 
   for (const [partition, partitionRows] of Object.entries(partitioned)) {
     const datasetDir = join(packageDir, 'dataset', partition);
@@ -48,10 +55,21 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
     const metadataRows = [];
 
     for (const row of partitionRows) {
-      if (!row.asset_path) continue;
+      if (!row.asset_path) {
+        imagesFailed.push({ record_id: row.entity_id, partition, reason: 'missing_asset_path' });
+        continue;
+      }
 
-      const sourcePath = join(projectRoot, row.asset_path);
-      if (!existsSync(sourcePath)) continue;
+      // SDL-H5 / SDL-H6: defense-in-depth — see generic-image-caption.js
+      // for the full rationale. Throws (hard fail) on traversal/unsafe id;
+      // that is a security boundary, not an operational hiccup.
+      assertSafeId(row.entity_id, `row.entity_id in ai-toolkit adapter (partition "${partition}")`);
+      const sourcePath = assertSafeAssetPath(row.asset_path, projectRoot, row.entity_id);
+
+      if (!existsSync(sourcePath)) {
+        imagesFailed.push({ record_id: row.entity_id, partition, reason: 'source_missing' });
+        continue;
+      }
 
       const sourceBasename = row.asset_path.split(/[\\/]/).pop();
       const extMatch = sourceBasename.match(/\.[^.]+$/);
@@ -67,7 +85,13 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
           await symlink(relative(datasetDir, sourcePath), destPath);
         }
         imageCount++;
-      } catch {
+      } catch (err) {
+        imagesFailed.push({
+          record_id: row.entity_id,
+          partition,
+          reason: copy ? 'copy_failed' : 'link_failed',
+          detail: err.message,
+        });
         continue;
       }
 
@@ -91,13 +115,21 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
     );
   }
 
+  if (imagesFailed.length > 0) {
+    const sample = imagesFailed.slice(0, 10).map(f => `${f.record_id} (${f.reason})`);
+    warn(
+      `ai-toolkit adapter: ${imagesFailed.length} of ${imageCount + imagesFailed.length} rows failed to place` +
+      (imagesFailed.length > 10 ? ` — first 10: ${sample.join(', ')}, ...` : ` — ${sample.join(', ')}`),
+    );
+  }
+
   const aiToolkitConfig = buildAiToolkitConfig({ profile, manifest });
   await writeFile(
     join(packageDir, 'ai-toolkit-config.yaml'),
     YAML.stringify(aiToolkitConfig)
   );
 
-  return { imageCount };
+  return { imageCount, imagesFailed };
 }
 
 /**

package/lib/adapters/comfyui-runner.js

@@ -7,9 +7,9 @@
 
 import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { comfyHealth, submitAndWait, downloadImage } from '../comfyui.js';
+import { comfyHealthDetailed, submitAndWait, downloadImage } from '../comfyui.js';
 import { buildWorkflowGraph, resolveTemplateId, QWEN_DEFAULTS } from './comfyui-workflows.js';
-import { buildSeedPlan, prepareRunDir, saveRunManifest } from '../runtime-runs.js';
+import { buildSeedPlan, prepareRunDir, saveRunManifest, checkpointRunManifest } from '../runtime-runs.js';
 import { loadProjectConfig } from '../config.js';
 import { pickOutputImage } from '../comfyui-output.js';
 import { buildPinning, seedPolicyFromMode, createHashCache, flushHashCache } from '../run-manifest.js';
@@ -17,6 +17,24 @@ import { SCHEMA_VERSION } from '../snapshot.js';
 import { log, info, warn } from '../log.js';
 import { runtimeError } from '../errors.js';
 
+// B04: comfyHealthDetailed()'s `reason` maps to an ACTIONABLE hint, instead
+// of every failure mode sharing the same "start ComfyUI" advice — which is
+// simply wrong for an `http-<5xx>` (ComfyUI is up and answering) and useless
+// for `dns`/`refused` against a misconfigured URL.
+const HEALTH_REASON_HINTS = {
+  timeout: 'ComfyUI accepted the connection but never responded — it may be loading a custom node or a large model. Wait and retry, or check its console for a stuck step.',
+  refused: 'Start ComfyUI, or check COMFY_URL / project defaults.comfy_url — the connection was actively refused.',
+  dns: 'COMFY_URL / project defaults.comfy_url does not resolve — check for a typo in the hostname.',
+  unknown: 'Start ComfyUI or set COMFY_URL / project defaults.comfy_url.',
+};
+
+function healthReasonHint(reason) {
+  if (reason && reason.startsWith('http-')) {
+    return `ComfyUI responded with ${reason.slice('http-'.length)} — it is reachable but reported an error; check its console/logs.`;
+  }
+  return HEALTH_REASON_HINTS[reason] || HEALTH_REASON_HINTS.unknown;
+}
+
 /**
  * Execute a brief: build graphs, submit to ComfyUI, capture outputs.
  *
@@ -50,12 +68,16 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
 
   // Health check
   if (!dryRun) {
-    const healthy = await comfyHealth(comfyUrl);
-    if (!healthy) {
+    // B04: use the reason-carrying check so a 503-while-loading, a refused
+    // connection, a DNS typo, and a genuine timeout each get their OWN
+    // actionable hint instead of the identical (and sometimes factually
+    // wrong) "ComfyUI not reachable — start ComfyUI" message.
+    const health = await comfyHealthDetailed(comfyUrl);
+    if (!health.ok) {
       throw runtimeError(
         'COMFYUI_OFFLINE',
-        `ComfyUI not reachable at ${comfyUrl}`,
-        'Start ComfyUI or set COMFY_URL / project defaults.comfy_url'
+        `ComfyUI not reachable at ${comfyUrl} (${health.reason})`,
+        healthReasonHint(health.reason)
       );
     }
     info('ComfyUI online');
@@ -63,6 +85,43 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
 
   const outputs = [];
   const errors = [];
+  // B01: fixed at run start and reused by every mid-loop checkpoint AND the
+  // final manifest, so `created_at` never drifts between an incremental
+  // snapshot and the finished manifest for the same run.
+  const createdAt = new Date().toISOString();
+
+  // B01: checkpointRunManifest() existed (with a docstring saying exactly
+  // this) but had zero production callers — comfyui-runner.js only called
+  // saveRunManifest() once, after the whole loop. A run killed partway
+  // through wrote NO manifest at all, so listRuns() silently skipped the
+  // directory entirely: no id, no `run show`, no resume. This snapshot
+  // mirrors the final manifest's shape (minus `pinning`, computed only
+  // after the loop) so a partial manifest.json is readable by the same
+  // code that reads a finished one.
+  function buildManifestSnapshot() {
+    return {
+      run_id: runId,
+      schema_version: SCHEMA_VERSION,
+      brief_id: brief.brief_id,
+      project_id: brief.project_id,
+      workflow_template_id: templateId,
+      adapter_target: 'comfyui',
+      output_mode: outputMode,
+      output_count: outputCount,
+      created_at: createdAt,
+      seed_plan: seedPlan,
+      comfy_url: comfyUrl,
+      checkpoint: defaults.checkpoint,
+      loras: defaults.loras || [],
+      pinning: null,
+      runtime_plan: brief.runtime_plan,
+      outputs,
+      errors,
+      dry_run: dryRun,
+      success_count: outputs.filter(o => o.status === 'ok' || o.status === 'dry_run').length,
+      error_count: errors.length,
+    };
+  }
 
   for (let i = 0; i < outputCount; i++) {
     const seed = seedPlan.seeds[i];
@@ -77,6 +136,7 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
         status: 'dry_run',
         filename: `${imageIndex}.png`,
       });
+      await checkpointRunManifest(runDir, buildManifestSnapshot());
       continue;
     }
 
@@ -106,6 +166,7 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
       if (!picked) {
         warn(`  No output image for seed ${seed}`);
         outputs.push({ index: i, seed, status: 'no_output', elapsed_ms: elapsed });
+        await checkpointRunManifest(runDir, buildManifestSnapshot());
         continue;
       }
 
@@ -138,6 +199,12 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
         elapsed_ms: elapsed,
       });
     }
+
+    // B01: checkpoint after every completed output (success OR error) so a
+    // crash/interruption mid-loop leaves a partial, readable manifest.json
+    // instead of an orphan directory — this is the call the docstring on
+    // checkpointRunManifest() always described but nothing ever made.
+    await checkpointRunManifest(runDir, buildManifestSnapshot());
   }
 
   // PIN_PER_STEP: pin the exact graph + model/LoRA content identity + seed
@@ -170,28 +237,14 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
     warn(`pinning skipped: ${err.message}`);
   }
 
-  // Build manifest
+  // Build manifest — reuses buildManifestSnapshot() (same helper the
+  // mid-loop checkpoints use) so the finished manifest and every
+  // incremental checkpoint before it are byte-for-byte the same shape,
+  // just with `pinning` filled in and no `incremental`/`last_checkpoint_at`
+  // stamp (that stamp is what lets a reader tell "done" from "still going").
   const manifest = {
-    run_id: runId,
-    schema_version: SCHEMA_VERSION,
-    brief_id: brief.brief_id,
-    project_id: brief.project_id,
-    workflow_template_id: templateId,
-    adapter_target: 'comfyui',
-    output_mode: outputMode,
-    output_count: outputCount,
-    created_at: new Date().toISOString(),
-    seed_plan: seedPlan,
-    comfy_url: comfyUrl,
-    checkpoint: defaults.checkpoint,
-    loras: defaults.loras || [],
+    ...buildManifestSnapshot(),
     pinning,
-    runtime_plan: brief.runtime_plan,
-    outputs,
-    errors,
-    dry_run: dryRun,
-    success_count: outputs.filter(o => o.status === 'ok' || o.status === 'dry_run').length,
-    error_count: errors.length,
   };
 
   await saveRunManifest(runDir, manifest);

package/lib/adapters/comfyui-workflows.js

@@ -33,8 +33,16 @@ export function listWorkflowTemplates() {
 
 /**
  * Resolve a template for a given output mode.
- * Returns 'txt2img-standard' for all standard modes.
- * Throws if no template matches.
+ *
+ * Returns the first template declaring `outputMode` in its `compatible_modes`,
+ * and falls back to `'txt2img-standard'` when none matches — it does NOT
+ * throw. (The docstring claimed a throw until 2026-08-04; a caller written
+ * against that claim would guard a branch that cannot fire and would miss the
+ * silent-default case, where an unrecognised mode renders through the standard
+ * SDXL graph instead of failing loudly.)
+ *
+ * The fallback is also what makes an install with no `runtime/comfyui/`
+ * templates degrade rather than crash — see `getRuntimeDir()` in lib/paths.js.
  */
 export function resolveTemplateId(outputMode) {
   const templates = listWorkflowTemplates();

package/lib/adapters/diffusers-lora.js

@@ -16,6 +16,8 @@ import { writeFile, mkdir, symlink, copyFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { existsSync } from 'node:fs';
 import { groupRowsByPartition } from '../rows.js';
+import { assertSafeAssetPath, assertSafeId } from '../export.js';
+import { warn } from '../log.js';
 
 /**
  * Build training package in diffusers LoRA format from canonical rows.
@@ -33,6 +35,11 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
   const partitioned = groupRowsByPartition(rows || []);
 
   let imageCount = 0;
+  // SDL-C5: per-row failure accounting (export.js DB-002 shape) — see
+  // generic-image-caption.js for the full rationale. A caught copy/symlink
+  // error must not silently drop the image, caption sidecar, AND metadata
+  // row together with zero logging.
+  const imagesFailed = [];
 
   for (const [partition, partitionRows] of Object.entries(partitioned)) {
     const datasetDir = join(packageDir, 'dataset', partition);
@@ -43,10 +50,21 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
     const metadataRows = [];
 
     for (const row of partitionRows) {
-      if (!row.asset_path) continue;
+      if (!row.asset_path) {
+        imagesFailed.push({ record_id: row.entity_id, partition, reason: 'missing_asset_path' });
+        continue;
+      }
 
-      const sourcePath = join(projectRoot, row.asset_path);
-      if (!existsSync(sourcePath)) continue;
+      // SDL-H5 / SDL-H6: defense-in-depth — see generic-image-caption.js
+      // for the full rationale. Throws (hard fail) on traversal/unsafe id;
+      // that is a security boundary, not an operational hiccup.
+      assertSafeId(row.entity_id, `row.entity_id in diffusers-lora adapter (partition "${partition}")`);
+      const sourcePath = assertSafeAssetPath(row.asset_path, projectRoot, row.entity_id);
+
+      if (!existsSync(sourcePath)) {
+        imagesFailed.push({ record_id: row.entity_id, partition, reason: 'source_missing' });
+        continue;
+      }
 
       const sourceBasename = row.asset_path.split(/[\\/]/).pop();
       const extMatch = sourceBasename.match(/\.[^.]+$/);
@@ -62,7 +80,13 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
           await symlink(relative(datasetDir, sourcePath), destPath);
         }
         imageCount++;
-      } catch {
+      } catch (err) {
+        imagesFailed.push({
+          record_id: row.entity_id,
+          partition,
+          reason: copy ? 'copy_failed' : 'link_failed',
+          detail: err.message,
+        });
         continue;
       }
 
@@ -77,7 +101,15 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
     );
   }
 
-  return { imageCount };
+  if (imagesFailed.length > 0) {
+    const sample = imagesFailed.slice(0, 10).map(f => `${f.record_id} (${f.reason})`);
+    warn(
+      `diffusers-lora adapter: ${imagesFailed.length} of ${imageCount + imagesFailed.length} rows failed to place` +
+      (imagesFailed.length > 10 ? ` — first 10: ${sample.join(', ')}, ...` : ` — ${sample.join(', ')}`),
+    );
+  }
+
+  return { imageCount, imagesFailed };
 }
 
 function buildMetadataRow(row, partition, filename, stem) {

package/lib/adapters/generic-image-caption.js

@@ -14,11 +14,20 @@ import { writeFile, mkdir, symlink, copyFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { existsSync } from 'node:fs';
 import { groupRowsByPartition } from '../rows.js';
+import { assertSafeAssetPath, assertSafeId } from '../export.js';
+import { warn } from '../log.js';
 
 export async function buildPackage({ packageDir, rows, profile, manifest, config, projectRoot, copy }) {
   const partitioned = groupRowsByPartition(rows || []);
 
   let imageCount = 0;
+  // SDL-C5: per-row failure accounting (export.js DB-002 shape). The old
+  // bare `catch { continue; }` silently dropped the image, the caption
+  // sidecar, AND the metadata row together with no logging — on Windows
+  // without Developer Mode this fired on every row, so imageCount stayed
+  // 0 and the build still reported success. Every drop is now accounted
+  // for and returned to the caller.
+  const imagesFailed = [];
 
   for (const [partition, partitionRows] of Object.entries(partitioned)) {
     const datasetDir = join(packageDir, 'dataset', partition);
@@ -29,10 +38,25 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
     const metadataRows = [];
 
     for (const row of partitionRows) {
-      if (!row.asset_path) continue;
+      if (!row.asset_path) {
+        imagesFailed.push({ record_id: row.entity_id, partition, reason: 'missing_asset_path' });
+        continue;
+      }
 
-      const sourcePath = join(projectRoot, row.asset_path);
-      if (!existsSync(sourcePath)) continue;
+      // SDL-H5 / SDL-H6: defense-in-depth. buildTrainingPackage validates
+      // every row before dispatching here, but this adapter is also
+      // unit-tested (and documented in lib/rows.js as a future direct
+      // canon-build target) independent of that caller, so the guard
+      // lives here too. A traversal / unsafe id is a security boundary,
+      // not an operational hiccup — it throws (hard fail) rather than
+      // joining the soft imagesFailed accounting below.
+      assertSafeId(row.entity_id, `row.entity_id in generic-image-caption adapter (partition "${partition}")`);
+      const sourcePath = assertSafeAssetPath(row.asset_path, projectRoot, row.entity_id);
+
+      if (!existsSync(sourcePath)) {
+        imagesFailed.push({ record_id: row.entity_id, partition, reason: 'source_missing' });
+        continue;
+      }
 
       const sourceBasename = row.asset_path.split(/[\\/]/).pop();
       const extMatch = sourceBasename.match(/\.[^.]+$/);
@@ -47,7 +71,13 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
           await symlink(relative(datasetDir, sourcePath), destPath);
         }
         imageCount++;
-      } catch {
+      } catch (err) {
+        imagesFailed.push({
+          record_id: row.entity_id,
+          partition,
+          reason: copy ? 'copy_failed' : 'link_failed',
+          detail: err.message,
+        });
         continue;
       }
 
@@ -67,5 +97,13 @@ export async function buildPackage({ packageDir, rows, profile, manifest, config
     );
   }
 
-  return { imageCount };
+  if (imagesFailed.length > 0) {
+    const sample = imagesFailed.slice(0, 10).map(f => `${f.record_id} (${f.reason})`);
+    warn(
+      `generic-image-caption adapter: ${imagesFailed.length} of ${imageCount + imagesFailed.length} rows failed to place` +
+      (imagesFailed.length > 10 ? ` — first 10: ${sample.join(', ')}, ...` : ` — ${sample.join(', ')}`),
+    );
+  }
+
+  return { imageCount, imagesFailed };
 }