@taprootio/site-authoring 0.8.5 → 0.9.0

package/README.md

@@ -291,10 +291,20 @@ each step names the reference it relies on.
    upload them with `media upload`, then assign `lightLogoId`, `darkLogoId`
    and `brand.faviconId` from the returned ids. There is no recolor, crop or
    SVG upload command.
-5. **Validate, then push.** `validate` runs offline; `theme push` writes the
-   footer colours, the appearance scalars and then both themes in that order,
-   not atomically, and a failure names `completedWrites` — pull, reconcile,
-   push again.
+5. **Validate, preview, then push.** `validate` runs offline;
+   `theme push --dry-run` reads the site and lists the JSON paths at which
+   each settings file differs from it, and whether the baseline `pull`
+   recorded is still current; `theme push` saves both themes, the appearance
+   scalars and the ten footer scheme colours in one transaction fenced by
+   that baseline. A concurrent change to any of those fields refuses the
+   whole push (`theme.concurrent_modification`) and nothing is written: keep
+   copies of the edited files, pull, re-apply, push again. A lost response is
+   safe to retry: the save is recorded as pending before it is sent, running
+   `theme push` again with the same files replays it under its original
+   baseline, and the site answers `applied: false` when it already holds the
+   change set. `pull` reads the four settings documents and the revision
+   from one snapshot, and `footer push` advances the recorded revision only
+   when its save replaced that same revision.
 6. **Review on staging in both schemes.** `deploy --staging` returns a
    single-use handoff in `stagingPreview.url`, on a managed Docs site too;
    open it once and use the site's theme toggle. No page draft is needed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",

package/src/api.js

@@ -103,6 +103,15 @@ export const DEPLOYMENT_STATUSES = Object.freeze([
   DEPLOYMENT_STATUS_FAILED,
 ]);
 
+// DeploySite's admission outcome (TR00839): whether this request created the
+// deployment or coalesced into an already-anchored one.
+export const DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED = "DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED";
+export const DEPLOYMENT_REQUEST_OUTCOME_COALESCED = "DEPLOYMENT_REQUEST_OUTCOME_COALESCED";
+export const DEPLOYMENT_REQUEST_OUTCOMES = Object.freeze([
+  DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED,
+  DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
+]);
+
 export const IMAGE_PROCESSING_STATE_UNKNOWN = "IMAGE_PROCESSING_STATE_UNKNOWN";
 export const IMAGE_PROCESSING_STATE_COMPLETE = "IMAGE_PROCESSING_STATE_COMPLETE";
 export const IMAGE_PROCESSING_STATE_FAILED = "IMAGE_PROCESSING_STATE_FAILED";
@@ -351,7 +360,11 @@ const REFUSAL_GUIDANCE = Object.freeze({
   [REFUSAL_CREDENTIAL_REJECTED]:
     "The site authoring credential was rejected: it is invalid, revoked, or bound to a different site. "
     + "Stop and re-issue it; retrying cannot succeed.",
-  [REFUSAL_THROTTLED]: "This credential exceeded its request budget. Back off and retry with delay.",
+  // Covers both the per-key request-budget throttle and the durable
+  // per-site/per-account deployment request limit (TR00839): both surface as
+  // gRPC ResourceExhausted / HTTP 429, and the remedy is identical either way.
+  [REFUSAL_THROTTLED]:
+    "Too many deployment requests for this site or account. Back off and retry after the delay the server reported.",
 });
 
 /**
@@ -436,6 +449,12 @@ export function announceRefusal(error, onProgress, action = "request") {
   }
   const guidance = REFUSAL_GUIDANCE[kind];
   if (guidance) onProgress(guidance);
+  // The retry-after trailer (TR00839) is the exact delay the server measured;
+  // surface it when the transport captured it rather than leaving the agent
+  // to guess a backoff.
+  if (kind === REFUSAL_THROTTLED && typeof error.retryAfterSeconds === "number") {
+    onProgress(`  Retry after: ${error.retryAfterSeconds}s.`);
+  }
 }
 
 /**
@@ -692,6 +711,63 @@ export async function saveSiteFooterSettings(client, siteId, footerSettings, exp
   );
 }
 
+/**
+ * The shape of a presentation revision as the site reports it (TR00807): the
+ * server's SHA-256 over the presentation change set, lowercase hex. The CLI
+ * never derives one — it records what it was told and sends it back — so this
+ * is a containment check on a server string that reaches the manifest, not a
+ * claim about how the value is computed.
+ */
+export const PRESENTATION_REVISION = /^[0-9a-f]{64}$/u;
+
+/**
+ * Reads the site's draft presentation — the four theme-gated settings groups
+ * as `GetSettings` projects them — with the revision a save must carry
+ * (TR00807).
+ */
+export async function getSitePresentation(client, siteId) {
+  return requireSitePresentation(await client.request(sitePath(siteId, "presentation")), siteId);
+}
+
+/**
+ * Applies a presentation change set atomically (TR00807). `expectedRevision`
+ * is the revision the workspace was pulled at; `expectedFooterDraftHash` is
+ * the footer document's draft token from the read immediately before, because
+ * the server overlays the ten colours onto that document. Sent through the
+ * replayable-POST path: a save whose response was lost is answered as already
+ * current when it committed, and applied when it did not.
+ */
+export async function saveSitePresentation(client, siteId, body) {
+  const response = requireObject(
+    await client.replaceablePost(sitePath(siteId, "presentation"), { body: { siteId, ...body } }),
+    "api.presentation_contract",
+    "presentation save",
+  );
+  return {
+    applied: response.applied === true,
+    presentation: requireSitePresentation(response.presentation, siteId),
+  };
+}
+
+function requireSitePresentation(value, siteId) {
+  const presentation = requireObject(value, "api.presentation_contract", "site presentation");
+  if (!PRESENTATION_REVISION.test(presentation.revision ?? "")) {
+    throw new SiteAuthoringError(
+      "api.presentation_contract",
+      "Taproot returned a presentation with no revision, so a later push could not be fenced against it.",
+      { field: "revision" },
+    );
+  }
+  if (typeof presentation.siteId === "string" && presentation.siteId !== "" && presentation.siteId !== siteId) {
+    throw new SiteAuthoringError(
+      "api.presentation_contract",
+      "Taproot returned a presentation for a different site.",
+      { field: "siteId" },
+    );
+  }
+  return presentation;
+}
+
 export async function requestImageUpload(client, body) {
   return requireObject(
     await client.request("v1/images/request-upload", { method: "POST", body }),
@@ -1017,6 +1093,9 @@ export function normalizeDeployment(value) {
     errorMessage: text(deployment.errorMessage),
     pageCount: safeCount(deployment.pageCount),
     phaseTimings: normalizePhaseTimings(deployment.phaseHistory),
+    // Identical requests coalesced into this deployment inside its settling
+    // window (TR00839). Zero for a deployment that never anchored one.
+    coalescedRequestCount: safeCount(deployment.coalescedRequestCount),
   };
 }
 
@@ -1074,7 +1153,19 @@ export async function deploySite(client, siteId, body) {
     }
     throw error;
   }
