@madebywild/agent-harness-framework 1.1.0 → 1.3.0

package/dist/engine/entities.js

@@ -1,11 +1,12 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import * as TOML from "@iarna/toml";
 import { DEFAULT_REGISTRY_ID, providerIdSchema } from "@madebywild/agent-harness-manifest";
 import { fetchEntityFromRegistry } from "../entity-registries.js";
-import { DEFAULT_PROMPT_SOURCE_PATH, defaultCommandOverridePath, defaultCommandSourcePath, defaultHookOverridePath, defaultHookSourcePath, defaultMcpOverridePath, defaultMcpSourcePath, defaultPromptOverridePath, defaultSkillOverridePath, defaultSkillSourcePath, defaultSubagentOverridePath, defaultSubagentSourcePath, resolveHarnessPaths, } from "../paths.js";
+import { DEFAULT_PROMPT_SOURCE_PATH, defaultCommandOverridePath, defaultCommandSourcePath, defaultHookOverridePath, defaultHookSourcePath, defaultMcpOverridePath, defaultMcpSourcePath, defaultPromptOverridePath, defaultSettingsSourcePath, defaultSkillOverridePath, defaultSkillSourcePath, defaultSubagentOverridePath, defaultSubagentSourcePath, resolveHarnessPaths, } from "../paths.js";
 import { listFilesRecursively, removeIfExists, writeLock, writeManifest } from "../repository.js";
 import { CLI_ENTITY_TO_MANIFEST_ENTITY, CLI_ENTITY_TYPES } from "../types.js";
-import { ensureParentDir, exists, normalizeRelativePath, nowIso, sha256, stableStringify } from "../utils.js";
+import { ensureParentDir, exists, normalizeRelativePath, nowIso, parseJsonAsRecord, parseTomlAsRecord, sha256, stableStringify, withSingleTrailingNewline, } from "../utils.js";
 import { readLockOrDefault, readManifestOrThrow, removeLockEntityRecord, setLockEntityRecord, upsertLockEntityRecord, writeManagedSourceIndex, } from "./state.js";
 import { computeSkillSourceSha, isSkillOverrideFile, manifestEntityTypeToCliEntityType, registryIdFromInput, resolveEntityRegistrySelection, resolveRemoveTargetId, sortEntities, validateEntityId, } from "./utils.js";
 export async function ensureOverrideFiles(cwd, entityType, entityId, existing) {
@@ -58,6 +59,12 @@ export async function readCurrentSourceSha(cwd, entity) {
         }
         return sha256(stableStringify(parsed));
     }
