@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/canon-review-gate.js

@@ -0,0 +1,205 @@
+/**
+ * Review gate before canon freeze & self-verification ban (DESIGN-v3 §11.5, §12.6, G11).
+ *
+ * Enforces:
+ *   1. Model-authored canon/prompt drafts are only ever proposed (`status: "draft"`).
+ *   2. Freezing or ratifying a draft requires an explicit recorded Director accept
+ *      (`approver: "human:director"`, non-empty `reason`, and matching `draft_sha256`).
+ *   3. A model may never self-approve or be the deciding verifier of a canon
+ *      entry or prompt it wrote (`SELF_VERIFICATION_FORBIDDEN`).
+ */
+
+import { computeDraftContentSha256 } from './canon-author.js';
+import { inputError as rawInputError } from './errors.js';
+
+function inputError(code, msg) {
+  return rawInputError(code, `${code}: ${msg}`);
+}
+
+export function normalizeModelFamilyKey(modelId) {
+  if (!modelId || typeof modelId !== 'string') return '';
+  const lower = modelId
+    .trim()
+    .toLowerCase()
+    .replace(/^model:/, '')
+    .replace(/@sha256:[0-9a-f]{64}$/, '');
+  if (!lower) return '';
+  if (lower.startsWith('human:') || lower === 'human') return 'human';
+  if (lower.startsWith('rule-based:') || lower === 'rule-based') return 'rule-based';
+  if (lower.includes('glimmer') || lower.includes('muse-glimmer') || lower.includes('muse_glimmer')) {
+    return 'family:muse-glimmer-30b';
+  }
+  if (lower.includes('qwen')) {
+    return 'family:qwen';
+  }
+  if (lower.includes('gemma')) {
+    return 'family:gemma';
+  }
+  if (lower.includes('internvl') || lower.includes('caprl-internvl')) {
+    return 'family:internvl';
+  }
+  if (lower.includes('siglip') || lower === 'ai-eyes') {
+    return 'family:siglip2';
+  }
+  if (lower.includes('flux') || lower === 'ae.safetensors') {
+    return 'family:flux';
+  }
+  if (lower.includes('sd3') || lower.includes('stable-diffusion-3')) {
+    return 'family:sd3';
+  }
+  if (
+    lower.includes('sdxl') ||
+    lower.includes('stable-diffusion-xl') ||
+    lower.includes('dreamshaper') ||
+    lower.includes('juggernaut') ||
+    lower.includes('pony') ||
+    lower.includes('illustrious') ||
+    lower.includes('animagine')
+  ) {
+    return 'family:sdxl';
+  }
+  return lower;
+}
+
+/**
+ * Enforce the §12.6 self-verification ban: a model (such as Muse-Glimmer-30B)
+ * may never be the deciding reader/verifier of a canon entry or prompt it wrote.
+ *
+ * @param {Object} opts
+ * @param {string|Object} opts.authorModel
+ * @param {string|Object} opts.verifierModel
+ * @param {string} [opts.context='artifact']
+ * @returns {{ ok: true, authorFamily: string, verifierFamily: string }}
+ */
+export function assertNoSelfVerification({ authorModel, verifierModel, context = 'artifact' } = {}) {
+  const authorRaw = typeof authorModel === 'object' ? authorModel?.name : authorModel;
+  const verifierRaw = typeof verifierModel === 'object' ? verifierModel?.name : verifierModel;
+
+  const authorFamily = normalizeModelFamilyKey(authorRaw);
+  const verifierFamily = normalizeModelFamilyKey(verifierRaw);
+
+  if (
+    authorFamily &&
+    verifierFamily &&
+    authorFamily !== 'human' &&
+    verifierFamily !== 'human' &&
+    authorFamily === verifierFamily
+  ) {
+    throw inputError(
+      'SELF_VERIFICATION_FORBIDDEN',
+      `Self-verification forbidden on ${context}: verifier "${verifierRaw}" belongs to the same model family ("${verifierFamily}") as author "${authorRaw}".`
+    );
+  }
+
+  return { ok: true, authorFamily, verifierFamily };
+}
+
+/**
+ * Record an explicit Director ratification on a model-authored canon/prompt draft (G11).
+ *
+ * @param {Object} opts
+ * @param {Object} opts.draft
+ * @param {string} opts.approver — must be "human:director" (or "human:<id>")
+ * @param {string} opts.reason
+ * @param {string} [opts.at]
+ * @returns {Object} ratified draft
+ */
+export function ratifyCanonDraft({
+  draft,
+  approver,
+  reason,
+  at = new Date().toISOString(),
+} = {}) {
+  if (!draft || typeof draft !== 'object') {
+    throw inputError('CANON_DRAFT_INVALID', 'ratifyCanonDraft requires a draft object.');
+  }
+  const approverStr = String(approver || '').trim();
+  if (approverStr.startsWith('model:') || !approverStr.startsWith('human:')) {
+    throw inputError(
+      'CANON_SELF_APPROVAL_FORBIDDEN',
+      `Canon draft "${draft.class_id || draft.draft_id}" can only be ratified by a human Director ("human:director"), got "${approverStr}".`
+    );
+  }
+  const reasonStr = String(reason || '').trim();
+  if (!reasonStr) {
+    throw inputError(
+      'CANON_RATIFICATION_REASON_REQUIRED',
+      `Ratifying canon draft "${draft.class_id || draft.draft_id}" requires a non-empty reason.`
+    );
+  }
+
+  const contentSha = computeDraftContentSha256(draft);
+  return {
+    ...draft,
+    status: 'ratified',
+    judgment: 'accepted',
+    draft_sha256: contentSha,
+    ratification: {
+      status: 'accepted',
+      approver: approverStr,
+      reason: reasonStr,
+      at,
+      draft_sha256: contentSha,
+    },
+  };
+}
+
+/**
+ * Assert that a canon entry or prompt draft has been explicitly ratified by
+ * the Director before it can be frozen (G11, §11.5).
+ *
+ * Refuses:
+ *   - `status === "draft"` or missing `ratification` on a model-authored draft
+ *   - `ratification.approver` not starting with `"human:"`
+ *   - `ratification.draft_sha256` mismatch against the current draft content
+ *
+ * @param {Object} draftOrFrontmatter
+ * @returns {{ ok: true, ratification: Object|null }}
+ */
+export function assertDirectorRatifiedForFreeze(draftOrFrontmatter) {
+  if (!draftOrFrontmatter || typeof draftOrFrontmatter !== 'object') {
+    throw inputError('CANON_DRAFT_INVALID', 'Cannot verify freeze gate on empty draft/frontmatter.');
+  }
+
+  const status = draftOrFrontmatter.status || draftOrFrontmatter.draft_status || null;
+  const isModelDraft =
+    status === 'draft' ||
+    status === 'ratified' ||
+    Boolean(draftOrFrontmatter.ratification) ||
+    Boolean(draftOrFrontmatter.author_model) ||
+    Boolean(draftOrFrontmatter.drafted_by_model);
+
+  if (!isModelDraft) {
+    return { ok: true, ratification: null };
+  }
+
+  const ratification = draftOrFrontmatter.ratification;
+  if (
+    status === 'draft' ||
+    !ratification ||
+    ratification.status !== 'accepted' ||
+    typeof ratification.approver !== 'string' ||
+    !ratification.approver.startsWith('human:') ||
+    typeof ratification.reason !== 'string' ||
+    !ratification.reason.trim()
+  ) {
+    throw inputError(
+      'CANON_DRAFT_UNRATIFIED',
+      `Refusing to freeze model-authored draft "${draftOrFrontmatter.class_id || draftOrFrontmatter.id || 'unknown'}": ` +
+        'status is still "draft" or lacks an explicit human Director ratification (`approver: "human:director"`, `reason`).'
+    );
+  }
+
+  if (draftOrFrontmatter.prompt !== undefined || draftOrFrontmatter.canon_entry_draft !== undefined) {
+    const actualSha = computeDraftContentSha256(draftOrFrontmatter);
+    if (ratification.draft_sha256 !== actualSha) {
+      throw inputError(
+        'CANON_DRAFT_SHA_MISMATCH',
+        `Draft content for "${draftOrFrontmatter.class_id || draftOrFrontmatter.id}" changed after Director ratification ` +
+          `(got ${actualSha}, ratified ${ratification.draft_sha256}). Re-ratify before freezing.`
+      );
+    }
+  }
+
+  return { ok: true, ratification };
+}

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/colab-launcher-guards.js