-  return normalizeDeployment(response.deployment);
+  const deployment = normalizeDeployment(response.deployment);
+  // `DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED` is the zero-adjacent default: an
+  // older server that omits the field, or the immutable Standard/Docs
+  // branches that never run through the admission seam, both read as this
+  // request creating its own deployment (TR00839).
+  const outcome = enumValue(
+    response.outcome,
+    DEPLOYMENT_REQUEST_OUTCOMES,
+    DEPLOYMENT_REQUEST_OUTCOME_ACCEPTED,
+    "api.deployment_contract",
+    "deployment request outcome",
+  );
+  return { ...deployment, outcome };
 }
 
 /**

package/src/cli.js

@@ -290,9 +290,16 @@ const VERBS = Object.freeze([
     surface: SURFACE_DOCS_PRESENTATION,
     capabilities: [CAPABILITY_DESIGN],
     tokens: ["theme", "push"],
-    summary: "Validate and push the workspace's complete theme and appearance settings.",
+    dryRun: true,
+    summary: "Validate and push the workspace's complete theme and appearance settings in one atomic save.",
     note: "Run pull first. Theme JSON stays decoded in the workspace; this command validates the complete light/dark"
       + " pair and encodes it only at the API boundary. Image settings reference site-owned image IDs from media upload. "
+      + "The complete change set — both themes, the appearance scalars, and the ten footer scheme colors — is saved in "
+      + "one transaction fenced by the presentation revision pull recorded: a concurrent change to any of those "
+      + "fields refuses the whole push (theme.concurrent_modification) and nothing is written. A save whose response "
+      + "was lost is replayed safely; the site answers applied=false when it already holds the change set. "
+      + "--dry-run reads the site, reports the JSON paths at which each settings file differs from it and whether "
+      + "the recorded baseline is still current, and writes nothing. "
       + "pull writes each scheme's complete effective theme — the stored theme resolved over the same defaults every "
       + "consumer renders — so a fresh workspace validates as pulled. semanticMappings holds only authored pins, listed "
       + "in explicitMappingTokens; every other token compiles from roles at render time, so never copy default "
@@ -570,6 +577,9 @@ function verbHelp(verb) {
   const jsonOption = verb.json
     ? "\n  --json           Emit the stable JSON contract (operational output is always JSON)."
     : "";
+  const dryRunOption = verb.dryRun
+    ? "\n  --dry-run        Read the site and report what a push would change, without writing."
+    : "";
   const nameOption = verb.keyName
     ? `\n  --name <text>    Name recorded on the issued key (default "${DEFAULT_LOGIN_KEY_NAME}",\n`
       + `                   1-${LOGIN_KEY_NAME_MAXIMUM} characters). The approval screen shows it.`
@@ -637,7 +647,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${deliveryTargetOption}${rawHtmlOption}${jsonOption}${nameOption}${note}
+${options}${targetOption}${deliveryTargetOption}${rawHtmlOption}${jsonOption}${dryRunOption}${nameOption}${note}
 `;
 }
 
@@ -912,6 +922,7 @@ function parseArguments(arguments_) {
   let browser;
   let allowFailedPreview = false;
   let allowRawHtml = false;
+  let dryRun = false;
   let json = false;
   let keyName;
   const positionals = [];
@@ -977,6 +988,11 @@ function parseArguments(arguments_) {
       allowRawHtml = true;
       continue;
     }
+    if (verb.dryRun && argument === "--dry-run") {
+      if (dryRun) throw usageError("cli.duplicate_option", "--dry-run may be supplied only once.");
+      dryRun = true;
+      continue;
+    }
     if (verb.json && argument === "--json") {
       if (json) throw usageError("cli.duplicate_option", "--json may be supplied only once.");
       json = true;
@@ -1107,6 +1123,7 @@ function parseArguments(arguments_) {
     ...(browser === undefined ? {} : { browser }),
     init,
     allowRawHtml,
+    dryRun,
     keyName,
     positionals: verb.positionals
       ? {
@@ -1184,6 +1201,7 @@ export async function runCli({
       init: parsed.init,
       quiet: parsed.quiet,
       allowRawHtml: parsed.allowRawHtml,
+      dryRun: parsed.dryRun,
       keyName: parsed.keyName,
       capabilities: parsed.capabilities,
       surface: parsed.surface,

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.8.5";
+export const CLI_VERSION = "0.9.0";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";

package/src/footer-draft-hash.js

@@ -66,7 +66,7 @@ function requireBoundedDepth(value) {
 }
 
 /** Deterministic JSON: sorted object keys, JSON.stringify value semantics. */
