primitive-admin 1.2.0-alpha.0 → 1.2.0-alpha.2

package/dist/src/commands/sync.js

@@ -13,7 +13,8 @@ import { parseMetadataCategoryToml, validateMetadataCategoryConfig, serializeMet
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { isPlatformOwnedWorkflow, isPlatformOwnedWorkflowKey, } from "../lib/platform-owned.js";
 import { getCurrentAppId, getServerUrl } from "../lib/config.js";
-import { resolveSyncDir, resolveSnapshotsRoot, syncStatePath, syncStateReadPath, SYNC_STATE_FILENAME, checkLegacyDatabaseTypesDir, } from "../lib/sync-paths.js";
+import { requireCurrentEnvironment } from "../lib/env-resolver.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";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
@@ -22,6 +23,7 @@ import { canonicalizeIntegrationRequestConfig } from "../lib/integration-request
 import { canonicalizeServerTextFields } from "../lib/server-text-normalization.js";
 import { canonicalJsonStringify } from "../lib/canonical-json.js";
 import { reconcileWorkflowIncludes } from "../lib/workflow-include-preserve.js";
+import { newPullWriteTally, writePulledFile, } from "../lib/pull-write.js";
 import { serializeSection, parseTomlToAppSettings, buildAppSettingsPayload, } from "../lib/app-settings-descriptor.js";
 import { collectAppSettingsPushErrors, writePulledAppSettings, diffAppSettings, appSettingsFieldDiffs, appSettingsNameExcluded, appSettingsNameExcludedForState, hashAppSettingsForDiff, } from "./sync-app-settings.js";
 import { applyWorkflowBody, legacyDraftSlotWarning } from "../lib/workflow-apply.js";
@@ -33,12 +35,12 @@ import { buildWorkflowPayloadFromToml, parseWorkflowExpressionsToml, } from "../
 // payload builder so the diff normalizer and the wire cannot disagree.
 import { WORKFLOW_MODEL_DEFAULTS } from "../lib/workflow-defaults.js";
 // #2644 — the one definition per configuration object, vendored from the server.
-import { BLOB_BUCKET_TABLE, COLLECTION_TYPE_CONFIG_TABLE, CRON_TRIGGER_TABLE, DATABASE_TYPE_TABLE, EMAIL_TEMPLATE_TABLE, GROUP_TYPE_CONFIG_TABLE, INTEGRATION_TABLE, METADATA_CATEGORY_CONFIG_TABLE, PROMPT_CONFIG_TABLE, PROMPT_TABLE, RULE_SET_TABLE, SERVER_FUNCTION_TABLE, TEST_CASE_SURFACE, TEST_CASE_TABLE, WEBHOOK_TABLE, WORKFLOW_TABLE, configDeclaredTypeErrors, fieldServerDefault, findMisshapenTables, findUnknownDocumentKeys, findUnknownGroupedTomlKeys, findUnknownServerKeys, findUnknownTomlKeys, misshapenTableMessage, retiredConfigKey, spellsDecimalNumber, unrecognizedPullKeysMessage, unrecognizedPushKeysMessage, unrecognizedPushTablesMessage, warnUnrecognizedServerKeys, } from "../lib/config-surface.js";
+import { BLOB_BUCKET_TABLE, COLLECTION_TYPE_CONFIG_TABLE, CRON_TRIGGER_TABLE, DATABASE_TYPE_TABLE, EMAIL_TEMPLATE_TABLE, GROUP_TYPE_CONFIG_TABLE, INTEGRATION_TABLE, METADATA_CATEGORY_CONFIG_TABLE, PROMPT_CONFIG_TABLE, PROMPT_TABLE, RULE_SET_TABLE, SERVER_FUNCTION_TABLE, TEST_CASE_SURFACE, TEST_CASE_TABLE, WEBHOOK_TABLE, WORKFLOW_TABLE, configDeclaredTypeErrors, fieldServerDefault, findMisshapenTables, findUnknownDocumentKeys, findUnknownGroupedTomlKeys, findUnknownServerKeys, findUnknownTomlKeys, misshapenTableMessage, retiredTomlKey, spellsDecimalNumber, unrecognizedPullKeysMessage, unrecognizedPushKeysMessage, unrecognizedPushTablesMessage, warnUnrecognizedServerKeys, } from "../lib/config-surface.js";
 import { buildPayloadFromToml, projectEntityToPayload, projectRecordToToml, tomlOwned, } from "../lib/config-payload.js";
 import { CONFIG_SURFACES, isEmptyForEmit, tomlGroupsOf, } from "../lib/generated-config-surfaces.js";
 // #3626 — the prompt KIND rule, vendored with the definitions so the CLI's
 // preflight refuses exactly what the admin routes refuse.
-import { hoistDeprecatedChatKeys, promptKindOf, resolvePromptKind, } from "../lib/generated-config-surfaces.js";
+import { promptKindOf, resolvePromptKind, } from "../lib/generated-config-surfaces.js";
 // #3798 — the `[prompt.agent]` declaration rule, vendored the same way.
 import { agentDeclarationFunctionKeys, agentTestCaseRefusal, resolveAgentDeclaration, } from "../lib/generated-config-surfaces.js";
 // #3799 — the meaning-preserving schema translation, vendored the same way, so
@@ -98,8 +100,13 @@ function printStaleInstanceWarning(updated) {
         warn(`  ${w.message}`);
     }
 }
