@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/reingest-selected.js

@@ -6,9 +6,9 @@
  * canon-binding flow as everything else. No bypass.
  */
 
-import { writeFile, mkdir, copyFile } from 'node:fs/promises';
+import { writeFile, mkdir, copyFile, rename, unlink } from 'node:fs/promises';
 import { join, extname } from 'node:path';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { getRunsDir } from './paths.js';
 import { getBatchesDir } from './batch-runs.js';
 import { getSelectionsDir, loadSelection } from './selections.js';
@@ -16,6 +16,35 @@ import { buildGeneratedProvenance } from './generated-provenance.js';
 import { buildBaseRecord } from './records.js';
 import { inputError } from './errors.js';
 
+// SDL-H7: the only shape a selection id can ever legitimately have,
+// mirroring generateSelectionId() in lib/selections.js (selection_<date>_<seq>,
+// same prefix/date/seq scheme as run/batch ids). Validated BEFORE the id is
+// used anywhere — including before loadSelection(), which does its own
+// unguarded join — so a traversal payload never reaches the filesystem, and
+// before the join at `selectionDir` below, which this module writes
+// provenance.jsonl into. A mismatch reuses loadSelection's own
+// SELECTION_NOT_FOUND shape (not a distinct code) because no real selection
+// can ever have an id outside this shape.
+const SELECTION_ID_RE = /^selection_\d{4}-\d{2}-\d{2}_\d{3}$/;
+
+/**
+ * B03: atomic write helper — write temp + rename, mirroring the same
+ * temp-file-then-rename checkpoint pattern lib/batch-runs.js uses for its
+ * per-slot manifest checkpoint. Rename is atomic on a single filesystem, so
+ * a crash mid-write can never leave a half-written provenance.jsonl in
+ * place of a good one.
+ */
+async function atomicWriteText(targetPath, text) {
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await writeFile(tmpPath, text);
+    await rename(tmpPath, targetPath);
+  } catch (err) {
+    try { await unlink(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
 /**
  * Re-ingest a selection — creates candidate records from chosen outputs.
  *
@@ -27,6 +56,14 @@ import { inputError } from './errors.js';
  * @returns {Promise<{created: string[], skipped: string[]}>}
  */
 export async function reingestSelection({ projectRoot, projectId, selectionId, dryRun }) {
+  if (typeof selectionId !== 'string' || !SELECTION_ID_RE.test(selectionId)) {
+    throw inputError(
+      'SELECTION_NOT_FOUND',
+      `Selection "${selectionId}" not found`,
+      'Check the selection ID or run: sdlab select --run <id> --approve <files>',
+    );
+  }
+
   const manifest = loadSelection(projectRoot, selectionId);
 
   if (!manifest.reingest_ready) {
@@ -69,7 +106,46 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
 
   const created = [];
   const skipped = [];
+
+  // B03: provenance.jsonl is now built incrementally — checkpointed (atomic
+  // full-rewrite, temp+rename) after every item — instead of accumulated in
+  // memory and overwritten once at the end. `provenanceLines` seeds from
+  // whatever is ALREADY on disk (e.g. left by an interrupted prior run of
+  // this same selection) so: (a) a rerun never duplicates a line for a
+  // record it already logged, and (b) a partial rerun can never ERASE lines
+  // a previous call already committed — the old end-of-run `writeFile`
+  // overwrote with only the CURRENT call's accumulator, so a second call
+  // touching fewer items than the first could silently wipe out provenance
+  // the first call had already written to disk.
+  const provenancePath = join(selectionDir, 'provenance.jsonl');
   const provenanceLines = [];
+  const seenProvenanceIds = new Set();
+  if (existsSync(provenancePath)) {
+    for (const line of readFileSync(provenancePath, 'utf-8').split('\n')) {
+      if (!line.trim()) continue;
+      provenanceLines.push(line);
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed?.record_id) seenProvenanceIds.add(parsed.record_id);
+      } catch {
+        // Tolerate a corrupt/partial trailing line from a prior crash —
+        // keep it verbatim rather than dropping it, just don't index it.
+      }
+    }
+  }
+
+  /**
+   * Checkpoint one provenance line: skips dryRun, and skips a record_id
+   * that's already logged (idempotent — safe to call on both the fresh-write
+   * path and the skip/backfill path below).
+   */
+  async function checkpointProvenance(recordId, prov) {
+    if (dryRun) return;
+    if (seenProvenanceIds.has(recordId)) return;
+    provenanceLines.push(JSON.stringify({ record_id: recordId, ...prov }));
+    seenProvenanceIds.add(recordId);
+    await atomicWriteText(provenancePath, provenanceLines.join('\n') + '\n');
+  }
 
   // D-010: use entries() — not indexOf() — to avoid O(n^2) behavior and
   // silent duplicate-ID bugs when manifest.items contains structurally
@@ -88,12 +164,11 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
     seenIds.add(recordId);
     const recordPath = join(recordsDir, `${recordId}.json`);
 
-    if (existsSync(recordPath)) {
-      skipped.push(recordId);
-      continue;
-    }
-
-    // Resolve the run manifest for this item
+    // Resolve the run manifest for this item + build its provenance BEFORE
+    // the existsSync check below — B03: a skipped (already-created) item
+    // still needs its provenance backfilled if an earlier interrupted run
+    // stopped short of appending it, so this can't be gated behind "the
+    // record is new".
     let runManifest;
     if (manifest.source_type === 'run') {
       runManifest = getRunManifest(manifest.source_id);
@@ -124,8 +199,19 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
       batchManifest,
       item,
       projectRoot,
+      canonSha: manifest.canon_sha ?? null,
     });
 
+    if (existsSync(recordPath)) {
+      // B03: the record already landed on disk (this item was completed by
+      // a prior, possibly-interrupted run of this same re-ingest). Backfill
+      // its provenance line if that prior run never got to append one —
+      // never let a record exist with no corresponding provenance entry.
+      await checkpointProvenance(recordId, prov);
+      skipped.push(recordId);
+      continue;
+    }
+
     // Image source in selection/chosen/
     const srcImage = join(selectionDir, 'chosen', item.filename);
     const ext = extname(item.filename) || '.png';
@@ -139,6 +225,15 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
       fileBytes = statSync(srcImage).size;
     }
 
+    const canonBlock =
+      prov.canon_sha || prov.entry_id || prov.entry_sha256
+        ? {
+            canon_sha: prov.canon_sha ?? null,
+            entry_id: prov.entry_id ?? null,
+            entry_sha256: prov.entry_sha256 ?? null,
+          }
+        : null;
+
     // Build record
     const record = buildBaseRecord(recordId, assetPath, {
       width: null,
@@ -148,9 +243,13 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
       source: 'generated',
       selection_id: selectionId,
       generation_provenance: prov,
+    }, {
+      canon: canonBlock,
     });
 
     record.schema_version = '2.2.0';
+    record.generation_provenance = prov;
+    if (projectId) record.project_id = projectId;
 
     // Tags
     const recordTags = ['generated', 'selected'];
@@ -166,18 +265,15 @@ export async function reingestSelection({ projectRoot, projectId, selectionId, d
       }
       // Write record
       await writeFile(recordPath, JSON.stringify(record, null, 2) + '\n');
+      // B03: checkpoint immediately after the record write (per-item,
+      // matching lib/batch-runs.js's per-slot checkpoint pattern) — NOT
+      // batched to the end of the run. A crash on item 120 of 200 must
+      // leave provenance for 1-119 durably on disk, not lose it because
+      // item 200 never finished.
+      await checkpointProvenance(recordId, prov);
     }
 
     created.push(recordId);
-    provenanceLines.push(JSON.stringify({ record_id: recordId, ...prov }));
-  }
-
-  // Write provenance log
-  if (!dryRun && provenanceLines.length > 0) {
-    await writeFile(
-      join(selectionDir, 'provenance.jsonl'),
-      provenanceLines.join('\n') + '\n',
-    );
   }
 
   return { created, skipped };