-function stableJson(value) {
+export function stableJson(value) {
   if (value === null || typeof value !== "object") {
     return JSON.stringify(value) ?? "null";
   }

package/src/footer-workspace.js

@@ -1,7 +1,8 @@
 import { isCanonicalUuid, SiteAuthoringError } from "./errors.js";
 import { appearanceImageIds } from "./appearance-contract.js";
 import { footerImageIds } from "./footer-contract.js";
-import { computeFooterContentHash, computeFooterDraftHash } from "./footer-draft-hash.js";
+import { createHash } from "node:crypto";
+import { computeFooterContentHash, computeFooterDraftHash, stableJson } from "./footer-draft-hash.js";
 import { readManifest, readMediaManifest, writeManifest } from "./workspace.js";
 
 export const FOOTER_SETTINGS_FILE = "settings/site-publishing-preferences.json";
@@ -73,7 +74,13 @@ export async function readAppearanceWorkspaceContext(workspaceDir, siteId) {
   };
 }
 
-export async function advanceFooterManifest(workspaceDir, siteId, footerSettings, expectedDraftHash) {
+export async function advanceFooterManifest(
+  workspaceDir,
+  siteId,
+  footerSettings,
+  expectedDraftHash,
+  { presentationRevision } = {},
+) {
   const manifest = await readManifest(workspaceDir, siteId);
   const prior = requireFooterMetadata(manifest);
   const hash = expectedDraftHash ?? computeFooterDraftHash(footerSettings);
@@ -90,10 +97,98 @@ export async function advanceFooterManifest(workspaceDir, siteId, footerSettings
     expectedContentHash: computeFooterContentHash(footerSettings),
     imageIds: [...new Set([...prior.imageIds, ...footerImageIds(footerSettings)])].sort(),
   };
+  // The ten scheme colours are part of the presentation change set, so a
+  // footer save that moved one moved the revision too; the server reports the
+  // new one from the same transaction and it becomes the baseline the next
+  // theme push must carry (TR00807). One manifest write for both baselines.
+  if (presentationRevision !== undefined) {
+    manifest.presentation = presentationManifestEntry(presentationRevision);
+  }
   await writeManifest(workspaceDir, manifest);
   return hash;
 }
 
+/**
+ * The manifest's record of the presentation revision this workspace was
+ * pulled at (TR00807): what `theme push` sends as its baseline, and what a
+ * dry run compares the site's current revision against.
+ */
+export function presentationManifestEntry(revision) {
+  if (!SHA256.test(revision ?? "")) {
+    throw new SiteAuthoringError(
+      "api.presentation_contract",
+      "Taproot returned a presentation revision that could not be recorded.",
+      { field: "revision" },
+    );
+  }
+  return { revision };
+}
+
+/**
+ * The recorded presentation baseline, or `undefined` when the manifest holds
+ * none — a workspace pulled before the atomic save existed, or against a
+ * Taproot that does not serve it. Absent is a fact `theme push` refuses on,
+ * not a value to guess.
+ */
+export function readPresentationBaseline(manifest) {
+  const presentation = manifest.presentation;
+  if (presentation === null || typeof presentation !== "object" || Array.isArray(presentation)) return undefined;
+  return SHA256.test(presentation.revision ?? "") ? { revision: presentation.revision } : undefined;
+}
+
+/**
+ * The content identity of one presentation change set — what `theme push`
+ * sends — so a later run can tell whether a save recorded as pending was for
+ * exactly the change set it is about to send again.
+ */
+export function computePresentationChangeSetHash(changeSet) {
+  return createHash("sha256").update(`presentation-change-set-v1${stableJson(changeSet)}`, "utf8").digest("hex");
+}
+
+/**
+ * The record of a presentation save whose outcome this workspace does not yet
+ * know (TR00807): the baseline it was sent under and the change set it
+ * carried, written before the request and replaced by the manifest write
+ * that follows an authoritative answer. A save that committed while its
+ * response was lost leaves the site one revision ahead of the workspace; the
+ * next push of the same change set replays it under this baseline, and the
+ * site answers already-current instead of the stale refusal the workspace's
+ * own comparison would give. `undefined` when nothing is pending.
+ */
+export function readPendingPresentationSave(manifest) {
+  const pending = manifest.presentation?.pending;
+  if (pending === null || typeof pending !== "object" || Array.isArray(pending)) return undefined;
+  if (!SHA256.test(pending.expectedRevision ?? "") || !SHA256.test(pending.changeSetHash ?? "")) return undefined;
+  return {
+    expectedRevision: pending.expectedRevision,
+    changeSetHash: pending.changeSetHash,
+    startedAt: typeof pending.startedAt === "string" ? pending.startedAt : undefined,
+  };
+}
+
+export async function recordPendingPresentationSave(workspaceDir, siteId, { expectedRevision, changeSetHash, startedAt }) {
+  const manifest = await readManifest(workspaceDir, siteId);
+  const baseline = readPresentationBaseline(manifest);
+  if (baseline === undefined) {
+    throw new SiteAuthoringError(
+      "theme.pull_required",
+      "The pull manifest records no presentation baseline. Run 'taproot-site pull' again.",
+      { field: "presentation.revision" },
+    );
+  }
+  manifest.presentation = { revision: baseline.revision, pending: { expectedRevision, changeSetHash, startedAt } };
+  await writeManifest(workspaceDir, manifest);
+}
+
+/** Drops the pending record after an authoritative refusal; the baseline stays. */
+export async function clearPendingPresentationSave(workspaceDir, siteId) {
+  const manifest = await readManifest(workspaceDir, siteId);
+  const baseline = readPresentationBaseline(manifest);
+  if (baseline === undefined || readPendingPresentationSave(manifest) === undefined) return;
+  manifest.presentation = presentationManifestEntry(baseline.revision);
+  await writeManifest(workspaceDir, manifest);
+}
+
 export function footerManifestEntry(footerSettings) {
   return {
     file: FOOTER_SETTINGS_FILE,

package/src/presentation-reference.js

@@ -440,14 +440,34 @@ export function getAppearanceReference() {
       + "menus with many groups. The navigation face itself is not an appearance scalar: fontMenu and fontWeightMenu "
       + "are per-scheme theme fields set in settings.lightTheme/darkTheme the same way fontBrand is, and an empty "
       + "fontMenu falls back to the body font, never to headings.",
-    mutationOrder: [
-      "fresh footer read plus concurrency-protected ten-color overlay",
+    changeSet: [
+      "the ten footer scheme colors, overlaid onto the site's current footer document",
       "default scheme, assets, favicon, and header scalars",
-      "complete light theme, then complete dark theme",
+      "the complete light theme and the complete dark theme",
     ],
-    nonAtomic: true,
+    atomic: true,
+    revision:
+      "pull reads the four settings documents and the site's presentation revision — a server hash over exactly "
+      + "the fields theme push writes — from one snapshot, so the recorded baseline is the revision of the "
+      + "documents the workspace holds; theme push sends it back as the baseline. The whole change set commits in "
+      + "one transaction or none of it does; a change to any of those fields since the pull refuses the push "
+      + "(theme.concurrent_modification) and nothing is written. Footer prose, links and imagery, and the "
+      + "publishing scalars are outside the revision, so an unrelated concurrent edit is preserved rather than "
+      + "refused. footer push advances the baseline only when its save replaced that same revision.",
+    dryRun:
+      CLI_BINARY_NAME + " theme push --dry-run reads the site, lists the JSON paths at which each settings file "
+      + "differs from it, and says whether the recorded baseline is still current or a pending save of the same "
+      + "change set would be replayed; it writes nothing.",
+    retry:
+      "The save is recorded as pending in the manifest before it is sent. A save whose response was lost is "
+      + "replayed by running theme push again with the same settings files: it goes under the baseline it was "
+      + "first sent with, even after the site's revision moved, and the site answers applied=false when it already "
+      + "holds the change set, so nothing is applied twice and no partial write is ever reported. Editing the "
+      + "files before retrying makes the pending record moot and a moved revision refuses toward pull.",
     recovery:
-      "A failure reports completedWrites. Pull, compare the remote result with the intended workspace, reconcile, and retry.",
+      "On theme.concurrent_modification keep copies of the edited settings files, run " + CLI_BINARY_NAME
+      + " pull to refresh the baseline, re-apply the edits, and push again. A Taproot without the atomic save "
+      + "refuses with theme.server_unsupported; theme push never falls back to sequential writes.",
     footerBoundary:
       "theme push changes only five colors per footer scheme. Use footer push for prose, links, layout, and imagery.",
     footerContentGuard:
@@ -604,9 +624,11 @@ export function getFooterReference() {
     concurrency:
       "pull records expectedDraftHash. A conflict returns footer.concurrent_modification; pull, reconcile, and retry.",
     themeInteraction:
-      "theme push rewrites this file from a fresh server read before its ten-color overlay. It refuses while "
-      + "unpushed footer-content edits exist (theme.unpushed_footer_content); run " + CLI_BINARY_NAME
-      + " footer push first, or " + CLI_BINARY_NAME + " pull to discard the local edit.",
+      "theme push overlays its ten scheme colors onto the site's current footer document inside its atomic save and "
+      + "rewrites this file from the saved result. It refuses while unpushed footer-content edits exist "
+      + "(theme.unpushed_footer_content); run " + CLI_BINARY_NAME + " footer push first, or " + CLI_BINARY_NAME
+      + " pull to discard the local edit. A footer push that changed a scheme color advances the presentation "
+      + "baseline theme push is fenced by.",
     workflow: [
       CLI_BINARY_NAME + " pull",
       "edit settings/site-publishing-preferences.json at settings.footerSettings",
@@ -704,8 +726,11 @@ export function formatPresentationReference(reference) {
       + "\nHeader width: " + reference.headerWidthContract
       + "\nMobile menu and menu font: " + reference.menuContract
       + "\nFooter: " + reference.footerBoundary
-      + "\nFooter content guard: " + reference.footerContentGuard + "\n\nMutation order (non-atomic):\n"
-      + reference.mutationOrder.map((step, index) => "  " + (index + 1) + ". " + step).join("\n")
+      + "\nFooter content guard: " + reference.footerContentGuard + "\n\nAtomic change set (one transaction):\n"
+      + reference.changeSet.map((step, index) => "  " + (index + 1) + ". " + step).join("\n")
+      + "\nRevision: " + reference.revision
+      + "\nDry run: " + reference.dryRun
+      + "\nRetry: " + reference.retry
       + "\nRecovery: " + reference.recovery + "\n";
   }
   if (reference.referenceKind === "footer") {

package/src/reference-help.js

@@ -481,9 +481,13 @@ const WORKFLOW_REFERENCES = Object.freeze({
       `Validate offline: ${CLI_BINARY_NAME} validate checks the complete pair, the appearance files and the footer against `
       + "the contracts the site enforces, and warns when a semanticMappings pin repeats the default on a token your "
       + "roles would have moved (the pin would keep the role from rendering).",
-      `Push: ${CLI_BINARY_NAME} theme push writes the footer scheme colours, the appearance scalars, then the light and dark `
-      + "themes in that order, not atomically. A failure reports completedWrites: pull, compare the remote result "
-      + "with the workspace, reconcile, and push again. footer push owns footer prose, links and imagery.",
+      `Push: ${CLI_BINARY_NAME} theme push --dry-run first: it reads the site and lists the JSON paths at which each `
+      + "settings file differs from it, and says whether the baseline pull recorded is still current. Then "
+      + `${CLI_BINARY_NAME} theme push saves both themes, the appearance scalars and the ten footer scheme colours in `
+      + "one transaction fenced by that baseline: a concurrent change to any of those fields refuses the whole push "
+      + "(theme.concurrent_modification) and nothing is written; keep copies of the edited files, pull, re-apply, "
+      + "and push again. A lost response is safe to retry — the site answers applied=false when it already holds "
+      + "the change set. footer push owns footer prose, links and imagery.",
       `Review on staging: ${CLI_BINARY_NAME} deploy --staging stages the presentation and returns a single-use review handoff `
       + "in stagingPreview.url (on a managed Docs site too). Open it once, then use the site's theme toggle to check "
       + "both schemes: text, headings, links and hover, actions and focus, the header logos, the favicon. When no "

package/src/transport.js

@@ -125,6 +125,12 @@ const UUID_PATH = "[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0
  *   server answers `..._CONSUMED`, which `login` surfaces as an issued-but-
  *   unreceived credential the owner must revoke. Not replaying would leave that
  *   same orphan and report only a network error, which is strictly worse.
+ * - **Atomic presentation save** (TR00807) — the request carries the revision
+ *   it was built against, and the server computes the revision the change set
+ *   would produce. A replay of a save that committed finds the site already at
+ *   that revision and answers `applied: false` with the current state; a
+ *   replay of one that never committed applies it; anything else is refused as
+ *   stale. No replay can apply the change set twice or report a partial one.
  */
 const REPLACEABLE_POST_PATHS = Object.freeze([
   new RegExp(
@@ -132,6 +138,7 @@ const REPLACEABLE_POST_PATHS = Object.freeze([
     "u",
   ),
   /^v1\/site-authoring\/cli-authorizations\/claim$/u,
+  new RegExp(`^v1/sites/${UUID_PATH}/presentation$`, "u"),
 ]);
 
 /**
@@ -396,8 +403,21 @@ export function capabilityRefusal(value) {
   return undefined;
 }
 
+/**
+ * Reads the `retry-after` response header as a non-negative integer number of
+ * seconds. `headers` is a Fetch `Headers` instance when available; anything
+ * else, a missing header, or a value that does not parse as a non-negative
+ * number, returns undefined rather than throwing.
+ */
+function parseRetryAfterHeader(headers) {
+  const raw = typeof headers?.get === "function" ? headers.get("retry-after") : undefined;
+  if (typeof raw !== "string" || raw.length === 0) return undefined;
+  const seconds = Number(raw);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}
+
 export class ApiError extends SiteAuthoringError {
-  constructor(httpStatus, body) {
+  constructor(httpStatus, body, headers) {
     const grpcCode = Number.isSafeInteger(body?.code) ? body.code : undefined;
     const fields = fieldViolations(body);
     const capability = capabilityRefusal(body);
@@ -433,6 +453,11 @@ export class ApiError extends SiteAuthoringError {
     this.fields = fields;
     this.violationDescriptions = fieldDescriptions(body);
     this.capability = capability;
+    // The `retry-after` trailer (TR00839's deployment throttle, or any other
+    // ResourceExhausted refusal that sets it) transcodes to an ordinary
+    // response header. Undefined when absent or unparseable — callers must
+    // not assume every throttle carries a delay.
+    this.retryAfterSeconds = parseRetryAfterHeader(headers);
   }
 
   hasField(field) {
@@ -767,7 +792,7 @@ export class SiteApiClient {
         responseBody = Object.create(null);
       }
       if (remainingBudget(deadline, now) <= 0) throw deadlineError();
-      throw new ApiError(response.status, responseBody);
+      throw new ApiError(response.status, responseBody, response.headers);
     }
     throw new SiteAuthoringError("transport.retry_exhausted", "The Taproot API request exhausted its retry budget.");
   }

package/src/verbs/deploy.js

@@ -1,6 +1,7 @@
 import {
   DEPLOYMENT_ENVIRONMENT_PRODUCTION,
   DEPLOYMENT_ENVIRONMENT_STAGING,
+  DEPLOYMENT_REQUEST_OUTCOME_COALESCED,
   DEPLOYMENT_STATUS_COMPLETED,
   deploySite,
   getDeploySelection,
@@ -80,6 +81,16 @@ function usageError(code, message, field) {
   return new SiteAuthoringError(code, message, { field, exitCode: 2 });
 }
 
+/**
+ * One line when this request coalesced into an already in-flight or recently
+ * anchored identical deployment (TR00839), instead of creating a new one.
+ */
+function announceOutcome(created, onProgress) {
+  if (created.outcome === DEPLOYMENT_REQUEST_OUTCOME_COALESCED) {
+    onProgress(`An identical deployment request is already in progress; reusing deployment ${created.id}.`);
+  }
+}
+
 function explicitSelection(invocation) {
   const stagedPageIds = Array.isArray(invocation.stagedPageIds) ? invocation.stagedPageIds : undefined;
   const selectedSettingsTypes = Array.isArray(invocation.selectedSettingsTypes)
@@ -268,6 +279,7 @@ export async function deploy(invocation) {
         ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
       });
       onProgress(`Production deployment ${created.id} accepted; waiting for it to complete.`);
+      announceOutcome(created, onProgress);
       const completed = await waitForDeployment(client, {
         siteId,
         deploymentId: created.id,
@@ -283,6 +295,7 @@ export async function deploy(invocation) {
         ...(presentationOnly ? { authoringSurface: SURFACE_DOCS_PRESENTATION } : {}),
         promotedStagingDeploymentId: stagingDeploymentId,
         deployment: completed,
+        outcome: created.outcome,
         readiness: reportReadiness(readiness),
       });
     }
@@ -357,6 +370,7 @@ export async function deploy(invocation) {
       ...(invocation.allowFailedPreview === true ? { allowFailedPreview: true } : {}),
     });
     onProgress(`Staging deployment ${created.id} accepted; waiting for it to complete.`);
+    announceOutcome(created, onProgress);
     const completed = await waitForDeployment(client, {
       siteId,
       deploymentId: created.id,
@@ -377,6 +391,7 @@ export async function deploy(invocation) {
           includeNavigation: false,
         },
         deployment: completed,
+        outcome: created.outcome,
         readiness: reportReadiness(readiness),
         stagingPreview,
         nextStep: stagingPreview.url === "" ? "staging review" : "deploy --production",
@@ -393,6 +408,7 @@ export async function deploy(invocation) {
         includeNavigation,
       },
       deployment: completed,
+      outcome: created.outcome,
       readiness: reportReadiness(readiness),
       stagingPreview,
       nextStep: stagingPreview.redirects?.verified === true ? "deploy --production" : "redirects check",

package/src/verbs/footer-push.js

@@ -1,9 +1,14 @@
-import { saveSiteFooterSettings, withRefusalGuidance } from "../api.js";
+import { PRESENTATION_REVISION, saveSiteFooterSettings, withRefusalGuidance } from "../api.js";
 import { VERB_FOOTER_PUSH } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { projectFooterSettingsForWorkspace, validateFooterDocument } from "../footer-contract.js";
 import { computeFooterDraftHash } from "../footer-draft-hash.js";
-import { advanceFooterManifest, FOOTER_SETTINGS_FILE, readFooterWorkspaceContext } from "../footer-workspace.js";
+import {
+  advanceFooterManifest,
+  FOOTER_SETTINGS_FILE,
+  readFooterWorkspaceContext,
+  readPresentationBaseline,
+} from "../footer-workspace.js";
 import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES } from "../settings-catalog.js";
 import { ApiError } from "../transport.js";
@@ -105,7 +110,27 @@ export async function footerPush(invocation) {
     // fails, a stale token prevents the next push from overwriting the saved
     // remote footer and the completed-write report tells the caller to pull.
     await writeWorkspaceJson(config.workspaceDir, FOOTER_SETTINGS_FILE, nextDocument);
-    await advanceFooterManifest(config.workspaceDir, siteId, saved, footerDraftHash);
+    // A footer save that moved a scheme colour moved the presentation revision
+    // (TR00807); the server reports the new one from its own transaction, and
+    // the one it replaced. The baseline advances only when the replaced
+    // revision is the one this workspace was pulled at: otherwise the site's
+    // appearance moved since the pull, the workspace's appearance files do not
+    // reflect it, and a baseline taken from this save would let the next
+    // theme push overwrite those edits unseen. A Taproot that predates the
+    // fields leaves the recorded baseline alone.
+    const baseline = readPresentationBaseline(context.manifest);
+    const reported = PRESENTATION_REVISION.test(response.presentationRevision ?? "")
+      && PRESENTATION_REVISION.test(response.previousPresentationRevision ?? "");
+    const advances = reported && baseline !== undefined && baseline.revision === response.previousPresentationRevision;
+    if (reported && baseline !== undefined && !advances) {
+      onProgress(
+        "The site's presentation moved after this workspace was pulled, so its presentation baseline was left as "
+          + "it is; 'taproot-site theme push' will refuse until the workspace is pulled again.",
+      );
+    }
+    await advanceFooterManifest(config.workspaceDir, siteId, saved, footerDraftHash, {
+      presentationRevision: advances ? response.presentationRevision : undefined,
+    });
   } catch (error) {
     if (error instanceof SiteAuthoringError) throw error.withCompletedWrites(["footerSettings"]);
     throw error;

package/src/verbs/pull.js

@@ -2,6 +2,7 @@ import {
   getNavigation,
   getPage,
   getSettingsGroup,
+  getSitePresentation,
   getSiteRedirectMap,
   listSitePages,
   PAGE_STATUS_DELETED,
@@ -17,7 +18,7 @@ import {
   VERB_PULL,
 } from "../constants.js";
 import { sanitizeDiagnostic, SiteAuthoringError } from "../errors.js";
-import { appearanceManifestEntry, footerManifestEntry } from "../footer-workspace.js";
+import { appearanceManifestEntry, footerManifestEntry, presentationManifestEntry } from "../footer-workspace.js";
 import { describeJsonDifferences, reportableDifferencePaths } from "../json-path-diff.js";
 import { projectRedirectMapForWorkspace, REDIRECTS_FILE_NAME } from "../redirects-contract.js";
 import { redirectsManifestEntry } from "../redirects-workspace.js";
@@ -626,28 +627,74 @@ export async function pull(invocation) {
     // decoding is a wire-contract check and can fail on malformed stored data;
     // discovering that after page bodies were written would strand an
     // unbound workspace that the next pull must refuse for safety.
+    //
+    // The four groups and the presentation revision `theme push` is fenced by
+    // (TR00807) come from one read: the presentation snapshot carries the
+    // groups' documents exactly as the revision covers them, so the baseline
+    // the manifest records is the revision of the documents the workspace
+    // holds. Four per-group reads followed by a revision read would pair
+    // whatever the groups held with whatever the revision had become by then,
+    // and a push fenced by that baseline could overwrite an edit the workspace
+    // never saw. The per-group reads remain for a Taproot that predates the
+    // snapshot (404) and for a credential that cannot read it (403): both
+    // record no baseline, and `theme push` refuses toward a pull that does.
+    let presentation;
+    onProgress("Reading the presentation snapshot.");
+    try {
+      presentation = await getSitePresentation(client, siteId);
+    } catch (error) {
+      if (
+        error instanceof ApiError
+        && error.refusalKind() === REFUSAL_UNCLASSIFIED
+        && error.httpStatus === 404
+      ) {
+        onProgress(
+          "This Taproot does not serve the atomic presentation save yet; the settings groups are read one at a "
+            + "time, the manifest records no presentation baseline, and 'theme push' will refuse until it is "
+            + "pulled from a Taproot that does.",
+        );
+      } else if (
+        error instanceof ApiError
+        && (error.refusalKind() === REFUSAL_UNCLASSIFIED
+          || error.refusalKind() === REFUSAL_CAPABILITY_MISSING)
+        && error.httpStatus === 403
+      ) {
+        onProgress(
+          "The presentation snapshot is not readable by this credential; the settings groups are read one at a "
+            + "time and the manifest records no presentation baseline.",
+        );
+      } else {
+        throw error;
+      }
+    }
+    const presentationRevision = presentation?.revision;
+
     const pulledSettings = [];
     const skippedSettings = [];
     const settingsDocuments = [];
     let pulledFooter;
     const pulledAppearance = {};
     for (const group of SETTINGS_GROUPS) {
-      onProgress(`Reading settings group ${group.settingsType}.`);
       let response;
-      try {
-        response = await getSettingsGroup(client, siteId, group.settingsType);
-      } catch (error) {
-        if (
-          error instanceof ApiError
-          && (error.refusalKind() === REFUSAL_UNCLASSIFIED
-            || error.refusalKind() === REFUSAL_CAPABILITY_MISSING)
-          && UNAVAILABLE_SETTINGS_STATUSES.has(error.httpStatus)
-        ) {
-          onProgress(`Settings group ${group.settingsType} is not readable by this credential; skipping it.`);
-          skippedSettings.push(group.settingsType);
-          continue;
+      if (presentation !== undefined) {
+        response = presentation;
+      } else {
+        onProgress(`Reading settings group ${group.settingsType}.`);
+        try {
+          response = await getSettingsGroup(client, siteId, group.settingsType);
+        } catch (error) {
+          if (
+            error instanceof ApiError
+            && (error.refusalKind() === REFUSAL_UNCLASSIFIED
+              || error.refusalKind() === REFUSAL_CAPABILITY_MISSING)
+            && UNAVAILABLE_SETTINGS_STATUSES.has(error.httpStatus)
+          ) {
+            onProgress(`Settings group ${group.settingsType} is not readable by this credential; skipping it.`);
+            skippedSettings.push(group.settingsType);
+            continue;
+          }
+          throw error;
         }
-        throw error;
       }
       const file = `${SETTINGS_DIRECTORY}/${group.file}`;
       const projected = projectSettingsGroup(group, response);
@@ -1048,6 +1095,7 @@ export async function pull(invocation) {
           ? { appearance: appearanceManifestEntry(pulledAppearance) }
           : {}
       ),
+      ...(presentationRevision === undefined ? {} : { presentation: presentationManifestEntry(presentationRevision) }),
       pages: manifestPages,
     };
     await writeManifest(config.workspaceDir, manifest);

package/src/verbs/theme-push.js

@@ -1,27 +1,36 @@
-import { getSettingsGroup, saveSiteFooterSettings, setSetting, withRefusalGuidance } from "../api.js";
+import { getSitePresentation, saveSitePresentation, withRefusalGuidance } from "../api.js";
 import {
+  APPEARANCE_FOOTER_COLOR_FIELDS,
   APPEARANCE_SCALAR_FIELDS,
-  applyFooterColors,
   buildAppearanceScalarOperations,
   footerColorOverlay,
 } from "../appearance-contract.js";
-import { VERB_THEME_PUSH } from "../constants.js";
+import { REFUSAL_UNCLASSIFIED, VERB_THEME_PUSH } from "../constants.js";
 import { MISSING_SETTING_MESSAGE, SiteAuthoringError } from "../errors.js";
 import { projectFooterSettingsForWorkspace } from "../footer-contract.js";
 import { computeFooterDraftHash } from "../footer-draft-hash.js";
 import {
   advanceFooterManifest,
+  clearPendingPresentationSave,
+  computePresentationChangeSetHash,
   readAppearanceWorkspaceContext,
+  readPendingPresentationSave,
+  readPresentationBaseline,
+  recordPendingPresentationSave,
   requireFooterContentPushed,
 } from "../footer-workspace.js";
+import { describeJsonDifferences } from "../json-path-diff.js";
 import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import {
+  projectSettingsGroup,
+  SETTINGS_GROUPS,
   SETTINGS_TYPE_BRAND,
   SETTINGS_TYPE_SITE_HEADER,
   SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
   SETTINGS_TYPE_TAPROOT_STYLES,
 } from "../settings-catalog.js";
 import { missingThemeFields, validateAndEncodeThemePair } from "../theme-validation.js";
+import { ApiError } from "../transport.js";
 import {
   readWorkspaceJson,
   SETTINGS_DIRECTORY,
@@ -36,6 +45,15 @@ const SETTINGS_FILES = Object.freeze({
   [SETTINGS_TYPE_SITE_HEADER]: "site-header.json",
   [SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES]: "site-publishing-preferences.json",
 });
+
+/**
+ * The two theme documents travel as writes beside the scalars: the same
+ * `(group, setting, value)` triples `SetSetting` accepts, which is what the
+ * atomic save takes (TR00807). Order is the appearance registry's, themes
+ * last, so the audit row reads the way the old sequential order did.
+ */
+const THEME_SETTINGS = Object.freeze(["lightTheme", "darkTheme"]);
+
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -142,96 +160,354 @@ export async function validateThemeWorkspace(workspaceDir, siteId, knownImageIds
   return { style, brand, header, publishing, themes, scalarOperations, footerColors };
 }
 
+/**
+ * The change set the atomic save receives: every appearance scalar in
+ * registry order, then the two encoded themes, plus the ten footer colours.
+ */
+function buildChangeSet(validated) {
+  return {
+    settings: [
+      ...validated.scalarOperations.map((operation) => ({
+        settingsType: operation.settingsType,
+        setting: operation.setting,
+        value: operation.value,
+      })),
+      ...THEME_SETTINGS.map((setting) => ({
+        settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+        setting,
+        value: setting === "lightTheme" ? validated.themes.light : validated.themes.dark,
+      })),
+    ],
+    footerColors: validated.footerColors,
+  };
+}
+
+/**
+ * A Taproot that answers the presentation routes with 404 predates the atomic
+ * save. The truthful answer is a refusal that says so: this verb no longer
+ * performs the sequential writes an older server would accept, because those
+ * are exactly the partial-failure shape the atomic save exists to remove.
+ */
+function translateServerSupport(error, action) {
+  if (
+    error instanceof ApiError
+    && error.refusalKind() === REFUSAL_UNCLASSIFIED
+    && error.httpStatus === 404
+  ) {
+    return new SiteAuthoringError(
+      "theme.server_unsupported",
+      `This Taproot does not serve the atomic presentation ${action}. 'theme push' saves the complete change set in `
+        + "one transaction and does not fall back to the older sequential writes; use a Taproot that serves "
+        + "/v1/sites/{siteId}/presentation, or an older CLI release against this one.",
+      { field: "presentation", status: error.status },
+    );
+  }
+  return error;
+}
+
+function translateSaveRefusal(error) {
+  if (error instanceof ApiError && error.hasField("ExpectedRevision")) {
+    return new SiteAuthoringError(
+      "theme.concurrent_modification",
+      "The site's presentation changed after this workspace was pulled, so the push was refused and nothing was "
+        + "written. Keep copies of the edited settings files, run 'taproot-site pull' to refresh the baseline, "
+        + "re-apply the edits, and push again; 'theme push --dry-run' shows what differs.",
+      { field: "revision", status: error.status },
+    );
+  }
+  if (error instanceof ApiError && error.hasField("ExpectedFooterDraftHash")) {
+    return new SiteAuthoringError(
+      "theme.footer_concurrent_modification",
+      "The footer document changed between this push's read and its save, so the push was refused and nothing was "
+        + "written. Run 'taproot-site theme push' again; it re-reads the footer before saving.",
+      { field: "expectedFooterDraftHash", status: error.status },
+    );
+  }
+  return translateServerSupport(error, "save");
+}
+
+/**
+ * The workspace's copy of exactly the fields the save owns, per settings
+ * file, and the site's copy projected the way `pull` writes it — so the paths
+ * reported are paths in the files an author edits.
+ */
+function ownedDocuments(validated, presentation) {
+  const projected = {};
+  for (const group of SETTINGS_GROUPS) {
+    projected[group.settingsType] = projectSettingsGroup(group, presentation);
+  }
+  const owned = (settingsType, local, remote, names) => ({
+    file: `${SETTINGS_DIRECTORY}/${SETTINGS_FILES[settingsType]}`,
+    local: Object.fromEntries(names.map((name) => [name, local[name]])),
+    remote: Object.fromEntries(names.map((name) => [name, remote[name]])),
+  });
+  const scalarNames = (settingsType) =>
+    APPEARANCE_SCALAR_FIELDS.filter((field) => field.settingsType === settingsType).map((field) => field.name);
+  const footerColors = (footer) => {
+    const colors = {};
+    for (const definition of APPEARANCE_FOOTER_COLOR_FIELDS) {
+      const scheme = isPlainObject(footer?.[definition.scheme]) ? footer[definition.scheme] : {};
+      colors[definition.scheme] ??= {};
+      colors[definition.scheme][definition.name] = scheme[definition.name] ?? "";
+    }
+    return { footerSettings: colors };
+  };
+  return [
+    owned(
+      SETTINGS_TYPE_TAPROOT_STYLES,
+      validated.style,
+      projected[SETTINGS_TYPE_TAPROOT_STYLES],
+      [...THEME_SETTINGS, ...scalarNames(SETTINGS_TYPE_TAPROOT_STYLES)],
+    ),
+    owned(SETTINGS_TYPE_BRAND, validated.brand, projected[SETTINGS_TYPE_BRAND], scalarNames(SETTINGS_TYPE_BRAND)),
+    owned(
+      SETTINGS_TYPE_SITE_HEADER,
+      validated.header,
+      projected[SETTINGS_TYPE_SITE_HEADER],
+      scalarNames(SETTINGS_TYPE_SITE_HEADER),
+    ),
+    {
+      file: `${SETTINGS_DIRECTORY}/${SETTINGS_FILES[SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES]}`,
+      local: footerColors(validated.publishing.footerSettings),
+      remote: footerColors(projected[SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES].footerSettings),
+    },
+  ];
+}
+
+/** The JSON paths at which each settings file differs from the site, remote first. */
+function describeDifferences(validated, presentation) {
+  return ownedDocuments(validated, presentation).map((document_) => {
+    const differences = describeJsonDifferences(document_.remote, document_.local);
+    return {
+      file: document_.file,
+      paths: differences.paths,
+      ...(differences.truncated ? { truncated: true } : {}),
+    };
+  });
+}
+
 export async function themePush(invocation) {
   const session = await openSession(invocation);
   const { client, config, siteId, onProgress } = session;
+  const dryRun = invocation.dryRun === true;
   // One advisory line before this verb does any work, and only when the
   // exchange said the platform is paused. It changes nothing else: the write
   // still runs and its refusal still classifies as platform_paused (TR00692).
-  warnIfExternalWritesPaused(session, VERB_THEME_PUSH);
+  if (!dryRun) warnIfExternalWritesPaused(session, VERB_THEME_PUSH);
   const appearanceContext = await readAppearanceWorkspaceContext(config.workspaceDir, siteId);
-  const { publishing, themes, scalarOperations, footerColors } = await validateThemeWorkspace(
+  const validated = await validateThemeWorkspace(
     config.workspaceDir,
     siteId,
     appearanceContext.knownImageIds,
   );
-  // The fresh footer read below replaces the workspace document, so refuse
+  const { publishing, themes, scalarOperations } = validated;
+  // The save's response replaces the workspace footer document, so refuse
   // while it still carries footer-content edits that footer push has not
   // saved. Colour-only differences are theme push's own to write.
   requireFooterContentPushed(appearanceContext.footer, publishing.footerSettings);
+  const baseline = readPresentationBaseline(appearanceContext.manifest);
+  if (!dryRun && baseline === undefined) {
+    throw new SiteAuthoringError(
+      "theme.pull_required",
+      "The pull manifest records no presentation baseline, so this push has no revision to be fenced by. Run "
+        + "'taproot-site pull' against a Taproot that serves the atomic presentation save, then retry 'theme push'.",
+      { field: "presentation.revision" },
+    );
+  }
   onProgress(`Validated the complete light/dark theme pair and ${scalarOperations.length} appearance settings.`);
   for (const warning of themes.warnings) onProgress(`Espalier warning: ${warning}`);
+  const warnings = {
+    items: themes.warnings,
+    count: themes.warningCount,
+    ...(themes.warningsTruncated ? { truncated: true } : {}),
+  };
 
-  const written = [];
+  // The fresh read serves both modes: the dry run compares against it, and
+  // the push takes the footer document's draft token from it. Nothing before
+  // this point, and nothing in a dry run after it, writes to the site.
+  let current;
   try {
-    await withRefusalGuidance(onProgress, "theme push", async () => {
-      // Re-read immediately before the concurrency-protected save and carry only
-      // the ten workspace color values across. Footer prose, links, and images
-      // always come from this fresh server document, never the pull snapshot.
-      const currentPublishing = await getSettingsGroup(
-        client,
-        siteId,
-        SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+    current = await withRefusalGuidance(onProgress, "theme push", async () => await getSitePresentation(client, siteId));
+  } catch (error) {
+    throw translateServerSupport(error, "read");
+  }
+  const stale = baseline !== undefined && baseline.revision !== current.revision;
+  // A save this workspace sent and never heard back from (TR00807). When the
+  // change set about to go is the same one, a moved revision is not evidence
+  // of a concurrent edit: it is what that save leaves behind when it
+  // committed. Replaying it under the baseline it was sent with lets the site
+  // answer already-current, or apply it if it never committed; anything else
+  // it refuses itself. A pending record for a different change set proves
+  // nothing about the site and takes the ordinary path.
+  const changeSet = buildChangeSet(validated);
+  const changeSetHash = computePresentationChangeSetHash(changeSet);
+  const pending = readPendingPresentationSave(appearanceContext.manifest);
+  const replayable = pending !== undefined && pending.changeSetHash === changeSetHash;
+  const replaying = stale && replayable;
+
+  if (dryRun) {
+    const differences = describeDifferences(validated, current);
+    const changed = differences.some((entry) => entry.paths.length > 0 || entry.truncated === true);
+    for (const entry of differences) {
+      if (entry.paths.length === 0 && entry.truncated !== true) continue;
+      onProgress(`${entry.file} differs at: ${entry.paths.join(", ")}${entry.truncated ? ", and more" : ""}.`);
+    }
+    if (!changed) onProgress("The workspace's presentation matches the site; a push would change nothing.");
+    if (baseline === undefined) {
+      onProgress("The pull manifest records no presentation baseline; a push would refuse until the workspace is re-pulled.");
+    } else if (replaying) {
+      onProgress(
+        `The site's presentation revision moved since this workspace was pulled (${baseline.revision} → `
+          + `${current.revision}), and the manifest records a save of this same change set whose response was `
+          + "lost; a push would replay it under its original baseline rather than refuse.",
       );
-      const currentFooter = currentPublishing.sitePublishingPreferences?.footerSettings ?? {};
-      const nextFooter = applyFooterColors(currentFooter, footerColors);
-      const footerResponse = await saveSiteFooterSettings(
-        client,
-        siteId,
-        nextFooter,
-        computeFooterDraftHash(currentFooter),
+    } else if (stale) {
+      onProgress(
+        `The site's presentation revision moved since this workspace was pulled (${baseline.revision} → `
+          + `${current.revision}); a push would be refused. Keep copies of the edited files, pull, and re-apply.`,
       );
-      written.push("footerSettings.light/dark colors");
-      if (!isPlainObject(footerResponse.footerSettings)) {
-        throw new SiteAuthoringError(
-          "api.footer_settings_contract",
-          "Taproot returned no normalized footer document after saving the color overlay.",
-          { field: "footerSettings" },
-        );
-      }
-      const savedFooter = footerResponse.footerSettings;
-      const projectedFooter = projectFooterSettingsForWorkspace(savedFooter);
-      await writeWorkspaceJson(
-        config.workspaceDir,
-        `${SETTINGS_DIRECTORY}/${SETTINGS_FILES[SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES]}`,
-        {
-          entityId: siteId,
-          settingsType: SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
-          settings: { ...publishing, footerSettings: projectedFooter },
+    }
+    onProgress("Dry run: nothing was written.");
+    return successResult(VERB_THEME_PUSH, siteId, {
+      dryRun: true,
+      revision: {
+        ...(baseline === undefined ? {} : { baseline: baseline.revision }),
+        current: current.revision,
+        stale: baseline === undefined ? undefined : stale,
+      },
+      ...(pending === undefined ? {} : {
+        pendingSave: {
+          ...(pending.startedAt === undefined ? {} : { startedAt: pending.startedAt }),
+          sameChangeSet: replayable,
         },
+      }),
+      changed,
+      differences,
+      warnings,
+    });
+  }
+
+  if (stale && !replaying) {
+    // Refused here, before any request that could write, with the same
+    // guidance the server's fence would give — and with the paths that
+    // differ, which the server cannot know.
+    if (pending !== undefined) {
+      onProgress(
+        "The manifest records an earlier save of a different change set whose response was lost; the site may hold "
+          + "it. The pull that refreshes the baseline shows what the site holds now.",
       );
-      await advanceFooterManifest(config.workspaceDir, siteId, projectedFooter);
-      onProgress("Saved the light and dark footer scheme colors over the current footer document.");
-
-      for (const operation of scalarOperations) {
-        await setSetting(client, siteId, operation.settingsType, operation.setting, operation.value);
-        written.push(`${operation.settingsType}.${operation.setting}`);
-        onProgress(`Saved ${operation.setting}.`);
-      }
-
-      // The pair is locally valid and complete before either mutation starts.
-      // These writes are last so the first one is also the point at which the
-      // server marks the theme externally managed and the visual editor adopts
-      // its guarded mode.
-      await setSetting(client, siteId, SETTINGS_TYPE_TAPROOT_STYLES, "lightTheme", themes.light);
-      written.push(`${SETTINGS_TYPE_TAPROOT_STYLES}.lightTheme`);
-      await setSetting(client, siteId, SETTINGS_TYPE_TAPROOT_STYLES, "darkTheme", themes.dark);
-      written.push(`${SETTINGS_TYPE_TAPROOT_STYLES}.darkTheme`);
-      onProgress("Saved both complete themes; Brand & Style now treats the color model as externally managed.");
+    }
+    const differences = describeDifferences(validated, current);
+    throw new SiteAuthoringError(
+      "theme.concurrent_modification",
+      `The site's presentation changed after this workspace was pulled (revision ${baseline.revision} → `
+        + `${current.revision}), so nothing was written. Keep copies of the edited settings files, run `
+        + "'taproot-site pull' to refresh the baseline, re-apply the edits, and push again; the paths below name "
+        + "where the workspace and the site now differ.",
+      { field: "revision", alternatives: differences.filter((entry) => entry.paths.length > 0).map((entry) => entry.file) },
+    ).withDifferences(differences.flatMap((entry) => entry.paths.map((path) => `${entry.file}:${path}`)));
+  }
+
+  const expectedRevision = replaying ? pending.expectedRevision : baseline.revision;
+  if (replaying) {
+    onProgress(
+      `Replaying the presentation save recorded${pending.startedAt === undefined ? "" : ` at ${pending.startedAt}`} `
+        + "whose response was lost, under the baseline it was sent with: a save that committed is answered as "
+        + "already current and nothing is applied twice; one that did not commit is applied.",
+    );
+  }
+  // Recorded before the request so a lost response leaves a record the next
+  // run can replay; the manifest write that follows an answer replaces it.
+  if (pending?.expectedRevision !== expectedRevision || pending.changeSetHash !== changeSetHash) {
+    await recordPendingPresentationSave(config.workspaceDir, siteId, {
+      expectedRevision,
+      changeSetHash,
+      startedAt: new Date(session.now()).toISOString(),
     });
+  }
+
+  // The footer token comes from the read just made: the server overlays the
+  // colours onto the document it holds now. On a replay of a committed save
+  // the site is already current and the token is not consulted.
+  const currentFooter = current.sitePublishingPreferences?.footerSettings ?? {};
+  let saved;
+  try {
+    saved = await withRefusalGuidance(onProgress, "theme push", async () =>
+      await saveSitePresentation(client, siteId, {
+        expectedRevision,
+        expectedFooterDraftHash: computeFooterDraftHash(currentFooter),
+        ...changeSet,
+      }));
   } catch (error) {
-    if (error instanceof SiteAuthoringError && written.length > 0) {
-      throw error.withCompletedWrites(written);
+    if (error instanceof SiteAuthoringError && error.code === "transport.mutation_ambiguous") {
+      onProgress(
+        "The save ended without an authoritative response and is recorded as pending. Run 'taproot-site theme "
+          + "push' again with the same settings files: a save that committed is answered as already current and "
+          + "nothing is applied twice; one that did not is applied.",
+      );
+      throw translateSaveRefusal(error);
     }
-    throw error;
+    // Only a fence refusal proves nothing committed; it drops the pending
+    // record so a later run compares against the site rather than replaying
+    // under a baseline the site already judged. Any other error keeps it: the
+    // server commits the presentation before it derives favicon renditions,
+    // so an error answered after that commit has moved the revision, and the
+    // record is what lets the next run of the same change set be answered as
+    // already current instead of refused as someone else's edit.
+    if (error instanceof ApiError && (error.hasField("ExpectedRevision") || error.hasField("ExpectedFooterDraftHash"))) {
+      await clearPendingPresentationSave(config.workspaceDir, siteId);
+    } else {
+      onProgress(
+        "The save was answered with an error after it may have committed; it stays recorded as pending, and running "
+          + "'taproot-site theme push' again with the same settings files settles it either way.",
+      );
+    }
+    throw translateSaveRefusal(error);
+  }
+
+  const { presentation, applied } = saved;
+  const savedFooter = presentation.sitePublishingPreferences?.footerSettings;
+  if (!isPlainObject(savedFooter)) {
+    throw new SiteAuthoringError(
+      "api.footer_settings_contract",
+      "Taproot returned no footer document with the saved presentation.",
+      { field: "footerSettings" },
+    );
   }
+  // The publishing document is rewritten from the site's copy — footer prose,
+  // links and imagery always come from there — and both baselines advance
+  // from the same response. Committed remotely before either local write, so
+  // a failure here leaves a stale baseline that refuses the next push rather
+  // than one that overwrites the save.
+  const projectedFooter = projectFooterSettingsForWorkspace(savedFooter);
+  await writeWorkspaceJson(
+    config.workspaceDir,
+    `${SETTINGS_DIRECTORY}/${SETTINGS_FILES[SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES]}`,
+    {
+      entityId: siteId,
+      settingsType: SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+      settings: { ...publishing, footerSettings: projectedFooter },
+    },
+  );
+  await advanceFooterManifest(config.workspaceDir, siteId, projectedFooter, undefined, {
+    presentationRevision: presentation.revision,
+  });
+  onProgress(
+    applied
+      ? "Saved the complete presentation in one transaction: footer scheme colors, appearance settings, and both "
+        + "themes; Brand & Style now treats the color model as externally managed."
+      : "The site already held this presentation; nothing was written and the baseline was refreshed.",
+  );
 
+  const written = [
+    "footerSettings.light/dark colors",
+    ...scalarOperations.map((operation) => `${operation.settingsType}.${operation.setting}`),
+    ...THEME_SETTINGS.map((setting) => `${SETTINGS_TYPE_TAPROOT_STYLES}.${setting}`),
+  ];
   return successResult(VERB_THEME_PUSH, siteId, {
+    applied,
+    revision: presentation.revision,
     written: boundedList(written, 100),
-    warnings: {
-      items: themes.warnings,
-      count: themes.warningCount,
-      ...(themes.warningsTruncated ? { truncated: true } : {}),
-    },
+    warnings,
   });
 }