primitive-admin 1.2.0-alpha.5 → 1.2.0-alpha.7

package/dist/src/commands/sync.js

@@ -13,6 +13,9 @@ import { parseMetadataCategoryToml, validateMetadataCategoryConfig, serializeMet
 import { isPlatformOwnedWorkflow, isPlatformOwnedWorkflowKey, } from "../lib/platform-owned.js";
 import { getCurrentAppId, getServerUrl } from "../lib/config.js";
 import { requireCurrentEnvironment } from "../lib/env-resolver.js";
+import { ensureFileIgnored } from "../lib/local-state.js";
+import { PROJECT_TREE_DIR } from "../lib/env-resolver-core.js";
+import { cachedVarsNote, layerVars, planVarsOverridePull, varsOverridePath as resolveVarsOverridePath, varsOverrideSummaryLine, VARS_OVERRIDE_GITIGNORE_PATTERN, } from "../lib/vars-override.js";
 import { resolveSyncDir, resolveSnapshotsRoot, resolveSyncStateReadPath, resolveSyncStateWritePath, SYNC_STATE_FILENAME, checkLegacyDatabaseTypesDir, } from "../lib/sync-paths.js";
 import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, collectWorkflowTomlNotes, formatWorkflowTomlErrors, validateWorkflowExpressionsToml, validateWorkflowExpressionsRawToml, } from "../lib/workflow-toml-validator.js";
@@ -48,6 +51,9 @@ import { AGENT_TEST_CASE_FIELDS, resolveAgentTestCase, } from "../lib/generated-
 // #3799 — the meaning-preserving schema translation, vendored the same way, so
 // the preflight refuses exactly the schemas the admin routes refuse.
 import { agentSchemaTranslationRefusals } from "../lib/generated-config-surfaces.js";
+// #4441 — the rule for a change to a function an agent uses, vendored the same
+// way, so the preflight refuses exactly the changes the function routes refuse.
+import { agentFunctionChangeRefusals, agentFunctionUses, } from "../lib/generated-config-surfaces.js";
 // #3801 — the strict-output rule, vendored the same way, so the preflight
 // refuses exactly the strict configs the admin routes refuse.
 import { resolvePromptStrictOutput } from "../lib/generated-config-surfaces.js";
@@ -82,6 +88,8 @@ export { resolveSlugCollisions, slugifyTestCaseName, testCaseFileBasenames, } fr
 import { success, error, printApiError, info, warn, keyValue, json, divider, } from "../lib/output.js";
 import { filterFilesBySelection, parseSyncSelectors, SelectorError, selectionIncludesKey, selectionIncludesType, selectionIncludesApp, selectionIncludesAnyVar, trackedSelectorKeys, unmatchedSelectors, } from "../lib/sync-selectors.js";
 import { confirmPrompt, ConfirmPromptError } from "../lib/confirm-prompt.js";
+import { pushFailureIsTransient, writePushFailureReport } from "../lib/push-failure-report.js";
+import { isTransientRequestFailure } from "../lib/transient-retry.js";
 import { signingSecretStatusWarning, signingSecretHealthWarning, previousSigningSecretWarning, } from "../lib/signing-secret-status.js";
 import chalk from "chalk";
 function ensureDir(dirPath) {
@@ -152,7 +160,7 @@ export function wrapEntityError(err, action, kind, key) {
         return new ApiError(wrappedMessage, err.statusCode, err.code, err.details);
     }
     // Non-ApiError (e.g. network failure, JSON parse error) — preserve cause.
-    const wrapped = new Error(wrappedMessage);
+    const wrapped = new Error(wrappedMessage, { cause: err });
     return wrapped;
 }
 /**
@@ -570,6 +578,69 @@ export function planVarsPull(outcome, priorVars) {
     }
     return { write: true, content: serializeVars(outcome.vars), varEntities };
 }
+/**
+ * The var leg of `config pull` on a machine-local environment (#4485): the
+ * server's vars go into the environment's `vars.<name>.override.toml`, and
+ * `vars.toml` — the shared tree's, which merges to main — is never written.
+ * Each pulled key (every key, or `selectedKeys`) is resolved against
+ * `vars.toml` by `planVarsOverridePull`. The file is created only when a key
+ * ends up in it; an existing one is rewritten, possibly to its comment-only
+ * state. The baseline entries (`varEntities`) are filled exactly as a pull on
+ * a committed environment fills them. A failed fetch writes nothing and keeps
+ * the prior entries.
+ */
+function pullVarsIntoOverride(input) {
+    const { outcome, overridePath, configDir, env, selectedKeys, priorVars, varEntities } = input;
+    const overrideFile = basename(overridePath);
+    if (!outcome.ok) {
+        const fetchError = outcome.error;
+        Object.assign(varEntities, priorVars ?? {});
+        error(`  Skipped ${overrideFile} — failed to fetch config vars: ${fetchError?.message ?? fetchError}. ` +
+            `Left the existing ${overrideFile} untouched.`);
+        return;
+    }
+    const readTable = (path) => {
+        if (!existsSync(path))
+            return {};
+        try {
+            return parseConfigToml(readFileSync(path, "utf-8"));
+        }
+        catch (err) {
+            error(`  Skipped ${overrideFile} — could not parse ${basename(path)}: ${err?.message || String(err)}`);
+            return null;
+        }
+    };
+    const base = readTable(join(configDir, "vars.toml"));
+    const current = readTable(overridePath);
+    if (base === null || current === null) {
+        Object.assign(varEntities, priorVars ?? {});
+        return;
+    }
+    Object.assign(varEntities, selectedKeys
+        ? planScopedVarsPull(outcome.vars, selectedKeys, {}, priorVars).varEntities
+        : planVarsPull(outcome).varEntities);
+    const plan = planVarsOverridePull(outcome.vars, base, selectedKeys, current, env);
+    const keys = Object.keys(plan.vars).sort();
+    const exists = existsSync(overridePath);
+    if (!exists && keys.length === 0)
+        return;
+    if (!exists) {
+        const coverage = ensureFileIgnored(overridePath, { reason: "primitive config pull" });
+        if (coverage.status === "failed") {
+            warn(`  Could not confirm ${overrideFile} is git-ignored: ${coverage.detail}. ` +
+                `Add "${VARS_OVERRIDE_GITIGNORE_PATTERN}" to your .gitignore — the file is machine-local and must never be committed.`);
+        }
+    }
+    const written = writePulledFile(overridePath, plan.content, input.tally, sameTomlAs(plan.content));
+    if (written)
+        info(`  Wrote ${overrideFile} (${keys.length} var${keys.length === 1 ? "" : "s"})`);
+    if (keys.length > 0) {
+        info(`  ${varsOverrideSummaryLine(overrideFile, {
+            overridingKeys: keys.filter((key) => key in base),
+            addedKeys: keys.filter((key) => !(key in base)),
+        })}`);
+    }
+}
 /**
  * `config pull --only var/<KEY>` — the same plan, narrowed to the named keys
  * (issue #2645).
@@ -710,27 +781,28 @@ export function validateWebhookCapForPush(localKeys, remoteKeys) {
 export function validateVarsFile(parsedVars, options = {}) {
     const errors = [];
     const { onlyKeys } = options;
+    const fileName = options.fileName ?? "vars.toml";
     const keyCount = Object.keys(parsedVars).length;
-    if (!onlyKeys && keyCount > MAX_VARS_PER_APP) {
-        errors.push(`vars.toml declares ${keyCount} vars, exceeding the maximum of ${MAX_VARS_PER_APP} vars per app. Remove ${keyCount - MAX_VARS_PER_APP} entr${keyCount - MAX_VARS_PER_APP === 1 ? "y" : "ies"}.`);
+    if (!onlyKeys && !options.skipCountCap && keyCount > MAX_VARS_PER_APP) {
+        errors.push(`${fileName} declares ${keyCount} vars, exceeding the maximum of ${MAX_VARS_PER_APP} vars per app. Remove ${keyCount - MAX_VARS_PER_APP} entr${keyCount - MAX_VARS_PER_APP === 1 ? "y" : "ies"}.`);
     }
     for (const [key, rawValue] of Object.entries(parsedVars)) {
         if (onlyKeys && !onlyKeys.has(key))
             continue;
         if (!VARS_KEY_RE.test(key)) {
-            errors.push(`Invalid var key "${key}" in vars.toml: must match ^[A-Z][A-Z0-9_]{0,63}$ (uppercase letters, digits, underscores; start with a letter; max 64 chars)`);
+            errors.push(`Invalid var key "${key}" in ${fileName}: must match ^[A-Z][A-Z0-9_]{0,63}$ (uppercase letters, digits, underscores; start with a letter; max 64 chars)`);
             continue;
         }
         if (typeof rawValue !== "string") {
-            errors.push(`Var "${key}" in vars.toml must be a string value (got ${typeof rawValue}) — quote the value.`);
+            errors.push(`Var "${key}" in ${fileName} must be a string value (got ${typeof rawValue}) — quote the value.`);
             continue;
         }
         const byteLength = new TextEncoder().encode(rawValue).length;
         if (byteLength === 0) {
-            errors.push(`Var "${key}" in vars.toml must not be empty.`);
+            errors.push(`Var "${key}" in ${fileName} must not be empty.`);
         }
         else if (byteLength > MAX_VAR_VALUE_BYTES) {
-            errors.push(`Var "${key}" in vars.toml exceeds the maximum value size of ${MAX_VAR_VALUE_BYTES} bytes (got ${byteLength}).`);
+            errors.push(`Var "${key}" in ${fileName} exceeds the maximum value size of ${MAX_VAR_VALUE_BYTES} bytes (got ${byteLength}).`);
         }
     }
     return errors;
@@ -943,7 +1015,12 @@ export function countVarsAfterPush(remoteVars, plan) {
  * local value). Pure and side-effect-free so it's unit-testable without a live
  * server.
  */
