@nextcommerce/campaigns-os 1.37.3 → 1.43.1

package/src/cli.mjs

@@ -1,3 +1,4 @@
+import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch, localSpecIdentityFields } from "./spec-source-identity.mjs";
 import { withHtmlScanSnapshot, readHtmlScanText, htmlScanDigest } from "./html-scan.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { createDemo, demoArguments } from "./demo.mjs";
@@ -28,7 +29,10 @@ 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";
-import { specMaterialHash } from "./spec-identity.mjs";
+import { specMaterialHash, specHashesMatch } from "./spec-identity.mjs";
+// The same predicate stage-ledger.mjs judges a mutator's result with, imported
+// rather than re-stated so the waive preview and the commit agree by identity.
+import { isPlainObject } from "./repo-scan.mjs";
 import { anyAssemblyReportStageBlocked, applyDerivedAssemblyReportSummary, commitAssemblyReport, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, qaGatePassedForCurrentBuild, recordProducerStageOutcome } from "./stage-ledger.mjs";
 import { SESSION_ENDING_DISPOSITIONS, summarizePlaceholderTextGate, summarizePurchaseProof } from "./qa-verdict.mjs";
 import { assessRunRecordCloseout, identityMatches, latestMatchingRunRecord, reasonIsRemitRecovery } from "./run-record-closeout.mjs";
@@ -95,14 +99,19 @@ import { campaignSidecarPaths, resolveCampaignWorkspace, targetRepoFor } from ".
 import { canonicalPath, sameFile } from "./fs-identity.mjs";
 import { DEFAULT_PROXY_BASE, fetchSpecByMapId } from "./spec-fetch.mjs";
 import { writeMapSdkPin } from "./map-pin-writeback.mjs";
-import { discoverQaVerdicts, iterateQaVerdicts, qaVerdictCandidateScore, qaVerdictCandidateTime, qaVerdictPathHints } from "./qa-verdict-discovery.mjs";
-import { assertSecureProxyBase, boundedResponseText, DEFAULT_RUNS_ENDPOINT, describeRemitBaseKind, isLoopbackHostname, REMIT_RESULTS, remitRunRecord } from "./remit.mjs";
+import { qaVerdictIdentityMatch, discoverQaVerdicts, iterateQaVerdicts, qaVerdictCandidateScore, qaVerdictCandidateTime, qaVerdictPathHints } from "./qa-verdict-discovery.mjs";
+import { assertFetchAvailable, assertSecureProxyBase, boundedResponseText, DEFAULT_RUNS_ENDPOINT, describeRemitBaseKind, isLoopbackHostname, REMIT_RESULTS, remitRunRecord } from "./remit.mjs";
 import {
   aggregateLifecycleForRun,
   appendLifecycleEntry,
   LIFECYCLE_JOURNAL_REL_PATH,
   NOOP_RECORDER,
   readLifecycleJournal,
+  REFUSED_INVOCATION,
+  refusalSeen,
+  refused,
+  refusing,
+  runWithRefusalScope,
   withCommandLifecycle,
 } from "./lifecycle.mjs";
 import {
@@ -139,7 +148,7 @@ import {
   formatStandardizationReportMarkdown,
 } from "./standardization-report.mjs";
 import { singleLineDetail, singleLineField } from "./text-safety.mjs";
-import { derivePackagePin, invocationPrefixFor, localInstallStatus, resolveInvocation } from "./install-mode.mjs";
+import { derivePackagePin, invocationPrefixFor, LOCAL_INVOCATION_PREFIX, localInstallStatus, resolveInvocation } from "./install-mode.mjs";
 import {
   campaignRouteRoot,
   isAbsoluteHttpUrl,
@@ -292,7 +301,6 @@ import {
 } from "./spec-derive.mjs";
 import {
   adminApiBaseForStore,
-  defaultStoreTokenEnvVar,
   normalizeStoreSubdomain,
   parseStoreTokenSource,
   planStoreProfileDerive,
@@ -316,10 +324,11 @@ export { derivePackagePin, localInstallStatus };
 
 // Every command this CLI PRODUCES for an operator or agent to copy is spelled
 // once, here, for the install it runs from (see install-mode.mjs): bare
-// `campaigns-os` from a checkout, `npx campaigns-os` from a campaign folder
-// that pins the toolkit, `npx --yes <spec>` from an npx cache. Result payloads
-// are never rewritten after the fact — a path, a quoted argument or a data
-// value that happens to contain the words is left exactly as it is.
+// `campaigns-os` from a checkout, `npx --no-install campaigns-os` from a
+// campaign folder that pins the toolkit, `npx --yes <spec>` from an npx cache.
+// Result payloads are never rewritten after the fact — a path, a quoted
+// argument or a data value that happens to contain the words is left exactly
+// as it is.
 function cmd(verb, rest = "") {
   const prefix = invocationPrefixFor(ROOT);
   return `${prefix} ${verb}${rest ? ` ${rest}` : ""}`;
@@ -467,18 +476,23 @@ Usage:
   campaigns-os standardize --target <campaign-repo> [--family <family>] [--slug <slug>] [--sdk-support-policy <path.json>] [--field-contract <path.json>] [--no-doctor] [--json]
   campaigns-os theme inspect --packet <campaign-runtime.build.json> [--context <json>] [--theme-policy <inspect_only|auto|off>] [--json]
   campaigns-os theme generate --packet <campaign-runtime.build.json> [--context <json>] [--out-dir <dir>] [--force] [--json]
-  campaigns-os theme waive --packet <campaign-runtime.build.json> --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--report <json>] [--json]   # record an explicit theme-gate waiver on the assembly report; placeholders such as "operator" are refused
-  campaigns-os checkpoint waive --packet <campaign-runtime.build.json> --gate <checkpoint-id> --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"] [--report <json>] [--json]   # one bound is required; registered gates: page_kit.store_profile, page_kit.sdk_version, polish.hidden_eager_media, built_output.upsell_selector_scope
+  campaigns-os theme waive --packet <campaign-runtime.build.json> --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--report <json>] [--dry-run] [--json]   # record an explicit theme-gate waiver on the assembly report; placeholders such as "operator" are refused. --dry-run validates the same way and prints the waiver it would write, without touching the report
+  campaigns-os checkpoint waive --packet <campaign-runtime.build.json> --gate <checkpoint-id> --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"] [--report <json>] [--dry-run] [--json]   # one bound is required; registered gates: page_kit.store_profile, page_kit.sdk_version, polish.hidden_eager_media, built_output.upsell_selector_scope. --dry-run runs every check (named human, bounds, registered and waivable gate) and prints the waiver it would write, without touching the report
   campaigns-os page-kit sync --packet <campaign-runtime.build.json> [--dry-run] [--json]   # write the CampaignSpec's Store Profile fields (campaign.store_*) and SDK pin (global_config.sdk_version, runtime.sdk_version alias) into the target's _data/campaigns.json entry for the packet's route, printing a field-by-field diff; the recovery for a doctor blocked on page_kit.store_profile / page_kit.sdk_version after a fresh scaffold. Writes only those ten fields, only from usable spec values (a bad pin, a non-http URL, a non-tel: phone URI or the demo value itself is reported as not synced, status PARTIAL); exit 2 when the entry or the spec is missing, or the spec identifies another campaign.
-  campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json] [--report <json>] [--from-store <subdomain> [--store-token-source env:<VAR>]] [--write-map] [--proxy-base <url>]   # write the fields the target repo already states into the packet's local CampaignSpec (spec.local_path): the SDK pin from _data/campaigns.json[<route>].sdk_version (global_config.sdk_version, and the runtime.sdk_version alias when declared), each page's page_url from the page tree under src/<route>/ (filename or permalink), and the analytics ids the entry carries (gtm_id -> analytics.providers.gtm.containerId, fb_pixel_id -> analytics.providers.facebook.pixelId); prints a field-by-field before -> after diff and writes nothing else. Repo-derived fields only and no network by default; --from-store <subdomain> (the <store> of <store>.29next.store) also reads the store's Admin API with the token in env:<SUBDOMAIN>_ADMIN_TOKEN (or --store-token-source env:<VAR>; a token never goes on the command line) and writes the nine campaign.store_* Store Profile fields: store_name and store_url (primary domain) and store_phone/store_phone_tel from GET /store/, and store_terms/privacy/contact/returns/shipping as https://<primary domain>/<slug>/ from the one storefront page (GET /pages/) whose slug or title names each policy; an empty store field, no page or several never empties the spec's value. A field the repo or store cannot state (a scaffold's seeded pin, an unbound page, an empty or malformed id, an active page_kit.sdk_version waiver, an empty store field, an unbound policy page) is reported as not derived, status PARTIAL; exit 2 when the packet, the spec or the target entry is missing, the spec identifies another campaign, or the store cannot be read (credential missing, 401/403, no such store, unreachable). --write-map also records the derived pin into the saved Map's Build hints (Campaign Cart SDK version) through the proxy Worker (PUT /api/maps/<spec.map_id> under X-Campaign-Key, the packet's Campaigns API key, with the Map's spec_hash as the X-Spec-Hash precondition): written when the Map declares no pin or one behind the repo, unchanged when equal, refused (warning, exit 0) when the Map pin is ahead or cannot be ordered, failed (error, exit 2) when the key is missing or mismatched, the Map is gone, was saved in between, or the proxy refuses the body; the write is recorded on the Assembly Report evidence[] and in the result's map object. --proxy-base overrides the canonical proxy (https, or a loopback host over http); --dry-run reads the Map and reports would_write without a PUT.
+  campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json] [--report <json>] [--from-store <subdomain> [--store-token-source env:<VAR>]] [--write-map] [--proxy-base <url>]   # write the fields the target repo already states into the packet's local CampaignSpec (spec.local_path): the SDK pin from _data/campaigns.json[<route>].sdk_version (global_config.sdk_version, and the runtime.sdk_version alias when declared), each page's page_url from the page tree under src/<route>/ (filename or permalink), and the analytics ids the entry carries (gtm_id -> analytics.providers.gtm.containerId, fb_pixel_id -> analytics.providers.facebook.pixelId); prints a field-by-field before -> after diff and writes nothing else. Repo-derived fields only and no network by default; --from-store <subdomain> (the <store> of <store>.29next.store) also reads through campaigns-os login gateway credentials (--store-token-source env:<VAR> explicitly selects the warned break-glass Admin path; a token never goes on the command line) and writes the nine campaign.store_* Store Profile fields: store_name and store_url (primary domain) and store_phone/store_phone_tel from GET /store/, and store_terms/privacy/contact/returns/shipping as https://<primary domain>/<slug>/ from the one storefront page (GET /pages/) whose slug or title names each policy; an empty store field, no page or several never empties the spec's value. A field the repo or store cannot state (a scaffold's seeded pin, an unbound page, an empty or malformed id, an active page_kit.sdk_version waiver, an empty store field, an unbound policy page) is reported as not derived, status PARTIAL; exit 2 when the packet, the spec or the target entry is missing, the spec identifies another campaign, or the store cannot be read (credential missing, 401/403, no such store, unreachable). --write-map also records the derived pin into the saved Map's Build hints (Campaign Cart SDK version) through the proxy Worker (PUT /api/maps/<spec.map_id> under X-Campaign-Key, the packet's Campaigns API key, with the Map's spec_hash as the X-Spec-Hash precondition): written when the Map declares no pin or one behind the repo, unchanged when equal, refused (warning, exit 0) when the Map pin is ahead or cannot be ordered, failed (error, exit 2) when the key is missing or mismatched, the Map is gone, was saved in between, or the proxy refuses the body; the write is recorded on the Assembly Report evidence[] and in the result's map object. --proxy-base overrides the canonical proxy (https, or a loopback host over http); --dry-run reads the Map and reports would_write without a PUT.
   campaigns-os page-kit parity --packet <campaign-runtime.build.json> [--report <json>] [--json]   # local proof mode (deploy.target local-serve): render the current source in development and production through the target's page-kit into temp dirs, assert the served _site/ is the current development render and that production differs from it only in environment-gated output (same page set, same route slugs, same Campaign Cart pin and next-api-key); records stages.assembly.evidence.local_proof.production_parity, which doctor reads as local_proof.production_parity. Exit 2 on a non-gated difference.
   campaigns-os polish capture --packet <campaign-runtime.build.json> --base-url <url> [--report <json>] [--headed] [--auth-cookie <cookie>] [--json]
+  campaigns-os readback <target-repo-root> [--json] [--packet <path>] [--doctor <path>] [--context <path>] [--report <path>] [--qa-verdict <path>] [--findings <path>]   # read-only projection of one run's emitted artifacts (packet, doctor output, build context, assembly report, QA verdict, findings export): artifact states, per-artifact freshness against the checkout's HEAD reflog, doctor warning grouping, skip cascades and cross-artifact divergences. Writes nothing, starts no process, touches no network, and records no lifecycle entry; --json emits one campaigns-os-readback/v2 object (docs/readback.md). Exit 2 for a missing target root or a Build Packet set freshness cannot single out.
+  campaigns-os readback --example [--json]                                # project the bundled synthetic sample; freshness is not computable for it by design
   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 setup --target <campaign-directory> [--platform claude] [--dry-run] [--json]   # after installing the pinned project dependencies, install skills, connect Claude's context and install the QA browser; preserve existing pages and instructions, then restart the agent
+  campaigns-os login [--store <subdomain>]
+  campaigns-os logout [--store <subdomain>]
+  campaigns-os tooling status [--platform <claude|codex|agents|all>] [--target <skills-dir>] [--skills-revision <bundle-revision|skill-id@version>] [--packet <campaign-runtime.build.json>] [--force] [--json]   # install-mode, git, skill freshness, and local gateway login/store/expiry/reported version. --skills-revision checks the bundle revision the skill you loaded states on its first body line (or that one skill's <skill-id>@<version>) against the bundle THIS CLI ships: revision_check is match, mismatch or unchecked, and a mismatch prints the full status and exits 2 because skill text already in context cannot be refreshed by re-running — start a fresh session. The pin check reports one executable per project: the project pin first — the first exact spec for this package (x.y.z, =x.y.z or vx.y.z) on the walk up from the nearest package.json, devDependencies then dependencies in each, entering a workspace root and stopping there, never peerDependencies or optionalDependencies — then the Build Packet's campaigns_os_version (the project's campaign-runtime.build.json, or --packet <path>); the Pin: line names the key and manifest (or packet) each version came from; pin.status is match, stale_pin (the pin is not the running version), conflicting_pin (the two sources disagree) or unpinned (neither, or only a range; exit 0). stale_pin and conflicting_pin exit 2 with the file to change; --force (bare) overrides them, is reported as pin.forced and lands on the lifecycle journal entry. See docs/skills-revision.md
   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> [--no-write] [--no-remit] [--proxy-base <url>] [--json]                       # self-decide next stage; returns gates[] + next_actions[] (exact commands) alongside the prompt
+  campaigns-os next [${NEXT_STAGE_ORDER.join("|")}] --packet <json> [--no-write] [--no-remit] [--proxy-base <url>] [--json]   # no stage self-decides; returns gates[] + next_actions[] 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]
@@ -487,21 +501,24 @@ Usage:
   campaigns-os qa resolve --packet <json> [--base-url <url>] [--no-probe] [--probe-timeout-ms <ms>] [--json]   # probes the derived entry URLs; a dead route set reports routes_unresolved, an unprobed one ready_unprobed
   campaigns-os qa run --packet <json> [--base-url <url>] [--browser] [--test-order <mode>] [--select-package <ref[:qty],...>] [--apply-coupon <code>] [--no-post-verdict] [--no-remit] [--output-dir <dir>] [--json]
   campaigns-os qa promote --packet <json> --verdict <full-verdict.json> [--json]   # project one explicit qa-output verdict to the committed .campaign-runtime/qa-verdict.json sidecar
-  campaigns-os qa publish --packet <json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--json]   # post an already-stored verdict (the sidecar's run, or --verdict) to the QA portal without a re-run or an order; refuses a stale spec_hash or an already-published verdict
+  campaigns-os qa publish --packet <json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--dry-run] [--json]   # post an already-stored verdict (the sidecar's run, or --verdict) to the QA portal without a re-run or an order; refuses a stale spec_hash or an already-published verdict. --dry-run runs every one of those refusal checks and prints what would be posted (endpoint, verdict run id, payload bytes) without the POST
   campaigns-os qa policy set --packet <json> [--allowed-domains-confirmed true|false] [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--order-path-depth <off|common|full>] [--json]   # --order-path-depth writes qa.proof_policy.order_path_depth and refreshes the assembly report's proof_policy mirror
   campaigns-os findings add --stage <stage> --kind <kind> --summary <text> [--details <text>] [--packet <json>] [--journal <path>] [--run-id <id>] [...context flags]
   campaigns-os findings harvest --packet <json> [--context <json>] [--report <json>] [--journal <path>] [--run-id <id>] [--write] [--json]
   campaigns-os findings list [--packet <json>] [--journal <path>] [--json]
   campaigns-os findings export [--summary | --json] [--packet <json>] [--journal <path>]
-  campaigns-os run-record --packet <json> [--context <json>] [--report <json>] [--qa-verdict <path>] [--run-id <id>] [--new-run] [--journal <path>] [--lifecycle-journal <path>] [--surfaces <a,b>] [--primary-surface <s>] [--surface-confidence <text>] [--agent-total-tokens <n>] [--agent-elapsed-ms <n>] [--proxy-base <url>] [--no-remit] [--no-write] [--list] [--json]
+  campaigns-os run-record --packet <json> [--context <json>] [--report <json>] [--qa-verdict <path>] [--run-id <id>] [--new-run] [--journal <path>] [--lifecycle-journal <path>] [--surfaces <a,b>] [--primary-surface <s>] [--surface-confidence <text>] [--agent-total-tokens <n>] [--agent-elapsed-ms <n>] [--proxy-base <url>] [--no-remit] [--no-write] [--dry-run] [--list] [--json]
     run_id: --run-id > the active run session > the most recent Run Record for this packet's campaign (re-emitted in place; a remitted one is left as written) > freshly minted. --new-run always mints; --list prints the run ids on disk for this packet (id, created_at, remit state, path) and, like --no-write, writes and sends nothing.
+    --dry-run assembles the record and prints it (with --json: dry_run, would_write, would_remit), then writes no file and sends nothing — where --no-write skips the assembly's reads too. Combining them is allowed and still writes nothing. \`run end --dry-run\` hands the flag on to run-record and leaves the run session open, so the close can still be made for real afterwards.
 
