@humwick/server 0.0.0-stage → 0.130.0

package/src/config-store.ts

@@ -0,0 +1,1253 @@
+import { cleanGateLimits } from "@humwick/sdk";
+import { recordConfigHistory } from "./db/provider-config-history";
+import { applyProfilePromptEntry, applyProfilePromptSlots, resetProfilePromptSlots, writeProfilePromptSlots } from "./db/prompt-versions";
+import { memoryRetirementMessage } from "./memory-retirement";
+import { cleanProfileWorkflows } from "./profile-workflow-policy";
+import { revokeRemovedVaultAccess } from "./db/vault-tokens";
+import { cleanServiceAccess, validateServiceCatalog } from "./service-access/validation";
+import { CHANNEL_OUTPUT_NAMESPACE, validateChannelOutputControl } from "./channel-output-validation";
+// Imported from the connection module rather than the `./db` barrel: #1700 gave src/db/channels.ts
+// a `../config-store.ts` import, and going through the barrel closes that into a cycle
+// (db → db/index → db/agents → db/channels → config-store → db). connection.ts owns both symbols
+// and pulls in no db domain modules, so this is also the barrel rule applied — behaviour comes from
+// the domain module. src/validation.ts already sources ValidationError the same way.
+import { getDb, ValidationError, writeTransaction } from "./db/connection.ts";
+import { deletePolicySelfEffortInternal } from "./db/self-effort-permissions";
+import { profileMatrixEnabled } from "./config";
+import { cleanEnum, cleanString, cleanStringArray } from "./validation";
+import { assertLaunchModeSupported } from "./launch-mode-support";
+import {
+  NOTIFICATIONS_CONFIG_DEFAULTS,
+  NOTIFICATIONS_DEFAULT_KEY,
+  NOTIFICATIONS_NAMESPACE,
+  parseNotificationSettingsKey,
+  validateNotificationSettingsLayer,
+  validateNotificationsConfig,
+} from "./notification-settings";
+import { validateSelfResumeConfig } from "./self-resume-config";
+import { WORKSPACE_CONFIG_DEFAULTS } from "./workspace-config";
+import { RETENTION_NAMESPACE, validateRetentionConfig } from "./retention-config";
+import { TEAM_TEMPLATE_NAMESPACE, validateTeamTemplate } from "./team-template-config";
+import { PROVIDER_ENABLEMENT_NAMESPACE, validateProviderEnablement } from "./provider-enablement";
+import { HOST_PROVIDER_ENABLEMENT_NAMESPACE, validateHostProviderEnablement } from "./host-provider-enablement";
+import { normalizeConfigModelSelection } from "./config-model-selection";
+import { RESERVED_SYNTHETIC_AUDIENCE } from "./memory-inject-filter";
+import { agentProfileDefaults, BUILT_IN_AGENT_PROFILE_NAMES, builtInAgentProfile, builtInAgentProfiles, legacyProfileAliasPinsHost, profileProviderRefusal } from "./agent-profile-catalog";
+import { PROJECT_MCP_POLICY_NAMES } from "./project-mcp";
+import { PROJECT_SETTINGS_POLICY_NAMES } from "./project-settings";
+import { parseNativeMemory } from "./native-memory";
+import { PROJECT_SKILLS_POLICY_NAMES } from "./project-skills"; import { cleanProfileProjectAck, cleanProfileProjectTrust } from "./profile-project-validation";
+import { SHARED_MCP_POLICY_NAMES } from "./shared-mcp";
+
+import { resolveRelayTools } from "./mcp/tool-groups";
+import { cleanLandStackDepth } from "./land-stack-depth";
+import { cleanAgentProfileProviderOptions } from "./profile-provider-options";
+import { reconcileHostCellInputs, withSyncedHostCells } from "./profile-host-sources";
+import type { ProviderEffort } from "@humwick/sdk/provider-catalog";
+import { AGENT_PROFILE_MESSAGING_POLICIES, canonicalAgentProfileName, isRecord, isSpawnProvider, LAUNCH_MODES, projectInstructionsOn, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, WEB_TOOL_NAMES } from "@humwick/sdk";
+import type {
+  AgentProfile,
+  ServiceAccessCatalog,
+  AgentProfileBase,
+  ProfileSourceMatrix,
+  ProfileToggleCell,
+  ProfileAssetCell,
+  ProfileProjectPolicyCell,
+  ProfileRelayInstructionsCell,
+  ProfileRelayMcpCell,
+  ConfigEntry,
+  ConfigHistoryEntry,
+  InsightsConfig,
+  LandingConfig,
+  ManagedAgentState,
+  ManagedAgentStatus,
+  NotificationsConfig,
+  SelfResumeConfig,
+  SpawnApprovalMode,
+  SpawnPolicy,
+  SpawnProvider,
+  StewardConfig,
+  WorkspaceConfig,
+  WorkspaceLandingPolicy,
+} from "./types";
+const CONFIG_HISTORY_LIMIT = 50;
+const SPAWN_POLICY_NAMESPACE = "spawn-policy";
+const AGENT_PROFILE_NAMESPACE = "agent-profile";
+export const AGENT_PROFILE_OVERRIDE_NAMESPACE = "agent-profile-override";
+// #1963 N10 — the immutable pre-migration snapshot of every rewritten override row. The v2 migration
+// copies each raw override here BEFORE rewriting the live row; while `AGENT_RELAY_PROFILE_MATRIX` is
+// off (default one release) `builtInProfileEntry` serves these bytes instead of the migrated row, so
+// rollback is byte-exact and needs no un-migration. An authoritative re-write of the live row
+// (operator PUT / built-in reset) deletes the snapshot — a deliberately re-authored row supersedes it.
+export const AGENT_PROFILE_OVERRIDE_V1_BACKUP_NAMESPACE = "agent-profile-override-v1-backup";
+const STEWARD_NAMESPACE = "steward";
+const STEWARD_KEY = "default";
+const INSIGHTS_NAMESPACE = "insights";
+const INSIGHTS_KEY = "default";
+const SELF_RESUME_NAMESPACE = "self-resume";
+const SELF_RESUME_KEY = "default";
+const WORKSPACE_NAMESPACE = "workspace";
+const WORKSPACE_KEY = "default";
+const LANDING_NAMESPACE = "landing";
+const LANDING_KEY = "default";
+const VALID_LANDING_STRATEGIES = ["direct", "pr"] as const;
+const VALID_LANDING_MECHANISMS = ["managed", "plain-git"] as const;
+const VALID_PROFILE_PROVIDERS = ["any", ...SPAWN_PROVIDERS] as const;
+const VALID_PROFILE_BASES = ["host", "minimal", "isolated", "vanilla"] as const;
+const VALID_PROFILE_INSTRUCTION_POLICIES = ["allow", "ignore"] as const;
+const VALID_PROFILE_CATEGORY_MODES = ["host", "profile", "repo", "none"] as const;
+const VALID_PROFILE_ASSET_SOURCES = ["relay", "repo", "inline", "provider"] as const;
+const VALID_PROFILE_FILESYSTEM_SCOPES = ["repo", "workspace", "host"] as const;
+const VALID_PERMISSION_MODES = ["open", "guarded", "read-only"] as const;
+const VALID_POLICY_MODES = ["always-on", "on-demand"] as const;
+const VALID_MANAGED_STATUSES = ["stopped", "starting", "running", "stopping", "backoff", "failed"] as const;
+export { agentProfileDefaults, builtInAgentProfiles, DEFAULT_SPAWN_PROFILE_NAME } from "./agent-profile-catalog";
+
+interface ConfigRow {
+  namespace: string;
+  key: string;
+  value: string;
+  version: number;
+  updated_at: string;
+  updated_by: string | null;
+}
+
+interface ConfigHistoryRow {
+  id: number;
+  namespace: string;
+  key: string;
+  value: string;
+  version: number;
+  changed_at: string;
+  changed_by: string | null;
+}
+
+interface ManagedAgentStateRow {
+  policy_name: string;
+  status: ManagedAgentStatus;
+  agent_id: string | null;
+  last_agent_id: string | null;
+  orchestrator_id: string;
+  provider: SpawnProvider;
+  tmux_session: string | null;
+  spawn_request_id: string | null;
+  workspace_id: string | null;
+  workspace_path: string | null;
+  workspace_branch: string | null;
+  last_spawn_at: number | null;
+  last_stop_at: number | null;
+  healthy_since: number | null;
+  restart_count: number;
+  consecutive_failures: number;
+  backoff_until: number | null;
+  last_error: string | null;
+  updated_at: number;
+}
+
+type ManagedAgentStateInput = Omit<ManagedAgentState, "updatedAt" | "restartCount" | "consecutiveFailures"> &
+  Partial<Pick<ManagedAgentState, "updatedAt" | "restartCount" | "consecutiveFailures">>;
+
+type ManagedAgentStatePatch = Partial<Omit<ManagedAgentState, "policyName" | "orchestratorId" | "provider">> &
+  Partial<Pick<ManagedAgentState, "orchestratorId" | "provider">>;
+
+function parseJsonValue(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function rowToConfigEntry<T>(row: ConfigRow): ConfigEntry<T> {
+  return {
+    namespace: row.namespace,
+    key: row.key,
+    value: parseJsonValue(row.value) as T,
+    version: row.version,
+    updatedAt: row.updated_at,
+    updatedBy: row.updated_by ?? undefined,
+  };
+}
+
+function rowToConfigHistoryEntry<T>(row: ConfigHistoryRow): ConfigHistoryEntry<T> {
+  return {
+    id: row.id,
+    namespace: row.namespace,
+    key: row.key,
+    value: parseJsonValue(row.value) as T,
+    version: row.version,
+    changedAt: row.changed_at,
+    changedBy: row.changed_by ?? undefined,
+  };
+}
+
+function rowToManagedAgentState(row: ManagedAgentStateRow): ManagedAgentState {
+  return {
+    policyName: row.policy_name,
+    status: row.status,
+    agentId: row.agent_id ?? undefined,
+    orchestratorId: row.orchestrator_id,
+    provider: row.provider,
+    tmuxSession: row.tmux_session ?? undefined,
+    spawnRequestId: row.spawn_request_id ?? undefined,
+    workspaceId: row.workspace_id ?? undefined,
+    workspacePath: row.workspace_path ?? undefined,
+    workspaceBranch: row.workspace_branch ?? undefined,
+    lastSpawnAt: row.last_spawn_at ?? undefined,
+    lastStopAt: row.last_stop_at ?? undefined,
+    healthySince: row.healthy_since ?? undefined,
+    restartCount: row.restart_count,
+    consecutiveFailures: row.consecutive_failures,
+    backoffUntil: row.backoff_until ?? undefined,
+    lastError: row.last_error ?? undefined,
+    updatedAt: row.updated_at,
+  };
+}
+
+function cleanStringRecord(value: unknown, field: string): Record<string, string> {
+  if (value === undefined || value === null) return {};
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  const result: Record<string, string> = {};
+  for (const [key, raw] of Object.entries(value)) {
+    const cleanKey = cleanString(key, `${field} key`, { required: true, max: 120 })!;
+    if (typeof raw !== "string") throw new ValidationError(`${field}.${cleanKey} must be a string`);
+    result[cleanKey] = raw;
+  }
+  return result;
+}
+
+function cleanJsonRecord(value: unknown, field: string): Record<string, unknown> {
+  if (value === undefined || value === null) return {};
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  return value;
+}
+
+function cleanBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
+  return value;
+}
+
+function cleanNumber(value: unknown, field: string, opts: { min: number; max: number }): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < opts.min || value > opts.max) {
+    throw new ValidationError(`${field} must be an integer between ${opts.min} and ${opts.max}`);
+  }
+  return value;
+}
+
+// #667 — project `.mcp.json` projection profile default:
+// boolean | { policy } → normalized { policy? } | undefined (OFF).
+function cleanAgentProfileProjectMcp(value: unknown): AgentProfile["projectMcp"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (!isRecord(value)) throw new ValidationError("projectMcp must be a boolean or { policy } object");
+  const policy = value.policy;
+  if (policy === undefined || policy === null) return {};
+  return { policy: cleanEnum(policy, "projectMcp.policy", PROJECT_MCP_POLICY_NAMES) as NonNullable<AgentProfile["projectMcp"]>["policy"] };
+}
+
+function cleanAgentProfileProjectSkills(value: unknown): AgentProfile["projectSkills"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (!isRecord(value)) throw new ValidationError("projectSkills must be a boolean or { policy } object");
+  const policy = value.policy;
+  if (policy === undefined || policy === null) return {};
+  return { policy: cleanEnum(policy, "projectSkills.policy", PROJECT_SKILLS_POLICY_NAMES) as NonNullable<AgentProfile["projectSkills"]>["policy"] };
+}
+
+function cleanAgentProfileProjectSettings(value: unknown): AgentProfile["projectSettings"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (!isRecord(value)) throw new ValidationError("projectSettings must be a boolean or { policy } object");
+  const policy = value.policy;
+  if (policy === undefined || policy === null) return {};
+  return { policy: cleanEnum(policy, "projectSettings.policy", PROJECT_SETTINGS_POLICY_NAMES) as NonNullable<AgentProfile["projectSettings"]>["policy"] };
+}
+
+// #672 — shared host-listener MCP projection profile default. Mirrors projectMcp:
+// boolean | { policy } → normalized { policy? } | undefined (OFF).
+function cleanAgentProfileSharedMcp(value: unknown): AgentProfile["sharedMcp"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (!isRecord(value)) throw new ValidationError("sharedMcp must be a boolean or { policy } object");
+  const policy = value.policy;
+  if (policy === undefined || policy === null) return {};
+  return { policy: cleanEnum(policy, "sharedMcp.policy", SHARED_MCP_POLICY_NAMES) as NonNullable<AgentProfile["sharedMcp"]>["policy"] };
+}
+
+function cleanAgentProfileHostAssets(value: unknown): AgentProfile["hostAssets"] {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (!isRecord(value)) throw new ValidationError("hostAssets must be an object");
+  const hostAssets = {
+    ...(value.skills === undefined ? {} : { skills: cleanBoolean(value.skills, "hostAssets.skills") }),
+    ...(value.plugins === undefined ? {} : { plugins: cleanBoolean(value.plugins, "hostAssets.plugins") }),
+    ...(value.settings === undefined ? {} : { settings: cleanBoolean(value.settings, "hostAssets.settings") }),
+  };
+  return Object.keys(hostAssets).length ? hostAssets : undefined;
+}
+
+function cleanAgentProfileNotifications(value: unknown): AgentProfile["notifications"] {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError("notifications must be an object");
+  const responseMode = value.responseMode === undefined || value.responseMode === null
+    ? undefined
+    : cleanEnum(value.responseMode, "notifications.responseMode", ["normal", "results-only"] as const);
+  return responseMode ? { responseMode } : {};
+}
+
+// #3024 — absent means on, so only an explicit `false` is stored: a profile that never touched
+// its web tools stays byte-identical, and switching one back on removes the key.
+function cleanAgentProfileWebTools(value: unknown): AgentProfile["webTools"] {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new ValidationError("webTools must be an object");
+  const off = WEB_TOOL_NAMES.filter((name) => value[name] !== undefined && value[name] !== null && !cleanBoolean(value[name], `webTools.${name}`));
+  return off.length ? Object.fromEntries(off.map((name) => [name, false])) : undefined;
+}
+
+function cleanAgentProfileAssetArray(value: unknown, field: string): AgentProfile["skills"] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array`);
+  if (value.length > 100) throw new ValidationError(`${field} can contain at most 100 entries`);
+  return value.map((item, index) => {
+    if (!isRecord(item)) throw new ValidationError(`${field}[${index}] must be an object`);
+    return {
+      source: cleanEnum(item.source, `${field}[${index}].source`, VALID_PROFILE_ASSET_SOURCES),
+      ref: cleanString(item.ref, `${field}[${index}].ref`, { required: true, max: 1000 })!,
+      enabled: item.enabled === undefined ? true : cleanBoolean(item.enabled, `${field}[${index}].enabled`),
+      provider: item.provider === undefined || item.provider === null
+        ? undefined
+        : cleanEnum(item.provider, `${field}[${index}].provider`, VALID_PROFILE_PROVIDERS),
+      meta: isRecord(item.meta) ? item.meta : undefined,
+    };
+  });
+}
+
+// ── #1963 N4 — v2 Source × Capability matrix validation ─────────────────────────────────────
+// `validateAgentProfile` accepts an optional additive `sources` block (a derived view of the v1
+// fields; not read by the runner yet) and validates its structure + the two legality rules the
+// epic locked: unknown relay tool-group names are rejected (against RELAY_TOOL_GROUPS), and
+// `project.plugins:on` is rejected (P.plugins is not-implemented). Everything else is structural
+// cleaning that mirrors the v1 field validators above.
+function cleanProfileToggleCell(value: unknown, field: string): ProfileToggleCell {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  return { enabled: cleanBoolean(value.enabled, `${field}.enabled`) };
+}
+
+function cleanProfileAssetCell(value: unknown, field: string): ProfileAssetCell {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  return {
+    enabled: cleanBoolean(value.enabled, `${field}.enabled`),
+    ...(value.bundled === undefined || value.bundled === null ? {} : { bundled: cleanBoolean(value.bundled, `${field}.bundled`) }),
+    refs: cleanAgentProfileAssetArray(value.refs, `${field}.refs`), ...(value.ack === undefined || value.ack === null ? {} : { ack: cleanProfileProjectAck(value.ack, `${field}.ack`) }),
+  };
+}
+
+function cleanProfileProjectPolicyCell(value: unknown, field: string, policyNames: readonly string[]): ProfileProjectPolicyCell {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  return {
+    enabled: cleanBoolean(value.enabled, `${field}.enabled`),
+    ...(value.policy === undefined || value.policy === null ? {} : { policy: cleanEnum(value.policy, `${field}.policy`, policyNames) as ProfileProjectPolicyCell["policy"] }), ...(value.ack === undefined || value.ack === null ? {} : { ack: cleanProfileProjectAck(value.ack, `${field}.ack`) }),
+  };
+}
+
+function cleanProfileRelayInstructionsCell(value: unknown, field: string): ProfileRelayInstructionsCell {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  return {
+    enabled: cleanBoolean(value.enabled, `${field}.enabled`),
+    ...(value.system === undefined || value.system === null ? {} : { system: cleanString(value.system, `${field}.system`, { max: 16_000 })! }),
+    append: cleanStringArray(value.append, `${field}.append`, { itemMax: 16_000, maxItems: 100 }) ?? [],
+    turnContext: cleanBoolean(value.turnContext, `${field}.turnContext`),
+  };
+}
+
+function cleanProfileRelayTools(value: unknown, field: string): NonNullable<AgentProfile["relay"]["tools"]> {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  const tools: NonNullable<AgentProfile["relay"]["tools"]> = {};
+  for (const key of ["groups", "include", "exclude"] as const) {
+    if (value[key] !== undefined) tools[key] = cleanStringArray(value[key], `${field}.${key}`, { itemMax: 120, maxItems: key === "groups" ? 40 : 300 }) ?? [];
+  }
+  try { resolveRelayTools(tools); } catch (error) { throw new ValidationError(`${field}: ${(error as Error).message}`); }
+  return tools;
+}
+
+function cleanProfileRelayMcpCell(value: unknown, field: string): ProfileRelayMcpCell {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  const tools = cleanProfileRelayTools(value, field);
+  return {
+    enabled: cleanBoolean(value.enabled, `${field}.enabled`),
+    ...tools,
+    ...(value.servers === undefined || value.servers === null ? {} : { servers: cleanJsonRecord(value.servers, `${field}.servers`) }),
+  };
+}
+
+function cleanProfileSources(value: unknown): ProfileSourceMatrix {
+  if (!isRecord(value)) throw new ValidationError("sources must be an object");
+  const host = isRecord(value.host) ? value.host : {};
+  const project = isRecord(value.project) ? value.project : {};
+  const agentRelay = isRecord(value.agentRelay) ? value.agentRelay : {};
+  // Project plugins are not implemented, but the cell is optional in persisted profiles. Treat
+  // omission as "not set" while continuing to validate/reject any explicitly supplied value.
+  const projectPlugins = project.plugins === undefined ? { enabled: false, refs: [] } : cleanProfileAssetCell(project.plugins, "sources.project.plugins");
+  // Legality rule 2 (#1963 §4): P.plugins is not-implemented — no provider lever exists.
+  if (projectPlugins.enabled) throw new ValidationError("sources.project.plugins cannot be enabled: project plugins are not implemented");
+  return {
+    host: {
+      instructions: cleanProfileToggleCell(host.instructions, "sources.host.instructions"),
+      mcp: cleanProfileToggleCell(host.mcp, "sources.host.mcp"),
+      hooks: cleanProfileAssetCell(host.hooks, "sources.host.hooks"),
+      skills: cleanProfileAssetCell(host.skills, "sources.host.skills"),
+      plugins: cleanProfileAssetCell(host.plugins, "sources.host.plugins"),
+    },
+    project: { trust: project.trust === undefined || project.trust === null ? { scope: "roots" } : cleanProfileProjectTrust(project.trust, "sources.project.trust"),
+      instructions: project.instructions === undefined ? { enabled: false } : cleanProfileToggleCell(project.instructions, "sources.project.instructions"),
+      mcp: project.mcp === undefined ? { enabled: false } : cleanProfileProjectPolicyCell(project.mcp, "sources.project.mcp", PROJECT_MCP_POLICY_NAMES),
+      hooks: project.hooks === undefined ? { enabled: false, refs: [] } : cleanProfileAssetCell(project.hooks, "sources.project.hooks"),
+      skills: project.skills === undefined ? { enabled: false } : cleanProfileProjectPolicyCell(project.skills, "sources.project.skills", PROJECT_SKILLS_POLICY_NAMES),
+      plugins: projectPlugins,
+    },
+    agentRelay: {
+      instructions: cleanProfileRelayInstructionsCell(agentRelay.instructions, "sources.agentRelay.instructions"),
+      mcp: cleanProfileRelayMcpCell(agentRelay.mcp, "sources.agentRelay.mcp"),
+      hooks: cleanProfileAssetCell(agentRelay.hooks, "sources.agentRelay.hooks"),
+      skills: cleanProfileAssetCell(agentRelay.skills, "sources.agentRelay.skills"),
+      plugins: cleanProfileAssetCell(agentRelay.plugins, "sources.agentRelay.plugins"),
+    },
+  };
+}
+
+export function validateAgentProfile(key: string, value: unknown, opts: { allowBuiltIn?: boolean } = {}): AgentProfile {
+  if (BUILT_IN_AGENT_PROFILE_NAMES.has(key) && !opts.allowBuiltIn) throw new ValidationError("built-in agent profiles are managed by Relay");
+  // #1626 F6a — the store-health probe addresses its synthetic marker to this audience precisely
+  // BECAUSE no real agent can match it. A profile that claimed the name would be the one agent a
+  // leaked probe marker could reach, which is the guarantee the reservation exists to make real.
+  if (key === RESERVED_SYNTHETIC_AUDIENCE) throw new ValidationError(`"${RESERVED_SYNTHETIC_AUDIENCE}" is reserved for relay's own synthetic memory entries and cannot name a profile`);
+  if (!isRecord(value)) throw new ValidationError("agent-profile value must be an object");
+  const name = cleanString(value.name, "name", { required: true, max: 120 })!;
+  if (name !== key) throw new ValidationError("agent-profile name must match config key");
+  // #2791 — the write chokepoint every profile create/rename funnels through (profile PUT route,
+  // generic /api/config PUT, setAgentProfile): a key that resolves to a DIFFERENT stored profile
+  // only by case is refused, naming the stored profile. Exact-key updates resolve to themselves.
+  const canonical = resolveAgentProfileKey(key);
+  if (canonical !== undefined && canonical !== key) {
+    throw new ValidationError(`agent-profile name "${key}" collides with existing profile "${canonical}" (profile names are case-insensitive)`);
+  }
+  const base = cleanEnum(value.base, "base", VALID_PROFILE_BASES) as AgentProfileBase;
+  const defaults = agentProfileDefaults({ name, base }), provider = value.provider === undefined || value.provider === null ? defaults.provider : cleanEnum(value.provider, "provider", VALID_PROFILE_PROVIDERS);
+  const instructions = isRecord(value.instructions) ? value.instructions : {};
+  const relay = isRecord(value.relay) ? value.relay : {};
+  const mcp = isRecord(value.mcp) ? value.mcp : {};
+  const hooks = isRecord(value.hooks) ? value.hooks : {};
+  const permissions = isRecord(value.permissions) ? value.permissions : {};
+  // #1963 N4 — additive v2 fields. Both are OMITTED when absent so a v1 profile's normalized shape
+  // is byte-identical to today (built-ins never carry them). `sources` is authoritative for
+  // matrix-controlled launch facts; v1 fields remain a lossless migration view (G7).
+  const sources = value.sources === undefined || value.sources === null ? undefined : cleanProfileSources(value.sources);
+  const profileSchemaVersion = value.profileSchemaVersion === undefined || value.profileSchemaVersion === null
+    ? undefined
+    : cleanNumber(value.profileSchemaVersion, "profileSchemaVersion", { min: 1, max: 1000 });
+  const normalized = agentProfileDefaults({
+    ...defaults,
+    hostAwareness: value.hostAwareness === undefined ? defaults.hostAwareness : cleanBoolean(value.hostAwareness, "hostAwareness"),
+    description: cleanString(value.description, "description", { max: 1000 }),
+    // #751: per-profile emoji icon. Short free string (single emoji incl. ZWJ
+    // sequences); cap length so it can't smuggle arbitrary text. Empty → undefined.
+    icon: cleanString(value.icon, "icon", { max: 8 }) || undefined,
+    provider,
+    instructions: {
+      system: cleanString(instructions.system, "instructions.system", { max: 16_000 }),
+      append: cleanStringArray(instructions.append, "instructions.append", { itemMax: 16_000, maxItems: 100 }) ?? [],
+      repoInstructions: instructions.repoInstructions === undefined
+        ? defaults.instructions.repoInstructions
+        : cleanEnum(instructions.repoInstructions, "instructions.repoInstructions", VALID_PROFILE_INSTRUCTION_POLICIES),
+      globalInstructions: instructions.globalInstructions === undefined
+        ? defaults.instructions.globalInstructions
+        : cleanEnum(instructions.globalInstructions, "instructions.globalInstructions", VALID_PROFILE_INSTRUCTION_POLICIES),
+    },
+    projectMcp: cleanAgentProfileProjectMcp(value.projectMcp),
+    projectSkills: cleanAgentProfileProjectSkills(value.projectSkills),
+    projectSettings: cleanAgentProfileProjectSettings(value.projectSettings),
+    // #1565 P5.7 — unlike the projectX gates, a literal `false` here means "switch native memory
+    // OFF" (the point of the field), not "did not opt in"; only undefined/null is absent.
+    serviceAccess: cleanServiceAccess(value.serviceAccess),
+    nativeMemory: parseNativeMemory(value.nativeMemory, (m) => new ValidationError(m)),
+    sharedMcp: cleanAgentProfileSharedMcp(value.sharedMcp),
+    hostAssets: cleanAgentProfileHostAssets(value.hostAssets),
+    notifications: cleanAgentProfileNotifications(value.notifications),
+    webTools: cleanAgentProfileWebTools(value.webTools),
+    ...(value.workflows === undefined ? {} : { workflows: cleanProfileWorkflows(value.workflows) }),
+    relay: {
+      context: relay.context === undefined ? defaults.relay.context : cleanBoolean(relay.context, "relay.context"),
+      skills: relay.skills === undefined ? defaults.relay.skills : cleanBoolean(relay.skills, "relay.skills"),
+      plugins: relay.plugins === undefined ? defaults.relay.plugins : cleanBoolean(relay.plugins, "relay.plugins"),
+      statusLine: relay.statusLine === undefined ? defaults.relay.statusLine : cleanBoolean(relay.statusLine, "relay.statusLine"),
+      mcp: relay.mcp === undefined ? defaults.relay.mcp : cleanBoolean(relay.mcp, "relay.mcp"),
+      ...(relay.tools === undefined ? {} : { tools: cleanProfileRelayTools(relay.tools, "relay.tools") }),
+    },
+    skills: cleanAgentProfileAssetArray(value.skills, "skills"),
+    plugins: cleanAgentProfileAssetArray(value.plugins, "plugins"),
+    mcp: {
+      mode: mcp.mode === undefined ? defaults.mcp.mode : cleanEnum(mcp.mode, "mcp.mode", VALID_PROFILE_CATEGORY_MODES),
+      ...(mcp.servers === undefined ? {} : { servers: cleanJsonRecord(mcp.servers, "mcp.servers") }),
+    },
+    hooks: {
+      mode: hooks.mode === undefined ? defaults.hooks.mode : cleanEnum(hooks.mode, "hooks.mode", VALID_PROFILE_CATEGORY_MODES),
+      refs: cleanAgentProfileAssetArray(hooks.refs, "hooks.refs"),
+    },
+    permissions: {
+      mode: permissions.mode === undefined || permissions.mode === null
+        ? undefined
+        : cleanEnum(permissions.mode, "permissions.mode", VALID_PERMISSION_MODES),
+      filesystem: permissions.filesystem === undefined
+        ? defaults.permissions.filesystem
+        : cleanEnum(permissions.filesystem, "permissions.filesystem", VALID_PROFILE_FILESYSTEM_SCOPES),
+    },
+    env: cleanStringRecord(value.env, "env"),
+    providerOptions: cleanAgentProfileProviderOptions(value.providerOptions),
+    ...(value.harnessSubagents === undefined ? {} : { harnessSubagents: cleanBoolean(value.harnessSubagents, "harnessSubagents") }),
+    ...(value.browser === undefined || value.browser === null || cleanBoolean(value.browser, "browser") ? {} : { browser: false }),
+    maxSpawnedAgents: value.maxSpawnedAgents === undefined || value.maxSpawnedAgents === null
+      ? undefined
+      : cleanNumber(value.maxSpawnedAgents, "maxSpawnedAgents", { min: 0, max: 100 }),
+    hostPinned: value.hostPinned === undefined || value.hostPinned === null
+      ? undefined
+      : cleanBoolean(value.hostPinned, "hostPinned"),
+    landingStrategy: value.landingStrategy === undefined || value.landingStrategy === null
+      ? undefined
+      : cleanEnum(value.landingStrategy, "landingStrategy", VALID_LANDING_STRATEGIES) as WorkspaceLandingPolicy,
+    messaging: value.messaging == null ? undefined : cleanEnum(value.messaging, "messaging", AGENT_PROFILE_MESSAGING_POLICIES),
+  });
+  // #3387 — `sources.host` is the synchronized projection of the canonical v1 Host fields.
+  return withSyncedHostCells({
+    ...normalized,
+    ...(profileSchemaVersion === undefined ? {} : { profileSchemaVersion }),
+    ...(sources === undefined ? {} : { sources }),
+  });
+}
+
+function cloneJson<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+export function mergeProfileOverride(base: AgentProfile, override: unknown): AgentProfile {
+  if (!isRecord(override)) return cloneJson(base);
+  return mergeRecord(cloneJson(base) as unknown as Record<string, unknown>, override) as unknown as AgentProfile;
+}
+
+function mergeRecord(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+    const current = base[key];
+    base[key] = isRecord(current) && isRecord(value) && !Array.isArray(current) && !Array.isArray(value)
+      ? mergeRecord({ ...current }, value)
+      : value;
+  }
+  return base;
+}
+
+export function agentProfileOverrideDiff(base: unknown, merged: unknown): unknown {
+  if (Array.isArray(base) || Array.isArray(merged) || !isRecord(base) || !isRecord(merged)) {
+    return JSON.stringify(base) === JSON.stringify(merged) ? undefined : merged;
+  }
+  const diff: Record<string, unknown> = {};
+  const keys = new Set([...Object.keys(base), ...Object.keys(merged)]);
+  for (const key of keys) {
+    if (key === "builtIn" || key === "overridden" || key === "provisioning") continue;
+    const value = agentProfileOverrideDiff(base[key], merged[key]);
+    if (value !== undefined) diff[key] = value;
+    else if (base[key] !== undefined && merged[key] === undefined) diff[key] = null;
+  }
+  return Object.keys(diff).length ? diff : undefined;
+}
+
+// #1963 N10 G8 — a profile's matrix must not contradict its own effective v1 instruction fields
+// (host.instructions ⟺ globalInstructions:"allow"; project.instructions ⟺ repoInstructions:"allow" —
+// the two cells `v1ToCells` derives deterministically). Enforced in `validateAgentProfileOverride`, the
+// SINGLE validator every override write funnels through (the profile route, the generic /api/config
+// PUT, and setAgentProfile), against the MERGED view — so a partial body that omits `base` is checked
+// against the seed's fields instead of bypassing the guard. It never runs on read-back
+// (builtInProfileEntry uses validateAgentProfile), so it can never reject an already-persisted row.
+// This is G8's "never silently pick between the v1 fields and the matrix" — reject the contradiction.
+// Host cells are reconciled onto the v1 fields before validation (#3387, reconcileHostCellInputs).
+function assertProfileSourcesMatchInstructions(profile: AgentProfile): void {
+  const sources = profile.sources;
+  if (!sources) return;
+  const project = sources.project;
+  if (project?.instructions && project.instructions.enabled !== (profile.instructions.repoInstructions === "allow")) {
+    throw new ValidationError(`sources.project.instructions.enabled contradicts instructions.repoInstructions="${profile.instructions.repoInstructions}"`);
+  }
+}
+
+function validateAgentProfileOverride(key: string, value: unknown): Partial<AgentProfile> {
+  const builtIn = builtInAgentProfile(key);
+  if (!builtIn) throw new ValidationError("agent profile override target must be a built-in profile");
+  if (!isRecord(value)) throw new ValidationError("agent-profile override value must be an object");
+  const body = reconcileHostCellInputs(value, typeof value.base === "string" ? value.base as AgentProfileBase : builtIn.base, builtIn.hostAssets);
+  const merged = mergeProfileOverride(builtIn, { ...body, name: key, builtIn: true });
+  const validated = validateAgentProfile(key, merged, { allowBuiltIn: true });
+  assertProfileSourcesMatchInstructions(validated);
+  const diff = agentProfileOverrideDiff(builtIn, validated);
+  return { name: key, ...(isRecord(diff) ? diff : {}) };
+}
+
+function validateSpawnPolicy(key: string, value: unknown): SpawnPolicy {
+  if (!isRecord(value)) throw new ValidationError("spawn-policy value must be an object");
+  const name = cleanString(value.name, "name", { required: true, max: 120 })!;
+  if (name !== key) throw new ValidationError("spawn-policy name must match config key");
+  const mode = cleanEnum(value.mode, "mode", VALID_POLICY_MODES);
+  const policy: SpawnPolicy = {
+    name,
+    description: cleanString(value.description, "description", { max: 1000 }),
+    enabled: value.enabled === undefined ? true : cleanBoolean(value.enabled, "enabled"),
+    orchestratorId: cleanString(value.orchestratorId, "orchestratorId", { required: true, max: 200 })!,
+    cwd: cleanString(value.cwd, "cwd", { required: true, max: 1000 })!,
+    provider: cleanEnum(value.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
+    workspaceMode: value.workspaceMode === undefined || value.workspaceMode === null ? "inherit" : cleanEnum(value.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES),
+    rig: cleanString(value.rig, "rig", { max: 120 }),
+    model: cleanString(value.model, "model", { max: 120 }),
+    effort: cleanString(value.effort, "effort", { max: 120 }) as ProviderEffort | undefined,
+    profile: cleanString(value.profile, "profile", { max: 120 }),
+    providerArgs: cleanStringArray(value.providerArgs, "providerArgs", { itemMax: 120, maxItems: 100 }) ?? [],
+    ...(value.launchMode === undefined || value.launchMode === null ? {} : { launchMode: cleanEnum(value.launchMode, "launchMode", LAUNCH_MODES) }),
+    prompt: cleanString(value.prompt, "prompt", { max: 16_000 }),
+    tags: cleanStringArray(value.tags, "tags", { itemMax: 120, maxItems: 100 }) ?? [],
+    capabilities: cleanStringArray(value.capabilities, "capabilities", { itemMax: 120, maxItems: 100 }) ?? [],
+    label: cleanString(value.label, "label", { max: 120 }),
+    mode,
+    permissionMode: cleanEnum(value.permissionMode, "permissionMode", VALID_PERMISSION_MODES),
+    restartOnUpdate: cleanBoolean(value.restartOnUpdate, "restartOnUpdate"),
+    scheduledDailyRestart: cleanBoolean(value.scheduledDailyRestart, "scheduledDailyRestart"),
+    backoff: cleanBackoff(value.backoff),
+  };
+  policy.model = normalizeConfigModelSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
+  // #2791 — store the canonical stored-case profile name so policy-driven spawns carry it
+  // downstream (tags, payload, token) instead of the case the operator typed.
+  if (policy.profile) {
+    const canonicalProfile = resolveAgentProfileKey(policy.profile);
+    if (!canonicalProfile) throw new ValidationError("agent profile not found");
+    policy.profile = canonicalProfile;
+    const refusal = profileProviderRefusal(canonicalProfile, policy.provider);
+    if (refusal) throw new ValidationError(refusal);
+  }
+  if (policy.launchMode) assertLaunchModeSupported(policy.provider, policy.launchMode);
+  if (mode === "on-demand") policy.onDemand = cleanOnDemand(value.onDemand);
+  if (value.binding !== undefined && value.binding !== null) policy.binding = cleanBinding(value.binding);
+  return policy;
+}
+
+function cleanBackoff(value: unknown): SpawnPolicy["backoff"] {
+  if (!isRecord(value)) throw new ValidationError("backoff must be an object");
+  if (!Array.isArray(value.schedule) || value.schedule.length === 0) {
+    throw new ValidationError("backoff.schedule must be a non-empty array");
+  }
+  if (value.schedule.length > 20) throw new ValidationError("backoff.schedule can contain at most 20 values");
+  return {
+    schedule: value.schedule.map((item, index) => cleanNumber(item, `backoff.schedule[${index}]`, { min: 1, max: 86_400 })),
+    resetAfterSeconds: cleanNumber(value.resetAfterSeconds, "backoff.resetAfterSeconds", { min: 1, max: 86_400 }),
+  };
+}
+
+function cleanOnDemand(value: unknown): NonNullable<SpawnPolicy["onDemand"]> {
+  if (!isRecord(value)) throw new ValidationError("onDemand must be an object when mode is on-demand");
+  const idleDefinition = cleanEnum(value.idleDefinition, "onDemand.idleDefinition", ["no-activity"] as const);
+  return {
+    keepaliveSeconds: cleanNumber(value.keepaliveSeconds, "onDemand.keepaliveSeconds", { min: 0, max: 2_592_000 }),
+    idleDefinition,
+  };
+}
+
+function cleanBinding(value: unknown): NonNullable<SpawnPolicy["binding"]> {
+  if (!isRecord(value)) throw new ValidationError("binding must be an object");
+  return {
+    type: cleanEnum(value.type, "binding.type", ["channel"] as const),
+    channelId: cleanString(value.channelId, "binding.channelId", { required: true, max: 200 })!,
+  };
+}
+
+const STEWARD_CONFIG_DEFAULTS: StewardConfig = {
+  enabled: false,
+  provider: "claude",
+  permissionMode: "open",
+  keepaliveSeconds: 300,
+};
+
+function validateStewardConfig(value: unknown): StewardConfig {
+  if (!isRecord(value)) throw new ValidationError("steward config value must be an object");
+  const config: StewardConfig = {
+    enabled: value.enabled === undefined ? false : cleanBoolean(value.enabled, "enabled"),
+    provider: cleanEnum(value.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
+    model: cleanString(value.model, "model", { max: 120 }),
+    effort: cleanString(value.effort, "effort", { max: 120 }) as ProviderEffort | undefined,
+    permissionMode: (value.permissionMode === undefined || value.permissionMode === null
+      ? "open"
+      : cleanEnum(value.permissionMode, "permissionMode", VALID_PERMISSION_MODES)) as SpawnApprovalMode,
+    keepaliveSeconds: value.keepaliveSeconds === undefined || value.keepaliveSeconds === null
+      ? 300
+      : cleanNumber(value.keepaliveSeconds, "keepaliveSeconds", { min: 0, max: 2_592_000 }),
+  };
+  // Reject a provider/model/effort combo the catalog can't resolve before it ever
+  // reaches a spawn (same guard as spawn policies).
+  config.model = normalizeConfigModelSelection({ provider: config.provider, model: config.model, effort: config.effort });
+  return config;
+}
+
+// Insights / self-improvement module config — feature toggles for the dogfooding
+// flywheel (epic #183, docs/self-improvement.md). Passive read-only observation, so it
+// defaults on; each feature toggles independently.
+const INSIGHTS_CONFIG_DEFAULTS: InsightsConfig = {
+  enabled: true,
+  contextRatio: { enabled: true },
+  introspection: { enabled: true, minTurns: 4, minContextRemaining: 0.15 },
+};
+
+function cleanFraction(value: unknown, field: string, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new ValidationError(`${field} must be a number between 0 and 1`);
+  }
+  return value;
+}
+
+function validateInsightsConfig(value: unknown): InsightsConfig {
+  if (!isRecord(value)) throw new ValidationError("insights config value must be an object");
+  const contextRatio = isRecord(value.contextRatio) ? value.contextRatio : {};
+  const introspection = isRecord(value.introspection) ? value.introspection : {};
+  return {
+    enabled: value.enabled === undefined ? INSIGHTS_CONFIG_DEFAULTS.enabled : cleanBoolean(value.enabled, "enabled"),
+    contextRatio: {
+      enabled: contextRatio.enabled === undefined
+        ? INSIGHTS_CONFIG_DEFAULTS.contextRatio.enabled
+        : cleanBoolean(contextRatio.enabled, "contextRatio.enabled"),
+    },
+    introspection: {
+      enabled: introspection.enabled === undefined
+        ? INSIGHTS_CONFIG_DEFAULTS.introspection.enabled
+        : cleanBoolean(introspection.enabled, "introspection.enabled"),
+      minTurns: introspection.minTurns === undefined || introspection.minTurns === null
+        ? INSIGHTS_CONFIG_DEFAULTS.introspection.minTurns
+        : cleanNumber(introspection.minTurns, "introspection.minTurns", { min: 0, max: 1000 }),
+      minContextRemaining: cleanFraction(
+        introspection.minContextRemaining,
+        "introspection.minContextRemaining",
+        INSIGHTS_CONFIG_DEFAULTS.introspection.minContextRemaining,
+      ),
+    },
+  };
+}
+
+// Global workspace provisioning config for isolated worktrees (#159 follow-up).
+
+function validateWorkspaceConfig(value: unknown): WorkspaceConfig {
+  if (!isRecord(value)) throw new ValidationError("workspace config value must be an object");
+  const symlinkPaths = cleanStringArray(value.symlinkPaths, "symlinkPaths", { itemMax: 120, maxItems: 100 }) ?? [];
+  // Reject absolute paths and parent-traversal up front: symlink sources must stay
+  // inside the main checkout. The orchestrator re-checks containment at link time,
+  // but failing here gives the operator immediate feedback in the dashboard.
+  for (const entry of symlinkPaths) {
+    if (entry.startsWith("/") || entry.split(/[\\/]/).includes("..")) {
+      throw new ValidationError(`symlinkPaths entry must be a relative path within the repo: ${entry}`);
+    }
+  }
+  return { symlinkPaths };
+}
+
+const LANDING_CONFIG_DEFAULTS: LandingConfig = {
+  strategy: "direct",
+  mechanism: "managed",
+};
+
+function validateLandingConfig(value: unknown): LandingConfig {
+  if (!isRecord(value)) throw new ValidationError("landing config value must be an object");
+  return {
+    strategy: value.strategy === undefined || value.strategy === null
+      ? LANDING_CONFIG_DEFAULTS.strategy
+      : cleanEnum(value.strategy, "strategy", VALID_LANDING_STRATEGIES) as WorkspaceLandingPolicy,
+    mechanism: value.mechanism === undefined || value.mechanism === null
+      ? LANDING_CONFIG_DEFAULTS.mechanism
+      : cleanEnum(value.mechanism, "mechanism", VALID_LANDING_MECHANISMS) as LandingConfig["mechanism"],
+    ...(value.stackDepth === undefined || value.stackDepth === null ? {} : { stackDepth: cleanLandStackDepth(value.stackDepth) }),
+  };
+}
+
+function normalizeValue(namespace: string, key: string, value: unknown, warnings: string[]): unknown {
+  const retirement = memoryRetirementMessage(namespace) ?? ([AGENT_PROFILE_NAMESPACE, AGENT_PROFILE_OVERRIDE_NAMESPACE].includes(namespace) ? memoryRetirementMessage(key) : undefined);
+  if (retirement) throw new ValidationError(retirement);
+  if (value === undefined) throw new ValidationError("value required");
+  if (namespace === "gates" && key === "default") return cleanGateLimits(value);
+  if (namespace === "service-access") return validateServiceCatalog(value);
+  if (namespace === CHANNEL_OUTPUT_NAMESPACE) return validateChannelOutputControl(value);
+  if (namespace === SPAWN_POLICY_NAMESPACE) return validateSpawnPolicy(key, value);
+  if (namespace === AGENT_PROFILE_NAMESPACE) return validateAgentProfile(key, isRecord(value) ? reconcileHostCellInputs(value, value.base as AgentProfileBase) : value);
+  if (namespace === AGENT_PROFILE_OVERRIDE_NAMESPACE) return validateAgentProfileOverride(key, value);
+  if (namespace === STEWARD_NAMESPACE) return validateStewardConfig(value);
+  if (namespace === INSIGHTS_NAMESPACE) return validateInsightsConfig(value);
+  if (namespace === NOTIFICATIONS_NAMESPACE) {
+    if (!parseNotificationSettingsKey(key)) throw new ValidationError("notifications config key must be default, team:<teamId>, or agent:<agentId>");
+    return key === NOTIFICATIONS_DEFAULT_KEY ? validateNotificationsConfig(value) : validateNotificationSettingsLayer(value);
+  }
+  if (namespace === SELF_RESUME_NAMESPACE) return validateSelfResumeConfig(value);
+  if (namespace === WORKSPACE_NAMESPACE) return validateWorkspaceConfig(value);
+  if (namespace === LANDING_NAMESPACE) return validateLandingConfig(value);
+  if (namespace === RETENTION_NAMESPACE) return validateRetentionConfig(value);
+  if (namespace === TEAM_TEMPLATE_NAMESPACE) return validateTeamTemplate(key, value);
+  if (namespace === PROVIDER_ENABLEMENT_NAMESPACE) return validateProviderEnablement(key, value);
+  if (namespace === HOST_PROVIDER_ENABLEMENT_NAMESPACE) return validateHostProviderEnablement(key, value);
+  if (JSON.stringify(value) === undefined) throw new ValidationError("value must be valid JSON");
+  return value;
+}
+
+export function getConfig<T = unknown>(namespace: string, key: string): ConfigEntry<T> | null {
+  const row = getDb().query("SELECT * FROM config WHERE namespace = ? AND key = ?").get(namespace, key) as ConfigRow | undefined;
+  return row ? rowToConfigEntry<T>(row) : null;
+}
+
+export function listConfig<T = unknown>(namespace: string): ConfigEntry<T>[] {
+  const rows = getDb()
+    .query("SELECT * FROM config WHERE namespace = ? ORDER BY key ASC")
+    .all(namespace) as ConfigRow[];
+  return rows.map(rowToConfigEntry<T>);
+}
+
+/**
+ * The op body for a config write (S3 L-F #1898). The ENTIRE read-modify-write — validation, the
+ * `version = existing.version + 1` READ, the history row, the upsert, and the prune — runs as ONE unit
+ * so the version read and the write are atomic under the caller's transaction. This is landmine #2
+ * (ADR §3.4 invariant, mirrored from `src/config-store.ts:723`): relocating only the write across the
+ * async seam would let two concurrent setters both read version N and both write N+1 — a lost update.
+ * Folding the read in closes that window. `now` is the submission-time wall-clock (H6, epoch ms),
+ * formatted to the ISO string the `config` columns store. Assumes a transaction is ALREADY open (the
+ * writer executor's `BEGIN IMMEDIATE`, or the sync wrapper below) — it must NOT open its own.
+ */
+export function setConfigInternal<T = unknown>(namespace: string, key: string, value: T, updatedBy: string | undefined, now: number): ConfigEntry<T> {
+  const warnings: string[] = [];
+  const normalized = normalizeValue(namespace, key, value, warnings) as T;
+  writeProfilePromptSlots(namespace, key, value as Partial<AgentProfile>, updatedBy ?? "system", now);
+  const existing = getConfig(namespace, key);
+  const nowIso = new Date(now).toISOString();
+  const nextVersion = existing ? existing.version + 1 : 1;
+  if (existing) {
+    recordConfigHistory(existing, nowIso, updatedBy, normalized);
+  }
+  getDb().query(`
+    INSERT INTO config (namespace, key, value, version, updated_at, updated_by)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(namespace, key) DO UPDATE SET
+      value = excluded.value,
+      version = excluded.version,
+      updated_at = excluded.updated_at,
+      updated_by = excluded.updated_by
+  `).run(namespace, key, JSON.stringify(normalized), nextVersion, nowIso, updatedBy ?? null);
+  // #1963 N10 — ANY authoritative write to an override row (this route, the generic /api/config PUT,
+  // or setAgentProfile) supersedes the migration's rollback snapshot. Dropping it HERE — the single
+  // chokepoint every sync + async write funnels through — is what keeps the flag-off read (which
+  // prefers `-v1-backup`) from silently shadowing a fresh operator edit. The migration writes the
+  // override via raw SQL, not this path, so its own snapshot is preserved.
+  if (namespace === AGENT_PROFILE_OVERRIDE_NAMESPACE) {
+    getDb().query("DELETE FROM config WHERE namespace = ? AND key = ?").run(AGENT_PROFILE_OVERRIDE_V1_BACKUP_NAMESPACE, key);
+  }
+  if (namespace === SPAWN_POLICY_NAMESPACE && isRecord(existing?.value) && isRecord(normalized) &&
+    (existing.value.provider !== normalized.provider || existing.value.model !== normalized.model)) {
+    const state = getManagedAgentState(key);
+    if (state) updateManagedAgentState(key, { ...(state.status === "failed" || state.status === "backoff" ? { status: "stopped", spawnRequestId: undefined, agentId: undefined, tmuxSession: undefined, healthySince: undefined, provider: normalized.provider as SpawnProvider } : {}), consecutiveFailures: 0, backoffUntil: undefined, lastError: undefined });
+  }
+  if ([AGENT_PROFILE_NAMESPACE, AGENT_PROFILE_OVERRIDE_NAMESPACE, "service-access"].includes(namespace)) revokeRemovedVaultAccess(namespace, key, now, getConfig<ServiceAccessCatalog>("service-access", "catalog")?.value.broker, namespace === "service-access" ? undefined : getAgentProfile(key)?.value.serviceAccess);
+  pruneConfigHistory(namespace, key);
+  return { ...getConfig<T>(namespace, key)!, ...(warnings.length ? { warnings } : {}) };
+}
+
+/** Synchronous config write for in-process callers not yet migrated to `setConfigAsync` (bootstrap,
+ * service loops). Same folded read-modify-write as the op body, wrapped in its own transaction. */
+export function setConfig<T = unknown>(namespace: string, key: string, value: T, updatedBy?: string): ConfigEntry<T> {
+  return writeTransaction(() => setConfigInternal(namespace, key, value, updatedBy, Date.now()));
+}
+
+/** Op body for a config delete (S3 L-F #1898): the existence read, history row, delete, and prune are
+ * one atomic unit for the same §3.4 reason as `setConfigInternal`. `now` is submission-time (H6). */
+export function deleteConfigInternal(namespace: string, key: string, updatedBy: string | undefined, now: number): boolean {
+  const existing = getConfig(namespace, key);
+  if (!existing) return false;
+  resetProfilePromptSlots(namespace, key, updatedBy ?? "system", now);
+  recordConfigHistory(existing, new Date(now).toISOString(), updatedBy);
+  getDb().query("DELETE FROM config WHERE namespace = ? AND key = ?").run(namespace, key);
+  // #1963 N10 — deleting/resetting an override row also drops its rollback snapshot (see setConfigInternal).
+  if (namespace === AGENT_PROFILE_OVERRIDE_NAMESPACE) {
+    getDb().query("DELETE FROM config WHERE namespace = ? AND key = ?").run(AGENT_PROFILE_OVERRIDE_V1_BACKUP_NAMESPACE, key);
+  }
+  if (namespace === SPAWN_POLICY_NAMESPACE) deletePolicySelfEffortInternal(key); // #2966
+  if ([AGENT_PROFILE_NAMESPACE, AGENT_PROFILE_OVERRIDE_NAMESPACE, "service-access"].includes(namespace)) revokeRemovedVaultAccess(namespace, key, now, getConfig<ServiceAccessCatalog>("service-access", "catalog")?.value.broker, namespace === "service-access" ? undefined : getAgentProfile(key)?.value.serviceAccess);
+  pruneConfigHistory(namespace, key);
+  return true;
+}
+
+export function deleteConfig(namespace: string, key: string, updatedBy?: string): boolean {
+  return writeTransaction(() => deleteConfigInternal(namespace, key, updatedBy, Date.now()));
+}
+
+export function getConfigHistory<T = unknown>(namespace: string, key: string, limit = CONFIG_HISTORY_LIMIT): ConfigHistoryEntry<T>[] {
+  const safeLimit = Math.min(Math.max(limit, 1), 500);
+  const rows = getDb()
+    .query("SELECT * FROM config_history WHERE namespace = ? AND key = ? ORDER BY version DESC, id DESC LIMIT ?")
+    .all(namespace, key, safeLimit) as ConfigHistoryRow[];
+  return rows.map(rowToConfigHistoryEntry<T>);
+}
+
+function pruneConfigHistory(namespace: string, key: string): void {
+  getDb().query(`
+    DELETE FROM config_history
+    WHERE namespace = ? AND key = ?
+      AND version != COALESCE((SELECT json_extract(value, '$.migrationSourceRevision') FROM config WHERE namespace = ? AND key = ?), -1)
+      AND id NOT IN (
+      SELECT id FROM config_history
+      WHERE namespace = ? AND key = ?
+      ORDER BY version DESC, id DESC
+      LIMIT ?
+    )
+  `).run(namespace, key, namespace, key, namespace, key, CONFIG_HISTORY_LIMIT);
+}
+
+export function getSpawnPolicy(name: string): ConfigEntry<SpawnPolicy> | null {
+  return getConfig<SpawnPolicy>(SPAWN_POLICY_NAMESPACE, name);
+}
+
+export function listSpawnPolicies(): ConfigEntry<SpawnPolicy>[] {
+  return listConfig<SpawnPolicy>(SPAWN_POLICY_NAMESPACE);
+}
+
+function setSpawnPolicy(policy: SpawnPolicy, updatedBy?: string): ConfigEntry<SpawnPolicy> {
+  return setConfig(SPAWN_POLICY_NAMESPACE, policy.name, policy, updatedBy);
+}
+
+/** Global steward config, merged over defaults (always returns a usable value). */
+export function getStewardConfig(): StewardConfig {
+  const entry = getConfig<StewardConfig>(STEWARD_NAMESPACE, STEWARD_KEY);
+  return entry ? { ...STEWARD_CONFIG_DEFAULTS, ...entry.value } : { ...STEWARD_CONFIG_DEFAULTS };
+}
+
+export function getStewardConfigEntry(): ConfigEntry<StewardConfig> {
+  const entry = getConfig<StewardConfig>(STEWARD_NAMESPACE, STEWARD_KEY);
+  return entry ?? {
+    namespace: STEWARD_NAMESPACE,
+    key: STEWARD_KEY,
+    value: { ...STEWARD_CONFIG_DEFAULTS },
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function setStewardConfig(value: unknown, updatedBy?: string): ConfigEntry<StewardConfig> {
+  return setConfig(STEWARD_NAMESPACE, STEWARD_KEY, value as StewardConfig, updatedBy);
+}
+
+/** Insights module config, merged over defaults (always returns a usable value). */
+export function getInsightsConfig(): InsightsConfig {
+  const entry = getConfig<Partial<InsightsConfig>>(INSIGHTS_NAMESPACE, INSIGHTS_KEY);
+  if (!entry) return { ...INSIGHTS_CONFIG_DEFAULTS };
+  return validateInsightsConfig({ ...INSIGHTS_CONFIG_DEFAULTS, ...entry.value });
+}
+
+export function getInsightsConfigEntry(): ConfigEntry<InsightsConfig> {
+  const entry = getConfig<InsightsConfig>(INSIGHTS_NAMESPACE, INSIGHTS_KEY);
+  return entry ?? {
+    namespace: INSIGHTS_NAMESPACE,
+    key: INSIGHTS_KEY,
+    value: { ...INSIGHTS_CONFIG_DEFAULTS },
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+/** Lifecycle-notification config (#239), merged over defaults (always usable). */
+export function getNotificationsConfig(): NotificationsConfig {
+  const entry = getConfig<Partial<NotificationsConfig>>(NOTIFICATIONS_NAMESPACE, NOTIFICATIONS_DEFAULT_KEY);
+  if (!entry) return { ...NOTIFICATIONS_CONFIG_DEFAULTS };
+  return validateNotificationsConfig({ ...NOTIFICATIONS_CONFIG_DEFAULTS, ...entry.value });
+}
+
+export function setInsightsConfig(value: unknown, updatedBy?: string): ConfigEntry<InsightsConfig> {
+  return setConfig(INSIGHTS_NAMESPACE, INSIGHTS_KEY, value as InsightsConfig, updatedBy);
+}
+
+/** Relay-owned self-resume defaults (#316), merged over defaults (always usable). */
+export function getSelfResumeConfig(): SelfResumeConfig {
+  const entry = getConfig<Partial<SelfResumeConfig>>(SELF_RESUME_NAMESPACE, SELF_RESUME_KEY);
+  return validateSelfResumeConfig(entry?.value ?? {});
+}
+
+/** Global workspace config, merged over defaults (always returns a usable value). */
+export function getWorkspaceConfig(): WorkspaceConfig {
+  const entry = getConfig<Partial<WorkspaceConfig>>(WORKSPACE_NAMESPACE, WORKSPACE_KEY);
+  if (!entry) return { ...WORKSPACE_CONFIG_DEFAULTS };
+  return validateWorkspaceConfig({ ...WORKSPACE_CONFIG_DEFAULTS, ...entry.value });
+}
+
+export function getWorkspaceConfigEntry(): ConfigEntry<WorkspaceConfig> {
+  const entry = getConfig<WorkspaceConfig>(WORKSPACE_NAMESPACE, WORKSPACE_KEY);
+  return entry ?? {
+    namespace: WORKSPACE_NAMESPACE,
+    key: WORKSPACE_KEY,
+    value: { ...WORKSPACE_CONFIG_DEFAULTS },
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function setWorkspaceConfig(value: unknown, updatedBy?: string): ConfigEntry<WorkspaceConfig> {
+  return setConfig(WORKSPACE_NAMESPACE, WORKSPACE_KEY, value as WorkspaceConfig, updatedBy);
+}
+
+/** Instance-wide landing config, merged over defaults (always returns a usable value). */
+export function getLandingConfig(): LandingConfig {
+  const entry = getConfig<Partial<LandingConfig>>(LANDING_NAMESPACE, LANDING_KEY);
+  if (!entry) return { ...LANDING_CONFIG_DEFAULTS };
+  return validateLandingConfig({ ...LANDING_CONFIG_DEFAULTS, ...entry.value });
+}
+
+export function setLandingConfig(value: unknown, updatedBy?: string): ConfigEntry<LandingConfig> {
+  return setConfig(LANDING_NAMESPACE, LANDING_KEY, value as LandingConfig, updatedBy);
+}
+
+/**
+ * Spawn-param fragment carrying the global workspace symlink list to the orchestrator.
+ * Spread into every spawn command's params next to `agentProfile` so any isolated
+ * worktree — direct spawn, managed policy, restart, automation — provisions the same
+ * untracked paths. Returns `{}` when nothing is configured (keeps params lean).
+ */
+export function workspaceSpawnParams(): { workspaceSymlinks?: string[] } {
+  const { symlinkPaths } = getWorkspaceConfig();
+  return symlinkPaths.length ? { workspaceSymlinks: symlinkPaths } : {};
+}
+
+function builtInProfileEntry(profile: AgentProfile): ConfigEntry<AgentProfile> {
+  // #1963 N10 — flag-off rollback: while the matrix is not authoritative, an override row the v2
+  // migration rewrote is served from its pristine `-v1-backup` snapshot, so the read is byte-exact to
+  // pre-migration. The backup exists ONLY for migrated-and-not-since-reauthored rows (a PUT/reset
+  // deletes it), so an operator edit made while the flag is off is still honored.
+  // ONE SANCTIONED EXCEPTION to that byte-exactness (#2154): the project-memory group backfill
+  // (db/project-memory-group-migration.ts) appends `project-memory` to the backup's tool groups too —
+  // it has to, because this namespace is the one SERVED here, so skipping it would leave the
+  // longest-standing profile-editor users with no memory write path at all.
+  const override = (!profileMatrixEnabled() && getConfig<Partial<AgentProfile>>(AGENT_PROFILE_OVERRIDE_V1_BACKUP_NAMESPACE, profile.name)) || getConfig<Partial<AgentProfile>>(AGENT_PROFILE_OVERRIDE_NAMESPACE, profile.name);
+  if (override) {
+    const merged = validateAgentProfile(profile.name, mergeProfileOverride(profile, override.value), { allowBuiltIn: true });
+    return {
+      namespace: AGENT_PROFILE_NAMESPACE,
+      key: profile.name,
+      value: applyProfilePromptSlots({ ...merged, builtIn: true, overridden: true }),
+      version: override.version,
+      updatedAt: override.updatedAt,
+      updatedBy: override.updatedBy,
+    };
+  }
+  return {
+    namespace: AGENT_PROFILE_NAMESPACE,
+    key: profile.name,
+    value: applyProfilePromptSlots({ ...profile, overridden: false }),
+    version: 1,
+    updatedAt: "built-in",
+    updatedBy: "system",
+  };
+}
+
+// #2791 — profile names are case-insensitive for identity, case-preserving for display.
+// Every lookup (spawn, dispatch, routes, dashboard, CLI) funnels through getAgentProfile, so this
+// resolver is the ONE seam: exact match first (built-in, then stored row), then a case-insensitive
+// scan (built-ins first, mirroring getAgentProfile's precedence). Returns the STORED key.
+export function resolveAgentProfileKey(name: string): string | undefined {
+  const retirement = memoryRetirementMessage(name);
+  if (retirement) return undefined;
+  if (BUILT_IN_AGENT_PROFILE_NAMES.has(name)) return name;
+  if (getConfig<AgentProfile>(AGENT_PROFILE_NAMESPACE, name)) return name;
+  const alias = canonicalAgentProfileName(name);
+  if (alias !== name) return alias;
+  const lower = name.toLowerCase();
+  return [...BUILT_IN_AGENT_PROFILE_NAMES].find((builtIn) => builtIn.toLowerCase() === lower)
+    ?? listConfig<AgentProfile>(AGENT_PROFILE_NAMESPACE).find((entry) => entry.key.toLowerCase() === lower)?.key;
+}
+
+export function getAgentProfile(name: string): ConfigEntry<AgentProfile> | null {
+  const canonical = resolveAgentProfileKey(name);
+  if (canonical === undefined) return null;
+  const builtIn = builtInAgentProfile(canonical);
+  if (builtIn) return builtInProfileEntry(builtIn);
+  return applyProfilePromptEntry(getConfig<AgentProfile>(AGENT_PROFILE_NAMESPACE, canonical));
+}
+
+/** Whether the authoritative Project Instructions cell includes project memory in injection.
+ * Profile-less identities preserve the pre-profile open default; an unknown named profile still
+ * fails closed because its selected switch cannot be resolved. */
+export function projectMemoryEnabledForProfile(
+  profileName: string | undefined,
+  resolvedProfile?: Pick<AgentProfile, "name" | "instructions" | "sources">,
+): boolean {
+  if (!profileName) return true;
+  const profile = resolvedProfile?.name === profileName ? resolvedProfile : getAgentProfile(profileName)?.value;
+  return profile ? projectInstructionsOn(profile) : false;
+}
+
+/** Profile policy only. Runtime token derivation clamps launch authority and lineage. */
+export function spawnGrantForProfile(
+  profileName: string | undefined,
+): { canSpawn: boolean; maxSpawnedAgents: number } {
+  const n = profileName ? (getAgentProfile(profileName)?.value.maxSpawnedAgents ?? 0) : 0;
+  return { canSpawn: n > 0, maxSpawnedAgents: n };
+}
+
+/** Whether a profile keeps its runner token bound to the launch host (#1018 opt-out). */
+export function hostPinForProfile(profileName: string | undefined): boolean {
+  if (legacyProfileAliasPinsHost(profileName)) return true;
+  return profileName ? getAgentProfile(profileName)?.value.hostPinned === true : false;
+}
+
+/**
+ * Relay tool groups enabled for a profile (#551). Absent profile OR an absent `groups` key → undefined
+ * (FULL surface). An explicit `groups: []` enables no optional groups; the shared resolver
+ * retains core/self-care and explicit includes (#3261). Because that flips the meaning of any row that
+ * historically persisted `[]`, the one-shot `rewriteEmptyToolGroupsToAbsent` migration rewrites every
+ * pre-existing `[]` row to absent (preserving its old "all" behaviour) BEFORE this runs, so only a
+ * row saved AFTER N2 lands can mean NONE. See src/db/tool-groups-empty-migration.ts.
+ */
+export function toolGroupsForProfile(profileName: string | undefined): string[] | undefined {
+  if (!profileName) return undefined;
+  return getAgentProfile(profileName)?.value.relay.tools?.groups;
+}
+
+export function listAgentProfiles(): ConfigEntry<AgentProfile>[] {
+  const custom = listConfig<AgentProfile>(AGENT_PROFILE_NAMESPACE).filter((entry) => !memoryRetirementMessage(entry.key));
+  return [
+    ...builtInAgentProfiles().map(builtInProfileEntry),
+    ...custom.map(entry => ({ ...entry, value: applyProfilePromptSlots(entry.value) })),
+  ].sort((a, b) => Number(Boolean(b.value.builtIn)) - Number(Boolean(a.value.builtIn)) || a.key.localeCompare(b.key));
+}
+
+export function setAgentProfile(profile: AgentProfile, updatedBy?: string, opts: { overrideBuiltIn?: boolean } = {}): ConfigEntry<AgentProfile> {
+  if (BUILT_IN_AGENT_PROFILE_NAMES.has(profile.name) && opts.overrideBuiltIn) {
+    // The rollback snapshot is dropped by setConfigInternal on this override write (#1963 N10).
+    setConfig(AGENT_PROFILE_OVERRIDE_NAMESPACE, profile.name, profile, updatedBy);
+    return getAgentProfile(profile.name)!;
+  }
+  return applyProfilePromptEntry(setConfig(AGENT_PROFILE_NAMESPACE, profile.name, profile, updatedBy))!;
+}
+
+export function deleteAgentProfile(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): boolean {
+  // #2791 — delete resolves case-insensitively to the stored key, so DELETE /qa drops "QA".
+  const canonical = resolveAgentProfileKey(name) ?? name;
+  if (BUILT_IN_AGENT_PROFILE_NAMES.has(canonical)) {
+    // The rollback snapshot is dropped by deleteConfigInternal on this override delete (#1963 N10).
+    if (opts.resetBuiltInOverride) return deleteConfig(AGENT_PROFILE_OVERRIDE_NAMESPACE, canonical, updatedBy);
+    throw new ValidationError("built-in agent profiles are managed by Relay");
+  }
+  return deleteConfig(AGENT_PROFILE_NAMESPACE, canonical, updatedBy);
+}
+
+export function getManagedAgentState(policyName: string): ManagedAgentState | null {
+  const row = getDb().query("SELECT * FROM managed_agent_state WHERE policy_name = ?").get(policyName) as ManagedAgentStateRow | undefined;
+  return row ? rowToManagedAgentState(row) : null;
+}
+
+/**
+ * The steward-provenance agent binding for `policyName` — the last relay-written `agent_id`, RETAINED
+ * across the steward's OWN stop (#1623). `agent_id` is nulled on backoff/stop/fail (it is the live-agent
+ * pointer other consumers read as "running"), so a restart of a stopped genuine steward must not lose
+ * its provenance; `last_agent_id` preserves it. Prefer the live `agent_id`, fall back to the retained
+ * `last_agent_id`. Used by `isProvenStewardAgent` (steward-spawn-guard.ts).
+ *
+ * Unforgeability is CONDITIONAL, not inherent (#1797). Both columns are relay-written, but "written
+ * by the relay" says nothing about where the relay got the value. Two rounds of #1797 each found a
+ * caller-controlled input reaching this pointer, so state the guard explicitly rather than the
+ * conclusion. `markManagedAgentRunning` is the writer that matters, and it is reachable two ways:
+ *   1. agent REGISTRATION — took its (policyName, spawnRequestId) from caller-sent `agent.meta`.
+ *      Now gated: a scoped caller must carry that pair in its SIGNED constraints, and registration
+ *      additionally strips authz-relevant meta the caller isn't signed for.
+ *   2. the ORCHESTRATOR-REPORT projection (`PATCH /api/orchestrators/:id/agents` →
+ *      `onOrchestratorManagedAgentsReported`) — a `system` context built from a request body, so
+ *      gate (1) does not apply to it. Round 2 (F1) found it reachable by any `command:write` holder.
+ *      Now gated on the caller holding the orchestrator-host credential for that id.
+ * So: this pointer is as trustworthy as those two gates, and NO stronger. A new writer, or a new
+ * route that mints a `system`/privileged context from caller input, must establish an equivalent
+ * claim — otherwise `isProvenStewardAgent` silently stops being provenance.
+ */
+export function managedStewardBoundAgentId(policyName: string): string | undefined {
+  const row = getDb().query("SELECT agent_id, last_agent_id FROM managed_agent_state WHERE policy_name = ?").get(policyName) as { agent_id: string | null; last_agent_id: string | null } | undefined;
+  return row?.agent_id ?? row?.last_agent_id ?? undefined;
+}
+
+function listManagedAgentStates(): ManagedAgentState[] {
+  const rows = getDb()
+    .query("SELECT * FROM managed_agent_state ORDER BY policy_name ASC")
+    .all() as ManagedAgentStateRow[];
+  return rows.map(rowToManagedAgentState);
+}
+
+export function upsertManagedAgentState(input: ManagedAgentStateInput): ManagedAgentState {
+  if (!VALID_MANAGED_STATUSES.includes(input.status)) throw new ValidationError("status must be a managed-agent status");
+  if (!isSpawnProvider(input.provider)) throw new ValidationError(`provider must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
+  const now = input.updatedAt ?? Date.now();
+  getDb().query(`
+    INSERT INTO managed_agent_state (
+      policy_name, status, agent_id, last_agent_id, orchestrator_id, provider, tmux_session, spawn_request_id, workspace_id, workspace_path, workspace_branch,
+      last_spawn_at, last_stop_at, healthy_since, restart_count, consecutive_failures,
+      backoff_until, last_error, updated_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(policy_name) DO UPDATE SET
+      status = excluded.status,
+      agent_id = excluded.agent_id,
+      -- #1623 — RETAIN the last relay-written agent_id when the new agent_id is NULL (stop/backoff/
+      -- fail), so the steward-provenance binding survives the steward's own stop.
+      last_agent_id = COALESCE(excluded.agent_id, managed_agent_state.last_agent_id),
+      orchestrator_id = excluded.orchestrator_id,
+      provider = excluded.provider,
+      tmux_session = excluded.tmux_session,
+      spawn_request_id = excluded.spawn_request_id,
+      workspace_id = excluded.workspace_id,
+      workspace_path = excluded.workspace_path,
+      workspace_branch = excluded.workspace_branch,
+      last_spawn_at = excluded.last_spawn_at,
+      last_stop_at = excluded.last_stop_at,
+      healthy_since = excluded.healthy_since,
+      restart_count = excluded.restart_count,
+      consecutive_failures = excluded.consecutive_failures,
+      backoff_until = excluded.backoff_until,
+      last_error = excluded.last_error,
+      updated_at = excluded.updated_at
+  `).run(
+    input.policyName,
+    input.status,
+    input.agentId ?? null,
+    // last_agent_id seed on first INSERT; the ON CONFLICT clause COALESCEs to retain it on later stops.
+    input.agentId ?? null,
+    input.orchestratorId,
+    input.provider,
+    input.tmuxSession ?? null,
+    input.spawnRequestId ?? null,
+    input.workspaceId ?? null,
+    input.workspacePath ?? null,
+    input.workspaceBranch ?? null,
+    input.lastSpawnAt ?? null,
+    input.lastStopAt ?? null,
+    input.healthySince ?? null,
+    input.restartCount ?? 0,
+    input.consecutiveFailures ?? 0,
+    input.backoffUntil ?? null,
+    input.lastError ?? null,
+    now,
+  );
+  return getManagedAgentState(input.policyName)!;
+}
+
+export function updateManagedAgentState(policyName: string, patch: ManagedAgentStatePatch): ManagedAgentState | null {
+  const existing = getManagedAgentState(policyName);
+  if (!existing) return null;
+  return upsertManagedAgentState({
+    ...existing,
+    ...patch,
+    policyName,
+    updatedAt: patch.updatedAt ?? Date.now(),
+  });
+}
+
+function deleteManagedAgentState(policyName: string): boolean {
+  const result = getDb().query("DELETE FROM managed_agent_state WHERE policy_name = ?").run(policyName);
+  return result.changes > 0;
+}