-export function diffVars(localVars, remoteVars) {
+export function diffVars(localVars, remoteVars, 
+/**
+ * The file `config pull` would write a server value into — a machine-local
+ * environment's override file (#4485). Defaults to `vars.toml`.
+ */
+pullTargetFile = "vars.toml") {
     const rows = [];
     for (const [key, localValue] of localVars) {
         if (!remoteVars.has(key)) {
@@ -954,7 +1031,9 @@ export function diffVars(localVars, remoteVars) {
                 type: "var",
                 key,
                 status: "modified",
-                hint: "run `config pull` to rewrite vars.toml to match the server value",
+                hint: pullTargetFile === "vars.toml"
+                    ? "run `config pull` to rewrite vars.toml to match the server value"
+                    : `run \`config pull\` to write the server value into ${pullTargetFile}`,
             });
         }
         else {
@@ -2483,7 +2562,7 @@ function localConfigWithServerIdentity(label, local, server, file) {
  * that being a visible change to this signature.
  */
 export async function runConfigPushPreflight(input) {
-    const { configDir, resolvedAppId, pushSelection, syncState, force, isCrossAppPush, localEnvironment = false, client, } = input;
+    const { configDir, resolvedAppId, pushSelection, syncState, force, isCrossAppPush, localEnvironment = false, client, varsOverridePath = null, } = input;
     /**
      * Narrow a type's file list to the `--only` selection — the same one-line
      * closure the action holds, rebuilt from the selection it passed in rather
@@ -2627,7 +2706,9 @@ export async function runConfigPushPreflight(input) {
     const preflightVarsTomlPath = join(configDir, "vars.toml");
     const varsSelected = selectionIncludesAnyVar(pushSelection);
     let preflightParsedVars = null;
-    if (varsSelected && existsSync(preflightVarsTomlPath)) {
+    let varsOverrideKeys = null;
+    const overrideExists = !!varsOverridePath && existsSync(varsOverridePath);
+    if (varsSelected && existsSync(preflightVarsTomlPath) && !overrideExists) {
         try {
             const parsed = parseTomlFile(preflightVarsTomlPath);
             // #2645 — under `--only var/<key>` only the selected entries are
@@ -2645,6 +2726,49 @@ export async function runConfigPushPreflight(input) {
             preflightValidationErrors.push(`  vars.toml: ${err?.message || String(err)}`);
         }
     }
+    else if (varsSelected && overrideExists) {
+        // #4485 — a machine-local environment's own values, layered over
+        // vars.toml. Each file is validated under its own name, and the count
+        // cap is measured on the layered set: that is what the push sends.
+        const overrideFile = basename(varsOverridePath);
+        const onlyKeys = pushSelection ? pushSelection.varKeys : undefined;
+        const tables = [];
+        let parsedAll = true;
+        for (const [path, fileName] of [
+            [preflightVarsTomlPath, "vars.toml"],
+            [varsOverridePath, overrideFile],
+        ]) {
+            if (!existsSync(path)) {
+                tables.push(null);
+                continue;
+            }
+            try {
+                const parsed = parseTomlFile(path);
+                for (const e of validateVarsFile(parsed, { onlyKeys, fileName, skipCountCap: true })) {
+                    preflightValidationErrors.push(`  ${e}`);
+                }
+                tables.push(parsed);
+            }
+            catch (err) {
+                parsedAll = false;
+                preflightValidationErrors.push(`  ${fileName}: ${err?.message || String(err)}`);
+            }
+        }
+        if (parsedAll) {
+            const [base, override] = tables;
+            const layered = layerVars(base, override);
+            const count = Object.keys(layered).length;
+            if (!onlyKeys && count > MAX_VARS_PER_APP) {
+                preflightValidationErrors.push(`  vars.toml and ${overrideFile} layer to ${count} vars, exceeding the maximum of ${MAX_VARS_PER_APP} vars per app. Remove ${count - MAX_VARS_PER_APP} entr${count - MAX_VARS_PER_APP === 1 ? "y" : "ies"}.`);
+            }
+            const overrideKeys = Object.keys(override ?? {}).sort();
+            varsOverrideKeys = {
+                overridingKeys: overrideKeys.filter((key) => base !== null && key in base),
+                addedKeys: overrideKeys.filter((key) => base === null || !(key in base)),
+            };
+            preflightParsedVars = layered;
+        }
+    }
     // #3182 — a function's capabilities, checked against the author's own
     // file before anything is applied. The grammar is purely local (and
     // since #3279 it keeps three kinds: `integration:<key>`,
@@ -2740,6 +2864,20 @@ export async function runConfigPushPreflight(input) {
     // #3798 — the functions an agent's references are checked against, read
     // once and only when a selected prompt is an agent that names one.
     let agentFunctions = null;
+    // The app's functions, listed at most once for the #3798 and #4441 checks.
+    // `null` when the listing failed.
+    let liveFunctionRows;
+    const liveFunctionListing = async () => {
+        if (liveFunctionRows === undefined) {
+            try {
+                liveFunctionRows = (await client.listFunctions(resolvedAppId)).items;
+            }
+            catch {
+                liveFunctionRows = null;
+            }
+        }
+        return liveFunctionRows;
+    };
     if (existsSync(preflightPromptsDir)) {
         for (const file of selectFiles("prompt", preflightPromptsDir, readdirSync(preflightPromptsDir).filter((f) => f.endsWith(".toml")))) {
             const filePath = join(preflightPromptsDir, file);
@@ -2757,17 +2895,10 @@ export async function runConfigPushPreflight(input) {
             if (promptKindOf(tomlData?.prompt) === "agent" &&
                 agentDeclarationFunctionKeys(tomlData?.prompt?.agent).length > 0) {
                 if (!agentFunctions) {
-                    let live = null;
-                    try {
-                        live = (await client.listFunctions(resolvedAppId)).items;
-                    }
-                    catch {
-                        live = null;
-                    }
                     agentFunctions = agentFunctionFactsForPush({
                         configDir,
                         pushSelection,
-                        live,
+                        live: await liveFunctionListing(),
                     });
                 }
                 for (const message of promptAgentFunctionErrors(filePath, tomlData, agentFunctions)) {
@@ -2776,6 +2907,88 @@ export async function runConfigPushPreflight(input) {
             }
         }
     }
+    // #4441 — a function file this push CHANGES, checked against the live
+    // agents that use it: refused here when an agent the push does not select
+    // cannot take the change, and the agent files that must release a reference
+    // first are moved ahead of the functions leg. Lists the app's prompts only
+    // when a selected function file changes a live function.
+    let agentFilesFirst = [];
+    const preflightFunctionFilesDir = join(configDir, "functions");
+    const selectedFunctionFiles = [];
+    if (existsSync(preflightFunctionFilesDir)) {
+        for (const file of selectFiles("function", preflightFunctionFilesDir, readdirSync(preflightFunctionFilesDir).filter(isFunctionDeclarationFile))) {
+            let table;
+            try {
+                table = parseTomlFile(join(preflightFunctionFilesDir, file))?.function ?? {};
+            }
+            catch {
+                // Reported by the function preflight with its own message.
+                continue;
+            }
+            selectedFunctionFiles.push({ file, key: table.key || basename(file, ".toml") });
+        }
+    }
+    if (selectedFunctionFiles.length > 0) {
+        const liveRows = await liveFunctionListing();
+        const live = liveAgentFunctionFacts(liveRows);
+        const changed = functionChangePreflightKeys(selectedFunctionFiles, live);
+        if (liveRows === null) {
+            warn("The app's functions could not be listed, so the function files this " +
+                "push changes were not checked against the agents that use them. The " +
+                "server still refuses a change an agent cannot take.");
+        }
+        else if (changed.length > 0) {
+            let prompts = null;
+            const configsOf = new Map();
+            try {
+                prompts = await fetchAll((p) => client.listPrompts(resolvedAppId, p));
+                for (const agent of functionChangePreflightAgents(prompts, changed.map((entry) => entry.key))) {
+                    const { items } = await client.listPromptConfigs(resolvedAppId, agent.promptId);
+                    configsOf.set(agent.promptId, items.map((config) => ({
+                        configName: String(config?.configName ?? ""),
+                        provider: String(config?.provider ?? ""),
+                        status: String(config?.status ?? "active"),
+                    })));
+                }
+            }
+            catch {
+                prompts = null;
+            }
+            const selectedAgentFiles = [];
+            if (existsSync(preflightPromptsDir)) {
+                for (const file of selectFiles("prompt", preflightPromptsDir, readdirSync(preflightPromptsDir).filter((f) => f.endsWith(".toml")))) {
+                    let tomlData;
+                    try {
+                        tomlData = parseTomlFile(join(preflightPromptsDir, file));
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (promptKindOf(tomlData?.prompt) !== "agent")
+                        continue;
+                    selectedAgentFiles.push({
+                        file,
+                        promptKey: tomlData?.prompt?.key || basename(file, ".toml"),
+                        tomlData,
+                    });
+                }
+            }
+            const checked = functionChangePreflight({
+                selectedFunctionFiles,
+                live,
+                pushed: agentFunctionFactsForPush({ configDir, pushSelection, live: liveRows }).facts,
+                prompts,
+                configsOf,
+                selectedAgentFiles,
+            });
+            for (const message of checked.warnings)
+                warn(message);
+            for (const message of checked.errors) {
+                preflightValidationErrors.push(`  ${message}`);
+            }
+            agentFilesFirst = checked.agentFilesFirst;
+        }
+    }
     // #3798, #4262 — a prompt's sidecar against its prompt's kind: an agent's
     // case is checked by the agent test case's shape rule, and `[test.agent]`
     // on a chat or decisions prompt's case is refused, before any file is
@@ -2805,7 +3018,7 @@ export async function runConfigPushPreflight(input) {
         throw new Error(`Aborting push: ${preflightValidationErrors.length} TOML validation error(s) — no changes were applied.\n` +
             preflightValidationErrors.join("\n"));
     }
-    return { parsedVars: preflightParsedVars };
+    return { parsedVars: preflightParsedVars, agentFilesFirst, varsOverrideKeys };
 }
 /**
  * Every per-entity config file whose TOML `config push` would refuse (#2880
@@ -3037,21 +3250,9 @@ function declaresSchema(value) {
  * availability on every call).
  */
 export function agentFunctionFactsForPush(input) {
-    const facts = {};
-    for (const row of input.live ?? []) {
-        const key = String(row?.functionKey ?? "");
-        if (!key || row?.status === "archived")
-            continue;
-        facts[key] = {
-            hasInputSchema: declaresSchema(row.inputSchema),
-            hasOutputSchema: declaresSchema(row.outputSchema),
-            // #3799 — the schemas themselves, as stored (a JSON string from the API,
-            // an object from a tree file), so a server tool's two schemas can be
-            // translated for each of the agent's providers.
-            inputSchema: row.inputSchema,
-            outputSchema: row.outputSchema,
-        };
-    }
+    const facts = {
+        ...liveAgentFunctionFacts(input.live),
+    };
     const functionsDir = join(input.configDir, "functions");
     if (existsSync(functionsDir)) {
         for (const file of filterFilesBySelection(input.pushSelection, "function", functionsDir, readdirSync(functionsDir).filter(isFunctionDeclarationFile))) {
@@ -3076,6 +3277,196 @@ export function agentFunctionFactsForPush(input) {
     }
     return { facts, liveListed: input.live !== null };
 }
+/**
+ * The functions the app holds now, as the agent rules read them — #3798. A
+ * live row that is archived is a tombstone, not a function, so it is absent.
+ */
+export function liveAgentFunctionFacts(live) {
+    const facts = {};
+    for (const row of live ?? []) {
+        const key = String(row?.functionKey ?? "");
+        if (!key || row?.status === "archived")
+            continue;
+        facts[key] = {
+            hasInputSchema: declaresSchema(row.inputSchema),
+            hasOutputSchema: declaresSchema(row.outputSchema),
+            // #3799 — the schemas themselves, as stored (a JSON string from the API,
+            // an object from a tree file), so a server tool's two schemas can be
+            // translated for each of the agent's providers.
+            inputSchema: row.inputSchema,
+            outputSchema: row.outputSchema,
+        };
+    }
+    return facts;
+}
+/**
+ * The selected function files that CHANGE a live function — #4441. A file
+ * whose function is not live creates it, which no agent can depend on yet.
+ * The push lists the app's prompts only when this is non-empty.
+ */
+export function functionChangePreflightKeys(selectedFunctionFiles, live) {
+    return selectedFunctionFiles.filter((entry) => Object.prototype.hasOwnProperty.call(live, entry.key) && live[entry.key] != null);
+}
+/**
+ * The live, non-archived agent prompts that name at least one of `keys`.
+ * Whose configs the push reads for `functionChangePreflight`.
+ */
+export function functionChangePreflightAgents(prompts, keys) {
+    return prompts.filter((prompt) => promptKindOf(prompt) === "agent" &&
+        prompt.status !== "archived" &&
+        agentDeclarationFunctionKeys(prompt.agent).some((key) => keys.includes(key)));
+}
+/** `tool "lookup"` for a tool's name, the path itself for a hook. */
+function functionUseLabels(uses) {
+    return uses.map((use) => (use.includes(".") ? use : `tool "${use}"`)).join(", ");
+}
+/**
+ * Would a function change this push makes break a live agent? — #4441.
+ *
+ * The same rule the function routes run (`agentFunctionChangeRefusals`), so a
+ * change the preflight lets through is one the server accepts, run for every
+ * selected file that changes a live function against every live non-archived
+ * agent that names it, with every config of that agent:
+ *
+ *  - an agent whose prompt file this push does NOT select would be broken by
+ *    the change: a preflight error naming the function file, the agent and its
+ *    uses, and the remedy (change the agent in the same push, or retire it);
+ *  - an agent whose file IS selected keeps the existing order (applied after
+ *    the functions leg) unless its LIVE declaration would be broken by the
+ *    change. Then the file must go first to release the reference, which it
+ *    can only do when it is valid against the functions the app holds NOW —
+ *    its references, the providers of its non-archived configs, and the
+ *    providers of the configs the server still holds at its prompt PATCH. When it
+ *    is, it joins `agentFilesFirst`; when it is not, the push cannot be
+ *    ordered in one run and the error names the sequence that can.
+ *
+ * `prompts: null` (the listing failed) checks nothing and says so once; the
+ * server's refusal remains.
+ */
+export function functionChangePreflight(input) {
+    const result = {
+        errors: [],
+        warnings: [],
+        agentFilesFirst: [],
+    };
+    const changed = functionChangePreflightKeys(input.selectedFunctionFiles, input.live);
+    if (changed.length === 0)
+        return result;
+    if (input.prompts === null) {
+        result.warnings.push("The app's prompts could not be listed, so the function files this push " +
+            "changes were not checked against the agents that use them. The server " +
+            "still refuses a change an agent cannot take.");
+        return result;
+    }
+    const agents = functionChangePreflightAgents(input.prompts, changed.map((entry) => entry.key));
+    for (const agent of agents) {
+        const configs = input.configsOf.get(agent.promptId) ?? [];
+        const named = agentDeclarationFunctionKeys(agent.agent);
+        // Per changed function, so each refusal is attributed to its file.
+        const broken = [];
+        for (const entry of changed) {
+            if (!named.includes(entry.key))
+                continue;
+            const refusals = agentFunctionChangeRefusals({
+                declaration: agent.agent,
+                configs,
+                before: input.live,
+                after: { ...input.live, [entry.key]: input.pushed[entry.key] ?? null },
+            });
+            if (refusals.length > 0)
+                broken.push({ entry, refusals });
+        }
+        if (broken.length === 0)
+            continue;
+        const agentFile = input.selectedAgentFiles.find((candidate) => candidate.promptKey === agent.promptKey);
+        if (!agentFile) {
+            for (const { entry, refusals } of broken) {
+                result.errors.push(`functions/${entry.file}: agent "${agent.promptKey}" ` +
+                    `(prompts/${agent.promptKey}.toml, not in this push) uses function ` +
+                    `"${entry.key}" as ${functionUseLabels(agentFunctionUses(agent.agent, entry.key))}, ` +
+                    `and this change would break it: ` +
+                    `${refusals.map((refusal) => refusal.message).join("; ")}. Change the ` +
+                    "agent in this same push so it no longer needs what the change " +
+                    "removes, or retire the agent.");
+            }
+            continue;
+        }
+        // The file must go first. Can it, against the functions the app holds now?
+        // Its prompt PATCH is checked against the configs the server still holds
+        // at that moment (CSO-4441-001): every non-archived one except those the
+        // file retires, which the apply stages ahead of the PATCH. The file's own
+        // config writes follow the PATCH and are checked against its entries.
+        const fileAgent = agentFile.tomlData?.prompt?.agent;
+        const blockers = promptAgentFunctionRefusalsAgainst(agentFile.tomlData, input.live, heldAtPromptPatch(agentFile.tomlData, configs));
+        const blocking = broken.map(({ entry }) => `functions/${entry.file}`).join(", ");
+        if (blockers.length === 0) {
+            result.agentFilesFirst.push(agentFile.file);
+            continue;
+        }
+        const created = agentDeclarationFunctionKeys(fileAgent).filter((key) => input.live[key] == null && input.pushed[key] != null);
+        const lead = `prompts/${agentFile.file}: agent "${agent.promptKey}" must be applied ` +
+            `before ${blocking}, because its live declaration cannot take that ` +
+            "change";
+        if (created.length > 0) {
+            result.errors.push(`${lead}, but it names ${created.map((key) => `function "${key}"`).join(", ")}, ` +
+                "which this push creates. Push the new function first, then rerun " +
+                `this push: primitive config push --only ` +
+                `${created.map((key) => `function/${key}`).join(",")}`);
+        }
+        else {
+            result.errors.push(`${lead}, but it cannot be applied against the functions and configs ` +
+                `the app holds now: ${blockers.map((refusal) => refusal.message).join("; ")}. ` +
+                "Split the change: push the agent's change on its own first, without " +
+                "what the live functions and configs cannot satisfy, then rerun this push.");
+        }
+    }
+    return result;
+}
+/**
+ * The function refusals an agent prompt file owes against `functions`: a
+ * missing function or tool schema, and a server-tool schema one of the file's
+ * non-archived configs cannot carry. The file-decidable refusals are left to
+ * the collector that already reports them.
+ */
+function promptAgentFunctionRefusalsAgainst(tomlData, functions, heldConfigs = []) {
+    const agent = tomlData?.prompt?.agent;
+    const resolved = resolveAgentDeclaration({ kind: "agent", agent, functions });
+    const refusals = resolved.ok === false
+        ? resolved.refusals.filter((refusal) => refusal.code === "AGENT_TOOL_FUNCTION_MISSING" ||
+            refusal.code === "AGENT_TOOL_FUNCTION_SCHEMA_MISSING")
+        : [];
+    const seen = new Set();
+    for (const configs of [
+        promptFileConfigFacts(Array.isArray(tomlData?.configs) ? tomlData.configs : []),
+        [...heldConfigs],
+    ]) {
+        const fileDecidable = new Set(agentSchemaTranslationRefusals({ declaration: agent, configs }).map((refusal) => refusal.message));
+        for (const refusal of agentSchemaTranslationRefusals({
+            declaration: agent,
+            functions,
+            configs,
+        })) {
+            if (fileDecidable.has(refusal.message) || seen.has(refusal.message))
+                continue;
+            seen.add(refusal.message);
+            refusals.push(refusal);
+        }
+    }
+    return refusals;
+}
+/**
+ * The configs the server holds for an agent when a push's prompt PATCH
+ * reaches it — #4441 (CSO-4441-001): every non-archived one but those the
+ * file archives, which the apply stages ahead of the PATCH. Each keeps the
+ * provider it has NOW; the file's change to it is sent after the PATCH.
+ */
+function heldAtPromptPatch(tomlData, configs) {
+    const retired = new Set(promptFileConfigFacts(Array.isArray(tomlData?.configs) ? tomlData.configs : [])
+        .filter((entry) => entry.status.trim().toLowerCase() === "archived")
+        .map((entry) => entry.configName));
+    return configs.filter((config) => String(config.status ?? "active").trim().toLowerCase() !== "archived" &&
+        !retired.has(config.configName));
+}
 /**
  * The function half of an agent's declaration — #3798: every tool, turn
  * context and history function that the functions this push believes
@@ -3130,9 +3521,10 @@ export function promptAgentFunctionErrors(filePath, tomlData, known) {
  * server functions that must exist when it is created, and the push applies
  * prompts before functions, so agent files go AFTER the server-functions leg;
  * every other file keeps its place. A file that does not parse stays first, so
- * the leg reports it where it always has.
+ * the leg reports it where it always has. #4441 — the agent files in
+ * `agentFilesFirst` (`functionChangePreflight`) go before the leg instead.
  */
-export function partitionPromptFilesForPush(promptsDir, files) {
+export function partitionPromptFilesForPush(promptsDir, files, agentFilesFirst = []) {
     const beforeFunctions = [];
     const afterFunctions = [];
     for (const file of files) {
@@ -3144,7 +3536,11 @@ export function partitionPromptFilesForPush(promptsDir, files) {
             beforeFunctions.push(file);
             continue;
         }
-        (kind === "agent" ? afterFunctions : beforeFunctions).push(file);
+        // #4441 — an agent file the preflight found must release a function
+        // reference before the functions leg changes that function.
+        (kind === "agent" && !agentFilesFirst.includes(file)
+            ? afterFunctions
+            : beforeFunctions).push(file);
     }
     return { beforeFunctions, afterFunctions };
 }
@@ -6343,8 +6739,8 @@ export async function listAllTestCases(client, appId, blockType, blockId) {
         try {
             page = await client.listTestCases(appId, blockType, blockId, cursor ? { cursor } : {});
         }
-        catch {
-            return { ok: false };
+        catch (error) {
+            return { ok: false, error };
         }
         items.push(...(page.items || []));
         const next = page.nextCursor;
@@ -6821,6 +7217,7 @@ export async function pushTestCasesForBlock(params) {
     const testCaseExtra = { lookupMaps: params.lookupMaps };
     const listed = await listAllTestCases(client, appId, blockType, blockId);
     const liveOk = listed.ok;
+    const liveReadTransient = "error" in listed && isTransientRequestFailure(listed.error);
     if (!liveOk) {
         warn(`  ${blockKey} test cases: live state unavailable — falling back to last-sync content hashes`);
     }
@@ -7082,6 +7479,7 @@ export async function pushTestCasesForBlock(params) {
                             type: "test-case",
                             key: `${blockKey}/${slug}`,
                             message,
+                            transient: isTransientRequestFailure(err),
                         });
                     }
                     continue;
@@ -7129,7 +7527,7 @@ export async function pushTestCasesForBlock(params) {
                 continue;
             }
             if (degraded.action === "decline") {
-                params.declined?.("test-case", `${blockKey}/${slug}`, { action: "live-unavailable" }, existingEntry?.modifiedAt);
+                params.declined?.("test-case", `${blockKey}/${slug}`, { action: "live-unavailable", transient: liveReadTransient }, existingEntry?.modifiedAt);
                 continue;
             }
         }
@@ -7192,7 +7590,12 @@ export async function pushTestCasesForBlock(params) {
                 catch (err) {
                     const message = err?.message || String(err);
                     warn(`  Failed to update test case ${blockKey}/${slug}: ${message}`);
-                    failures.push({ type: "test-case", key: `${blockKey}/${slug}`, message });
+                    failures.push({
+                        type: "test-case",
+                        key: `${blockKey}/${slug}`,
+                        message,
+                        transient: isTransientRequestFailure(err),
+                    });
                     continue;
                 }
             }
@@ -7266,7 +7669,12 @@ export async function pushTestCasesForBlock(params) {
                         ? `${keyError} — rename ${file} to a path-safe file name`
                         : serverMessage;
                     warn(`  Failed to create test case ${blockKey}/${slug}: ${message}`);
-                    failures.push({ type: "test-case", key: `${blockKey}/${slug}`, message });
+                    failures.push({
+                        type: "test-case",
+                        key: `${blockKey}/${slug}`,
+                        message,
+                        transient: isTransientRequestFailure(err),
+                    });
                     continue;
                 }
             }
@@ -7310,6 +7718,7 @@ export async function pushTestCasesForBlock(params) {
                     type: "attachment",
                     key: `${blockKey}/${slug}/${filename}`,
                     message,
+                    transient: isTransientRequestFailure(err),
                 });
             }
         }
@@ -7881,7 +8290,7 @@ export async function applyTestCasePrune(params) {
         catch (err) {
             const message = err?.message || String(err);
             warn(`  Failed to delete attachment ${key}: ${message}`);
-            params.failures.push({ type: "attachment", key, message });
+            params.failures.push({ type: "attachment", key, message, transient: isTransientRequestFailure(err) });
         }
     }
     for (const candidate of params.candidates) {
@@ -7916,7 +8325,7 @@ export async function applyTestCasePrune(params) {
         catch (err) {
             const message = err?.message || String(err);
             warn(`  Failed to delete test case ${key}: ${message}`);
-            params.failures.push({ type: "test-case", key, message });
+            params.failures.push({ type: "test-case", key, message, transient: isTransientRequestFailure(err) });
         }
     }
     return { deleted, deletedAttachments };
@@ -8020,6 +8429,8 @@ export function registerConfigSyncCommands(sync) {
         const resolvedAppId = getCurrentAppId();
         const configDir = resolveSyncDir();
         const pullsLocalEnvironment = requireCurrentEnvironment().local;
+        // #4485 — null for a committed environment, which never reads one.
+        const pullVarsOverridePath = resolveVarsOverridePath(configDir, requireCurrentEnvironment());
         if (!options.json) {
             info(`Using per-environment config directory: ${configDir}`);
         }
@@ -8312,7 +8723,27 @@ export function registerConfigSyncCommands(sync) {
                 catch (varErr) {
                     varsOutcome = { ok: false, error: varErr };
                 }
-                if (pullSelection && varsOutcome.ok) {
+                if (pullVarsOverridePath) {
+                    // #4485 — a machine-local environment never writes vars.toml: the
+                    // tree's file is the parent's. Its own values land in its override.
+                    if (pullSelection && varsOutcome.ok) {
+                        for (const v of varsOutcome.vars) {
+                            if (pullSelection.varKeys.has(v.key))
+                                matchedSelectors.add(`var/${v.key}`);
+                        }
+                    }
+                    pullVarsIntoOverride({
+                        outcome: varsOutcome,
+                        overridePath: pullVarsOverridePath,
+                        configDir,
+                        env: requireCurrentEnvironment(),
+                        selectedKeys: pullSelection ? pullSelection.varKeys : null,
+                        priorVars: priorEntities.vars,
+                        varEntities,
+                        tally: pullWrites,
+                    });
+                }
+                else if (pullSelection && varsOutcome.ok) {
                     // Scoped: merge the named keys into the file that is already there
                     // rather than re-emitting the whole var surface.
                     for (const v of varsOutcome.vars) {
@@ -9403,6 +9834,9 @@ What a push guarantees (two stages):
         // tree, so `[app].name` in it is that environment's name: never sent,
         // never compared, never hashed into this environment's baseline.
         const localEnvironment = requireCurrentEnvironment().local;
+        // #4485 — a machine-local environment's own var values, layered over
+        // vars.toml. Null for a committed environment, which never reads one.
+        const pushVarsOverridePath = resolveVarsOverridePath(configDir, requireCurrentEnvironment());
         // Detect cross-app push: if pushing to a different app, clear entity IDs
         // so everything goes through the create path
         const isCrossAppPush = syncState && syncState.appId !== resolvedAppId;
@@ -9432,7 +9866,7 @@ What a push guarantees (two stages):
         // cross-app reset has to have happened first: it clears the entity ids, so
         // there is nothing for prune to retire and a removed key IS a typo again.
         if (pushSelection) {
-            const missing = unmatchedSelectors(pushSelection, configDir, trackedSelectorKeys(syncState, { prune: !!options.prune }));
+            const missing = unmatchedSelectors(pushSelection, configDir, trackedSelectorKeys(syncState, { prune: !!options.prune }), pushVarsOverridePath);
             if (missing.length > 0) {
                 error(`No local file declares: ${missing.join(", ")}. Run 'primitive config pull', or 'primitive config create <type> <key>' to create one.`);
                 process.exit(1);
@@ -9452,6 +9886,11 @@ What a push guarantees (two stages):
         try {
             const changes = [];
             let skippedCount = 0;
+            let functionsWithUnchangedCode = 0;
+            // #4485 — functions whose code axis this push evaluated; any other
+            // function the server holds (left out by `--only`, or not in the tree)
+            // also keeps its version, and with it the vars it has cached.
+            const functionKeysEvaluated = new Set();
             const conflicts = [];
             // Issue #666: per-class buckets for schema-feature errors. Each entry
             // groups failures by the code so the end-of-run report can print
@@ -9636,7 +10075,13 @@ What a push guarantees (two stages):
              * never an unconditional write — with the type named so the operator
              * knows drift detection was not in force for it this run.
              */
+            /** Whether each live read that failed this run was transient (#4491). */
+            const liveReadFailures = [];
             const warnLiveUnavailable = (label, reason) => {
+                // A string reason names a consequence ("rule sets unavailable") of a
+                // read already recorded here.
+                if (typeof reason !== "string")
+                    liveReadFailures.push(isTransientRequestFailure(reason));
                 const message = reason instanceof Error ? reason.message : String(reason ?? "unknown");
                 warn(`  ${label}: live state unavailable (${message}) — falling back to last-sync content hashes`);
             };
@@ -9654,6 +10099,11 @@ What a push guarantees (two stages):
                     applyFailures.push({
                         type,
                         key,
+                        // A rerun can read what this one could not only when the failed
+                        // read was transient; a decliner that does not say which read
+                        // failed is judged by every read that failed this run.
+                        transient: outcome.transient ??
+                            (liveReadFailures.length > 0 && liveReadFailures.every(Boolean)),
                         message: "live state could not be read and the manifest holds no " +
                             "last-sync content hash for this file, so push cannot tell " +
                             "which side moved. Nothing was written. Run `config pull` to " +
@@ -9831,7 +10281,7 @@ What a push guarantees (two stages):
             // proved to be reached from it before anything below mutates. Nothing
             // about what it checks, the order it checks it, or what it prints
             // moved with it.
-            const { parsedVars: preflightParsedVars } = await runConfigPushPreflight({
+            const { parsedVars: preflightParsedVars, agentFilesFirst: preflightAgentFilesFirst, varsOverrideKeys, } = await runConfigPushPreflight({
                 configDir,
                 resolvedAppId,
                 pushSelection,
@@ -9840,7 +10290,12 @@ What a push guarantees (two stages):
                 isCrossAppPush: !!isCrossAppPush,
                 localEnvironment,
                 client,
+                varsOverridePath: pushVarsOverridePath,
             });
+            const varsOverrideFile = varsOverrideKeys && pushVarsOverridePath ? basename(pushVarsOverridePath) : null;
+            if (varsOverrideKeys && varsOverrideFile) {
+                info(varsOverrideSummaryLine(varsOverrideFile, varsOverrideKeys));
+            }
             // Re-derived, not returned: both are one-line functions of inputs the
             // entry point already took, and widening its return type to carry them
             // would make the vars apply leg depend on the preflight's internals.
@@ -9864,7 +10319,7 @@ What a push guarantees (two stages):
             // is a network call whose failure aborts the push, so making it for a
             // singleton nobody selected would let `--only workflow/x` fail over
             // vars.toml.
-            if (varsSelected && existsSync(preflightVarsTomlPath)) {
+            if (varsSelected && (existsSync(preflightVarsTomlPath) || varsOverrideFile)) {
                 try {
                     remoteVarsSnapshot = await client.listAppConfigVars(resolvedAppId);
                 }
@@ -9873,7 +10328,7 @@ What a push guarantees (two stages):
                         throw new Error(`Aborting push: could not fetch remote config vars to check for ` +
                             `concurrent edits (${err?.message || String(err)}) — no changes ` +
                             `were applied. Re-run with --force to push without the ` +
-                            `concurrency guard.`);
+                            `concurrency guard.`, { cause: err });
                     }
                     // --force: proceed without a snapshot; the guard is intentionally
                     // bypassed and every local var is upserted as authoritative. The
@@ -9922,11 +10377,13 @@ What a push guarantees (two stages):
                     const localKeys = new Set(Object.keys(preflightParsedVars));
                     const plannedDeletes = new Set(varPlan.deletions);
                     const remoteOnlyCount = remoteVarsSnapshot.filter((r) => !localKeys.has(r.key) && !plannedDeletes.has(r.key)).length;
+                    const pullTarget = varsOverrideFile ?? "vars.toml";
+                    const localFiles = varsOverrideFile ? `vars.toml or ${varsOverrideFile}` : "vars.toml";
                     throw new Error(`Aborting push: it would leave ${finalVarCount} config vars on the server, ` +
                         `exceeding the maximum of ${MAX_VARS_PER_APP} vars per app ` +
                         `(server has ${remoteVarsSnapshot.length} vars, ${remoteOnlyCount} of ` +
-                        `which are not in vars.toml) — no changes were applied. Run ` +
-                        `\`config pull\` to bring the remote-only vars into vars.toml, or ` +
+                        `which are not in ${localFiles}) — no changes were applied. Run ` +
+                        `\`config pull\` to bring the remote-only vars into ${pullTarget}, or ` +
                         `delete unneeded vars, then push again.`);
                 }
             }
@@ -10203,6 +10660,7 @@ What a push guarantees (two stages):
             // r-2 P1), and the plan itself was computed up-front so the final
             // server var count could be validated against the cap before any
             // mutation (review pass 5).
+            const changedExistingVarKeys = [];
             if (varPlan) {
                 skippedCount += varPlan.skippedCount;
                 // Feed var conflicts into the shared accumulator — same convention as
@@ -10305,6 +10763,12 @@ What a push guarantees (two stages):
                                     contentHash: item.valueHash,
                                 };
                             }
+                            // #4485 — a var that already existed and now holds another
+                            // value, for the cached-vars note after the function leg.
+                            const before = remoteVarsSnapshot.find((r) => r.key === item.key);
+                            if (before && before.value !== item.value) {
+                                changedExistingVarKeys.push(item.key);
+                            }
                         }
                         catch (err) {
                             // A remote edit landed since our snapshot — report a conflict
@@ -12276,7 +12740,7 @@ What a push guarantees (two stages):
             let deferredAgentPromptFiles = [];
             if (existsSync(promptsDir)) {
                 const files = selectFiles("prompt", promptsDir, readdirSync(promptsDir).filter((f) => f.endsWith(".toml")));
-                const ordered = partitionPromptFilesForPush(promptsDir, files);
+                const ordered = partitionPromptFilesForPush(promptsDir, files, preflightAgentFilesFirst);
                 deferredAgentPromptFiles = ordered.afterFunctions;
                 await pushPromptFiles(ordered.beforeFunctions);
             }
@@ -13361,7 +13825,9 @@ What a push guarantees (two stages):
                             typeGateBlocked = true;
                         }
                         else {
-                            throw wrapEntityError(err, "update", "database type", dbType);
+                            // A fresh type's failure here is its create dry-run's, so it
+                            // is named a create, as the apply path names it.
+                            throw wrapEntityError(err, typeExistsOnServer ? "update" : "create", "database type", dbType);
                         }
                     }
                     // If the validate pass found a gate failure, record the change
@@ -13933,6 +14399,11 @@ What a push guarantees (two stages):
                     const codeUnchanged = !!liveFunction &&
                         !!activeVersion &&
                         String(activeVersion.envelopeHash ?? "") === push.envelopeHash;
+                    // #4485 — the server makes no new version of it, so a running one
+                    // keeps the vars it has cached.
+                    functionKeysEvaluated.add(key);
+                    if (codeUnchanged)
+                        functionsWithUnchangedCode++;
                     if (headerAction === "skip" && codeUnchanged) {
                         skippedCount++;
                         if (syncState && liveFunction?.functionId) {
@@ -14015,6 +14486,7 @@ What a push guarantees (two stages):
                             type: "function",
                             key,
                             message: String(err?.message ?? err),
+                            transient: isTransientRequestFailure(err),
                         });
                         // A refused create, or a refused push to a row the server does
                         // not hold live (an archived tombstone). A row this push created
@@ -14847,6 +15319,7 @@ What a push guarantees (two stages):
                                     type: "email-template",
                                     key: emailType,
                                     message: err?.message || String(err),
+                                    transient: isTransientRequestFailure(err),
                                 });
                             }
                         }
@@ -15284,6 +15757,27 @@ What a push guarantees (two stages):
                     }
                 }
             }
+            // #4485 (D4485-001) — an override changed a var some unchanged
+            // function may already have read and cached. Informational only.
+            if (varsOverrideFile && !options.dryRun && changedExistingVarKeys.length > 0) {
+                let functionsKeepingVersion = functionsWithUnchangedCode;
+                try {
+                    const listed = await client.listFunctions(resolvedAppId);
+                    for (const f of (listed?.items ?? [])) {
+                        if (f?.functionKey &&
+                            String(f.status ?? "active") !== "archived" &&
+                            !functionKeysEvaluated.has(f.functionKey)) {
+                            functionsKeepingVersion++;
+                        }
+                    }
+                }
+                catch {
+                    // Informational only: without the list, count what was evaluated.
+                }
+                const note = cachedVarsNote(changedExistingVarKeys, functionsKeepingVersion);
+                if (note)
+                    warn(note);
+            }
             divider();
             // Issue #813: a gate failure surfaced by the validate-first pass (which
             // also runs in dry-run mode via the server's dry-run gate endpoints).
@@ -15362,6 +15856,17 @@ What a push guarantees (two stages):
                 else {
                     error(failureSummary);
                 }
+                writePushFailureReport(pushFailureIsTransient({
+                    applyFailures,
+                    conflicts: conflicts.length,
+                    blockedDatabaseTypes: blockedDatabaseTypes.length,
+                    schemaErrors: schemaErrors.schemaRequired.length +
+                        schemaErrors.opRefs.length +
+                        schemaErrors.schemaBreaks.length +
+                        schemaErrors.uncheckableOps.length +
+                        schemaErrors.tomlParse.length +
+                        schemaErrors.opsExist.length,
+                }));
                 process.exit(1);
             }
             else {
@@ -15402,6 +15907,7 @@ What a push guarantees (two stages):
             // Print message + structured server-side validation details
             // (issue #684; now via the shared #1173 helper).
             printApiError(err);
+            writePushFailureReport(isTransientRequestFailure(err));
             process.exit(1);
         }
     });
@@ -15824,6 +16330,36 @@ What a push guarantees (two stages):
                         localVars.set(key, rawValue);
                 }
             }
