@nextcommerce/campaigns-os 1.53.0 → 1.55.0

package/src/doctor/checks.mjs

@@ -108,7 +108,7 @@ import { evaluatePageKitSdkVersion, PAGE_KIT_SDK_VERSION_SCOPE } from "../page-k
 // `npm run build:spec` (tsc -> campaign-spec/dist) so the package runs on the
 // node engine in package.json without type-stripping. build runs on `prepare`,
 // so a fresh install (including the git-ref consumer) always has dist.
-import { normalize as normalizeCampaignSpec, runRules, specOnlyRules } from "../../campaign-spec/dist/index.js";
+import { isReleasedSdkVersion, normalize as normalizeCampaignSpec, runRules, specOnlyRules } from "../../campaign-spec/dist/index.js";
 import { cmd, asInvocation } from "../install-invocation.mjs";
 import { specHashesMatch, specMaterialHash } from "../spec-identity.mjs";
 import {
@@ -440,7 +440,7 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
   {
     id: SDK_MARKUP,
     phase: "built-output",
-    run: ({ packet, errors, warnings, ready, derived }) => validateSdkMarkup(packet, errors, warnings, ready, derived),
+    run: ({ spec, packet, errors, warnings, ready, derived }) => validateSdkMarkup(packet, errors, warnings, ready, derived, spec),
   },
   {
     id: SCRIPT_SYNTAX,
@@ -832,7 +832,7 @@ function validateAdapterContracts(packet, packetPath, spec, errors, warnings, re
   const packetContract = packet.source_html?.adapter_contract;
   validateAdapterDecisionShape(packetContract, "source_html.adapter_contract", warnings, ready, { addIssue });
   validateAdapterSourceFiles({
-    decisions: packetContract,
+    decisions: buildState.report?.adapter_decisions || buildState.context?.adapter_decisions || packetContract,
     sourceRoot: resolveFromFile(packetPath, packet.source_html?.root),
     pages: packet.source_html?.pages || [],
     warnings,
@@ -2147,6 +2147,10 @@ export function validateCampaignIdentity(packet, errors, ready, derived, spec =
       site_root: siteRoot && targetRepo ? relFromDir(targetRepo, siteRoot) : null,
     },
     pages,
+    expectedApiKey: (() => {
+      const resolved = resolveCampaignsApiKeySource(packet, null, process.env, { spec });
+      return resolved.key ? { key: resolved.key, source: resolved.origin } : null;
+    })(),
     errors,
     ready,
     derived,
@@ -2290,8 +2294,8 @@ function readBoundedScript(realSiteRoot, path, maxBytes) {
   }
 }
 
-function recordCampaignIdentityGate({ subject, pages, errors, ready, derived }) {
-  const gate = evaluateCampaignIdentity({ subject, pages });
+function recordCampaignIdentityGate({ subject, pages, expectedApiKey = null, errors, ready, derived }) {
+  const gate = evaluateCampaignIdentity({ subject, pages, expectedApiKey });
   if (Array.isArray(derived?.checkpoint_gates)) derived.checkpoint_gates.push(gate);
 
   if (gate.status === "blocked") {
@@ -2315,17 +2319,23 @@ function recordCampaignIdentityGate({ subject, pages, errors, ready, derived })
 // Static SDK markup checks (#303). Every doctor invocation, both entry points,
 // filesystem enumeration, blocking regardless of stage status — the same
 // contract as the two gates above, for the same reasons.
-function validateSdkMarkup(packet, errors, warnings, ready, derived) {
+function validateSdkMarkup(packet, errors, warnings, ready, derived, spec = null) {
   const targetRepo = derived.target_repo;
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   const siteRoot = targetRepo && publicRouteSlug ? join(targetRepo, "_site", publicRouteSlug) : null;
   const scope = siteRoot && existsSync(siteRoot) ? resolveBuiltSiteScope(targetRepo, { slug: publicRouteSlug }) : null;
+  const declaredTypes = new Map(activeSpecPages(spec).filter((page) => ["receipt", "thankyou"].includes(page.type)).map((page) => [
+    builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived), "receipt",
+  ]));
   recordSdkMarkupGate({
     subject: {
       public_route_slug: publicRouteSlug || null,
       site_root: siteRoot && targetRepo ? relFromDir(targetRepo, siteRoot) : null,
     },
-    pages: scope?.ok ? collectBuiltPageIdentityInputs(scope, targetRepo) : [],
+    pages: scope?.ok ? collectBuiltPageIdentityInputs(scope, targetRepo).map((page) => ({
+      ...page,
+      page_type: declaredTypes.get(resolve(targetRepo, page.file)) || null,
+    })) : [],
     errors,
     warnings,
     ready,
@@ -2522,7 +2532,7 @@ function recordSmokeQc({ subject, targetRepo, pages, environment, deployBase, wa
 }
 
 function recordSdkMarkupGate({ subject, pages, errors, warnings, ready, derived }) {
-  const gate = evaluateSdkMarkup({ subject, pages });
+  const gate = evaluateSdkMarkup({ subject, pages, sdkVersion: campaignSdkPin(derived?.target_repo, subject?.public_route_slug) });
   if (Array.isArray(derived?.checkpoint_gates)) derived.checkpoint_gates.push(gate);
 
   if (gate.status === "not_applicable") {
@@ -2553,6 +2563,16 @@ function recordSdkMarkupGate({ subject, pages, errors, warnings, ready, derived
   return gate;
 }
 
+// The campaign's SDK pin from the target's campaigns.json entry, when it is an
+// exact released version; else null. The SDK markup check reads a page's own
+// loader pin first and falls back to this one.
+function campaignSdkPin(targetRepo, publicRouteSlug) {
+  if (!targetRepo || !publicRouteSlug) return null;
+  const load = loadPageKitCampaignEntry({ targetRepo, publicRouteSlug });
+  const version = load.status === "ok" ? load.entry?.sdk_version : null;
+  return isReleasedSdkVersion(version) ? version : null;
+}
+
 // Route drift: a CampaignSpec page whose declared route has no built page at
 // that path. page-kit derives the public route from the source FILENAME, so a
 // file named presell-running.html builds at /presell-running/ even if the spec

package/src/doctor/inspect.mjs

@@ -5,6 +5,7 @@ import { withHtmlScanSnapshot } from "../html-scan.mjs";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { shellToken } from "../shell-token.mjs";
+import { cmd } from "../install-invocation.mjs";
 import { commitAssemblyReport, recordProducerStageOutcome } from "../stage-ledger.mjs";
 import { annotateDoctorIssueCauses } from "../finding-cause.mjs";
 import { DOCTOR_SIDECAR_SCHEMA } from "../doctor-sidecar.mjs";
@@ -244,6 +245,18 @@ export function doctorBuiltOutput(args) {
     qc_results: [],
   };
   ready.push(`Resolved ${scope.html_count} built page(s) from ${relFromDir(targetRepo, scope.campaign_dir)} (slug "${scope.slug || "(site root)"}")`);
+  // #583: --base-url reads like a check of the deployed site, but these checks
+  // read only the local built files. Say so wherever the URL is given, and
+  // name the command that does load the served pages.
+  if (baseUrl) {
+    derived.base_url = { value: baseUrl, fetched: false, recorded_as: "deploy.preview_url" };
+    // Without --family there is no value to print that the CLI would accept,
+    // so the command is printed only when it is runnable as shown.
+    const servedCheck = family
+      ? `To check the served pages, run ${cmd("qa", `run --site ${shellToken(String(args.built || args.site))} --base-url ${shellToken(baseUrl)} --family ${shellToken(family)} --browser`)}.`
+      : `To check the served pages, run ${cmd("qa")} run --site with this --base-url and the campaign's --family, plus --browser.`;
+    ready.push(`Checked the local built files only: --base-url ${baseUrl} was not fetched; it only fills deploy.preview_url in the minimal Build Packet. ${servedCheck}`);
+  }
 
   const resolution = resolveBrandContractOnce(derived, family);
   let brandContract = null;

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 { polishCarriedForwardForLadder } 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,7 +16,7 @@ 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 { isObject, isNonEmptyString, optionalString, resolveFromFile, addIssue, filesystemPathsMatch } from "../cli-helpers.mjs";
@@ -473,9 +473,9 @@ 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;
     const reportKey = reportKeyForCliStage(cliStage);
     const stage = report.stages[reportKey];
     if (!stage) {
@@ -500,6 +500,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
@@ -711,6 +715,12 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
   const fallbackAction = picked.stage === "done"
     ? `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),

package/src/invocation.mjs

@@ -54,7 +54,7 @@ const COMMANDS = frozen({
   logout: { class: "auth" },
   demo: { class: "inline" },
   tooling: { subcommands: ["diagnose", "setup", "status"] },
-  sdk: { subcommands: ["storage-check"] },
+  sdk: { subcommands: ["repin", "storage-check"] },
   readback: { class: "projection" },
   start: { sweepRoot: "target" },
   "prepare-build": { sweepRoot: "target" },
@@ -86,6 +86,8 @@ const SUBCOMMAND_OVERRIDES = frozen({
   "tooling diagnose": { class: "inline" },
   "tooling setup": { class: "inline" },
   "sdk storage-check": { class: "inspection" },
+  // Preview by default: only --apply writes, so only --apply journals.
+  "sdk repin": { journalExemptWhen: { given: "target", unlessBare: "apply" } },
   "theme waive": { dryRun: true },
   "checkpoint accept": { dryRun: true },
   "checkpoint waive": { dryRun: true },
@@ -130,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,
   };
 }

package/src/local-preview-policy.mjs

@@ -75,6 +75,12 @@ export function applyLocalPreviewToCheckpoint(gate, { packet, report, baseUrl =
 
 // The polish gate folds the checkpoint in, so it is carried forward only when
 // whatever it owns from the checkpoint was carried forward too.
+export function polishCarriedForwardForLadder(report, gate) {
+  return gate?.status === CARRIED_FORWARD
+    && !report?.theme?.waiver
+    && !report?.stages?.polish?.evidence?.visual_review?.page_load;
+}
+
 export function applyLocalPreviewToPolishGate(gate, { packet, checkpointGate = null, baseUrl = null } = {}) {
   if (gate?.status !== "blocked" || !isLocalPreview(packet, { baseUrl })) return gate;
   const checkpointCarried = checkpointGate?.status === CARRIED_FORWARD;

package/src/login.mjs

@@ -1,4 +1,5 @@
 import { createCredentialStore } from './credential-store.mjs';
+import { timeOperatorWait } from './lifecycle.mjs';
 
 export const GATEWAY = 'https://mcp.nextcommerce.com';
 export const CLIENT_ID = 'campaigns-os-owned-store-pilot';
@@ -27,7 +28,7 @@ export function authenticationArguments(argv) {
 async function askStore() {
   const { createInterface } = await import('node:readline/promises');
   const prompt = createInterface({ input: process.stdin, output: process.stdout });
-  try { return await prompt.question('Store subdomain (or network domain): '); }
+  try { return await timeOperatorWait(() => prompt.question('Store subdomain (or network domain): ')); }
   finally { prompt.close(); }
 }
 const bindingFor = store => ({ gateway: GATEWAY, client_id: CLIENT_ID, store });

package/src/polish-browser.mjs

@@ -1012,6 +1012,10 @@ function polishBrowserMissing(kind, error) {
     ].join(" "));
 }
 
+// `networkIdleTimeoutMs`, like the deadlines, can only shorten its bound: the
+// wait for network idle after each navigation (NETWORKIDLE_TIMEOUT_MS). The
+// CLI never passes it; a test whose page holds a transfer open passes a
+// shorter window rather than wait out the production one on every cell.
 export async function createPolishBrowserAdapter({
   headed = false,
   authCookie = null,
@@ -1019,6 +1023,7 @@ export async function createPolishBrowserAdapter({
   cellDeadlineMs,
   cleanupDeadlineMs,
   startupDeadlineMs,
+  networkIdleTimeoutMs,
 } = {}) {
   const authCookies = parseAuthCookie(authCookie);
   const boundedCellDeadlineMs = boundedPolishDeadline(cellDeadlineMs, POLISH_BROWSER_CELL_DEADLINE_MS);
@@ -1030,6 +1035,7 @@ export async function createPolishBrowserAdapter({
     startupDeadlineMs,
     POLISH_BROWSER_STARTUP_DEADLINE_MS,
   );
+  const networkIdleMs = boundedPolishDeadline(networkIdleTimeoutMs, NETWORKIDLE_TIMEOUT_MS);
   let browser;
   let startupTimedOut = false;
   const startupAbort = new AbortController();
@@ -1234,7 +1240,7 @@ export async function createPolishBrowserAdapter({
         const initialMediaElements = await awaitActive(collectMediaElements(page));
         let networkidle;
         try {
-          await awaitActive(page.waitForLoadState("networkidle", { timeout: NETWORKIDLE_TIMEOUT_MS }));
+          await awaitActive(page.waitForLoadState("networkidle", { timeout: networkIdleMs }));
           networkidle = { status: "settled", duration_ms: durationSince(navigationStartedAt) };
         } catch (error) {
           if (!timeoutError(error)) throw error;
@@ -1327,7 +1333,7 @@ export async function createPolishBrowserAdapter({
           if (initialTree === BOUND_ENDED) return unmeasured(boundEnded());
           if (initialTree.error) return unmeasured("document_changed");
           const initialMainFrame = initialTree.value?.frameTree?.frame;
-          const idleTimeout = Math.max(1, Math.min(NETWORKIDLE_TIMEOUT_MS, Math.floor(addedLeft()), Math.floor(cellLeftMs())));
+          const idleTimeout = Math.max(1, Math.min(networkIdleMs, Math.floor(addedLeft()), Math.floor(cellLeftMs())));
           const idle = await awaitActive(steps.step(() => page.waitForLoadState("networkidle", { timeout: idleTimeout })));
           if (idle === BOUND_ENDED) return unmeasured(boundEnded());
           if (idle.error && !timeoutError(idle.error)) throw idle.error;

package/src/polish-node.mjs

@@ -669,6 +669,7 @@ async function runPolishCapture({
   captureCellDeadlineMs,
   adapterCloseDeadlineMs,
   probeClock = null,
+  mediaProbeRunBudgetMs,
   targetRepo = null,
   now = new Date(),
 } = {}) {
@@ -687,6 +688,10 @@ async function runPolishCapture({
     adapterCloseDeadlineMs,
     POLISH_CAPTURE_CLOSE_DEADLINE_MS,
   );
+  // The 1.3 image probe's run budget. Like the deadlines it can only shorten:
+  // the CLI never passes it, and a test that spends the budget passes a
+  // smaller one so that fewer slow cells spend it.
+  const probeRunBudgetMs = boundedPolishDeadline(mediaProbeRunBudgetMs, MEDIA_PROBE_LIMITS.runBudgetMs);
 
   let adapter = null;
   // Failure is tracked apart from its reason: a rejection may carry any value,
@@ -806,7 +811,7 @@ async function runPolishCapture({
           const abortController = new AbortController();
           const imageProbe = {
             ...(isProbeClock(probeClock) ? { clock: probeClock } : {}),
-            remainingMs: MEDIA_PROBE_LIMITS.runBudgetMs - probeSpentMs,
+            remainingMs: probeRunBudgetMs - probeSpentMs,
             cellBoundMs: MEDIA_PROBE_LIMITS.cellBoundMs,
             imageCap: MEDIA_PROBE_LIMITS.imageCap,
           };

package/src/polish-readability.mjs

@@ -433,8 +433,8 @@ export function readabilityProbe(toolkit, limits, closedRoots, generatedText) {
   // ancestor matches. checkout_label and checkout_hint are read separately.
   const ROLES = [
     ["add_to_cart", "[data-next-action=\"add-to-cart\"]"],
-    ["upsell_accept", "[data-next-upsell-action=\"add\"]"],
-    ["upsell_decline", "[data-next-upsell-action=\"skip\"]"],
+    ["upsell_accept", "[data-next-upsell-action=\"add\"], [data-next-upsell-action=\"accept\"]"],
+    ["upsell_decline", "[data-next-upsell-action=\"skip\"], [data-next-upsell-action=\"decline\"]"],
     ["submit_control", "button.submit-button[os-checkout-payment=\"combo\"], button[os-checkout-payment=\"combo\"], button[type=\"submit\"], input[type=\"submit\"], input[type=\"button\"]"],
     ["sdk_action", "[data-next-action]"],
     ["bundle_card", "[data-next-bundle-card], [data-next-selector-card], [data-next-package-id], [data-next-bundle-id]"],

package/src/progress-node.mjs

@@ -96,7 +96,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
 }
 function lock(dir,fn,{budgetMs=1500}={}) {
   const lockPath=join(dir,'.allocation-lock');
-  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:()=>Object.assign(new Error('progress.lock_unavailable'),{lockPath})});
+  return withDirectoryLock(lockPath,fn,{budgetMs,unavailable:(error)=>Object.assign(new Error('progress.lock_unavailable'),{lockPath,code:error?.code,obstruction:error?.obstruction})});
 }
 export async function persistProgressObservation(observation,{dir,now=()=>new Date(),historyLimit=32}={}) {
   mkdirSync(dir,{recursive:true,mode:0o700});
@@ -164,7 +164,8 @@ export async function observeProgress(args,continuation,{qaResult=null,packageVe
     if(remit.state==='failed')warn('[campaigns-os] Progress delivery pending; the local observation is retained. Lifecycle result is unchanged.');
     return {...remit,snapshot_id:snapshot.snapshot_id,reused};
   } catch(error) {
-    if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
+    if(error?.message==='progress.lock_unavailable'&&error.obstruction)warn(`[campaigns-os] Progress allocation lock path ${error.lockPath} is occupied by ${error.obstruction}; it is never removed automatically. Move it out of the way. Lifecycle result is unchanged.`);
+    else if(error?.message==='progress.lock_unavailable')warn(`[campaigns-os] Progress allocation lock occupied${error.lockPath?` at ${error.lockPath}`:''}; wait for the current writer. If it stays occupied (an abandoned, ownerless or interrupted lock), stop all campaigns-os writers for this target, then remove that lock directory (docs/progress-snapshots.md). Lifecycle result is unchanged.`);
     else warn('[campaigns-os] Progress observation unavailable; lifecycle result is unchanged.');
     return {state:'failed',reason:'capture_unavailable'};
   }