@nextcommerce/campaigns-os 1.54.0 → 1.57.0

package/src/doctor/next-step.mjs

@@ -1,9 +1,9 @@
 // The next step doctor recommends, and the gate issues `next` reads from doctor.
 import { campaignIdentitiesMatch } from "../spec-source-identity.mjs";
-import { CARRIED_FORWARD } from "../local-preview-policy.mjs";
+import { NO_CAPTURABLE_ROUTES_CODE, hostedTemplateNeedsUsablePreview, polishCarriedForwardForLadder, polishGateCanCarryPreview } from "../local-preview-policy.mjs";
 import { resolve } from "node:path";
 import { orderPathDepthDriftText } from "../proof-policy.mjs";
-import { anyAssemblyReportStageBlocked } from "../stage-ledger.mjs";
+import { anyAssemblyReportStageBlocked, qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "../stage-ledger.mjs";
 import {
   SOURCE_PREP_DOCUMENT_WRAPPER,
   SOURCE_PREP_FRONTMATTER_RESIDUE,
@@ -16,9 +16,10 @@ import {
   stageIsBlocked,
   stageIsTerminal,
 } from "../orchestration-stage-contract.mjs";
-import { evaluatePolishGate } from "../polish-gate.mjs";
+import { currentBuildFingerprint, evaluatePolishGate } from "../polish-gate.mjs";
 import { effectiveStageStatus, effectiveStatusIsTerminal } from "../input-currency.mjs";
 import { cmd } from "../install-invocation.mjs";
+import { shellToken } from "../shell-token.mjs";
 import { isObject, isNonEmptyString, optionalString, resolveFromFile, addIssue, filesystemPathsMatch } from "../cli-helpers.mjs";
 import { orderPathDepthDrift } from "./checks.mjs";
 
@@ -412,7 +413,7 @@ export function assessPurchaseProofCoverage({ packet = null, report = null } = {
   };
 }
 
-function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate, purchaseProof = null) {
+function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate, purchaseProof = null, packet = null) {
   const polishGate = derived?.polish_gate || evaluatePolishGate({ report });
   const polishCheckpointGate = derived?.polish_checkpoint_gate || null;
   // prepare-build is the earliest lifecycle prerequisite. Surface its
@@ -473,9 +474,15 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
   }
 
   for (const cliStage of NEXT_STAGE_ORDER) {
-    // On the local preview, missing polish is carried forward as a warning
-    // (local-preview-policy.mjs): the ladder moves on to deploy and QA.
-    if (cliStage === "polish" && polishGate.status === CARRIED_FORWARD) continue;
+    // A first local preview may carry missing Polish forward. A theme waiver
+    // or prior capture makes the recorded Polish stage owed again.
+    if (cliStage === "polish" && polishCarriedForwardForLadder(report, polishGate)) continue;
+    // A hosted all-template preview has no hosted deploy recorder. The
+    // recorded preview URL satisfies this one deploy handoff while the
+    // carried-forward gate identifies the exact preview-only shape.
+    if (cliStage === "deploy" && packet?.deploy?.preview_url
+      && polishGate?.carried_forward?.policy === "hosted_template_preview"
+      && polishCheckpointGate?.carried_forward?.policy === "hosted_template_preview") continue;
     const reportKey = reportKeyForCliStage(cliStage);
     const stage = report.stages[reportKey];
     if (!stage) {
@@ -500,6 +507,10 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
         reason: `Stage "${reportKey}" has status "${status || "(unset)"}"; run "${cliStage}" next.`,
       };
     }
+    if (cliStage === "qa" && qaRecordedBuildFingerprint(report) && currentBuildFingerprint(report)
+      && !qaRecordedForCurrentBuild(report, currentBuildFingerprint(report))) {
+      return { stage: "qa", reason: "QA was recorded for a different build; run QA against the current build." };
+    }
     // A terminal QA status is not the same claim as purchase proof. QA finalizes
     // a verdict and records a terminal status even when no order path ran, so a
     // `--test-order off` diagnostic used to carry the pipeline to "done" against
@@ -513,9 +524,13 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
     }
   }
 
