@nextcommerce/campaigns-os 1.34.1 → 1.37.2

package/src/cli.mjs

@@ -1,5 +1,6 @@
 import { withHtmlScanSnapshot, readHtmlScanText, htmlScanDigest } from "./html-scan.mjs";
 import { createHash, randomUUID } from "node:crypto";
+import { createDemo, demoArguments } from "./demo.mjs";
 import { execFileSync } from "node:child_process";
 import {
   accessSync,
@@ -22,6 +23,8 @@ import { homedir } from "node:os";
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { shellToken } from "./shell-token.mjs";
+import { diagnosticExport, diagnosticTextLines } from "./diagnostic.mjs";
+import { observeProgress, PROGRESS_OBSERVATION } from "./progress-node.mjs";
 import { describeSdkIgnoredMetaTags, isSdkIgnoredMetaTag } from "./sdk-meta-tags.mjs";
 import { HIDDEN_EAGER_MEDIA_ACTIONS, requiredActionText, substitutePacket } from "./gate-actions.mjs";
 import { ORDER_PATH_DEPTH_DRIFT_CODE, orderPathDepthDriftText, orderPathDepthReconcileAction, orderPathDepthsDisagree, parseOrderPathDepthFlag } from "./proof-policy.mjs";
@@ -444,6 +447,7 @@ const HELP = `Campaigns OS toolkit
 
 Usage:
   campaigns-os help
+  campaigns-os demo --target <new-directory>   # offline inert sample; open landing/index.html; no campaign evidence
   campaigns-os start (--spec <json> | --map-id <id>) --source <html-dir> --target <page-kit-dir> --template-family <family>
                      [--brief <yaml|json>] [--proxy-base <url>] [--cached-spec] [--theme-policy <inspect_only|auto|off>]
                      [--wrapper-policy <strip_document_wrappers|preserve_document_wrappers|not_required|unknown>] [--design-manifest <path>]
@@ -472,8 +476,9 @@ Usage:
   campaigns-os validate-assembly-report --report <json> [--json]
   campaigns-os install-skills [--platform <claude|codex|agents|all>] [--target <skills-dir>] [--dry-run] [--json]
   campaigns-os tooling status [--platform <claude|codex|agents|all>] [--target <skills-dir>] [--json]   # install-mode (checkout or pinned package), git, and skill freshness preflight
+  campaigns-os tooling diagnose [--packet <packet>] [--platform <claude|codex|agents|all>] [--json]   # read-only redacted support summary
   campaigns-os install-agent-context --target <page-kit-dir> [--dry-run]
-  campaigns-os next --packet <json> [--json]                       # self-decide next stage; returns gates[] + next_actions[] (exact commands) alongside the prompt
+  campaigns-os next --packet <json> [--no-write] [--no-remit] [--proxy-base <url>] [--json]                       # self-decide next stage; returns gates[] + next_actions[] (exact commands) alongside the prompt
   campaigns-os next setup --packet <json> [--context <json>] [--report <json>] [--json]
   campaigns-os next build --packet <json> [--context <json>] [--report <json>] [--json]
   campaigns-os next polish --packet <json> --report <json> [--json]
@@ -598,6 +603,24 @@ export async function main(argv) {
   if (args._[0] === "campaigns-os") args._.shift();
   const command = args._[0] || "help";
 
+  // An offline sample must not recover sessions or emit lifecycle evidence.
+  if (command === "demo") {
+    // Validate raw tokens here: parsing loses duplicate flags. The private
+    // dispatcher then rechecks the parsed shape and extracts the target.
+    demoArguments(args, argv);
+    await dispatch(command, args);
+    return;
+  }
+
+  // Diagnostic export is an inspection, including when a run is active or
+  // stale. Bypass session sweeping, ambient resolution, and lifecycle capture
+  // so no closeout/remit or journal write can occur before the projection.
+  if (command === "tooling" && args._[1] === "diagnose") {
+    const result = toolingDiagnose(args);
+    console.log(args.json ? JSON.stringify(result, null, 2) : diagnosticTextLines(result).join("\n"));
+    return;
+  }
+
   // Ambient run session (Tier 3): when `run start` is active, every command
   // shares its run_id WITHOUT --run-id. Explicit --run-id still wins. Resolved
   // ONCE here and threaded through dispatch + persistence so the run_id a
@@ -1010,6 +1033,17 @@ const PREPARE_MODES = Object.freeze({
 });
 
 async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null, sessionHolder = null) {
+  if (command === "demo") {
+    // main() already validated raw argv before entering this private function.
+    const target = demoArguments(args);
+    if (target === null) {
+      console.log("campaigns-os demo --target <new-directory>\nOffline Apollo sample only. Open the printed landing/index.html file. Start a real campaign in a separate new Page Kit folder; preserve your sample edits.");
+      return;
+    }
+    const result = createDemo(target);
+    console.log(`Offline sample only; no campaign evidence.\nOpen: ${result.index}\nStart a real campaign in a separate new Page Kit folder. Preserve sample edits; demo is never converted automatically.`);
+    return;
+  }
   if (command === "help" || (args.help && command !== "qa")) {
     console.log(HELP);
     return;
@@ -1171,6 +1205,7 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     // explicit stage (`next build`, `next polish`, etc.) is unchanged.
     const stage = args._[1] || null;
     const result = nextStage(stage, args, ambient);
+    await observeProgress(args, result, { packageVersion: packageVersion(), resolveKey: resolveCampaignsApiKeySource });
     writeResult(result, args, result.ok ? 0 : 2);
     printNextTinyPrompt(result, args);
     return;
@@ -1182,7 +1217,14 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     // command a QA run prints has to agree with the run_id this session will
     // later close and remit under.
     const result = await runQaCli(args, { ambient });
-    if (args._[1] === "run" && result?.verdict) recordQaStageOutcome(args, result);
+    if (args._[1] === "run" && result?.verdict && recordQaStageOutcome(args, result)) {
+      // Observe committed QA before the existing closeout; this cannot close
+      // a run or change the QA disposition. Reuse the canonical picker.
+      try {
+        const continuation = nextStage(null, { ...args, "no-write": true }, null);
+        await observeProgress(args, continuation, { qaResult: result, packageVersion: packageVersion(), resolveKey: resolveCampaignsApiKeySource });
+      } catch { /* optional progress never changes lifecycle closeout */ }
+    }
     if (sessionHolder) sessionHolder.qaResult = result;
     return;
   }
@@ -1327,7 +1369,10 @@ async function resolveSpecPath(args, opts = {}) {
     const spec = await fetchSpecByMapId(mapId, { proxyBase, fetchImpl: opts.fetchImpl });
     mkdirSync(cacheDir, { recursive: true });
     writeFileSync(cachePath, `${JSON.stringify(spec, null, 2)}\n`);
-    return { specPath: cachePath, source: "remote", mapId, proxyBase };
+    return { specPath: cachePath, source: "remote", mapId, proxyBase,
+      savedMapRevision: { map_id: mapId, hash: spec.spec_identity?.spec_hash || spec.spec_hash || null,
+        algorithm: "map-store-v1", local_spec_material_hash: specMaterialHash(spec) },
+    };
   }
   throw new Error(
     "Either --spec <path> or --map-id <id> is required. " +
@@ -2478,6 +2523,7 @@ function prepareBuild(args, options = {}) {
       : null,
     map_id: specInput?.mapId || null,
     proxy_base: specInput?.proxyBase || null,
+    saved_map_revision: specInput?.savedMapRevision || null,
     source_root: portable(sourceRoot),
     target_repo: portable(targetRepo),
     template_family: explicitTemplateFamily || null,
@@ -9500,6 +9546,10 @@ export function nextStage(stage, args, ambient = null) {
     runRecordCloseout = null;
   }
   const finalize = (result) => {
+    Object.defineProperty(result, PROGRESS_OBSERVATION, { value: {
+      workspace: { packet, packetPath, targetRepo, contextPath, reportPath },
+      context: readJsonIfExists(contextPath), report, doctor,
+    } });
     if (divergences.length) result.divergences = divergences;
     result.gates = buildNextGates({ doctor, report, themeGate, polishGate, prepareBuildGate, packetPath });
     result.next_actions = buildNextActions({ result, packetPath, packet, themeGate, polishGate, polishCheckpointGate, prepareBuildGate, ambient, runRecordCloseout, purchaseProof, brandContract: doctor.derived?.brand_contract || null, context: readJsonIfExists(contextPath), targetRepo });
@@ -10917,7 +10967,9 @@ function toolingCommand(args) {
   } else if (install.mode !== "checkout" && cli.global_binary.status === "found_other_install") {
     // An npx cache is ephemeral: never tell the operator to put its .bin on
     // PATH. The pinned npx form is what makes the inspected copy run.
-    warnings.push(install.mode === "npx_cache"
+    warnings.push(install.mode === "global"
+      ? `The campaigns-os on PATH is a different install; use \`${cli.invocation_prefix} <command>\` to run the global copy inspected here.`
+      : install.mode === "npx_cache"
       ? `The campaigns-os on PATH (${cli.global_binary.path}) is a different install from the one inspected here (${install.location}); bare commands would run that other copy. Use \`${cli.invocation_prefix} <command>\` so the pinned copy runs.`
       : cli.bin_dir
         ? `The campaigns-os on PATH (${cli.global_binary.path}) is a different install from the one inspected here (${cli.local_bin}); bare commands would run that other copy. Run export PATH="${cli.bin_dir}:$PATH" to put this install first.`
@@ -10948,6 +11000,24 @@ function toolingCommand(args) {
   };
 }
 