package/lib/reingest.js

@@ -12,6 +12,8 @@ import { join, basename, extname } from 'node:path';
 import { existsSync } from 'node:fs';
 import { loadTrainingManifest } from './training-manifests.js';
 import { buildBaseRecord } from './records.js';
+import { resolveCanonLink } from './generated-provenance.js';
+import { resolveModelLicence } from './model-licences.js';
 
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
 
@@ -22,12 +24,12 @@ const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
  * - provenance.source = "generated"
  * - provenance.training_manifest_id = <manifest-id>
  * - judgment = null (must be reviewed)
- * - canon = null (must be bound)
+ * - canon = resolved canon link when canon-build is present, else null
  *
  * @param {string} projectRoot
  * @param {string} sourcePath — directory containing generated images
  * @param {string} manifestId — training manifest that produced them
- * @param {Object} options — { dryRun? }
+ * @param {Object} options — { dryRun?, canonSha?, entryId? }
  * @returns {Promise<{created: number, skipped: number, records: string[]}>}
  */
 export async function reingestGenerated(projectRoot, sourcePath, manifestId, options = {}) {
@@ -66,12 +68,32 @@ export async function reingestGenerated(projectRoot, sourcePath, manifestId, opt
     // Relative asset path from project root
     const assetPath = `outputs/candidates/${file}`;
 
+    const canonLink = resolveCanonLink(projectRoot, {
+      canonSha: options.canonSha || manifest.canon_sha || null,
+      entryId: options.entryId || stem,
+    });
+    const baseLic = manifest.base_model ? resolveModelLicence(manifest.base_model) : null;
+
     const provenance = {
       source: 'generated',
       training_manifest_id: manifestId,
       training_profile_id: manifest.training_profile_id,
       adapter_target: manifest.adapter_target,
       base_model: manifest.base_model || null,
+      ...(baseLic
+        ? {
+            licence_id: baseLic.licence_id,
+            licence_url: baseLic.licence_url,
+            date_read: baseLic.date_read,
+          }
+        : {}),
+      ...(canonLink
+        ? {
+            canon_sha: canonLink.canon_sha,
+            entry_id: canonLink.entry_id,
+            entry_sha256: canonLink.entry_sha256,
+          }
+        : {}),
       source_export_id: manifest.source_export_id,
       generated_at: new Date().toISOString(),
       original_path: filePath,
@@ -81,7 +103,9 @@ export async function reingestGenerated(projectRoot, sourcePath, manifestId, opt
       width: null,
       height: null,
       bytes: fileStat.size,
-    }, provenance);
+    }, provenance, {
+      canon: canonLink,
+    });
 
     record.schema_version = '2.1.0';
 