-function loadSyncState(configDir) {
-    const syncFile = syncStateReadPath(configDir);
+/**
+ * The current environment's baseline. Every reader goes through
+ * `resolveSyncStateReadPath`, so a machine-local environment reads its own
+ * machine-local baseline and never the committed tree's (#4117).
+ */
+function loadSyncState() {
+    const syncFile = resolveSyncStateReadPath();
     if (!existsSync(syncFile)) {
         return null;
     }
@@ -110,8 +117,8 @@ function loadSyncState(configDir) {
         return null;
     }
 }
-function saveSyncState(configDir, state) {
-    const syncFile = syncStatePath(configDir);
+function saveSyncState(state) {
+    const syncFile = resolveSyncStateWritePath();
     writeFileSync(syncFile, JSON.stringify(state, null, 2));
 }
 /**
@@ -449,6 +456,30 @@ export function hashRemoteWorkflowForDiff(workflow, draft, configs, logger, opti
     const parsed = parseConfigToml(serialized);
     return hashWorkflowTomlForDiff(parsed, undefined, options);
 }
+/**
+ * Whether a workflow file already describes the workflow `remoteToml`
+ * serializes (#4160), by `config diff`'s comparison: the normalized hash, with
+ * activation compared only when the file names a configuration.
+ *
+ * Three shapes never match, because pull has work to do on them: a file with
+ * `[[include]]` fragments (`reconcileWorkflowIncludes` owns those), one still
+ * carrying the retired inline `[[configs]]` list, and any other file push
+ * refuses (`pullMustRewrite`).
+ */
+export function sameWorkflowAs(workflowKey, remoteToml) {
+    return (localContent) => {
+        const local = parseConfigToml(localContent);
+        if ("include" in local || "configs" in local)
+            return false;
+        if (pullMustRewrite("workflow", local))
+            return false;
+        const compareActivation = Boolean(authoredActiveConfigName(local));
+        return (hashWorkflowTomlForDiff(local, workflowKey, { compareActivation }) ===
+            hashWorkflowTomlForDiff(parseConfigToml(remoteToml), undefined, {
+                compareActivation,
+            }));
+    };
+}
 /**
  * Build the [auth] block of app.toml from server settings (pull direction).
  *
@@ -1600,20 +1631,32 @@ export function buildCronTriggerPushPayload(key, tomlData, { mode = "update" } =
     }
     return payload;
 }
-export function serializeBlobBucket(bucket, logger) {
+export function serializeBlobBucket(bucket, ruleSetIdToName = new Map(), logger) {
+    const file = `blob-buckets/${bucket?.bucketKey}.toml`;
     // #2644 — the `[bucket]` key set comes from the vendored definition.
-    warnUnrecognizedServerKeys(bucket, BLOB_BUCKET_TABLE, `blob-buckets/${bucket?.bucketKey}.toml`, logger);
+    warnUnrecognizedServerKeys(bucket, BLOB_BUCKET_TABLE, file, logger);
+    // #4116 — the rule set is written by NAME, which every app can resolve. An
+    // id the listing cannot name is reported and left out, never written: an id
+    // in the file is the spelling a copied tree cannot resolve (the #3998 rule).
+    const ruleSetName = bucket?.ruleSetId
+        ? ruleSetIdToName.get(bucket.ruleSetId)
+        : undefined;
+    if (bucket?.ruleSetId && !ruleSetName) {
+        logger?.(`${file}: rule set ${bucket.ruleSetId} is not in this app's rule-set listing; ` +
+            "no ruleSetName written (an orphaned or unlisted rule set denies access closed)");
+    }
     const data = {
         bucket: {
             key: bucket.bucketKey,
             ...projectRecordToToml(BLOB_BUCKET_TABLE, bucket, {
-                // #1020: `preset` is the honest key; a custom bucket carries ruleSetId
-                // instead. Omit preset for custom buckets (preset === "custom").
+                // #1020: `preset` is the honest key; a custom bucket carries its rule
+                // set instead. Omit preset for custom buckets (preset === "custom").
                 preset: (record) => record.preset && record.preset !== "custom"
                     ? record.preset
                     : record.ruleSetId
                         ? undefined
                         : record.preset,
+                ruleSetId: () => ruleSetName,
             }),
         },
     };
@@ -1624,13 +1667,80 @@ export function serializeBlobBucket(bucket, logger) {
     });
     return stringifyConfigToml(data);
 }
+/**
+ * The entity a `blob-buckets/<key>.toml` describes (#4116) — the parse
+ * `config push` builds its bodies from and `config diff` compares.
+ *
+ * Read in CREATE mode, so the immutable `ttlTier` stays nameable. The rule set
+ * is left as `_ruleSetName` for `resolveRuleSetReference`; the deprecated
+ * `ruleSetId` spelling is forwarded as the id it already is. A file carrying
+ * both is refused by the preflight (`blobBucketFileErrors`) before this runs.
+ *
+ * An omitted `name` stays omitted: the update leaves the server's name alone,
+ * and only the create body falls back to the key.
+ */
+export function parseBlobBucketToml(doc) {
+    const section = doc?.bucket ?? {};
+    const entity = dropUndefined({
+        bucketKey: section.key ?? "",
+        ...buildPayloadFromToml(BLOB_BUCKET_TABLE, section, {
+            mode: "create",
+            values: {
+                name: (value) => value || undefined,
+                description: tomlOwned,
+            },
+        }),
+    });
+    // The builder read the `ruleSetName` value onto the `ruleSetId` field.
+    delete entity.ruleSetId;
+    if (typeof section.ruleSetName === "string" && section.ruleSetName.trim() !== "") {
+        // Trimmed, as `applyRuleSetReference` does for the type configs.
+        entity._ruleSetName = section.ruleSetName.trim();
+    }
+    else if (typeof section.ruleSetId === "string" && section.ruleSetId !== "") {
+        entity.ruleSetId = section.ruleSetId;
+    }
+    return entity;
+}
+/**
+ * The advisory `config push` prints for a bucket file still naming its rule set
+ * by id (#4116). The key is deprecated, not retired: the file pushes.
+ */
+export function blobBucketDeprecatedKeyWarning(filePath, tomlData) {
+    const bucket = tomlData?.bucket;
+    if (!bucket || bucket.ruleSetId === undefined)
+        return null;
+    // Beside `ruleSetName` it is a refusal instead (`blobBucketFileErrors`).
+    if (bucket.ruleSetName !== undefined)
+        return null;
+    return (`${filePath}: bucket.ruleSetId is deprecated — a rule-set id belongs to one app, ` +
+        `so a copied tree cannot resolve it; write ruleSetName = "<name>" ` +
+        "(config pull rewrites the file). Retiring the key is a later change.");
+}
+/** A bucket file's own refusals, decided from the file alone (#4116). */
+export function blobBucketFileErrors(filePath, tomlData) {
+    const bucket = tomlData?.bucket;
+    if (bucket && bucket.ruleSetId !== undefined && bucket.ruleSetName !== undefined) {
+        return [`${filePath}: bucket.ruleSetId is set beside bucket.ruleSetName; keep ruleSetName`];
+    }
+    // The deprecated spelling is a TOML-only key, so the declared-type check
+    // reads only `ruleSetName`; the old key keeps the field's type under its
+    // own name, or a mistyped id would be dropped from the body unreported.
+    const field = BLOB_BUCKET_TABLE.fields.find((f) => f.field === "ruleSetId");
+    if (!field)
+        return [];
+    return configDeclaredTypeErrors(filePath, tomlData, {
+        ...BLOB_BUCKET_TABLE,
+        fields: [{ ...field, tomlKey: "ruleSetId" }],
+    });
+}
 /**
  * Build the PATCH payload for a blob-bucket update from local TOML.
  *
  * EXACT extraction of the inline builder shared by the existing-update and
  * 409-adopt branches — do NOT "clean up" the truthiness checks on the access
- * model. The server treats `preset` and `accessPolicy` as mutually exclusive,
- * only clears `ruleSetId` when a preset/accessPolicy is also present, and
+ * model. The server treats `preset` and `ruleSetId` as mutually exclusive,
+ * only clears `ruleSetId` when a preset is also present, and
  * refuses to leave a bucket with no access model or a blank name — so those
  * fields are not clearable. `bucketKey` and `ttlTier` are immutable and never
  * sent. Both call sites must go through this helper so their field sets never
@@ -1639,7 +1749,9 @@ export function serializeBlobBucket(bucket, logger) {
 export function buildBlobBucketUpdatePayload(bucket) {
     // The access model's truthiness checks are the SERVER's rule and stay
     // verbatim; the definition contributes the field list, not the semantics.
-    const updatePayload = buildPayloadFromToml(BLOB_BUCKET_TABLE, bucket, {
+    // #4116 — reads the parsed ENTITY (`parseBlobBucketToml`, its rule set
+    // resolved), whose field names are the wire keys.
+    const updatePayload = projectEntityToPayload(BLOB_BUCKET_TABLE, bucket, {
         mode: "update",
         values: {
             // A preset and a rule set are mutually exclusive per request, and a
@@ -1655,12 +1767,6 @@ export function buildBlobBucketUpdatePayload(bucket) {
             description: tomlOwned,
         },
     });
-    // `accessPolicy` is the pre-#1020 spelling of `preset`, declared in the
-    // definition's `tomlOnlyKeys`: an unmigrated file still pushes its access
-    // model, and the server takes at most one of the two.
-    if (!updatePayload.preset && bucket?.accessPolicy) {
-        updatePayload.accessPolicy = bucket.accessPolicy;
-    }
     for (const key of Object.keys(updatePayload)) {
         if (updatePayload[key] === undefined)
             delete updatePayload[key];
@@ -1743,7 +1849,8 @@ export function promptConfigPayload(tomlConfig, options = {}) {
         : { description: tomlConfig.description ?? null, ...shared };
 }
 /**
- * Build the POST body for a blob-bucket create from local TOML.
+ * Build the POST body for a blob-bucket create from the parsed entity
+ * (`parseBlobBucketToml`, its rule set resolved).
  *
  * `ttlTier` is here and absent from the update body because the definition says
  * so (`writableOn: ["create"]`) — the retention tier is fixed at creation.
@@ -1751,7 +1858,7 @@ export function promptConfigPayload(tomlConfig, options = {}) {
 export function buildBlobBucketCreatePayload(key, bucket) {
     const payload = {
         bucketKey: key,
-        ...buildPayloadFromToml(BLOB_BUCKET_TABLE, bucket, {
+        ...projectEntityToPayload(BLOB_BUCKET_TABLE, bucket, {
             mode: "create",
             values: {
                 name: (value) => value || key,
@@ -1761,9 +1868,6 @@ export function buildBlobBucketCreatePayload(key, bucket) {
             },
         }),
     };
-    if (!payload.preset && bucket?.accessPolicy) {
-        payload.accessPolicy = bucket.accessPolicy;
-    }
     for (const field of Object.keys(payload)) {
         if (payload[field] === undefined)
             delete payload[field];
@@ -2068,15 +2172,10 @@ export function buildPromptConfigPayload(tomlConfig, { mode = "update" } = {}) {
      * differ from the one the server has always received.
      */
     const tomlOwned = (value) => (create ? value : (value ?? null));
-    // #3626 §4 — the nine chat keys moved under `[configs.chat]`, and the flat
-    // spelling is accepted as DEPRECATED. Hoisting here rather than at each call
-    // site means push, `config diff` and the create-seed builder all read a file
-    // the same way, so an unmigrated file and its pulled rewrite compare Synced.
-    // A key set BOTH ways is refused in preflight
-    // (`promptDeprecatedChatKeyErrors`); the hoist leaves the grouped value
-    // standing so nothing here has to guess.
-    const entry = hoistDeprecatedChatKeys(tomlConfig).entry;
-    return buildPayloadFromToml(PROMPT_CONFIG_TABLE, entry, {
+    // #3626 — the chat keys are read from `[configs.chat]` only. Their flat
+    // spelling is retired (#3642) and refused in preflight, so a root chat key
+    // never reaches this builder as a value.
+    return buildPayloadFromToml(PROMPT_CONFIG_TABLE, tomlConfig, {
         mode,
         values: {
             provider: (value) => (create ? value || "openrouter" : value),
@@ -2202,16 +2301,19 @@ export function configUnknownKeyError(filePath, tomlData, table) {
     // once beside the definitions (`src/config-surface/retired-keys.ts`), not the
     // generic "check the spelling, or upgrade the CLI" hint, which is exactly
     // backwards for it. The server's create/update handlers read the same table.
+    // #3642 — a spelling retired from TOML only (a flat chat key under
+    // `[[configs]]`) is answered from the same module, before the misplaced-key
+    // line below could send the author to the block without saying why.
     const prefix = table.tomlPath.join(".");
     const retiredHere = [...unknown]
-        .filter((k) => retiredConfigKey(prefix, k))
+        .filter((k) => retiredTomlKey(prefix, k))
         .sort();
     const trulyUnknown = [...unknown]
-        .filter((k) => !retiredConfigKey(prefix, k))
+        .filter((k) => !retiredTomlKey(prefix, k))
         .sort();
     const messages = [];
     for (const key of retiredHere) {
-        messages.push(`${filePath}: ${prefix}.${key} — ${retiredConfigKey(prefix, key).toml}`);
+        messages.push(`${filePath}: ${prefix}.${key} — ${retiredTomlKey(prefix, key).toml}`);
     }
     // #3626, SO3626-013 — a key the definition DOES declare, written at the
     // table root when it is authored under a group. Before grouping,
@@ -2309,49 +2411,72 @@ export function unknownKeyPreflightTargets() {
  */
 function localConfigRowKey(label, tomlData, file) {
     const fallback = basename(file, ".toml");
-    const stated = (table, key) => tomlData?.[table]?.[key] || fallback;
-    switch (label) {
-        case "integration":
-            return stated("integration", "key");
-        case "webhook":
-            return stated("webhook", "key");
-        case "cron-trigger":
-            return stated("cronTrigger", "key");
-        case "blob-bucket":
-            return stated("bucket", "key");
-        case "prompt":
-            return stated("prompt", "key");
-        case "workflow":
-            return stated("workflow", "key");
-        // #3320 — the declared key, like the function preflight collector, the
-        // apply loop and `--only`. A renamed file is one object, so both
-        // collectors' messages land on the one comparison row.
-        case "function":
-            return stated("function", "key");
-        case "email-template":
-            return stated("template", "emailType");
-        case "database-type-config":
-            return stated("type", "databaseType");
-        case "group-type-config":
-            return stated("groupTypeConfig", "groupType");
-        case "collection-type-config":
-            return stated("collectionTypeConfig", "collectionType");
-        case "metadata-category-config": {
-            const section = tomlData?.metadataCategoryConfig || {};
-            if (section.resourceType && section.category) {
-                return `${section.resourceType}#${section.category}`;
-            }
-            // `resourceType.category.toml`, the filename fallback push and diff share.
-            const dot = fallback.indexOf(".");
-            return dot > 0
-                ? `${fallback.slice(0, dot)}#${fallback.slice(dot + 1)}`
-                : fallback;
+    const identity = CONFIG_ROW_IDENTITY[label];
+    if (label === "metadata-category-config") {
+        const section = tomlData?.metadataCategoryConfig || {};
+        if (section.resourceType && section.category) {
+            return `${section.resourceType}#${section.category}`;
         }
-        // Rule sets are keyed by FILE NAME on both sides — a renamed `ruleSet.name`
-        // still updates the same entity, so the row is the file's.
-        default:
-            return fallback;
+        // `resourceType.category.toml`, the filename fallback push and diff share.
+        const dot = fallback.indexOf(".");
+        return dot > 0
+            ? `${fallback.slice(0, dot)}#${fallback.slice(dot + 1)}`
+            : fallback;
+    }
+    // Rule sets are keyed by FILE NAME on both sides — a renamed `ruleSet.name`
+    // still updates the same entity, so the row is the file's.
+    if (!identity)
+        return fallback;
+    const [table, key] = identity[0];
+    return tomlData?.[table]?.[key] || fallback;
+}
+/**
+ * The `[table].key` fields that name the object a config file describes, per
+ * type — what `localConfigRowKey` reads before falling back to the file name.
+ * A type absent here (rule sets, test cases) is identified by its file name
+ * alone.
+ */
+const CONFIG_ROW_IDENTITY = {
+    integration: [["integration", "key"]],
+    webhook: [["webhook", "key"]],
+    "cron-trigger": [["cronTrigger", "key"]],
+    "blob-bucket": [["bucket", "key"]],
+    prompt: [["prompt", "key"]],
+    workflow: [["workflow", "key"]],
+    // #3320 — the declared key, like the function preflight collector, the
+    // apply loop and `--only`. A renamed file is one object, so both
+    // collectors' messages land on the one comparison row.
+    function: [["function", "key"]],
+    "email-template": [["template", "emailType"]],
+    "database-type-config": [["type", "databaseType"]],
+    "group-type-config": [["groupTypeConfig", "groupType"]],
+    "collection-type-config": [["collectionTypeConfig", "collectionType"]],
+    "metadata-category-config": [
+        ["metadataCategoryConfig", "resourceType"],
+        ["metadataCategoryConfig", "category"],
+    ],
+};
+/**
+ * The local file as `config diff` compares it against the server object pull
+ * writes to `file` (#4160), or `null` when the file names a different object.
+ *
+ * Diff pairs a file with a server object by the identity the file states, or
+ * its file name when it states none, and injects that identity before
+ * comparing. So a file whose stated key is another object's is not this
+ * object's file whatever its other values say, and a file that leaves its
+ * identity to the file name is compared with the identity filled in.
+ */
+function localConfigWithServerIdentity(label, local, server, file) {
+    if (localConfigRowKey(label, local, file) !== localConfigRowKey(label, server, file)) {
+        return null;
     }
+    const resolved = { ...local };
+    for (const [table, key] of CONFIG_ROW_IDENTITY[label] ?? []) {
+        if (server?.[table]?.[key] === undefined)
+            continue;
+        resolved[table] = { ...(resolved[table] ?? {}), [key]: server[table][key] };
+    }
+    return resolved;
 }
 /**
  * `config push`'s preflight — every check the authored files decide on their
@@ -2382,7 +2507,7 @@ function localConfigRowKey(label, tomlData, file) {
  * that being a visible change to this signature.
  */
 export async function runConfigPushPreflight(input) {
-    const { configDir, resolvedAppId, pushSelection, syncState, force, isCrossAppPush, client, } = input;
+    const { configDir, resolvedAppId, pushSelection, syncState, force, isCrossAppPush, localEnvironment = false, client, } = 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
@@ -2523,6 +2648,24 @@ export async function runConfigPushPreflight(input) {
             }
         }
     }
+    // #4116 — the deprecated `ruleSetId` spelling in a bucket file. Advisory
+    // only: the file pushes. Bounded by `--only`, like the notice above.
+    const preflightBucketsDir = join(configDir, "blob-buckets");
+    if (existsSync(preflightBucketsDir)) {
+        for (const file of selectFiles("blob-bucket", preflightBucketsDir, readdirSync(preflightBucketsDir).filter((f) => f.endsWith(".toml")))) {
+            let tomlData;
+            try {
+                tomlData = parseTomlFile(join(preflightBucketsDir, file));
+            }
+            catch {
+                // A file that does not parse is reported by the collector below.
+                continue;
+            }
+            const advice = blobBucketDeprecatedKeyWarning(`blob-buckets/${file}`, tomlData);
+            if (advice)
+                warn(`  ${advice}`);
+        }
+    }
     // Validate app.toml settings up-front (issue #1033). A mistyped value
     // is a hard error that must abort BEFORE any mutation — same
     // fail-before-mutate contract as the vars preflight below. The apply
@@ -2539,10 +2682,12 @@ export async function runConfigPushPreflight(input) {
                 // #2880 DSO-001 — the same exclusion the apply block computes, so
                 // the preflight validates the body that will actually be sent.
                 excludeName: appSettingsNameExcluded({
+                    localEnvironment,
                     isCrossAppPush: !!isCrossAppPush,
                     recordedExcludedName: syncState?.entities?.app?.excludedName,
                     fileName: parsedApp?.app?.name,
                 }),
+                nameOptional: localEnvironment,
             });
             for (const e of appErrors) {
                 preflightValidationErrors.push(`  app.toml: ${e}`);
@@ -2680,11 +2825,9 @@ export async function runConfigPushPreflight(input) {
             preflightValidationErrors.push(`  ${message}`);
         }
     }
-    // #3626 §4 — one advisory line per prompt file still written in the flat
-    // chat spelling, beside the `celContextAccess` notice above. The push
-    // continues and the keys are applied; `config pull` rewrites the file, so a
-    // single pull-then-push clears the notice. Printed even under `--dry-run`,
-    // which never reaches the apply — the notice is about the FILE.
+    // #3798 — the prompt files this push selects, read once more for the check
+    // that needs app state: an agent's functions must exist. Bounded by `--only`,
+    // and run before anything is applied.
     const preflightPromptsDir = join(configDir, "prompts");
     // #3798 — the functions an agent's references are checked against, read
     // once and only when a selected prompt is an agent that names one.
@@ -2700,9 +2843,6 @@ export async function runConfigPushPreflight(input) {
                 // A file that does not parse is reported by the collector above.
                 continue;
             }
-            const notice = promptFlatChatKeyWarning(filePath, tomlData);
-            if (notice)
-                warn(`  ${notice}`);
             // #3798 — an agent's tool, turn-context and history functions must
             // exist, and a tool's must declare both schemas, before anything is
             // applied. Bounded by `--only` like the rest of this loop.
@@ -2775,22 +2915,16 @@ export async function runConfigPushPreflight(input) {
 /**
  * The blocks one `[[configs]]` entry carries that its prompt's kind does not
  * name — #3798. An agent's entry may carry only `[configs.agent]`; a chat or
- * decisions entry may not carry it. `movedFlat` are the deprecated flat chat
- * keys the hoist moved under `chat`, named as the author wrote them.
+ * decisions entry may not carry it.
  *
  * Only the blocks the other arms of `resolvePromptKind` cannot see are checked
  * here: a decisions block on a chat entry, and chat keys on a decisions entry,
  * stay the resolver's refusals with their #3626 wording.
  */
-function promptEntryBlockErrors(kind, entry, movedFlat) {
+function promptEntryBlockErrors(kind, entry) {
     const has = (block) => entry != null && typeof entry === "object" && entry[block] !== undefined;
     const errors = [];
     if (kind === "agent") {
-        if (movedFlat.length > 0) {
-            errors.push(`sets ${movedFlat.join(", ")} flat — the deprecated [configs.chat] ` +
-                'spelling — but prompt kind is "agent", so it may carry only a ' +
-                "[configs.agent] block; write them under [configs.agent]");
-        }
         for (const block of ["chat", "decisions"]) {
             if (!has(block))
                 continue;
@@ -2810,10 +2944,9 @@ function promptEntryBlockErrors(kind, entry, movedFlat) {
 /**
  * A prompt file's KIND errors — #3626, decidable from the file alone.
  *
- * Three refusals, all of them the same rule seen from different angles: a key
- * set both flat and under `[configs.chat]` (the hoist will not guess), a
- * `[[configs]]` entry carrying the block of the OTHER kind, and a malformed
- * decisions declaration. The last two come from `resolvePromptKind`, the same
+ * Two refusals, the same rule seen from different angles: a `[[configs]]`
+ * entry carrying the block of the OTHER kind, and a malformed decisions
+ * declaration. Both come from `resolvePromptKind`, the same
  * vendored function the admin routes validate with, so the CLI's refusal and
  * the server's cannot disagree — and this one lands in the preflight, before
  * the first mutating call.
@@ -2868,27 +3001,28 @@ export function promptKindFileErrors(filePath, tomlData) {
             errors.push(`${filePath}: ${refusal.message}`);
         }
     }
-    for (const [index, entry] of entries.entries()) {
-        const hoisted = hoistDeprecatedChatKeys(entry);
-        for (const key of hoisted.conflicts) {
-            errors.push(`${filePath}: configs[${index}].${key} is set both flat and under ` +
-                `[configs.chat]; keep the [configs.chat] spelling`);
-        }
+    for (const [index, rawEntry] of entries.entries()) {
+        // #3642 — the blocks are read as the file wrote them. A chat key at the
+        // entry's root is the retired flat spelling, which the unknown-key check
+        // refuses on its own; it is not a value any rule here reads.
+        const entry = rawEntry && typeof rawEntry === "object" && !Array.isArray(rawEntry)
+            ? rawEntry
+            : {};
         // #3798 — the block rule for three kinds, stated per entry: an entry may
         // carry only the block its prompt's kind names. An agent's `[configs.agent]`
         // holds keys chat also holds, so a stray block would otherwise be read (or
         // ignored) in silence by the payload builder.
-        const blockErrors = promptEntryBlockErrors(fileKind, entry, hoisted.moved).map((message) => `${filePath}: configs[${index}] ${message}`);
+        const blockErrors = promptEntryBlockErrors(fileKind, entry).map((message) => `${filePath}: configs[${index}] ${message}`);
         if (blockErrors.length > 0) {
             errors.push(...blockErrors);
             continue;
         }
         if (fileKind === "agent") {
-            const agent = hoisted.entry.agent ?? {};
+            const agent = entry.agent ?? {};
             const resolution = resolvePromptKind({
                 kind: "agent",
-                provider: hoisted.entry.provider,
-                model: hoisted.entry.model,
+                provider: entry.provider,
+                model: entry.model,
                 config: {
                     systemPrompt: agent.systemPrompt,
                     temperature: agent.temperature,
@@ -2906,8 +3040,8 @@ export function promptKindFileErrors(filePath, tomlData) {
             }
             continue;
         }
-        const chat = hoisted.entry.chat ?? {};
-        const decisions = hoisted.entry.decisions ?? {};
+        const chat = entry.chat ?? {};
+        const decisions = entry.decisions ?? {};
         // #3626 — the FIRST entry of a chat prompt carries the create seed's
         // placeholder. `buildPromptCreatePayload` sends `{{ input }}` when the
         // file names no template, which is how a prompt authored without one has
@@ -2927,8 +3061,8 @@ export function promptKindFileErrors(filePath, tomlData) {
             : chat.userPromptTemplate;
         const resolution = resolvePromptKind({
             kind: tomlData?.prompt?.kind,
-            provider: hoisted.entry.provider,
-            model: hoisted.entry.model,
+            provider: entry.provider,
+            model: entry.model,
             config: {
                 systemPrompt: chat.systemPrompt,
                 userPromptTemplate,
@@ -2953,12 +3087,12 @@ export function promptKindFileErrors(filePath, tomlData) {
         // against what the server holds.
         if (resolution.kind === "chat") {
             const strict = resolvePromptStrictOutput({
-                provider: hoisted.entry.provider,
+                provider: entry.provider,
                 strictOutput: chat.strictOutput,
                 outputFormat: chat.outputFormat,
                 configOutputSchema: chat.outputSchema,
                 promptOutputSchema: tomlData?.prompt?.outputSchema,
-                status: hoisted.entry.status ?? PROMPT_CONFIG_DEFAULT_STATUS,
+                status: entry.status ?? PROMPT_CONFIG_DEFAULT_STATUS,
             });
             if (strict.ok === false) {
                 errors.push(`${filePath}: configs[${index}] — ${strict.error} (${strict.code})`);
@@ -3174,26 +3308,64 @@ export function promptKindImmutableOutcome(storedKind, localDoc) {
     };
 }
 /**
- * The one deprecation notice a prompt file using the FLAT chat spelling earns
- * — #3626 §4, beside the `celContextAccess` notice's precedent.
+ * The file-decidable refusals `config push` gives one config file — the
+ * per-file body of `collectConfigFileValidationErrors`, shared with `config
+ * pull` (#4160), which never keeps a local file push would refuse.
  *
- * Advisory: the push continues and the keys are applied. `null` when the file
- * is already written in the grouped spelling, so a migrated tree is silent.
+ * `tables` are the tables whose unrecognized keys are checked here (none for a
+ * workflow, whose own validator owns that message); declared types run over
+ * every table of the surface.
  */
-export function promptFlatChatKeyWarning(filePath, tomlData) {
-    const entries = Array.isArray(tomlData?.configs) ? tomlData.configs : [];
-    const moved = new Set();
-    for (const entry of entries) {
-        for (const key of hoistDeprecatedChatKeys(entry).moved)
-            moved.add(key);
+export function configFileValidationMessages(filePath, tomlData, surface, tables) {
+    const messages = [];
+    // The document's own shape first: an unrecognized top-level table makes
+    // every per-table check below read an absent table, so its silence would
+    // be misleading.
+    messages.push(...configDocumentShapeErrors(filePath, tomlData, surface));
+    for (const table of tables) {
+        const unknownKeyError = configUnknownKeyError(filePath, tomlData, table);
+        if (unknownKeyError)
+            messages.push(unknownKeyError);
     }
-    if (moved.size === 0)
-        return null;
-    const named = [...moved].sort().join(", ");
-    return (`${filePath}: ${named} ${moved.size === 1 ? "is" : "are"} written flat ` +
-        "under [[configs]]; this spelling is deprecated — move them under " +
-        "[configs.chat] (`config pull` rewrites the file). Rejecting the flat " +
-        "spelling is tracked in #3642.");
+    // Declared types run over EVERY table of the surface, workflows included
+    // — `tables` above is pruned for workflows because `validateWorkflowToml`
+    // owns their unrecognized-key message, which is a different check.
+    for (const table of surface.tables) {
+        messages.push(...configDeclaredTypeErrors(filePath, tomlData, table));
+    }
+    // #3626 — the prompt kind's own file-decidable refusals, run by the same
+    // collector so `config push` and `config diff` cannot disagree about
+    // which prompt files are pushable.
+    if (surface.label === "prompt") {
+        messages.push(...promptKindFileErrors(filePath, tomlData));
+    }
+    // #4116 — a bucket naming its rule set both ways.
+    if (surface.label === "blob-bucket") {
+        messages.push(...blobBucketFileErrors(filePath, tomlData));
+    }
+    return messages;
+}
+/**
+ * Whether `config pull` must rewrite a local file whatever it says (#4160):
+ * `config push` would refuse it, or it spells something in a deprecated form
+ * pull exists to migrate (a bucket naming its rule set by id). Keeping such a
+ * file because its VALUES match would leave the tree unpushable, or the
+ * deprecation unresolved, after a pull that reported success.
+ */
+export function pullMustRewrite(label, tomlData) {
+    // A test-case sidecar is not one of the preflight's per-directory targets;
+    // push refuses it through its own collector.
+    if (label === "test-case") {
+        return testCaseSidecarPreflightErrors("", tomlData).length > 0;
+    }
+    const target = unknownKeyPreflightTargets().find((t) => t.surface.label === label);
+    if (target) {
+        const tables = label === "workflow" ? [WORKFLOW_TABLE] : target.tables;
+        if (configFileValidationMessages("", tomlData, target.surface, tables).length > 0) {
+            return true;
+        }
+    }
+    return (label === "blob-bucket" && blobBucketDeprecatedKeyWarning("", tomlData) !== null);
 }
 export function collectConfigFileValidationErrors(configDir) {
     const found = [];
@@ -3214,28 +3386,7 @@ export function collectConfigFileValidationErrors(configDir) {
             catch {
                 continue;
             }
-            const messages = [];
-            // The document's own shape first: an unrecognized top-level table makes
-            // every per-table check below read an absent table, so its silence would
-            // be misleading.
-            messages.push(...configDocumentShapeErrors(filePath, tomlData, surface));
-            for (const table of tables) {
-                const unknownKeyError = configUnknownKeyError(filePath, tomlData, table);
-                if (unknownKeyError)
-                    messages.push(unknownKeyError);
-            }
-            // Declared types run over EVERY table of the surface, workflows included
-            // — `tables` above is pruned for workflows because `validateWorkflowToml`
-            // owns their unrecognized-key message, which is a different check.
-            for (const table of surface.tables) {
-                messages.push(...configDeclaredTypeErrors(filePath, tomlData, table));
-            }
-            // #3626 — the prompt kind's own file-decidable refusals, run by the same
-            // collector so `config push` and `config diff` cannot disagree about
-            // which prompt files are pushable.
-            if (surface.label === "prompt") {
-                messages.push(...promptKindFileErrors(filePath, tomlData));
-            }
+            const messages = configFileValidationMessages(filePath, tomlData, surface, tables);
             if (messages.length === 0)
                 continue;
             found.push({
@@ -4535,16 +4686,16 @@ function jsonFieldsForDiff(table, entity) {
 /**
  * One test-case reference as the comparison reads it (#2880 behavior 17).
  *
- * A reference reaches the projection in one of three states, and all three
- * describe the same thing on both sides once this is applied:
+ * A reference reaches the projection as the value in its NAME slot, in one of
+ * two states, and both describe the same thing on both sides once this is
+ * applied:
  *
- *  - a portable NAME (`configName = "default"`), which a test file carries so
- *    it survives a move between apps;
- *  - a legacy ID that RESOLVES, which becomes that same name — otherwise a file
- *    pinned by id would differ forever from the file pull writes for it;
- *  - a legacy ID that does NOT resolve, which stays the id, because pull writes
- *    an unresolvable id straight back and comparing it away would hide a pin
- *    the next push still sends.
+ *  - a portable NAME (`configName = "default"`) — what a test file carries,
+ *    and what the server's id renders as when the lookups resolve it;
+ *  - a live ID the lookups could NOT resolve, which the comparison's rendering
+ *    (`serializeTestCaseForComparison`) carries in the name slot and which
+ *    stays the id here, so a case pinned to a deleted or unlistable config is
+ *    a difference against an unpinned file rather than hidden (#3998).
  */
 function testCaseReference(value, idToName) {
     if (typeof value !== "string" || value === "")
@@ -4819,28 +4970,14 @@ const CONFIG_DIFF_SPECS = {
     "blob-bucket": {
         label: "blob-bucket",
         table: BLOB_BUCKET_TABLE,
-        parse: (doc) => {
-            const bucket = { ...(doc?.bucket ?? {}) };
-            // #1020 — `accessPolicy` is the pre-`preset` spelling, still accepted on
-            // the wire and still authored in unmigrated files. Both spellings mean
-            // the same access model, so they project the same way; without this an
-            // unmigrated file reports a difference no push can clear (push sends the
-            // legacy key and the server answers with `preset`).
-            if (bucket.preset === undefined && bucket.accessPolicy !== undefined) {
-                bucket.preset = bucket.accessPolicy;
-            }
-            return {
-                bucketKey: doc?.bucket?.key ?? "",
-                ...buildPayloadFromToml(BLOB_BUCKET_TABLE, bucket, {
-                    mode: "create",
-                    values: {
-                        name: (value) => value || doc?.bucket?.key || "",
-                        description: tomlOwned,
-                    },
-                }),
-            };
-        },
-        serialize: (record) => serializeBlobBucket(record),
+        parse: (doc) => parseBlobBucketToml(doc),
+        // #4116 — the rule set is compared by the thing referred to: the record's
+        // id is rendered as its name, and both sides resolve the name back.
+        serialize: (record, maps) => serializeBlobBucket(record, maps.ruleSetIdToName),
+        extras: (entity) => ({
+            _unresolvedRuleSetName: entity._unresolvedRuleSetName,
+        }),
+        ruleSetRef: true,
         // `name` is trimmed on the way in and a blank description is stored as
         // none (DSO-003).
         canonicalize: (entity) => canonicalizeServerTextFields(entity, {
@@ -4862,9 +4999,14 @@ const CONFIG_DIFF_SPECS = {
             const keys = [];
             if (!bucket.name)
                 keys.push("name");
-            if (!bucket.preset && !bucket.accessPolicy)
+            if (!bucket.preset)
                 keys.push("preset");
-            if (!bucket.ruleSetId)
+            // Either spelling manages the rule set (#4116) — read as the parse reads
+            // it, so a blank name is no reference rather than a difference the
+            // update cannot carry.
+            const named = typeof bucket.ruleSetName === "string" && bucket.ruleSetName.trim() !== "";
+            const legacy = typeof bucket.ruleSetId === "string" && bucket.ruleSetId !== "";
+            if (!named && !legacy)
                 keys.push("ruleSetId");
             return keys;
         },
@@ -4874,17 +5016,15 @@ const CONFIG_DIFF_SPECS = {
     // edited expectation read as Synced while push applied it from the file's
     // byte hash.
     //
-    // The type's own difficulty is that a reference has two legal spellings — the
-    // portable `configName` a test file carries so it survives a move between
-    // apps, and the legacy `configId` pull still writes back when the name cannot
-    // be resolved. They name the same thing, so they project the same way; the
-    // `extra` context is what makes that possible (the id→name lookups are not in
-    // the document).
+    // The type's own difficulty is that a reference is a NAME in the file and an
+    // id on the server. The comparison renders the server's id through the
+    // id→name lookups (which are not in the document — the `extra` context
+    // carries them), so both sides project the thing referred to.
     "test-case": {
         label: "test-case",
         table: TEST_CASE_TABLE,
         parse: (doc) => parseTestCaseToml(doc),
-        serialize: (record, _maps, extra) => serializeTestCase(record, extra?.lookupMaps),
+        serialize: (record, _maps, extra) => serializeTestCaseForComparison(record, extra?.lookupMaps),
         // The server trims a test-case name on write (`src/admin-api.ts`), so a
         // padded one in the file is not a difference — it is what the server will
         // store (#2880 DSO-003).
@@ -4894,12 +5034,11 @@ const CONFIG_DIFF_SPECS = {
         },
         extras: (entity, _doc, extra) => ({
             // These three OVERRIDE the definition's fields of the same name: the
-            // value compared is the thing referred to, not the spelling that referred
-            // to it. Precedence matches the push path exactly — a file carrying both
-            // an id and a name is pushed on the id, so it is compared on the id.
-            configId: testCaseReference(entity.configId ?? entity._configName, extra?.lookupMaps?.configIdToName),
-            evaluatorPromptId: testCaseReference(entity.evaluatorPromptId ?? entity._evaluatorPromptKey, extra?.lookupMaps?.promptIdToKey),
-            evaluatorConfigId: testCaseReference(entity.evaluatorConfigId ?? entity._evaluatorConfigName, extra?.lookupMaps?.configIdToName),
+            // value compared is the thing referred to, read from the name the file
+            // (or the comparison's rendering of the server record) carries.
+            configId: testCaseReference(entity._configName, extra?.lookupMaps?.configIdToName),
+            evaluatorPromptId: testCaseReference(entity._evaluatorPromptKey, extra?.lookupMaps?.promptIdToKey),
+            evaluatorConfigId: testCaseReference(entity._evaluatorConfigName, extra?.lookupMaps?.configIdToName),
         }),
         describe: (entity) => `test case "${entity?.name}"`,
     },
@@ -4984,6 +5123,15 @@ export function projectRemoteConfig(spec, record, maps, extra) {
 export function projectConfigPair(spec, localParsed, remoteRecord, maps, extra, localExtra) {
     const local = projectLocalConfig(spec, localParsed, maps, localExtra);
     const remote = projectRemoteConfig(spec, remoteRecord, maps, extra);
+    reconcileUnmanagedFields(spec, localParsed, local, remote);
+    return { local, remote };
+}
+/**
+ * Take the server's value for every field the local file leaves unmanaged
+ * (#2880), on `local` in place — the reconciliation `projectConfigPair` makes,
+ * shared with `config pull`'s keep-or-write comparison (#4160).
+ */
+function reconcileUnmanagedFields(spec, localParsed, local, remote) {
     for (const key of spec.unmanaged?.(localParsed) ?? []) {
         // Key-for-key, so an unmanaged field the server does not hold either is
         // absent on both sides rather than present-and-undefined on one.
@@ -4992,7 +5140,20 @@ export function projectConfigPair(spec, localParsed, remoteRecord, maps, extra,
         else
             delete local[key];
     }
-    return { local, remote };
+}
+/**
+ * One `config diff` row's verdict once both sides exist (#4116, DSO-4116-003).
+ *
+ * A type whose files name a rule set cannot be compared without the app's
+ * rule-set listing: an unresolvable reference would read as a difference that
+ * is not there. So when the listing failed the row says so rather than
+ * comparing; otherwise `compare` decides.
+ */
+export function configDiffRowVerdict(parsed, remote, compare, contentComparable) {
+    if (!contentComparable) {
+        return { status: "exists", hint: "content not compared (rule sets unavailable)" };
+    }
+    return compare(parsed, remote);
 }
 /**
  * One `config diff` row's content verdict for a registered type (#2880).
@@ -5506,6 +5667,59 @@ export function configSemanticHash(label, filePath, maps) {
         return undefined;
     }
 }
+/**
+ * Whether a local config file says what the file `config pull` would write
+ * says (#4160) — the definition-projected field set `config diff` compares, so
+ * a file diff calls Synced keeps its comments, key order and explicit defaults
+ * through a pull.
+ *
+ * Both sides go through the same projection with the same context, so
+ * `extra` is the context a reference is read through (a test case's lookups),
+ * never server-only rows. As in diff, the file is paired by the identity it
+ * states (or `filePath`'s name), and the fields it leaves unmanaged take the
+ * server's values — so a kept file's baseline is the server's projection
+ * (`pulledSemanticHash`), never the file's own.
+ */
+export function sameConfigAs(label, serverContent, filePath, maps, extra) {
+    const spec = configDiffSpec(label);
+    return (localContent) => {
+        const parsed = parseConfigToml(localContent);
+        if (pullMustRewrite(label, parsed))
+            return false;
+        const server = parseConfigToml(serverContent);
+        const local = localConfigWithServerIdentity(label, parsed, server, filePath);
+        if (local === null)
+            return false;
+        const localProjected = projectLocalConfig(spec, local, maps, extra);
+        const serverProjected = projectLocalConfig(spec, server, maps, extra);
+        reconcileUnmanagedFields(spec, local, localProjected, serverProjected);
+        return (computeExpandedContentHash(localProjected) ===
+            computeExpandedContentHash(serverProjected));
+    };
+}
+/**
+ * The semantic baseline `config pull` stamps for a config file (#4160): the
+ * projection of what the server serializes, whether the file was written or
+ * kept. A kept file can leave unmanaged fields or its identity to the server,
+ * so hashing it would record a baseline the server never had.
+ */
+export function pulledSemanticHash(label, serverContent, maps) {
+    try {
+        return hashLocalConfigForDiff(configDiffSpec(label), parseConfigToml(serverContent), maps);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a local TOML file parses to the same document as `serverContent`
+ * (#4160): the comparison for `vars.toml`, which has no field definition
+ * behind it, so only comments, key order and spelling are free.
+ */
+export function sameTomlAs(serverContent) {
+    return (localContent) => canonicalJsonStringify(parseConfigToml(localContent)) ===
+        canonicalJsonStringify(parseConfigToml(serverContent));
+}
 /**
  * The sync state `config push` writes into (#2731 B6, closing #2374).
  *
@@ -5718,49 +5932,81 @@ export function getTestsDir(configDir, blockType, blockKey) {
 function blockSelectionLabel(blockType) {
     return blockType === "script" ? "transform" : blockType;
 }
-export function serializeTestCase(testCase, lookupMaps, options = {}) {
-    // #2644 — name any server key this CLI version does not know rather than
-    // dropping it silently on the way into the file. Test cases are a registered
-    // surface; their sidecar shape is the only thing that sets them apart.
-    warnUnrecognizedServerKeys(testCase, TEST_CASE_TABLE, options.file ?? `<block>.tests/${testCase?.name ?? "unnamed"}.toml`, options.logger);
-    // Resolve ID references to key-based references
-    const configName = testCase.configId && lookupMaps?.configIdToName
-        ? (lookupMaps.configIdToName.get(testCase.configId) || "") : "";
-    const evaluatorPromptKey = testCase.evaluatorPromptId && lookupMaps?.promptIdToKey
-        ? (lookupMaps.promptIdToKey.get(testCase.evaluatorPromptId) || "") : "";
-    const evaluatorConfigName = testCase.evaluatorConfigId && lookupMaps?.configIdToName
-        ? (lookupMaps.configIdToName.get(testCase.evaluatorConfigId) || "") : "";
+/**
+ * The `[test]` table for one server record, and the references it could not
+ * name (#3998).
+ *
+ * A sidecar authors its references by NAME only — the id spellings are retired
+ * — so a reference whose id has no lookup entry has no honest spelling in a
+ * file. `unresolvedSpelling` says what goes in the name slot for one: `"empty"`
+ * for the file pull writes (and the caller decides whether to write it at all),
+ * `"raw-id"` for the comparison's rendering, which is parsed and never written.
+ */
+function testCaseSidecarTable(testCase, lookupMaps, unresolvedSpelling) {
+    const unresolved = [];
+    const reference = (field, tomlKey, idToName) => {
+        const id = testCase?.[field];
+        if (typeof id !== "string" || id === "")
+            return "";
+        const name = idToName?.get(id);
+        if (name)
+            return name;
+        unresolved.push({ tomlKey, field, id });
+        return unresolvedSpelling === "raw-id" ? id : "";
+    };
+    const configName = reference("configId", "configName", lookupMaps?.configIdToName);
+    const evaluatorPromptKey = reference("evaluatorPromptId", "evaluatorPromptKey", lookupMaps?.promptIdToKey);
+    // The judge's config belongs to the evaluator prompt, not to this sidecar's
+    // block; config ids are app-unique, so the app-wide map names it.
+    const evaluatorConfigName = reference("evaluatorConfigId", "evaluatorConfigName", lookupMaps?.configIdToName);
     // #2644 criterion 1 — the `[test]` key set comes from the vendored
     // definition, so a field added there is emitted by pull with no edit here.
     // The three reference fields carry the resolved NAME (a test file is portable
     // across apps); the rest keep the empty-string / "{}" / "[]" spellings a test
     // file has always used for "not set".
-    const data = {
-        test: projectRecordToToml(TEST_CASE_TABLE, testCase, {
-            name: (record) => record.name || "",
-            description: (record) => record.description || "",
-            inputVariables: (record) => jsonFieldText(record.inputVariables, "{}"),
-            configId: () => configName,
-            evaluatorPromptId: () => evaluatorPromptKey,
-            evaluatorConfigId: () => evaluatorConfigName,
-            expectedOutputPattern: (record) => record.expectedOutputPattern || "",
-            expectedOutputContains: (record) => jsonFieldText(record.expectedOutputContains, "[]"),
-            expectedJsonSubset: (record) => jsonFieldText(record.expectedJsonSubset, "{}"),
-        }),
-    };
-    // #2769 — a reference the id→name lookup could not resolve (an unknown id, or
-    // a config listing that failed on this pull) is written back in the legacy id
-    // spelling the parser still accepts, NOT as an empty name. Rewriting a pinned
-    // test as unpinned would push the pin away on the next `config push`.
-    if (testCase.configId && !configName)
-        data.test.configId = testCase.configId;
-    if (testCase.evaluatorPromptId && !evaluatorPromptKey) {
-        data.test.evaluatorPromptId = testCase.evaluatorPromptId;
-    }
-    if (testCase.evaluatorConfigId && !evaluatorConfigName) {
-        data.test.evaluatorConfigId = testCase.evaluatorConfigId;
-    }
-    return stringifyConfigToml(data);
+    const test = projectRecordToToml(TEST_CASE_TABLE, testCase, {
+        name: (record) => record.name || "",
+        description: (record) => record.description || "",
+        inputVariables: (record) => jsonFieldText(record.inputVariables, "{}"),
+        configId: () => configName,
+        evaluatorPromptId: () => evaluatorPromptKey,
+        evaluatorConfigId: () => evaluatorConfigName,
+        expectedOutputPattern: (record) => record.expectedOutputPattern || "",
+        expectedOutputContains: (record) => jsonFieldText(record.expectedOutputContains, "[]"),
+        expectedJsonSubset: (record) => jsonFieldText(record.expectedJsonSubset, "{}"),
+    });
+    return { test, unresolved };
+}
+/**
+ * The sidecar `config pull` writes for one server record. It never emits an id
+ * key (#3998): a reference the lookups cannot name is written as an empty name
+ * and reported through `onUnresolved`, and `pullTestCasesForBlock` declines to
+ * write such a case rather than unpin it on disk.
+ */
+export function serializeTestCase(testCase, lookupMaps, options = {}) {
+    // #2644 — name any server key this CLI version does not know rather than
+    // dropping it silently on the way into the file. Test cases are a registered
+    // surface; their sidecar shape is the only thing that sets them apart.
+    warnUnrecognizedServerKeys(testCase, TEST_CASE_TABLE, options.file ?? `<block>.tests/${testCase?.name ?? "unnamed"}.toml`, options.logger);
+    const { test, unresolved } = testCaseSidecarTable(testCase, lookupMaps, "empty");
+    if (unresolved.length > 0)
+        options.onUnresolved?.(unresolved);
+    return stringifyConfigToml({ test });
+}
+/**
+ * The rendering of a server record that the comparison parses (#3998) — never
+ * written to disk.
+ *
+ * It differs from the file pull writes in one place: a reference the lookups
+ * cannot name carries its raw id in the NAME slot. A live case pinned to a
+ * deleted or unlistable configuration must stay a difference against an
+ * unpinned file; projecting it as "no reference" would read the pair as Synced,
+ * and the next content edit would push `configId: null` and clear the pin in
+ * silence.
+ */
+export function serializeTestCaseForComparison(testCase, lookupMaps) {
+    const { test } = testCaseSidecarTable(testCase, lookupMaps, "raw-id");
+    return stringifyConfigToml({ test });
 }
 /**
  * The TOML spelling of a JSON-valued test-case field (#2769).
@@ -5810,20 +6056,22 @@ export function parseTestCaseToml(tomlData) {
             description: (value) => (value ? value : undefined),
             // Always sent — the server requires it, and `{}` is the empty spelling.
             inputVariables: (value) => parseJsonText(value, ["{}"]) ?? {},
-            // The legacy ID-based spellings stay accepted (declared in the
-            // definition's `tomlOnlyKeys`); the name-based ones become the `_`
-            // markers below, which the push path resolves against the live app.
-            configId: (_value, _mode, toml) => toml.configId || undefined,
-            evaluatorPromptId: (_value, _mode, toml) => toml.evaluatorPromptId || undefined,
-            evaluatorConfigId: (_value, _mode, toml) => toml.evaluatorConfigId || undefined,
+            // A reference is authored by name only: the names become the `_`
+            // markers below, which the push path resolves against the live app. The
+            // id spellings are retired (#3998) and refused by the preflight, so
+            // nothing is read into the wire field here — and these producers must
+            // stay, because without one `buildPayloadFromToml` would forward the
+            // NAME (`configName`) under the id field.
+            configId: () => undefined,
+            evaluatorPromptId: () => undefined,
+            evaluatorConfigId: () => undefined,
             expectedOutputPattern: (value) => (value ? value : undefined),
             expectedOutputContains: (value) => parseJsonText(value, ["[]"]),
             expectedJsonSubset: (value) => parseJsonText(value, ["{}"]),
         },
     });
     // An omitted field must be absent from the body, not present-and-undefined:
-    // the push path tests `!testPayload.configId` and the server's unknown-key
-    // check reads the body's keys.
+    // the server's unknown-key check reads the body's keys.
     for (const key of Object.keys(payload)) {
         if (payload[key] === undefined)
             delete payload[key];
@@ -5877,7 +6125,9 @@ export async function pullScripts(client, appId, configDir, logger = () => { },
  * `config pull --only` (issue #2645): which transform names this pull may
  * write. Defaults to every one the server lists.
  */
-selects = () => true) {
+selects = () => true, 
+/** Counts each transform as written or left unchanged (#4160). */
+writes) {
     const transformsDir = join(configDir, "transforms");
     ensureDir(transformsDir);
     const scriptEntities = {};
@@ -5930,7 +6180,9 @@ selects = () => true) {
         }
         const filename = `${name}.rhai`;
         const filePath = join(transformsDir, filename);
-        writeFileSync(filePath, activeConfig.body);
+        // A transform's comparator is its bytes, so only identical bytes keep the
+        // file (#4160).
+        const fileWritten = writePulledFile(filePath, activeConfig.body, writes);
         scriptEntities[name] = {
             id: script.scriptId,
             modifiedAt: script.modifiedAt || new Date().toISOString(),
@@ -5943,7 +6195,8 @@ selects = () => true) {
             semanticHash: computeScriptBodyHash(activeConfig.body),
         };
         written += 1;
-        logger(`  Wrote transforms/${filename}`);
+        if (fileWritten)
+            logger(`  Wrote transforms/${filename}`);
     }
     const serverKeys = items.map((s) => s?.name).filter(Boolean);
     const presence = detailsOk
@@ -6019,7 +6272,9 @@ export function pushedFunctionBaseline(input) {
  * normalizes outside the tree, and the refusals are reported rather than
  * swallowed.
  */
-export async function pullFunctions(client, appId, configDir, logger = () => { }, selects = () => true) {
+export async function pullFunctions(client, appId, configDir, logger = () => { }, selects = () => true, 
+/** Counts each function file as written or left unchanged (#4160). */
+writes) {
     const functionsDir = join(configDir, "functions");
     ensureDir(functionsDir);
     const functionEntities = {};
@@ -6062,12 +6317,17 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
             // The logger carries #1446's one warning: a schema holding a `null`
             // anywhere cannot be a native table, so it is written as a JSON string
             // and the operator is told which key that happened to.
-            writeFileSync(filePath, serializeFunction(record, undefined, logger));
+            const content = serializeFunction(record, undefined, logger);
+            const fileWritten = writePulledFile(filePath, content, writes, sameConfigAs("function", content, filePath, {
+                ruleSetIdToName: new Map(),
+                ruleSetNameToId: new Map(),
+            }));
             entity.contentHash = computeFileHash(filePath);
             entity.semanticHash = hashRemoteConfigForDiff(configDiffSpec("function"), record, { ruleSetIdToName: new Map(), ruleSetNameToId: new Map() });
             functionEntities[key] = entity;
             written += 1;
-            logger(`  Wrote functions/${key}.toml (no version pushed yet)`);
+            if (fileWritten)
+                logger(`  Wrote functions/${key}.toml (no version pushed yet)`);
             continue;
         }
         let active;
@@ -6123,7 +6383,7 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
         // this is what says so rather than editing a developer's file in silence.
         for (const note of plan.notes)
             logger(`  ${note}`);
-        const applied = applyFunctionPull(plan);
+        const applied = applyFunctionPull(plan, writes);
         for (const refusal of applied.refusals)
             logger(`  ${refusal}`);
         entity.contentHash = computeFileHash(filePath);
@@ -6161,7 +6421,7 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
     });
     for (const warning of schemaPlan.warnings)
         logger(`  ${warning}`);
-    const schemaApplied = applyFunctionPull(schemaPlan);
+    const schemaApplied = applyFunctionPull(schemaPlan, writes);
     for (const refusal of schemaApplied.refusals)
         logger(`  ${refusal}`);
     const presence = detailsOk
@@ -6176,6 +6436,35 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
         items,
     };
 }
+/**
+ * The id→name lookups `config pull` writes test-case references through
+ * (#3998).
+ *
+ * The prompt half is built from EVERY prompt's detail — the pull fetches them
+ * all before `--only` filters the list — so a judge prompt outside the
+ * selection still names. Configurations come from the pulled blocks (a case
+ * pins one of its own block's) and from every prompt (a judge's config is the
+ * judge prompt's). An entry without both an id and a name is skipped.
+ */
+export function testCaseLookupMapsForPull(input) {
+    const configIdToName = new Map();
+    const promptIdToKey = new Map();
+    const addConfig = (config) => {
+        if (config?.configId && config?.configName) {
+            configIdToName.set(config.configId, config.configName);
+        }
+    };
+    for (const prompt of input.prompts) {
+        if (prompt?.promptId && prompt?.promptKey) {
+            promptIdToKey.set(prompt.promptId, prompt.promptKey);
+        }
+        for (const config of prompt?.configs ?? [])
+            addConfig(config);
+    }
+    for (const config of input.configs)
+        addConfig(config);
+    return { configIdToName, promptIdToKey };
+}
 /**
  * Every test case a block has, draining the cursor (#2769).
  *
@@ -6228,6 +6517,27 @@ export function carryForwardTestCaseEntities(params) {
     }
     return carried;
 }
+/**
+ * Whether two sidecar names in `testsDir` are one file on disk (#3998).
+ *
+ * Names that differ only by case are one file on the case-insensitive
+ * filesystems most of these trees live on and two on the rest (#2896), so the
+ * answer comes from the filesystem itself: the same device and inode.
+ */
+function sameTestCaseFile(testsDir, a, b) {
+    if (a === b)
+        return true;
+    if (normalizeTestCaseKey(a) !== normalizeTestCaseKey(b))
+        return false;
+    try {
+        const left = statSync(join(testsDir, `${a}.toml`));
+        const right = statSync(join(testsDir, `${b}.toml`));
+        return left.dev === right.dev && left.ino === right.ino;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Write one block's test cases into its `<key>.tests/` sidecar and record them
  * in sync state. Exported so the unit tests can drive it against a stubbed
@@ -6243,10 +6553,9 @@ export async function pullTestCasesForBlock(params) {
     const testsDir = getTestsDir(configDir, blockType, blockKey);
     // A block with no cases and no sidecar is not a block whose sidecar is empty:
     // creating the directory here would commit an empty folder Git cannot carry.
-    if (testCases.length === 0 && !existsSync(testsDir))
-        return { ok: true, count: 0 };
-    if (testCases.length > 0)
-        ensureDir(testsDir);
+    if (testCases.length === 0 && !existsSync(testsDir)) {
+        return { ok: true, count: 0, unwritten: [] };
+    }
     const pulledSlugs = new Set();
     // #2896 — a keyed case is written to the file its key names, so pull stops
     // renaming what push authored: the repro's `full-refresh-takes-all-history`
@@ -6256,15 +6565,35 @@ export async function pullTestCasesForBlock(params) {
     // The key is server data becoming a path: the containment check an
     // attachment's filename gets, so nothing lands outside the sidecar dir.
     (name) => attachmentWritePath(testsDir, `${name}.toml`) !== null);
+    // #3998 — render every case before anything is written. A reference the
+    // lookups cannot name has no honest spelling in a sidecar (the id keys are
+    // retired, and an empty name would unpin the case on the next push), so such
+    // a case is NOT written: its file, fixtures and record stay as they were.
+    const writable = [];
+    const skipped = [];
     for (const tc of testCases) {
         const slug = fileNames.get(tc);
+        let references = [];
+        const toml = serializeTestCase(tc, lookupMaps, {
+            file: join(testsDir, `${slug}.toml`),
+            logger: (message) => log(message),
+            onUnresolved: (refs) => {
+                references = refs;
+            },
+        });
+        if (references.length > 0)
+            skipped.push({ tc, slug, references });
+        else
+            writable.push({ tc, slug, toml });
+    }
+    if (writable.length > 0)
+        ensureDir(testsDir);
+    const writtenSlugs = new Map(writable.map((w) => [w.slug, w.tc]));
+    for (const { tc, slug, toml } of writable) {
         pulledSlugs.add(slug);
         // Write test case TOML
         const tomlPath = join(testsDir, `${slug}.toml`);
-        writeFileSync(tomlPath, serializeTestCase(tc, lookupMaps, {
-            file: tomlPath,
-            logger: (message) => log(message),
-        }));
+        writePulledFile(tomlPath, toml, params.writes, sameConfigAs("test-case", toml, tomlPath, { ruleSetIdToName: new Map(), ruleSetNameToId: new Map() }, { lookupMaps }));
         // Attachments: the sidecar directory is the authored set, so pull makes it
         // match the server — downloading what is there, recording each file's
         // content hash (so push can see a byte change under an unchanged name), and
@@ -6288,7 +6617,8 @@ export async function pullTestCasesForBlock(params) {
                 }
                 try {
                     const downloaded = await client.downloadTestCaseAttachment(appId, blockType, blockId, tc.testCaseId, att.filename);
-                    writeFileSync(destination, downloaded.data);
+                    // An attachment's comparator is its bytes (#4160).
+                    writePulledFile(destination, downloaded.data, params.writes);
                     (attachments ??= {})[att.filename] = computeFileHash(destination);
                 }
                 catch (err) {
@@ -6356,12 +6686,79 @@ export async function pullTestCasesForBlock(params) {
             }),
         };
     }
+    // #3998 — a skipped case is found by its ID in the prior state, not by the
+    // file name it would get now: the server can rename a case's key between
+    // pulls, and the old file is the one holding the pin. Every such file is
+    // kept out of the cleanup below and every such record carried forward under
+    // its existing key — unless a case written above now owns that file, whose
+    // write wins it (the key-to-file rule of #2896). "That file" is decided by
+    // the filesystem: `Alpha` and `alpha` are one file where names fold case.
+    const unwritten = [];
+    const writtenOwner = (candidate) => writtenSlugs.get(candidate) ??
+        writable.find((w) => sameTestCaseFile(testsDir, w.slug, candidate))?.tc;
+    for (const { tc, slug, references } of skipped) {
+        const priorEntries = Object.entries(params.priorTestCaseEntities ?? {}).filter(([, entry]) => entry?.blockType === blockType &&
+            entry?.blockKey === blockKey &&
+            entry?.id === tc.testCaseId);
+        const slugs = new Set([slug]);
+        for (const [stateKey, entry] of priorEntries) {
+            slugs.add(entry.slug ?? stateKey.slice(stateKey.lastIndexOf("/") + 1));
+        }
+        const preservedSlugs = [];
+        const superseded = new Set();
+        for (const candidate of slugs) {
+            const owner = writtenOwner(candidate);
+            if (owner) {
+                superseded.add(candidate);
+                warn(`  ${blockType}: ${blockKey}/${candidate}.toml now holds test case ` +
+                    `"${owner?.name ?? ""}" — the prior sidecar of unwritten test case ` +
+                    `"${tc?.name ?? ""}" at that path was superseded`);
+                continue;
+            }
+            pulledSlugs.add(candidate);
+            if (existsSync(join(testsDir, `${candidate}.toml`))) {
+                preservedSlugs.push(candidate);
+            }
+        }
+        for (const [stateKey, entry] of priorEntries) {
+            const entrySlug = entry.slug ?? stateKey.slice(stateKey.lastIndexOf("/") + 1);
+            if (superseded.has(entrySlug))
+                continue;
+            if (testCaseEntities[stateKey])
+                continue;
+            testCaseEntities[stateKey] = entry;
+        }
+        const what = references
+            .map((ref) => `${ref.tomlKey} (id ${ref.id})`)
+            .join(", ");
+        const kept = preservedSlugs.length > 0
+            ? `kept ${preservedSlugs.map((s) => `${s}.toml`).join(", ")} as it was`
+            : "no sidecar exists for it";
+        warn(`  Test case not written for ${blockType}: ${blockKey}/${slug} ` +
+            `("${tc?.name ?? ""}"): ${what} could not be resolved to a name — ` +
+            `${kept}, so the pin is not lost. The configuration or prompt may have ` +
+            "been deleted (re-pin the case on the server), or its listing failed " +
+            "on this pull (run `config pull` again).");
+        unwritten.push({
+            blockType,
+            blockKey,
+            slug,
+            name: tc?.name ?? "",
+            testCaseId: tc?.testCaseId,
+            references,
+            preservedSlugs,
+        });
+    }
     // Clean up local files for remotely-deleted test cases
     if (existsSync(testsDir)) {
         const localFiles = readdirSync(testsDir).filter((f) => f.endsWith(".toml"));
         for (const file of localFiles) {
             const localSlug = basename(file, ".toml");
-            if (!pulledSlugs.has(localSlug)) {
+            // A listing keeps the casing a file was created with, so the name a case
+            // was just written to can come back as `Alpha.toml` — the same file.
+            const pulled = pulledSlugs.has(localSlug) ||
+                [...pulledSlugs].some((slug) => sameTestCaseFile(testsDir, slug, localSlug));
+            if (!pulled) {
                 // Remove orphaned TOML
                 unlinkSync(join(testsDir, file));
                 // Remove orphaned attachment dir if exists
@@ -6381,7 +6778,7 @@ export async function pullTestCasesForBlock(params) {
             }
         }
     }
-    return { ok: true, count: testCases.length };
+    return { ok: true, count: writable.length, unwritten };
 }
 /**
  * One pull leg: every block of a type the pull selected (#2769).
@@ -6395,6 +6792,7 @@ export async function pullTestCasesForBlocks(params) {
     const log = params.logger ?? ((message) => info(message));
     let count = 0;
     const skippedBlocks = [];
+    const unwritten = [];
     for (const block of params.blocks) {
         const outcome = await pullTestCasesForBlock({
             client: params.client,
@@ -6406,6 +6804,7 @@ export async function pullTestCasesForBlocks(params) {
             testCaseEntities: params.testCaseEntities,
             priorTestCaseEntities: params.priorTestCaseEntities,
             lookupMaps: params.lookupMaps,
+            writes: params.writes,
         });
         if (!outcome.ok) {
             skippedBlocks.push(block.key);
@@ -6422,9 +6821,14 @@ export async function pullTestCasesForBlocks(params) {
         if (outcome.count > 0) {
             log(`  Wrote ${outcome.count} test case(s) for ${params.blockType}: ${block.key}`);
         }
+        if (outcome.unwritten.length > 0) {
+            log(`  ${outcome.unwritten.length} test case(s) not written for ` +
+                `${params.blockType}: ${block.key} (unresolved references; see above)`);
+        }
         count += outcome.count;
+        unwritten.push(...outcome.unwritten);
     }
-    return { count, skippedBlocks };
+    return { count, skippedBlocks, unwritten };
 }
 /** The 10 MB per-attachment cap the server enforces. */
 const TEN_MB = 10 * 1024 * 1024;
@@ -6616,9 +7020,20 @@ export async function pushTestCasesForBlock(params) {
             continue;
         }
         const tomlData = parseTomlFile(filePath);
+        // #3998 — the command's preflight refuses a sidecar it cannot push, but
+        // this leg is exported and the parser no longer reads the retired id keys:
+        // a file reaching it unchecked would be pushed UNPINNED in silence. The
+        // same per-loop defense the workflow leg keeps (#976).
+        const sidecarErrors = testCaseSidecarPreflightErrors(filePath, tomlData);
+        if (sidecarErrors.length > 0) {
+            const message = sidecarErrors.join("; ");
+            warn(`  Failed to push test case ${blockKey}/${slug}: ${message}`);
+            failures.push({ type: "test-case", key: `${blockKey}/${slug}`, message });
+            continue;
+        }
         const testPayload = parseTestCaseToml(tomlData);
-        // Resolve key-based references to IDs. An authored name that does not
-        // resolve is a FAILURE: silently dropping it would push the test case with
+        // Resolve the authored names to IDs — a name is the only spelling a
+        // sidecar has (#3998). An authored name that does not resolve is a FAILURE: silently dropping it would push the test case with
         // no pin, quietly changing what the case tests (#2769). The exception is a
         // preview of a block this push has not created yet — its configs cannot
         // exist to be named, so a dry run reports the reference as pending rather
@@ -6639,7 +7054,7 @@ export async function pushTestCasesForBlock(params) {
         delete testPayload._configName;
         delete testPayload._evaluatorPromptKey;
         delete testPayload._evaluatorConfigName;
-        if (configName && !testPayload.configId) {
+        if (configName) {
             const configMap = blockType === "prompt"
                 ? resolutionMaps?.promptConfigNameToId
                 : blockType === "script"
@@ -6657,14 +7072,14 @@ export async function pushTestCasesForBlock(params) {
             else
                 noteUnresolved(`configName "${configName}"`, blockType, blockKey);
         }
-        if (evaluatorPromptKey && !testPayload.evaluatorPromptId) {
+        if (evaluatorPromptKey) {
             const resolvedId = resolutionMaps?.promptKeyToId.get(evaluatorPromptKey);
             if (resolvedId)
                 testPayload.evaluatorPromptId = resolvedId;
             else
                 noteUnresolved(`evaluatorPromptKey "${evaluatorPromptKey}"`, "prompt", evaluatorPromptKey);
         }
-        if (evaluatorConfigName && !testPayload.evaluatorConfigId) {
+        if (evaluatorConfigName) {
             let resolvedId = evaluatorPromptKey
                 ? resolutionMaps?.promptConfigNameToId.get(`${evaluatorPromptKey}#${evaluatorConfigName}`)
                 : undefined;
@@ -7245,9 +7660,10 @@ export function pairTestCases(input) {
  * integration and workflow sidecar pinned to a config reported Modified
  * forever, and push read the same pair as server drift.
  *
- * One listing per block that has sidecars, and a failed one is silent: an
- * unresolved reference compares as the id both sides carry, which is the same
- * degradation `serializeTestCase` already applies.
+ * One listing per block that has sidecars, and a failed one is silent: the
+ * live side's unresolved reference then compares as its raw id
+ * (`serializeTestCaseForComparison`), so the row reads Modified rather than
+ * hiding a pin.
  */
 async function fillBlockConfigNames(client, appId, blockType, blockId, configIdToName) {
     try {
@@ -7305,10 +7721,6 @@ export async function compareTestCasesForBlock(params) {
     });
     for (const slug of localSlugs) {
         const live = paired.bySlug.get(slug);
-        if (!live) {
-            rows.push({ ...base, slug, status: LOCAL_ONLY_NEW });
-            continue;
-        }
         const filePath = join(testsDir, `${slug}.toml`);
         let row;
         try {
@@ -7316,7 +7728,9 @@ export async function compareTestCasesForBlock(params) {
             // #2880 criterion 1 — a sidecar push's preflight would reject is not one
             // this command calls synced, and the message is the same one. The WHOLE
             // preflight, not just the sidecar's own rules: an unknown key or a
-            // mistyped value aborts push too.
+            // mistyped value aborts push too. #3998 — and an UNPAIRED sidecar is
+            // checked before it is called local-only, so a new file push would refuse
+            // (a retired id key) is reported with the guidance, not as a create.
             const errors = testCaseSidecarPreflightErrors(filePath, tomlData);
             if (errors.length > 0) {
                 row = {
@@ -7326,6 +7740,10 @@ export async function compareTestCasesForBlock(params) {
                     hint: errors.join("; "),
                 };
             }
+            else if (!live) {
+                rows.push({ ...base, slug, status: LOCAL_ONLY_NEW });
+                continue;
+            }
             else {
                 const verdict = compareLocalToRemote(spec, tomlData, live, { ruleSetIdToName: new Map(), ruleSetNameToId: new Map() }, extra, 
                 // Both sides read a reference through the same lookups — see
@@ -7342,6 +7760,12 @@ export async function compareTestCasesForBlock(params) {
                 hint: `${filePath}: ${err?.message || String(err)}`,
             };
         }
+        // An unpaired file push would refuse has no attachment plan, as a
+        // local-only one has none.
+        if (!live) {
+            rows.push(row);
+            continue;
+        }
         // #2880 behavior 19 — attachments are part of what push would do, read
         // from the SAME plan push executes. A sidecar whose text compares clean but
         // whose fixtures have not been uploaded is not Synced.
@@ -7705,7 +8129,7 @@ export function registerConfigSyncCommands(sync) {
             lastSyncedAt: new Date().toISOString(),
             entities: {},
         };
-        saveSyncState(configDir, state);
+        saveSyncState(state);
         success(`Initialized config directory: ${configDir}`);
         info("Run 'primitive config pull' to download current configuration.");
     });
@@ -7724,6 +8148,7 @@ export function registerConfigSyncCommands(sync) {
         .action(async (options) => {
         const resolvedAppId = getCurrentAppId();
         const configDir = resolveSyncDir();
+        const pullsLocalEnvironment = requireCurrentEnvironment().local;
         if (!options.json) {
             info(`Using per-environment config directory: ${configDir}`);
         }
@@ -7817,7 +8242,11 @@ export function registerConfigSyncCommands(sync) {
             const appWorkflowItems = selectPull("workflow", workflowItems.filter((w) => !isPlatformOwnedWorkflow(w)), (w) => w.workflowKey);
             // Fetch details for each entity
             const integrations = selectPull("integration", await Promise.all(integrationItems.map((i) => client.getIntegration(resolvedAppId, i.integrationId))), (i) => i.integrationKey);
-            const prompts = selectPull("prompt", await Promise.all(promptItems.map((p) => client.getPrompt(resolvedAppId, p.promptId))), (p) => p.promptKey);
+            // #3998 — every prompt's detail is kept, not just the selection's: a
+            // test case of a selected block may be judged by a prompt `--only`
+            // left out, and its sidecar names that prompt by key.
+            const promptDetails = await Promise.all(promptItems.map((p) => client.getPrompt(resolvedAppId, p.promptId)));
+            const prompts = selectPull("prompt", promptDetails, (p) => p.promptKey);
             const workflows = await Promise.all(appWorkflowItems.map(async (w) => {
                 const workflowData = await client.getWorkflow(resolvedAppId, w.workflowId);
                 // #2645 — fetch EVERY config's body, not just the active one. The
@@ -7926,7 +8355,11 @@ export function registerConfigSyncCommands(sync) {
             // sync dir (nothing to back up). Prune to 28 days after success.
             try {
                 const snapshotsRoot = resolveSnapshotsRoot({ appId: resolvedAppId });
-                const snapshot = createSnapshot(configDir, snapshotsRoot);
+                // A machine-local environment's baseline is its own file, not the
+                // shared tree's (#4117): that is the one the snapshot carries.
+                const snapshot = createSnapshot(configDir, snapshotsRoot, {
+                    baselinePath: pullsLocalEnvironment ? resolveSyncStateReadPath() : undefined,
+                });
                 if (snapshot) {
                     info(`  Snapshot: ${snapshot.path}`);
                     pruneSnapshots(snapshotsRoot, 28);
@@ -7955,11 +8388,15 @@ export function registerConfigSyncCommands(sync) {
             ensureDir(join(configDir, "collection-type-configs"));
             ensureDir(join(configDir, "metadata-category-configs"));
             ensureDir(join(configDir, "email-templates"));
+            // #4160 — every pulled file goes through `writePulledFile`, which
+            // leaves a file alone when it already says what the server says, and
+            // counts both outcomes for the summary below.
+            const pullWrites = newPullWriteTally();
             // The prior sync state is the record of which local files a previous
             // pull wrote — the discriminator the prune pass keys off (#1659). Read
             // it now: `saveSyncState` at the end of the pull overwrites it, and the
             // files themselves are about to be rewritten.
-            const priorState = loadSyncState(configDir);
+            const priorState = loadSyncState();
             const priorEntities = priorState?.entities ?? {};
             // Write app settings. Under `--only`, `app` has to be named — a pull
             // scoped to one workflow must not overwrite app.toml, which is what
@@ -7986,8 +8423,16 @@ export function registerConfigSyncCommands(sync) {
                 // Every writable setting round-trips as of #2891 — the server
                 // withholds nothing — so the pulled file is complete and pushable as
                 // written, with no accompanying note about what it could not carry.
-                writePulledAppSettings(configDir, settings);
-                info("  Wrote app.toml");
+                // On a machine-local environment the tree's name is the shared
+                // tree's, and a pull never writes the child's over it (#4117).
+                const written = writePulledAppSettings(configDir, settings, {
+                    keepStatedName: pullsLocalEnvironment,
+                    tally: pullWrites,
+                });
+                if (written.written)
+                    info("  Wrote app.toml");
+                if (written.note)
+                    warn(`  ${written.note}`);
             }
             // Write config vars (issue #1423). A single flat vars.toml at the
             // sync-dir root (like app.toml), holding the per-environment non-secret
@@ -8027,17 +8472,21 @@ export function registerConfigSyncCommands(sync) {
                         ? Object.fromEntries(Object.entries(parseConfigToml(readFileSync(varsTomlPathPull, "utf-8"))).map(([k, v]) => [k, String(v ?? "")]))
                         : {};
                     const scoped = planScopedVarsPull(varsOutcome.vars, pullSelection.varKeys, localVars, priorEntities.vars);
-                    writeFileSync(varsTomlPathPull, scoped.content);
+                    const varsWritten = writePulledFile(varsTomlPathPull, scoped.content, pullWrites, sameTomlAs(scoped.content));
                     Object.assign(varEntities, scoped.varEntities);
-                    info(`  Wrote vars.toml (${pullSelection.varKeys.size} selected var(s))`);
+                    if (varsWritten) {
+                        info(`  Wrote vars.toml (${pullSelection.varKeys.size} selected var(s))`);
+                    }
                 }
                 else {
                     const varsPlan = planVarsPull(varsOutcome, varsOutcome.ok ? undefined : priorEntities.vars);
                     Object.assign(varEntities, varsPlan.varEntities);
                     if (varsPlan.write && varsPlan.content !== null) {
-                        writeFileSync(varsTomlPathPull, varsPlan.content);
+                        const varsWritten = writePulledFile(varsTomlPathPull, varsPlan.content, pullWrites, sameTomlAs(varsPlan.content));
                         const count = varsOutcome.vars.length;
-                        info(`  Wrote vars.toml (${count} var${count === 1 ? "" : "s"})`);
+                        if (varsWritten) {
+                            info(`  Wrote vars.toml (${count} var${count === 1 ? "" : "s"})`);
+                        }
                     }
                     else {
                         const err = varsOutcome.error;
@@ -8057,16 +8506,18 @@ export function registerConfigSyncCommands(sync) {
             for (const integration of integrations) {
                 const filename = `${integration.integrationKey}.toml`;
                 const filePath = join(configDir, "integrations", filename);
-                writeFileSync(filePath, serializeIntegration(integration, (msg) => info(`  ${msg}`)));
+                const content = serializeIntegration(integration, (msg) => info(`  ${msg}`));
+                const written = writePulledFile(filePath, content, pullWrites, sameConfigAs("integration", content, filePath, integrationPullMaps));
                 integrationEntities[integration.integrationKey] = {
                     id: integration.integrationId,
                     modifiedAt: integration.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
                     // #2880 — the two sides agree right now, so this is the baseline
                     // the next push classifies direction against.
-                    semanticHash: configSemanticHash("integration", filePath, integrationPullMaps),
+                    semanticHash: pulledSemanticHash("integration", content, integrationPullMaps),
                 };
-                info(`  Wrote integrations/${filename}`);
+                if (written)
+                    info(`  Wrote integrations/${filename}`);
             }
             // Pull webhooks. #2803 — an ARCHIVED webhook is retired, not
             // configuration, so it is not exported: writing a tombstone into the
@@ -8091,14 +8542,15 @@ export function registerConfigSyncCommands(sync) {
             for (const webhook of webhooks) {
                 const filename = `${webhook.webhookKey}.toml`;
                 const filePath = join(webhooksDir, filename);
-                writeFileSync(filePath, serializeWebhook(webhook, (msg) => info(`  ${msg}`)));
+                const content = serializeWebhook(webhook, (msg) => info(`  ${msg}`));
+                writePulledFile(filePath, content, pullWrites, sameConfigAs("webhook", content, filePath, webhookPullMaps));
                 webhookEntities[webhook.webhookKey] = {
                     id: webhook.webhookId,
                     modifiedAt: webhook.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
                     // #2880 — the file and the server agree right now, so this is the
                     // baseline the next push classifies direction against.
-                    semanticHash: configSemanticHash("webhook", filePath, webhookPullMaps),
+                    semanticHash: pulledSemanticHash("webhook", content, webhookPullMaps),
                 };
                 // A stored value that is not a reference is never written to TOML, so
                 // pull time is where an operator finds out: a legacy literal from
@@ -8131,6 +8583,24 @@ export function registerConfigSyncCommands(sync) {
                 }
             }
             info(`  Pulled ${webhooks.length} webhook(s)`);
+            // #2731 B4 — pull is one of the two moments local and server provably
+            // agree, so it stamps the semantic baseline beside the byte hash (push
+            // stamps the other one, from the entity the server returned). The
+            // rule-set maps the shared projection resolves references through are
+            // filled here, before the first type that names a rule set (blob
+            // buckets, #4116), from the FULL listing rather than the `--only`
+            // selection: a scoped pull of a bucket must still name its rule set.
+            const ruleSetIdToName = new Map();
+            const ruleSetNameToIdPull = new Map();
+            const pullDiffMaps = {
+                ruleSetIdToName,
+                ruleSetNameToId: ruleSetNameToIdPull,
+            };
+            for (const ruleSet of Array.isArray(ruleSetsResult) ? ruleSetsResult : []) {
+                ruleSetIdToName.set(ruleSet.ruleSetId, ruleSet.name);
+                if (ruleSet.name)
+                    ruleSetNameToIdPull.set(ruleSet.name, ruleSet.ruleSetId);
+            }
             // Pull cron triggers. An older server without the route (or any other
             // failure) leaves the type unlisted — tolerated as before, but recorded
             // so prune skips it rather than reading it as "no cron triggers".
@@ -8139,8 +8609,7 @@ export function registerConfigSyncCommands(sync) {
             const cronTriggersDir = join(configDir, "cron-triggers");
             mkdirSync(cronTriggersDir, { recursive: true });
             const cronTriggerEntities = {};
-            // No rule-set reference on either type, and the pull-wide maps are not
-            // filled until the rule-set leg — see the webhook block above.
+            // No rule-set reference on a cron trigger — see the webhook block above.
             const keylessPullMaps = {
                 ruleSetIdToName: new Map(),
                 ruleSetNameToId: new Map(),
@@ -8148,13 +8617,14 @@ export function registerConfigSyncCommands(sync) {
             for (const trigger of cronTriggerItems) {
                 const filename = `${trigger.triggerKey}.toml`;
                 const filePath = join(cronTriggersDir, filename);
-                writeFileSync(filePath, serializeCronTrigger(trigger, (msg) => info(`  ${msg}`)));
+                const content = serializeCronTrigger(trigger, (msg) => info(`  ${msg}`));
+                writePulledFile(filePath, content, pullWrites, sameConfigAs("cron-trigger", content, filePath, keylessPullMaps));
                 cronTriggerEntities[trigger.triggerKey] = {
                     id: trigger.triggerId,
                     modifiedAt: trigger.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
                     // #2880 — the baseline the next push classifies direction against.
-                    semanticHash: configSemanticHash("cron-trigger", filePath, keylessPullMaps),
+                    semanticHash: pulledSemanticHash("cron-trigger", content, keylessPullMaps),
                 };
             }
             info(`  Pulled ${cronTriggerItems.length} cron trigger(s)`);
@@ -8164,31 +8634,50 @@ export function registerConfigSyncCommands(sync) {
             const blobBucketsDir = join(configDir, "blob-buckets");
             mkdirSync(blobBucketsDir, { recursive: true });
             const blobBucketEntities = {};
+            // #4116 — a bound bucket's file names its rule set, which only the
+            // rule-set listing can supply. When that listing failed, the bucket's
+            // file and sync-state entry are kept as they are rather than rewritten
+            // without the name.
+            const unwrittenBlobBucketKeys = [];
             for (const bucket of blobBucketItems) {
+                if (!ruleSetsOutcome.ok && bucket.ruleSetId) {
+                    unwrittenBlobBucketKeys.push(bucket.bucketKey);
+                    continue;
+                }
                 const filename = `${bucket.bucketKey}.toml`;
                 const filePath = join(blobBucketsDir, filename);
-                writeFileSync(filePath, serializeBlobBucket(bucket, (msg) => info(`  ${msg}`)));
+                const content = serializeBlobBucket(bucket, ruleSetIdToName, (msg) => info(`  ${msg}`));
+                writePulledFile(filePath, content, pullWrites, sameConfigAs("blob-bucket", content, filePath, pullDiffMaps));
                 blobBucketEntities[bucket.bucketKey] = {
                     id: bucket.bucketId,
                     modifiedAt: bucket.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
-                    // #2880 — as for cron triggers.
-                    semanticHash: configSemanticHash("blob-bucket", filePath, keylessPullMaps),
+                    // #2880 — the baseline the next push classifies direction against.
+                    semanticHash: pulledSemanticHash("blob-bucket", content, pullDiffMaps),
                 };
             }
-            info(`  Pulled ${blobBucketItems.length} blob bucket(s)`);
+            info(`  Pulled ${blobBucketItems.length - unwrittenBlobBucketKeys.length} blob bucket(s)`);
+            if (unwrittenBlobBucketKeys.length > 0) {
+                warn(`${unwrittenBlobBucketKeys.length} blob bucket(s) not written — the rule-set ` +
+                    `listing failed, so their ruleSetName is unknown; existing files kept ` +
+                    `(${unwrittenBlobBucketKeys.join(", ")})`);
+            }
             // Write prompts
             const promptEntities = {};
             for (const prompt of prompts) {
                 const filename = `${prompt.promptKey}.toml`;
                 const filePath = join(configDir, "prompts", filename);
-                writeFileSync(filePath, serializePrompt(prompt, (msg) => info(`  ${msg}`)));
+                const content = serializePrompt(prompt, (msg) => info(`  ${msg}`));
+                const written = writePulledFile(filePath, content, pullWrites, 
+                // Prompts carry no rule-set reference.
+                sameConfigAs("prompt", content, filePath, keylessPullMaps));
                 promptEntities[prompt.promptKey] = {
                     id: prompt.promptId,
                     modifiedAt: prompt.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
                 };
-                info(`  Wrote prompts/${filename}`);
+                if (written)
+                    info(`  Wrote prompts/${filename}`);
             }
             // Write workflows
             const workflowEntities = {};
@@ -8214,13 +8703,21 @@ export function registerConfigSyncCommands(sync) {
                 if (reconciled.message) {
                     info(`  ${reconciled.message}`);
                 }
+                let workflowWritten = false;
                 if (reconciled.action === "write-merged") {
                     writeFileSync(filePath, reconciled.content);
+                    pullWrites.written += 1;
+                    workflowWritten = true;
                 }
                 else if (reconciled.action === "write-expanded") {
-                    writeFileSync(filePath, remoteToml);
+                    // #4160 — a file with no fragments that already describes the
+                    // running workflow keeps its bytes.
+                    workflowWritten = writePulledFile(filePath, remoteToml, pullWrites, sameWorkflowAs(workflow.workflowKey, remoteToml));
+                }
+                else {
+                    pullWrites.unchanged += 1;
                 }
-                if (reconciled.action !== "skip") {
+                if (workflowWritten) {
                     info(`  Wrote workflows/${filename}`);
                 }
                 // #2645 — the workflow's OTHER named configs, one file each. The
@@ -8232,8 +8729,11 @@ export function registerConfigSyncCommands(sync) {
                     const sidecarDir = workflowConfigsDir(configDir, workflow.workflowKey);
                     mkdirSync(sidecarDir, { recursive: true });
                     for (const sidecar of sidecars) {
-                        writeFileSync(join(sidecarDir, `${sidecar.name}.toml`), sidecar.content);
-                        info(`  Wrote workflows/${workflow.workflowKey}.configs/${sidecar.name}.toml`);
+                        const sidecarWritten = writePulledFile(join(sidecarDir, `${sidecar.name}.toml`), sidecar.content, pullWrites, (local) => hashWorkflowConfigSidecar(parseConfigToml(local)) ===
+                            hashWorkflowConfigSidecar(parseConfigToml(sidecar.content)));
+                        if (sidecarWritten) {
+                            info(`  Wrote workflows/${workflow.workflowKey}.configs/${sidecar.name}.toml`);
+                        }
                     }
                 }
                 // A sidecar for a config the server no longer has is a file that
@@ -8300,7 +8800,7 @@ export function registerConfigSyncCommands(sync) {
                     return false;
                 matchedSelectors.add(`transform/${name}`);
                 return true;
-            });
+            }, pullWrites);
             if (pulledScriptsCount > 0) {
                 info(`  Pulled ${pulledScriptsCount} transform(s)`);
             }
@@ -8314,79 +8814,49 @@ export function registerConfigSyncCommands(sync) {
                     return false;
                 matchedSelectors.add(`function/${key}`);
                 return true;
-            });
+            }, pullWrites);
             if (pulledFunctionsCount > 0) {
                 info(`  Pulled ${pulledFunctionsCount} function(s)`);
             }
-            // Build lookup maps for test case serialization
-            const configIdToName = new Map();
-            const promptIdToKey = new Map();
-            for (const prompt of prompts) {
-                promptIdToKey.set(prompt.promptId, prompt.promptKey);
-                if (prompt.configs) {
-                    for (const config of prompt.configs) {
-                        configIdToName.set(config.configId, config.configName);
-                    }
-                }
-            }
-            // Also include workflow config names
-            for (const { configs } of workflows) {
-                if (configs) {
-                    for (const config of configs) {
-                        configIdToName.set(config.configId, config.configName);
-                    }
-                }
-            }
-            // Include script config names so a pinned script test case
-            // round-trips its `configName` reference (the same way prompt/workflow
-            // configs above do). One extra `configs` fetch per pulled script.
-            for (const [name, entity] of Object.entries(scriptEntities)) {
+            // Lookup maps for test case serialization (#3998): every prompt's
+            // detail, so a judge prompt outside an `--only` selection still names,
+            // and the configurations of the pulled blocks — a case pins one of its
+            // own block's. A reference these cannot resolve is reported by
+            // `pullTestCasesForBlock`, and its sidecar is not written.
+            const blockConfigs = [];
+            for (const { configs } of workflows)
+                blockConfigs.push(...(configs ?? []));
+            // One `configs` fetch per pulled script and integration. A failed one
+            // is non-fatal: the references it would have named are reported.
+            for (const entity of Object.values(scriptEntities)) {
                 try {
-                    const { items: scriptConfigs } = await client.listScriptConfigs(resolvedAppId, entity.id);
-                    for (const config of scriptConfigs) {
-                        configIdToName.set(config.configId, config.configName);
-                    }
+                    const { items } = await client.listScriptConfigs(resolvedAppId, entity.id);
+                    blockConfigs.push(...items);
                 }
                 catch {
-                    // Non-fatal: a script test case pinned to a config serializes with
-                    // its legacy id spelling instead of a name (#2769), so the pin
-                    // survives. The header/body still pulled fine — `name` retained.
-                    void name;
+                    // Non-fatal — see above.
                 }
             }
-            // Integration config names, for the same reason (#2769). A failed fetch
-            // is non-fatal here too: `serializeTestCase` keeps the pin as `configId`
-            // rather than writing an empty reference.
             for (const integration of integrations) {
                 try {
-                    const { items: integrationConfigs } = await client.listIntegrationConfigs(resolvedAppId, integration.integrationId);
-                    for (const config of integrationConfigs) {
-                        configIdToName.set(config.configId, config.configName);
-                    }
+                    const { items } = await client.listIntegrationConfigs(resolvedAppId, integration.integrationId);
+                    blockConfigs.push(...items);
                 }
                 catch {
                     // Non-fatal — see above.
                 }
             }
-            const testCaseLookupMaps = { configIdToName, promptIdToKey };
-            // #2731 B4 — pull is one of the two moments local and server provably
-            // agree, so it stamps the semantic baseline beside the byte hash (push
-            // stamps the other one, from the entity the server returned). The
-            // rule-set maps the shared projection resolves references through are
-            // declared here and filled below, before the first type that needs
-            // them is written.
-            const ruleSetIdToName = new Map();
-            const ruleSetNameToIdPull = new Map();
-            const pullDiffMaps = {
-                ruleSetIdToName,
-                ruleSetNameToId: ruleSetNameToIdPull,
-            };
+            const testCaseLookupMaps = testCaseLookupMapsForPull({
+                prompts: promptDetails,
+                configs: blockConfigs,
+            });
             // Write email templates (use detailed emailTemplates, not summaries)
             const emailTemplateEntities = {};
             for (const template of emailTemplates) {
                 const filename = `${template.emailType}.toml`;
                 const templatePath = join(configDir, "email-templates", filename);
-                writeFileSync(templatePath, serializeEmailTemplate(template, (msg) => info(`  ${msg}`)));
+                const content = serializeEmailTemplate(template, (msg) => info(`  ${msg}`));
+                const written = writePulledFile(templatePath, content, pullWrites, sameConfigAs("email-template", content, templatePath, pullDiffMaps));
                 emailTemplateEntities[template.emailType] = {
                     id: template.emailType,
                     modifiedAt: template.override?.modifiedAt || new Date().toISOString(),
@@ -8394,9 +8864,10 @@ export function registerConfigSyncCommands(sync) {
                     // live-fetch fallback gates on, and an entry without one fails
                     // closed rather than being blind-upserted.
                     contentHash: computeFileHash(templatePath),
-                    semanticHash: configSemanticHash("email-template", templatePath, pullDiffMaps),
+                    semanticHash: pulledSemanticHash("email-template", content, pullDiffMaps),
                 };
-                info(`  Wrote email-templates/${filename}`);
+                if (written)
+                    info(`  Wrote email-templates/${filename}`);
             }
             // Email-template files for removed overrides used to be cleaned up here
             // by a hand-coded loop — the only type that pruned at all (#1659). It is
@@ -8408,6 +8879,7 @@ export function registerConfigSyncCommands(sync) {
             const testCaseEntities = {};
             const priorTestCaseEntities = priorEntities.testCases;
             let totalTestCases = 0;
+            let unwrittenTestCases = 0;
             for (const [blockType, blocks] of [
                 [
                     "prompt",
@@ -8437,7 +8909,7 @@ export function registerConfigSyncCommands(sync) {
                     })),
                 ],
             ]) {
-                const { count } = await pullTestCasesForBlocks({
+                const { count, unwritten } = await pullTestCasesForBlocks({
                     client,
                     appId: resolvedAppId,
                     configDir,
@@ -8447,16 +8919,22 @@ export function registerConfigSyncCommands(sync) {
                     priorTestCaseEntities,
                     lookupMaps: testCaseLookupMaps,
                     logger: (message) => info(message),
+                    writes: pullWrites,
                 });
                 totalTestCases += count;
+                unwrittenTestCases += unwritten.length;
             }
-            // Build ruleSetId → name map for database types and group type configs
-            const ruleSets = selectPull("rule-set", Array.isArray(ruleSetsResult) ? ruleSetsResult : [], (rs) => ruleSetFileKey(rs));
-            for (const ruleSet of ruleSets) {
-                ruleSetIdToName.set(ruleSet.ruleSetId, ruleSet.name);
-                if (ruleSet.name)
-                    ruleSetNameToIdPull.set(ruleSet.name, ruleSet.ruleSetId);
+            // #3998 — a case pull could not name a reference for is not written, so
+            // its pin is never lost; the count is repeated here so it is not missed
+            // among the per-block lines. Exit status is unchanged, as for every
+            // other partial fetch this command reports.
+            if (unwrittenTestCases > 0) {
+                warn(`${unwrittenTestCases} test case(s) not written — references could not be resolved; see above`);
             }
+            // The rule-set files this pull writes. The reference maps above are
+            // filled from the full listing instead, so a scoped pull of a type that
+            // names a rule set still names it (#4116, DSO-4116-001).
+            const ruleSets = selectPull("rule-set", Array.isArray(ruleSetsResult) ? ruleSetsResult : [], (rs) => ruleSetFileKey(rs));
             // Write database types
             const databaseTypeEntities = {};
             for (const { typeConfig, operations, subscriptions } of databaseTypesWithOps) {
@@ -8468,14 +8946,15 @@ export function registerConfigSyncCommands(sync) {
                 const hints = existsSync(filePath)
                     ? detectExistingOperationForms(readFileSync(filePath, "utf-8"))
                     : undefined;
-                writeFileSync(filePath, serializeDatabaseType(typeConfig, operations, ruleSetIdToName, {
+                const content = serializeDatabaseType(typeConfig, operations, ruleSetIdToName, {
                     hints,
                     defaultForm: "native",
                     logger: (msg) => info(`  ${msg}`),
                     // Issue #803: emit `[[subscriptions]]` blocks so a pull → push
                     // cycle round-trips subscriptions without a spurious diff.
                     subscriptions,
-                }));
+                });
+                const written = writePulledFile(filePath, content, pullWrites, sameConfigAs("database-type-config", content, filePath, pullDiffMaps));
                 const opsEntities = {};
                 for (const op of operations) {
                     opsEntities[op.name] = {
@@ -8499,11 +8978,12 @@ export function registerConfigSyncCommands(sync) {
                     operations: Object.keys(opsEntities).length > 0 ? opsEntities : undefined,
                     subscriptions: Object.keys(subsEntities).length > 0 ? subsEntities : undefined,
                     contentHash: computeFileHash(filePath),
-                    semanticHash: configSemanticHash("database-type-config", filePath, pullDiffMaps),
+                    semanticHash: pulledSemanticHash("database-type-config", content, pullDiffMaps),
                     hasSchema: typeof typeConfig.schema === "string" &&
                         typeConfig.schema.trim().length > 0,
                 };
-                info(`  Wrote database-type-configs/${filename}`);
+                if (written)
+                    info(`  Wrote database-type-configs/${filename}`);
             }
             // #3182 — the typed-handle artifacts are REGENERATED, never pulled:
             // they are not in the envelope, and a fresh clone must end up with the
@@ -8526,14 +9006,16 @@ export function registerConfigSyncCommands(sync) {
                 const fileKey = ruleSetFileKey(ruleSet);
                 const filename = `${fileKey}.toml`;
                 const filePath = join(configDir, "rule-sets", filename);
-                writeFileSync(filePath, serializeRuleSet(ruleSet, (msg) => info(`  ${msg}`)));
+                const content = serializeRuleSet(ruleSet, (msg) => info(`  ${msg}`));
+                const written = writePulledFile(filePath, content, pullWrites, sameConfigAs("rule-set", content, filePath, pullDiffMaps));
                 ruleSetEntities[fileKey] = {
                     id: ruleSet.ruleSetId,
                     modifiedAt: ruleSet.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
-                    semanticHash: configSemanticHash("rule-set", filePath, pullDiffMaps),
+                    semanticHash: pulledSemanticHash("rule-set", content, pullDiffMaps),
                 };
-                info(`  Wrote rule-sets/${filename}`);
+                if (written)
+                    info(`  Wrote rule-sets/${filename}`);
             }
             // Write group type configs
             const groupTypeConfigEntities = {};
@@ -8541,13 +9023,15 @@ export function registerConfigSyncCommands(sync) {
             for (const config of groupTypeConfigs) {
                 const filename = `${config.groupType}.toml`;
                 const filePath = join(configDir, "group-type-configs", filename);
-                writeFileSync(filePath, serializeGroupTypeConfig(config, ruleSetIdToName, (msg) => info(`  ${msg}`)));
+                const content = serializeGroupTypeConfig(config, ruleSetIdToName, (msg) => info(`  ${msg}`));
+                const written = writePulledFile(filePath, content, pullWrites, sameConfigAs("group-type-config", content, filePath, pullDiffMaps));
                 groupTypeConfigEntities[config.groupType] = {
                     modifiedAt: config.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
-                    semanticHash: configSemanticHash("group-type-config", filePath, pullDiffMaps),
+                    semanticHash: pulledSemanticHash("group-type-config", content, pullDiffMaps),
                 };
-                info(`  Wrote group-type-configs/${filename}`);
+                if (written)
+                    info(`  Wrote group-type-configs/${filename}`);
             }
             // Write collection type configs
             const collectionTypeConfigEntities = {};
@@ -8555,13 +9039,15 @@ export function registerConfigSyncCommands(sync) {
             for (const config of collectionTypeConfigs) {
                 const filename = `${config.collectionType}.toml`;
                 const filePath = join(configDir, "collection-type-configs", filename);
-                writeFileSync(filePath, serializeCollectionTypeConfig(config, ruleSetIdToName, (msg) => info(`  ${msg}`)));
+                const content = serializeCollectionTypeConfig(config, ruleSetIdToName, (msg) => info(`  ${msg}`));
+                const written = writePulledFile(filePath, content, pullWrites, sameConfigAs("collection-type-config", content, filePath, pullDiffMaps));
                 collectionTypeConfigEntities[config.collectionType] = {
                     modifiedAt: config.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
-                    semanticHash: configSemanticHash("collection-type-config", filePath, pullDiffMaps),
+                    semanticHash: pulledSemanticHash("collection-type-config", content, pullDiffMaps),
                 };
-                info(`  Wrote collection-type-configs/${filename}`);
+                if (written)
+                    info(`  Wrote collection-type-configs/${filename}`);
             }
             // Write metadata category configs (issue #1304, P-B). One file per
             // `{resourceType, category}`; the entity key is the `resourceType#category`
@@ -8571,13 +9057,15 @@ export function registerConfigSyncCommands(sync) {
             for (const config of metadataCategoryConfigs) {
                 const filename = `${config.resourceType}.${config.category}.toml`;
                 const filePath = join(configDir, "metadata-category-configs", filename);
-                writeFileSync(filePath, serializeMetadataCategoryConfig(config, (msg) => info(`  ${msg}`)));
+                const content = serializeMetadataCategoryConfig(config, (msg) => info(`  ${msg}`));
+                const written = writePulledFile(filePath, content, pullWrites, sameConfigAs("metadata-category-config", content, filePath, pullDiffMaps));
                 metadataCategoryConfigEntities[`${config.resourceType}#${config.category}`] = {
                     modifiedAt: config.modifiedAt || new Date().toISOString(),
                     contentHash: computeFileHash(filePath),
-                    semanticHash: configSemanticHash("metadata-category-config", filePath, pullDiffMaps),
+                    semanticHash: pulledSemanticHash("metadata-category-config", content, pullDiffMaps),
                 };
-                info(`  Wrote metadata-category-configs/${filename}`);
+                if (written)
+                    info(`  Wrote metadata-category-configs/${filename}`);
             }
             // ── Prune reconciliation (issue #1659) ───────────────────────────────
             //
@@ -8727,6 +9215,7 @@ export function registerConfigSyncCommands(sync) {
             preserveUnwrittenEntries(emailTemplateEntities, priorEntities.emailTemplates, emailTemplatesOutcome.ok
                 ? emailTemplateOverrides.map((t) => t.emailType)
                 : []);
+            preserveUnwrittenEntries(blobBucketEntities, priorEntities.blobBuckets, unwrittenBlobBucketKeys);
             const finalCronTriggerEntities = keepPrior(cronTriggersOutcome.ok, cronTriggerEntities, "cronTriggers");
             const finalBlobBucketEntities = keepPrior(blobBucketsOutcome.ok, blobBucketEntities, "blobBuckets");
             const finalScriptEntities = keepPrior(scriptListOk, scriptEntities, "scripts");
@@ -8924,8 +9413,12 @@ export function registerConfigSyncCommands(sync) {
                             // this is the state both sides agree on: the baseline the
                             // next push classifies against. A pull also ends any
                             // cross-app name exclusion, because the file it just wrote
-                            // states the target's own name.
-                            semanticHash: hashAppSettingsForDiff(settings),
+                            // states the target's own name — except on a
+                            // machine-local environment, whose file states the shared
+                            // tree's name and whose baseline never includes one.
+                            semanticHash: hashAppSettingsForDiff(settings, {
+                                excludeName: pullsLocalEnvironment,
+                            }),
                         }
                         : pullSelection
                             ? priorEntities.app
@@ -8952,7 +9445,7 @@ export function registerConfigSyncCommands(sync) {
                         : undefined,
                 },
             };
-            saveSyncState(configDir, state);
+            saveSyncState(state);
             divider();
             success(`Pulled configuration to ${configDir}`);
             keyValue("Config Vars", Object.keys(varEntities).length);
@@ -8966,12 +9459,17 @@ export function registerConfigSyncCommands(sync) {
             keyValue("Functions", pulledFunctionsCount);
             keyValue("Email Templates", emailTemplates.length);
             keyValue("Test Cases", totalTestCases);
+            if (unwrittenTestCases > 0) {
+                keyValue("Test Cases not written", unwrittenTestCases);
+            }
             keyValue("Database Types", databaseTypesWithOps.length);
             keyValue("Rule Sets", ruleSets.length);
             keyValue("Group Type Configs", groupTypeConfigs.length);
             keyValue("Collection Type Configs", collectionTypeConfigs.length);
             keyValue("Metadata Category Configs", metadataCategoryConfigs.length);
             keyValue("Pruned", prunedCount);
+            keyValue("Files written", pullWrites.written);
+            keyValue("Files unchanged", pullWrites.unchanged);
             // A selector the server had nothing for wrote nothing. Say so and fail:
             // otherwise a typo pulls an empty set and reports success, and the
             // operator reads "Pulled configuration" as "my object is now in the
@@ -9079,7 +9577,11 @@ What a push guarantees (two stages):
         // state write holds on the first push and the end-of-run save persists
         // the ids. Without it a successful create-push recorded nothing and the
         // next push re-entered every create path.
-        let syncState = ensurePushSyncState(loadSyncState(configDir), resolvedAppId, getServerUrl());
+        let syncState = ensurePushSyncState(loadSyncState(), resolvedAppId, getServerUrl());
+        // A machine-local environment (#4117) shares a committed environment's
+        // 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;
         // 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;
@@ -9515,6 +10017,7 @@ What a push guarantees (two stages):
                 syncState,
                 force: !!options.force,
                 isCrossAppPush: !!isCrossAppPush,
+                localEnvironment,
                 client,
             });
             // Re-derived, not returned: both are one-line functions of inputs the
@@ -9691,13 +10194,21 @@ What a push guarantees (two stages):
                 // `appNameEdited` — the file has moved away from the recorded name.
                 // That is a local rename BY CONSTRUCTION, not by comparison: no
                 // baseline hashed without `name` can ever attribute it.
+                //
+                // On a machine-local environment (#4117) all three are settled
+                // before they start: the name is the shared tree's, so it is out of
+                // the body and the comparison, and no edit to it is this app's.
                 const payloadExcludesName = appSettingsNameExcluded({
+                    localEnvironment,
                     isCrossAppPush: !!isCrossAppPush,
                     recordedExcludedName,
                     fileName: appFileName,
                 });
-                const compareExcludesName = !!isCrossAppPush || recordedExcludedName !== undefined;
-                const appNameEdited = !isCrossAppPush &&
+                const compareExcludesName = localEnvironment ||
+                    !!isCrossAppPush ||
+                    recordedExcludedName !== undefined;
+                const appNameEdited = !localEnvironment &&
+                    !isCrossAppPush &&
                     recordedExcludedName !== undefined &&
                     !payloadExcludesName;
                 // The whole-truth body. Errors (an unrecognized or retired key, a
@@ -9705,6 +10216,7 @@ What a push guarantees (two stages):
                 // the preflight pass above, so only warnings remain here.
                 const { settings: appPayload, warnings: appWarnings } = buildAppSettingsPayload(tomlData, {
                     excludeName: payloadExcludesName,
+                    nameOptional: localEnvironment,
                 });
                 for (const w of appWarnings) {
                     warn(`  ${w}`);
@@ -9727,8 +10239,12 @@ What a push guarantees (two stages):
                             appEntry?.modifiedAt ||
                             new Date().toISOString(),
                         contentHash: appFileHash,
+                        // Every stamp on a machine-local environment is hashed without
+                        // the name, or the next comparison — which never sees it —
+                        // could not match the baseline (#4117).
                         semanticHash: hashAppSettingsForDiff(baselineSettings, {
-                            excludeName: options.recordExclusion !== undefined ||
+                            excludeName: localEnvironment ||
+                                options.recordExclusion !== undefined ||
                                 (options.keepExclusion && compareExcludesName),
                         }),
                         ...(options.recordExclusion !== undefined
@@ -10936,16 +11452,25 @@ What a push guarantees (two stages):
                 const liveBuckets = new Map();
                 let bucketsLiveOk = true;
                 if (files.length > 0) {
-                    try {
-                        const listed = await client.listBlobBuckets(resolvedAppId);
-                        for (const b of (listed?.items ?? [])) {
-                            if (b?.bucketKey)
-                                liveBuckets.set(b.bucketKey, b);
-                        }
+                    // #4116 — a bound bucket's rule set is compared by name, so the
+                    // comparison needs the rule-set listing; without it the leg
+                    // degrades as the type configs do.
+                    bucketsLiveOk = (await loadLiveRuleSets()).ok;
+                    if (!bucketsLiveOk) {
+                        warnLiveUnavailable("blob-buckets", "rule sets unavailable");
                     }
-                    catch (err) {
-                        bucketsLiveOk = false;
-                        warnLiveUnavailable("blob-buckets", err);
+                    else {
+                        try {
+                            const listed = await client.listBlobBuckets(resolvedAppId);
+                            for (const b of (listed?.items ?? [])) {
+                                if (b?.bucketKey)
+                                    liveBuckets.set(b.bucketKey, b);
+                            }
+                        }
+                        catch (err) {
+                            bucketsLiveOk = false;
+                            warnLiveUnavailable("blob-buckets", err);
+                        }
                     }
                 }
                 const refetchLiveBucket = async (bucketId) => {
@@ -10957,7 +11482,13 @@ What a push guarantees (two stages):
                     const tomlData = parseTomlFile(filePath);
                     const key = tomlData.bucket?.key || basename(file, ".toml");
                     withDerivedIdentity(tomlData, "bucket", { key });
-                    const bucket = tomlData.bucket || {};
+                    // #4116 — `ruleSetName` resolves to THIS app's rule set before any
+                    // request; a name that resolves nowhere fails here, so a bucket is
+                    // never created or updated without its rule set.
+                    const bucket = parseBlobBucketToml(tomlData);
+                    resolveRuleSetReference(bucket, ruleSetNameToId, `blob bucket "${key}"`, {
+                        hint: ruleSetSelectionHint,
+                    });
                     const existingEntry = syncState?.entities?.blobBuckets?.[key];
                     const liveBucket = liveBuckets.get(key);
                     let gate;
@@ -11428,7 +11959,7 @@ What a push guarantees (two stages):
                                 const serverConfig = liveServerConfig(tomlConfig.name);
                                 if (!serverConfig || serverConfig.strictOutput !== true)
                                     continue;
-                                const chat = hoistDeprecatedChatKeys(tomlConfig).entry.chat ?? {};
+                                const chat = tomlConfig.chat ?? {};
                                 const retired = String(tomlConfig?.status ?? "").trim().toLowerCase() ===
                                     "archived";
                                 // An entry that stays strict AND live is refused in preflight
@@ -15662,7 +16193,7 @@ What a push guarantees (two stages):
                 // Update sync state for non-conflicting changes
                 if (syncState) {
                     syncState.lastSyncedAt = new Date().toISOString();
-                    saveSyncState(configDir, syncState);
+                    saveSyncState(syncState);
                 }
                 const successCount = countAppliedChanges({
                     changes,
@@ -15693,7 +16224,7 @@ What a push guarantees (two stages):
                 // Update sync state after push
                 if (syncState) {
                     syncState.lastSyncedAt = new Date().toISOString();
-                    saveSyncState(configDir, syncState);
+                    saveSyncState(syncState);
                 }
                 reportDrift();
                 success(formatPushSummary({
@@ -15718,7 +16249,7 @@ What a push guarantees (two stages):
             if (syncState && recordedProgress && !options.dryRun) {
                 try {
                     syncState.lastSyncedAt = new Date().toISOString();
-                    saveSyncState(configDir, syncState);
+                    saveSyncState(syncState);
                 }
                 catch {
                     // Don't mask the original error
@@ -15751,7 +16282,7 @@ What a push guarantees (two stages):
             error(`Config directory not found: ${configDir}`);
             process.exit(1);
         }
-        const syncState = loadSyncState(configDir);
+        const syncState = loadSyncState();
         // `--only` scopes the comparison the same way it scopes push and pull.
         const diffSelection = readSelection(options);
         // `--only app` on its own IS the retired `settings diff`: it reports the
@@ -15837,7 +16368,6 @@ What a push guarantees (two stages):
             const remoteIntegrations = new Set(integrationItems.map((i) => i.integrationKey));
             const remoteWebhooks = new Set(webhookItems.map((w) => w.webhookKey));
             const remoteCronTriggers = new Set(cronTriggerItemsDiff.map((t) => t.triggerKey));
-            const remoteBlobBuckets = new Set((blobBucketsDiffResult.items || []).map((b) => b.bucketKey));
             const remotePrompts = new Set(promptItems.map((p) => p.promptKey));
             // #1660 — exclude platform-owned workflows (reserved `__internal.*`)
             // from the remote set so `diff` never reports them (they are not app
@@ -15874,7 +16404,6 @@ What a push guarantees (two stages):
             const localIntegrations = new Set();
             const localWebhooks = new Set();
             const localCronTriggers = new Set();
-            const localBlobBuckets = new Set();
             const localPrompts = new Set();
             const localWorkflows = new Set();
             const localEmailTemplates = new Set();
@@ -15950,7 +16479,6 @@ What a push guarantees (two stages):
                 for (const file of readdirSync(blobBucketsDiffDir).filter((f) => f.endsWith(".toml"))) {
                     const tomlData = parseTomlFile(join(blobBucketsDiffDir, file));
                     const key = tomlData.bucket?.key || basename(file, ".toml");
-                    localBlobBuckets.add(key);
                     // #2880 — as above.
                     if (!tomlData.bucket)
                         tomlData.bucket = {};
@@ -16303,23 +16831,6 @@ What a push guarantees (two stages):
                     differences.push({ type: "cron-trigger", key, status: remoteOnlyStatus("cronTriggers", key) });
                 }
             }
-            // Blob Buckets — #2880: the same, and the list row is the record here
-            // too.
-            const blobBucketSpec = configDiffSpec("blob-bucket");
-            const remoteBlobBucketRecords = new Map((blobBucketsDiffResult.items || []).map((b) => [b.bucketKey, b]));
-            for (const key of localBlobBuckets) {
-                if (!remoteBlobBuckets.has(key)) {
-                    differences.push({ type: "blob-bucket", key, status: localOnlyStatus("blobBuckets", key) });
-                    continue;
-                }
-                const { status, hint } = compareLocalToRemote(blobBucketSpec, localBlobBucketsParsed.get(key), remoteBlobBucketRecords.get(key));
-                differences.push({ type: "blob-bucket", key, status, hint });
-            }
-            for (const key of remoteBlobBuckets) {
-                if (!localBlobBuckets.has(key)) {
-                    differences.push({ type: "blob-bucket", key, status: remoteOnlyStatus("blobBuckets", key) });
-                }
-            }
             // Prompts — #2748: content-aware comparison through the shared registry
             // spec, for the reason webhooks got one in #2757. Existence-only
             // reporting meant a prompt's `accessRule` (and every other `[prompt]`
@@ -16745,20 +17256,12 @@ What a push guarantees (two stages):
                         differences.push({ type: typeLabel, key, status: localOnlyStatus(slot, key) });
                         continue;
                     }
-                    let status = "exists";
-                    let hint;
-                    if (!contentComparable) {
-                        // Rule-set list failed, so a `ruleSetName` reference can't be
-                        // resolved on either side — decline the content comparison rather
-                        // than risk a false `Modified`.
-                        hint = "content not compared (rule sets unavailable)";
-                    }
-                    else {
-                        // The shared verdict names the differing field (#3267) and
-                        // degrades a malformed local file to "not compared" rather than
-                        // aborting the whole diff.
-                        ({ status, hint } = compare(parsed, remoteEntities.get(key)));
-                    }
+                    // Rule-set list failed, so a `ruleSetName` reference can't be
+                    // resolved on either side — decline the content comparison rather
+                    // than risk a false `Modified`. Otherwise the shared verdict names
+                    // the differing field (#3267) and degrades a malformed local file
+                    // to "not compared" rather than aborting the whole diff.
+                    const { status, hint } = configDiffRowVerdict(parsed, remoteEntities.get(key), compare, contentComparable);
                     differences.push({ type: typeLabel, key, status, hint });
                 }
                 for (const key of remoteEntities.keys()) {
@@ -16782,6 +17285,9 @@ What a push guarantees (two stages):
             compareByDefinition("group-type-config", "groupTypeConfigs", localGroupTypeConfigsParsed, remoteGroupTypeConfigs, ruleSetsOk);
             compareByDefinition("collection-type-config", "collectionTypeConfigs", localCollectionTypeConfigsParsed, remoteCollectionTypeConfigs, ruleSetsOk);
             compareByDefinition("metadata-category-config", "metadataCategoryConfigs", localMetadataCategoryParsed, remoteMetadataCategoryConfigs, true);
+            // Blob buckets — #2880: the list row is the record. #4116: a bucket
+            // names its rule set, so its rows take the type configs' gate.
+            compareByDefinition("blob-bucket", "blobBuckets", localBlobBucketsParsed, new Map((blobBucketsDiffResult.items || []).map((b) => [b.bucketKey, b])), blobBucketsOutcomeDiff.ok && ruleSetsOk);
             // database-type-configs: the list carries only the type header, so operations
             // and subscriptions are fetched per type (mirroring pull) before the
             // content comparison. A per-type fetch failure degrades that one row to
@@ -16912,12 +17418,16 @@ What a push guarantees (two stages):
                     appRow(VALIDATION_ERROR, `could not parse app.toml: ${err?.message || String(err)}`);
                 }
                 if (appTomlData) {
-                    const excludeName = appSettingsNameExcludedForState(syncState, resolvedAppId, appTomlData);
+                    const diffsLocalEnvironment = requireCurrentEnvironment().local;
+                    const excludeName = appSettingsNameExcludedForState(syncState, resolvedAppId, appTomlData, diffsLocalEnvironment);
                     // The SAME validator push's preflight runs (criterion 1): a
                     // declared-type mismatch, an unrecognized or retired key, and a
                     // missing required key are reported here with push's own message
                     // rather than compared past and called Synced.
-                    const { settings: localAppSettings, errors: appErrors } = buildAppSettingsPayload(appTomlData, { excludeName });
+                    const { settings: localAppSettings, errors: appErrors } = buildAppSettingsPayload(appTomlData, {
+                        excludeName,
+                        nameOptional: diffsLocalEnvironment,
+                    });
                     if (appErrors.length > 0) {
                         appRow(VALIDATION_ERROR, appErrors.join("; "));
                     }
@@ -17322,11 +17832,11 @@ What a push guarantees (two stages):
                     writeFileSync(filePath, rewritten);
                     info(`Migrated database-type-configs/${file}`);
                     // Update content hash in sync state if we have an entry for it.
-                    const syncState = loadSyncState(configDir);
+                    const syncState = loadSyncState();
                     const dbType = typeConfig.databaseType || basename(file, ".toml");
                     if (syncState?.entities?.databaseTypes?.[dbType]) {
                         syncState.entities.databaseTypes[dbType].contentHash = computeFileHash(filePath);
-                        saveSyncState(configDir, syncState);
+                        saveSyncState(syncState);
                     }
                 }
                 migratedCount++;
@@ -17354,11 +17864,11 @@ What a push guarantees (two stages):
                 writeFileSync(filePath, rewritten);
                 info(`Migrated workflows/${file}`);
                 // Update the stored content hash so a subsequent push sees a no-op.
-                const syncState = loadSyncState(configDir);
+                const syncState = loadSyncState();
                 if (syncState?.entities?.workflows?.[workflowKey]) {
                     syncState.entities.workflows[workflowKey].contentHash =
                         computeWorkflowContentHash(configDir, workflowKey, parseTomlFile(filePath));
-                    saveSyncState(configDir, syncState);
+                    saveSyncState(syncState);
                 }
             }
             migratedCount++;
@@ -17496,14 +18006,26 @@ What a push guarantees (two stages):
                 return;
             }
         }
+        // A machine-local environment's baseline lives outside the shared tree
+        // (#4117): the snapshot's baseline goes back there, and the tree's own
+        // baseline — the committed environment's — is left exactly as it is.
+        const baselinePath = requireCurrentEnvironment().local
+            ? resolveSyncStateWritePath()
+            : undefined;
         try {
-            restoreSnapshot(target.path, configDir);
+            restoreSnapshot(target.path, configDir, { baselinePath });
         }
         catch (err) {
             error(`Restore failed: ${err?.message ?? err}`);
             process.exit(1);
         }
-        success(`Restored snapshot ${target.id} into ${configDir} (including ${SYNC_STATE_FILENAME}).`);
+        if (baselinePath) {
+            success(`Restored snapshot ${target.id} into ${configDir} and this environment's baseline into ${baselinePath}.`);
+            info(`The committed baseline in ${configDir} belongs to the shared tree's environment and was left as it was.`);
+        }
+        else {
+            success(`Restored snapshot ${target.id} into ${configDir} (including ${SYNC_STATE_FILENAME}).`);
+        }
         info("Run 'primitive config diff' to inspect the restored state versus the server.");
     });
 }