+    if (entity.type === "settings") {
+        const text = await fs.readFile(sourceAbs, "utf8");
+        const provider = resolveSettingsProviderOrThrow(entity.id);
+        const parsed = parseSettingsPayloadFromText(provider, text, entity.sourcePath);
+        return sha256(stableStringify(parsed));
+    }
     if (entity.type === "command") {
         const text = await fs.readFile(sourceAbs, "utf8");
         return sha256(text);
@@ -80,6 +87,29 @@ export async function loadSkillSourceHashes(skillRootAbs) {
     output.sort((left, right) => left.path.localeCompare(right.path));
     return output;
 }
+function resolveSettingsProviderOrThrow(id) {
+    try {
+        return providerIdSchema.parse(id);
+    }
+    catch {
+        throw new Error(`Settings id must be one of: ${providerIdSchema.options.join(", ")}`);
+    }
+}
+function parseSettingsPayloadFromText(provider, text, sourcePath) {
+    try {
+        return provider === "codex" ? parseTomlAsRecord(text, TOML) : parseJsonAsRecord(text);
+    }
+    catch (error) {
+        const format = provider === "codex" ? "TOML" : "JSON";
+        throw new Error(`Settings source '${sourcePath}' is invalid ${format}: ${error instanceof Error ? error.message : "unknown error"}`);
+    }
+}
+function serializeSettingsPayload(provider, payload) {
+    if (provider === "codex") {
+        return withSingleTrailingNewline(TOML.stringify(payload));
+    }
+    return stableStringify(payload);
+}
 export async function materializeFetchedEntity(cwd, entity, fetched) {
     if (entity.type === "prompt" && fetched.type === "prompt") {
         const sourceAbs = path.join(cwd, entity.sourcePath);
@@ -105,6 +135,12 @@ export async function materializeFetchedEntity(cwd, entity, fetched) {
         await fs.writeFile(sourceAbs, fetched.sourceText, "utf8");
         return;
     }
+    if (entity.type === "settings" && fetched.type === "settings") {
+        const sourceAbs = path.join(cwd, entity.sourcePath);
+        await ensureParentDir(sourceAbs);
+        await fs.writeFile(sourceAbs, serializeSettingsPayload(fetched.provider, fetched.sourcePayload), "utf8");
+        return;
+    }
     if (entity.type === "command" && fetched.type === "command") {
         const sourceAbs = path.join(cwd, entity.sourcePath);
         await ensureParentDir(sourceAbs);
@@ -146,18 +182,29 @@ export async function addPromptEntity(cwd, options) {
     if (await exists(sourceAbs)) {
         throw new Error(`Cannot add prompt because '${sourcePath}' already exists`);
     }
-    const registry = resolveEntityRegistrySelection(manifest, options?.registry);
-    let sourceText = "# System Prompt\n\nDescribe the core behavior for the assistant.\n";
+    let sourceText;
+    let registryId;
     let importedSourceSha256;
     let registryRevision;
-    if (registry.definition.type === "git") {
-        const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "prompt", "system");
-        if (fetched.type !== "prompt") {
-            throw new Error(`REGISTRY_FETCH_FAILED: expected prompt from registry '${registry.id}'`);
+    if (options?.sourceText) {
+        sourceText = options.sourceText;
+        registryId = DEFAULT_REGISTRY_ID;
+    }
+    else {
+        const registry = resolveEntityRegistrySelection(manifest, options?.registry);
+        registryId = registry.id;
+        if (registry.definition.type === "git") {
+            const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "prompt", "system");
+            if (fetched.type !== "prompt") {
+                throw new Error(`REGISTRY_FETCH_FAILED: expected prompt from registry '${registry.id}'`);
+            }
+            sourceText = fetched.sourceText;
+            importedSourceSha256 = fetched.importedSourceSha256;
+            registryRevision = fetched.registryRevision;
+        }
+        else {
+            sourceText = "# System Prompt\n\nDescribe the core behavior for the assistant.\n";
         }
-        sourceText = fetched.sourceText;
-        importedSourceSha256 = fetched.importedSourceSha256;
-        registryRevision = fetched.registryRevision;
     }
     await ensureParentDir(sourceAbs);
     await fs.writeFile(sourceAbs, sourceText, "utf8");
@@ -165,7 +212,7 @@ export async function addPromptEntity(cwd, options) {
     manifest.entities.push({
         id: "system",
         type: "prompt",
-        registry: registry.id,
+        registry: registryId,
         sourcePath,
         overrides,
         enabled: true,
@@ -176,7 +223,7 @@ export async function addPromptEntity(cwd, options) {
     await upsertLockEntityRecord(paths, manifest, {
         id: "system",
         type: "prompt",
-        registry: registry.id,
+        registry: registryId,
         sourceSha256: sha256(sourceText),
         overrideSha256ByProvider: overrideShaByProvider,
         importedSourceSha256,
@@ -196,35 +243,48 @@ export async function addSkillEntity(cwd, skillId, options) {
     if (await exists(skillRootAbs)) {
         throw new Error(`Cannot add skill because '${skillRootRel}' already exists`);
     }
-    const registry = resolveEntityRegistrySelection(manifest, options?.registry);
     let sourceSha256;
+    let registryId;
     let importedSourceSha256;
     let registryRevision;
     let skillFiles;
-    if (registry.definition.type === "git") {
-        const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "skill", skillId);
-        if (fetched.type !== "skill") {
-            throw new Error(`REGISTRY_FETCH_FAILED: expected skill '${skillId}' from registry '${registry.id}'`);
-        }
-        skillFiles = fetched.files.map((file) => ({
-            path: file.path,
+    if (options?.files) {
+        skillFiles = options.files.map((file) => ({
+            path: normalizeRelativePath(file.path),
             content: file.content,
-            sha256: file.sha256,
+            sha256: sha256(file.content),
         }));
-        sourceSha256 = fetched.importedSourceSha256;
-        importedSourceSha256 = fetched.importedSourceSha256;
-        registryRevision = fetched.registryRevision;
+        sourceSha256 = computeSkillSourceSha(skillFiles.map((file) => ({ path: file.path, sha256: file.sha256 })));
+        registryId = DEFAULT_REGISTRY_ID;
     }
     else {
-        const content = `---\nname: ${skillId}\ndescription: Describe what this skill does.\n---\n\n# ${skillId}\n\nAdd usage guidance here.\n`;
-        skillFiles = [
-            {
-                path: "SKILL.md",
-                content,
-                sha256: sha256(content),
-            },
-        ];
-        sourceSha256 = computeSkillSourceSha(skillFiles.map((file) => ({ path: file.path, sha256: file.sha256 })));
+        const registry = resolveEntityRegistrySelection(manifest, options?.registry);
+        registryId = registry.id;
+        if (registry.definition.type === "git") {
+            const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "skill", skillId);
+            if (fetched.type !== "skill") {
+                throw new Error(`REGISTRY_FETCH_FAILED: expected skill '${skillId}' from registry '${registry.id}'`);
+            }
+            skillFiles = fetched.files.map((file) => ({
+                path: file.path,
+                content: file.content,
+                sha256: file.sha256,
+            }));
+            sourceSha256 = fetched.importedSourceSha256;
+            importedSourceSha256 = fetched.importedSourceSha256;
+            registryRevision = fetched.registryRevision;
+        }
+        else {
+            const content = `---\nname: ${skillId}\ndescription: Describe what this skill does.\n---\n\n# ${skillId}\n\nAdd usage guidance here.\n`;
+            skillFiles = [
+                {
+                    path: "SKILL.md",
+                    content,
+                    sha256: sha256(content),
+                },
+            ];
+            sourceSha256 = computeSkillSourceSha(skillFiles.map((file) => ({ path: file.path, sha256: file.sha256 })));
+        }
     }
     for (const file of skillFiles) {
         const absolute = path.join(skillRootAbs, file.path);
@@ -235,7 +295,7 @@ export async function addSkillEntity(cwd, skillId, options) {
     manifest.entities.push({
         id: skillId,
         type: "skill",
-        registry: registry.id,
+        registry: registryId,
         sourcePath,
         overrides,
         enabled: true,
@@ -246,7 +306,7 @@ export async function addSkillEntity(cwd, skillId, options) {
     await upsertLockEntityRecord(paths, manifest, {
         id: skillId,
         type: "skill",
-        registry: registry.id,
+        registry: registryId,
         sourceSha256,
         overrideSha256ByProvider: overrideShaByProvider,
         importedSourceSha256,
@@ -265,28 +325,36 @@ export async function addMcpEntity(cwd, configId, options) {
     if (await exists(sourceAbs)) {
         throw new Error(`Cannot add MCP config because '${sourcePath}' already exists`);
     }
-    const registry = resolveEntityRegistrySelection(manifest, options?.registry);
     let sourceJson;
+    let registryId;
     let importedSourceSha256;
     let registryRevision;
-    if (registry.definition.type === "git") {
-        const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "mcp_config", configId);
-        if (fetched.type !== "mcp_config") {
-            throw new Error(`REGISTRY_FETCH_FAILED: expected mcp config '${configId}' from registry '${registry.id}'`);
-        }
-        sourceJson = fetched.sourceJson;
-        importedSourceSha256 = fetched.importedSourceSha256;
-        registryRevision = fetched.registryRevision;
+    if (options?.sourceJson) {
+        sourceJson = options.sourceJson;
+        registryId = DEFAULT_REGISTRY_ID;
     }
     else {
-        sourceJson = {
-            servers: {
-                [configId]: {
-                    command: "echo",
-                    args: ["configure-this-mcp-server"],
+        const registry = resolveEntityRegistrySelection(manifest, options?.registry);
+        registryId = registry.id;
+        if (registry.definition.type === "git") {
+            const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "mcp_config", configId);
+            if (fetched.type !== "mcp_config") {
+                throw new Error(`REGISTRY_FETCH_FAILED: expected mcp config '${configId}' from registry '${registry.id}'`);
+            }
+            sourceJson = fetched.sourceJson;
+            importedSourceSha256 = fetched.importedSourceSha256;
+            registryRevision = fetched.registryRevision;
+        }
+        else {
+            sourceJson = {
+                servers: {
+                    [configId]: {
+                        command: "echo",
+                        args: ["configure-this-mcp-server"],
+                    },
                 },
-            },
-        };
+            };
+        }
     }
     const sourceContent = stableStringify(sourceJson);
     await ensureParentDir(sourceAbs);
@@ -295,7 +363,7 @@ export async function addMcpEntity(cwd, configId, options) {
     manifest.entities.push({
         id: configId,
         type: "mcp_config",
-        registry: registry.id,
+        registry: registryId,
         sourcePath,
         overrides,
         enabled: true,
@@ -306,7 +374,7 @@ export async function addMcpEntity(cwd, configId, options) {
     await upsertLockEntityRecord(paths, manifest, {
         id: configId,
         type: "mcp_config",
-        registry: registry.id,
+        registry: registryId,
         sourceSha256: sha256(stableStringify(sourceJson)),
         overrideSha256ByProvider: overrideShaByProvider,
         importedSourceSha256,
@@ -325,23 +393,31 @@ export async function addSubagentEntity(cwd, subagentId, options) {
     if (await exists(sourceAbs)) {
         throw new Error(`Cannot add subagent because '${sourcePath}' already exists`);
     }
-    const registry = resolveEntityRegistrySelection(manifest, options?.registry);
     let sourceText;
+    let registryId;
     let importedSourceSha256;
     let registryRevision;
-    if (registry.definition.type === "git") {
-        const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "subagent", subagentId);
-        if (fetched.type !== "subagent") {
-            throw new Error(`REGISTRY_FETCH_FAILED: expected subagent '${subagentId}' from registry '${registry.id}'`);
-        }
-        sourceText = fetched.sourceText;
-        importedSourceSha256 = fetched.importedSourceSha256;
-        registryRevision = fetched.registryRevision;
+    if (options?.sourceText) {
+        sourceText = options.sourceText;
+        registryId = DEFAULT_REGISTRY_ID;
     }
     else {
-        sourceText =
-            `---\nname: ${subagentId}\ndescription: Describe what this subagent does.\n---\n\n` +
-                `You are the ${subagentId} subagent.\n\nAdd instructions here.\n`;
+        const registry = resolveEntityRegistrySelection(manifest, options?.registry);
+        registryId = registry.id;
+        if (registry.definition.type === "git") {
+            const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "subagent", subagentId);
+            if (fetched.type !== "subagent") {
+                throw new Error(`REGISTRY_FETCH_FAILED: expected subagent '${subagentId}' from registry '${registry.id}'`);
+            }
+            sourceText = fetched.sourceText;
+            importedSourceSha256 = fetched.importedSourceSha256;
+            registryRevision = fetched.registryRevision;
+        }
+        else {
+            sourceText =
+                `---\nname: ${subagentId}\ndescription: Describe what this subagent does.\n---\n\n` +
+                    `You are the ${subagentId} subagent.\n\nAdd instructions here.\n`;
+        }
     }
     await ensureParentDir(sourceAbs);
     await fs.writeFile(sourceAbs, sourceText, "utf8");
@@ -349,7 +425,7 @@ export async function addSubagentEntity(cwd, subagentId, options) {
     manifest.entities.push({
         id: subagentId,
         type: "subagent",
-        registry: registry.id,
+        registry: registryId,
         sourcePath,
         overrides,
         enabled: true,
@@ -360,7 +436,7 @@ export async function addSubagentEntity(cwd, subagentId, options) {
     await upsertLockEntityRecord(paths, manifest, {
         id: subagentId,
         type: "subagent",
-        registry: registry.id,
+        registry: registryId,
         sourceSha256: sha256(sourceText),
         overrideSha256ByProvider: overrideShaByProvider,
         importedSourceSha256,
@@ -379,31 +455,39 @@ export async function addHookEntity(cwd, hookId, options) {
     if (await exists(sourceAbs)) {
         throw new Error(`Cannot add hook because '${sourcePath}' already exists`);
     }
-    const registry = resolveEntityRegistrySelection(manifest, options?.registry);
     let sourceJson;
+    let registryId;
     let importedSourceSha256;
     let registryRevision;
-    if (registry.definition.type === "git") {
-        const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "hook", hookId);
-        if (fetched.type !== "hook") {
-            throw new Error(`REGISTRY_FETCH_FAILED: expected hook '${hookId}' from registry '${registry.id}'`);
-        }
-        sourceJson = fetched.sourceJson;
-        importedSourceSha256 = fetched.importedSourceSha256;
-        registryRevision = fetched.registryRevision;
+    if (options?.sourceJson) {
+        sourceJson = options.sourceJson;
+        registryId = DEFAULT_REGISTRY_ID;
     }
     else {
-        sourceJson = {
-            mode: "best_effort",
-            events: {
-                pre_tool_use: [
-                    {
-                        type: "command",
-                        command: "echo 'replace-with-hook-command'",
-                    },
-                ],
-            },
-        };
+        const registry = resolveEntityRegistrySelection(manifest, options?.registry);
+        registryId = registry.id;
+        if (registry.definition.type === "git") {
+            const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "hook", hookId);
+            if (fetched.type !== "hook") {
+                throw new Error(`REGISTRY_FETCH_FAILED: expected hook '${hookId}' from registry '${registry.id}'`);
+            }
+            sourceJson = fetched.sourceJson;
+            importedSourceSha256 = fetched.importedSourceSha256;
+            registryRevision = fetched.registryRevision;
+        }
+        else {
+            sourceJson = {
+                mode: "best_effort",
+                events: {
+                    pre_tool_use: [
+                        {
+                            type: "command",
+                            command: "echo 'replace-with-hook-command'",
+                        },
+                    ],
+                },
+            };
+        }
     }
     const sourceContent = stableStringify(sourceJson);
     await ensureParentDir(sourceAbs);
@@ -412,7 +496,7 @@ export async function addHookEntity(cwd, hookId, options) {
     manifest.entities.push({
         id: hookId,
         type: "hook",
-        registry: registry.id,
+        registry: registryId,
         sourcePath,
         overrides,
         enabled: true,
@@ -423,13 +507,70 @@ export async function addHookEntity(cwd, hookId, options) {
     await upsertLockEntityRecord(paths, manifest, {
         id: hookId,
         type: "hook",
-        registry: registry.id,
+        registry: registryId,
         sourceSha256: sha256(stableStringify(sourceJson)),
         overrideSha256ByProvider: overrideShaByProvider,
         importedSourceSha256,
         registryRevision,
     });
 }
+export async function addSettingsEntity(cwd, provider, options) {
+    const settingsProvider = providerIdSchema.parse(provider);
+    const paths = resolveHarnessPaths(cwd);
+    const manifest = await readManifestOrThrow(paths);
+    if (manifest.entities.some((entity) => entity.type === "settings" && entity.id === settingsProvider)) {
+        throw new Error(`Settings '${settingsProvider}' already exists`);
+    }
+    const sourcePath = defaultSettingsSourcePath(settingsProvider);
+    const sourceAbs = path.join(cwd, sourcePath);
+    if (await exists(sourceAbs)) {
+        throw new Error(`Cannot add settings because '${sourcePath}' already exists`);
+    }
+    let sourcePayload;
+    let registryId;
+    let importedSourceSha256;
+    let registryRevision;
+    if (options?.sourcePayload) {
+        sourcePayload = options.sourcePayload;
+        registryId = DEFAULT_REGISTRY_ID;
+    }
+    else {
+        const registry = resolveEntityRegistrySelection(manifest, options?.registry);
+        registryId = registry.id;
+        sourcePayload = {};
+        if (registry.definition.type === "git") {
+            const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "settings", settingsProvider);
+            if (fetched.type !== "settings") {
+                throw new Error(`REGISTRY_FETCH_FAILED: expected settings '${settingsProvider}' from registry '${registry.id}'`);
+            }
+            sourcePayload = fetched.sourcePayload;
+            importedSourceSha256 = fetched.importedSourceSha256;
+            registryRevision = fetched.registryRevision;
+        }
+    }
+    const sourceContent = serializeSettingsPayload(settingsProvider, sourcePayload);
+    await ensureParentDir(sourceAbs);
+    await fs.writeFile(sourceAbs, sourceContent, "utf8");
+    manifest.entities.push({
+        id: settingsProvider,
+        type: "settings",
+        registry: registryId,
+        sourcePath,
+        enabled: true,
+    });
+    manifest.entities = sortEntities(manifest.entities);
+    await writeManifest(paths, manifest);
+    await writeManagedSourceIndex(paths, manifest);
+    await upsertLockEntityRecord(paths, manifest, {
+        id: settingsProvider,
+        type: "settings",
+        registry: registryId,
+        sourceSha256: sha256(sourceContent),
+        overrideSha256ByProvider: {},
+        importedSourceSha256,
+        registryRevision,
+    });
+}
 export async function addCommandEntity(cwd, commandId, options) {
     validateEntityId(commandId, "command");
     const paths = resolveHarnessPaths(cwd);
@@ -442,21 +583,29 @@ export async function addCommandEntity(cwd, commandId, options) {
     if (await exists(sourceAbs)) {
         throw new Error(`Cannot add command because '${sourcePath}' already exists`);
     }
-    const registry = resolveEntityRegistrySelection(manifest, options?.registry);
     let sourceText;
+    let registryId;
     let importedSourceSha256;
     let registryRevision;
-    if (registry.definition.type === "git") {
-        const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "command", commandId);
-        if (fetched.type !== "command") {
-            throw new Error(`REGISTRY_FETCH_FAILED: expected command '${commandId}' from registry '${registry.id}'`);
-        }
-        sourceText = fetched.sourceText;
-        importedSourceSha256 = fetched.importedSourceSha256;
-        registryRevision = fetched.registryRevision;
+    if (options?.sourceText) {
+        sourceText = options.sourceText;
+        registryId = DEFAULT_REGISTRY_ID;
     }
     else {
-        sourceText = `---\ndescription: "Describe what this command does"\n---\n\n# ${commandId}\n\nDescribe the task here. Use $ARGUMENTS to reference arguments passed to this command.\n`;
+        const registry = resolveEntityRegistrySelection(manifest, options?.registry);
+        registryId = registry.id;
+        if (registry.definition.type === "git") {
+            const fetched = await fetchEntityFromRegistry(registry.id, registry.definition, "command", commandId);
+            if (fetched.type !== "command") {
+                throw new Error(`REGISTRY_FETCH_FAILED: expected command '${commandId}' from registry '${registry.id}'`);
+            }
+            sourceText = fetched.sourceText;
+            importedSourceSha256 = fetched.importedSourceSha256;
+            registryRevision = fetched.registryRevision;
+        }
+        else {
+            sourceText = `---\ndescription: "Describe what this command does"\n---\n\n# ${commandId}\n\nDescribe the task here. Use $ARGUMENTS to reference arguments passed to this command.\n`;
+        }
     }
     await ensureParentDir(sourceAbs);
     await fs.writeFile(sourceAbs, sourceText, "utf8");
@@ -464,7 +613,7 @@ export async function addCommandEntity(cwd, commandId, options) {
     manifest.entities.push({
         id: commandId,
         type: "command",
-        registry: registry.id,
+        registry: registryId,
         sourcePath,
         overrides,
         enabled: true,
@@ -475,7 +624,7 @@ export async function addCommandEntity(cwd, commandId, options) {
     await upsertLockEntityRecord(paths, manifest, {
         id: commandId,
         type: "command",
-        registry: registry.id,
+        registry: registryId,
         sourceSha256: sha256(sourceText),
         overrideSha256ByProvider: overrideShaByProvider,
         importedSourceSha256,
@@ -532,15 +681,22 @@ export async function pullRegistryEntities(cwd, options) {
     for (const planned of plannedUpdates) {
         const { entity, fetched } = planned;
         await materializeFetchedEntity(cwd, entity, fetched);
-        const ensuredOverrides = await ensureOverrideFiles(cwd, entity.type, entity.id, entity.overrides);
-        entity.overrides = ensuredOverrides.overrides;
-        manifestMutated = true;
+        let overrideShaByProvider = {};
+        if (entity.type !== "settings") {
+            const ensuredOverrides = await ensureOverrideFiles(cwd, entity.type, entity.id, entity.overrides);
+            entity.overrides = ensuredOverrides.overrides;
+            overrideShaByProvider = ensuredOverrides.overrideShaByProvider;
+            manifestMutated = true;
+        }
+        const sourceSha256ForLock = entity.type === "settings" && fetched.type === "settings"
+            ? sha256(serializeSettingsPayload(fetched.provider, fetched.sourcePayload))
+            : fetched.importedSourceSha256;
         setLockEntityRecord(lock, {
             id: entity.id,
             type: entity.type,
             registry: entity.registry,
-            sourceSha256: fetched.importedSourceSha256,
-            overrideSha256ByProvider: ensuredOverrides.overrideShaByProvider,
+            sourceSha256: sourceSha256ForLock,
+            overrideSha256ByProvider: overrideShaByProvider,
             importedSourceSha256: fetched.importedSourceSha256,
             registryRevision: fetched.registryRevision,
         });