package/lib/run-manifest.js

@@ -25,6 +25,20 @@
 import { createHash } from 'node:crypto';
 import { openSync, readSync, closeSync, statSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { warn } from './log.js';
+import {
+  CLEARED_SPDX_IDS,
+  resolveModelLicence,
+  isClearedLicenceEntry,
+  assertClearedPinningLicences,
+} from './model-licences.js';
+
+export {
+  CLEARED_SPDX_IDS,
+  resolveModelLicence,
+  isClearedLicenceEntry,
+  assertClearedPinningLicences,
+};
 
 /**
  * Contract version for the `pinning` block itself. Bump when the block's shape
@@ -35,6 +49,16 @@ import { join } from 'node:path';
  */
 export const PINNING_VERSION = '1.0.0';
 
+/**
+ * The ONE hash_note value that means "hashing was never attempted because
+ * --hash-models wasn't passed" — NOT a failure. buildPinning() (B07) needs
+ * to tell this apart from every other hash_note (unresolved/stat
+ * failed/read error/no filename), all of which ARE failures worth warning
+ * about. Shared as a constant so hashModelFile's own note and buildPinning's
+ * filter can never drift apart.
+ */
+const HASH_SKIPPED_NOTE = 'hash skipped (pass --hash-models)';
+
 /**
  * Seed policies — the INTENT behind seed selection, recorded alongside the
  * concrete per-item seed values so a reader knows how to regenerate.
@@ -144,17 +168,24 @@ const KIND_SUBDIRS = {
 
 /**
  * Resolve a model filename to an absolute path under the models dir. Searches
- * the kind-appropriate subdirs first, then every known subdir, then the root.
- * Returns null when nothing matches (unresolvable → sha256 null with a note).
+ * ONLY the kind-appropriate subdirs (plus the modelsDir root itself, which is
+ * kind-agnostic, not another kind's territory) — mirroring ComfyUI's own
+ * loaders, which never search across kinds (a UNETLoader never looks in
+ * checkpoints/, a VAELoader never looks in loras/, etc).
+ *
+ * SDL-M8: this used to also fall back to every OTHER kind's subdirs, so a
+ * missing unet could silently resolve to a same-named file under
+ * checkpoints/ and get pinned as though it were the unet ComfyUI actually
+ * loaded — a clean-looking wrong identity. An honest `null` (unresolved →
+ * sha256 null + a note, see hashModelFile) is the correct outcome when the
+ * kind-specific subdirs don't have the file.
+ *
+ * Returns null when nothing matches.
  */
 export function resolveModelPath(name, kind, modelsDir = defaultModelsDir()) {
   if (!name || !modelsDir) return null;
+  const subdirs = [...(KIND_SUBDIRS[kind] || []), '.'];
   const tried = new Set();
-  const subdirs = [
-    ...(KIND_SUBDIRS[kind] || []),
-    ...Object.values(KIND_SUBDIRS).flat(),
-    '.',
-  ];
   for (const sub of subdirs) {
     const candidate = join(modelsDir, sub, name);
     if (tried.has(candidate)) continue;
@@ -183,12 +214,63 @@ export function sha256File(path) {
   return 'sha256:' + hash.digest('hex');
 }
 
+// SDL-M9: a cheap partial-content fingerprint folded into the cache key
+// alongside name/size/mtime. The key used to be bare name:size:round(mtime)
+// with no content check — on a coarse-mtime mount (network shares, some
+// FAT/exFAT mounts), a same-size in-place replacement (e.g. swapping a
+// LoRA) can round to the SAME mtime as the file it replaced, so the cache
+// would silently serve the sha256 of the OLD content forever. Sampling the
+// first/last few KB — not hashing the whole multi-GB file, which would
+// defeat the point of caching — is enough to catch almost any real
+// replacement while staying cheap on every call (including cache hits).
+const SAMPLE_BYTES = 4096;
+
+/**
+ * Cheap content fingerprint: sha256 of the first + last SAMPLE_BYTES of the
+ * file (or the whole file if smaller). Synchronous, bounded I/O — a few KB
+ * regardless of file size, unlike sha256File's full-content streaming read.
+ */
+function sampleFingerprint(path, size) {
+  const fd = openSync(path, 'r');
+  try {
+    const hash = createHash('sha256');
+    const headLen = Math.min(SAMPLE_BYTES, size);
+    if (headLen > 0) {
+      const head = Buffer.allocUnsafe(headLen);
+      readSync(fd, head, 0, headLen, 0);
+      hash.update(head);
+    }
+    if (size > SAMPLE_BYTES) {
+      const tailLen = Math.min(SAMPLE_BYTES, size - headLen);
+      const tail = Buffer.allocUnsafe(tailLen);
+      readSync(fd, tail, 0, tailLen, size - tailLen);
+      hash.update(tail);
+    }
+    return hash.digest('hex').slice(0, 16);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function withLicenceFields(base, name, { licence = null, modelLicences = null } = {}) {
+  const lic = resolveModelLicence(name, licence, modelLicences);
+  return {
+    ...base,
+    licence_id: lic.licence_id,
+    licence_url: lic.licence_url,
+    date_read: lic.date_read,
+    licence: lic,
+  };
+}
+
 /**
  * Best-effort content identity for one model/LoRA file: {name, size_bytes, sha256}
  * (+ a short `hash_note` when sha256 can't be produced). size_bytes is always
  * filled when the file resolves (a cheap stat); sha256 is gated behind
- * `doHash` (the --hash-models opt-in) and cached by (name, size, mtime) so
- * multi-GB checkpoints aren't re-hashed every wave.
+ * `doHash` (the --hash-models opt-in) and cached by (name, size, mtime,
+ * partial-content sample) so multi-GB checkpoints aren't re-hashed every
+ * wave (SDL-M9: the sample is what keeps a same-size in-place replacement
+ * from reusing a stale cache entry).
  *
  * @param {string} name — model filename as it appears in the graph
  * @param {Object} [opts]
@@ -197,10 +279,10 @@ export function sha256File(path) {
  * @param {boolean} [opts.doHash=false] — compute sha256 (else record name+size only)
  * @param {{map: Map, cacheFile?: string, dirty: boolean}} [opts.cache]
  */
-export function hashModelFile(name, { kind, modelsDir = defaultModelsDir(), doHash = false, cache } = {}) {
-  if (!name) return { name: name ?? null, size_bytes: null, sha256: null, hash_note: 'no filename' };
+export function hashModelFile(name, { kind, modelsDir = defaultModelsDir(), doHash = false, cache, licence = null, modelLicences = null } = {}) {
+  if (!name) return withLicenceFields({ name: name ?? null, size_bytes: null, sha256: null, hash_note: 'no filename' }, name, { licence, modelLicences });
   const resolved = resolveModelPath(name, kind, modelsDir);
-  if (!resolved) return { name, size_bytes: null, sha256: null, hash_note: `unresolved under ${modelsDir}` };
+  if (!resolved) return withLicenceFields({ name, size_bytes: null, sha256: null, hash_note: `unresolved under ${modelsDir}` }, name, { licence, modelLicences });
   let size_bytes = null;
   let mtimeMs = 0;
   try {
@@ -208,22 +290,30 @@ export function hashModelFile(name, { kind, modelsDir = defaultModelsDir(), doHa
     size_bytes = st.size;
     mtimeMs = st.mtimeMs;
   } catch {
-    return { name, size_bytes: null, sha256: null, hash_note: 'stat failed' };
+    return withLicenceFields({ name, size_bytes: null, sha256: null, hash_note: 'stat failed' }, name, { licence, modelLicences });
+  }
+  if (!doHash) return withLicenceFields({ name, size_bytes, sha256: null, hash_note: HASH_SKIPPED_NOTE }, name, { licence, modelLicences });
+  let sample = '';
+  try {
+    sample = sampleFingerprint(resolved, size_bytes);
+  } catch {
+    // Best-effort — if sampling fails, fall back to the coarser
+    // name:size:mtime key; the sha256File() attempt below will surface any
+    // real read error anyway.
   }
-  if (!doHash) return { name, size_bytes, sha256: null, hash_note: 'hash skipped (pass --hash-models)' };
-  const key = `${name}:${size_bytes}:${Math.round(mtimeMs)}`;
-  if (cache?.map?.has(key)) return { name, size_bytes, sha256: cache.map.get(key) };
+  const key = `${name}:${size_bytes}:${Math.round(mtimeMs)}:${sample}`;
+  if (cache?.map?.has(key)) return withLicenceFields({ name, size_bytes, sha256: cache.map.get(key) }, name, { licence, modelLicences });
   let sha256;
   try {
     sha256 = sha256File(resolved);
   } catch {
-    return { name, size_bytes, sha256: null, hash_note: 'hash failed (read error)' };
+    return withLicenceFields({ name, size_bytes, sha256: null, hash_note: 'hash failed (read error)' }, name, { licence, modelLicences });
   }
   if (cache?.map) {
     cache.map.set(key, sha256);
     cache.dirty = true;
   }
-  return { name, size_bytes, sha256 };
+  return withLicenceFields({ name, size_bytes, sha256 }, name, { licence, modelLicences });
 }
 
 /**
@@ -291,18 +381,62 @@ export function flushHashCache(cache) {
  * @param {boolean} [args.hashModels=false] — opt-in sha256 of model/LoRA files
  * @param {string} [args.modelsDir]
  * @param {{map: Map, cacheFile?: string, dirty: boolean}} [args.cache]
+ * @param {Object} [args.modelLicences]
+ * @param {boolean} [args.enforceLicence=false]
+ * @param {boolean} [args.allowUnlicensedResearch=false]
  * @returns {Object} pinning block
  */
-export function buildPinning({ graph, models = {}, loras = [], seedPolicy = null, hashModels = false, modelsDir = defaultModelsDir(), cache } = {}) {
-  const opts = { modelsDir, doHash: hashModels, cache };
+export function buildPinning({
+  graph,
+  models = {},
+  loras = [],
+  seedPolicy = null,
+  hashModels = false,
+  modelsDir = defaultModelsDir(),
+  cache,
+  modelLicences = null,
+  enforceLicence = false,
+  allowUnlicensedResearch = false,
+} = {}) {
+  const opts = { modelsDir, doHash: hashModels, cache, modelLicences };
+  const modelHashes = buildModelHashes(models, opts);
+  const loraHashes = (loras || []).map((l) => ({
+    ...hashModelFile(l.name, { ...opts, kind: 'lora', licence: l.licence || null }),
+    weight: l.weight ?? 1.0,
+  }));
+
+  if (enforceLicence) {
+    assertClearedPinningLicences(modelHashes, loraHashes, { allowUnlicensedResearch });
+  }
+
+  // B07: hash_note silently encoded a hashing FAILURE (unresolved file,
+  // stat failed, read error, no filename) with nothing reading it —
+  // buildPinning() never aggregated or logged, and this file imported no
+  // logger at all. A typo'd SDLAB_MODELS_DIR produced a wave where every
+  // model has sha256: null + a note, with zero console signal — PIN_PER_STEP's
+  // whole purpose (byte-for-byte replayability) lost silently. Warn ONCE per
+  // wave with a count, but never on HASH_SKIPPED_NOTE — that note means
+  // "hashing wasn't requested" (the default, --hash-models omitted), which
+  // is expected behavior, not a failure, and would make every ordinary run
+  // noisy if it warned too.
+  const allEntries = [...Object.values(modelHashes), ...loraHashes];
+  const failed = allEntries.filter((e) => e && e.hash_note != null && e.hash_note !== HASH_SKIPPED_NOTE);
+  if (failed.length > 0) {
+    const detail = failed.map((e) => `${e.name ?? '(unnamed)'} (${e.hash_note})`).join(', ');
+    warn(`buildPinning: ${failed.length}/${allEntries.length} model(s)/lora(s) failed to hash: ${detail}`);
+  }
+
+  const ccBy4Eligible =
+    !allowUnlicensedResearch &&
+    allEntries.length > 0 &&
+    allEntries.every((entry) => isClearedLicenceEntry(entry));
+
   return {
     pinning_version: PINNING_VERSION,
     comfy_workflow_sha: comfyWorkflowSha(graph),
     seed_policy: seedPolicy,
-    models: buildModelHashes(models, opts),
-    loras: (loras || []).map((l) => ({
-      ...hashModelFile(l.name, { ...opts, kind: 'lora' }),
-      weight: l.weight ?? 1.0,
-    })),
+    cc_by_4_eligible: ccBy4Eligible,
+    models: modelHashes,
+    loras: loraHashes,
   };
 }

package/lib/run-summary.js

@@ -12,8 +12,11 @@ import { join } from 'node:path';
  * Build a summary object from a manifest.
  */
 export function buildRunSummary(manifest) {
-  const ok = manifest.outputs.filter(o => o.status === 'ok');
-  const failed = manifest.outputs.filter(o => o.status === 'error');
+  // B10: defensive default — manifest.errors two lines below already had
+  // one; a legacy/truncated manifest with no `outputs` field crashed here
+  // with a bare TypeError instead of degrading to an empty results view.
+  const ok = (manifest.outputs || []).filter(o => o.status === 'ok');
+  const failed = (manifest.outputs || []).filter(o => o.status === 'error');
   const totalElapsed = ok.reduce((sum, o) => sum + (o.elapsed_ms || 0), 0);
 
   return {
@@ -54,7 +57,7 @@ export function renderRunMarkdown(manifest) {
   lines.push('');
   lines.push(`| # | Seed | Status | File | Time |`);
   lines.push(`|---|------|--------|------|------|`);
-  for (const out of manifest.outputs) {
+  for (const out of (manifest.outputs || [])) {
     const file = out.filename || '—';
     const time = out.elapsed_ms ? `${(out.elapsed_ms / 1000).toFixed(1)}s` : '—';
     const status = out.status === 'ok' ? '✓' : out.status === 'dry_run' ? '○' : '✗';
@@ -98,8 +101,11 @@ export function renderRunMarkdown(manifest) {
  * Render a manifest to terminal text.
  */
 export function renderRunText(manifest) {
-  const ok = manifest.outputs.filter(o => o.status === 'ok' || o.status === 'dry_run');
-  const failed = manifest.outputs.filter(o => o.status === 'error');
+  // B10: same defensive default as buildRunSummary above — not explicitly
+  // named by line number in the finding, but the identical defect in the
+  // same file (this is the function `sdlab run show` calls in text mode).
+  const ok = (manifest.outputs || []).filter(o => o.status === 'ok' || o.status === 'dry_run');
+  const failed = (manifest.outputs || []).filter(o => o.status === 'error');
   const lines = [];
 
   lines.push(`Run: ${manifest.run_id}`);
@@ -111,7 +117,7 @@ export function renderRunText(manifest) {
   if (failed.length > 0) lines.push(`Errors: ${failed.length}`);
   lines.push('');
 
-  for (const out of manifest.outputs) {
+  for (const out of (manifest.outputs || [])) {
     const status = out.status === 'ok' ? '✓' : out.status === 'dry_run' ? '○' : '✗';
     const time = out.elapsed_ms ? ` (${(out.elapsed_ms / 1000).toFixed(1)}s)` : '';
     const file = out.filename ? ` → ${out.filename}` : '';

package/lib/runtime-runs.js

@@ -11,7 +11,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { randomInt } from 'node:crypto';
 import { getRunsDir, getBriefsDir } from './paths.js';
 import { inputError } from './errors.js';
-import { verbose } from './log.js';
+import { verbose, warn } from './log.js';
 
 // ─── Run ID generation ───────────────────────────────────────────
 
@@ -165,10 +165,28 @@ export async function checkpointRunManifest(runDir, manifest) {
 
 // ─── Load / List ─────────────────────────────────────────────────
 
+// SDL-H7: the only shape a run id can ever legitimately have, mirroring the
+// prefix/date/seq scheme generateRunId() builds above. Validated BEFORE the
+// id is joined into a path, so `--resume ../../../../some/dir/leftover`
+// (or any other traversal payload) never reaches existsSync/readFile. A
+// mismatch is reported as the SAME RUN_NOT_FOUND (not a distinct code)
+// because no real run can ever have an id outside this shape — the two
+// cases are indistinguishable to the caller, and this avoids leaking
+// validation internals to whoever is probing.
+const RUN_ID_RE = /^run_\d{4}-\d{2}-\d{2}_\d{3}$/;
+
 /**
  * Load a run manifest by ID.
  */
 export async function loadRun(projectRoot, runId) {
+  if (typeof runId !== 'string' || !RUN_ID_RE.test(runId)) {
+    throw inputError(
+      'RUN_NOT_FOUND',
+      `Run "${runId}" not found`,
+      `Check the run ID or run: sdlab run generate --brief <id>`
+    );
+  }
+
   const runDir = join(getRunsDir(projectRoot), runId);
   const manifestPath = join(runDir, 'manifest.json');
 
@@ -185,6 +203,15 @@ export async function loadRun(projectRoot, runId) {
 
 /**
  * List all runs in a project.
+ *
+ * B01: this used to `continue` past a directory with no readable
+ * manifest.json with zero signal — the exact shape a crashed/killed run
+ * leaves behind (see checkpointRunManifest() above). A run that ate 90
+ * minutes of GPU time before dying became invisible: no id, no `run show`,
+ * no resume, and no indication anything was ever skipped. Skipped/unreadable
+ * directories are now reported: a one-line warn() with a count always
+ * (so a human running `sdlab run list` cannot miss it), and the per-directory
+ * detail under --verbose.
  */
 export function listRuns(projectRoot) {
   const runsDir = getRunsDir(projectRoot);
@@ -195,9 +222,13 @@ export function listRuns(projectRoot) {
     .sort((a, b) => a.name.localeCompare(b.name));
 
   const runs = [];
+  const skipped = [];
   for (const entry of entries) {
     const manifestPath = join(runsDir, entry.name, 'manifest.json');
-    if (!existsSync(manifestPath)) continue;
+    if (!existsSync(manifestPath)) {
+      skipped.push({ name: entry.name, reason: 'no manifest.json' });
+      continue;
+    }
 
     try {
       const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
@@ -209,8 +240,18 @@ export function listRuns(projectRoot) {
         created_at: manifest.created_at,
         adapter_target: manifest.adapter_target,
       });
-    } catch {
-      // Skip malformed
+    } catch (err) {
+      skipped.push({ name: entry.name, reason: `unreadable manifest.json (${err.message})` });
+    }
+  }
+
+  if (skipped.length > 0) {
+    warn(
+      `listRuns: skipped ${skipped.length} run director${skipped.length === 1 ? 'y' : 'ies'} ` +
+      `with no readable manifest.json (run with --verbose for details)`
+    );
+    for (const s of skipped) {
+      verbose(`  skipped run dir "${s.name}": ${s.reason}`);
     }
   }