primitive-admin 1.2.0-alpha.1 → 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,6 +1667,73 @@ 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.
  *
@@ -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
@@ -1737,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.
@@ -1745,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,
@@ -2059,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),
@@ -2193,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,
@@ -2300,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
@@ -2373,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
@@ -2514,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
@@ -2530,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}`);
@@ -2671,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.
@@ -2691,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.
@@ -2766,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;
@@ -2801,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.
@@ -2859,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,
@@ -2897,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
@@ -2918,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,
@@ -2944,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})`);
@@ -3165,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 = [];
@@ -3205,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({
@@ -4810,20 +4970,14 @@ const CONFIG_DIFF_SPECS = {
     "blob-bucket": {
         label: "blob-bucket",
         table: BLOB_BUCKET_TABLE,
-        parse: (doc) => {
-            const bucket = { ...(doc?.bucket ?? {}) };
-            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, {
@@ -4847,7 +5001,12 @@ const CONFIG_DIFF_SPECS = {
                 keys.push("name");
             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;
         },
@@ -4964,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.
@@ -4972,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).
@@ -5486,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).
  *
@@ -5891,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 = {};
@@ -5944,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(),
@@ -5957,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
@@ -6033,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 = {};
@@ -6076,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;
@@ -6137,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);
@@ -6175,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
@@ -6347,7 +6593,7 @@ export async function pullTestCasesForBlock(params) {
         pulledSlugs.add(slug);
         // Write test case TOML
         const tomlPath = join(testsDir, `${slug}.toml`);
-        writeFileSync(tomlPath, toml);
+        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
@@ -6371,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) {
@@ -6557,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);
@@ -7881,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.");
     });
@@ -7900,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}`);
         }
@@ -8106,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);
@@ -8135,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
@@ -8166,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
@@ -8207,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;
@@ -8237,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
@@ -8271,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
@@ -8311,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".
@@ -8319,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(),
@@ -8328,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)`);
@@ -8344,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 = {};
@@ -8394,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
@@ -8412,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
@@ -8480,7 +8800,7 @@ export function registerConfigSyncCommands(sync) {
                     return false;
                 matchedSelectors.add(`transform/${name}`);
                 return true;
-            });
+            }, pullWrites);
             if (pulledScriptsCount > 0) {
                 info(`  Pulled ${pulledScriptsCount} transform(s)`);
             }
@@ -8494,7 +8814,7 @@ export function registerConfigSyncCommands(sync) {
                     return false;
                 matchedSelectors.add(`function/${key}`);
                 return true;
-            });
+            }, pullWrites);
             if (pulledFunctionsCount > 0) {
                 info(`  Pulled ${pulledFunctionsCount} function(s)`);
             }
@@ -8530,24 +8850,13 @@ export function registerConfigSyncCommands(sync) {
                 prompts: promptDetails,
                 configs: blockConfigs,
             });
-            // #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,
-            };
             // 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(),
@@ -8555,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
@@ -8609,6 +8919,7 @@ export function registerConfigSyncCommands(sync) {
                     priorTestCaseEntities,
                     lookupMaps: testCaseLookupMaps,
                     logger: (message) => info(message),
+                    writes: pullWrites,
                 });
                 totalTestCases += count;
                 unwrittenTestCases += unwritten.length;
@@ -8620,13 +8931,10 @@ export function registerConfigSyncCommands(sync) {
             if (unwrittenTestCases > 0) {
                 warn(`${unwrittenTestCases} test case(s) not written — references could not be resolved; see above`);
             }
-            // Build ruleSetId → name map for database types and group type configs
+            // 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));
-            for (const ruleSet of ruleSets) {
-                ruleSetIdToName.set(ruleSet.ruleSetId, ruleSet.name);
-                if (ruleSet.name)
-                    ruleSetNameToIdPull.set(ruleSet.name, ruleSet.ruleSetId);
-            }
             // Write database types
             const databaseTypeEntities = {};
             for (const { typeConfig, operations, subscriptions } of databaseTypesWithOps) {
@@ -8638,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] = {
@@ -8669,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
@@ -8696,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 = {};
@@ -8711,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 = {};
@@ -8725,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`
@@ -8741,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) ───────────────────────────────
             //
@@ -8897,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");
@@ -9094,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
@@ -9122,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);
@@ -9145,6 +9468,8 @@ export function registerConfigSyncCommands(sync) {
             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
@@ -9252,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;
@@ -9688,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
@@ -9864,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
@@ -9878,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}`);
@@ -9900,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
@@ -11109,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) => {
@@ -11130,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;
@@ -11601,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
@@ -15835,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,
@@ -15866,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({
@@ -15891,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
@@ -15924,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
@@ -16010,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
@@ -16047,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();
@@ -16123,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 = {};
@@ -16476,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]`
@@ -16918,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()) {
@@ -16955,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
@@ -17085,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("; "));
                     }
@@ -17495,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++;
@@ -17527,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++;
@@ -17669,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.");
     });
 }