@@ -0,0 +1,285 @@
+/**
+ * C2 Colab launcher guards (DESIGN-v3 §9.2 item 6 — lessons v4k, v4p, v4q).
+ *
+ * Implements the four required launcher guards:
+ *   1. Independent wall watcher (`evaluateWallGuard`, v4k): honours `wallS` and
+ *      `graceS` in ALL modes including `stub` mode.
+ *   2. Independent cap watcher (`evaluateCapGuard`, v4k): honours `cap` and
+ *      `margin` in ALL modes including `stub` mode (`spend = max(drop, rate * elapsed_h)`).
+ *   3. `vitals.log` parser & `DEAD HARNESS` / `STALL` watcher (`parseVitalsLog`,
+ *      `evaluateVitalsAndStallGuard`, v4p): trips `DEAD_HARNESS_TRIPPED` when 2
+ *      consecutive `phase: run` samples have 0 active worker processes, and trips
+ *      `STALL_GUARD_TRIPPED` when neither rows nor `vitals.log` advance in `stallS`.
+ *   4. Host-RAM / cgroup limit pre-load projection check & between-item fetch
+ *      (`checkHostRamProjection`, `runBetweenItemFetch`, v4q): refuses any step
+ *      whose projected anonymous host RAM (`projectedMb * 1.05 > limitMb`) would
+ *      trigger a kernel SIGKILL (`rc=-9`), and copies completed artifacts listed
+ *      in `current.json` before `current.json` is overwritten for the next item.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { inputError as rawInputError } from './errors.js';
+
+function inputError(code, msg) {
+  return rawInputError(code, `${code}: ${msg}`);
+}
+
+const WORKER_PROC_RE = /\b(comfy|main\.py|ai-toolkit|run\.py|llama-server|ollama|lane1_render\.py)\b/i;
+
+/**
+ * 1. Independent wall-clock watcher (v4k).
+ * Never disabled in `stub` mode: trips when `elapsedS >= wallS - graceS`.
+ *
+ * @param {Object} opts
+ * @param {string} [opts.mode='live']
+ * @param {number} opts.elapsedS
+ * @param {number} [opts.wallS=3000]
+ * @param {number} [opts.graceS=60]
+ * @returns {{ mode: string, tripped: boolean, code: string|null, remainingS: number, thresholdS: number }}
+ */
+export function evaluateWallGuard({
+  mode = 'live',
+  elapsedS,
+  wallS = 3000,
+  graceS = 60,
+} = {}) {
+  const thresholdS = Math.max(0, Number(wallS) - Number(graceS));
+  const remainingS = thresholdS - Number(elapsedS);
+  const tripped = Number(elapsedS) >= thresholdS;
+  return {
+    mode,
+    tripped,
+    code: tripped ? 'WALL_GUARD_TRIPPED' : null,
+    remainingS,
+    thresholdS,
+  };
+}
+
+/**
+ * 2. Independent CCU spend cap watcher (v4k).
+ * Never disabled in `stub` mode: computes `spend = max(startBalance - currentBalance, rateCcuPerHour * elapsedH)`
+ * and trips when `spend >= cap - margin`.
+ *
+ * @param {Object} opts
+ * @param {string} [opts.mode='live']
+ * @param {number} [opts.cap=0.05]
+ * @param {number} [opts.margin=0.01]
+ * @param {number|null} [opts.startBalance=null]
+ * @param {number|null} [opts.currentBalance=null]
+ * @param {number} [opts.rateCcuPerHour=0]
+ * @param {number} [opts.elapsedS=0]
+ * @returns {{ mode: string, tripped: boolean, code: string|null, spendCcu: number, ceilingCcu: number }}
+ */
+export function evaluateCapGuard({
+  mode = 'live',
+  cap = 0.05,
+  margin = 0.01,
+  startBalance = null,
+  currentBalance = null,
+  rateCcuPerHour = 0,
+  elapsedS = 0,
+} = {}) {
+  const balanceDrop =
+    startBalance !== null && currentBalance !== null
+      ? Math.max(0, Number(startBalance) - Number(currentBalance))
+      : 0;
+  const rateEst = Math.max(0, (Number(rateCcuPerHour) * Number(elapsedS)) / 3600);
+  const spendCcu = Math.max(balanceDrop, rateEst);
+  const ceilingCcu = Math.max(0, Number(cap) - Number(margin));
+  const tripped = spendCcu >= ceilingCcu;
+  return {
+    mode,
+    tripped,
+    code: tripped ? 'CAP_GUARD_TRIPPED' : null,
+    spendCcu: Number(spendCcu.toFixed(6)),
+    ceilingCcu: Number(ceilingCcu.toFixed(6)),
+  };
+}
+
+/**
+ * Parse `vitals.log` blocks (`=== VITALS <iso> ===`) emitted by the VM vitals sampler (v4p).
+ *
+ * @param {string} vitalsText
+ * @returns {Array<{ timestamp: string, phase: string|null, workerProcCount: number, rawBlock: string }>}
+ */
+export function parseVitalsLog(vitalsText = '') {
+  const blocks = String(vitalsText)
+    .split(/^===\s*VITALS\s+/m)
+    .map((b) => b.trim())
+    .filter(Boolean);
+
+  const samples = [];
+  for (const block of blocks) {
+    const lines = block.split(/\r?\n/);
+    const header = lines[0] || '';
+    const tsMatch = /^([^\s=]+)/.exec(header);
+    const timestamp = tsMatch ? tsMatch[1] : '';
+
+    let phase = null;
+    let workerProcCount = 0;
+    let inProc = false;
+
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.startsWith('PROC:')) {
+        inProc = true;
+        continue;
+      }
+      if (line.startsWith('HARNESS:')) {
+        inProc = false;
+        const payload = line.slice('HARNESS:'.length).trim();
+        try {
+          const parsed = JSON.parse(payload);
+          phase = parsed.phase || null;
+        } catch {
+          const m = /"phase"\s*:\s*"([^"]+)"/.exec(payload) || /phase:\s*([a-z0-9_-]+)/i.exec(payload);
+          phase = m ? m[1] : null;
+        }
+        continue;
+      }
+      if (inProc && WORKER_PROC_RE.test(line)) {
+        workerProcCount++;
+      }
+    }
+
+    samples.push({
+      timestamp,
+      phase,
+      workerProcCount,
+      rawBlock: block,
+    });
+  }
+  return samples;
+}
+
+/**
+ * 3. Evaluate the `DEAD HARNESS` and `STALL` watcher over `vitals.log` + idle timer (v4p).
+ *
+ * Trips `DEAD_HARNESS_TRIPPED` when the last 2 vitals samples both show
+ * `phase === 'run'` (or `phase.startsWith('run')`) and `workerProcCount === 0`.
+ * Otherwise trips `STALL_GUARD_TRIPPED` when `idleSeconds >= stallS`.
+ *
+ * @param {Object} opts
+ * @param {string} opts.vitalsText
+ * @param {number} [opts.idleSeconds=0]
+ * @param {number} [opts.stallS=300]
+ * @returns {{ tripped: boolean, code: string|null, reason: string|null, samplesCount: number }}
+ */
+export function evaluateVitalsAndStallGuard({
+  vitalsText = '',
+  idleSeconds = 0,
+  stallS = 300,
+} = {}) {
+  const samples = parseVitalsLog(vitalsText);
+  if (samples.length >= 2) {
+    const lastTwo = samples.slice(-2);
+    const bothDeadInRun = lastTwo.every(
+      (s) => typeof s.phase === 'string' && s.phase.startsWith('run') && s.workerProcCount === 0
+    );
+    if (bothDeadInRun) {
+      return {
+        tripped: true,
+        code: 'DEAD_HARNESS_TRIPPED',
+        reason: '2 consecutive vitals samples in phase=run with 0 active worker processes',
+        samplesCount: samples.length,
+      };
+    }
+  }
+
+  if (Number(idleSeconds) >= Number(stallS)) {
+    return {
+      tripped: true,
+      code: 'STALL_GUARD_TRIPPED',
+      reason: `No output row or vitals progress for ${idleSeconds}s (stallS=${stallS}s)`,
+      samplesCount: samples.length,
+    };
+  }
+
+  return {
+    tripped: false,
+    code: null,
+    reason: null,
+    samplesCount: samples.length,
+  };
+}
+
+/**
+ * 4a. Host-RAM / cgroup limit pre-load projection check (v4q).
+ * Refuses any step whose projected anonymous host RAM (`(currentAnonMb + projectedDeltaMb) * safetyFactor`)
+ * exceeds `min(memTotalMb, cgroupMaxMb)`.
+ *
+ * @param {Object} opts
+ * @param {number} opts.currentAnonMb
+ * @param {number} opts.projectedDeltaMb
+ * @param {number} opts.memTotalMb
+ * @param {number|null} [opts.cgroupMaxMb=null]
+ * @param {number} [opts.safetyFactor=1.05]
+ * @returns {{ ok: true, projectedMb: number, limitMb: number }}
+ */
+export function checkHostRamProjection({
+  currentAnonMb,
+  projectedDeltaMb,
+  memTotalMb,
+  cgroupMaxMb = null,
+  safetyFactor = 1.05,
+}) {
+  const limits = [Number(memTotalMb)];
+  if (cgroupMaxMb !== null && cgroupMaxMb !== undefined && Number.isFinite(Number(cgroupMaxMb))) {
+    limits.push(Number(cgroupMaxMb));
+  }
+  const limitMb = Math.min(...limits);
+  const rawProjected = Number(currentAnonMb) + Number(projectedDeltaMb);
+  const projectedWithMargin = rawProjected * Number(safetyFactor);
+
+  if (projectedWithMargin > limitMb) {
+    throw inputError(
+      'HOST_RAM_PROJECTION_EXCEEDED',
+      `Projected anonymous host RAM ${projectedWithMargin.toFixed(1)} MB (${rawProjected} MB * ${safetyFactor}) exceeds host/cgroup ceiling ${limitMb} MB (v4q guard against kernel SIGKILL rc=-9).`
+    );
+  }
+
+  return {
+    ok: true,
+    projectedMb: Number(projectedWithMargin.toFixed(1)),
+    limitMb,
+  };
+}
+
+/**
+ * 4b. Between-item fetch (v4q): copies every completed file listed in `current.json`
+ * from `remoteDir` to `localDir` BEFORE `current.json` is overwritten for `nextItem`.
+ *
+ * @param {Object} opts
+ * @param {string} opts.remoteDir
+ * @param {string} opts.localDir
+ * @param {Object|null} [opts.nextItem=null]
+ * @returns {{ copiedFiles: string[], previousItem: Object|null }}
+ */
+export function runBetweenItemFetch({ remoteDir, localDir, nextItem = null }) {
+  mkdirSync(localDir, { recursive: true });
+  const currentJsonPath = join(remoteDir, 'current.json');
+  const copiedFiles = [];
+  let previousItem = null;
+
+  if (existsSync(currentJsonPath)) {
+    previousItem = JSON.parse(readFileSync(currentJsonPath, 'utf-8'));
+    const files = Array.isArray(previousItem?.files) ? previousItem.files : [];
+    for (const relFile of files) {
+      const src = join(remoteDir, relFile);
+      if (existsSync(src)) {
+        const dst = join(localDir, relFile);
+        mkdirSync(join(dst, '..'), { recursive: true });
+        copyFileSync(src, dst);
+        copiedFiles.push(relFile);
+      }
+    }
+    copyFileSync(currentJsonPath, join(localDir, 'current.json'));
+  }
+
+  if (nextItem) {
+    writeFileSync(currentJsonPath, JSON.stringify(nextItem, null, 2) + '\n', 'utf-8');
+  }
+
+  return { copiedFiles, previousItem };
+}