-  Any command accepts [--lifecycle-journal <path>] (or env CAMPAIGNS_OS_LIFECYCLE_LOG) to append a command-lifecycle entry (command, argv shape, exit status, timing) for the run; pair with --run-id so run-record can embed it.
+  Commands other than login, logout, demo, and tooling diagnose accept [--lifecycle-journal <path>] (or env CAMPAIGNS_OS_LIFECYCLE_LOG) to append a command-lifecycle entry (command, argv shape, exit status, timing) for the run; pair with --run-id so run-record can embed it.
+    --no-write suppresses that append for every command, however the journal was selected (flag, env, or the active run session); a refused invocation (unknown command, an unknown subcommand refused before its handler runs, or a flag the command refuses up front) and \`run status\` never append one at all.
+    A refused invocation writes no file of its own. One effect still precedes argument refusal: \`start\`, \`prepare-build\`, \`build\`, \`run start\` and \`run end\` close out a STALE run session at the root they are about to act on (Run Record assembled and remitted under the usual consent, session file cleared) before argv is refused — a declared effect of those commands. --no-write suppresses that closeout too, so a --no-write invocation leaves the target byte-identical.
   campaigns-os telemetry status|on [--proxy-base <url>] [--json]   # machine-level Run Telemetry consent (gates remit only; capture is always local). \`on\` records consent for ONE endpoint: the canonical NEXT endpoint by default, or the --proxy-base you name (a loopback or staging receiver); \`status\` reports the stored scope and checks it against the canonical endpoint or the --proxy-base you name
   campaigns-os telemetry off [--json]                                  # turn remit off for every endpoint (takes no --proxy-base)
   campaigns-os telemetry list [--packet <json> | --admin-key-env <VAR>] [--since <ISO>] [--package <v>] [--surface <s>] [--trusted] [--limit <n>] [--proxy-base <url>] [--trust-proxy-base] [--json]   # read stored Run Records: tenant scope via the packet's campaign key, or cross-tenant via the ops admin key (default env CAMPAIGN_OPS_ADMIN_KEY). --proxy-base must be https unless it is a loopback host (allowed over http, with a warning that the credential is in clear).
   campaigns-os run start [--packet <json>] [--run-id <id>] [--lifecycle-journal <path>] [--force] [--json]   # begin an ambient run session: one run_id + journal auto-shared by every command, no per-command flags; with --packet the session lives in the packet's target repo, whatever the cwd
-  campaigns-os run status [--json]                                 # active session + incomplete stages + deviation count + exact next command
+  campaigns-os run status [--json]                                 # active session + incomplete stages + deviation count + exact next command; read-only — it never sweeps and never journals
   campaigns-os run end [--packet <json>] [--no-remit] [--no-write] [--proxy-base <url>] [--json]   # assemble the aggregated Run Record for the session, then clear it (also closes out a stale session at cwd); --proxy-base is handed to run-record, so the session record remits to that receiver under the consent scoped to it
 
   Gates: when theme inspect finds a generatable brand theme and the campaign ships commerce pages, \`next polish|deploy|qa\` and \`qa run\` BLOCK until the brand layer is applied after next-core.css or explicitly waived (\`theme waive\` / \`qa run --theme-waive "<reason>"\`).
@@ -535,9 +552,15 @@ Examples:
   npm run campaigns-os -- standardize --target examples/target-page-kit --json
 `;
 
+// `refused()`, its `REFUSED_INVOCATION` tag, and the `refusalSeen()` /
+// `runWithRefusalScope()` accessors live in lifecycle.mjs — see the contract
+// there.
+// Command modules raise refusals too (`qa`'s unknown subcommand) and cli.mjs
+// imports them, so the factory has to sit below both.
+
 // Top-level commands the CLI dispatches, used to offer a did-you-mean
 // suggestion on a typo instead of a bare "Unknown command". Derived from the
-// `command === "…"` literals in dispatch() itself (memoized on first use) so
+// `command === "…"` literals in main() and dispatch() (memoized on first use) so
 // the list cannot drift as dispatch branches are added or removed. The regex
 // tolerates whitespace and either quote style so common reformats don't
 // silently empty the list; a known-commands test guards against a refactor