+            // #4485 — on a machine-local environment, its own override layered
+            // over vars.toml: the values its push would send.
+            const diffEnv = requireCurrentEnvironment();
+            const diffVarsOverridePath = resolveVarsOverridePath(configDir, diffEnv);
+            let diffVarsOverride = null;
+            if (diffVarsOverridePath && existsSync(diffVarsOverridePath)) {
+                const parsed = parseTomlFile(diffVarsOverridePath);
+                const baseKeys = new Set(existsSync(varsTomlPathDiff)
+                    ? Object.keys(parseTomlFile(varsTomlPathDiff))
+                    : []);
+                const keys = Object.keys(parsed).sort();
+                const overridingKeys = keys.filter((key) => baseKeys.has(key));
+                const addedKeys = keys.filter((key) => !baseKeys.has(key));
+                if (varsOutcomeDiff.ok) {
+                    for (const [key, rawValue] of Object.entries(parsed)) {
+                        if (typeof rawValue === "string")
+                            localVars.set(key, rawValue);
+                    }
+                }
+                diffVarsOverride = {
+                    file: [PROJECT_TREE_DIR, diffEnv.tree, basename(diffVarsOverridePath)].join("/"),
+                    keys,
+                };
+                if (!options.json) {
+                    info(varsOverrideSummaryLine(basename(diffVarsOverridePath), {
+                        overridingKeys,
+                        addedKeys,
+                    }));
+                }
+            }
             // Compare
             let differences = [];
             // Issue #1659: a local file with no server entity means one of two very
@@ -16384,7 +16920,9 @@ What a push guarantees (two stages):
                 }
             }
             // Config vars — issue #1423 (see `diffVars`).
-            for (const row of diffVars(localVars, remoteVars)) {
+            for (const row of diffVars(localVars, remoteVars, 
+            // A child's pull writes its override, created or not (#4485).
+            diffVarsOverridePath ? basename(diffVarsOverridePath) : "vars.toml")) {
                 differences.push(row);
             }
             // Database-config types (issue #1485). rule-sets, group/collection-type
@@ -16647,6 +17185,7 @@ What a push guarantees (two stages):
                     differences,
                     testCases: testCaseDiffs,
                     notCompared,
+                    ...(diffVarsOverride ? { varsOverride: diffVarsOverride } : {}),
                 }, null, 2));
                 return;
             }