@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/config/project-security.ts

@@ -0,0 +1,940 @@
+import {
+    DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE,
+    PER_HARNESS_MIGRATION_INVENTORY,
+    PER_HARNESS_MODEL_KEYS,
+} from "./schema/magic-context";
+
+/**
+ * Security hardening for PROJECT-level (repo-supplied, untrusted) config.
+ *
+ * A project config lives inside a repository the user cloned. Opening a repo
+ * must never let that repo's config escalate privilege or exfiltrate secrets.
+ * These helpers run on the raw project config BEFORE/AFTER it is merged over the
+ * trusted user config, mutating the relevant object in place and returning
+ * human-readable warnings.
+ *
+ * Shared by OpenCode and the Pi-compatible Pi/OMP extension so the trust
+ * boundary is identical across every supported harness.
+ */
+
+/** Hidden agents that run with elevated/autonomous capability. */
+const HIDDEN_AGENT_KEYS = ["historian"] as const;
+const HARNESS_KEYS = PER_HARNESS_MODEL_KEYS;
+/** Every historian model-resolution field, including per-harness qualifiers.
+ *  Variant and thinking_level merge onto the user's historian model at resolve
+ *  time, so leaving them would let a cloned repo force extra spend. */
+const HISTORIAN_USER_ONLY_FIELDS = PER_HARNESS_MIGRATION_INVENTORY.historian.migrated_execution;
+const PROMPT_SURFACE_USER_ONLY_FIELDS = ["guidance_override_path", "tool_descriptions"] as const;
+
+/**
+ * Fields on a hidden-agent block that constitute a privilege-escalation /
+ * code-execution vector when set from an untrusted repo:
+ *
+ *  - `prompt`     — reprograms the agent's instructions.
+ *  - `permission` — broadens the agent's per-tool permissions.
+ *  - `tools`      — enable/disable map; could flip a denied tool (e.g. `bash`)
+ *                   on for an agent whose allow-list intentionally excludes it.
+ * Historian model selection stays USER-tier only, and compaction thresholds are
+ * project raise-only, so a cloned repo cannot force earlier compaction or extra
+ * historian spend on the user's dime.
+ */
+const AGENT_ESCALATION_FIELDS = ["prompt", "permission", "tools"] as const;
+const PERCENTAGE_THRESHOLD_REASON =
+    "security: a repository may only raise compaction thresholds above the user's effective value; it cannot force earlier historian work or cloned-repo cost escalation.";
+const TOKEN_THRESHOLD_REASON =
+    "security: a repository may only raise execute_threshold_tokens above the user's trusted token threshold; it cannot force earlier historian work or cloned-repo cost escalation.";
+const TOKEN_THRESHOLD_INTRODUCTION_REASON =
+    "security: a repository cannot introduce a new execute_threshold_tokens override when the user has no trusted token threshold for that key; that could force earlier historian work or cloned-repo cost escalation.";
+const PROTECTED_TOKENS_REASON =
+    "security: a repository may only raise protected_tokens above the resolved user-or-derived floor; it cannot lower protection.";
+
+interface PercentageThresholdConfig {
+    defaultValue: number;
+    overrides: Map<string, number>;
+}
+
+interface TokenThresholdConfig {
+    defaultValue: number | undefined;
+    overrides: Map<string, number>;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function resolveProtectedTokensScalar(value: unknown): number | undefined {
+    if (
+        typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= 4000 &&
+        value <= 1_000_000
+    ) {
+        return value;
+    }
+    return undefined;
+}
+
+export interface ProtectedTokensTierOverrides {
+    readonly user?: number;
+    readonly project?: number;
+}
+
+const PROTECTED_TOKENS_TIER_OVERRIDES = Symbol.for(
+    "@retaw106/mmc-oc/protected-tokens-tier-overrides",
+);
+
+type ConfigWithProtectedTokensTiers = {
+    [PROTECTED_TOKENS_TIER_OVERRIDES]?: ProtectedTokensTierOverrides;
+};
+
+/**
+ * Retain trusted user and project values outside the public config schema until
+ * live context geometry is available. The symbol is non-enumerable so runtime
+ * provenance cannot leak into saved JSON or generated schema surfaces.
+ */
+export function attachProtectedTokensTierOverrides<T extends object>(
+    config: T,
+    args: { trustedUser: unknown; project: unknown },
+): T {
+    const user = resolveProtectedTokensScalar(args.trustedUser);
+    const rawProject = resolveProtectedTokensScalar(args.project);
+    const project =
+        rawProject !== undefined && (user === undefined || rawProject >= user)
+            ? rawProject
+            : undefined;
+    if (user === undefined && project === undefined) return config;
+
+    Object.defineProperty(config, PROTECTED_TOKENS_TIER_OVERRIDES, {
+        value: {
+            ...(user !== undefined ? { user } : {}),
+            ...(project !== undefined ? { project } : {}),
+        },
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+    return config;
+}
+
+export function getProtectedTokensTierOverrides(
+    config: object,
+): ProtectedTokensTierOverrides | undefined {
+    return (config as ConfigWithProtectedTokensTiers)[PROTECTED_TOKENS_TIER_OVERRIDES];
+}
+
+function stripListedFields(
+    target: Record<string, unknown>,
+    fields: readonly string[],
+    path: string,
+    removed: string[],
+): void {
+    for (const field of fields) {
+        if (field in target) {
+            delete target[field];
+            removed.push(path.length > 0 ? `${path}.${field}` : field);
+        }
+    }
+}
+
+/** Strip prompt, permission, tools, and system_prompt from one agent, harness,
+ *  task, or model-entry object, including each fallback_models entry. A cloned
+ *  repo must not reprogram hidden agents through any of those nestings. */
+function stripEscalationAtExecutableSite(
+    block: Record<string, unknown>,
+    path: string,
+    removed: string[],
+): void {
+    stripListedFields(block, AGENT_ESCALATION_FIELDS, path, removed);
+    if (isPlainObject(block.model)) {
+        stripListedFields(block.model, AGENT_ESCALATION_FIELDS, `${path}.model`, removed);
+    }
+    if (Array.isArray(block.fallback_models)) {
+        for (let index = 0; index < block.fallback_models.length; index++) {
+            const entry = block.fallback_models[index];
+            if (isPlainObject(entry)) {
+                stripListedFields(
+                    entry,
+                    AGENT_ESCALATION_FIELDS,
+                    `${path}.fallback_models.${index}`,
+                    removed,
+                );
+            }
+        }
+    }
+}
+
+// Must match the schema's execute_threshold_percentage range (20-90). A narrower
+// range here let a valid project value of 81-90 skip the raise-only clamp and
+// reach the merged config as-is, lowering a higher user threshold.
+function isValidPercentageThreshold(value: unknown): value is number {
+    return typeof value === "number" && Number.isFinite(value) && value >= 20 && value <= 90;
+}
+
+function isValidTokenThreshold(value: unknown): value is number {
+    return (
+        typeof value === "number" && Number.isFinite(value) && value >= 5_000 && value <= 2_000_000
+    );
+}
+
+function normalizeTrustedPercentageThresholds(value: unknown): PercentageThresholdConfig {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return { defaultValue: value, overrides: new Map() };
+    }
+
+    if (
+        isPlainObject(value) &&
+        typeof value.default === "number" &&
+        Number.isFinite(value.default)
+    ) {
+        const overrides = new Map<string, number>();
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "default") continue;
+            if (typeof child === "number" && Number.isFinite(child)) {
+                overrides.set(key, child);
+            }
+        }
+        return { defaultValue: value.default, overrides };
+    }
+
+    return { defaultValue: DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE, overrides: new Map() };
+}
+
+function normalizeTrustedTokenThresholds(value: unknown): TokenThresholdConfig {
+    if (!isPlainObject(value)) {
+        return { defaultValue: undefined, overrides: new Map() };
+    }
+
+    const overrides = new Map<string, number>();
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "default") continue;
+        if (typeof child === "number" && Number.isFinite(child)) {
+            overrides.set(key, child);
+        }
+    }
+
+    return {
+        defaultValue:
+            typeof value.default === "number" && Number.isFinite(value.default)
+                ? value.default
+                : undefined,
+        overrides,
+    };
+}
+
+function clonePercentageThresholds(value: PercentageThresholdConfig): PercentageThresholdConfig {
+    return {
+        defaultValue: value.defaultValue,
+        overrides: new Map(value.overrides),
+    };
+}
+
+function cloneTokenThresholds(value: TokenThresholdConfig): TokenThresholdConfig {
+    return {
+        defaultValue: value.defaultValue,
+        overrides: new Map(value.overrides),
+    };
+}
+
+function percentageThresholdsEqual(
+    left: PercentageThresholdConfig,
+    right: PercentageThresholdConfig,
+): boolean {
+    if (left.defaultValue !== right.defaultValue) return false;
+    if (left.overrides.size !== right.overrides.size) return false;
+    for (const [key, value] of left.overrides) {
+        if (right.overrides.get(key) !== value) return false;
+    }
+    return true;
+}
+
+function setMergedPercentageThreshold(
+    mergedRaw: Record<string, unknown>,
+    value: PercentageThresholdConfig,
+): void {
+    if (value.overrides.size === 0) {
+        mergedRaw.execute_threshold_percentage = value.defaultValue;
+        return;
+    }
+
+    const serialized: Record<string, number> = { default: value.defaultValue };
+    for (const [key, threshold] of value.overrides) {
+        serialized[key] = threshold;
+    }
+    mergedRaw.execute_threshold_percentage = serialized;
+}
+
+function setMergedTokenThreshold(
+    mergedRaw: Record<string, unknown>,
+    value: TokenThresholdConfig,
+): void {
+    if (value.defaultValue === undefined && value.overrides.size === 0) {
+        delete mergedRaw.execute_threshold_tokens;
+        return;
+    }
+
+    const serialized: Record<string, number> = {};
+    if (value.defaultValue !== undefined) {
+        serialized.default = value.defaultValue;
+    }
+    for (const [key, threshold] of value.overrides) {
+        serialized[key] = threshold;
+    }
+    mergedRaw.execute_threshold_tokens = serialized;
+}
+
+function makeProjectThresholdWarning(field: string, reason: string): string {
+    return `Ignoring ${field} from project config (${reason})`;
+}
+
+/**
+ * Strip unsafe fields from a raw PROJECT config IN PLACE, before it is merged
+ * over the user config. Returns warnings describing what was ignored.
+ *
+ * Closes:
+ *  - `profiles` — profile definitions choose hidden-agent models and must stay
+ *    in trusted user config; a repository may select a named profile but cannot
+ *    supply its contents.
+ *  - `auto_update` — a repo must not suppress plugin self-updates (which can
+ *    carry security fixes).
+ *  - `fail_closed_blocking` — a repo must not un-block (or force-block) the
+ *    loud inoperability gate; only the user may restore silent degrade.
+ *  - `debug_rpc` — a repo must not enable process heap capture or memory diagnostics.
+ *  - `allow_home_project` — only the user may opt a home-directory session
+ *    into a durable project identity.
+ *  - `output_reserve` / `models.window_overlay_path` — only the user may change
+ *    process-wide window geometry inputs.
+ *  - `language`: a repo must not inject prompt text through a user preference.
+ *  - `maintenance` — budgets, cooldowns, and anomaly thresholds of the
+ *    automatic memory-maintenance task are user-level only; a cloned repo
+ *    must not re-budget or re-arm an autonomous spend-capable task.
+ *  - `sqlite` — `sqlite.cache_size_mb` / `mmap_size_mb` become PRAGMAs on the
+ *    process-global shared DB handle (one connection across every project in the
+ *    process). A cloned repo could set a huge value to exhaust host memory /
+ *    address space — a resource-exhaustion vector with no legitimate per-repo
+ *    use. Honor user-level config only.
+ *  - `storage.enforce_private_permissions` — changing a shared store from
+ *    owner-private to group-readable changes every session and memory's local
+ *    confidentiality. Only the machine operator's user config may opt into an
+ *    externally managed trusted-group deployment.
+ *  - historian model-resolution fields (model, fallback_models, variant,
+ *    thinking_level), including both per-harness blocks — historian model
+ *    spend is user-level only. Qualifiers merge onto the user's historian
+ *    model at resolve time, so a cloned repo cannot force extra thinking or
+ *    variant cost.
+ *  - `pi.subagent_extensions` — a cloned repo must not choose which extensions
+ *    the user's Pi child processes load.
+ *  - `prompt_surface.guidance_override_path` / `tool_descriptions` — a repository
+ *    may select a reviewed preset, but must not inject arbitrary guidance or tool
+ *    description text into the user's provider-visible prompt.
+ *  - hidden-agent `prompt`/`permission`/`tools`/`system_prompt` at the agent
+ *    root, each harness block, each task block, and inside model/fallback
+ *    entry objects — a repo must not reprogram or re-permission hidden agents.
+ */
+export function stripUnsafeProjectConfigFields(projectRaw: Record<string, unknown>): string[] {
+    const warnings: string[] = [];
+
+    if ("profiles" in projectRaw) {
+        delete projectRaw.profiles;
+        warnings.push(
+            "Ignoring profiles from project config (security: profile definitions are user-level only; a repository may select a named user profile with profile).",
+        );
+    }
+
+    if ("auto_update" in projectRaw) {
+        delete projectRaw.auto_update;
+        warnings.push(
+            "Ignoring auto_update from project config (security: this setting only honors user-level config).",
+        );
+    }
+
+    if ("fail_closed_blocking" in projectRaw) {
+        delete projectRaw.fail_closed_blocking;
+        warnings.push(
+            "Ignoring fail_closed_blocking from project config (security: only user-level config may disable or force the loud inoperability gate).",
+        );
+    }
+
+    if ("debug_rpc" in projectRaw) {
+        delete projectRaw.debug_rpc;
+        warnings.push(
+            "Ignoring debug_rpc from project config (security: only user-level config may enable process heap diagnostics).",
+        );
+    }
+
+    if ("allow_home_project" in projectRaw) {
+        delete projectRaw.allow_home_project;
+        warnings.push(
+            "Ignoring allow_home_project from project config (security: only user-level config may opt the user's home directory into Magic Context).",
+        );
+    }
+
+    // compaction.enabled is USER-tier only: a cloned repo must never silently
+    // disable the user's context management (it changes how the window is
+    // owned and interacts with native compaction state). Field-scoped, not
+    // block-scoped: a sibling key in a project `compaction` block survives the
+    // strip, so a future project-tier compaction knob can still land.
+    const compaction = projectRaw.compaction;
+    if (isPlainObject(compaction) && "enabled" in compaction) {
+        delete compaction.enabled;
+        warnings.push(
+            "Ignoring compaction.enabled from project config (security: only user-level config may disable Magic Context's context-window management; a cloned repo cannot change how the user's window is owned).",
+        );
+    }
+
+    // maintenance.* is USER-tier only (memory-maintenance plan decision 27).
+    // The group budgets an autonomous, spend-capable task. Unlike
+    // compaction.enabled (field-scoped so a future project-tier compaction
+    // knob can land), EVERY key in this group is user-only, so the whole
+    // block is stripped: a cloned repo must not raise run budgets, relax
+    // cooldowns/backoff, or loosen the anomaly guard to weaponize the
+    // maintenance task (cost escalation or a mass-archive cover).
+    if ("maintenance" in projectRaw) {
+        delete projectRaw.maintenance;
+        warnings.push(
+            "Ignoring maintenance from project config (security: automatic memory maintenance budgets, cooldowns, and anomaly thresholds are user-level only; a cloned repo cannot re-budget or re-arm the maintenance task).",
+        );
+    }
+
+    if ("output_reserve" in projectRaw) {
+        delete projectRaw.output_reserve;
+        warnings.push(
+            "Ignoring output_reserve from project config (security: output-token reservation only honors user-level config).",
+        );
+    }
+
+    const models = projectRaw.models;
+    if (isPlainObject(models) && "window_overlay_path" in models) {
+        delete models.window_overlay_path;
+        warnings.push(
+            "Ignoring models.window_overlay_path from project config (security: only user-level config may select model geometry metadata).",
+        );
+    }
+
+    if ("language" in projectRaw) {
+        delete projectRaw.language;
+        warnings.push(
+            "Ignoring language from project config (security: output language is a user-level setting).",
+        );
+    }
+
+    if ("sqlite" in projectRaw) {
+        delete projectRaw.sqlite;
+        warnings.push(
+            "Ignoring sqlite.* from project config (security: SQLite cache/mmap PRAGMAs apply to the " +
+                "process-global shared database handle; only user-level config may set them).",
+        );
+    }
+
+    // storage.enforce_private_permissions is USER-tier only because disabling it
+    // changes the confidentiality of the process-global shared store. Field-scoped
+    // stripping preserves future project-tier storage settings in the same block.
+    const storage = projectRaw.storage;
+    if (isPlainObject(storage) && "enforce_private_permissions" in storage) {
+        delete storage.enforce_private_permissions;
+        warnings.push(
+            "Ignoring storage.enforce_private_permissions from project config (security: only user-level config may opt into externally managed shared storage permissions).",
+        );
+    }
+
+    // Repositories may select preset routing, but project settings cannot add
+    // guidance or tool-description text to the provider-visible prompt; those
+    // user-only fields are removed before project settings are merged.
+    const promptSurface = projectRaw.prompt_surface;
+    if (isPlainObject(promptSurface)) {
+        const removed: string[] = [];
+        for (const field of PROMPT_SURFACE_USER_ONLY_FIELDS) {
+            if (field in promptSurface) {
+                delete promptSurface[field];
+                removed.push(field);
+            }
+        }
+        if (removed.length > 0) {
+            warnings.push(
+                `Ignoring prompt_surface.${removed.join("/")} from project config (security: repositories may select prompt presets but only user config may provide guidance or tool-description text).`,
+            );
+        }
+    }
+
+    const pi = projectRaw.pi;
+    if (isPlainObject(pi) && "subagent_extensions" in pi) {
+        delete pi.subagent_extensions;
+        warnings.push(
+            "Ignoring pi.subagent_extensions from project config (security: only user-level config may choose extensions loaded by Pi subagent children).",
+        );
+    }
+
+    for (const agentKey of HIDDEN_AGENT_KEYS) {
+        const block = projectRaw[agentKey];
+        if (!isPlainObject(block)) continue;
+        const removed: string[] = [];
+        stripEscalationAtExecutableSite(block, agentKey, removed);
+        for (const harness of HARNESS_KEYS) {
+            const harnessBlock = block[harness];
+            if (!isPlainObject(harnessBlock)) continue;
+            stripEscalationAtExecutableSite(harnessBlock, `${agentKey}.${harness}`, removed);
+            const tasks = harnessBlock.tasks;
+            if (isPlainObject(tasks)) {
+                for (const [taskName, taskBlock] of Object.entries(tasks)) {
+                    if (isPlainObject(taskBlock)) {
+                        stripEscalationAtExecutableSite(
+                            taskBlock,
+                            `${agentKey}.${harness}.tasks.${taskName}`,
+                            removed,
+                        );
+                    }
+                }
+            }
+        }
+        const schedulingTasks = block.tasks;
+        if (isPlainObject(schedulingTasks)) {
+            for (const [taskName, taskBlock] of Object.entries(schedulingTasks)) {
+                if (isPlainObject(taskBlock)) {
+                    stripListedFields(
+                        taskBlock,
+                        AGENT_ESCALATION_FIELDS,
+                        `${agentKey}.tasks.${taskName}`,
+                        removed,
+                    );
+                }
+            }
+        }
+        if (removed.length > 0) {
+            warnings.push(
+                `Ignoring ${removed.join(", ")} from project config ` +
+                    "(security: a repository cannot reprogram or re-permission hidden agents).",
+            );
+        }
+    }
+
+    const historian = projectRaw.historian;
+    if (isPlainObject(historian)) {
+        const removed: string[] = [];
+        for (const field of HISTORIAN_USER_ONLY_FIELDS) {
+            if (field in historian) {
+                delete historian[field];
+                removed.push(field);
+            }
+        }
+        for (const harness of HARNESS_KEYS) {
+            const harnessBlock = historian[harness];
+            if (!isPlainObject(harnessBlock)) continue;
+            for (const field of HISTORIAN_USER_ONLY_FIELDS) {
+                if (field in harnessBlock) {
+                    delete harnessBlock[field];
+                    removed.push(`${harness}.${field}`);
+                }
+            }
+        }
+        if (removed.length > 0) {
+            warnings.push(
+                `Ignoring ${removed.map((path) => `historian.${path}`).join(", ")} from project config ` +
+                    "(security: historian model selection is user-level only; a repository cannot force extra compaction cost).",
+            );
+        }
+    }
+
+    return warnings;
+}
+
+/**
+ * Clamp project-tier compaction thresholds after merge so a cloned repository
+ * may only DELAY compaction relative to the trusted user/default settings. A
+ * repo may never lower thresholds in a way that forces earlier historian work
+ * or cloned-repo cost escalation on the user's account.
+ */
+export function constrainProjectThresholdOverrides(args: {
+    mergedRaw: Record<string, unknown>;
+    projectRaw: Record<string, unknown>;
+    trustedBaseConfig: {
+        execute_threshold_percentage?: unknown;
+        execute_threshold_tokens?: unknown;
+        protected_tokens?: unknown;
+    };
+}): string[] {
+    const warnings: string[] = [];
+    const basePercentage = normalizeTrustedPercentageThresholds(
+        args.trustedBaseConfig.execute_threshold_percentage,
+    );
+    const baseTokens = normalizeTrustedTokenThresholds(
+        args.trustedBaseConfig.execute_threshold_tokens,
+    );
+
+    if ("execute_threshold_percentage" in args.projectRaw) {
+        const projectValue = args.projectRaw.execute_threshold_percentage;
+
+        if (isValidPercentageThreshold(projectValue)) {
+            const constrained = clonePercentageThresholds(basePercentage);
+            constrained.defaultValue = Math.max(basePercentage.defaultValue, projectValue);
+            for (const [modelKey, threshold] of basePercentage.overrides) {
+                const raisedThreshold = Math.max(threshold, projectValue);
+                if (raisedThreshold === constrained.defaultValue) {
+                    constrained.overrides.delete(modelKey);
+                } else {
+                    constrained.overrides.set(modelKey, raisedThreshold);
+                }
+            }
+            setMergedPercentageThreshold(args.mergedRaw, constrained);
+            if (percentageThresholdsEqual(constrained, basePercentage)) {
+                warnings.push(
+                    makeProjectThresholdWarning(
+                        "execute_threshold_percentage",
+                        PERCENTAGE_THRESHOLD_REASON,
+                    ),
+                );
+            }
+        } else if (isPlainObject(projectValue)) {
+            const constrained = clonePercentageThresholds(basePercentage);
+            let touchedValidEntry = false;
+
+            if (isValidPercentageThreshold(projectValue.default)) {
+                touchedValidEntry = true;
+                if (projectValue.default > basePercentage.defaultValue) {
+                    constrained.defaultValue = projectValue.default;
+                } else {
+                    warnings.push(
+                        makeProjectThresholdWarning(
+                            "execute_threshold_percentage.default",
+                            PERCENTAGE_THRESHOLD_REASON,
+                        ),
+                    );
+                }
+            }
+
+            for (const [modelKey, rawValue] of Object.entries(projectValue)) {
+                if (modelKey === "default") continue;
+                if (!isValidPercentageThreshold(rawValue)) continue;
+                touchedValidEntry = true;
+                const baseValue =
+                    basePercentage.overrides.get(modelKey) ?? basePercentage.defaultValue;
+                if (rawValue > baseValue) {
+                    if (rawValue === constrained.defaultValue) {
+                        constrained.overrides.delete(modelKey);
+                    } else {
+                        constrained.overrides.set(modelKey, rawValue);
+                    }
+                } else {
+                    warnings.push(
+                        makeProjectThresholdWarning(
+                            `execute_threshold_percentage.${modelKey}`,
+                            PERCENTAGE_THRESHOLD_REASON,
+                        ),
+                    );
+                }
+            }
+
+            if (touchedValidEntry) {
+                setMergedPercentageThreshold(args.mergedRaw, constrained);
+            }
+        }
+    }
+
+    if (
+        "execute_threshold_tokens" in args.projectRaw &&
+        isPlainObject(args.projectRaw.execute_threshold_tokens)
+    ) {
+        const projectValue = args.projectRaw.execute_threshold_tokens;
+        const constrained = cloneTokenThresholds(baseTokens);
+        let touchedValidEntry = false;
+
+        if (isValidTokenThreshold(projectValue.default)) {
+            touchedValidEntry = true;
+            if (baseTokens.defaultValue === undefined) {
+                warnings.push(
+                    makeProjectThresholdWarning(
+                        "execute_threshold_tokens.default",
+                        TOKEN_THRESHOLD_INTRODUCTION_REASON,
+                    ),
+                );
+            } else if (projectValue.default > baseTokens.defaultValue) {
+                constrained.defaultValue = projectValue.default;
+            } else {
+                warnings.push(
+                    makeProjectThresholdWarning(
+                        "execute_threshold_tokens.default",
+                        TOKEN_THRESHOLD_REASON,
+                    ),
+                );
+            }
+        }
+
+        for (const [modelKey, rawValue] of Object.entries(projectValue)) {
+            if (modelKey === "default") continue;
+            if (!isValidTokenThreshold(rawValue)) continue;
+            touchedValidEntry = true;
+            const baseValue = baseTokens.overrides.get(modelKey) ?? baseTokens.defaultValue;
+            if (baseValue === undefined) {
+                warnings.push(
+                    makeProjectThresholdWarning(
+                        `execute_threshold_tokens.${modelKey}`,
+                        TOKEN_THRESHOLD_INTRODUCTION_REASON,
+                    ),
+                );
+                continue;
+            }
+            if (rawValue > baseValue) {
+                if (rawValue === constrained.defaultValue) {
+                    constrained.overrides.delete(modelKey);
+                } else {
+                    constrained.overrides.set(modelKey, rawValue);
+                }
+            } else {
+                warnings.push(
+                    makeProjectThresholdWarning(
+                        `execute_threshold_tokens.${modelKey}`,
+                        TOKEN_THRESHOLD_REASON,
+                    ),
+                );
+            }
+        }
+
+        if (touchedValidEntry) {
+            setMergedTokenThreshold(args.mergedRaw, constrained);
+        }
+    }
+
+    if ("protected_tokens" in args.projectRaw) {
+        const rawProject = args.projectRaw.protected_tokens;
+        const projectVal = resolveProtectedTokensScalar(rawProject);
+        const trustedUserVal = resolveProtectedTokensScalar(
+            args.trustedBaseConfig.protected_tokens,
+        );
+
+        if (projectVal !== undefined) {
+            if (trustedUserVal !== undefined) {
+                if (projectVal >= trustedUserVal) {
+                    args.mergedRaw.protected_tokens = projectVal;
+                } else {
+                    args.mergedRaw.protected_tokens = trustedUserVal;
+                    warnings.push(
+                        makeProjectThresholdWarning("protected_tokens", PROTECTED_TOKENS_REASON),
+                    );
+                }
+            } else {
+                args.mergedRaw.protected_tokens = projectVal;
+            }
+        } else {
+            if (trustedUserVal !== undefined) {
+                args.mergedRaw.protected_tokens = trustedUserVal;
+            } else {
+                delete args.mergedRaw.protected_tokens;
+            }
+            warnings.push(makeProjectThresholdWarning("protected_tokens", PROTECTED_TOKENS_REASON));
+        }
+    }
+
+    return warnings;
+}
+
+/** Path of a schema issue in the merged raw config, e.g. ["compaction", "enabled"]. */
+export type ConfigIssuePath = readonly PropertyKey[];
+
+/**
+ * Shortest prefix of `issuePath` whose value the PROJECT tier supplied, or
+ * undefined when the invalid value did not come from the project. The raw merge
+ * recurses only into plain objects on both sides, so the project owns the value
+ * at the first prefix where its node is not a plain object (a scalar, array or
+ * null replaces the user's value whole), or at the full issue path.
+ */
+function projectContributionPath(
+    projectRaw: Record<string, unknown>,
+    issuePath: ConfigIssuePath,
+): ConfigIssuePath | undefined {
+    let node: unknown = projectRaw;
+    for (let index = 0; index < issuePath.length; index++) {
+        const segment = String(issuePath[index]);
+        if (!isPlainObject(node) || !Object.hasOwn(node, segment)) return undefined;
+        node = node[segment];
+        if (index === issuePath.length - 1 || !isPlainObject(node)) {
+            return issuePath.slice(0, index + 1);
+        }
+    }
+    return undefined;
+}
+
+/**
+ * The trusted value the project displaced along `contribution`, and where it
+ * sits. Walking down, the first trusted node that is not a plain object was
+ * replaced whole by the project's object (e.g. a user scalar threshold of 80
+ * under a project `{ default: 5 }`), so it is restored at that shorter path.
+ * Undefined when the trusted tier has no value there to protect.
+ */
+function displacedTrustedValue(
+    trustedRaw: Record<string, unknown>,
+    contribution: ConfigIssuePath,
+): { path: ConfigIssuePath; value: unknown } | undefined {
+    let node: unknown = trustedRaw;
+    for (let index = 0; index < contribution.length; index++) {
+        const segment = String(contribution[index]);
+        if (!isPlainObject(node) || !Object.hasOwn(node, segment)) return undefined;
+        node = node[segment];
+        if (index === contribution.length - 1 || !isPlainObject(node)) {
+            return { path: contribution.slice(0, index + 1), value: node };
+        }
+    }
+    return undefined;
+}
+
+function defineOwnValue(target: Record<string, unknown>, key: string, value: unknown): void {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+}
+
+/** Put `value` at `path` in `root`, copying each object on the way so objects
+ *  shared with the trusted or project raw configs are never mutated. */
+function writeOwnPath(root: Record<string, unknown>, path: ConfigIssuePath, value: unknown): void {
+    let node = root;
+    for (let index = 0; index < path.length - 1; index++) {
+        const segment = String(path[index]);
+        const child = node[segment];
+        if (!isPlainObject(child)) return;
+        const copy = { ...child };
+        defineOwnValue(node, segment, copy);
+        node = copy;
+    }
+    defineOwnValue(node, String(path[path.length - 1]), value);
+}
+
+/** Most rounds a single load can take; each round restores at least one path. */
+const MAX_PROJECT_RESTORE_ROUNDS = 16;
+
+/**
+ * After the project config is merged over the trusted (user + profile) config,
+ * put back the trusted value wherever an INVALID project value displaced it.
+ *
+ * Without this, a repository could reset user settings by writing a wrong type:
+ * `compaction: false` replaces the user's `compaction` block in the raw merge,
+ * the schema rejects it, and schema recovery drops the key and uses the schema
+ * default, so compaction turns back on, the historian loses its model, or the
+ * embedding provider flips and forces a full re-embed. A repository may only
+ * tighten what the user configured, so an invalid project value is ignored and
+ * the user's value stays. When the user has no value at that path, the project
+ * value is left for normal schema recovery, which already lands on the default
+ * the user would get anyway.
+ *
+ * `collectIssuePaths` runs the caller's own pre-schema migrations and schema
+ * check and returns every issue path (empty when the config is valid), so this
+ * stays aligned with the loader's real parse on every harness. `mergedRaw` is
+ * mutated in place.
+ */
+export function restoreTrustedValuesOverInvalidProjectValues(args: {
+    mergedRaw: Record<string, unknown>;
+    trustedRaw: Record<string, unknown>;
+    projectRaw: Record<string, unknown>;
+    collectIssuePaths: (raw: Record<string, unknown>) => readonly ConfigIssuePath[];
+}): { warnings: string[]; restoredTopLevelKeys: string[] } {
+    const warnings: string[] = [];
+    const restoredTopLevelKeys = new Set<string>();
+    const restored = new Set<string>();
+
+    for (let round = 0; round < MAX_PROJECT_RESTORE_ROUNDS; round++) {
+        let changed = false;
+        for (const issuePath of args.collectIssuePaths(args.mergedRaw)) {
+            const contribution = projectContributionPath(args.projectRaw, issuePath);
+            if (contribution === undefined || contribution.length === 0) continue;
+            const trusted = displacedTrustedValue(args.trustedRaw, contribution);
+            if (trusted === undefined) continue;
+            const key = trusted.path.map(String).join(".");
+            // Already restored: any remaining issue there is in the user's own
+            // value, which normal schema recovery handles.
+            if (restored.has(key)) continue;
+            writeOwnPath(args.mergedRaw, trusted.path, trusted.value);
+            restored.add(key);
+            restoredTopLevelKeys.add(String(trusted.path[0]));
+            changed = true;
+            warnings.push(
+                `Ignoring invalid ${key} from project config and keeping the user-level value (security: a repository cannot reset user settings by supplying an invalid value).`,
+            );
+        }
+        if (!changed) break;
+    }
+
+    return { warnings, restoredTopLevelKeys: [...restoredTopLevelKeys] };
+}
+
+const PROJECT_COMMAND_STRING_FIELDS = ["description", "agent", "model"] as const;
+
+/** A well-formed command entry with only the fields the command config uses. */
+function wellFormedCommand(value: unknown): Record<string, unknown> | undefined {
+    if (!isPlainObject(value)) return undefined;
+    if (typeof value.template !== "string" || value.template.trim().length === 0) return undefined;
+    const command: Record<string, unknown> = { template: value.template };
+    for (const field of PROJECT_COMMAND_STRING_FIELDS) {
+        if (value[field] === undefined) continue;
+        if (typeof value[field] !== "string") return undefined;
+        command[field] = value[field];
+    }
+    if (value.subtask !== undefined) {
+        if (typeof value.subtask !== "boolean") return undefined;
+        command.subtask = value.subtask;
+    }
+    return command;
+}
+
+/**
+ * Rebuild the merged `command` block so a repository may only ADD commands.
+ *
+ * The command block is not part of the schema; it is copied into the host's
+ * command config after Magic Context's built-in commands. Merged as raw
+ * config, a project could replace a command the user defined, shadow a
+ * built-in /mmc-* command, wipe the user's commands with a non-object value,
+ * or pass malformed entries to the host. Now the user's commands are kept as
+ * they are, and a project entry is used only when it is well formed and its
+ * name is neither a user command nor one of `reservedNames`. `mergedRaw` is
+ * mutated in place.
+ */
+export function constrainProjectCommands(args: {
+    mergedRaw: Record<string, unknown>;
+    trustedRaw: Record<string, unknown>;
+    projectRaw: Record<string, unknown>;
+    reservedNames: readonly string[];
+}): string[] {
+    if (!("command" in args.projectRaw)) return [];
+    const warnings: string[] = [];
+    const trustedCommands = isPlainObject(args.trustedRaw.command)
+        ? args.trustedRaw.command
+        : undefined;
+    const merged: Record<string, unknown> = { ...(trustedCommands ?? {}) };
+    const projectCommands = args.projectRaw.command;
+
+    if (!isPlainObject(projectCommands)) {
+        warnings.push(
+            "Ignoring command from project config (it must be an object of named commands).",
+        );
+    } else {
+        for (const [name, value] of Object.entries(projectCommands)) {
+            if (trustedCommands && Object.hasOwn(trustedCommands, name)) {
+                warnings.push(
+                    `Ignoring command.${name} from project config (security: a repository cannot replace a command defined in user config).`,
+                );
+                continue;
+            }
+            if (args.reservedNames.includes(name)) {
+                warnings.push(
+                    `Ignoring command.${name} from project config (security: a repository cannot replace a built-in Magic Context command).`,
+                );
+                continue;
+            }
+            const command = wellFormedCommand(value);
+            if (!command) {
+                warnings.push(
+                    `Ignoring command.${name} from project config (it needs a non-empty string template; description, agent and model must be strings and subtask a boolean).`,
+                );
+                continue;
+            }
+            Object.defineProperty(merged, name, {
+                value: command,
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+
+    if (Object.keys(merged).length === 0) delete args.mergedRaw.command;
+    else args.mergedRaw.command = merged;
+    return warnings;
+}