@nextcommerce/campaigns-os 1.34.1 → 1.37.1

package/src/diagnostic.mjs

@@ -0,0 +1,101 @@
+// A projection, never a scrubber: source objects and free text never enter
+// the export. Unknown producer values have fixed, non-actionable markers.
+const MODES = new Set(["checkout", "node_modules", "global", "npx_cache", "package_directory"]);
+const PLATFORMS = new Set(["claude", "codex", "agents", "all"]);
+const STAGES = new Set(["prepare-build", "doctor-blocked", "setup", "build", "polish", "deploy", "qa", "done"]);
+const STATUSES = new Set(["ready", "attention_required", "ready_with_warnings", "ready_with_waivers", "blocked"]);
+const REASONS = new Set([
+  "assembly.template_lock", "campaign.allowed_domains_confirmed", "deploy.preview_url",
+  "page_kit.scaffold_required", "spec.page_url_html_extension", "spec.route_collision",
+  "scope.runtime_qa_blocked", "scope.partial_build", "content_residue.needs_merchant_input",
+  "page_kit.store_profile.mismatch", "page_kit.store_profile.demo_residue",
+  "page_kit.sdk_version.expected_observed_mismatch", "page_kit.sdk_version.repo_newer",
+  "page_kit.sdk_version.conflicting_declarations", "polish.evidence_missing",
+  "polish.assembly_source_package_stale", "polish.source_package_stale", "polish.stale",
+  "polish.hidden_eager_media.capture_missing", "polish.hidden_eager_media.capture_malformed",
+  "theme_gate.starter_palette_only", "built_output.campaign_identity",
+  "built_output.upsell_selector_scope", "built_output.sdk_markup.swap_with_add_to_cart",
+  "built_output.sdk_markup.checkout_not_form", "built_output.sdk_markup.wrong_field_name",
+  "built_output.sdk_markup.missing_selector_id_match",
+]);
+const ACTIONS = new Set([
+  "repair_target", "align_store_profile", "align_sdk_version", "repair_waiver", "waive_checkpoint",
+  "rerun_build", "run_polish", "theme_generate", "apply_brand_layer", "waive_theme",
+  "polish.hidden_eager_media.capture", "polish.hidden_eager_media.install_browser",
+  "polish.hidden_eager_media.repair", "polish.hidden_eager_media.repair_authority",
+  "polish.hidden_eager_media.local_proof_rebuild", "polish.hidden_eager_media.waive",
+]);
+
+const RECOVERY = Object.freeze({
+  skills: { owner: "operator", action_id: "install-skills", input_needed: "Selected agent profile", instruction: "Refresh the bundled skills for that profile and restart the agent." },
+  pin: { owner: "operator", action_id: "tooling.status", input_needed: "Reviewed toolkit version and lockfile", instruction: "Compare the installed package with the reviewed version; registry currency is not checked." },
+  update: { owner: "operator", action_id: "tooling.status", input_needed: "Reviewed upstream revision", instruction: "Review and update the toolkit checkout using the existing worktree workflow." },
+  doctor: { owner: "workflow_owner", action_id: "doctor", input_needed: "Local packet inputs and detailed doctor findings", instruction: "Inspect doctor locally and follow its existing owner, required inputs, and recovery actions." },
+  unsupported: { owner: "toolkit_maintainer", action_id: "tooling.diagnose", input_needed: "Producer vocabulary supported by this diagnostic version", instruction: "Review unsupported producer values locally; this export gives them no authority." },
+});
+
+export function diagnosticExport({ tooling = null, doctor = null, platform = "all", inspectionFailed = false } = {}) {
+  const reasonIds = new Set();
+  const actionIds = new Set();
+  const recovery = [];
+  const enumValue = (value, allowed) => {
+    if (allowed.has(value)) return value;
+    reasonIds.add("diagnostic.unsupported_value");
+    return "unknown";
+  };
+  const safePlatform = enumValue(platform, PLATFORMS);
+  const mode = tooling ? enumValue(tooling.install?.mode, MODES) : "unknown";
+  const version = typeof tooling?.package?.version === "string" && /^\d{1,6}\.\d{1,6}\.\d{1,6}$/.test(tooling.package.version)
+    ? tooling.package.version : null;
+  const toolingStatus = tooling ? enumValue(tooling.status, STATUSES) : "unavailable";
+  if (!tooling) reasonIds.add("diagnostic.tooling_unavailable");
+  const doctorStatus = doctor ? enumValue(doctor.status, STATUSES) : inspectionFailed ? "unavailable" : "not_requested";
+  const stage = doctor ? enumValue(doctor.next?.stage, STAGES) : "unknown";
+  let freshness = "unknown";
+  if (tooling?.install?.pinned?.commit && /^[0-9a-f]{7,40}$/.test(tooling.install.pinned.commit)) freshness = "pinned";
+  else if (mode === "checkout" && tooling?.git?.status === "ok" && Number.isInteger(tooling.git.behind) && tooling.git.behind >= 0) {
+    freshness = tooling.git.behind > 0 ? "local_ref_behind" : "local_ref_current";
+  }
+  if (tooling) {
+    if (typeof tooling.skills?.ok !== "boolean") {
+      reasonIds.add("diagnostic.unsupported_value");
+    } else if (tooling.skills.ok === false) {
+      reasonIds.add("tooling.skills_stale"); actionIds.add("install-skills"); recovery.push(RECOVERY.skills);
+    }
+  }
+  if (freshness === "unknown") { reasonIds.add("tooling.freshness_unknown"); recovery.push(RECOVERY.pin); }
+  if (freshness === "local_ref_behind") { reasonIds.add("tooling.checkout_behind"); recovery.push(RECOVERY.update); }
+  for (const issue of [...(Array.isArray(doctor?.errors) ? doctor.errors : []), ...(Array.isArray(doctor?.warnings) ? doctor.warnings : [])]) {
+    reasonIds.add(REASONS.has(issue?.code) ? issue.code : "diagnostic.unsupported_reason");
+  }
+  for (const gate of Array.isArray(doctor?.derived?.checkpoint_gates) ? doctor.derived.checkpoint_gates : []) {
+    for (const action of Array.isArray(gate?.required_actions) ? gate.required_actions : []) {
+      actionIds.add(ACTIONS.has(action?.id) ? action.id : "diagnostic.unsupported_action");
+    }
+  }
+  if ((doctor && doctorStatus !== "ready") || inspectionFailed) {
+    if (inspectionFailed) reasonIds.add("diagnostic.inspection_unavailable");
+    actionIds.add("doctor"); recovery.push(RECOVERY.doctor);
+  }
+  if ([...reasonIds, ...actionIds].some((id) => id.startsWith("diagnostic.unsupported_"))) recovery.push(RECOVERY.unsupported);
+  return {
+    schema_version: "campaigns-os-diagnostic/v0",
+    version, install_mode: mode, platform: safePlatform,
+    tooling_status: toolingStatus, doctor_status: doctorStatus, stage,
+    freshness: { toolkit: freshness, inspection: doctor ? "observed" : inspectionFailed ? "unavailable" : "not_requested" },
+    reason_ids: [...reasonIds].sort(), action_ids: [...actionIds].sort(), recovery,
+  };
+}
+
+export function diagnosticTextLines(result) {
+  return [
+    "Campaigns OS diagnostic (redacted)",
+    `Version: ${result.version || "unknown"}; install: ${result.install_mode}; platform: ${result.platform}`,
+    `Tooling: ${result.tooling_status}; doctor: ${result.doctor_status}; next stage: ${result.stage}`,
+    `Freshness: ${result.freshness.toolkit}; local inspection: ${result.freshness.inspection}`,
+    `Reasons: ${result.reason_ids.join(", ") || "none"}`,
+    `Actions: ${result.action_ids.join(", ") || "none"}`,
+    ...result.recovery.map((item) => `Recovery (${item.owner}, ${item.action_id}): ${item.instruction} Input needed: ${item.input_needed}.`),
+    "This summary contains no campaign content or paths. Inspect detailed recovery locally. QA publication recovery uses the retained verdict with qa publish; never repeat an order to publish evidence.",
+  ];
+}