+  const hostedPreview = Boolean(packet?.deploy?.preview_url && polishGate?.carried_forward?.policy === "hosted_template_preview");
   return {
     stage: "done",
-    reason: "All stages are in a terminal status (completed / completed_with_warnings / skipped). Pipeline is complete.",
+    outcome: hostedPreview ? "hosted_preview_satisfies_deploy" : "standard_closeout",
+    reason: hostedPreview
+      ? "The recorded hosted preview satisfies deploy, and QA is terminal for the current build. Pipeline is complete."
+      : "All stages are in a terminal status (completed / completed_with_warnings / skipped). Pipeline is complete.",
   };
 }
 
@@ -573,7 +588,7 @@ export const DOCTOR_NEXT_STAGE_OWNERS = NEXT_STAGE_OWNERS;
 // The code -> action strings doctor prints under `Next:`. They describe the
 // repairs the findings ask for and are independent of which stage the picker
 // names, so they survive the picker consolidation unchanged.
-function doctorNextActions(errors, warnings, derived, { polishBlocked, polishGate, polishCheckpointGate, packetRef = derived.packet_path || "<packet>" }) {
+function doctorNextActions(errors, warnings, derived, { polishBlocked, polishGate, polishCheckpointGate, packet = null, packetRef = derived.packet_path || "<packet>" }) {
   const codes = new Set([...errors, ...warnings].map((issue) => issue.code));
   const onlyPolishErrors = doctorErrorsAreOnlyPolishGate(errors);
   const actions = [];
@@ -629,11 +644,17 @@ function doctorNextActions(errors, warnings, derived, { polishBlocked, polishGat
     actions.push(`Target campaign output directory is missing; run ${cmd("next")} setup --packet ${packetRef} before build.`);
   }
   if (polishBlocked) {
-    if (polishGate.status === "blocked") {
+    const needsHostedPreview = hostedTemplateNeedsUsablePreview(packet, polishCheckpointGate);
+    if (needsHostedPreview) {
+      actions.push(`Every mapped page is template stock and needs a hosted preview URL that differs from the production URL. Run ${cmd("qa")} policy set --packet ${packetRef} --preview-url <url>, then run ${cmd("next")} --packet ${packetRef}.`);
+    }
+    if (polishGate.status === "blocked" && (!needsHostedPreview || !polishGateCanCarryPreview(polishGate))) {
       actions.push(`${polishGate.reason} Run next-campaigns-polish and record structured evidence before deploy/QA handoff.`);
     }
-    if (polishCheckpointGate?.status === "blocked") {
-      actions.push(`${polishCheckpointGate.reason} Run ${cmd("polish")} capture before marking Polish complete.`);
+    if (polishCheckpointGate?.status === "blocked" && !needsHostedPreview) {
+      actions.push(polishCheckpointGate.code === NO_CAPTURABLE_ROUTES_CODE
+        ? `${polishCheckpointGate.reason} ${polishCheckpointGate.required_actions?.[0]?.description || "Map a design route and rerun intake before QA."}`
+        : `${polishCheckpointGate.reason} Run ${cmd("polish")} capture before marking Polish complete.`);
     }
   }
   return actions;
@@ -652,7 +673,7 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
     && (polishGate.status === "blocked" || polishCheckpointGate?.status === "blocked");
   const codes = new Set([...errors, ...warnings].map((issue) => issue.code));
   const purchaseProof = report ? assessPurchaseProofCoverage({ packet, report }) : null;
-  const picked = pickNextStage(report, { errors, derived }, prepareBuildGate, purchaseProof);
+  const picked = pickNextStage(report, { errors, derived }, prepareBuildGate, purchaseProof, packet);
   // The picker's vocabulary and this table must not drift apart: a stage the
   // table does not know would otherwise be relabelled as an operator step and
   // sliced into the whole ladder. Fail loudly instead.
@@ -661,8 +682,8 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
   }
   // An explicit --context / --report is carried into every recommended
   // command, so a recovery reads the same artifacts the recommendation did.
-  const packetRef = `${derived.packet_path || "<packet>"}${sidecarArgs}`;
-  const actions = doctorNextActions(errors, warnings, derived, { polishBlocked, polishGate, polishCheckpointGate, packetRef });
+  const packetRef = `${derived.packet_path ? shellToken(derived.packet_path) : "<packet>"}${sidecarArgs}`;
+  const actions = doctorNextActions(errors, warnings, derived, { polishBlocked, polishGate, polishCheckpointGate, packet, packetRef });
   const deployStatus = String(report?.stages?.deploy?.status || "");
   const deploySatisfied = ["completed", "completed_with_warnings", "ready_with_exceptions"].some((prefix) => deployStatus.startsWith(prefix))
     || Boolean(deployUrlFromReportOutputs(report));
@@ -709,8 +730,16 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
       ? `${cmd("next")} --packet ${packetRef}`
       : `${cmd("next")} ${picked.stage} --packet ${packetRef}`;
   const fallbackAction = picked.stage === "done"
-    ? `All stages are recorded as terminal; run ${cmd("next")} to confirm the closeout actions.`
+    ? (picked.outcome === "hosted_preview_satisfies_deploy"
+      ? `${picked.reason} Run ${cmd("next")} to confirm the closeout actions.`
+      : `All stages are recorded as terminal; run ${cmd("next")} to confirm the closeout actions.`)
     : `Run ${command}.`;
+  if (picked.stage === "done") {
+    actions.unshift(fallbackAction);
+    if (report?.stages?.qa?.status === "completed_with_warnings") {
+      actions.push("QA passed with exceptions. Report them to the operator; do not clear or waive them, or change markup just to make them pass.");
+    }
+  }
   return {
     stage: picked.stage,
     status: blocked ? "blocked" : readinessStatus(warnings, derived),
@@ -723,6 +752,7 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
     default_skill: owners.default_skill,
     command,
     reason: picked.reason,
+    ...(picked.outcome ? { outcome: picked.outcome } : {}),
     actions: actions.length ? actions : [fallbackAction],
     // Gate-blocked stages stay listed even when the recommended stage is
     // runnable (a Design Source Package change after assembly names build,

package/src/doctor-sidecar.mjs

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { portableArtifactPaths } from "./cli-helpers.mjs";
 
 export const DOCTOR_SIDECAR_REL_PATH = ".campaign-runtime/doctor-output.json";
 export const DOCTOR_SIDECAR_SCHEMA = "campaigns-os-doctor-output/v0";
@@ -61,8 +62,9 @@ export function stampDoctorProducer(doctor, command) {
 // through this (or through `stampDoctorProducer` when its own transactional
 // writer must do the rename), so `generated_by` cannot be skipped by one of
 // them the way #327's cause labels once were.
-export function writeDoctorSidecar(path, doctor, { command } = {}) {
-  writeJsonAtomic(path, stampDoctorProducer(doctor, command));
+export function writeDoctorSidecar(path, doctor, { command, targetRepo = null } = {}) {
+  const stamped = stampDoctorProducer(doctor, command);
+  writeJsonAtomic(path, targetRepo ? portableArtifactPaths(stamped, targetRepo) : stamped);
   return path;
 }
 
@@ -89,7 +91,7 @@ export function markDoctorSidecarStale(targetBaseDir, { command = null, reason =
     stale_reason: reason
       || "A later command changed doctor inputs after this snapshot was written. Re-run campaigns-os doctor (or campaigns-os next) for current state.",
   };
-  writeJsonAtomic(path, stamped);
+  writeJsonAtomic(path, portableArtifactPaths(stamped, targetBaseDir));
   return path;
 }
 

package/src/gate-actions.mjs

@@ -68,10 +68,30 @@ export const HIDDEN_EAGER_MEDIA_ACTIONS = Object.freeze({
     id: "polish.hidden_eager_media.map_design_route",
     kind: "manual",
     command: null,
-    description: "Every mapped page is template stock, so polish capture has nothing to measure. Map at least one page to its design source HTML (source_html.pages[].path) and rerun intake, or prove the campaign on the local preview (deploy.target local-serve served from localhost), where this missing evidence is carried forward as a warning.",
+    description: "Every mapped page is template stock, so there is no design route to measure. Map at least one page to its design source HTML (source_html.pages[].path) and rerun intake, or use a local or hosted preview for QA with the missing evidence carried forward as a warning.",
   }),
 });
 
+export function qaRunCommand(packetPath, url, bumpCart = null) {
+  return `${invocationPrefixFor(PACKAGE_ROOT)} qa run --packet ${packetPath ? shellToken(packetPath) : "<packet>"} --base-url ${url === "<preview-url>" ? url : shellToken(url)} --browser --test-order common${bumpCart ? ` --cart ${shellToken(bumpCart.cart)}` : ""}`;
+}
+
+export function hostedTemplateQaAction(previewUrl) {
+  return {
+    id: "polish.hidden_eager_media.hosted_preview_qa",
+    kind: "command",
+    command: qaRunCommand(null, previewUrl),
+    description: "Run QA against the packet's hosted preview URL; missing Polish evidence remains a warning.",
+  };
+}
+
+export const HOSTED_TEMPLATE_PREVIEW_URL_ACTION = Object.freeze({
+  id: "polish.hidden_eager_media.set_hosted_preview_url",
+  kind: "command",
+  command: "campaigns-os qa policy set --packet <packet> --preview-url <url>",
+  description: "Record a hosted preview URL that differs from the production URL with qa policy set, then run next again; missing Polish evidence can be carried forward on that preview.",
+});
+
 const PACKET_PLACEHOLDER = "--packet <packet>";
 
 // The placeholder becomes the packet this run read, shell-quoted, so the

package/src/input-refresh.mjs

@@ -26,7 +26,7 @@ import {
   loadCampaignBuildBriefFile,
 } from "./build-brief.mjs";
 import { resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
-import { isObject, optionalString, relFromDir, resolveFromFile } from "./cli-helpers.mjs";
+import { isObject, optionalString, portableArtifactPaths, relFromDir, resolveFromFile } from "./cli-helpers.mjs";
 import { writeJsonAtomic } from "./doctor-sidecar.mjs";
 import { activeSpecPages, specIdentityMismatch } from "./doctor/checks.mjs";
 import {
@@ -475,9 +475,9 @@ function saveBriefUnderLock({ packetPath, explicitBrief, sidecars, lockedTarget,
     if (!dryRun) {
       // Intake's publication order, the report last: a failure between files
       // leaves the report bound to the old material, which reads as owed.
-      writeJsonAtomic(packetPath, nextPacket);
-      writeJsonAtomic(normalizedPath, buildBrief.artifact);
-      writeJsonAtomic(contextPath, saved.nextContext);
+      writeJsonAtomic(packetPath, portableArtifactPaths(nextPacket, targetRepo, { artifactPath: packetPath }));
+      writeJsonAtomic(normalizedPath, portableArtifactPaths(buildBrief.artifact, targetRepo, { artifactPath: normalizedPath }));
+      writeJsonAtomic(contextPath, portableArtifactPaths(saved.nextContext, targetRepo, { artifactPath: contextPath }));
       commitAssemblyReport(workspace, () => nextReport, {
         command: "record brief",
         staleReason: "The Campaign Build Brief was saved after this doctor snapshot. Re-run doctor (or next) for current state.",
@@ -674,8 +674,8 @@ function refreshSpecUnderLock({ packetPath, sidecars, lockedTarget, dryRun, time
     if (!dryRun) {
       // Intake's publication order, the report last: a failure between files
       // leaves the report bound to the old spec material, which reads as owed.
-      if (briefWritten) writeJsonAtomic(normalizedPath, brief.buildBrief.artifact);
-      writeJsonAtomic(contextPath, nextContext);
+      if (briefWritten) writeJsonAtomic(normalizedPath, portableArtifactPaths(brief.buildBrief.artifact, targetRepo, { artifactPath: normalizedPath }));
+      writeJsonAtomic(contextPath, portableArtifactPaths(nextContext, targetRepo, { artifactPath: contextPath }));
       commitAssemblyReport(workspace, () => nextReport, {
         command: "record spec",
         staleReason: "The CampaignSpec was bound with record spec after this doctor snapshot. Re-run doctor (or next) for current state.",

package/src/invocation.mjs

@@ -132,14 +132,15 @@ export function resolveInvocationPolicy(command, args) {
   const steps = CLASS_STEPS[rule.class];
   const noWrite = args["no-write"] === true;
   const implementsDryRun = rule.dryRun === true;
-  const sweepSuppressed = optsOutOfRunSession(args) || noWrite || (Object.hasOwn(args, "dry-run") && implementsDryRun);
+  const help = Boolean(args.help);
+  const sweepSuppressed = help || optsOutOfRunSession(args) || noWrite || (Object.hasOwn(args, "dry-run") && implementsDryRun);
   const inspection = Boolean(rule.journalExemptWhen && args[rule.journalExemptWhen.given] && args[rule.journalExemptWhen.unlessBare] !== true);
   return Object.freeze({
     class: rule.class,
     wrapper: steps.includes("wrapper"), ambient: steps.includes("ambient"),
     sweepRoot: steps.includes("sweep") && !sweepSuppressed ? rule.sweepRoot || null : null,
-    journalExempt: !steps.includes("journal") || rule.journalExempt === true || noWrite || (args["dry-run"] === true && implementsDryRun) || inspection,
-    implementsDryRun, autoEnd: rule.autoEnd === true,
+    journalExempt: help || !steps.includes("journal") || rule.journalExempt === true || noWrite || (args["dry-run"] === true && implementsDryRun) || inspection,
+    implementsDryRun, autoEnd: !help && rule.autoEnd === true,
   });
 }
 

package/src/lifecycle.mjs

@@ -66,6 +66,7 @@ export const LIFECYCLE_JOURNAL_REL_PATH = ".campaign-runtime/command-lifecycle.j
 // from anywhere.
 export const REFUSED_INVOCATION = "refused_invocation";
 const refusalScope = new AsyncLocalStorage();
+const invocationScope = new AsyncLocalStorage();
 
 /** Run `fn` with its own refusal verdict. Returns whatever `fn` returns. */
 export function runWithRefusalScope(fn) {
@@ -96,6 +97,14 @@ export function refusalSeen() {
   return refusalScope.getStore()?.seen === true;
 }
 
+// Prompt sites share this hook. Nested prompts count only the outer blocked
+// interval, so a prompt helper can call another without inflating wait time.
+export async function timeOperatorWait(fn) {
+  const active = invocationScope.getStore();
+  if (!active) return fn();
+  return active.wait(fn);
+}
+
 /**
  * Run `fn()` and re-throw anything it throws as a tagged refusal, message
  * byte-identical. The contract it encodes: THE TAG IS APPLIED AT THE UP-FRONT
@@ -123,6 +132,10 @@ function isStringArray(value) {
   return Array.isArray(value) && value.every((entry) => typeof entry === "string");
 }
 
+function isFindingCodes(value) {
+  return isStringArray(value) && value.length <= 5 && new Set(value).size === value.length;
+}
+
 // Injectable so tests are deterministic. `now` is wall-clock (ISO source);
 // `monotonic` is a steadily-increasing millisecond counter for durations.
 const defaultClock = {
@@ -146,13 +159,22 @@ function defaultReadExitStatus() {
 export function createLifecycleRecorder(clock = defaultClock) {
   const stages = [];
   let repairLoopCount = 0;
+  let waitMs = 0;
+  let waitDepth = 0;
+  const activeStages = [];
+  const findingCodes = [];
   function stage(name) {
     const t0 = clock.monotonic();
+    const phase = { name: String(name), wait_ms: 0 };
+    activeStages.push(phase);
     let stopped = false;
     return function stop() {
       if (stopped) return;
       stopped = true;
-      stages.push({ name: String(name), duration_ms: Math.max(0, Math.round(clock.monotonic() - t0)) });
+      activeStages.splice(activeStages.indexOf(phase), 1);
+      // Wait accumulates unrounded and is rounded once here, so it never
+      // exceeds the stage's own rounded duration.
+      stages.push({ ...phase, wait_ms: Math.round(phase.wait_ms), duration_ms: Math.max(0, Math.round(clock.monotonic() - t0)) });
     };
   }
   // Convenience: time `fn` as a named sub-phase. Records the stage even if fn
@@ -168,11 +190,38 @@ export function createLifecycleRecorder(clock = defaultClock) {
   return {
     stage,
     time,
+    async wait(fn) {
+      if (waitDepth++) {
+        try { return await fn(); } finally { waitDepth -= 1; }
+      }
+      const t0 = clock.monotonic();
+      const phase = activeStages.at(-1);
+      try { return await fn(); }
+      finally {
+        const elapsed = Math.max(0, clock.monotonic() - t0);
+        waitMs += elapsed;
+        if (phase) phase.wait_ms += elapsed;
+        waitDepth -= 1;
+      }
+    },
+    recordFindingCodes(codes) {
+      // Codes attach to the phase active when they are recorded; outside any
+      // phase they stay invocation-level only.
+      const phase = activeStages.at(-1);
+      for (const code of Array.isArray(codes) ? codes : []) {
+        if (typeof code !== "string") continue;
+        if (!findingCodes.includes(code) && findingCodes.length < 5) findingCodes.push(code);
+        if (phase) {
+          phase.finding_codes ??= [];
+          if (!phase.finding_codes.includes(code) && phase.finding_codes.length < 5) phase.finding_codes.push(code);
+        }
+      }
+    },
     recordRepairLoop() {
       repairLoopCount += 1;
     },
     snapshot() {
-      return { stages: stages.slice(), repair_loop_count: repairLoopCount };
+      return { stages: stages.slice(), repair_loop_count: repairLoopCount, wait_ms: Math.round(waitMs), finding_codes: findingCodes.slice() };
     },
   };
 }
@@ -183,7 +232,9 @@ export const NOOP_RECORDER = {
   stage: () => () => {},
   time: async (_name, fn) => fn(),
   recordRepairLoop: () => {},
-  snapshot: () => ({ stages: [], repair_loop_count: 0 }),
+  wait: (fn) => fn(),
+  recordFindingCodes: () => {},
+  snapshot: () => ({ stages: [], repair_loop_count: 0, wait_ms: 0, finding_codes: [] }),
 };
 
 function buildLifecycle({ command, argvShape, runId, exitStatus, startedAt, completedAt, durationMs, recorder }) {
@@ -197,7 +248,10 @@ function buildLifecycle({ command, argvShape, runId, exitStatus, startedAt, comp
     started_at: startedAt,
     completed_at: completedAt,
     duration_ms: Number.isFinite(durationMs) ? Math.max(0, Math.round(durationMs)) : null,
-    stages: recorded.stages,
+    wait_ms: recorded.wait_ms,
+    ...(Number.isInteger(exitStatus) && exitStatus !== 0 && recorded.finding_codes.length ? { finding_codes: recorded.finding_codes } : {}),
+    stages: recorded.stages.map(({ finding_codes, ...stage }) =>
+      Number.isInteger(exitStatus) && exitStatus !== 0 && finding_codes?.length ? { ...stage, finding_codes } : stage),
     repair_loop_count: recorded.repair_loop_count,
   };
 }
@@ -225,7 +279,7 @@ export async function withCommandLifecycle({
   let thrown = null;
   let exitStatus = 0;
   try {
-    result = await fn(recorder);
+    result = await invocationScope.run(recorder, () => fn(recorder));
     // A clean return is exit 0 unless the command set process.exitCode.
     const raw = readExitStatus();
     exitStatus = Number.isInteger(raw) ? raw : 0;
@@ -278,6 +332,8 @@ export function validateLifecycle(entry) {
   if (entry.exit_status != null && !Number.isInteger(entry.exit_status)) add("lifecycle.exit_status", "exit_status must be an integer or null.");
   if (entry.run_id != null && typeof entry.run_id !== "string") add("lifecycle.run_id", "run_id must be a string or null.");
   if (entry.duration_ms != null && typeof entry.duration_ms !== "number") add("lifecycle.duration_ms", "duration_ms must be a number or null.");
+  if (entry.wait_ms != null && (!Number.isInteger(entry.wait_ms) || entry.wait_ms < 0)) add("lifecycle.wait_ms", "wait_ms must be a non-negative integer or null.");
+  if (entry.finding_codes !== undefined && (!isFindingCodes(entry.finding_codes) || !Number.isInteger(entry.exit_status) || entry.exit_status === 0)) add("lifecycle.finding_codes", "finding_codes must have at most five distinct strings and require a non-zero exit_status.");
   if (entry.repair_loop_count != null && !Number.isInteger(entry.repair_loop_count)) add("lifecycle.repair_loop_count", "repair_loop_count must be an integer.");
   if (entry.stages != null) {
     if (!Array.isArray(entry.stages)) {
@@ -285,7 +341,11 @@ export function validateLifecycle(entry) {
     } else {
       entry.stages.forEach((stage, index) => {
         if (!stage || typeof stage !== "object" || Array.isArray(stage)) add(`lifecycle.stages[${index}]`, "each stage must be an object.");
-        else if (!isNonEmptyString(stage.name)) add(`lifecycle.stages[${index}].name`, "stage name is required.");
+        else {
+          if (!isNonEmptyString(stage.name)) add(`lifecycle.stages[${index}].name`, "stage name is required.");
+          if (stage.wait_ms != null && (!Number.isInteger(stage.wait_ms) || stage.wait_ms < 0)) add(`lifecycle.stages[${index}].wait_ms`, "wait_ms must be a non-negative integer or null.");
+          if (stage.finding_codes !== undefined && (!isFindingCodes(stage.finding_codes) || !Number.isInteger(entry.exit_status) || entry.exit_status === 0)) add(`lifecycle.stages[${index}].finding_codes`, "finding_codes must have at most five distinct strings and require a non-zero exit_status.");
+        }
       });
     }
   }
@@ -366,6 +426,8 @@ export function aggregateLifecycleForRun(journal, runId, { excludeCommands = []
   let latest = null;
   let durationSum = 0;
   let explicitRepairLoops = 0;
+  let needsInputCount = 0;
+  let failureCount = 0;
 
   // Only finite, parseable ISO timestamps participate in span timing; a junk
   // string (e.g. a hand-edited journal) is ignored rather than emitted as a
@@ -376,6 +438,11 @@ export function aggregateLifecycleForRun(journal, runId, { excludeCommands = []
     const command = typeof entry.command === "string" ? entry.command : "(unknown)";
     commandCounts.set(command, (commandCounts.get(command) || 0) + 1);
     const exitStatus = Number.isInteger(entry.exit_status) ? entry.exit_status : null;
+    if (exitStatus === 2) needsInputCount += 1;
+    else if (exitStatus !== null && exitStatus !== 0) failureCount += 1;
+    const findings = exitStatus !== null && exitStatus !== 0 && isStringArray(entry.finding_codes)
+      ? [...new Set(entry.finding_codes)].slice(0, 5) : [];
+    const findingFields = findings.length ? { finding_codes: findings } : {};
     // A command may have recorded its own repair loops via recordRepairLoop().
     if (Number.isInteger(entry.repair_loop_count)) explicitRepairLoops += entry.repair_loop_count;
 
@@ -384,12 +451,25 @@ export function aggregateLifecycleForRun(journal, runId, { excludeCommands = []
           name: `${command}:${typeof stage?.name === "string" ? stage.name : "stage"}`,
           duration_ms: typeof stage?.duration_ms === "number" ? stage.duration_ms : null,
           exit_status: exitStatus,
+          ...(Number.isInteger(stage?.wait_ms) && stage.wait_ms >= 0 ? { wait_ms: stage.wait_ms } : {}),
+          ...(exitStatus !== null && exitStatus !== 0 && isFindingCodes(stage?.finding_codes) && stage.finding_codes.length
+            ? { finding_codes: stage.finding_codes } : {}),
         }))
       : [{
           name: command,
           duration_ms: typeof entry.duration_ms === "number" ? entry.duration_ms : null,
           exit_status: exitStatus,
+          ...(Number.isInteger(entry.wait_ms) && entry.wait_ms >= 0 ? { wait_ms: entry.wait_ms } : {}),
+          ...findingFields,
         }];
+    if (subStages.length > 1 || (Array.isArray(entry.stages) && entry.stages.length)) {
+      const attributed = new Set(subStages.flatMap((stage) => stage.finding_codes ?? []));
+      const unknown = findings.filter((code) => !attributed.has(code));
+      if (unknown.length) {
+        const lastStage = subStages.at(-1);
+        lastStage.finding_codes = [...new Set([...(lastStage.finding_codes ?? []), ...unknown])].slice(0, 5);
+      }
+    }
     stages.push(...subStages);
 
     if (typeof entry.duration_ms === "number") durationSum += entry.duration_ms;
@@ -430,5 +510,7 @@ export function aggregateLifecycleForRun(journal, runId, { excludeCommands = []
     wall_clock_duration_ms: wallClockDurationMs == null ? null : Math.round(wallClockDurationMs),
     stages,
     repair_loop_count: repairLoopCount,
+    needs_input_count: needsInputCount,
+    failure_count: failureCount,
   };
 }