@mcptoolshop/style-dataset-lab 3.2.0 → 3.4.0

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,14 +7,34 @@
 
 import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { comfyHealth, submitAndWait, downloadImage } from '../comfyui.js';
-import { buildWorkflowGraph, resolveTemplateId } from './comfyui-workflows.js';
-import { buildSeedPlan, prepareRunDir, saveRunManifest } from '../runtime-runs.js';
+import { comfyHealthDetailed, submitAndWait, downloadImage } from '../comfyui.js';
+import { buildWorkflowGraph, resolveTemplateId, QWEN_DEFAULTS } from './comfyui-workflows.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';
+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.
  *
@@ -26,7 +46,7 @@ import { runtimeError } from '../errors.js';
  * @param {boolean} [opts.dryRun] — if true, prepare run dir but do not submit
  * @returns {Promise<Object>} — manifest
  */
-export async function executeRun({ projectRoot, projectName, brief, baseSeed, dryRun = false }) {
+export async function executeRun({ projectRoot, projectName, brief, baseSeed, dryRun = false, hashModels = false }) {
   const config = loadProjectConfig(projectRoot);
   const defaults = config.meta?.defaults ?? {};
   const comfyUrl = defaults.comfy_url || process.env.COMFY_URL || 'http://127.0.0.1:8188';
@@ -48,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');
@@ -61,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];
@@ -75,6 +136,7 @@ export async function executeRun({ projectRoot, projectName, brief, baseSeed, dr
         status: 'dry_run',
         filename: `${imageIndex}.png`,
       });
+      await checkpointRunManifest(runDir, buildManifestSnapshot());
       continue;
     }
 
@@ -104,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;
       }
 
@@ -136,28 +199,52 @@ 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
+  // policy via the shared contract (lib/run-manifest.js). One run = one prompt
+  // across N seeds, so the pin is wave-level (per-item seed is normalized out of
+  // comfy_workflow_sha and kept in seed_plan). Best-effort — a build/hash failure
+  // degrades to null pinning rather than failing the run.
+  let pinning = null;
+  try {
+    const isQwen = String(defaults.base || '').toLowerCase() === 'qwen-image';
+    const pinModels = isQwen
+      ? {
+          unet: defaults.unet || QWEN_DEFAULTS.unet,
+          clip: defaults.clip || QWEN_DEFAULTS.clip,
+          vae: defaults.vae || QWEN_DEFAULTS.vae,
+        }
+      : { checkpoint: defaults.checkpoint };
+    const pinCache = hashModels ? createHashCache() : undefined;
+    const { nodes: pinNodes } = buildWorkflowGraph({ brief, projectDefaults: defaults, seed: seedPlan.seeds[0] ?? 0 });
+    pinning = buildPinning({
+      graph: pinNodes,
+      models: pinModels,
+      loras: defaults.loras || [],
+      seedPolicy: seedPolicyFromMode(seedMode),
+      hashModels,
+      cache: pinCache,
+    });
+    flushHashCache(pinCache);
+  } catch (err) {
+    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,
-    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 || [],
-    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,
+    ...buildManifestSnapshot(),
+    pinning,
   };
 
   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 };
 }

package/lib/args.js

@@ -149,8 +149,23 @@ export function getProjectName(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--project' || a === '--game') {
+      const flagName = a === '--game' ? 'game' : 'project';
       if (a === '--game') warnDeprecated('game', 'project');
-      explicit = argv[i + 1];
+      const next = argv[i + 1];
+      // SDL-L1: mirror takeFlagValue's guard below — without it, a missing
+      // value silently swallowed the NEXT flag as the project name (e.g.
+      // `--project --dry-run` yielded the project name "--dry-run").
+      if (next === undefined) {
+        throw inputError('INPUT_MISSING_VALUE', `Flag --${flagName} requires a value.`);
+      }
+      if (next.startsWith('--')) {
+        throw inputError(
+          'INPUT_MISSING_VALUE',
+          `Flag --${flagName} is missing its value (got another flag: ${next}).`,
+          `Pass a value after --${flagName}.`
+        );
+      }
+      explicit = next;
       break;
     }
     if (a.startsWith('--project=')) { explicit = a.slice('--project='.length); break; }

package/lib/batch-modes.js

@@ -27,25 +27,35 @@ export function getBatchModesDir(projectRoot) {
 
 /**
  * List all batch modes for a project.
+ *
+ * B06: listWorkflowProfiles() (its structurally identical sibling in
+ * workflow-profiles.js) already skips a malformed file per-entry via
+ * try/catch. This function had no such guard, so one bad batch-mode file
+ * threw an uncaught SyntaxError out of Array.prototype.map and hid EVERY
+ * batch mode, not just the broken one.
  */
 export function listBatchModes(projectRoot) {
   const dir = getBatchModesDir(projectRoot);
   if (!existsSync(dir)) return [];
 
-  return readdirSync(dir)
-    .filter(f => f.endsWith('.json'))
-    .map(f => {
+  const modes = [];
+  for (const f of readdirSync(dir).filter(f => f.endsWith('.json'))) {
+    try {
       const data = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
-      return {
+      modes.push({
         mode_id: data.mode_id,
         label: data.label,
         batch_type: data.batch_type,
         base_workflow_id: data.base_workflow_id,
         subject_mode: data.subject_mode || 'optional',
         slot_count: data.variant_plan?.length || 0,
-      };
-    })
-    .sort((a, b) => a.mode_id.localeCompare(b.mode_id));
+      });
+    } catch {
+      // Skip malformed — matches listWorkflowProfiles' existing resilience.
+    }
+  }
+
+  return modes.sort((a, b) => a.mode_id.localeCompare(b.mode_id));
 }
 
 /**
@@ -63,7 +73,18 @@ export function getBatchMode(projectRoot, modeId) {
     );
   }
 
-  return JSON.parse(readFileSync(filePath, 'utf-8'));
+  // B06: JSON.parse used to run unguarded here, so a malformed mode file
+  // threw a raw, uncaught SyntaxError naming nothing. Wrapped in the same
+  // structured-error pattern lib/config.js's loadJsonFile already uses.
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    throw inputError(
+      'INPUT_INVALID_JSON',
+      `Failed to parse ${filePath}: ${err.message}`,
+      'Check the file for JSON syntax errors (trailing commas, unquoted keys, etc).'
+    );
+  }
 }
 
 /**