package/src/install-mode.mjs

@@ -5,12 +5,14 @@
 import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { basename, delimiter, dirname, join, relative, resolve, sep } from "node:path";
+import { shellToken } from "./shell-token.mjs";
 
 const PACKAGE_INSTALL_MODE_LABELS = Object.freeze({
   checkout: "git checkout",
   npx_cache: "package install (npx cache)",
   node_modules: "package install (node_modules)",
   package_directory: "package install",
+  global: "global package install",
 });
 
 const PUBLIC_GIT_SOURCE = "github:NextCommerceCo/campaigns-os";
@@ -111,9 +113,18 @@ export function localInstallStatus(root, pkg = {}) {
   const segments = root.split(sep);
   const npxIndex = segments.indexOf("_npx");
   const inNpxCache = npxIndex >= 0 && /^[0-9a-f]{8,}$/i.test(segments[npxIndex + 1] || "") && segments[npxIndex + 2] === "node_modules";
+  const modules = enclosingNodeModules(root);
+  // npm's global layout is prefix/lib/node_modules on POSIX and
+  // prefix/node_modules on Windows. Verify the prefix's own bin points to
+  // this package, independently of PATH, which may select another install.
+  const globalPrefix = modules && (process.platform === "win32" ? dirname(modules) : basename(dirname(modules)) === "lib" ? dirname(dirname(modules)) : null);
+  const globalBin = globalPrefix ? join(globalPrefix, process.platform === "win32" ? "campaigns-os.cmd" : "bin/campaigns-os") : null;
+  const ownBin = resolve(root, typeof pkg.bin === "object" ? pkg.bin["campaigns-os"] || "bin/campaigns-os.mjs" : "bin/campaigns-os.mjs");
+  const globalInstall = globalBin && existsSync(globalBin) && executableTargetPath(globalBin) === realpathOrSelf(ownBin);
   const mode = inNpxCache
     ? "npx_cache"
-    : enclosingNodeModules(root)
+    : globalInstall ? "global"
+    : modules
       ? "node_modules"
       : "package_directory";
   const pinned = derivePackagePin(root, pkg);
@@ -227,6 +238,7 @@ export function resolveInvocation(root, pkg = {}, install = localInstallStatus(r
   if (install.mode === "checkout") prefix = "npm run campaigns-os --";
   else if (install.mode === "npx_cache") prefix = install.pinned?.spec ? `npx --yes ${install.pinned.spec}` : "campaigns-os";
   else if (install.mode === "node_modules") prefix = "npx campaigns-os";
+  else if (install.mode === "global") prefix = matches ? "campaigns-os" : `node ${shellToken(localBin)}`;
   else prefix = "campaigns-os";
   return {
     install,

package/src/progress-node.mjs

@@ -0,0 +1,177 @@
+// Best-effort producer adapter. Sanitized immutable bytes are durable before delivery.
+import {randomBytes,createHash} from 'node:crypto';
+import {mkdirSync,readFileSync,writeFileSync,renameSync,rmSync,readdirSync,lstatSync} from 'node:fs';
+import {join,resolve,dirname} from 'node:path';
+import {PROGRESS_SCHEMA_VERSION,PROGRESS_STAGES,PROGRESS_STAGE_STATUSES,PROGRESS_CONTINUATIONS,PROGRESS_ACTION_IDS,PROGRESS_GATE_IDS,canonicalProgressJson,progressSnapshotId,verifyProgressSnapshot} from './progress.mjs';
+import {specMaterialHash} from './spec-identity.mjs';
+import {sameFile} from './fs-identity.mjs';
+import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefaultOnTelemetry} from './consent.mjs';
+import {boundedResponseText,isLoopbackHostname} from './remit.mjs';
+export const PROGRESS_OBSERVATION = Symbol('canonical progress observation');
+export const PROGRESS_ENDPOINT = '/api/progress';
+const accepted = (value,values,fallback='unknown')=>values.includes(value)?value:fallback;
+const hash = value=>typeof value==='string'&&/^(?:sha256:)?[0-9a-f]{64}$/i.test(value)?`sha256:${value.replace(/^sha256:/i,'').toLowerCase()}`:null;
+const id = value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(value)?value:null;
+const digest = value=>`sha256:${createHash('sha256').update(value).digest('hex')}`;
+const read = path=>{try{return JSON.parse(readFileSync(path,'utf8'));}catch{return null;}};
+function atomic(path,value) {const tmp=`${path}.${randomBytes(8).toString('hex')}.tmp`;writeFileSync(tmp,`${canonicalProgressJson(value)}\n`,{mode:0o600});renameSync(tmp,path);}
+export function resolveProgressEndpoint(args,workspace,context) {
+  // A foreign context cannot donate a source endpoint or quietly fall back.
+  const named=context?.packet_path;
+  const bound=typeof named==='string'&&named.trim()&&sameFile(resolve(workspace.targetRepo,named),workspace.packetPath,{requireExisting:true});
+  const explicit=args['proxy-base'];
+  const source=context?.intake?.proxy_base;
+  if (!explicit && !bound && source) return {ok:false,reason:'source_binding_invalid'};
+  if (explicit===undefined && (source===null||source===undefined) && workspace.packet?.spec?.spec_url) {
+    try { if (new URL(workspace.packet.spec.spec_url).origin!==CANONICAL_REMIT_SCOPE) return {ok:false,reason:'source_binding_missing'}; } catch { return {ok:false,reason:'source_binding_invalid'}; }
+  }
+  const raw=explicit!==undefined?explicit:source!==null&&source!==undefined?source:CANONICAL_REMIT_SCOPE;
+  if (typeof raw!=='string'||!raw.trim()) return {ok:false,reason:'endpoint_invalid'};
+  try {
+    const url=new URL(raw);
+    if (url.username||url.password||url.search||url.hash||!['https:','http:'].includes(url.protocol)||(url.protocol==='http:'&&!isLoopbackHostname(url.hostname))) return {ok:false,reason:'endpoint_invalid'};
+    const base=url.href.replace(/\/+$/,'');
+    return {ok:true,base,scope:normalizeConsentScope(base)};
+  } catch {return {ok:false,reason:'endpoint_invalid'};}
+}
+export function projectProgressObservation({workspace,context,report,doctor,continuation,qaResult=null,packageVersion}) {
+  const packet=workspace.packet;
+  let spec=null;
+  try {spec=JSON.parse(readFileSync(resolve(dirname(workspace.packetPath),packet.spec.local_path),'utf8'));}catch{}
+  const mapId=id(packet?.spec?.map_id);
+  const localHash=spec?hash(specMaterialHash(spec)):null;
+  const localMapId=id(spec?.spec_identity?.map_id||spec?.map_id);
+  const baseline=context?.intake?.saved_map_revision;
+  const contextBound=typeof context?.packet_path==='string'&&context.packet_path.trim()&&sameFile(resolve(workspace.targetRepo,context.packet_path),workspace.packetPath,{requireExisting:true});
+  const aligned=contextBound&&mapId&&localMapId===mapId&&baseline?.map_id===mapId&&baseline?.algorithm==='map-store-v1'&&hash(baseline.hash)&&localHash&&localHash===hash(baseline.local_spec_material_hash);
+  const build=hash(doctor?.derived?.build_output_fingerprint?.value);
+  const recordedBuild=hash(report?.stages?.assembly?.build_fingerprint);
+  const reportBound=doctor?.derived?.prepare_build_gate?.binding_failure!==true&&contextBound&&mapId&&localMapId===mapId&&report?.identity?.map_id===mapId&&localHash&&localHash===hash(report?.identity?.spec_material_hash);
+  const qaSource=hash(report?.stages?.qa?.evidence?.source_build_fingerprint);
+  const verdict=qaResult?.verdict;
+  const qa=verdict?{
+    verdict_id:id(verdict.run_id),disposition:accepted(verdict.disposition,['ready','ready_with_exceptions','blocked']),
+    binding:reportBound&&id(verdict.run_id)&&id(verdict.run_id)===id(report?.stages?.qa?.verdict_run_id)&&build&&qaSource===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'&&hash(verdict.spec_hash)===localHash?'matching':'unconfirmed',
+    publish_state:accepted(qaResult?.qa_verdict_publish?.state,['skipped','ok','failed']),
+  }:null;
+  const gates=(Array.isArray(continuation?.gates)?continuation.gates:[]).slice(0,16).map(gate=>({id:accepted(gate?.id,PROGRESS_GATE_IDS),state:PROGRESS_GATE_IDS.includes(gate?.id)?accepted(gate?.status,['pass','blocked','waived','not_applicable']):'unknown'}));
+  const actions=[...new Set((Array.isArray(continuation?.next_actions)?continuation.next_actions:[]).slice(0,64).map(action=>accepted(action?.id,PROGRESS_ACTION_IDS)))];
+  const stage=accepted(continuation?.stage,PROGRESS_CONTINUATIONS);
+  const preview=typeof packet?.deploy?.preview_url==='string'&&packet.deploy.preview_url?packet.deploy.preview_url:null;
+  return {
+    schema_version:PROGRESS_SCHEMA_VERSION,package_version:packageVersion,producer:qaResult?'qa':'next',
+    identity:{map_id:mapId,map_revision_hash:contextBound&&baseline?.map_id===mapId?hash(baseline?.hash):(localMapId===mapId?hash(spec?.spec_identity?.spec_hash||spec?.spec_hash):null),map_revision_algorithm:'map-store-v1',saved_revision_alignment:aligned?'aligned':'unconfirmed',local_spec_material_hash:localHash,local_spec_material_algorithm:'campaign-spec-material-v1',build_fingerprint:build,build_fingerprint_algorithm:'sha256-manifest/v1'},
+    stages:PROGRESS_STAGES.map(stage=>{
+      const status=reportBound?accepted(report?.stages?.[stage]?.status,PROGRESS_STAGE_STATUSES):'unknown';
+      const source=stage==='assembly'?recordedBuild:stage==='qa'?qaSource:null;
+      return {stage,status,source_build_fingerprint:source,build_binding:reportBound&&build&&source===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'?'matching':'unconfirmed'};
+    }),
+    preview:{present:Boolean(preview),url_hash:preview?digest(preview):null},
+    continuation:{stage,blocked:continuation?.ok!==true||(Array.isArray(continuation?.divergences)&&continuation.divergences.length>0)||stage==='unknown'||gates.some(gate=>['blocked','unknown'].includes(gate.state))||actions.includes('unknown'),divergent:Array.isArray(continuation?.divergences)&&continuation.divergences.length>0,action_ids:actions,gates},qa,
+  };
+}
+async function lock(dir,fn,{budgetMs=1500}={}) {
+  const path=join(dir,'.allocation-lock'); const start=Date.now();const token=randomBytes(16).toString('hex');
+  const abandoned=(unownedMtime=null)=>{
+    try {
+      const stat=lstatSync(path);if(!stat.isDirectory()||stat.isSymbolicLink())return false;
+      const owner=read(join(path,'owner.json'));
+      if(Number.isInteger(owner?.pid)&&owner.pid>0&&typeof owner.token==='string') {
+        try {process.kill(owner.pid,0);return false;}catch(error){return error.code==='ESRCH';}
+      }
+      // A killed process can leave the directory before writing its owner.
+      // Give a live allocator ample time to finish that tiny synchronous gap.
+      return Date.now()-(unownedMtime??stat.mtimeMs)>10000;
+    }catch{return false;}
+  };
+  const recover=()=>{
+    if(!abandoned())return;
+    let originalMtime;try{originalMtime=lstatSync(path).mtimeMs;}catch{return;}
+    const claim=join(path,'.recovery');
+    // Only this exclusive claimant can rename the old lock. An interrupted
+    // recovery claim fails closed for explicit offline recovery; recursively
+    // stealing recovery claims would reintroduce a check/rename race.
+    try {mkdirSync(claim);atomic(join(claim,'owner.json'),{pid:process.pid,token});}catch{return;}
+    let moved=false;
+    try {
+      if(!abandoned(originalMtime))return;
+      const tomb=`${path}.abandoned-${token}`;
+      renameSync(path,tomb);moved=true;rmSync(tomb,{recursive:true,force:true});
+    }catch{}finally{if(!moved&&read(join(claim,'owner.json'))?.token===token){try{rmSync(claim,{recursive:true,force:true});}catch{}}}
+  };
+  while (true) {
+    try {mkdirSync(path);atomic(join(path,'owner.json'),{pid:process.pid,token});break;}catch(error){if(error.code!=='EEXIST'||Date.now()-start>=budgetMs)throw new Error('progress.lock_unavailable');recover();await new Promise(resolve=>setTimeout(resolve,20));}
+  }
+  try{return await fn();}finally{if(read(join(path,'owner.json'))?.token===token)rmSync(path,{recursive:true,force:true});}
+}
+export async function persistProgressObservation(observation,{dir,now=()=>new Date(),historyLimit=32}={}) {
+  mkdirSync(dir,{recursive:true,mode:0o700});
+  return lock(dir,async()=>{
+    const latest=read(join(dir,'latest.json'));
+    const latestValid=latest&&(await verifyProgressSnapshot(latest)).ok;
+    const observationHash=digest(canonicalProgressJson(observation));
+    if (latestValid) {
+      const {snapshot_id,stream_id,sequence,previous_snapshot_id,observed_at,...old}=latest;
+      if (digest(canonicalProgressJson(old))===observationHash) return {snapshot:latest,reused:true};
+    }
+    // A new spec/build identity starts an independent history; stage completion
+    // from the old output cannot become completion for the new output.
+    const sameIdentity=latestValid&&canonicalProgressJson(latest.identity)===canonicalProgressJson(observation.identity);
+    const snapshot={...observation,stream_id:sameIdentity?latest.stream_id:`progress_${randomBytes(16).toString('hex')}`,sequence:sameIdentity?latest.sequence+1:1,previous_snapshot_id:sameIdentity?latest.snapshot_id:null,observed_at:now().toISOString()};
+    snapshot.snapshot_id=await progressSnapshotId(snapshot);
+    if (!(await verifyProgressSnapshot(snapshot)).ok) throw new Error('progress.invalid_projection');
+    atomic(join(dir,`${snapshot.snapshot_id.slice(7)}.snapshot.json`),snapshot);
+    atomic(join(dir,'latest.json'),snapshot);
+    const history=readdirSync(dir).filter(name=>/^[0-9a-f]{64}\.snapshot\.json$/.test(name)).map(name=>({name,at:read(join(dir,name))?.observed_at||''})).sort((a,b)=>a.name===`${snapshot.snapshot_id.slice(7)}.snapshot.json`?-1:b.name===`${snapshot.snapshot_id.slice(7)}.snapshot.json`?1:b.at.localeCompare(a.at)||b.name.localeCompare(a.name));
+    const limit=Math.min(32,Math.max(1,historyLimit));
+    for (const old of history.slice(limit)) if(old.name!==`${snapshot.snapshot_id.slice(7)}.snapshot.json`) {rmSync(join(dir,old.name),{force:true});rmSync(join(dir,old.name.replace('.snapshot.json','.remit.json')),{force:true});}
+    return {snapshot,reused:false};
+  });
+}
+export async function remitProgressSnapshot(snapshot,{base,campaignKey,fetchImpl=globalThis.fetch,budgetMs=2000}={}) {
+  const bytes=canonicalProgressJson(snapshot);const deadline=Date.now()+Math.min(2000,Math.max(1,budgetMs));
+  let reason='transport_failed';let attempts=0;let httpStatus=null;
+  for (let attempt=0;attempt<2&&Date.now()<deadline;attempt++) {
+    attempts++;
+    try {
+      const response=await fetchImpl(`${base}${PROGRESS_ENDPOINT}`,{method:'POST',redirect:'error',headers:{'Content-Type':'application/json','Accept':'application/json','X-Campaign-Key':campaignKey},body:bytes,signal:AbortSignal.timeout(Math.max(1,deadline-Date.now()))});
+      httpStatus=response.status;
+      let ack=null;try{ack=JSON.parse(await boundedResponseText(response,{maxBodyBytes:4096,timeoutMs:Math.max(1,deadline-Date.now())}));}catch{}
+      if ((response.ok||response.status===409)&&ack?.ok===true&&ack.snapshot_id===snapshot.snapshot_id&&ack.digest===snapshot.snapshot_id) return {state:'ok',reason:'acknowledged',attempts,http_status:httpStatus};
+      reason=response.status===409?'conflict':response.ok?'ack_invalid':'http_refused';
+      if (!(response.status===429||response.status>=500)) break;
+    } catch {reason='transport_failed';}
+  }
+  return {state:'failed',reason,attempts,http_status:httpStatus};
+}
+export async function observeProgress(args,continuation,{qaResult=null,packageVersion,resolveKey,env=process.env,configPath,fetchImpl,warn=message=>process.stderr.write(`${message}\n`)}={}) {
+  if (args['no-write']===true) return {state:'disabled',reason:'no_write'};
+  try {
+    const source=continuation?.[PROGRESS_OBSERVATION];
+    if (!source) return {state:'skipped',reason:'observation_unavailable'};
+    const {workspace,context}=source;
+    const endpoint=resolveProgressEndpoint(args,workspace,context);
+    const observation=projectProgressObservation({...source,continuation,qaResult,packageVersion});
+    const storageScope=digest(canonicalProgressJson({packet:workspace.packetPath,context:workspace.contextPath,report:workspace.reportPath,endpoint:endpoint.ok?endpoint.scope:null})).slice(7);
+    const dir=join(workspace.targetRepo,'.campaign-runtime','progress',storageScope);
+    const {snapshot,reused}=await persistProgressObservation(observation,{dir});
+    const metaPath=join(dir,`${snapshot.snapshot_id.slice(7)}.remit.json`);
+    const prior=read(metaPath);
+    if (prior?.state==='ok') return {state:'ok',reason:'already_acknowledged',snapshot_id:snapshot.snapshot_id,reused};
+    let reason=!snapshot.identity.map_id?'map_id_missing':!endpoint.ok?endpoint.reason:args['no-remit']===true?'no_remit':null;
+    const consent=reason?null:resolveConsent({env,...(configPath?{configPath}:{}),proxyBase:endpoint.base,warn:()=>{}});
+    if (!reason&&consent.state!=='on') reason='consent_off';
+    if (!reason&&consent.scope_bypassed) reason='scoped_consent_required';
+    const key=reason?null:resolveKey?.(workspace.packet,workspace.packetPath,env)?.key;
+    if (!reason&&!key) reason='campaign_key_missing';
+    if (!reason) announceDefaultOnTelemetry(`${endpoint.base}${PROGRESS_ENDPOINT}`);
+    const remit=reason?{state:'skipped',reason,attempts:0,http_status:null}:await remitProgressSnapshot(snapshot,{base:endpoint.base,campaignKey:key,fetchImpl});
+    atomic(metaPath,{...remit,snapshot_id:snapshot.snapshot_id});
+    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; wait for the current writer. For abandoned or interrupted recovery, stop target writers and follow the offline lock recovery in 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'};
+  }
+}

package/src/progress.mjs

@@ -0,0 +1,133 @@
+// Portable wire contract. No filesystem, network, Node globals or lifecycle picker.
+export const PROGRESS_SCHEMA_VERSION = 'campaigns-os-progress-snapshot/v0';
+export const PROGRESS_STAGES = ['prepare_build', 'setup', 'assembly', 'polish', 'deploy', 'qa'];
+export const PROGRESS_CONTINUATIONS = ['prepare-build', 'doctor-blocked', 'setup', 'build', 'polish', 'deploy', 'qa', 'done', 'unknown'];
+export const PROGRESS_STAGE_STATUSES = ['pending', 'required', 'blocked', 'completed', 'completed_with_warnings', 'skipped', 'unknown'];
+export const PROGRESS_GATE_IDS = ['doctor', 'prepare_build', 'theme_gate', 'polish_gate', 'page_kit.sdk_version', 'page_kit.store_profile', 'built_output.upsell_selector_scope', 'polish.hidden_eager_media', 'unknown'];
+export const PROGRESS_ACTION_IDS = [
+  'doctor_recheck', 'restore_prepare_build_binding', 'recheck', 'rerun_prepare_build',
+  'divergence_inspect', 'setup_skill', 'build_skill', 'build_local_proof', 'build_production_parity',
+  'polish_skill', 'deploy', 'advance', 'install_browser', 'qa_run', 'run_end', 'run_record_present',
+  'run_record_remit_recovery', 'run_record_closeout', 'purchase_proof_unknown',
+  'theme_gate.starter_palette_blocks_qa', 'theme_gate.brand_contract_unreadable',
+  'theme_gate.theme_generate', 'theme_gate.apply_brand_layer', 'theme_gate.waive_theme', 'theme_gate.fix_load_order',
+  'polish_gate.rerun_build', 'polish_gate.run_polish', 'polish_gate.repair_waiver',
+  'checkpoint.page_kit.sdk_version.repair_spec', 'checkpoint.page_kit.sdk_version.refresh_spec',
+  'checkpoint.page_kit.store_profile.repair_spec', 'checkpoint.built_output.upsell_selector_scope.repair_selectors',
+  ...['page_kit.sdk_version', 'page_kit.store_profile', 'built_output.upsell_selector_scope'].flatMap(id => ['repair_target', 'align_store_profile', 'align_sdk_version', 'repair_waiver', 'waive'].map(action => `checkpoint.${id}.${action}`)),
+  ...['capture', 'install_browser', 'repair', 'repair_authority', 'local_proof_rebuild', 'waive'].map(action => `checkpoint.polish.hidden_eager_media.${action}`),
+  'unknown',
+];
+const str = pattern => ({type:'string', pattern});
+const hash = {type:['string','null'], pattern:'^sha256:[0-9a-f]{64}$'};
+const opaque = {type:['string','null'], pattern:'^[A-Za-z0-9_-]{1,64}$'};
+const enumeration = values => ({enum:values});
+const object = properties => ({type:'object', additionalProperties:false, required:Object.keys(properties), properties});
+export const PROGRESS_SNAPSHOT_SCHEMA = {
+  $schema:'https://json-schema.org/draft/2020-12/schema',
+  $id:'https://nextcommerce.com/schemas/campaigns-os-progress-snapshot.v0.schema.json',
+  title:'Campaigns OS minimal progress observation v0',
+  ...object({
+    schema_version:{const:PROGRESS_SCHEMA_VERSION}, snapshot_id:str('^sha256:[0-9a-f]{64}$'),
+    stream_id:str('^progress_[0-9a-f]{32}$'), sequence:{type:'integer',minimum:1,maximum:2147483647},
+    previous_snapshot_id:hash, observed_at:str('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$'),
+    package_version:str('^\\d{1,6}\\.\\d{1,6}\\.\\d{1,6}$'), producer:enumeration(['next','qa']),
+    identity:object({map_id:opaque,map_revision_hash:hash,map_revision_algorithm:{const:'map-store-v1'},
+      saved_revision_alignment:enumeration(['aligned','unconfirmed']),local_spec_material_hash:hash,
+      local_spec_material_algorithm:{const:'campaign-spec-material-v1'},build_fingerprint:hash,
+      build_fingerprint_algorithm:{const:'sha256-manifest/v1'}}),
+    stages:{type:'array',minItems:6,maxItems:6,items:object({stage:enumeration(PROGRESS_STAGES),status:enumeration(PROGRESS_STAGE_STATUSES),
+      build_binding:enumeration(['matching','unconfirmed']),source_build_fingerprint:hash})},
+    preview:object({present:{type:'boolean'},url_hash:hash}),
+    continuation:object({stage:enumeration(PROGRESS_CONTINUATIONS),blocked:{type:'boolean'},divergent:{type:'boolean'},
+      action_ids:{type:'array',maxItems:64,uniqueItems:true,items:enumeration(PROGRESS_ACTION_IDS)},
+      gates:{type:'array',maxItems:16,items:object({id:enumeration(PROGRESS_GATE_IDS),state:enumeration(['pass','blocked','waived','not_applicable','unknown'])})}}),
+    qa:{anyOf:[{type:'null'},object({verdict_id:opaque,disposition:enumeration(['ready','ready_with_exceptions','blocked','unknown']),
+      binding:enumeration(['matching','unconfirmed']),publish_state:enumeration(['skipped','ok','failed','unknown'])})]},
+  }),
+};
+export function canonicalProgressJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalProgressJson).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key=>`${JSON.stringify(key)}:${canonicalProgressJson(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+export async function progressDigest(value, cryptoImpl = globalThis.crypto) {
+  const bytes = new TextEncoder().encode(canonicalProgressJson(value));
+  const digest = await cryptoImpl.subtle.digest('SHA-256',bytes);
+  return `sha256:${Array.from(new Uint8Array(digest),byte=>byte.toString(16).padStart(2,'0')).join('')}`;
+}
+export async function progressSnapshotId(snapshot, cryptoImpl) {
+  const {snapshot_id:ignored,...content} = snapshot;
+  return progressDigest(content,cryptoImpl);
+}
+// Small bounded validator for exactly the schema vocabulary above. Fixed error codes,
+// never values or property names from an untrusted payload.
+export function validateProgressSnapshot(value) {
+  const errors = [];
+  let count = 0;
+  function check(data,schema,depth=0) {
+    if (++count>2048 || depth>12) return false;
+    if (schema.anyOf) return schema.anyOf.some(branch=>check(data,branch,depth+1));
+    if (Object.hasOwn(schema,'const') && data!==schema.const) return false;
+    if (schema.enum && !schema.enum.includes(data)) return false;
+    if (schema.type) {
+      const type = data===null?'null':Array.isArray(data)?'array':typeof data==='number'&&Number.isInteger(data)?'integer':typeof data;
+      const allowed = Array.isArray(schema.type)?schema.type:[schema.type];
+      if (!allowed.includes(type)) return false;
+    }
+    if (typeof data==='string' && schema.pattern && !new RegExp(schema.pattern).test(data)) return false;
+    if (typeof data==='number' && (data<schema.minimum||data>schema.maximum)) return false;
+    if (Array.isArray(data)) {
+      if (data.length<(schema.minItems||0)||data.length>(schema.maxItems||0)) return false;
+      if (Object.keys(data).length!==data.length) return false;
+      if (schema.uniqueItems && new Set(data).size!==data.length) return false;
+      return data.every(item=>check(item,schema.items,depth+1));
+    }
+    if (data && typeof data==='object') {
+      if (!schema.properties || Object.keys(data).some(key=>!Object.hasOwn(schema.properties,key))) return false;
+      if (schema.required.some(key=>!Object.hasOwn(data,key))) return false;
+      return Object.entries(data).every(([key,item])=>check(item,schema.properties[key],depth+1));
+    }
+    return true;
+  }
+  if (!check(value,PROGRESS_SNAPSHOT_SCHEMA)) errors.push('progress.invalid_shape');
+  if (!errors.length && (new Set(value.stages.map(stage=>stage.stage)).size!==6 || value.stages.some((stage,index)=>stage.stage!==PROGRESS_STAGES[index]))) errors.push('progress.invalid_stages');
+  if (!errors.length && value.identity.saved_revision_alignment==='aligned' && (!value.identity.map_id||!value.identity.map_revision_hash||!value.identity.local_spec_material_hash)) errors.push('progress.invalid_alignment');
+  if (!errors.length && value.continuation.gates.some(gate=>gate.id==='unknown'&&gate.state!=='unknown')) errors.push('progress.unsupported_authority');
+  if (!errors.length && value.sequence===1 && value.previous_snapshot_id!==null) errors.push('progress.invalid_chain');
+  if (!errors.length && value.sequence>1 && value.previous_snapshot_id===null) errors.push('progress.invalid_chain');
+  if (!errors.length && value.stages.some(stage=>stage.build_binding==='matching'&&(!value.identity.build_fingerprint||stage.source_build_fingerprint!==value.identity.build_fingerprint))) errors.push('progress.invalid_build_binding');
+  if (!errors.length && value.qa?.binding==='matching'&&(!value.qa.verdict_id||!value.identity.build_fingerprint||value.stages.find(stage=>stage.stage==='qa').build_binding!=='matching')) errors.push('progress.invalid_qa_binding');
+  if (!errors.length && (value.continuation.stage==='unknown'||value.continuation.action_ids.includes('unknown')||value.continuation.gates.some(gate=>gate.id==='unknown'||gate.state==='unknown'))&&!value.continuation.blocked) errors.push('progress.unsupported_authority');
+  if (!errors.length && value.preview.present!==(value.preview.url_hash!==null)) errors.push('progress.invalid_preview');
+  if (!errors.length && value.continuation.divergent&&!value.continuation.blocked) errors.push('progress.invalid_divergence');
+  if (!errors.length && !Number.isFinite(Date.parse(value.observed_at))) errors.push('progress.invalid_time');
+  return {ok:errors.length===0,errors};
+}
+export async function verifyProgressSnapshot(snapshot,cryptoImpl) {
+  const checked=validateProgressSnapshot(snapshot);
+  if (!checked.ok) return checked;
+  return (await progressSnapshotId(snapshot,cryptoImpl))===snapshot.snapshot_id?checked:{ok:false,errors:['progress.digest_mismatch']};
+}
+// Identity groups include build, local spec and saved revision; never merge stages
+// across builds. Histories contain whole observations, not a readiness decision.
+export async function groupProgressHistories(snapshots,{cryptoImpl,maxSnapshots=256}={}) {
+  if (!Array.isArray(snapshots)||snapshots.length>Math.min(maxSnapshots,256)) return {ok:false,groups:[],errors:['progress.history_bound']};
+  const groups=new Map(); let rejected=0;
+  for (const snapshot of snapshots) {
+    if (!(await verifyProgressSnapshot(snapshot,cryptoImpl)).ok) {rejected++;continue;}
+    const key=canonicalProgressJson({identity:snapshot.identity,stream_id:snapshot.stream_id});
+    if (!groups.has(key)) groups.set(key,[]);
+    groups.get(key).push(snapshot);
+  }
+  return {ok:rejected===0,errors:rejected?['progress.invalid_history_member']:[],groups:[...groups.values()].map(items=>{
+    const unique=[...new Map(items.map(item=>[item.snapshot_id,item])).values()].sort((a,b)=>a.sequence-b.sequence);
+    const conflicted=new Set(unique.map(item=>item.sequence)).size!==unique.length;
+    const incomplete=unique[0].sequence!==1 || unique.some((item,index)=>index>0&&(item.sequence!==unique[index-1].sequence+1||item.previous_snapshot_id!==unique[index-1].snapshot_id));
+    return {identity:unique[0].identity,stream_id:unique[0].stream_id,state:conflicted?'conflicted':incomplete?'incomplete':unique[0].identity.saved_revision_alignment!=='aligned'||!unique[0].identity.build_fingerprint?'unconfirmed':'observed',snapshots:unique};
+  })};
+}
+export function progressStorageKey(snapshot,scopeHash) {
+  if (!validateProgressSnapshot(snapshot).ok||!/^sha256:[0-9a-f]{64}$/.test(scopeHash)||!snapshot.identity.map_id||!snapshot.identity.map_revision_hash) return null;
+  return `progress:v0:${scopeHash.slice(7)}:${snapshot.identity.map_id}:${snapshot.identity.map_revision_hash.slice(7)}:${snapshot.stream_id}:${snapshot.sequence}:${snapshot.snapshot_id.slice(7)}`;
+}