+export function toolingDiagnose(args, { runTooling = toolingCommand, runDoctor = doctorCommand } = {}) {
+  let tooling = null;
+  let doctor = null;
+  let inspectionFailed = false;
+  const platform = args.platform || "all";
+  // Inputs are used only by local producers, never echoed, and mutation flags
+  // are not forwarded. Even an exception's message may contain a secret path.
+  try {
+    tooling = runTooling({ _: ["tooling", "status"], platform, ...(typeof args.target === "string" ? { target: args.target } : {}) });
+  } catch { /* unavailable, no raw producer exception in a support export */ }
+  if (args.packet !== undefined) {
+    try {
+      doctor = runDoctor({ packet: args.packet, "no-write": true, ...(typeof args.context === "string" ? { context: args.context } : {}), ...(typeof args.report === "string" ? { report: args.report } : {}) });
+    } catch { inspectionFailed = true; }
+  }
+  return diagnosticExport({ tooling, doctor, platform, inspectionFailed });
+}
+
 function localCliStatus(pkg, install = { mode: "checkout", pinned: null }) {
   const resolved = resolveInvocation(ROOT, pkg, install);
   return {

package/src/consent.mjs

@@ -298,7 +298,7 @@ let defaultOnAnnounced = false;
 export function announceDefaultOnTelemetry(endpoint, { write = (line) => process.stderr.write(line) } = {}) {
   if (defaultOnAnnounced) return false;
   defaultOnAnnounced = true;
-  write(`[campaigns-os] Run telemetry is ON by default: anonymized run records are sent to ${endpoint || CANONICAL_REMIT_SCOPE} to improve templates, tooling, and guidance. Disable with \`campaigns-os telemetry off\` or CAMPAIGNS_OS_TELEMETRY=off.\n`);
+  write(`[campaigns-os] Run telemetry is ON by default: anonymized run records and minimal stage observations are sent to ${endpoint || CANONICAL_REMIT_SCOPE} to improve templates, tooling, and guidance; stage observations support Workspace progress. Disable with \`campaigns-os telemetry off\` or CAMPAIGNS_OS_TELEMETRY=off.\n`);
   return true;
 }
 
@@ -338,7 +338,7 @@ export async function promptAndPersistConsent({
   if (!isTTY) return { state: "off", source: "default", resolved: false, prompted: false };
 
   const answer = await ask(
-    "Campaigns OS can send build telemetry to Next Commerce to improve templates, tools, and guidance. Share telemetry from this machine? [Y/n] (change any time): ",
+    "Campaigns OS can send build telemetry and minimal stage observations to Next Commerce to improve templates, tools, and guidance; stage observations support Workspace progress. Share telemetry from this machine? [Y/n] (change any time): ",
   );
   const normalized = String(answer || "").trim().toLowerCase();
   const state = (normalized === "" || ["y", "yes", "1", "true", "on"].includes(normalized)) ? "on" : "off";

package/src/demo-artifact.mjs

@@ -0,0 +1,97 @@
+// Validator for the one reviewed bundled projection; never a general sanitizer.
+import {readFileSync,readdirSync,lstatSync} from 'node:fs';
+import {createHash} from 'node:crypto';
+import {join,posix} from 'node:path';
+import {parse,parseFragment} from 'parse5';
+export const DEMO_ROUTES=['landing','checkout','upsell-bundle-stepper','receipt'];
+export const DEMO_CSP="default-src 'none'; img-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self'; form-action 'none'; base-uri 'none'; connect-src 'none'; frame-src 'none'; object-src 'none'";
+const digest=bytes=>`sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const allowedPath=name=>/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_.-]+)*\.(?:html|css|svg|png|jpe?g|webp|gif|woff2?|txt|json)$/.test(name)&&!name.split('/').some(part=>part==='.'||part==='..');
+const image=name=>/\.(?:svg|png|jpe?g|webp|gif)$/.test(name);
+const inactiveTags=new Set(['script','iframe','frame','frameset','object','embed','base','form','noscript','template','foreignobject','animate','animatetransform','animatemotion','set','audio','video']);
+const resourceAttrs=new Set(['href','xlink:href','src','srcset','poster','data','action','formaction','ping','background','manifest','profile','codebase','archive','dynsrc','lowsrc','srcdoc']);
+function localReference(value,from,files,{fragment=false}={}) {
+  if(fragment&&/^#[A-Za-z_][A-Za-z0-9_.:-]*$/.test(value))return null;
+  if(typeof value!=='string'||!value||/[\\%?#\s\u0000-\u001f]/.test(value)||value.startsWith('/')||/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value))throw Error('demo.resource_invalid');
+  const target=posix.normalize(posix.join(posix.dirname(from),value));
+  if(!allowedPath(target)||!files.has(target))throw Error('demo.resource_missing');
+  return target;
+}
+function cssText(text,from,files) {
+  // Decode CSS escapes before inspecting resource constructs, including escaped
+  // identifiers. This projection has no imports, image-set or active behavior.
+  const decoded=text.replace(/\\([0-9a-f]{1,6})(?:\r\n|[\t\n\r\f ])?/gi,(_,hex)=>String.fromCodePoint(Math.min(parseInt(hex,16)||0xfffd,0x10ffff))).replace(/\\([^\n\r\f])/g,'$1').replace(/\/\*[\s\S]*?\*\//g,'');
+  if(/@import\b|\b(?:image-set|expression|element)\s*\(|-moz-binding|behavior\s*:/i.test(decoded))throw Error('demo.css_active');
+  for(const match of decoded.matchAll(/url\s*\(\s*([^)]*)\)/gi)) {
+    let value=match[1].trim();if(/^(['"])[\s\S]*\1$/.test(value))value=value.slice(1,-1);
+    const target=localReference(value,from,files,{fragment:true});
+    if(target&&!image(target)&&!/\.woff2?$/.test(target))throw Error('demo.css_resource_invalid');
+  }
+  if((decoded.match(/url\s*\(/gi)||[]).length!==[...decoded.matchAll(/url\s*\(\s*([^)]*)\)/gi)].length)throw Error('demo.css_invalid');
+}
+function markup(text,from,files,{svg=false}={}) {
+  if(svg&&(/<!doctype/i.test(text)||/<\?(?!xml(?:\s|\?))/i.test(text)))throw Error('demo.svg_document_active');
+  const document=svg?parseFragment(text):parse(text);let head=null,banner=false,nav=0,csp=0;
+  function visit(node) {
+    const tag=node.tagName?.toLowerCase();const attrs=Object.fromEntries((node.attrs||[]).map(attr=>[attr.prefix?`${attr.prefix}:${attr.name}`:attr.name,attr.value]));
+    if(inactiveTags.has(tag)||node.content)throw Error('demo.markup_active');
+    if(tag==='head')head=node;
+    if(attrs.role==='button'&&attrs['aria-disabled']!=='true')throw Error('demo.control_active');
+    if(tag==='aside'&&attrs['data-demo-banner']==='true')banner=true;
+    if(['button','input','select','textarea'].includes(tag)&&!Object.hasOwn(attrs,'disabled'))throw Error('demo.control_active');
+    for(const [name,value] of Object.entries(attrs)) {
+      if(/^on/i.test(name)||/^data-next-|^os-checkout-|^next-/.test(name))throw Error('demo.attribute_active');
+      if(name==='style')cssText(value,from,files);
+      if(!resourceAttrs.has(name))continue;
+      let target;
+      if(tag==='a'&&name==='href'&&attrs['data-demo-nav']==='true') {
+        target=localReference(value,from,files);if(!DEMO_ROUTES.some(route=>target===`${route}/index.html`))throw Error('demo.navigation_invalid');nav++;
+      }else if(tag==='link'&&name==='href'&&attrs.rel==='stylesheet') {
+        target=localReference(value,from,files);if(!target.endsWith('.css'))throw Error('demo.stylesheet_invalid');
+      }else if(tag==='img'&&name==='src') {
+        target=localReference(value,from,files);if(!image(target))throw Error('demo.image_invalid');
+      }else if(['use','image'].includes(tag)&&['href','xlink:href'].includes(name)) {
+        target=localReference(value,from,files,{fragment:true});if(target&&!image(target))throw Error('demo.svg_reference_invalid');
+      }else throw Error('demo.resource_attribute_invalid');
+    }
+    if(tag==='meta'&&Object.hasOwn(attrs,'http-equiv')) {
+      if(attrs['http-equiv'].toLowerCase()!=='content-security-policy'||attrs.content!==DEMO_CSP)throw Error('demo.policy_invalid');csp++;
+    }
+    if(tag==='style')cssText((node.childNodes||[]).map(child=>child.value||'').join(''),from,files);
+    for(const child of node.childNodes||[])visit(child);
+  }
+  visit(document);
+  if(!svg) {
+    const first=(head?.childNodes||[]).find(node=>node.tagName);
+    if(csp!==1||first?.tagName!=='meta'||!banner||nav!==4)throw Error('demo.shell_invalid');
+  }
+}
+export function validateDemoArtifact(root) {
+  const files=new Map();let total=0;
+  function collect(dir,prefix='') {
+    for(const name of readdirSync(dir).sort()) {
+      const path=join(dir,name),stat=lstatSync(path),relative=prefix?`${prefix}/${name}`:name;
+      if(stat.isSymbolicLink())throw Error('demo.symlink_invalid');
+      if(stat.isDirectory()){if(!/^[A-Za-z0-9_-]+$/.test(name))throw Error('demo.path_invalid');collect(path,relative);continue;}
+      if(!stat.isFile()||!allowedPath(relative)||stat.size>2097152||(total+=stat.size)>8388608||files.size>=256)throw Error('demo.file_invalid');
+      files.set(relative,readFileSync(path));
+    }
+  }
+  collect(root);
+  const provenance=JSON.parse(files.get('provenance.json')?.toString()||'null');
+  if(provenance?.schema_version!=='campaigns-os-inert-demo/v0'||provenance.template_commit!=='11352c30c596db258679fd3a552b906086b11bb9'||provenance.page_kit_version!=='0.2.0'||provenance.tailwind_version!=='3.4.17'||JSON.stringify(provenance.routes)!==JSON.stringify(DEMO_ROUTES))throw Error('demo.provenance_invalid');
+  const expected=provenance.output_hashes;
+  const provenanceFields=['schema_version','template_commit','page_kit_version','page_kit_commit','tailwind_version','routes','typography','input_hashes','toolchain_lock_hash','output_hashes'];
+  if(Object.keys(provenance).length!==provenanceFields.length||Object.keys(provenance).some(name=>!provenanceFields.includes(name))||provenance.page_kit_commit!=='eed0679b1d02ef5cbe7f21964165c4202724d91d'||provenance.typography!=='system-ui, sans-serif'||!/^sha256:[0-9a-f]{64}$/.test(provenance.toolchain_lock_hash)||!provenance.input_hashes||Object.keys(provenance.input_hashes).length>256||Object.entries(provenance.input_hashes).some(([name,value])=>!/^(?:src\/explore|rendered|_data)\/[A-Za-z0-9_./-]+$/.test(name)||name.split('/').includes('..')||!/^sha256:[0-9a-f]{64}$/.test(value)))throw Error('demo.provenance_invalid');
+  if(!expected||Object.keys(expected).length!==files.size-1||Object.keys(expected).some(name=>!files.has(name)||name==='provenance.json'))throw Error('demo.manifest_invalid');
+  for(const [name,bytes] of files) {
+    if(name!=='provenance.json'&&expected[name]!==digest(bytes))throw Error('demo.digest_mismatch');
+    if(name.endsWith('.html')){if(!DEMO_ROUTES.some(route=>name===`${route}/index.html`))throw Error('demo.route_invalid');markup(bytes.toString(),name,files);}
+    if(name.endsWith('.svg'))markup(bytes.toString(),name,files,{svg:true});
+    if(name.endsWith('.css'))cssText(bytes.toString(),name,files);
+    if(name.endsWith('.json')&&name!=='provenance.json')throw Error('demo.json_invalid');
+  }
+  for(const route of DEMO_ROUTES)if(!files.has(`${route}/index.html`))throw Error('demo.route_missing');
+  if(!files.has('NOTICE.txt'))throw Error('demo.notice_missing');
+  return {files,provenance,totalBytes:total};
+}

package/src/demo.mjs

@@ -0,0 +1,85 @@
+import { mkdirSync, openSync, fstatSync, lstatSync, writeFileSync, closeSync, unlinkSync, rmdirSync, realpathSync } from "node:fs";
+import { resolve, dirname, basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateDemoArtifact } from "./demo-artifact.mjs";
+
+const BUNDLE = fileURLToPath(new URL("../demo/apollo-v0", import.meta.url));
+const TARGET_CHANGED_MESSAGE = "demo.target_changed: destination changed during copy; inspect and preserve its files, then retry with a different new directory";
+const same = (left, right) => left.dev === right.dev && left.ino === right.ino;
+function owns(path, stat) {
+  try { const current = lstatSync(path); return !current.isSymbolicLink() && same(current, stat); } catch { return false; }
+}
+
+export function resolveDemoTarget(target, { resolveParent = realpathSync } = {}) {
+  if (typeof target !== "string" || !target.trim()) throw Error("demo.target_required: use --target <new-directory>");
+  const destination = resolve(target), name = basename(destination);
+  if (!name) throw Error("demo.target_invalid: choose a new directory below an existing parent");
+  return join(resolveParent(dirname(destination)), name);
+}
+
+// Exclusive creation only. Failure cleanup removes precisely the entries this
+// invocation created, and never recursively removes a caller's directory.
+export function createDemo(target, { bundle = BUNDLE, writeBytes = writeFileSync } = {}) {
+  if (typeof target !== "string" || !target.trim()) throw Error("demo.target_required: use --target <new-directory>");
+  const artifact = validateDemoArtifact(bundle);
+  // Resolve the existing parent once; mkdir remains exclusive at the final
+  // component, so an existing directory, file or symlink cannot be overwritten.
+  const root = resolveDemoTarget(target);
+  const directories = [], files = [];
+  function directory(path) {
+    mkdirSync(path);
+    const stat = lstatSync(path);
+    directories.push({ path, stat });
+    return stat;
+  }
+  let rootStat;
+  try { rootStat = directory(root); } catch (error) {
+    if (error.code === "EEXIST") throw Error("demo.target_exists: choose a new directory; demo never merges or overwrites");
+    throw error;
+  }
+  const created = new Map([[root, rootStat]]);
+  try {
+    for (const [name, bytes] of artifact.files) {
+      const path = join(root, name);
+      const parts = name.split("/"); parts.pop();
+      let current = root;
+      for (const part of parts) {
+        if (!owns(current, created.get(current))) throw Error(TARGET_CHANGED_MESSAGE);
+        current = join(current, part);
+        if (!created.has(current)) created.set(current, directory(current));
+      }
+      if (!owns(current, created.get(current))) throw Error(TARGET_CHANGED_MESSAGE);
+      const fd = openSync(path, "wx");
+      try {
+        files.push({ path, stat: fstatSync(fd) });
+        writeBytes(fd, bytes);
+      } finally { closeSync(fd); }
+    }
+  } catch (error) {
+    for (const entry of files.reverse()) if (owns(entry.path, entry.stat)) { try { unlinkSync(entry.path); } catch {} }
+    for (const entry of directories.reverse()) if (owns(entry.path, entry.stat)) { try { rmdirSync(entry.path); } catch {} }
+    throw error;
+  }
+  return { index: join(root, "landing", "index.html"), files: artifact.files.size };
+}
+
+export function demoArguments(args, argv = null) {
+  if (argv) {
+    const tokens = argv[0] === "campaigns-os" ? argv.slice(1) : argv;
+    const seen = new Set();
+    for (let index = 1; index < tokens.length; index++) {
+      const flag = tokens[index];
+      if (!["--target", "--help"].includes(flag) || seen.has(flag)) throw Error("demo.unsupported_arguments: only one --target and --help are supported");
+      seen.add(flag);
+      if (flag === "--target") {
+        if (!tokens[index + 1] || tokens[index + 1].startsWith("--")) throw Error("demo.target_required: use --target <new-directory>");
+        index++;
+      }
+    }
+  }
+  const unsupported = Object.keys(args).filter(name => !["_", "target", "help"].includes(name));
+  if (unsupported.length || args._.length !== 1 || (args.help !== undefined && args.help !== true)) throw Error("demo.unsupported_arguments: supported usage is demo --target <new-directory> or demo --help; no-write and dry-run are unsupported");
+  if (args.help) return null;
+  if (typeof args.target !== "string" || !args.target.trim()) throw Error("demo.target_required: use --target <new-directory>");
+  return args.target;
+}

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,