@@ -546,7 +569,7 @@ let knownCommandsCache = null;
 export function knownCommands() {
   if (knownCommandsCache) return knownCommandsCache;
   const found = new Set(["help"]);
-  for (const match of dispatch.toString().matchAll(/command\s*===\s*["']([^"']+)["']/g)) {
+  for (const match of (main.toString() + dispatch.toString()).matchAll(/command\s*===\s*["']([^"']+)["']/g)) {
     found.add(match[1]);
   }
   knownCommandsCache = [...found];
@@ -593,7 +616,7 @@ function closestCommand(input) {
   return bestDistance <= budget ? best : null;
 }
 
-export async function main(argv) {
+export async function main(argv, { authentication } = {}) {
   const args = parseArgs(argv);
   // `npx --yes -p <spec> campaigns-os <command>` and `npx --yes <spec>
   // campaigns-os <command>` both hand the bin its own name as the first
@@ -603,65 +626,100 @@ 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;
-  }
+  // Everything below — dispatch and the onFinish that reads the verdict — runs
+  // inside ONE refusal scope, so a refusal raised by this invocation is visible
+  // only to this invocation's persistence step. Two main() calls interleaved
+  // in-process (a test, an embedding host) no longer share the verdict.
+  return runWithRefusalScope(async () => {
+    // Authentication never recovers/remits run sessions or records argv in a
+    // lifecycle journal. Credentials belong only in the user credential store.
+    if (command === "login" || command === "logout") {
+      const { runAuthentication } = await import("./login.mjs");
+      return runAuthentication(argv[0] === "campaigns-os" ? argv.slice(1) : argv, authentication);
+    }
+
+    // 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;
-  }
+    // 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
-  // command is tagged with and the journal it writes to come from a single
-  // read (no TOCTOU skew if the session changes mid-run).
-  //
-  // Before that read, close out any STALE session at the root this command is
-  // about to open a new one in. findRunSession ignores stale sessions so a new
-  // run never inherits an old run_id — but an ignored session was also an
-  // abandoned one: nine of them were found lingering with no Run Record and
-  // nothing remitted. Closing out is best-effort and never blocks the command.
-  const storageInspection = command === "sdk" && args._[1] === "storage-check";
-  const sweptStale = storageInspection ? [] : await closeOutStaleRunSessions(command, args);
-  const ambient = ambientRunSession(args);
-
-  // Wrap every command in the lifecycle instrumentation (T6): it captures the
-  // command, its argv shape, exit status, and timing. Re-throws unchanged so
-  // the CLI exit code is unaffected. Persistence runs via onFinish so it fires
-  // on BOTH the success and error paths — a command that THROWS (the most
-  // valuable failure telemetry) is recorded too, not just clean exits.
-  // Persistence is OPT-IN — an explicit --lifecycle-journal /
-  // CAMPAIGNS_OS_LIFECYCLE_LOG, or an active run session. With none, behavior
-  // is identical to before.
-  //
-  // `sessionHolder` is per-invocation, NOT module state: when start/
-  // prepare-build auto-open a run session mid-command, they publish it here
-  // so onFinish persists this command's own lifecycle entry into the new
-  // session — without two interleaved invocations ever sharing a session.
-  const sessionHolder = { current: ambient, autoStarted: false, adopted: false, qaResult: null, sweptStale };
-  await withCommandLifecycle(
-    {
-      command,
-      argvShape: argvShape(args),
-      runId: optionalString(args["run-id"]) || ambient?.session?.run_id || null,
-      onFinish: async (lifecycle, thrown) => {
-        persistLifecycleIfRequested(args, command, lifecycle, sessionHolder);
-        await autoEndRunSessionAfterTerminalQa(args, command, sessionHolder, thrown);
+    // Project setup must not recover campaign sessions, read gateway bindings,
+    // or emit lifecycle/telemetry evidence before a campaign is selected.
+    if (command === "tooling" && args._[1] === "setup") {
+      const { setupArguments, setupTooling, setupTextLines } = await import("./tooling-setup.mjs");
+      setupArguments(args, argv);
+      const { installQaBrowser } = await import("./qa-node.mjs");
+      const result = setupTooling(args, { packageRoot: ROOT, installSkills, installAgentContext, installBrowser: installQaBrowser });
+      console.log(args.json ? JSON.stringify(result, null, 2) : setupTextLines(result).join("\n"));
+      if (!result.ok) process.exitCode = 2;
+      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
+    // command is tagged with and the journal it writes to come from a single
+    // read (no TOCTOU skew if the session changes mid-run).
+    //
+    // Before that read, close out any STALE session at the root this command is
+    // about to open a new one in. findRunSession ignores stale sessions so a new
+    // run never inherits an old run_id — but an ignored session was also an
+    // abandoned one: nine of them were found lingering with no Run Record and
+    // nothing remitted. Closing out is best-effort and never blocks the command.
+    const storageInspection = command === "sdk" && args._[1] === "storage-check";
+    // `readback` bypasses session resolution entirely, sweep included. Its
+    // `--packet` is a readback OVERRIDE naming the Build Packet to project, not a
+    // Build Packet to act on, and ambientRunSession treats that flag as a session
+    // locator: it read the named file whole through readJson, so a 40 MB packet
+    // was loaded into memory past readback's own 32 MiB bound before readback
+    // ever saw it, and a valid override exited 1 whenever some active session was
+    // bound to a different packet. Neither belongs to a command declared
+    // read-only. The lifecycle wrapper below still runs; the read-only exemption
+    // lives in persistLifecycleIfRequested, which writes no entry for readback.
+    const readOnlyProjection = command === "readback";
+    const sweptStale = storageInspection || readOnlyProjection ? [] : await closeOutStaleRunSessions(command, args);
+    const ambient = readOnlyProjection ? null : ambientRunSession(args);
+
+    // Wrap every command in the lifecycle instrumentation (T6): it captures the
+    // command, its argv shape, exit status, and timing. Re-throws unchanged so
+    // the CLI exit code is unaffected. Persistence runs via onFinish so it fires
+    // on BOTH the success and error paths — a command that THROWS (the most
+    // valuable failure telemetry) is recorded too, not just clean exits.
+    // Persistence is OPT-IN — an explicit --lifecycle-journal /
+    // CAMPAIGNS_OS_LIFECYCLE_LOG, or an active run session. With none, behavior
+    // is identical to before.
+    //
+    // `sessionHolder` is per-invocation, NOT module state: when start/
+    // prepare-build auto-open a run session mid-command, they publish it here
+    // so onFinish persists this command's own lifecycle entry into the new
+    // session — without two interleaved invocations ever sharing a session.
+    const sessionHolder = { current: ambient, autoStarted: false, adopted: false, qaResult: null, sweptStale };
+    await withCommandLifecycle(
+      {
+        command,
+        argvShape: argvShape(args),
+        runId: optionalString(args["run-id"]) || ambient?.session?.run_id || null,
+        onFinish: async (lifecycle, thrown) => {
+          persistLifecycleIfRequested(args, command, lifecycle, sessionHolder, thrown);
+          await autoEndRunSessionAfterTerminalQa(args, command, sessionHolder, thrown);
+        },
       },
-    },
-    (recorder) => dispatch(command, args, recorder, ambient, sessionHolder),
-  );
+      (recorder) => dispatch(command, args, recorder, ambient, sessionHolder),
+    );
+  });
 }
 
 function ambientRunSession(args = {}) {
@@ -777,14 +835,72 @@ function resolveLifecycleJournal(args, { ambient = null, fallbackDir = null } =
   return fallbackDir ? join(resolve(fallbackDir), LIFECYCLE_JOURNAL_REL_PATH) : null;
 }
 
+// The commands and subcommands that actually IMPLEMENT `--dry-run`. The flag
+// reaches every handler through a permissive parseArgs, so it is silently
+// accepted everywhere — and the lifecycle exemption below, scoped to the flag
+// alone, therefore fired on commands that ignore it: `qa run --dry-run` placed
+// orders while writing no journal entry, and (see runSessionEndArgs) carried
+// the flag into its own auto-end, which assembled no Run Record and left the
+// session open. Keyed by `command`, or `command <args._[1]>` where the flag
+// belongs to one subcommand. A command outside this set given `--dry-run`
+// behaves exactly as it did before: it journals if it otherwise would, and it
+// is not refused — refusing unknown flags is separate work.
+const DRY_RUN_COMMANDS = new Set([
+  "page-kit sync",
+  "spec derive",
+  "install-skills",
+  "install-agent-context",
+  "run-record",
+  "run end",
+  "qa publish",
+  "checkpoint waive",
+  "theme waive",
+]);
+
+function commandImplementsDryRun(command, args = {}) {
+  return DRY_RUN_COMMANDS.has(command) || DRY_RUN_COMMANDS.has(`${command} ${args._?.[1]}`);
+}
+
 // Append the command's lifecycle entry only when capture is active: an explicit
 // flag/env, or an ambient run session. Never throws — a lifecycle write must
 // not break a command (telemetry never blocks a build). `help` is a no-op
 // command and is not worth recording.
-function persistLifecycleIfRequested(args, command, lifecycle, sessionHolder) {
+function persistLifecycleIfRequested(args, command, lifecycle, sessionHolder, thrown) {
   if (command === "help" || (command === "sdk" && args._[1] === "storage-check")) return;
+  // Three rules about what NEVER reaches the journal, whichever way the journal
+  // was selected (--lifecycle-journal, CAMPAIGNS_OS_LIFECYCLE_LOG, or an
+  // ambient run session). The in-process lifecycle object is still built; only
+  // the persistence below — the journal append and the deviation entry that
+  // follows it — is skipped, so a suppressed command still exits as before.
+  //   1. --no-write writes nothing, the journal included (issue #459: `run
+  //      status --no-write` under an ambient session still created
+  //      .campaign-runtime/command-lifecycle.jsonl).
+  //   2. A refused INVOCATION records nothing — an unknown top-level command,
+  //      an unknown subcommand (`tooling statuss`), or a flag the command
+  //      refuses up front (`standardize --dryrun`). None of them reached a
+  //      handler, so a typo must not materialize a journal under the target.
+  //      The tag the refusal carries IS the mechanism, read two ways: on the
+  //      thrown error, or via refusalSeen() when the refusal was caught and
+  //      rendered instead of thrown. There is deliberately no command-list
+  //      backstop here — knownCommands() is regex-harvested and documented as
+  //      fragile, so a second reading of it would be a second command list that
+  //      could disagree with dispatch.
+  //   3. `run status` is read-only: it never sweeps and never journals.
+  if (args["no-write"] === true) return;
+  if (refusalSeen() || thrown?.code === REFUSED_INVOCATION) return;
+  if (command === "run" && args._[1] === "status") return;
   // An inspection must not append to a delivered campaign's active run either.
-  if (command === "doctor" && args.packet && (args.write !== true || args["no-write"] === true)) return;
+  // (--no-write is handled above, so only the read-only `doctor` form is left.)
+  if (command === "doctor" && args.packet && args.write !== true) return;
+  // The same rule, per-flag, for every command that takes `--dry-run`: the
+  // flag's whole promise is that the invocation writes nothing under the
+  // target, and the journal lives under the target. Only for the commands that
+  // make that promise, though — DRY_RUN_COMMANDS above.
+  if (args["dry-run"] === true && commandImplementsDryRun(command, args)) return;
+  // `readback` is declared read-only for the whole command, not per-flag: it
+  // writes nothing under the target, so a journal entry would be the one write
+  // its own contract forbids. Skipped the way doctor inspection is skipped.
+  if (command === "readback") return;
   const ambient = sessionHolder?.current || null;
   // A session auto-started DURING this command (start/prepare-build) is
   // published into sessionHolder by autoStartRunSession; this command's own
@@ -857,31 +973,38 @@ export function recordQaStageOutcome(args, result) {
     if (!existsSync(reportPath)) return false;
 
     const verdict = result.verdict;
+    const hasLocalIdentity = packet.spec?.local_spec_id != null || verdict?.local_spec_id != null;
+    if (hasLocalIdentity && !qaVerdictIdentityMatch(verdict, packet)) return false;
     const failed = (Array.isArray(verdict.assertions) ? verdict.assertions : [])
       .filter((assertion) => assertion?.status === "fail")
       .map((assertion) => `${assertion.id}: ${assertion.actual || "assertion failed"}`);
-    const committed = commitAssemblyReport(workspace, (report) => recordProducerStageOutcome(report, {
-      stage: "qa",
-      disposition: verdict.disposition,
-      timestamp: verdict.completed_at,
-      command: `campaigns-os ${QA_RUN_PRODUCER}`,
-      outputs: [result.local_path, result.qa_sidecar?.path].filter(isNonEmptyString),
-      blockers: verdict.disposition === "blocked" ? failed : [],
-      warnings: verdict.disposition === "ready_with_exceptions"
-        ? ["QA completed with explicitly attributed exceptions; inspect the verdict artifact."]
-        : [],
-      // The producer knows its own run id and must restate it, or the stage
-      // keeps a previous run's identity beside this run's status and outputs.
-      identity: { verdict_run_id: optionalString(verdict.run_id) },
-      // Which build this verdict judged, and the gates whose browser outcome
-      // the doctor's static scan defers to (qaGatePassedForCurrentBuild). A
-      // gate that never ran is left out, so silence never reads as a pass.
-      evidence: qaStageGateEvidence(verdict, report),
-      // Counts-only: never order ids, refs, emails or URLs (see
-      // summarizePurchaseProof). This is what lets `next` tell a real purchase
-      // path from a `--test-order off` diagnostic.
-      proof: summarizePurchaseProof({ verdict, proofPolicy: packet.qa?.proof_policy }),
-    }), {
+    const committed = commitAssemblyReport(workspace, (report) => {
+      if (hasLocalIdentity && !specHashesMatch(verdict.spec_hash, report.identity?.spec_material_hash)) {
+        throw new Error("Local-spec QA verdict belongs to a different material revision; report evidence was not changed.");
+      }
+      return recordProducerStageOutcome(report, {
+        stage: "qa",
+        disposition: verdict.disposition,
+        timestamp: verdict.completed_at,
+        command: `campaigns-os ${QA_RUN_PRODUCER}`,
+        outputs: [result.local_path, result.qa_sidecar?.path].filter(isNonEmptyString),
+        blockers: verdict.disposition === "blocked" ? failed : [],
+        warnings: verdict.disposition === "ready_with_exceptions"
+          ? ["QA completed with explicitly attributed exceptions; inspect the verdict artifact."]
+          : [],
+        // The producer knows its own run id and must restate it, or the stage
+        // keeps a previous run's identity beside this run's status and outputs.
+        identity: { verdict_run_id: optionalString(verdict.run_id) },
+        // Which build this verdict judged, and the gates whose browser outcome
+        // the doctor's static scan defers to (qaGatePassedForCurrentBuild). A
+        // gate that never ran is left out, so silence never reads as a pass.
+        evidence: qaStageGateEvidence(verdict, report),
+        // Counts-only: never order ids, refs, emails or URLs (see
+        // summarizePurchaseProof). This is what lets `next` tell a real purchase
+        // path from a `--test-order off` diagnostic.
+        proof: summarizePurchaseProof({ verdict, proofPolicy: packet.qa?.proof_policy }),
+      });
+    }, {
       stage: "qa",
       // The sidecar names this refresh as its producer (generated_by, #312).
       // This function is the `qa run` stage record, whichever token dispatch
@@ -1009,9 +1132,18 @@ async function autoEndRunSessionAfterTerminalQa(args, command, sessionHolder, th
     return;
   }
 
+  // `dry-run` is inheritable because `run end --dry-run` hands it to
+  // run-record on purpose. The invoking command here is `qa run`, which does
+  // not implement the flag, so inheriting it would turn its own auto-end into
+  // a dry run: no Run Record written, and the session left open after a
+  // terminal QA. Every other inheritable flag `qa run` may carry is one
+  // run-record reads the same way whoever passed it.
+  const extraArgs = { ...args, "qa-verdict": result.local_path };
+  if (!commandImplementsDryRun(command, args)) delete extraArgs["dry-run"];
+
   const summary = await closeRunSession(updatedFound, {
     packet,
-    extraArgs: { ...args, "qa-verdict": result.local_path },
+    extraArgs,
     silent: true,
     promptForConsent: false,
     onError: (error) => process.stderr.write(`[campaigns-os] run session auto-end skipped after QA: ${error.message}\n`),
@@ -1056,6 +1188,23 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     // them from this function's source.
     const mode = PREPARE_MODES[command];
     if (!mode) throw new Error(`No intake mode registered for "${command}"; add it to PREPARE_MODES.`);
+    // Validate argv before --spec is inspected or --map-id fetches and caches.
+    // Preserve resolveSpecPath's missing-input and map-id/target diagnostics.
+    for (const flag of ["spec", "map-id", "source", "target", "source-kind", "proxy-base"]) {
+      if (Object.hasOwn(args, flag)) requireArg(args, flag);
+    }
+    if (args.spec || (args["map-id"] && args.target)) requireArg(args, "source");
+    if (args.spec) requireArg(args, "target");
+    const sourceKind = optionalString(args["source-kind"], "html_funnel");
+    if (sourceKind !== "html_funnel") {
+      throw refused(`Unsupported source adapter "${sourceKind}". Use html_funnel for the current prepared-HTML flow.`);
+    }
+    if (Object.hasOwn(args, "wrapper-policy") && !isNonEmptyString(args["wrapper-policy"])) {
+      throw refused(`--wrapper-policy needs a value. Accepted values: ${ADAPTER_WRAPPER_POLICIES.join(", ")}.`);
+    }
+    const wrapperPolicyFlag = refusing(() => parseWrapperPolicyFlag(args));
+    refusing(() => requireDesignManifestValue(args));
+    const orderPathDepthFlag = refusing(() => parseOrderPathDepthFlag(args, { command: "prepare-build" }));
     // Tier 2: mark sub-phases so the lifecycle journal entry carries per-phase
     // timings (spec resolve vs the prepare+doctor+install build), which Tier 1
     // aggregates into `start:resolve-spec` / `start:prepare-build` stages.
@@ -1067,7 +1216,7 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     args.spec = resolved.specPath;
     // `command` rides along for the doctor sidecar's generated_by stamp when
     // the mode runs doctor (#312): threaded from here, not re-read from argv.
-    const result = await recorder.time("prepare-build", () => prepareBuild(args, { ...mode, command, specInput }));
+    const result = await recorder.time("prepare-build", () => prepareBuild(args, { ...mode, command, specInput, sourceKind, wrapperPolicyFlag, orderPathDepthFlag }));
     result.spec_source = resolved;
     autoStartRunSession(result, args, ambient, sessionHolder);
     printPrepareResult(result, args);
@@ -1083,7 +1232,7 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
 
   if (command === "bundle") {
     const subcommand = args._[1] || "check";
-    if (subcommand !== "check") throw new Error('Unknown bundle subcommand. Use: campaigns-os bundle check --packet <campaign-runtime.build.json> [--require-qa] [--json].');
+    if (subcommand !== "check") throw refused('Unknown bundle subcommand. Use: campaigns-os bundle check --packet <campaign-runtime.build.json> [--require-qa] [--json].');
     const { inspectSidecarBundle, sidecarBundleReadinessLine } = await import("./sidecar-bundle.mjs");
     const result = inspectSidecarBundle({
       packetPath: requireArg(args, "packet"),
@@ -1097,10 +1246,10 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
   }
 
   if (command === "sdk") {
-    if (args._[1] !== "storage-check" || args._.length !== 2) throw new Error("Use: campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json].");
+    if (args._[1] !== "storage-check" || args._.length !== 2) throw refused("Use: campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json].");
     const known = new Set(["_", "target", "target-sdk", "manifest", "scope", "exclude", "json"]);
-    if (args.json !== undefined && args.json !== true) throw new Error("--json is a boolean flag and takes no value.");
-    for (const key of Object.keys(args)) if (!known.has(key)) throw new Error(`Unknown SDK storage-check flag: --${key}`);
+    if (args.json !== undefined && args.json !== true) throw refused("--json is a boolean flag and takes no value.");
+    for (const key of Object.keys(args)) if (!known.has(key)) throw refused(`Unknown SDK storage-check flag: --${key}`);
     const { scanSdkStorageCompatibility, formatStorageCompatibilityReport } = await import("./sdk-storage-compatibility.mjs");
     const result = scanSdkStorageCompatibility({
       cwd: requireArg(args, "target"),
@@ -1145,6 +1294,21 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     return;
   }
 
+  if (command === "readback") {
+    // Read-only projection over a target's already-emitted artifacts. It owns
+    // its own exit codes (0 for any projection it could form, 2 for a request
+    // that cannot form one) rather than throwing, so a usage error reads as a
+    // one-line refusal instead of a stack-shaped CLI error.
+    const { runReadbackCommand } = await import("./readback.mjs");
+    const { exitCode, text } = runReadbackCommand(args);
+    if (exitCode === 0) process.stdout.write(text);
+    else {
+      process.stderr.write(text);
+      process.exitCode = 2;
+    }
+    return;
+  }
+
   if (command === "validate-assembly-report") {
     const reportPath = requireArg(args, "report");
     const result = validateAssemblyReport(readJson(resolve(reportPath)));
@@ -1160,8 +1324,8 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
   }
 
   if (command === "install-skills") {
-    if (args.target === true) throw new Error("Missing value for --target");
-    if (args.platform === true) throw new Error("Missing value for --platform");
+    if (args.target === true) throw refused("Missing value for --target");
+    if (args.platform === true) throw refused("Missing value for --platform");
     const result = installSkills(args.target, Boolean(args["dry-run"]), args.platform);
     writeResult(result, args, 0);
     return;
@@ -1172,7 +1336,7 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     // Spelled as inequalities: knownCommands() harvests the top-level
     // command literals from this function by an equality pattern that a
     // subcommand equality would also match.
-    if (subcommand !== "sync" && subcommand !== "parity") throw new Error("Unknown page-kit subcommand. Use: campaigns-os page-kit sync --packet <campaign-runtime.build.json> [--dry-run] [--json], or campaigns-os page-kit parity --packet <campaign-runtime.build.json> [--report <json>] [--json].");
+    if (subcommand !== "sync" && subcommand !== "parity") throw refused("Unknown page-kit subcommand. Use: campaigns-os page-kit sync --packet <campaign-runtime.build.json> [--dry-run] [--json], or campaigns-os page-kit parity --packet <campaign-runtime.build.json> [--report <json>] [--json].");
     const parity = subcommand !== "sync";
     const result = parity ? pageKitParityCommand(args) : pageKitSyncCommand(args);
     if (args.json) console.log(JSON.stringify(result, null, 2));
@@ -1185,7 +1349,7 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
     const subcommand = args._[1] || null;
     // Inequality on purpose: knownCommands() harvests top-level command
     // literals by an equality pattern a subcommand equality would also match.
-    if (subcommand !== "derive") throw new Error("Unknown spec subcommand. Use: campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json].");
+    if (subcommand !== "derive") throw refused("Unknown spec subcommand. Use: campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json].");
     const result = await specDeriveWithMapWriteback(args);
     if (args.json) console.log(JSON.stringify(result, null, 2));
     else for (const line of specDeriveWriteMapTextLines(result)) console.log(line);
@@ -1194,8 +1358,11 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
   }
 
   if (command === "tooling") {
-    const result = toolingCommand(args);
-    writeResult(result, args, result.ok ? 0 : 2);
+    const result = await toolingStatusCommand(args);
+    // The revision line is a header, so a mismatch is stated before the status
+    // an operator would otherwise read as fine — and the full status still
+    // prints, because the exit code is set after the render, not instead of it.
+    writeResult(result, args, result.ok ? 0 : 2, { headerLines: [...skillsRevisionTextLines(result), ...pinTextLines(result)] });
     return;
   }
 
@@ -1217,7 +1384,9 @@ 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)) {
+    // nextStage requires a packet. Guard its optional, swallowed progress
+    // probe explicitly so it cannot construct a refusal in that try block.
+    if (args._[1] === "run" && result?.verdict && isNonEmptyString(args.packet) && 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 {
@@ -1235,6 +1404,9 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
   }
 
   if (command === "run-record") {
+    // These are the operator's own argv. Internal closeouts call
+    // runRecordCommand directly and retain their pre-1.43.1 flag handling.
+    validateRunRecordArgv(args);
     await runRecordCommand(args, ambient);
     return;
   }
@@ -1252,7 +1424,7 @@ async function dispatch(command, args, recorder = NOOP_RECORDER, ambient = null,
 
   const suggestion = closestCommand(command);
   const didYouMean = suggestion ? ` Did you mean "${suggestion}"?` : "";
-  throw new Error(
+  throw refused(
     `Unknown command: ${command}.${didYouMean} Run \`campaigns-os --help\` to see available commands.`,
   );
 }
@@ -1277,12 +1449,25 @@ function parseArgs(argv) {
   return args;
 }
 
+// The shared "missing required flag" refusal. Every call site resolves flags
+// at the top of its handler, before the command reads or writes anything, so
+// this is always an up-front refusal and carries the tag.
 function requireArg(args, key) {
   const value = args[key];
-  if (!isNonEmptyString(value)) throw new Error(`Missing required --${key}`);
+  if (!isNonEmptyString(value)) throw refused(`Missing required --${key}`);
   return value;
 }
 
+// `--dry-run` is a bare flag on every command that takes one. The shared
+// parser would read a following token as its value, so `--dry-run true` must
+// fail rather than quietly become a real write or a real send.
+function isDryRun(args) {
+  if (Object.hasOwn(args, "dry-run") && args["dry-run"] !== true) {
+    throw refused(`--dry-run takes no value (got ${JSON.stringify(args["dry-run"])}); write \`--dry-run\` on its own, after the other flags.`);
+  }
+  return args["dry-run"] === true;
+}
+
 function isObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -1355,7 +1540,7 @@ async function resolveSpecPath(args, opts = {}) {
     const mapId = String(args["map-id"]).trim();
     const targetRepo = opts.targetRepo || (args.target ? resolve(args.target) : null);
     if (!targetRepo) {
-      throw new Error("--map-id requires --target (so the fetched spec can be cached under <target>/.campaign-runtime/).");
+      throw refused("--map-id requires --target (so the fetched spec can be cached under <target>/.campaign-runtime/).");
     }
     const proxyBase = optionalString(args["proxy-base"], DEFAULT_PROXY_BASE);
     const cacheDir = join(targetRepo, ".campaign-runtime", "fetched-specs");
@@ -1374,7 +1559,7 @@ async function resolveSpecPath(args, opts = {}) {
         algorithm: "map-store-v1", local_spec_material_hash: specMaterialHash(spec) },
     };
   }
-  throw new Error(
+  throw refused(
     "Either --spec <path> or --map-id <id> is required. " +
       "Pass a local CampaignSpec (--spec <path-to-campaignspec.json>) " +
       "or fetch one from Map Builder (--map-id <id> --target <page-kit-dir>).",
@@ -1533,7 +1718,7 @@ function campaignIdentity(spec, args) {
     || optionalString(spec.spec_identity?.public_route_slug)
     || optionalString(spec.campaign?.slug)
     || optionalString(spec.campaign?.id);
-  return { mapId, publicRouteSlug };
+  return { mapId, publicRouteSlug, localSpecId: spec.spec_identity?.local_spec_id ?? null };
 }
 
 function preferredTemplateFamily(spec) {
@@ -2146,11 +2331,8 @@ function parseWrapperPolicyFlag(args) {
 // directory are errors: the operator named the file, so silently falling back
 // to filesystem matching would discard the declaration they made.
 function parseDesignManifestFlag(args) {
-  const raw = args["design-manifest"];
+  const raw = requireDesignManifestValue(args);
   if (raw == null) return null;
-  if (raw === true || !isNonEmptyString(raw)) {
-    throw new Error("--design-manifest needs a value: the path of a source-html-manifest/v0 JSON file.");
-  }
   const path = resolve(raw);
   if (!existsSync(path) || !statSync(path).isFile()) {
     throw new Error(`Design manifest does not exist or is not a file: ${path}`);
@@ -2158,6 +2340,14 @@ function parseDesignManifestFlag(args) {
   return path;
 }
 
+function requireDesignManifestValue(args) {
+  const raw = args["design-manifest"];
+  if (raw != null && (raw === true || !isNonEmptyString(raw))) {
+    throw new Error("--design-manifest needs a value: the path of a source-html-manifest/v0 JSON file.");
+  }
+  return raw;
+}
+
 // Same precedence the template family uses (docs/build-packet.md
 // "Authoring-Time Hints"): an explicit CLI flag beats a declared file hint,
 // and with neither the default stands. The vocabulary is the adapter
@@ -2208,21 +2398,18 @@ function prepareBuild(args, options = {}) {
   assertDistinctPrepareBuildOutputPaths(prepareBuildCollisionPaths);
   guardAssemblyReportOverwrite(reportPath, args);
   const spec = readJson(specPath);
-  const { mapId, publicRouteSlug } = campaignIdentity(spec, args);
-  if (!mapId) throw new Error("CampaignSpec has no map ID. Re-export a saved Map Builder spec with spec_identity.map_id before assembly; use --map-id only for legacy diagnostics.");
-  if (!publicRouteSlug) throw new Error("CampaignSpec has no public route slug. Re-export a saved Map Builder spec with spec_identity.public_route_slug or set campaign.slug.");
-
-  const sourceKind = optionalString(args["source-kind"], "html_funnel");
-  if (sourceKind !== "html_funnel") {
-    throw new Error(`Unsupported source adapter "${sourceKind}". Use html_funnel for the current prepared-HTML flow.`);
-  }
-  // Validated here, with the other argv checks, rather than where the policy
-  // is consumed: prepare-build publishes an immutable Design Source Package
-  // partway through, so a flag that throws later would leave persistent state
-  // behind for a bad argument.
-  const wrapperPolicyFlag = parseWrapperPolicyFlag(args);
+  const { mapId, publicRouteSlug, localSpecId } = campaignIdentity(spec, args);
+  if (!resolveCampaignIdentity({ map_id: mapId, local_spec_id: localSpecId })) {
+    throw new Error("CampaignSpec requires exactly one identity: a saved spec_identity.map_id, or an agent-authored spec_identity.local_spec_id (1–64 letters, digits, underscores or hyphens). Keep the local ID stable across revisions; do not invent a Map ID.");
+  }
+  if (!publicRouteSlug) throw new Error("CampaignSpec has no public route slug. Set spec_identity.public_route_slug or campaign.slug.");
+
+  // Dispatch validated the argv-only flags before spec resolution. Only the
+  // manifest's filesystem check remains here, before preparation writes.
+  const sourceKind = options.sourceKind;
+  const wrapperPolicyFlag = options.wrapperPolicyFlag;
   const designManifestPath = parseDesignManifestFlag(args);
-  const orderPathDepthFlag = parseOrderPathDepthFlag(args, { command: "prepare-build" });
+  const orderPathDepthFlag = options.orderPathDepthFlag;
 
   const activePages = activeSpecPages(spec);
   const htmlFiles = collectHtmlFiles(sourceRoot);
@@ -2444,6 +2631,9 @@ function prepareBuild(args, options = {}) {
   const packet = {
     schema_version: PACKET_SCHEMA,
     generated_at: new Date().toISOString(),
+    // The kernel version that prepared this packet: the second pin source
+    // `tooling status` reads when the project declares no exact devDependency.
+    campaigns_os_version: packageVersion(),
     campaign: {
       public_route_slug: publicRouteSlug,
       ...(specRouteRoot ? { route_root: specRouteRoot } : {}),
@@ -2455,7 +2645,8 @@ function prepareBuild(args, options = {}) {
     },
     spec: {
       map_id: mapId,
-      spec_url: spec.spec_identity?.spec_url || null,
+      ...(localSpecId ? { local_spec_id: localSpecId } : {}),
+      spec_url: localSpecId ? null : spec.spec_identity?.spec_url || null,
       local_path: relFromFile(packetPath, specPath),
     },
     design_source_package: designSourcePackage.referenceFor(packetPath),
@@ -2820,6 +3011,7 @@ function createAssemblyReport({
     status: "prepared",
     identity: {
       map_id: packet.spec.map_id,
+      ...localSpecIdentityFields(packet.spec),
       public_route_slug: packet.campaign.public_route_slug,
       campaign_directory: packet.campaign.campaign_directory,
       live_url_path: packet.campaign.live_url_path,
@@ -3218,7 +3410,7 @@ function rejectUnknownStandardizeFlags(args) {
   const valueHint = unknown.some((key) => key.includes("="))
     ? " A flag takes its value as the next argument (--flag value), not --flag=value."
     : "";
-  throw new Error(
+  throw refused(
     `Unknown flag${unknown.length > 1 ? "s" : ""} for standardize: ${unknown.map((key) => `--${key}`).join(", ")}.${valueHint} Known flags: ${STANDARDIZE_FLAGS.map((key) => `--${key}`).join(", ")}.`,
   );
 }
@@ -3227,7 +3419,7 @@ function standardizationReportCommand(args) {
   rejectUnknownStandardizeFlags(args);
   const target = optionalString(args.target);
   if (!target) {
-    throw new Error("standardize requires --target <campaign-repo> (a Page Kit root, a parent repo, or a Campaign Cart application checkout).");
+    throw refused("standardize requires --target <campaign-repo> (a Page Kit root, a parent repo, or a Campaign Cart application checkout).");
   }
   const family = optionalString(args.family) || optionalString(args["template-family"]);
   const slug = optionalString(args.slug);
@@ -3283,7 +3475,7 @@ function standardizationReportCommand(args) {
 function themeCommand(args) {
   const subcommand = args._[1] || "inspect";
   if (!["inspect", "generate", "waive"].includes(subcommand)) {
-    throw new Error(`Unknown theme subcommand "${subcommand}". Use: inspect | generate | waive.`);
+    throw refused(`Unknown theme subcommand "${subcommand}". Use: inspect | generate | waive.`);
   }
   if (subcommand === "waive") return themeWaive(args);
   const packetPath = resolve(requireArg(args, "packet"));
@@ -3325,20 +3517,25 @@ function themeCommand(args) {
 // improvising past advisory prose.
 export function themeWaive(args) {
   const packetPath = resolve(requireArg(args, "packet"));
+  const dryRun = isDryRun(args);
   const packet = readJson(packetPath);
   const reason = optionalString(args.reason);
-  if (!reason) throw new Error("theme waive requires --reason \"<why the starter palette is acceptable for this campaign>\".");
+  // A missing flag, raised after reading nothing but argv and the packet: a
+  // refusal, so the journal records nothing for it (docs/effects.md `*refused*`).
+  if (!reason) throw refused("theme waive requires --reason \"<why the starter palette is acceptable for this campaign>\".");
   // The same attribution rule as `checkpoint waive`: a named human, no
   // placeholder, an expiry (when given) that lies in the future and is
   // recorded. A bound is not demanded here: the theme gate's waiver has always
   // been open-ended, and QA re-surfaces the starter palette on every run.
-  const waiver = validateWaiverAttribution({
+  // A shared validator of argv alone, still ahead of the report read: its
+  // throws are refusals at this call site (the position decides, not the file).
+  const waiver = refusing(() => validateWaiverAttribution({
     reason,
     waivedBy: args["waived-by"] == null ? null : String(args["waived-by"]),
     expiresAt: args["expires-at"] == null ? null : String(args["expires-at"]),
     requireBound: false,
     label: "theme waive",
-  });
+  }));
   const workspace = resolveCampaignWorkspace(packetPath, {
     packet,
     reportPath: args.report ? resolve(args.report) : undefined,
@@ -3346,7 +3543,7 @@ export function themeWaive(args) {
   });
   const { reportPath } = workspace;
   if (!existsSync(reportPath)) throw new Error(`theme waive needs an assembly report at ${reportPath}; run prepare-build/start first.`);
-  commitAssemblyReport(workspace, (report) => {
+  const recordWaiver = (report) => {
     report.theme = report.theme && isObject(report.theme)
       ? { ...report.theme, waiver }
       : { status: "skipped", css_path: null, load_order: "not-applied", commerce_pages: [], evidence: [], warnings: [], repair_loop_defect: null, waiver };
@@ -3355,12 +3552,37 @@ export function themeWaive(args) {
       `Theme gate waived by ${waiver.waived_by} at ${waiver.waived_at}: ${reason}`,
     ];
     return report;
-  }, {
+  };
+  // Every check above is the real command's; only the commit is skipped. The
+  // readiness block is not reported for a dry run because doctor reads it off
+  // the report on disk, which by construction still has no waiver on it.
+  //
+  // Both modes go through the committing path itself (see
+  // commitWaiverToAssemblyReport): the dry run used to return on the existsSync
+  // check alone, so a torn report was reported as a successful `would_write`
+  // with exit 0 while the real invocation refused with "Assembly Report ... is
+  // not valid JSON" and exit 1, and a report that is not an object was previewed
+  // as writable while the commit refused it. Validation must never be weaker
+  // under --dry-run than without it.
+  commitWaiverToAssemblyReport(workspace, recordWaiver, {
     // #171: the waiver changes what doctor would conclude; the retained doctor
     // sidecar (if any) now predates it.
     command: "theme waive",
     staleReason: `A theme-gate waiver was recorded after this doctor snapshot. Re-run ${cmd("doctor")} (or next) for current state.`,
-  });
+  }, { dryRun });
+  if (dryRun) {
+    return {
+      ok: true,
+      status: "dry_run",
+      dry_run: true,
+      action: "theme-waive",
+      gate: "theme_gate",
+      waiver,
+      report_path: reportPath,
+      would_write: reportPath,
+      note: "Dry run: nothing was written and the doctor sidecar was not marked stale. Re-run without --dry-run to record this waiver.",
+    };
+  }
   return {
     ok: true,
     ...waiveReadiness(packetPath, reportPath),
@@ -3378,6 +3600,44 @@ export function themeWaive(args) {
 // "unknown" fallback. Doctor is re-run rather than patched from the pre-waive
 // result because a waiver changes what every other gate concludes about the
 // stage. Nothing is persisted here; the sidecar was already marked stale.
+/**
+ * The one route both waive commands take to the Assembly Report, real or
+ * previewed. `commitAssemblyReport` is called identically in both modes — same
+ * workspace, same mutator, same options — so every check the committing path
+ * makes runs on both: the report must exist, it must parse (a torn one fails by
+ * name), the mutator's own refusals fire, its result must be an Assembly Report
+ * object, and the derived summary is restated over that result. A dry run
+ * differs in one statement: this wrapper — not the mutator — returns `null` to
+ * commitAssemblyReport, which is its "nothing to write" answer, so the report
+ * is not rewritten and the doctor sidecar is not stamped stale. Nothing is
+ * re-implemented and nothing is skipped but the write itself. A mutator that
+ * returns nothing does not get to borrow that sentinel: it is a bug, and it
+ * throws here on both paths.
+ *
+ * The result-shape check and the summary restatement sit here rather than being
+ * left to commitAssemblyReport alone because they must run in BOTH modes and
+ * commitAssemblyReport reaches its own copies only on the way to the write.
+ * Running them here means one message and one order, not two: the real path
+ * now fails on this line and never on the copy in stage-ledger.mjs, so the two
+ * cannot drift into different text.
+ */
+export function commitWaiverToAssemblyReport(workspace, mutate, options, { dryRun = false } = {}) {
+  const previewOrCommit = (report) => {
+    const mutated = mutate(report);
+    // null and undefined are refused here rather than forwarded. Both waive
+    // mutators always return the report they built, and commitAssemblyReport
+    // reads a null result as "nothing to write" — so a mutator that forgot to
+    // return would skip the write silently while the command still reported the
+    // waiver recorded. That is a bug in the mutator and fails loudly. The dry
+    // run's own "do not write" is this wrapper's null below, not the mutator's.
+    if (!isPlainObject(mutated)) throw new TypeError("commitAssemblyReport mutate(report) must return an Assembly Report object.");
+    if (!dryRun) return mutated;
+    applyDerivedAssemblyReportSummary(mutated);
+    return null;
+  };
+  return commitAssemblyReport(workspace, previewOrCommit, options);
+}
+
 function waiveReadiness(packetPath, reportPath) {
   const doctor = doctorPacket(packetPath, { reportPath });
   return { status: doctor.status, next_stage: doctor.next?.stage || null, next_stage_reason: doctor.next?.reason || null };
@@ -3400,14 +3660,14 @@ function requireValidPolishCaptureReport(report, reportPath) {
 export async function polishCaptureCommand(args, options = {}) {
   const subcommand = args?._?.[1] || "help";
   if (subcommand !== "capture") {
-    throw new Error(
+    throw refused(
       `Unknown polish subcommand. Use: ${cmd("polish")} capture --packet <campaign-runtime.build.json> --base-url <url> [--report <json>] [--headed] [--auth-cookie <cookie>] [--json].`,
     );
   }
   const packetPath = resolve(requireArg(args, "packet"));
   const baseUrl = requireArg(args, "base-url");
-  if (args.report === true) throw new Error("Missing value for --report");
-  if (args["auth-cookie"] === true) throw new Error("Missing value for --auth-cookie");
+  if (args.report === true) throw refused("Missing value for --report");
+  if (args["auth-cookie"] === true) throw refused("Missing value for --auth-cookie");
 
   const packet = readJson(packetPath);
   const workspace = resolveCampaignWorkspace(packetPath, {
@@ -3547,13 +3807,14 @@ function waiveOrRefuse(args, run, { gate = null, registeredGates = [] } = {}) {
 function checkpointCommand(args) {
   const subcommand = args._[1] || "help";
   if (subcommand !== "waive") {
-    throw new Error(`Unknown checkpoint subcommand. Use: ${cmd("checkpoint")} waive --packet <campaign-runtime.build.json> --gate <checkpoint-id> --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"]. Registered gates: ${Object.keys(CHECKPOINT_EVALUATORS).join(", ")}.`);
+    throw refused(`Unknown checkpoint subcommand. Use: ${cmd("checkpoint")} waive --packet <campaign-runtime.build.json> --gate <checkpoint-id> --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"]. Registered gates: ${Object.keys(CHECKPOINT_EVALUATORS).join(", ")}.`);
   }
   return checkpointWaive(args);
 }
 
 export function checkpointWaive(args) {
   const packetPath = resolve(requireArg(args, "packet"));
+  const dryRun = isDryRun(args);
   const gateId = requireArg(args, "gate").trim();
   const reason = requireArg(args, "reason");
   const waivedBy = requireArg(args, "waived-by");
@@ -3570,7 +3831,7 @@ export function checkpointWaive(args) {
 
   const doctor = doctorPacket(packetPath, { reportPath });
   let waiver = null;
-  commitAssemblyReport(workspace, (report) => {
+  const recordWaiver = (report) => {
     const gate = evaluateCheckpointRegistry(CHECKPOINT_EVALUATORS, gateId, { doctor, packet, report });
     if (!gate) throw new Error(`Checkpoint gate "${gateId}" has no current evidence; repair the packet/spec/target and re-run doctor.`);
     if (gate.status !== "blocked") {
@@ -3591,10 +3852,30 @@ export function checkpointWaive(args) {
       `Checkpoint waiver: ${gateId} waived by ${waiver.waived_by} at ${waiver.waived_at}: ${waiver.reason}`,
     ];
     return updated;
-  }, {
+  };
+  // The gate registry decides waivability from the report, so both modes go
+  // through the committing path itself (see commitWaiverToAssemblyReport): the
+  // report is read and parsed the same way and the very same mutator runs over
+  // it, so every refusal above fires exactly as it would for real. Only the
+  // write and the doctor-sidecar stale stamp are skipped, and with them the
+  // readiness block, which doctor can only read off a report on disk.
+  commitWaiverToAssemblyReport(workspace, recordWaiver, {
     command: "checkpoint waive",
     staleReason: `A checkpoint waiver was recorded after this doctor snapshot. Re-run ${cmd("doctor")} (or next) for current state.`,
-  });
+  }, { dryRun });
+  if (dryRun) {
+    return {
+      ok: true,
+      status: "dry_run",
+      dry_run: true,
+      action: "checkpoint-waive",
+      gate: gateId,
+      waiver,
+      report_path: reportPath,
+      would_write: reportPath,
+      note: "Dry run: nothing was written and the doctor sidecar was not marked stale. Re-run without --dry-run to record this waiver.",
+    };
+  }
   return {
     ok: true,
     ...waiveReadiness(packetPath, reportPath),
@@ -3626,11 +3907,17 @@ export function doctorPacket(packetPath, options = {}) {
   // to go by first. Code granularity, because that is the granularity the
   // record stores. baseDir is the packet directory, the same root the Run
   // Record writes under.
+  // An invalid identity cannot select history. In particular, withholding a
+  // malformed local ID from derived must not turn it into an unfiltered or
+  // Map-only lookup of another campaign's findings.
+  const comparableIdentity = resolveCampaignIdentity(result.derived)
+    && !result.errors.some(issue => issue.code === "spec.local_identity" || issue.code === "spec.map_id");
   result.cause_summary = annotateDoctorIssueCauses({
     errors: result.errors,
     warnings: result.warnings,
-    baseDir: dirname(resolve(packetPath)),
+    baseDir: comparableIdentity ? dirname(resolve(packetPath)) : null,
     mapId: result.derived?.map_id || null,
+    localSpecId: result.derived?.local_spec_id || null,
   });
   return result;
 }
@@ -3650,6 +3937,7 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
   const errors = [];
   const warnings = [];
   const ready = [];
+  const packetIdentity = resolveCampaignIdentity(packet?.spec);
   const derived = {
     packet_path: packetPath,
     // The report this inspection read (null when the caller switched the
@@ -3657,6 +3945,7 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
     // different file.
     assembly_report_path: typeof resolvedReportPath === "string" ? resolvedReportPath : null,
     map_id: packet?.spec?.map_id || null,
+    ...(packetIdentity?.kind === "local_spec" ? { local_spec_id: packetIdentity.id } : {}),
     public_route_slug: packet?.campaign?.public_route_slug || null,
     template_family: packet?.assembly?.template_family || null,
     source_root: null,
@@ -4090,7 +4379,10 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
 
   requireString(packet, errors, "campaign.public_route_slug");
   requireBoolean(packet, errors, "campaign.allowed_domains_confirmed");
-  requireString(packet, errors, "spec.map_id");
+  if (!resolveCampaignIdentity(packet.spec)) addIssue(errors, packet.spec?.local_spec_id != null ? "spec.local_identity" : "spec.map_id", "Packet spec requires exactly one valid map_id or local_spec_id.", { kind: packet.spec?.local_spec_id != null ? "local_spec" : "saved_map" });
+  if (packet.spec?.local_spec_id != null && (packet.spec.spec_url != null || !isNonEmptyString(packet.spec.local_path))) {
+    addIssue(errors, "spec.local_identity", "Local-spec packets require a local_path and no saved-Map spec_url.");
+  }
   if (!synthesizedBuiltSite) {
     requireString(packet, errors, "source_html.root");
     requireArray(packet, errors, "source_html.pages");
@@ -4276,8 +4568,11 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
     buildState.specStatus = specStatus;
     if (specStatus === "ok") {
       const specMapId = spec.spec_identity?.map_id || spec.map_id;
-      if (specMapId && specMapId !== packet.spec.map_id) {
-        addIssue(errors, "spec.map_id", `Packet map_id "${packet.spec.map_id}" does not match CampaignSpec map_id "${specMapId}".`);
+      if ((specMapId && specMapId !== packet.spec.map_id)
+        || ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
+          && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec))) {
+        const localIdentity = spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null;
+        addIssue(errors, localIdentity ? "spec.local_identity" : "spec.map_id", "Packet identity does not match the CampaignSpec map_id/local_spec_id.", { kind: localIdentity ? "local_spec" : "saved_map" });
       }
       ready.push("Local CampaignSpec parsed");
       runDoctorChecks(SPEC_DOCTOR_CHECKS, { packet, packetPath, spec, targetRepo, errors, warnings, ready, derived, buildState });
@@ -4685,16 +4980,10 @@ export function pageKitSyncCommand(args) {
   const unknown = Object.keys(args).filter((key) => key !== "_" && !PAGE_KIT_SYNC_FLAGS.includes(key));
   if (unknown.length) {
     const valueHint = unknown.some((key) => key.includes("=")) ? " A flag takes its value as the next argument (--flag value), not --flag=value." : "";
-    throw new Error(`Unknown flag${unknown.length > 1 ? "s" : ""} for page-kit sync: ${unknown.map((key) => `--${key}`).join(", ")}.${valueHint} Known flags: ${PAGE_KIT_SYNC_FLAGS.map((key) => `--${key}`).join(", ")}.`);
+    throw refused(`Unknown flag${unknown.length > 1 ? "s" : ""} for page-kit sync: ${unknown.map((key) => `--${key}`).join(", ")}.${valueHint} Known flags: ${PAGE_KIT_SYNC_FLAGS.map((key) => `--${key}`).join(", ")}.`);
   }
   const packetPath = resolve(requireArg(args, "packet"));
-  // `--dry-run` is a bare flag. The shared parser would read a following
-  // token as its value, so `--dry-run true` must fail rather than quietly
-  // become a real write.
-  if (Object.hasOwn(args, "dry-run") && args["dry-run"] !== true) {
-    throw new Error(`--dry-run takes no value (got ${JSON.stringify(args["dry-run"])}); write \`--dry-run\` on its own, after the other flags.`);
-  }
-  const dryRun = args["dry-run"] === true;
+  const dryRun = isDryRun(args);
   const result = {
     ok: false,
     action: "page-kit sync",
@@ -4778,6 +5067,9 @@ export function pageKitSyncCommand(args) {
       addIssue(result.errors, "page_kit.sync.spec_identity_mismatch", `CampaignSpec identifies route "${singleLineField(specSlug)}" but the packet's campaign.public_route_slug is "${publicRouteSlug}". Point spec.local_path at this campaign's export (or re-run prepare-build from it); nothing was written.`);
     } else if (specMapId && packetMapId && specMapId !== packetMapId) {
       addIssue(result.errors, "page_kit.sync.spec_identity_mismatch", `CampaignSpec spec_identity.map_id "${singleLineField(specMapId)}" does not match the packet's spec.map_id "${singleLineField(packetMapId)}". Point spec.local_path at this campaign's export (or re-run prepare-build from it); nothing was written.`);
+    } else if ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
+      && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec)) {
+      addIssue(result.errors, "page_kit.sync.spec_identity_mismatch", "CampaignSpec identity (spec_identity.map_id/local_spec_id) does not match the packet identity. Point spec.local_path at this campaign's spec (or re-run prepare-build from it); nothing was written.");
     }
   }
 
@@ -4918,8 +5210,8 @@ export function pageKitSyncCommand(args) {
 // refereed by doctor. Exactly the derived fields are written; the rest of the
 // spec and every other file are untouched. The store-derived fields (the nine
 // campaign.store_* Store Profile fields, slice 2) join the write only behind
-// --from-store <subdomain>, which reads the store's Admin API with the token
-// named by --store-token-source env:<VAR> (default env:<SUBDOMAIN>_ADMIN_TOKEN);
+// --from-store <subdomain>, which reads the store's Admin API
+// through gateway login, or the explicit --store-token-source env:<VAR> break-glass path;
 // the default run stays offline. --dry-run prints the same diff and writes
 // nothing. Exit 2 when the packet, the spec or the target entry is missing,
 // or the store cannot be read.
@@ -4931,17 +5223,17 @@ const SPEC_DERIVE_FLAGS = Object.freeze(["packet", "dry-run", "json", "report",
 // mistake as an unknown flag: refused before anything is read).
 function parseSpecDeriveStoreFlags(args) {
   if (!Object.hasOwn(args, "from-store")) {
-    if (Object.hasOwn(args, "store-token-source")) throw new Error("--store-token-source only applies with --from-store <subdomain>.");
+    if (Object.hasOwn(args, "store-token-source")) throw refused("--store-token-source only applies with --from-store <subdomain>.");
     return null;
   }
   const subdomain = normalizeStoreSubdomain(args["from-store"] === true ? "" : String(args["from-store"] ?? ""));
   if (!subdomain) {
-    throw new Error(`--from-store takes the store's subdomain (the <store> of <store>.29next.store), got ${JSON.stringify(args["from-store"] === true ? "" : args["from-store"])}.`);
+    throw refused(`--from-store takes the store's subdomain (the <store> of <store>.29next.store), got ${JSON.stringify(args["from-store"] === true ? "" : args["from-store"])}.`);
   }
-  let tokenEnv = defaultStoreTokenEnvVar(subdomain);
+  let tokenEnv = null;
   if (Object.hasOwn(args, "store-token-source")) {
     const parsed = parseStoreTokenSource(args["store-token-source"] === true ? "" : String(args["store-token-source"] ?? ""));
-    if (parsed.problem) throw new Error(`--store-token-source ${parsed.problem}`);
+    if (parsed.problem) throw refused(`--store-token-source ${parsed.problem}`);
     tokenEnv = parsed.env;
   }
   return { subdomain, token_env: tokenEnv };
@@ -4950,23 +5242,22 @@ function parseSpecDeriveStoreFlags(args) {
 // `spec derive --from-store`: resolve the credential, read the store, then
 // run the same command with the store read in hand. The only network the
 // command ever does happens here, and the token never leaves this function:
-// the result names the env var, not its value.
-export async function specDeriveFromStoreCommand(args, { fetchImpl = globalThis.fetch, env = process.env } = {}) {
+// the result names the credential source, never its value.
+export async function specDeriveFromStoreCommand(args, { fetchImpl = globalThis.fetch, env = process.env, credentials, warn = console.warn } = {}) {
   const store = parseSpecDeriveStoreFlags(args);
   if (!store) return specDeriveCommand(args);
-  const token = typeof env[store.token_env] === "string" ? env[store.token_env].trim() : "";
-  if (!token) {
-    return specDeriveCommand(args, { store: { ...store, status: "credential_missing", detail: `${store.token_env} is not set (or empty) in the environment; export the store's Admin API access token there (Settings > API Access, scopes store:read and content:read), or name another variable with --store-token-source env:<VAR>.` } });
-  }
-  // Local preconditions first: a packet, spec or entry the command would
-  // refuse is refused before the token is sent anywhere. The preflight run
-  // stops at the store gate and writes nothing.
   const preflight = specDeriveCommand(args, { store: { ...store, status: "preflight" } });
   if (preflight.errors.length) return preflight;
-  const read = await readStoreProfile({ subdomain: store.subdomain, token, fetchImpl });
-  // The real run re-reads the packet; it must still be the campaign the
-  // preflight checked, or the store's profile lands in another campaign's
-  // spec.
+  let read;
+  if (store.token_env) {
+    warn("Warning: explicit Admin environment credentials are a break-glass path. Use campaigns-os login --store <subdomain> and omit --store-token-source for supported gateway reads.");
+    const token = typeof env[store.token_env] === "string" ? env[store.token_env].trim() : "";
+    read = token ? await readStoreProfile({ subdomain: store.subdomain, token, fetchImpl }) : { status: "credential_missing", detail: `${store.token_env} is not set (or empty); use campaigns-os login --store ${store.subdomain}, or explicitly supply the break-glass environment credential.` };
+  } else {
+    const { readGatewayStoreProfile } = await import("./admin-transport.mjs");
+    read = await readGatewayStoreProfile({ subdomain: store.subdomain, credentials, fetchImpl });
+  }
+  // Recheck the original packet/spec identity after the network operation.
   return specDeriveCommand(args, { store: { ...store, ...read, expected: { spec_path: preflight.spec_path, public_route_slug: preflight.public_route_slug } } });
 }
 
@@ -5019,7 +5310,7 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
   const unknown = Object.keys(args).filter((key) => key !== "_" && !SPEC_DERIVE_FLAGS.includes(key));
   if (unknown.length) {
     const valueHint = unknown.some((key) => key.includes("=")) ? " A flag takes its value as the next argument (--flag value), not --flag=value." : "";
-    throw new Error(`Unknown flag${unknown.length > 1 ? "s" : ""} for spec derive: ${unknown.map((key) => `--${key}`).join(", ")}.${valueHint} Known flags: ${SPEC_DERIVE_FLAGS.map((key) => `--${key}`).join(", ")}.`);
+    throw refused(`Unknown flag${unknown.length > 1 ? "s" : ""} for spec derive: ${unknown.map((key) => `--${key}`).join(", ")}.${valueHint} Known flags: ${SPEC_DERIVE_FLAGS.map((key) => `--${key}`).join(", ")}.`);
   }
   // The store read is supplied by specDeriveFromStoreCommand; this function
   // never touches the network itself, so a --from-store call that reaches it
@@ -5027,13 +5318,8 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
   const storeFlags = parseSpecDeriveStoreFlags(args);
   if (storeFlags && !storeRead) throw new Error("spec derive --from-store must be dispatched through specDeriveFromStoreCommand (no store read was supplied).");
   const packetPath = resolve(requireArg(args, "packet"));
-  // `--dry-run` is a bare flag; `--dry-run true` must fail rather than
-  // quietly become a real write.
-  if (Object.hasOwn(args, "dry-run") && args["dry-run"] !== true) {
-    throw new Error(`--dry-run takes no value (got ${JSON.stringify(args["dry-run"])}); write \`--dry-run\` on its own, after the other flags.`);
-  }
-  if (args.report === true) throw new Error("Missing value for --report");
-  const dryRun = args["dry-run"] === true;
+  const dryRun = isDryRun(args);
+  if (args.report === true) throw refused("Missing value for --report");
   const result = {
     ok: false,
     action: "spec derive",
@@ -5053,7 +5339,7 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
     not_in_target: [],
     stale_hints: [],
     store: storeFlags
-      ? { subdomain: storeFlags.subdomain, admin_api: adminApiBaseForStore(storeFlags.subdomain), token_source: `env:${storeFlags.token_env}`, store_read: null, pages_read: null, primary_domain: null }
+      ? { subdomain: storeFlags.subdomain, admin_api: adminApiBaseForStore(storeFlags.subdomain), ...(storeFlags.token_env ? {} : { transport: "gateway", endpoint: "https://mcp.nextcommerce.com/admin/" }), token_source: storeFlags.token_env ? `env:${storeFlags.token_env}` : "gateway:login", store_read: null, pages_read: null, primary_domain: null }
       : null,
     rebound: { build_context: null, assembly_report: null },
     errors: [],
@@ -5127,6 +5413,9 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
       addIssue(result.errors, "spec.derive.spec_identity_mismatch", `CampaignSpec identifies route "${singleLineField(specSlug)}" but the packet's campaign.public_route_slug is "${publicRouteSlug}". Point spec.local_path at this campaign's export (or re-run prepare-build from it); nothing was written.`);
     } else if (specMapId && packetMapId && specMapId !== packetMapId) {
       addIssue(result.errors, "spec.derive.spec_identity_mismatch", `CampaignSpec spec_identity.map_id "${singleLineField(specMapId)}" does not match the packet's spec.map_id "${singleLineField(packetMapId)}". Point spec.local_path at this campaign's export (or re-run prepare-build from it); nothing was written.`);
+    } else if ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
+      && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec)) {
+      addIssue(result.errors, "spec.derive.spec_identity_mismatch", "CampaignSpec identity (spec_identity.map_id/local_spec_id) does not match the packet identity. Point spec.local_path at this campaign's spec (or re-run prepare-build from it); nothing was written.");
     }
   }
 
@@ -5236,8 +5525,8 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
     return result;
   }
   if (storeRead && storeRead.status !== "ok") {
-    const codes = { credential_missing: "store_credential_missing", credential_invalid: "store_credential_invalid", unauthorized: "store_unauthorized", not_found: "store_not_found", unreachable: "store_unreachable", invalid: "store_response_invalid" };
-    addIssue(result.errors, `spec.derive.${codes[storeRead.status] || "store_unreachable"}`, `${storeRead.detail} Nothing was written.`, { subdomain: storeRead.subdomain, token_source: `env:${storeRead.token_env}` });
+    const codes = { credential_unavailable: "store_credential_unavailable", credential_missing: "store_credential_missing", credential_invalid: "store_credential_invalid", unauthorized: "store_unauthorized", not_found: "store_not_found", unreachable: "store_unreachable", invalid: "store_response_invalid" };
+    addIssue(result.errors, `spec.derive.${codes[storeRead.status] || "store_unreachable"}`, `${storeRead.detail} Nothing was written.`, { subdomain: storeRead.subdomain, token_source: storeRead.token_env ? `env:${storeRead.token_env}` : "gateway:login" });
     return result;
   }
   const plan = planSpecDerive({ spec, entry, pageFiles, packetBindings, waivedGates, waiversUnknown, publicRouteSlug });
@@ -5440,7 +5729,7 @@ export function specDeriveTextLines(result) {
   if (result.spec_path) lines.push(`Spec: ${singleLineField(result.spec_path)}`);
   if (result.campaigns_path) lines.push(`Target: ${singleLineField(result.campaigns_path)}[${result.public_route_slug || "<public-route-slug>"}]${result.page_tree ? `, page tree ${singleLineField(result.page_tree)}/` : ""}`);
   if (result.store) {
-    lines.push(`Store: ${singleLineField(result.store.admin_api)} (token ${singleLineField(result.store.token_source)}${result.store.primary_domain ? `, primary domain ${singleLineField(result.store.primary_domain)}` : ""}${result.store.pages_read && result.store.pages_read !== "ok" ? `, pages ${result.store.pages_read}` : ""})`);
+    lines.push(`Store: ${singleLineField(result.store.endpoint || result.store.admin_api)} (token ${singleLineField(result.store.token_source)}${result.store.primary_domain ? `, primary domain ${singleLineField(result.store.primary_domain)}` : ""}${result.store.pages_read && result.store.pages_read !== "ok" ? `, pages ${result.store.pages_read}` : ""})`);
   }
   if (result.errors?.length) {
     lines.push("Errors:");
@@ -5481,9 +5770,9 @@ const PAGE_KIT_PARITY_FLAGS = Object.freeze(["packet", "json", "report"]);
 export function pageKitParityCommand(args, options = {}) {
   const unknown = Object.keys(args).filter((key) => key !== "_" && !PAGE_KIT_PARITY_FLAGS.includes(key));
   if (unknown.length) {
-    throw new Error(`Unknown flag${unknown.length > 1 ? "s" : ""} for page-kit parity: ${unknown.map((key) => `--${key}`).join(", ")}. Known flags: ${PAGE_KIT_PARITY_FLAGS.map((key) => `--${key}`).join(", ")}.`);
+    throw refused(`Unknown flag${unknown.length > 1 ? "s" : ""} for page-kit parity: ${unknown.map((key) => `--${key}`).join(", ")}. Known flags: ${PAGE_KIT_PARITY_FLAGS.map((key) => `--${key}`).join(", ")}.`);
   }
-  if (args.report === true) throw new Error("Missing value for --report");
+  if (args.report === true) throw refused("Missing value for --report");
   const packetPath = resolve(requireArg(args, "packet"));
   const result = {
     ok: false,
@@ -5911,15 +6200,15 @@ function validateSpecPackageAvailability(spec, warnings, ready) {
 
 function validateSpecIdentityExport(spec, warnings, ready) {
   const identity = spec?.spec_identity;
-  if (isObject(identity) && isNonEmptyString(identity.map_id) && isNonEmptyString(identity.public_route_slug)) {
-    ready.push("CampaignSpec spec_identity includes map_id and public_route_slug");
+  if (isObject(identity) && resolveCampaignIdentity(identity) && isNonEmptyString(identity.public_route_slug)) {
+    ready.push(`CampaignSpec spec_identity includes ${identity.local_spec_id ? "local_spec_id" : "map_id"} and public_route_slug`);
     return;
   }
 
   addIssue(
     warnings,
     "spec_identity.export",
-    "CampaignSpec is missing complete spec_identity.map_id/public_route_slug. Prefer re-exporting from a saved Map Builder map; CLI identity overrides should stay diagnostic-only."
+    "CampaignSpec is missing complete spec_identity: declare map_id for a saved Map or local_spec_id for a local spec, plus public_route_slug. CLI identity overrides should stay diagnostic-only."
   );
 }
 
@@ -8802,7 +9091,12 @@ function validateAssemblyReport(report, { checkSourcePackageFreshness = true } =
   if (report.schema_version !== REPORT_SCHEMA) addIssue(errors, "schema_version", `Expected ${REPORT_SCHEMA}.`);
   else ready.push(`Assembly report schema ${REPORT_SCHEMA}`);
   for (const path of ["run_id", "generated_at", "status", "identity.map_id", "identity.public_route_slug", "inputs.packet_path", "template_family.value"]) {
-    requireString(report, errors, path);
+    if (path === "identity.map_id") {
+      if (!resolveCampaignIdentity(report.identity)) addIssue(errors, "identity.map_id", "Assembly Report requires exactly one valid map_id or local_spec_id.");
+    } else requireString(report, errors, path);
+  }
+  if (report.identity?.local_spec_id != null && !/^sha256:[0-9a-f]{64}$/.test(report.identity.spec_material_hash || "")) {
+    addIssue(errors, "identity.spec_material_hash", "Local-spec reports require a current SHA-256 material spec hash.");
   }
   const stages = report.stages;
   if (!isObject(stages)) {
@@ -9052,13 +9346,14 @@ function nextPrepareBuildBindingIssues({
   const expectedSlug = optionalString(packet.campaign?.public_route_slug);
   const recordedMapId = optionalString(report.identity?.map_id);
   const recordedSlug = optionalString(report.identity?.public_route_slug);
-  if (recordedMapId !== expectedMapId || recordedSlug !== expectedSlug) {
+  if (!campaignIdentitiesMatch(packet.spec, report.identity) || recordedSlug !== expectedSlug) {
     push(
       "next.prepare_build.report_campaign_mismatch",
       "Assembly Report campaign identity does not match the current Build Packet.",
       {
-        expected: { map_id: expectedMapId, public_route_slug: expectedSlug },
-        recorded: { map_id: recordedMapId, public_route_slug: recordedSlug },
+        // Failed identity fields are diagnostic data, never adopted evidence.
+        expected: { map_id: expectedMapId, local_spec_id: packet.spec?.local_spec_id ?? null, public_route_slug: expectedSlug },
+        recorded: { map_id: recordedMapId, local_spec_id: report.identity?.local_spec_id ?? null, public_route_slug: recordedSlug },
       },
     );
   }
@@ -9467,6 +9762,9 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
 }
 
 export function nextStage(stage, args, ambient = null) {
+  if (stage !== null && !NEXT_STAGE_ORDER.includes(stage)) {
+    throw refused(`Unknown next stage: ${stage}. Accepted stages: ${NEXT_STAGE_ORDER.join(", ")}.`);
+  }
   const packetPath = resolve(requireArg(args, "packet"));
   // A custom prepare-build report is recorded on the Build Context relative
   // to the target repo. Packet-only `next` must follow that durable pointer;
@@ -9672,8 +9970,6 @@ export function nextStage(stage, args, ambient = null) {
     addPolishCheckpointGateErrors(errors, polishCheckpointGate, "qa");
     addThemeGateErrors(errors, themeGate, "qa");
     prompt = qaPrompt(packetPath, reportPath, packet);
-  } else {
-    throw new Error(`Unknown next stage: ${stage}`);
   }
   const status = errors.length
     ? "blocked"
@@ -10380,7 +10676,7 @@ function qaPrompt(packetPath, reportPath, packet) {
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
   return `Use next-campaigns-qa for this deployed campaign.
 
-Map ID: ${packet.spec.map_id}
+${packet.spec.local_spec_id ? "Local spec ID" : "Map ID"}: ${packet.spec.local_spec_id || packet.spec.map_id}
 Base URL: ${url}
 Build Packet: ${packetPath}
 Assembly Report: ${reportPath}
@@ -10784,7 +11080,7 @@ function resolveSkillInstallTargets(targetArg = null, platformArg = null) {
     : SKILL_PLATFORMS.filter((platform) => platform.id === requested);
 
   if (!selected.length) {
-    throw new Error(`Unknown --platform ${requested}. Use one of: ${skillPlatformHelp()}.`);
+    throw refused(`Unknown --platform ${requested}. Use one of: ${skillPlatformHelp()}.`);
   }
 
   return selected.map((platform) => ({
@@ -10847,6 +11143,31 @@ function installSkills(targetArg = null, dryRun = false, platformArg = null) {
   };
 }
 
+// A platform directory counts as installed when a skill already sits under one
+// of the bundled names (current or not), or our own copy under a retired name. A
+// slot install-skills would only create says nothing about that platform, and
+// neither does a retired slot another skill occupies. A foreign skill under a
+// CURRENT bundled name reads as `updated` — install-skills would replace it —
+// so it does count; the refresh action is then what install-skills would do.
+const SKILL_ACTIONS_THAT_MARK_A_PLATFORM_INSTALLED = new Set(["unchanged", "updated", "retired"]);
+
+export function scopeSkillStatusToInstalledPlatforms(status) {
+  if (!Array.isArray(status?.targets)) return { status, scope: "requested", notInstalled: [] };
+  const installedOn = (target) => (target.skills || []).some((skill) => SKILL_ACTIONS_THAT_MARK_A_PLATFORM_INSTALLED.has(skill?.action));
+  const installed = status.targets.filter(installedOn);
+  const describe = (target) => ({
+    platform: target.platform,
+    platform_label: target.platform_label,
+    target_directory: target.target_directory,
+  });
+  if (!installed.length) return { status, scope: "no_platform_installed", notInstalled: status.targets.map(describe) };
+  return {
+    status: { ...status, targets: installed, skills: installed.flatMap((target) => target.skills) },
+    scope: "installed_platforms",
+    notInstalled: status.targets.filter((target) => !installedOn(target)).map(describe),
+  };
+}
+
 const TOOLING_ACTIONABLE_SKILL_ACTIONS = new Set(["created", "updated", "retired"]);
 const TOOLING_CLEAN_SKILL_ACTIONS = new Set(["unchanged"]);
 
@@ -10871,14 +11192,344 @@ function toolingSkillIdentity(skill) {
   return `${prefix}${skill?.name || "unknown skill"}`;
 }
 
+/**
+ * `--skills-revision <value>`: the skills bundle identity an agent read, checked
+ * against the bundle THIS CLI ships.
+ *
+ * The asymmetry is the whole point, and it is why the reported revision is named
+ * `on_disk`. A skill's text is pulled into an agent's context once, at the start
+ * of the task, and is never re-read; the CLI on disk, meanwhile, can be updated
+ * underneath that session by an `npm install`, an `npx` cache refresh, or a
+ * `git pull` in the checkout. So the only honest comparison is "what you are
+ * still reading" against "what is installed right now", and the only honest
+ * remedy for a mismatch is a fresh session — re-running the command cannot pull
+ * the newer skill text into a context that already has the older one.
+ *
+ * The bundle spelling (`<package version>+skills.<n>`) is what every SKILL.md
+ * states on its first body line. The `<skill-id>@<version>` spelling is a
+ * fallback for an agent that carries only the frontmatter of the one skill it
+ * loaded; it is checked against that skill's manifest entry. An id this bundle
+ * does not ship is a mismatch, not a refusal: an agent quoting a skill that is
+ * not here is reading text from some other bundle, which is exactly the
+ * condition this flag exists to catch.
+ */
+export function parseSkillsRevisionArg(value) {
+  const text = String(value).trim();
+  const at = text.lastIndexOf("@");
+  if (at > 0 && at < text.length - 1) {
+    return { spelling: "skill", id: text.slice(0, at), version: text.slice(at + 1), requested: text };
+  }
+  return { spelling: "bundle", requested: text };
+}
+
+export function evaluateSkillsRevision(value, manifest) {
+  const onDisk = typeof manifest?.bundle_revision === "string" ? manifest.bundle_revision : null;
+  if (value === undefined) {
+    return {
+      status: "unchecked",
+      requested: null,
+      spelling: null,
+      on_disk: onDisk,
+      on_disk_skill: null,
+      message: `unchecked (on disk ${onDisk || "unknown"})`,
+    };
+  }
+  const parsed = parseSkillsRevisionArg(value);
+  if (parsed.spelling === "skill") {
+    const entry = (manifest?.skills || []).find((skill) => skill?.id === parsed.id) || null;
+    const onDiskSkill = entry ? { id: entry.id, version: entry.version ?? null } : null;
+    const match = Boolean(entry) && entry.version === parsed.version;
+    return {
+      status: match ? "match" : "mismatch",
+      requested: parsed.requested,
+      spelling: "skill",
+      on_disk: onDisk,
+      on_disk_skill: onDiskSkill,
+      message: match
+        ? `match (${parsed.requested}; bundle ${onDisk || "unknown"})`
+        : `mismatch: loaded ${parsed.requested}, on disk ${
+            onDiskSkill ? `${onDiskSkill.id}@${onDiskSkill.version}` : `no skill named ${parsed.id}`
+          } (bundle ${onDisk || "unknown"}) — start a fresh session`,
+    };
+  }
+  const match = Boolean(onDisk) && onDisk === parsed.requested;
+  return {
+    status: match ? "match" : "mismatch",
+    requested: parsed.requested,
+    spelling: "bundle",
+    on_disk: onDisk,
+    on_disk_skill: null,
+    message: match
+      ? `match (${onDisk})`
+      : `mismatch: loaded ${parsed.requested}, on disk ${onDisk || "unknown"} — start a fresh session`,
+  };
+}
+
+export function skillsRevisionTextLines(result) {
+  const revision = result?.skills_revision;
+  return revision ? [`Skills revision: ${revision.message}`] : [];
+}
+
+// The pin checks (ADR 0002, campaigns-os#466): one executable per project. The
+// project pin (an exact devDependency or dependency on this package) comes
+// first, the kernel version the Build Packet records second. Only an exact
+// version is a pin — a range or tag names no one executable, so it is reported
+// as `range` and the project counts as unpinned.
+const PIN_PACKAGE_NAME = "@nextcommerce/campaigns-os";
+const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+// npm reads `=1.2.3` and `v1.2.3` as the exact version 1.2.3.
+const EXACT_PIN_SPEC_RE = /^=?v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)$/;
+// peerDependencies and optionalDependencies install nothing this project runs.
+const PIN_KEYS = ["devDependencies", "dependencies"];
+const PIN_BLOCKING_STATUSES = new Set(["conflicting_pin", "stale_pin"]);
+
+function exactPinVersion(spec) {
+  return typeof spec === "string" ? EXACT_PIN_SPEC_RE.exec(spec)?.[1] ?? null : null;
+}
+
+// An installed package's own manifest (node_modules/<name>/package.json or
+// node_modules/@<scope>/<name>/package.json) is never the project: run from
+// inside an install, the walk resolves the enclosing project as if the working
+// directory were that project. Any other manifest is a candidate, even one with
+// a node_modules segment higher up its path.
+function isInstalledPackageDir(dir) {
+  const parent = dirname(dir);
+  if (basename(parent) === "node_modules") return true;
+  return basename(parent).startsWith("@") && basename(dirname(parent)) === "node_modules";
+}
+
+function nearestPackageJson(startDir) {
+  for (let dir = resolve(startDir); ; dir = dirname(dir)) {
+    const candidate = join(dir, "package.json");
+    if (!isInstalledPackageDir(dir) && existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+// npm's array form, or the `{ packages: [...] }` object form yarn also reads.
+function declaresWorkspaces(manifest) {
+  const workspaces = manifest.workspaces;
+  return Array.isArray(workspaces) || (isObject(workspaces) && Array.isArray(workspaces.packages));
+}
+
+// An empty or whitespace-only spec pins nothing, so it counts as absent rather
+// than as a range.
+function pinSpecsIn(manifest) {
+  return PIN_KEYS.flatMap((key) => {
+    const spec = manifest?.[key]?.[PIN_PACKAGE_NAME];
+    return typeof spec === "string" && spec.trim() ? [{ key, spec: spec.trim() }] : [];
+  });
+}
+
+// The project pin is the first exact spec on the walk up from the nearest
+// manifest, devDependencies before dependencies in each; a range is kept only
+// if nothing exact turns up. A manifest that names nothing is
+// neutral and walked through: it cannot supply a pin, so stopping there would
+// only hide one higher up. The walk ends after a workspace root, at the
+// filesystem root, and at a manifest it cannot read, with a warning, since
+// that one might have held the pin.
+function resolveProjectPin(packageJsonPath, warnings) {
+  let range = null;
+  for (let path = packageJsonPath; path; path = nearestPackageJson(dirname(dirname(path)))) {
+    const problem = {};
+    const manifest = readPinJson(path, problem);
+    if (!manifest) {
+      warnings.push(path === packageJsonPath
+        ? `Project pin unavailable: ${path} ${problem.reason}.`
+        : `Project pin walk stopped at ${path}: it ${problem.reason}.`);
+      break;
+    }
+    const specs = pinSpecsIn(manifest);
+    const exact = specs.find(({ spec }) => exactPinVersion(spec));
+    if (exact) return { projectSpec: exact.spec, projectManifest: path, projectKey: exact.key };
+    if (!range && specs.length) range = { projectSpec: specs[0].spec, projectManifest: path, projectKey: specs[0].key };
+    if (declaresWorkspaces(manifest) || dirname(dirname(path)) === dirname(path)) break;
+  }
+  return range || { projectSpec: null, projectManifest: packageJsonPath, projectKey: null };
+}
+
+// A malformed file is a missing source plus a warning, never a crash: the pin
+// line is one report among several and must not take the status down with it.
+// A leading BOM is valid to npm, so it is valid here.
+function readPinJson(path, problem = {}) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    problem.reason = `could not be read (${error.code || error.message})`;
+    return null;
+  }
+  let value;
+  try {
+    value = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch {
+    problem.reason = "is not valid JSON";
+    return null;
+  }
+  if (isObject(value)) return value;
+  problem.reason = "is not a JSON object";
+  return null;
+}
+
+/** The project and packet sources `tooling status` compares, read from disk. */
+export function resolvePinSources(args, { cwd = process.cwd() } = {}) {
+  const warnings = [];
+  const explicitPacket = optionalString(args.packet);
+  let packetPath = explicitPacket ? resolve(cwd, explicitPacket) : null;
+  let packet = null;
+  const packetProblem = {};
+  if (packetPath) {
+    if (!existsSync(packetPath)) throw refused(`Build Packet not found: ${packetPath}`);
+    packet = readPinJson(packetPath, packetProblem);
+  }
+  // An explicit packet names its project: its target repo, whatever the cwd.
+  const projectStart = packet ? targetRepoFor(packetPath, packet) : cwd;
+  const packageJsonPath = nearestPackageJson(projectStart);
+  if (!packetPath) {
+    // The contracted home of the packet is the project root beside package.json
+    // (prepare-build's default --out), the same place readback discovers it.
+    packetPath = join(packageJsonPath ? dirname(packageJsonPath) : resolve(cwd), "campaign-runtime.build.json");
+    if (existsSync(packetPath)) packet = readPinJson(packetPath, packetProblem);
+  }
+
+  const { projectSpec, projectManifest, projectKey } = resolveProjectPin(packageJsonPath, warnings);
+
+  let packetVersion = null;
+  let packetVersionIgnored = null;
+  if (packet && Object.hasOwn(packet, "campaigns_os_version")) {
+    const recorded = packet.campaigns_os_version;
+    if (typeof recorded === "string" && EXACT_VERSION_RE.test(recorded)) {
+      packetVersion = recorded;
+    } else {
+      // Kept verbatim (a non-string as its JSON text) so the Pin: line can say
+      // the field was there and ignored, not that it was absent.
+      packetVersionIgnored = typeof recorded === "string" ? recorded : JSON.stringify(recorded);
+      warnings.push(`Packet campaigns_os_version ignored: ${JSON.stringify(recorded)} in ${packetPath} is not an exact version.`);
+    }
+  } else if (existsSync(packetPath) && !packet) {
+    warnings.push(`Packet pin unavailable: ${packetPath} ${packetProblem.reason}.`);
+  }
+  return {
+    packageJsonPath,
+    projectSpec,
+    projectManifest,
+    projectKey,
+    packetPath: packet ? packetPath : null,
+    packetVersion,
+    packetVersionIgnored,
+    warnings,
+  };
+}
+
+/**
+ * Pure: the pin status from the two sources and the running version. The
+ * message names where each version it quotes was read: the key and manifest of
+ * the project pin, the packet file of the recorded version.
+ */
+export function evaluatePin({ projectSpec = null, projectManifest = null, projectKey = null, packetVersion = null, packetVersionIgnored = null, packetPath = null, running, force = false }) {
+  const projectVersion = exactPinVersion(projectSpec);
+  const range = projectSpec != null && !projectVersion ? projectSpec : null;
+  const source = projectVersion ? "project" : packetVersion ? "packet" : null;
+  const version = projectVersion || packetVersion || null;
+  const manifest = projectManifest || "package.json";
+  const projectFrom = `${projectKey || "devDependencies"} in ${manifest}`;
+  const packetFrom = `campaigns_os_version in ${packetPath || "the Build Packet"}`;
+  const noPacket = packetVersionIgnored != null
+    ? `campaigns_os_version ${JSON.stringify(packetVersionIgnored)} in ${packetPath || "the Build Packet"} is not a bare x.y.z version and was ignored`
+    : packetPath ? `no campaigns_os_version in ${packetPath}` : "no packet version";
+  let status;
+  let message;
+  if (projectVersion && packetVersion && projectVersion !== packetVersion) {
+    status = "conflicting_pin";
+    message = `conflicting_pin — project pins ${projectVersion} (${projectFrom}), packet records ${packetVersion} (${packetFrom})`;
+  } else if (!version) {
+    status = "unpinned";
+    const project = range != null
+      ? `project range ${range || '""'} (${projectFrom}) is not an exact version`
+      : projectManifest ? `no project pin in ${projectManifest}` : "no package.json found";
+    message = `unpinned (${project}; ${noPacket})`;
+  } else if (version !== running) {
+    status = "stale_pin";
+    message = `stale_pin — ${source === "project" ? `project pins ${version} (${projectFrom})` : `packet records ${version} (${packetFrom})`}, running ${running}`;
+  } else {
+    status = "match";
+    message = `match (${version} — ${source === "project" ? projectFrom : packetFrom})`;
+  }
+  const forced = force && PIN_BLOCKING_STATUSES.has(status);
+  return {
+    source,
+    version,
+    running,
+    status,
+    range,
+    packet_version: packetVersion,
+    packet_version_ignored: packetVersionIgnored,
+    project_version: projectVersion,
+    project_manifest: projectManifest,
+    project_key: projectKey,
+    forced,
+    message: forced ? `${message} (overridden by --force)` : message,
+  };
+}
+
+// Each line names the manifest and key the pin (or range) was read from; with
+// neither, the nearest manifest and devDependencies, where the ADR puts a pin.
+function pinAction(pin, sources) {
+  const manifest = pin.project_manifest || "the project's package.json";
+  const key = pin.project_key || "devDependencies";
+  const packet = sources.packetPath || "the Build Packet";
+  if (pin.status === "conflicting_pin") {
+    return `Align the project pin: set ${key}["${PIN_PACKAGE_NAME}"] in ${manifest} to ${pin.packet_version}, or re-run prepare-build with ${pin.project_version} so ${packet} records it. Pass --force to proceed anyway (recorded).`;
+  }
+  if (pin.source === "project") {
+    return `Run the pinned executable (${LOCAL_INVOCATION_PREFIX} from the project), or move the pin: set ${key}["${PIN_PACKAGE_NAME}"] in ${manifest} to ${pin.running} and reinstall. Pass --force to proceed anyway (recorded).`;
+  }
+  const pinStep = pin.project_key
+    ? `set ${key}["${PIN_PACKAGE_NAME}"] in ${manifest} to ${pin.running} (it holds the range ${JSON.stringify(pin.range)})`
+    : `add "${PIN_PACKAGE_NAME}": "${pin.running}" to ${key} in ${manifest}`;
+  return `Run the version ${packet} records (${pin.packet_version}), or pin the project: ${pinStep}; the next prepare-build re-stamps ${packet}. Pass --force to proceed anyway (recorded).`;
+}
+
+export function pinTextLines(result) {
+  return result?.pin ? [`Pin: ${result.pin.message}`] : [];
+}
+
 function toolingCommand(args) {
   const action = args._[1] || "status";
-  if (action !== "status") throw new Error(`Unknown tooling command: ${action}`);
-  if (args.target === true) throw new Error("Missing value for --target");
-  if (args.platform === true) throw new Error("Missing value for --platform");
+  if (action !== "status") throw refused(`Unknown tooling command: ${action}`);
+  if (args.target === true) throw refused("Missing value for --target");
+  if (args.platform === true) throw refused("Missing value for --platform");
+  if (args["skills-revision"] === true) {
+    // The example is the bundle this CLI ships, read from skills.json, so the
+    // refusal never teaches a revision that has since moved.
+    const shipped = readJson(join(ROOT, "skills.json")).bundle_revision;
+    throw refused(`Missing value for --skills-revision. Pass the bundle revision the skill you loaded states on its first body line (for example --skills-revision ${shipped}), or that skill's <skill-id>@<version>.`);
+  }
+  // Bare, like --dry-run: the shared parser would read `--force true` as a
+  // value, and an override must never hinge on how a token happened to parse.
+  if (Object.hasOwn(args, "force") && args.force !== true) {
+    throw refused(`--force takes no value (got ${JSON.stringify(args.force)}); write \`--force\` on its own.`);
+  }
+  // The parser keeps `--no-force` as its own key, so without this it would
+  // run as if unsaid and the operator would never learn it did nothing.
+  if (Object.hasOwn(args, "no-force")) {
+    throw refused("--no-force is not a flag of tooling status; --force is bare and off by default");
+  }
+  if (args.packet === true) throw refused("Missing value for --packet");
+  const pinSources = resolvePinSources(args);
 
   const pkg = readJson(join(ROOT, "package.json"));
-  const skillStatus = installSkills(args.target, true, args.platform || "all");
+  // An explicit --target or --platform (`all` included) is checked as asked.
+  // Without either, only the platform directories that already hold a
+  // Campaigns OS skill are held to this bundle: the documented install is one
+  // platform, and reading the other two as stale told that operator to install
+  // everywhere and exit 2 on a correct setup.
+  const explicitSkillScope = isNonEmptyString(args.target) || isNonEmptyString(args.platform);
+  const allSkillStatus = installSkills(args.target, true, args.platform || "all");
+  const skillScope = explicitSkillScope
+    ? { status: allSkillStatus, scope: "requested", notInstalled: [] }
+    : scopeSkillStatusToInstalledPlatforms(allSkillStatus);
+  const skillStatus = skillScope.status;
   const skillActions = classifyToolingSkillActions(skillStatus.skills || []);
   const staleSkills = skillActions.actionable;
   const install = localInstallStatus(ROOT, pkg);
@@ -10950,9 +11601,30 @@ function toolingCommand(args) {
     warnings.push(`No pinned commit could be derived for this ${install.mode_label}; the package version is ${pkg.version || "unknown"}. Compare it against the commit you oriented on before relying on it.`);
   }
 
-  if (staleSkills.length) {
-    const skillArgs = args.target ? ["--target", args.target] : ["--platform", args.platform || "all"];
-    actions.push(`Refresh installed skills: ${cli.invocation_prefix} install-skills ${skillArgs.join(" ")}. Restart local agent sessions afterwards.`);
+  if (skillScope.scope === "installed_platforms" && skillScope.notInstalled.length) {
+    const checked = skillStatus.targets.map((target) => target.platform_label).join(", ");
+    const skipped = skillScope.notInstalled.map((target) => target.platform_label);
+    ready.push(`Skills checked for ${checked}; ${skipped.join(", ")} ${skipped.length === 1 ? "has" : "have"} no Campaigns OS skills installed and ${skipped.length === 1 ? "was" : "were"} not checked (pass --platform to check one).`);
+  }
+
+  if (skillScope.scope === "no_platform_installed") {
+    // Nothing to refresh: the documented install is one platform, the
+    // harness in use, so name the choice rather than installing everywhere.
+    // The command ends its own sentence and is runnable as printed (Claude
+    // Code, the documented install). The other platforms follow in a separate
+    // sentence of prose: no `<a|b>` template or parenthesis a shell would read
+    // as a redirect or a subshell if the command were copied with it.
+    actions.push(`Install bundled skills for the harness you use: ${cli.invocation_prefix} install-skills --platform claude. Use --platform codex for Codex, or --platform agents for shared agent skills such as Cursor's. Restart local agent sessions afterwards.`);
+  } else if (staleSkills.length) {
+    const stalePlatforms = SKILL_PLATFORMS.map((platform) => platform.id)
+      .filter((id) => staleSkills.some((skill) => skill.platform === id));
+    const invocations = args.target
+      ? [["--target", args.target]]
+      : skillScope.scope === "installed_platforms" && stalePlatforms.length < SKILL_PLATFORMS.length
+        ? stalePlatforms.map((platform) => ["--platform", platform])
+        : [["--platform", args.platform || "all"]];
+    const commands = invocations.map((skillArgs) => `${cli.invocation_prefix} install-skills ${skillArgs.join(" ")}`);
+    actions.push(`Refresh installed skills: ${commands.join(" and ")}. Restart local agent sessions afterwards.`);
   }
 
   if (install.mode === "checkout" && cli.global_binary.status === "not_found") {
@@ -10960,8 +11632,8 @@ function toolingCommand(args) {
   } else if (install.mode === "node_modules" && cli.global_binary.status !== "found") {
     // A consumer install runs through npm's bin resolution; no PATH ritual.
     warnings.push(cli.global_binary.status === "found_other_install"
-      ? `The campaigns-os on PATH (${cli.global_binary.path}) is a different install from the one inspected here (${install.location}); run commands as \`npx campaigns-os <command>\` from the folder that pins this toolkit so this copy runs.`
-      : `campaigns-os is not on PATH; run commands as \`npx campaigns-os <command>\` from the folder that pins this toolkit (npm resolves node_modules/.bin), or call node ${cli.local_bin} directly.`);
+      ? `The campaigns-os on PATH (${cli.global_binary.path}) is a different install from the one inspected here (${install.location}); run commands as \`${LOCAL_INVOCATION_PREFIX} <command>\` from the folder that pins this toolkit so this copy runs.`
+      : `campaigns-os is not on PATH; run commands as \`${LOCAL_INVOCATION_PREFIX} <command>\` from the folder that pins this toolkit (npm resolves node_modules/.bin), or call node ${cli.local_bin} directly.`);
   } else if (install.mode !== "checkout" && install.mode !== "npx_cache" && cli.global_binary.status === "not_found") {
     warnings.push(`campaigns-os is not on PATH; call node ${cli.local_bin} directly.`);
   } else if (install.mode !== "checkout" && cli.global_binary.status === "found_other_install") {
@@ -10980,11 +11652,43 @@ function toolingCommand(args) {
     warnings.push("This checkout has uncommitted changes; verify they are intentional before publishing or comparing freshness.");
   }
 
+  // The manifest THIS CLI ships, read from its own package root — never from the
+  // working directory, which may be a campaign repo with no skills.json at all.
+  const skillsRevision = evaluateSkillsRevision(args["skills-revision"], readJsonIfExists(join(ROOT, "skills.json")) || {});
+  if (skillsRevision.status === "mismatch") {
+    actions.push(`Start a fresh session: the skills text you are reading is ${skillsRevision.requested}, and this CLI ships ${skillsRevision.on_disk || "an unknown bundle revision"}. Re-running this command cannot refresh skill text already in context.`);
+  }
+
+  // The CLI's own package.json is the running version: the executable this
+  // command is, not whichever one the project would have resolved.
+  const pin = evaluatePin({
+    projectSpec: pinSources.projectSpec,
+    projectManifest: pinSources.projectManifest,
+    projectKey: pinSources.projectKey,
+    packetVersion: pinSources.packetVersion,
+    packetVersionIgnored: pinSources.packetVersionIgnored,
+    packetPath: pinSources.packetPath,
+    running: pkg.version,
+    force: args.force === true,
+  });
+  warnings.push(...pinSources.warnings);
+  const pinBlocks = PIN_BLOCKING_STATUSES.has(pin.status) && !pin.forced;
+  if (PIN_BLOCKING_STATUSES.has(pin.status)) {
+    (pin.forced ? warnings : actions).push(pin.forced
+      ? `Pin ${pin.status} overridden by --force; this run proceeds on ${pin.running}.`
+      : pinAction(pin, pinSources));
+  }
+
   const gitBlocks = git.status === "ok" && Number.isFinite(git.behind) && git.behind > 0;
-  const ok = !gitBlocks && staleSkills.length === 0;
+  const ok = !gitBlocks && staleSkills.length === 0 && skillsRevision.status !== "mismatch" && !pinBlocks;
   return {
     ok,
     status: ok ? "ready" : "attention_required",
+    // A bare status string, so a consumer can branch on it without reaching into
+    // an object; the detail sits beside it under skills_revision.
+    revision_check: skillsRevision.status,
+    skills_revision: skillsRevision,
+    pin,
     install,
     package: packageStatus,
     git,
@@ -10992,6 +11696,12 @@ function toolingCommand(args) {
     skills: {
       ok: staleSkills.length === 0,
       stale_count: staleSkills.length,
+      // requested: --target/--platform named the scope. installed_platforms:
+      // only platforms with Campaigns OS skills installed were checked, and
+      // not_installed_platforms lists the rest. no_platform_installed: none
+      // had any, so every platform is listed there and was checked.
+      scope: skillScope.scope,
+      not_installed_platforms: skillScope.notInstalled,
       status: skillStatus,
     },
     ready,
@@ -11000,21 +11710,37 @@ function toolingCommand(args) {
   };
 }
 
+export async function toolingStatusCommand(args, options = {}) {
+  const result = toolingCommand(args);
+  const { gatewayLoginStatus } = await import("./admin-transport.mjs");
+  result.gateway_login = await gatewayLoginStatus(options);
+  const auth = result.gateway_login;
+  if (!auth.accounts.length) result.warnings.push(auth.state === "unavailable"
+    ? "Gateway credential storage is unavailable or busy. Check user credential directory permissions and keychain access; wait for another campaigns-os process to finish. See docs/gateway-login.md for interrupted-process recovery."
+    : `Gateway login: ${auth.state}. Use ${result.cli.invocation_prefix} login --store <subdomain>.`);
+  for (const account of auth.accounts) (account.state === "logged_in" ? result.ready : result.warnings).push(`Gateway login: ${account.state}; store ${account.store}; access remaining ${account.remaining_seconds}s; gateway ${auth.gateway}; reported version ${account.gateway_version || "unavailable"} (local credential metadata only).`);
+  return result;
+}
+
 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.
+  // An unnamed platform is not forwarded, so status checks only the platforms
+  // that hold Campaigns OS skills, as it does when run directly.
   try {
-    tooling = runTooling({ _: ["tooling", "status"], platform, ...(typeof args.target === "string" ? { target: args.target } : {}) });
+    tooling = runTooling({ _: ["tooling", "status"], ...(args.platform ? { platform: args.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; }
   }
+  // `installed` only when status actually narrowed to installed platforms; an
+  // unnamed platform that checked every one (nothing installed) stays `all`.
+  const platform = args.platform || (tooling?.skills?.scope === "installed_platforms" ? "installed" : "all");
   return diagnosticExport({ tooling, doctor, platform, inspectionFailed });
 }
 
@@ -11495,7 +12221,7 @@ async function findingsCommand(args, ambient = null) {
   if (sub === "harvest") return findingsHarvest(args, ambient);
   if (sub === "list") return findingsList(args, ambient);
   if (sub === "export") return findingsExport(args, ambient);
-  throw new Error(`Unknown findings subcommand "${sub}". Use: add | harvest | list | export.`);
+  throw refused(`Unknown findings subcommand "${sub}". Use: add | harvest | list | export.`);
 }
 
 function resolveFindingsJournalPath(args, ambient = null) {
@@ -11539,7 +12265,7 @@ async function findingsAdd(args, ambient = null) {
       summary = answers.summary;
       details = answers.details;
     } else {
-      throw new Error(
+      throw refused(
         `findings add is missing required flags: ${missing.join(", ")}. `
           + `Provide them as flags (flags-first for agents/CI), e.g. `
           + `--stage ${FINDING_STAGES[0]} --kind ${FINDING_KINDS[0]} --summary "..."`,
@@ -11773,7 +12499,7 @@ export async function runSessionCommand(args, ambient = null, sessionHolder = nu
   if (sub === "start") return runSessionStart(args);
   if (sub === "status") return runSessionStatus(args, ambient);
   if (sub === "end") return runSessionEnd(args, ambient, sessionHolder);
-  throw new Error(`Unknown run subcommand "${sub}". Use: start | end | status.`);
+  throw refused(`Unknown run subcommand "${sub}". Use: start | end | status.`);
 }
 
 function writeRunSessionResult(result, args, exitCode) {
@@ -11957,6 +12683,12 @@ function runSessionProgress(found) {
 }
 
 async function runSessionEnd(args, ambient = null, sessionHolder = null) {
+  // The closer reads a session, but its own argv refusals still belong to the
+  // invoking command. Check them before entering closeRunSession's nested scope.
+  if (Object.hasOwn(args, "new-run") || Object.hasOwn(args, "run-id")) {
+    throw refused("run end uses the saved session's run ID; --new-run and --run-id are not accepted.");
+  }
+  validateRunRecordArgv(args);
   // Use the session resolved once in main() (single source of truth).
   const found = ambient;
   if (!found) {
@@ -11987,10 +12719,18 @@ async function runSessionEnd(args, ambient = null, sessionHolder = null) {
 // `qa run`'s --base-url, --browser or --test-order say nothing about the
 // record — and run-record stamps the flag NAMES it was given into the Run
 // Record's argv_shape, so carrying them over would file them as run-record's.
-const RUN_RECORD_INHERITABLE_FLAGS = Object.freeze([
+// `dry-run` is on the list for `run end --dry-run`, the one closer whose
+// invoking command implements the flag; a closer invoked by a command that
+// does not (the QA auto-end) drops it from extraArgs before calling — see
+// DRY_RUN_COMMANDS and autoEndRunSessionAfterTerminalQa.
+export const RUN_RECORD_INHERITABLE_FLAGS = Object.freeze([
   "context", "report", "qa-verdict", "journal", "surfaces", "primary-surface", "surface-confidence",
   "agent-input-tokens", "agent-output-tokens", "agent-tool-output-tokens", "agent-total-tokens", "agent-elapsed-ms", "agent-model", "agent-usage-source",
-  "no-remit", "no-write", "proxy-base", "json",
+  "no-remit", "no-write", "proxy-base", "dry-run", "json",
+]);
+const RUN_RECORD_BOOLEAN_INHERITABLE_FLAGS = new Set(["no-remit", "no-write", "dry-run", "json"]);
+const RUN_RECORD_INTEGER_INHERITABLE_FLAGS = new Set([
+  "agent-input-tokens", "agent-output-tokens", "agent-tool-output-tokens", "agent-total-tokens", "agent-elapsed-ms",
 ]);
 
 // The run-record argv that closes `session`: its run_id and journal, the
@@ -12018,12 +12758,23 @@ export function runSessionEndArgs(session, packet, extraArgs = {}) {
 async function closeRunSession(found, { packet, extraArgs = {}, silent = false, promptForConsent = true, onError = null } = {}) {
   const endArgs = runSessionEndArgs(found.session, packet, extraArgs);
   try {
-    const summary = await runRecordCommand(endArgs, found, { silent, promptForConsent });
-    clearRunSession(found.path);
+    // No internal closeout currently constructs a refusal before its invoking
+    // command journals: the sweep forwards only remit controls tolerated by
+    // run-record, run end validates its own argv first, and QA auto-end runs
+    // after QA persistence. Keep the scope at this boundary so a future
+    // closeout refusal swallowed by onError cannot mark the outer invocation.
+    const summary = await runWithRefusalScope(() => runRecordCommand(endArgs, found, { silent, promptForConsent }));
+    // Clearing the session is a write like any other, so a closer carrying
+    // --dry-run leaves it open: the operator sees the record the close would
+    // assemble and can still close for real afterwards.
+    if (endArgs["dry-run"] !== true) clearRunSession(found.path);
     return summary;
   } catch (error) {
-    if (!onError) throw error;
-    onError(error);
+    // A nested run-record refusal is a failure of the invoking closer, which
+    // has already read session state. Do not pass its tag to outer persistence.
+    const failure = error?.code === REFUSED_INVOCATION ? new Error(error.message, { cause: error }) : error;
+    if (!onError) throw failure;
+    onError(failure);
     return null;
   }
 }
@@ -12041,11 +12792,34 @@ async function closeRunSession(found, { packet, extraArgs = {}, silent = false,
 // forms. `run status` never sweeps — it is read-only.
 // Best-effort throughout: a closeout failure clears the file and says so on
 // stderr; it never blocks the command that triggered it.
+//
+// The sweep is an effect of the command that triggers it, and it runs BEFORE
+// dispatch — so it happens even when the argv that follows is refused. That is
+// deliberate (the stale session at the target is closed out either way), but it
+// makes the sweep the one place where `--no-write` could still write: it
+// assembles a Run Record and removes the session file. `--no-write` writes
+// nothing, the closeout included; see the guard below.
 const STALE_SWEEP_TARGET_COMMANDS = new Set(["start", "prepare-build", "build"]);
 
 async function closeOutStaleRunSessions(command, args) {
   // A command that opted out of sessions altogether must not sweep either.
   if (args["no-run-session"] === true) return [];
+  // --no-write leaves the tree byte-identical. Inheriting the flag into the
+  // closeout was not enough: it suppressed the Run Record but clearRunSession
+  // still deleted the session file, so `--no-write` moved bytes. Skip the
+  // sweep entirely instead — the stale session stays for the next run that
+  // does write.
+  if (args["no-write"] === true) return [];
+  // Nor may a dry run sweep. The closeout writes a Run Record, deletes the
+  // session file and (under consent) sends a remit — every effect --dry-run
+  // promises not to have. The sweep runs BEFORE dispatch, so it was doing all
+  // three for commands that implement the flag: `run end --dry-run --json`
+  // over an aged session exited 0, wrote a record, POSTed once and removed the
+  // session. --dry-run means "show me, do nothing"; the stale session simply
+  // stays stale until a real invocation closes it. Gated on the same predicate
+  // persistLifecycleIfRequested uses, so a stray --dry-run on a command that
+  // does not implement it changes nothing here either.
+  if (args["dry-run"] === true && commandImplementsDryRun(command, args)) return [];
   const roots = [];
   if (STALE_SWEEP_TARGET_COMMANDS.has(command) && optionalString(args.target)) roots.push(resolve(args.target));
   if (command === "run" && (args._[1] === "start" || args._[1] === "end")) {
@@ -12062,8 +12836,11 @@ async function closeOutStaleRunSessions(command, args) {
     }
   }
   // The closeout inherits the invoking command's remit controls: an explicit
-  // --no-remit / --no-write stays an opt-out, and a run pointed at a custom
-  // --proxy-base never remits the stale record to the canonical endpoint.
+  // --no-remit stays an opt-out, and a run pointed at a custom --proxy-base
+  // never remits the stale record to the canonical endpoint. --no-write is
+  // carried too, though the guard above means it never arrives true: if the
+  // sweep ever becomes conditional rather than skipped, the closeout must
+  // still see it.
   const inherited = {};
   for (const flag of ["no-remit", "no-write", "proxy-base"]) {
     if (args[flag] !== undefined) inherited[flag] = args[flag];
@@ -12207,6 +12984,14 @@ export function describeCampaignKeyRejection(rejected) {
 // docs/workflow-findings-sidecar.md.
 async function runRecordCommand(args, ambient = null, { silent = false, promptForConsent = true } = {}) {
   const packetPath = resolve(requireArg(args, "packet"));
+  if (args["new-run"] === true && optionalString(args["run-id"])) {
+    throw refused("run-record: --new-run and --run-id are exclusive; --run-id names the run to re-emit, --new-run mints a fresh one.");
+  }
+  const agentUsage = refusing(() => parseAgentUsageArgs(args));
+  // --dry-run assembles the record and shows it, then writes and sends
+  // nothing. It differs from --no-write, which skips the assembly's reads
+  // as well; combining the two is allowed and still writes nothing.
+  const dryRun = isDryRun(args);
   const parsedSurfaces = parseRunRecordSurfaces(args.surfaces);
   const packet = readJson(packetPath);
   const explicitTargetRepo = resolveFromFile(packetPath, packet.assembly?.target_repo);
@@ -12230,10 +13015,12 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     : inferQaVerdictPath({ packet, report, reportPath: reportExists ? reportPath : null, targetRepo, baseDir });
   const qaVerdictExists = qaVerdictPath != null && existsSync(qaVerdictPath);
   const qaVerdict = qaVerdictExists ? readJson(qaVerdictPath) : null;
+  if (qaVerdict && (packet.spec?.local_spec_id != null || qaVerdict.local_spec_id != null) && !qaVerdictIdentityMatch(qaVerdict, packet)) {
+    throw new Error("run-record: QA verdict does not match this packet's local_spec_id; foreign evidence cannot be recorded as this local campaign.");
+  }
 
   const journalPath = resolveJournalPath(args);
   const journal = readJournal(journalPath);
-  const agentUsage = parseAgentUsageArgs(args);
 
   // run_id: explicit flag > --new-run (mint) > active run session > the most
   // recent Run Record on disk for this packet's campaign > freshly minted.
@@ -12246,9 +13033,6 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
   // record for this campaign exists, or when --new-run asks for it. The
   // source travels on the stdout envelope only: the record's schema is
   // hashed surface and does not carry it.
-  if (args["new-run"] === true && optionalString(args["run-id"])) {
-    throw new Error("run-record: --new-run and --run-id are exclusive; --run-id names the run to re-emit, --new-run mints a fresh one.");
-  }
   const listOnly = args.list === true;
   // The directory is scanned only when something reads it: --list, or an id
   // that nothing else names. An explicit --run-id, --new-run or an open
@@ -12307,6 +13091,7 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
       run_id_source: runIdSource,
       records,
       remit: { result: null, http_status: null, base_kind: null, sent: false, preserved: false },
+      ...(dryRun ? { dry_run: true, would_write: null, would_remit: null } : {}),
     };
     if (silent) return summary;
     if (args.json) {
@@ -12373,7 +13158,11 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
   }
   if (existsSync(journalPath)) artifacts.push(runRecordArtifactRef("findings_journal", journalPath, WORKFLOW_FINDING_SCHEMA, baseDir));
 
-  const write = args["no-write"] !== true;
+  // What a real run of this command line would write, and what this one does:
+  // a dry run assembles and validates the record a real run would write
+  // (assertRunRecordValid), and stops at the write itself (writeRunRecord).
+  const wouldWrite = args["no-write"] !== true;
+  const write = wouldWrite && !dryRun;
   // The verdict publish outcome this record carries: the session's attempt
   // for the verdict being recorded (the auto-end and `run end` both close
   // through here with the session still ambient), else the newest attempt
@@ -12388,8 +13177,10 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
   // refuses a second send, so a record it already has is final: it is neither
   // re-sent nor rewritten here. A prior send that did not land (failed,
   // pending) is retried when this run may send, and kept as it stands when it
-  // may not. A dry run reads nothing: it writes and sends nothing.
-  const prior = write ? readPriorRunRecord(runId, baseDir) : null;
+  // may not. A pure --no-write run reads nothing: it writes and sends nothing.
+  // A --dry-run does read it, because what a real run would do here is the
+  // very thing the dry run is being asked to report.
+  const prior = write || dryRun ? readPriorRunRecord(runId, baseDir) : null;
   const priorRemit = priorRemitOutcome(prior?.record);
   const storedRemotely = priorRemit?.state === "ok";
   // A pure local-inspection run (--no-write), an explicit --no-remit, or a
@@ -12410,6 +13201,16 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     announceDefaultOnTelemetry(consent.scope || proxyBase);
   }
 
+  // Under --dry-run the remit is disabled by construction (write is false), so
+  // `remitDisabled` cannot say whether a real run would have sent. This does:
+  // the same three stoppers minus the dry run itself, against the consent this
+  // machine actually resolved.
+  const wouldRemit = dryRun
+    && args["no-remit"] !== true
+    && args["no-write"] !== true
+    && !storedRemotely
+    && consent.state === "on";
+
   // A publish the record already says landed is never downgraded by a
   // reassembly: the prior ok block wins over a session attempt that did not
   // land, mirroring the remit carry-forward below.
@@ -12428,6 +13229,7 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     consent: { state: consent.state, source: consent.source },
     identity: {
       map_id: optionalString(packet.spec?.map_id),
+      ...localSpecIdentityFields(packet.spec),
       campaign_slug: optionalString(packet.campaign?.public_route_slug),
       template_family: optionalString(packet.assembly?.template_family),
       entry_point_shape: "packet",
@@ -12446,9 +13248,6 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     agentUsage,
   });
 
-  // Write before any network call so local capture does not depend on telemetry
-  // being fast or reachable. If a crash lands before the final rewrite below,
-  // the durable record is explicitly pending instead of silently skipped.
   const shouldAttemptRemit = !remitDisabled && consent.state === "on";
   const remitBaseKind = describeRemitBaseKind(proxyBase);
 
@@ -12467,6 +13266,9 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
       record: prior.record,
       run_id_source: runIdSource,
       remit: { result: REMIT_RESULTS.not_contacted, http_status: null, base_kind: null, sent: false, preserved: true },
+      // A record the receiver already holds is final: a real run of this same
+      // command line would write nothing and send nothing either.
+      ...(dryRun ? { dry_run: true, would_write: null, would_remit: null } : {}),
     };
     if (silent) return summary;
     if (args.json) {
@@ -12504,7 +13306,11 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     record.remit_base_kind = carriedForward.base_kind;
   }
 
-  const recordPath = write ? writeRunRecord(record, { baseDir }) : null;
+  // The record is validated whenever a real run of this command line would
+  // write one — under --dry-run too — and always BEFORE the remit below, so an
+  // invalid record refuses ahead of any send on both paths. The write itself is
+  // separate and happens after the remit; validating here does not write.
+  if (wouldWrite) assertRunRecordValid(record);
 
   // Remit is consent-gated, non-fatal, bounded, and keyed on run_id — the
   // receiver holds one record per id and refuses a second POST for one it
@@ -12514,7 +13320,10 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
   // The key is only resolved when a send will actually be attempted: under
   // consent-off or --no-remit nothing goes out, so nothing is read and nothing
   // is said about a credential.
-  const keySource = shouldAttemptRemit ? resolveCampaignsApiKeySource(packet, packetPath, process.env) : { key: null, rejected: null };
+  // A dry run resolves it too, and only when a real run would have: the
+  // destination gate below names the credential that would travel, and the
+  // preview must name the one the real send would.
+  const keySource = shouldAttemptRemit || wouldRemit ? resolveCampaignsApiKeySource(packet, packetPath, process.env) : { key: null, rejected: null };
   const campaignKey = keySource.key;
   // A refused key is not a missing key. Say so on stderr, naming the source
   // and not the value, so the operator fixes the credential instead of reading
@@ -12524,7 +13333,30 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
   // send's outcome, which is only known below; the credential itself never
   // leaves the machine.
   const keyRejection = describeCampaignKeyRejection(keySource.rejected);
-  if (keyRejection) process.stderr.write(`[campaigns-os] run-record: ${keyRejection} This run's remit is attempted without a tenant scope.\n`);
+  if (keyRejection) process.stderr.write(`[campaigns-os] run-record: ${keyRejection} ${dryRun ? "A real run's remit would be attempted without a tenant scope." : "This run's remit is attempted without a tenant scope."}\n`);
+
+  // The transport's own preconditions, run for a dry run as well: `remit`
+  // demands a fetch to send with, and refuses a base that is not https (nor a
+  // loopback host), BEFORE it opens a socket — so a send the real run could
+  // never have made must not be previewed as one it would post. Same
+  // functions, in the transport's order, with the same label and the same
+  // credential wording the remit below hands them. The remit rail is non-fatal
+  // by contract — the real run classifies either refusal as a failed remit and
+  // still exits 0 — so the dry run reports it on the envelope and exits 0 too.
+  let wouldRemitEndpoint = null;
+  let wouldRemitRefusal = null;
+  if (wouldRemit) {
+    try {
+      assertFetchAvailable(globalThis.fetch);
+      const { base } = assertSecureProxyBase(proxyBase, {
+        label: "Run Telemetry remit",
+        credential: typeof campaignKey === "string" && campaignKey.trim() ? "the campaign key" : null,
+      });
+      wouldRemitEndpoint = `${base}${DEFAULT_RUNS_ENDPOINT}`;
+    } catch (error) {
+      wouldRemitRefusal = String(error?.message ?? error);
+    }
+  }
   const remitStatus = shouldAttemptRemit
     ? await remitRunRecord(record, { proxyBase, consent, campaignKey })
     : { attempted: false, ok: null, error: null, endpoint: null, result: null, http_status: null };
@@ -12543,7 +13375,11 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     record.remit_base_kind = remitStatus.attempted ? remitBaseKind : null;
   }
 
-  if (write) writeRunRecord(record, { baseDir });
+  // The record's one and only write, after the remit so the file that lands
+  // carries this run's remit_* outcome rather than the placeholders it was
+  // assembled with. Validated above, ahead of the send; nothing is written
+  // under --dry-run or --no-write.
+  const recordPath = write ? writeRunRecord(record, { baseDir }) : null;
 
   const summary = {
     ok: true,
@@ -12569,6 +13405,13 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
       sent: remitStatus.attempted,
       preserved: Boolean(carriedForward),
     },
+    // What a real run of this same command line — the one without --dry-run —
+    // would have done: the record file it would write, and the endpoint it
+    // would POST to (null when --no-remit, --no-write or consent would have
+    // stopped the send anyway, and null with `would_remit_refused` set when the
+    // transport's destination gate refuses the base before any socket opens).
+    // Envelope only; never on the record.
+    ...(dryRun ? { dry_run: true, would_write: resolveRunRecordPath(runId, baseDir), would_remit: wouldRemitEndpoint, would_remit_refused: wouldRemitRefusal } : {}),
   };
   if (silent) return summary;
   if (args.json) {
@@ -12589,10 +13432,33 @@ async function runRecordCommand(args, ambient = null, { silent = false, promptFo
     console.log(`Remit: skipped (consent ${record.consent_state}${remitDisabled ? ", disabled for this run" : ""}).`);
   }
   if (write) console.log(`Wrote: ${recordPath}`);
-  else console.log("Dry run only (--no-write). No record written, no remit.");
+  else if (dryRun) {
+    console.log("Dry run (--dry-run). Nothing written, nothing sent.");
+    console.log(`Would write: ${summary.would_write}`);
+    console.log(`Would remit: ${summary.would_remit || (summary.would_remit_refused ? `nothing — the destination is refused before any request: ${summary.would_remit_refused}` : "nothing (remit is off for this run)")}`);
+  } else console.log("Dry run only (--no-write). No record written, no remit.");
   return summary;
 }
 
+/**
+ * The Run Record's refusal, lifted out of the write. `writeRunRecord` validates
+ * the record before it writes and refuses an invalid one; that refusal belongs
+ * to the command rather than to the write, because it has to fire on the dry
+ * path (which never writes) and ahead of the remit on the real one (which
+ * writes only afterwards). Both modes therefore refuse the same record with the
+ * same message and the same exit code, before any send: the check fires here,
+ * never on the identical one inside run-record.mjs (which stays as the writer's
+ * own last guard). The validator is that writer's — imported, not re-stated —
+ * so the two cannot disagree about what a valid record is. Writes nothing.
+ */
+function assertRunRecordValid(record) {
+  const validation = validateRunRecord(record);
+  if (!validation.ok) {
+    const detail = validation.errors.map((error) => `[${error.code}] ${error.message}`).join("; ");
+    throw new Error(`Run Record failed validation; refusing to write: ${detail}`);
+  }
+}
+
 // The record already written under `runId` for this target, or null when there
 // is none, it cannot be parsed, or it is not a valid Run Record. Only a record
 // `writeRunRecord` could have written is trusted as a prior — the same
@@ -12697,7 +13563,8 @@ function inferQaVerdictPath({ packet, report, reportPath = null, targetRepo = nu
     report,
     reportPath: reportPath || (targetRepo ? campaignSidecarPaths(targetRepo).reportPath : null),
     roots: [targetRepo, baseDir],
-  }).filter((candidate) => candidate.verdict && candidate.trusted);
+  }).filter((candidate) => candidate.verdict && candidate.trusted
+    && ((packet?.spec?.local_spec_id == null && candidate.verdict.local_spec_id == null) || candidate.identityMatch));
   eligible.sort((a, b) => {
     const scoreDelta = qaVerdictCandidateScore(b, packet) - qaVerdictCandidateScore(a, packet);
     if (scoreDelta !== 0) return scoreDelta;
@@ -12733,11 +13600,31 @@ function parseRunRecordSurfaces(value) {
   const surfaces = parseCommaList(value);
   const unknown = surfaces.filter((surface) => !RUN_RECORD_SURFACES.includes(surface));
   if (unknown.length) {
-    throw new Error(`Unknown --surfaces value(s): ${unknown.join(", ")}. Use one of: ${RUN_RECORD_SURFACES.join(", ")}.`);
+    throw refused(`Unknown --surfaces value(s): ${unknown.join(", ")}. Use one of: ${RUN_RECORD_SURFACES.join(", ")}.`);
   }
   return surfaces;
 }
 
+function validateRunRecordArgv(args) {
+  for (const flag of RUN_RECORD_INHERITABLE_FLAGS) {
+    // The integer flags are checked below by parseAgentUsageArgs, which keeps
+    // their non-negative-integer diagnostics for bare and blank values.
+    if (!RUN_RECORD_BOOLEAN_INHERITABLE_FLAGS.has(flag) && !RUN_RECORD_INTEGER_INHERITABLE_FLAGS.has(flag) && Object.hasOwn(args, flag)) requireArg(args, flag);
+  }
+  if (Object.hasOwn(args, "run-id")) requireArg(args, "run-id");
+  if (Object.hasOwn(args, "new-run") && args["new-run"] !== true) {
+    throw refused("--new-run takes no value.");
+  }
+  if (args["new-run"] === true && optionalString(args["run-id"])) {
+    throw refused("run-record: --new-run and --run-id are exclusive; --run-id names the run to re-emit, --new-run mints a fresh one.");
+  }
+  return {
+    agentUsage: refusing(() => parseAgentUsageArgs(args)),
+    dryRun: isDryRun(args),
+    parsedSurfaces: parseRunRecordSurfaces(args.surfaces),
+  };
+}
+
 function parseAgentUsageArgs(args) {
   const fields = {
     "agent-input-tokens": "input_tokens",
@@ -12823,6 +13710,21 @@ function toolkitProvenance({ silent = false } = {}) {
 // canonical endpoint, or against --proxy-base when given, so it reports what
 // a remit to that endpoint would do. `off` takes no --proxy-base: an OFF
 // choice is machine-wide and the record it writes carries no scope.
+// `assertSecureProxyBase` is SHARED with the remit rail, where it runs in the
+// middle of a handler: `remit()` reaches it after the Run Record has been built
+// and written, and `spec derive --write-map` after the derive produced one. A
+// throw from those positions is a handler failure — the most valuable lifecycle
+// entry there is — so the refusal tag cannot live inside the validator.
+//
+// The call sites below are the up-front ones: the base comes straight off argv
+// and is checked before any configuration read or write, before a credential is
+// attached, and before a request. The tag therefore goes HERE, where the
+// position is known — `refusing()` is the shared form of that contract. The
+// message and the exit code stay the validator's own; only the verdict the
+// lifecycle journal reads is added.
+const refuseInsecureProxyBase = (proxyBase, options) =>
+  refusing(() => assertSecureProxyBase(proxyBase, options));
+
 async function telemetryCommand(args) {
   const sub = args._[1] || "status";
   const configPath = resolveConfigPath();
@@ -12831,17 +13733,17 @@ async function telemetryCommand(args) {
   // empty variable) is not "no flag": treating it as absent would grant or
   // check the canonical endpoint under a request that named something else.
   if (Object.hasOwn(args, "proxy-base") && !requestedBase) {
-    throw new Error(`telemetry ${sub}: --proxy-base needs a URL (https, or a loopback host); nothing was written.`);
+    throw refused(`telemetry ${sub}: --proxy-base needs a URL (https, or a loopback host); nothing was written.`);
   }
   // Same transport rule as the remit rail: https, or a loopback host. A grant
   // for a base a remit would refuse to send to is not a grant, and a status
   // check against one would report on a remit that can never happen. Nothing
   // is sent here, so the in-clear warning is left to the remit.
-  const secureBase = () => assertSecureProxyBase(requestedBase, { label: `telemetry ${sub}`, warn: () => {} }).base;
+  const secureBase = () => refuseInsecureProxyBase(requestedBase, { label: `telemetry ${sub}`, warn: () => {} }).base;
 
   if (sub === "on" || sub === "off") {
     if (sub === "off" && requestedBase) {
-      throw new Error(`telemetry off: --proxy-base is not accepted; turning telemetry off applies to every endpoint. To grant one endpoint instead, run: ${scopedConsentCommand(requestedBase)}`);
+      throw refused(`telemetry off: --proxy-base is not accepted; turning telemetry off applies to every endpoint. To grant one endpoint instead, run: ${scopedConsentCommand(requestedBase)}`);
     }
     const proxyBase = requestedBase ? secureBase() : DEFAULT_PROXY_BASE;
     const { configPath: written, config } = writeConsentConfig(sub, { configPath, proxyBase, source: "telemetry-command" });
@@ -12917,7 +13819,7 @@ async function telemetryCommand(args) {
 
   if (sub === "list") return telemetryList(args);
 
-  throw new Error(`Unknown telemetry subcommand "${sub}". Use: status | on | off | list.`);
+  throw refused(`Unknown telemetry subcommand "${sub}". Use: status | on | off | list.`);
 }
 
 // `telemetry list` — the reader that never existed. Since the receiver
@@ -12932,14 +13834,16 @@ const TELEMETRY_LIST_TIMEOUT_MS = 15_000;
 
 const TELEMETRY_LIST_MAX_BODY_BYTES = 4_000_000; // the receiver caps a listing at 500 summaries
 
-async function telemetryList(args, { fetchImpl = globalThis.fetch } = {}) {
-  if (typeof fetchImpl !== "function") throw new Error("Global fetch is not available. Upgrade to Node 18+.");
+export async function telemetryList(args, { fetchImpl = globalThis.fetch } = {}) {
+  if (typeof fetchImpl !== "function") throw refused("Global fetch is not available. Upgrade to Node 18+.");
   // Same transport gate the remit rail uses: https, or a loopback host with a
-  // loud warning that the credential is in clear. Anything else throws here,
-  // before a credential is attached to a request. The gate's own normalized
-  // base is what the consent scope and the request URL below are built from,
-  // so one string decides both.
-  const { url: proxyUrl, base: proxyBase, loopback } = assertSecureProxyBase(
+  // loud warning that the credential is in clear. Anything else is refused
+  // here, before a credential is attached to a request and before the packet
+  // below is read — the same up-front position the gate holds under
+  // `telemetry status|on`, so it is tagged the same way. The gate's own
+  // normalized base is what the consent scope and the request URL below are
+  // built from, so one string decides both.
+  const { url: proxyUrl, base: proxyBase, loopback } = refuseInsecureProxyBase(
     optionalString(args["proxy-base"]) || DEFAULT_PROXY_BASE,
     { label: "telemetry list", credential: "the listing credential (the ops admin key, or the packet's campaign key)" },
   );
@@ -12951,9 +13855,11 @@ async function telemetryList(args, { fetchImpl = globalThis.fetch } = {}) {
     const { key, rejected } = resolveCampaignsApiKeySource(packet, packetPath, process.env);
     const rejection = describeCampaignKeyRejection(rejected);
     // Fail fast, before a request: a refused credential names its source so
-    // the operator can fix it, and nothing is sent in the meantime.
-    if (rejection) throw new Error(`telemetry list --packet: ${rejection}`);
-    if (!key) throw new Error(`telemetry list --packet: no Campaigns API key found in ${packetPath}, its local CampaignSpec, or the declared env source; pass a packet that carries one, or list cross-tenant with the admin key instead.`);
+    // the operator can fix it, and nothing is sent in the meantime. Every
+    // refusal ahead of the request is tagged, so the lifecycle journal records
+    // nothing for it — the same rule as a flag refused up front.
+    if (rejection) throw refused(`telemetry list --packet: ${rejection}`);
+    if (!key) throw refused(`telemetry list --packet: no Campaigns API key found in ${packetPath}, its local CampaignSpec, or the declared env source; pass a packet that carries one, or list cross-tenant with the admin key instead.`);
     headers["X-Campaign-Key"] = key;
     scope = "tenant";
   } else {
@@ -12963,11 +13869,12 @@ async function telemetryList(args, { fetchImpl = globalThis.fetch } = {}) {
     // posture remit takes with default-on consent.
     const canonical = normalizeConsentScope(proxyBase) === CANONICAL_REMIT_SCOPE;
     if (!canonical && !loopback && args["trust-proxy-base"] !== true) {
-      throw new Error(`telemetry list: refusing to send the ops admin key to non-canonical ${proxyUrl.origin}. Pass --trust-proxy-base if that endpoint is yours, or use --packet for a tenant-scoped listing.`);
+      throw refused(`telemetry list: refusing to send the ops admin key to non-canonical ${proxyUrl.origin}. Pass --trust-proxy-base if that endpoint is yours, or use --packet for a tenant-scoped listing.`);
     }
     const envName = optionalString(args["admin-key-env"]) || DEFAULT_ADMIN_KEY_ENV;
     const adminKey = process.env[envName];
-    if (!isNonEmptyString(adminKey)) throw new Error(`telemetry list: set ${envName} (the ops admin key) for the cross-tenant listing, or pass --packet <campaign-runtime.build.json> for a tenant-scoped one.`);
+    if (!isNonEmptyString(adminKey)) throw refused(`telemetry list: set ${envName} (the ops admin key) for the cross-tenant listing, or pass --packet <campaign-runtime.build.json> for a tenant-scoped one.`);
+    console.warn("Warning: CAMPAIGN_OPS_ADMIN_KEY (or the selected admin-key env) is a break-glass /api/runs listing credential. Use campaigns-os login for supported store-profile reads; login does not grant cross-tenant run listing.");
     headers["X-Campaigns-Ops-Admin-Key"] = adminKey.trim();
     scope = "admin";
   }
@@ -13291,7 +14198,8 @@ export function resultTextLines(result, { headerLines = [] } = {}) {
   // A waive command's second line names what it recorded; the third is the
   // stage doctor now picks for the report the waiver was written to.
   if (WAIVE_ACTIONS.has(result.action) && result.gate) {
-    lines.push(`Waived: ${result.gate} by ${result.waiver?.waived_by || "(unattributed)"}${result.waiver?.expires_at ? ` until ${result.waiver.expires_at}` : ""}`);
+    lines.push(`${result.dry_run ? "Would waive" : "Waived"}: ${result.gate} by ${result.waiver?.waived_by || "(unattributed)"}${result.waiver?.expires_at ? ` until ${result.waiver.expires_at}` : ""}`);
+    if (result.dry_run) lines.push(`Would write: ${result.would_write} (nothing was written)`);
     if (result.next_stage) lines.push(`Next stage: ${result.next_stage}${result.next_stage_reason ? ` (${result.next_stage_reason})` : ""}`);
   }
   if (result.targets?.length) {
@@ -13386,13 +14294,13 @@ export async function specDeriveWithMapWriteback(args, { fetchImpl = undefined,
   // by a stray value. `--proxy-base` names a URL or is refused here, before
   // anything is read, as `telemetry` refuses a bare one.
   if (Object.hasOwn(args, "write-map") && args["write-map"] !== true) {
-    throw new Error(`--write-map takes no value (got ${JSON.stringify(args["write-map"])}); write \`--write-map\` on its own, after the other flags.`);
+    throw refused(`--write-map takes no value (got ${JSON.stringify(args["write-map"])}); write \`--write-map\` on its own, after the other flags.`);
   }
   if (Object.hasOwn(args, "proxy-base") && !optionalString(args["proxy-base"])) {
-    throw new Error("spec derive: --proxy-base needs a URL (https, or a loopback host); nothing was written.");
+    throw refused("spec derive: --proxy-base needs a URL (https, or a loopback host); nothing was written.");
   }
   if (optionalString(args["proxy-base"]) && args["write-map"] !== true) {
-    throw new Error("spec derive: --proxy-base only applies with --write-map; nothing was written.");
+    throw refused("spec derive: --proxy-base only applies with --write-map; nothing was written.");
   }
   const writeMap = args["write-map"] === true;
   const localArgs = Object.fromEntries(Object.entries(args).filter(([key]) => !SPEC_DERIVE_MAP_FLAGS.includes(key)));