@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/config/schema/magic-context.ts

@@ -0,0 +1,1019 @@
+import { z } from "zod";
+import { isValidLanguageCode } from "../../agents/language-directive";
+import { toolTemplateError } from "../../shared/historian-tool-template";
+import { isValidPromptSurfaceModelKey } from "../../shared/prompt-surface";
+import { AgentOverrideConfigSchema } from "./agent-overrides";
+
+export const DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE = 65;
+// Output reservation now removes generation capacity from the usable window.
+// The 90% cap leaves roughly 10% of that safe input budget for mid-turn growth;
+// escalation derives above the effective threshold and the 95% wall stays fixed.
+export const EXECUTE_THRESHOLD_CAP_MESSAGE =
+    "execute_threshold is capped at 90% for cache safety: output capacity is reserved from the usable context window, and the remaining 10% absorbs mid-turn growth before the absolute 95% emergency wall. Use a value between 20 and 90.";
+export const DEFAULT_HISTORIAN_TIMEOUT_MS = 600_000;
+export const DEFAULT_HISTORY_BUDGET_PERCENTAGE = 0.15;
+
+// Minimum absolute token floor for protected_tokens. Kept as a named constant so
+// the schema's `.min()` and the loader's below-minimum warning share ONE source
+// of truth — the loader must not duplicate the literal 4000.
+export const PROTECTED_TOKENS_MIN = 4000;
+
+/** Valid thinking levels for Pi subagents. Maps to Pi's --thinking CLI flag.
+ *  Off: disable reasoning. Minimal/low/medium/high/xhigh/max: increasing reasoning depth.
+ *  `max` was added in Pi 0.83.0.
+ *  Pi-only — OpenCode uses `variant` in agent config instead. */
+export const PiThinkingLevelSchema = z
+    .enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"])
+    .optional();
+export type PiThinkingLevel = z.infer<typeof PiThinkingLevelSchema>;
+
+/** Pi-only child-process controls. This block is intentionally optional so an
+ * absent allowlist preserves Pi's normal extension discovery behavior. */
+export const PiConfigSchema = z
+    .object({
+        subagent_extensions: z
+            .array(z.string().trim().min(1))
+            .optional()
+            .describe(
+                "User-only allowlist of Pi extensions for Magic Context subagent children. When set, children use --no-extensions and load only these entries (plus Magic Context's scoped child extension where applicable). Relative paths resolve from ~/.pi/agent, matching Pi's settings.json package location. Unset preserves normal Pi extension discovery.",
+            ),
+    })
+    .optional();
+export type PiConfig = NonNullable<z.infer<typeof PiConfigSchema>>;
+
+/**
+ * Route the built-in prompt surface without changing guidance or tool registration.
+ * Project config can choose preset routing; only user config can provide override text.
+ */
+export const PromptSurfacePresetSchema = z.enum(["full", "light"]);
+export type { PromptSurfacePreset } from "../../shared/prompt-surface";
+
+const PromptSurfaceModelKeySchema = z.string().refine(isValidPromptSurfaceModelKey, {
+    message:
+        "Use a non-empty bare model key, provider/model key, or the literal provider/* wildcard; model IDs may contain additional slashes and matching is case-sensitive.",
+});
+// Tool-description keys must be non-empty IDs; harness-specific known-tool
+// validation can run when a user override is applied.
+const PromptSurfaceToolKeySchema = z.string().refine((value) => value.trim().length > 0, {
+    message: "tool description keys must not be empty or whitespace-only",
+});
+
+export const PromptSurfaceConfigSchema = z
+    .object({
+        default: PromptSurfacePresetSchema.default("full").describe(
+            'Fallback prompt-surface preset ("full" or "light").',
+        ),
+        models: z
+            .record(PromptSurfaceModelKeySchema, PromptSurfacePresetSchema)
+            .optional()
+            .describe(
+                "Literal per-model routing. Keys are bare model IDs, provider/model, or provider/*; matching is case-sensitive and preserves additional slashes in model IDs.",
+            ),
+        guidance_override_path: z
+            .string()
+            .refine((value) => value.trim().length > 0, {
+                message: "guidance_override_path must not be empty or whitespace-only",
+            })
+            .optional()
+            .describe(
+                "USER-LEVEL ONLY path to a complete primary guidance section. Relative paths resolve from the user config file.",
+            ),
+        tool_descriptions: z
+            .record(
+                PromptSurfaceToolKeySchema,
+                z.string().refine((value) => value.trim().length > 0, {
+                    message: "tool description values must not be empty or whitespace-only",
+                }),
+            )
+            .optional()
+            .describe(
+                "USER-LEVEL ONLY top-level description overrides keyed by mmc_* tool ID; parameter schemas and descriptions are unchanged.",
+            ),
+    })
+    .describe(
+        "Prompt-surface preset routing. Project config may select default/models, while guidance_override_path and tool_descriptions are user-level only.",
+    );
+export type PromptSurfaceConfig = z.infer<typeof PromptSurfaceConfigSchema>;
+
+/**
+ * The flat model-resolution fields are the only fields that move into harness
+ * blocks. Keeping this inventory next to the schema gives the loader migration
+ * an exhaustive contract instead of a catch-all rule.
+ */
+export const PER_HARNESS_MIGRATION_INVENTORY = {
+    historian: {
+        retained: [
+            "temperature",
+            "top_p",
+            "prompt",
+            "tools",
+            "disable",
+            "description",
+            "mode",
+            "color",
+            "maxSteps",
+            "permission",
+            "maxTokens",
+            "two_pass",
+            "disallowed_tools",
+        ],
+        migrated_execution: ["model", "fallback_models", "variant", "thinking_level"],
+    },
+} as const;
+
+/** Harness keys that own independent hidden-agent model-selection blocks. */
+export const PER_HARNESS_MODEL_KEYS = ["opencode", "pi"] as const;
+
+/** OpenCode entry objects permit `variant` and reject Pi-only `thinking_level`. */
+const OcEntryObjectSchema = z
+    .object({
+        model: z.string().describe("OpenCode model ID (for example, provider/model)."),
+        variant: z.string().optional().describe("OpenCode reasoning variant for this entry."),
+    })
+    .strict();
+export const OcEntrySchema = z.union([z.string(), OcEntryObjectSchema]);
+export type OcEntry = z.infer<typeof OcEntrySchema>;
+
+/** Pi entry objects permit `thinking_level` and reject OpenCode-only `variant`. */
+const PiEntryObjectSchema = z
+    .object({
+        model: z.string().describe("Pi model ID (for example, provider/model)."),
+        thinking_level: PiThinkingLevelSchema.describe("Pi thinking level for this entry."),
+    })
+    .strict();
+export const PiEntrySchema = z.union([z.string(), PiEntryObjectSchema]);
+export type PiEntry = z.infer<typeof PiEntrySchema>;
+
+/** Strict model-resolution block used by historian.opencode. */
+export const OpenCodeHarnessBlockSchema = z
+    .object({
+        model: OcEntrySchema.optional().describe("Primary OpenCode model entry."),
+        fallback_models: z
+            .array(OcEntrySchema)
+            .optional()
+            .describe(
+                "Ordered fallback OpenCode entries. New-shape configuration requires an array; legacy singleton values migrate to a one-element array.",
+            ),
+        variant: z
+            .string()
+            .optional()
+            .describe(
+                "OpenCode reasoning variant for the primary entry when it declares none. Fallback entries declare variants per-entry.",
+            ),
+    })
+    .strict()
+    .describe("Strict OpenCode model-resolution block. It accepts no Pi vocabulary.");
+export type OpenCodeHarnessBlock = z.infer<typeof OpenCodeHarnessBlockSchema>;
+
+/** Strict model-resolution block used by historian.pi. */
+export const PiHarnessBlockSchema = z
+    .object({
+        model: PiEntrySchema.optional().describe("Primary Pi model entry."),
+        fallback_models: z
+            .array(PiEntrySchema)
+            .optional()
+            .describe(
+                "Ordered fallback Pi entries. New-shape configuration requires an array; legacy singleton values migrate to a one-element array.",
+            ),
+        thinking_level: PiThinkingLevelSchema.describe(
+            "Pi thinking level for the primary entry when it declares none. Fallback entries declare thinking levels per-entry.",
+        ),
+    })
+    .strict()
+    .describe("Strict Pi model-resolution block. It accepts no OpenCode vocabulary.");
+export type PiHarnessBlock = z.infer<typeof PiHarnessBlockSchema>;
+
+/**
+ * A profile may select models but must not alter execution policy. Keep this
+ * separate from the full harness schemas, which also admit execution-policy
+ * fields beyond model selection.
+ */
+const ProfileOpenCodeModelBlockSchema = z
+    .object({
+        model: OcEntrySchema.optional().describe("Primary OpenCode model entry."),
+        fallback_models: z
+            .array(OcEntrySchema)
+            .optional()
+            .describe("Ordered fallback OpenCode model entries."),
+        variant: z
+            .string()
+            .optional()
+            .describe("OpenCode reasoning variant for the primary model entry."),
+    })
+    .strict()
+    .describe("Strict profile-only OpenCode model-selection block.");
+const ProfilePiModelBlockSchema = z
+    .object({
+        model: PiEntrySchema.optional().describe("Primary Pi model entry."),
+        fallback_models: z
+            .array(PiEntrySchema)
+            .optional()
+            .describe("Ordered fallback Pi model entries."),
+        thinking_level: PiThinkingLevelSchema.describe(
+            "Pi thinking level for the primary model entry.",
+        ),
+    })
+    .strict()
+    .describe("Strict profile-only Pi model-selection block.");
+const ProfileHistorianSchema = z
+    .object({
+        opencode: ProfileOpenCodeModelBlockSchema.optional(),
+        pi: ProfilePiModelBlockSchema.optional(),
+    })
+    .strict();
+
+export const ConfigProfileSchema = z
+    .object({
+        historian: ProfileHistorianSchema.optional(),
+    })
+    .strict()
+    .describe(
+        "User-owned model-selection overlay. Only historian harness model blocks are allowed.",
+    );
+export type ConfigProfile = z.infer<typeof ConfigProfileSchema>;
+
+export const ConfigProfilesSchema = z.record(
+    z.string().trim().min(1, "Profile names must not be empty or whitespace-only."),
+    ConfigProfileSchema,
+);
+export type ConfigProfiles = z.infer<typeof ConfigProfilesSchema>;
+
+const AgentMetadataSchema = AgentOverrideConfigSchema.pick({
+    temperature: true,
+    top_p: true,
+    prompt: true,
+    tools: true,
+    disable: true,
+    description: true,
+    mode: true,
+    color: true,
+    maxSteps: true,
+    permission: true,
+    maxTokens: true,
+});
+
+/**
+ * Historian metadata remains harness-independent. Only model resolution moves to
+ * the strict opencode and pi blocks; two_pass and disallowed_tools stay here.
+ */
+export const HistorianConfigSchema = AgentMetadataSchema.extend({
+    expand_tools: z
+        .record(
+            z.string(),
+            z.union([
+                z.string().superRefine((value, ctx) => {
+                    const error = toolTemplateError(value);
+                    if (error) ctx.addIssue({ code: "custom", message: error });
+                }),
+                z.literal(false),
+            ]),
+        )
+        .optional()
+        .describe(
+            'Readable historian tool expansions, keyed by exact host tool name. Templates override built-in defaults; false disables an expansion. Supports ${input.path}, ${output.path}, bare ${output}, array [N], [*].field, .each("${field}"), .join("separator"), .count and final .truncate(N). Missing fields are empty; placeholders default to 300 characters, lists to 10 elements, expansions to 1000 characters. Valid in user and project config; affects historian/recomp and verbose ctx_expand only, never the wire or default ctx_expand transcript.',
+        ),
+    opencode: OpenCodeHarnessBlockSchema.optional(),
+    pi: PiHarnessBlockSchema.optional(),
+    two_pass: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Run a second editor pass over historian output to clean low-signal U: lines and cross-compartment duplicates. Adds ~1 extra API call and ~1.3x cost per historian run. Useful for models without extended thinking support. (default: false)",
+        ),
+    disallowed_tools: z
+        .array(z.enum(["*", "read", "aft_outline", "aft_zoom", "aft_search"]))
+        .default([])
+        .describe(
+            'OpenCode only. Tools to REMOVE from the historian\'s default allow-list [read, aft_outline, aft_zoom, aft_search]. Applies to both historian and historian-editor agents. Use ["*"] to strip all tool definitions from the model request — this prevents weak instruction-following models (e.g. mistral-small-latest) from entering tool-calling loops. Individual tool names remove just that tool. Note: a user-supplied historian.permission override can re-allow a tool that disallowed_tools removed — disallowed_tools sets the baseline, permission overrides take precedence. (default: [])',
+        ),
+}).optional();
+export type HistorianConfig = NonNullable<z.infer<typeof HistorianConfigSchema>>;
+
+export interface MagicContextConfig {
+    enabled: boolean;
+    /** User-level setting that lets a session in the canonical home directory use project memory. */
+    allow_home_project: boolean;
+    /** DEPRECATED no-op: the auto-update check was removed (2026-10-05) — the package is
+     *  private-registry-only, so public npm checks always failed. The key is still accepted
+     *  (USER config only; project configs stripped) so existing configs keep parsing. */
+    auto_update?: boolean;
+    /** Output language for generated Magic Context prose. USER config only. */
+    language?: string;
+    /** Active user-owned model profile after user/project resolution. */
+    profile?: string;
+    /** Named user-owned model profiles. Declarations are consumed during resolution. */
+    profiles?: ConfigProfiles;
+    historian?: HistorianConfig;
+    cache_ttl: string | { default: string; [modelKey: string]: string };
+    /** Preset routing for guidance and provider-visible prompt surfaces. */
+    prompt_surface: PromptSurfaceConfig;
+    /** User-only output-token reservation override. Zero disables reservation. */
+    output_reserve?: number | { default: number; [modelKey: string]: number };
+    /** User-only model metadata inputs. */
+    models?: { window_overlay_path?: string };
+    /** TUI toast lifetime in milliseconds for Magic Context notifications. Default: 5000. */
+    toast_duration_ms?: number;
+    execute_threshold_percentage: number | { default: number; [modelKey: string]: number };
+    /** Absolute token thresholds per model. When set for a given model (or via `default`),
+     *  this overrides `execute_threshold_percentage` for that model. Useful for hard caps
+     *  matching provider input limits. Values above 90% × context_limit are clamped with a warning. */
+    execute_threshold_tokens?: { default?: number; [modelKey: string]: number | undefined };
+    protected_tokens?: number;
+    clear_reasoning_age: number;
+    history_budget_percentage: number;
+    historian_timeout_ms: number;
+    commit_cluster_trigger: {
+        enabled: boolean;
+        min_clusters: number;
+    };
+    /** Per-connection SQLite tuning for Magic Context's own context.db. */
+    sqlite: {
+        cache_size_mb: number;
+        mmap_size_mb: number;
+    };
+    /**
+     * Keep shared-storage permissions under an external operator's control.
+     * USER config only; project configs cannot weaken local data privacy.
+     */
+    storage: {
+        enforce_private_permissions: boolean;
+    };
+    /**
+     * Controls whether and where Magic Context augments the system prompt
+     * (`## Magic Context` guidance, sticky date)
+     * inside `experimental.chat.system.transform`.
+     *
+     * Internal OpenCode hidden agents (title, summary, compaction) are
+     * always skipped automatically — that's a separate code path.
+     */
+    system_prompt_injection: {
+        /** When false, NO injection happens for ANY agent — global escape hatch. */
+        enabled: boolean;
+        /**
+         * If the agent's system prompt contains any of these substrings,
+         * skip ALL Magic Context injection for that call. Lets users opt
+         * specific agents out (e.g. read-only QA agents that deny our
+         * `mmc_*` tools and don't need the guidance). The default marker
+         * `<!-- magic-context: skip -->` is meant to be added inside the
+         * user's custom agent prompt.
+         */
+        skip_signatures: string[];
+    };
+    /** Inject elapsed-time markers between user messages and date ranges on
+     *  compartments so the agent has a wall-clock sense of the session.
+     *  Graduated from `experimental.temporal_awareness`; default: true. */
+    temporal_awareness: boolean;
+    /** Debug: when true, keep the child sessions Magic Context spawns for its
+     *  own subagents (historian) instead
+     *  of deleting them on success. For short-term inspection/data collection;
+     *  kept sessions accumulate until manually cleared. Default false. */
+    keep_subagents: boolean;
+    /** Enable loopback-only diagnostic RPCs that expose memory usage and heap snapshots. */
+    debug_rpc?: boolean;
+    /**
+     * When true (default), deterministic inoperability (schema fence, storage
+     * open/migration failure) blocks the primary-session transform with a loud
+     * recovery error instead of silently falling through to native compaction.
+     * USER config only — project tier cannot set this. Not recommended to disable.
+     */
+    fail_closed_blocking: boolean;
+    /**
+     * Compaction-off mode gate. When `enabled` is false Magic Context stops
+     * managing the context window and keeps only its knowledge layer, letting
+     * the harness's native compaction (or nothing) own the window. USER config
+     * only — project tier `compaction.enabled` is stripped for security.
+     * Boot-resolved: changing it requires a process restart.
+     */
+    compaction: {
+        enabled: boolean;
+    };
+    /** Pi-only controls for Magic Context's OpenCode-parity todowrite surface. */
+    todowrite: {
+        enabled: boolean;
+        overlay: boolean;
+    };
+    /** Pi-only child-process extension controls. */
+    pi?: PiConfig;
+    /** Content-aware reclaim of tool output that a later call supersedes, added
+     *  to the normal age-based auto-drop: superseded todowrite/mmc_reduce/meta
+     *  outputs are dropped, and older edits to a file are compressed to a marker
+     *  that keeps only the filePath. Only runs on a transform pass that is
+     *  already rewriting the messages, so it never triggers a prompt-cache miss
+     *  on its own; when off, the messages sent to the model are byte-identical to
+     *  the age-based-only behavior. Experimental, opt-in, default off until cache
+     *  stability is proven. */
+    smart_drops: boolean;
+    /**
+     * Age-tier caveman compression for long user/assistant text parts.
+     * Graduated from `experimental.caveman_text_compression`; opt-in, default off.
+     *
+     * Active only for primary sessions when enabled; never for subagents.
+     * Buckets eligible (outside-protected-tail) messages into four age
+     * tiers by tag position — oldest 20% → ultra, next 20% → full,
+     * next 20% → lite, newest 40% → untouched — and rewrites the text
+     * part in place.
+     * Always compresses from the original source (source_contents), so
+     * tier shifts produce the same result as if the target depth were
+     * applied directly to the original text.
+     *
+     * Disabled by default because it rewrites agent-visible history.
+     */
+    caveman_text_compression: {
+        enabled: boolean;
+        /** Text parts shorter than this (characters) are left untouched. */
+        min_chars: number;
+    };
+    memory: {
+        enabled: boolean;
+        injection_budget_tokens: number;
+        auto_promote: boolean;
+        /** Appends a compact hint to new user messages when mmc_search finds
+         *  highly-related memories or conversation. Does NOT
+         *  inject full content — just vague fragments that nudge the agent to
+         *  run mmc_search for full context if relevant. Graduated from
+         *  `experimental.auto_search`; enabled by default. Independent of
+         *  `memory.enabled` — it can still surface conversation hints when
+         *  the memory store is off. */
+        auto_search: {
+            enabled: boolean;
+            /** Top hit score must exceed this threshold for the hint to fire. */
+            score_threshold: number;
+            /** Minimum user message length in characters (skip short prompts). */
+            min_prompt_chars: number;
+        };
+    };
+    /**
+     * Automatic memory-maintenance run controls (plan 10, dreamer replacement).
+     * USER config only — the whole group is stripped from project-tier config:
+     * a cloned repository must not raise run budgets, relax cooldowns/backoff,
+     * or loosen the anomaly guard to weaponize the maintenance task.
+     */
+    maintenance: {
+        enabled: boolean;
+        /** Per-run four-dimensional budget (decision 9; provisional, calibrated in P3/P4). */
+        budgets: {
+            inputTokens: number;
+            outputTokens: number;
+            toolSteps: number;
+            wallMs: number;
+        };
+        /** Inter-run cooldown and failure-backoff schedule (decision 10; provisional). */
+        cooldowns: {
+            interRunMs: number;
+            backoffScheduleMs: number[];
+            backoffCapMs: number;
+            maxRetries: number;
+        };
+        /** Anomaly guard: single-run change-volume dual gate (decision 11).
+         *  Defaults are P1/P2 TEST defaults — production values are calibrated
+         *  against real-model samples in P3. */
+        anomalyThreshold: {
+            absoluteRows: number;
+            poolFraction: number;
+        };
+    };
+}
+
+export const MagicContextConfigSchema = z.object({
+    enabled: z.boolean().default(true).describe("Enable magic context (default: true)"),
+    allow_home_project: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Allow Magic Context sessions launched from the exact canonical home directory. A non-git home uses its deterministic dir: identity; a home repository uses its git: identity. USER-LEVEL ONLY: project config is ignored. The home identity is excluded from registry seed exports, never resolves descendants by containment, and cannot join a workspace.",
+        ),
+    auto_update: z
+        .boolean()
+        .optional()
+        .describe(
+            "DEPRECATED no-op: the automatic update check was removed (the package is private-registry-only, so public npm checks always 404). The key is still accepted so existing configs keep parsing; upgrade via the host's own plugin update channel.",
+        ),
+    language: z
+        .string()
+        .trim()
+        .toLowerCase()
+        .refine(
+            (s) => isValidLanguageCode(s),
+            'language must be a 2-letter ISO 639-1 code (e.g. "tr", "es", "de")',
+        )
+        .optional()
+        .describe(
+            "Output language for Magic Context's generated content and guidance, as a " +
+                '2-letter ISO 639-1 code (e.g. "tr", "es", "de", "ja", "pt"). When set, the ' +
+                "historian and the agent-guidance block instruct the model to " +
+                "write its PROSE in this language while keeping all structural tokens (XML tags, " +
+                "the five memory category names, code identifiers, file paths) in English. " +
+                "USER-LEVEL ONLY (ignored in project config for security). Unset = today's " +
+                "behavior (model mirrors the conversation; English scaffolding). Changing it " +
+                "triggers one cache re-materialization; existing compartments/memories keep their " +
+                "original language until naturally rewritten.",
+        ),
+    profile: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe(
+            "Select a named user-owned model profile. A valid project name overrides this user default; an empty string, null, or other non-string project value is ignored with a warning so the user selection still applies. Unknown names warn and use the base configuration.",
+        ),
+    profiles: ConfigProfilesSchema.optional().describe(
+        "User-level named model profiles. A profile may contain only historian model, fallback_models, OpenCode variant, and Pi thinking_level fields. Project configs may select a name but cannot define profiles.",
+    ),
+    historian: HistorianConfigSchema.describe(
+        "Historian metadata plus independent strict OpenCode and Pi execution blocks. Retained metadata stays at historian; model, fallback_models, variant, and thinking_level belong only in historian.opencode or historian.pi.",
+    ),
+    cache_ttl: z
+        .union([z.string(), z.object({ default: z.string() }).catchall(z.string())])
+        .default("5m")
+        .describe(
+            'How long Magic Context assumes the provider\'s cached prefix stays valid. This is MC\'s own deferral gate — it does not change the provider\'s actual cache lifetime. String (e.g. "5m", "1h", "30s") or per-model object ({ default: "5m", "provider/model": "1h", "provider/*": "never" }); keys resolve most-specific first (exact provider/model, bare model ID, shorter dash-prefixes, then the provider/* wildcard). Explicit per-model entries win; otherwise GPT-5.6 and later (including gpt-6*, through any provider prefix) use a built-in 30m lifetime before the object default or 5m fallback. An unset or global "5m" opts into built-in defaults; any other global string is an explicit policy and wins. Policy is frozen per session, including across restarts; a model switch resolves against that frozen policy. /mmc-status shows the effective value and source. OpenAI documents at least 30 minutes since the latest write or reuse: https://developers.openai.com/api/docs/guides/prompt-caching (Cache lifetime and Summary of model differences). Set to "never" to mean MC never assumes expiry (for lanes kept warm externally by a cache-keep tool) — disables the idle-TTL heuristic so MC never initiates a rebuild based on elapsed time. Provider-side extended TTL is a separate request-level concern (cache_control: { ttl } in the request body).',
+        ),
+    prompt_surface: PromptSurfaceConfigSchema.default({ default: "full" }).describe(
+        "Prompt-surface presets: default is full; models use bare model IDs, provider/model, or provider/* routing keys. Guidance and tool-description overrides are user-level only. OpenCode 1.x and Pi register tool descriptions once per process (they follow the default preset). OpenCode 2 rewrites the five mmc_* descriptions per request from the draft model.",
+    ),
+    output_reserve: z
+        .union([
+            z.number().min(0),
+            z.object({ default: z.number().min(0) }).catchall(z.number().min(0)),
+        ])
+        .optional()
+        .describe(
+            'User-only output-token reservation override. Number or per-model object ({ default: 16384, "provider/model": 8192 }); 0 disables reservation. Takes precedence over every derived source: an explicit value here always wins against catalog output limits, provider window-geometry facts, and the 25%-of-context fallback (usable window = context window minus this reserve). When unset, Magic Context reserves the catalog output limit (capped at 25% of context) for shared-window providers and keeps proven separate-quota Google/Gemini windows unchanged.',
+        ),
+    models: z
+        .object({
+            window_overlay_path: z.string().trim().min(1).optional(),
+        })
+        .optional()
+        .describe(
+            "User-only Fusiform window-overlay settings. The path defaults to <dataDir>/fusiform/window-overlay.json.",
+        ),
+    toast_duration_ms: z
+        .number()
+        .min(0)
+        .max(60_000)
+        .default(5_000)
+        .describe(
+            "TUI toast lifetime in milliseconds for Magic Context notifications. Set to 0 to disable Magic Context toasts entirely (min: 0, max: 60000, default: 5000)",
+        ),
+    execute_threshold_percentage: z
+        .union([
+            z.number().min(20).max(90, EXECUTE_THRESHOLD_CAP_MESSAGE),
+            z
+                .object({ default: z.number().min(20).max(90, EXECUTE_THRESHOLD_CAP_MESSAGE) })
+                .catchall(z.number().min(20).max(90, EXECUTE_THRESHOLD_CAP_MESSAGE)),
+        ])
+        .default(DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE)
+        .describe(
+            'Context percentage that forces queued operations to execute. Number or per-model object ({ default: 65, "provider/model": 45 }). Values above 90 are rejected because the runtime caps at 90% of the output-reserved safe window (MAX_EXECUTE_THRESHOLD). Default: DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE',
+        ),
+    execute_threshold_tokens: z
+        .object({
+            default: z.number().min(5_000).max(2_000_000).optional(),
+        })
+        .catchall(z.number().min(5_000).max(2_000_000))
+        .optional()
+        .describe(
+            "Absolute token thresholds per model. When matched, overrides execute_threshold_percentage for that model. Accepts `default` for all models or per-model keys. Values above 90% × context_limit are clamped with a warning log. Min 5_000, max 2_000_000.",
+        ),
+    protected_tokens: z
+        .number()
+        .int()
+        .min(PROTECTED_TOKENS_MIN)
+        .max(1_000_000)
+        .optional()
+        .describe(
+            "Positive integer token floor to protect from automatic reclaim (min: 4_000, max: 1_000_000). When omitted, the derived default is clamp(round(0.05 × usableSoft), min(16_000, round(0.08 × usableSoft)), 64_000).",
+        ),
+    clear_reasoning_age: z
+        .number()
+        .min(10)
+        .default(50)
+        .describe("Clear reasoning/thinking blocks older than N tags (default: 50)"),
+    history_budget_percentage: z
+        .number()
+        .min(0.05)
+        .max(0.5)
+        .default(DEFAULT_HISTORY_BUDGET_PERCENTAGE)
+        .describe(
+            "Fraction of usable context (context_limit × execute_threshold) reserved for the session history block (default: 0.15)",
+        ),
+    historian_timeout_ms: z
+        .number()
+        .min(60_000)
+        .default(DEFAULT_HISTORIAN_TIMEOUT_MS)
+        .describe(
+            "Timeout for each historian prompt call in both TypeScript and Rust transform modes, in milliseconds (default: 600000)",
+        ),
+    commit_cluster_trigger: z
+        .object({
+            enabled: z
+                .boolean()
+                .default(true)
+                .describe("Enable commit-cluster based historian triggering (default: true)"),
+            min_clusters: z
+                .number()
+                .min(1)
+                .default(3)
+                .describe(
+                    "Minimum commit clusters required to trigger historian (min: 1, default: 3)",
+                ),
+        })
+        .default({ enabled: true, min_clusters: 3 })
+        .describe(
+            "Commit-cluster trigger: fire historian when enough commit clusters accumulate in the unsummarized tail",
+        ),
+    system_prompt_injection: z
+        .object({
+            enabled: z
+                .boolean()
+                .default(true)
+                .describe(
+                    "When false, NO injection happens for ANY agent — global escape hatch. (default: true)",
+                ),
+            skip_signatures: z
+                .array(z.string())
+                .default(["<!-- magic-context: skip -->"])
+                .describe(
+                    "Substring opt-out list. If the agent's system prompt contains any of these strings, skip ALL Magic Context injection for that call. Default \"<!-- magic-context: skip -->\" is meant to be added inside a user's custom agent prompt to opt that agent out.",
+                ),
+        })
+        .default({
+            enabled: true,
+            skip_signatures: ["<!-- magic-context: skip -->"],
+        })
+        .describe(
+            "Controls whether and where Magic Context augments the system prompt. Lets users opt specific agents out of the Magic Context guidance. OpenCode's internal hidden agents — title, summary, and compaction — are always skipped automatically.",
+        ),
+    // v2: the LLM compressor was removed — deterministic decay-tier rendering
+    // (decay-render.ts) replaces it, so there are no compressor knobs. A
+    // leftover `compressor` block in an existing config is silently ignored
+    // (the schema strips unknown keys).
+    sqlite: z
+        .object({
+            cache_size_mb: z
+                .number()
+                .min(2)
+                .max(2048)
+                .default(64)
+                .describe(
+                    "Page-cache size in MiB per connection (PRAGMA cache_size). Larger keeps more hot pages resident, cutting re-reads on repeated full-table scans. (min 2, max 2048, default 64)",
+                ),
+            mmap_size_mb: z
+                .number()
+                .min(0)
+                .max(8192)
+                .default(0)
+                .describe(
+                    "Memory-mapped I/O size in MiB (PRAGMA mmap_size). 0 disables mmap (SQLite default). Raising it can cut read overhead on large DBs at the cost of address space. (min 0, max 8192, default 0)",
+                ),
+        })
+        .default({ cache_size_mb: 64, mmap_size_mb: 0 })
+        .describe(
+            "SQLite connection tuning for Magic Context's own context.db. These are per-connection PRAGMAs applied at open; they do not change the schema or what is stored.",
+        ),
+    storage: z
+        .object({
+            enforce_private_permissions: z
+                .boolean()
+                .default(true)
+                .describe(
+                    "When true (default), Magic Context creates and re-tightens its storage directories to owner-only 0700 and storage files to owner-only 0600. Set false only for a deliberate trusted-group deployment whose operator manages directory, database, WAL/SHM, cache, and RPC file permissions externally; Magic Context then never chmods or supplies restrictive creation modes. USER-LEVEL ONLY — ignored in project config for security. On Windows, POSIX chmod modes are already meaningless, so this setting is a no-op.",
+                ),
+        })
+        .default({ enforce_private_permissions: true })
+        .describe(
+            "Storage permission policy. The default keeps session content and memories owner-private. Disabling enforcement is for trusted shared-group storage managed externally; every group member able to read the storage can read all stored session content and memories.",
+        ),
+    temporal_awareness: z
+        .boolean()
+        .default(true)
+        .describe(
+            'Inject wall-clock gap markers (<!-- +Xm -->) between user messages where > 5 min elapsed since the previous message, and add compact date ranges to compartment headings. Gives the agent a sense of session pacing and "how long ago" across multi-day sessions. Graduated from experimental.temporal_awareness; default: true (set false to opt out).',
+        ),
+    keep_subagents: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Debug: keep every settled Magic Context child session instead of deleting it after success: historian runs. Kept hidden children can contain memory-pool text and user messages from other sessions of the same operator; their full transcript (prompt, tool calls, token usage, output) stays in the host session store. Kept sessions accumulate until manually cleared; leave false for normal use. Requires a restart to take effect. On OpenCode 2, one hidden session holds many runs; it is kept once any of its runs settled.",
+        ),
+    debug_rpc: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Developer-only: enable authenticated loopback RPCs for memory counters and heap snapshots. Disabled by default. USER-LEVEL ONLY and requires a restart.",
+        ),
+    fail_closed_blocking: z
+        .boolean()
+        .default(true)
+        .describe(
+            "When Magic Context cannot operate (schema fence mismatch, storage open/migration failure), block the primary-session prompt with a loud recovery error instead of silently degrading to native compaction. Default true. Set false only to restore the old degrade-silently behavior (not recommended). USER-LEVEL ONLY — ignored in project config for security. Requires a restart.",
+        ),
+    compaction: z
+        .object({
+            enabled: z
+                .boolean()
+                .default(true)
+                .describe(
+                    "When false, Magic Context stops managing the context window and keeps its knowledge layer: memory injection through additive m[0]/m[1], raw-message FTS indexing, notes, mmc_search, mmc_expand, and mmc_memory remain available. MC's historian/compartment preparation, tagging, markers, pruning, folding, drops, strips, splicing, synthetic context-management todos, temporal markers, nudges, and fail-closed blocking stop; mmc_expand remains a knowledge-surface tool. fail_closed_blocking is inert: a transform failure passes the input messages through without blocking or cancelling. This setting does not enable native compaction: OpenCode's compaction.auto / compaction.prune or Pi's equivalent owns the window, or nothing does. MC's compaction.enabled in mmc.jsonc is distinct from OpenCode's compaction.auto / compaction.prune in opencode.jsonc; they are different files and different owners. On the first turn after disabling, a long session may trigger one native compaction cycle; MC removes only its own marker boundary, leaves native boundaries and stored compartments intact, and does no pre-trimming mitigation. Marker cleanup is lazy per session, so an unresumed session is cleaned when it is next resumed. If compaction is enabled again, run /mmc-wrapup when the historian is runnable to catch up. OpenCode peer verification against v1.18.4 confirms native compaction covers child sessions: subagents receive additive memory injection and no MC reclaim in this mode, so keep subagent tasks small or leave compaction.enabled on for long subagent runs. This is boot-resolved and requires a process restart; project-tier compaction.enabled is stripped so a cloned repository cannot disable the user's setting. The sidebar reports raw usage as Context: <pct>% · native compaction or Context: <pct>% · no active compaction and does not show an MC execute-threshold fill. /mmc-wrapup, /mmc-recomp, and /mmc-flush refuse without context-management side effects. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.",
+                ),
+        })
+        .default({ enabled: true })
+        .describe(
+            "Compaction-off mode gate. Default true (MC manages the context window as today). Set compaction.enabled=false to keep the knowledge layer while letting native compaction (or nothing) own the window. Boot-resolved; requires a restart to change.",
+        ),
+    todowrite: z
+        .object({
+            enabled: z
+                .boolean()
+                .default(false)
+                .describe(
+                    "Pi only: off by default. Set todowrite.enabled=true to register Magic Context's todowrite task-list tool and /todos command. OpenCode ships its own built-in todowrite; this setting has no effect there.",
+                ),
+            overlay: z
+                .boolean()
+                .default(true)
+                .describe(
+                    "Pi only: show the persistent todo overlay above the editor while tasks are active.",
+                ),
+        })
+        .default({ enabled: false, overlay: true })
+        .describe(
+            "Pi-only todowrite tool and overlay controls. Pi registers tools and widgets at extension boot, so changing this after /cd requires /reload or restart.",
+        ),
+    pi: PiConfigSchema.describe(
+        "Pi-only child-process extension controls. This setting is user-level only; project configuration cannot choose which extensions a user's subagent children load.",
+    ),
+    smart_drops: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Content-aware reclaim of provably-superseded tool output, layered on the existing execute-pass auto-drop. When on: superseded todowrite (keep newest 1), spent mmc_reduce (keep newest 3), and zero-value meta (bash_status, bash_kill, mmc_note read/dismiss) outputs are dropped; older edits to a file are compressed to a filePath-preserving marker while the newest edit per file stays full. Only acts on passes already busting the cache, so it never originates a cache bust. Honors the protected-tag reserve. Experimental: opt-in, default off until cache stability is proven; when off the wire is byte-identical to the positional-only reclaim. Requires a restart.",
+        ),
+    caveman_text_compression: z
+        .object({
+            enabled: z
+                .boolean()
+                .default(false)
+                .describe(
+                    "Apply deterministic caveman-style text compression to old conversation text. Active for primary sessions when enabled; never for subagents. Compresses user/assistant text in oldest-first tiers: ultra (oldest 20%), full, lite, untouched (newest 40%).",
+                ),
+            min_chars: z
+                .number()
+                .min(100)
+                .max(10000)
+                .default(500)
+                .describe(
+                    "Text parts shorter than this (characters) stay untouched. Min 100, max 10000. Default: 500.",
+                ),
+        })
+        .default({ enabled: false, min_chars: 500 })
+        .describe(
+            "Age-tier caveman compression for long user/assistant text parts. Active for primary sessions when enabled; never for subagents. Oldest 20% of eligible tags (outside protected tail) go to ultra, next 20% to full, next 20% to lite, newest 40% untouched. Graduated from experimental.caveman_text_compression; opt-in, default off (lossy).",
+        ),
+    memory: z
+        .object({
+            enabled: z
+                .boolean()
+                .default(true)
+                .describe("Enable cross-session memory (default: true)"),
+            injection_budget_tokens: z
+                .number()
+                .min(500)
+                .max(20000)
+                .default(4000)
+                .describe(
+                    "Token budget for memory injection on session start (min: 500, max: 20000, default: 4000)",
+                ),
+            auto_promote: z
+                .boolean()
+                .default(true)
+                .describe(
+                    "Automatically promote eligible session facts into memory (default: true)",
+                ),
+            auto_search: z
+                .object({
+                    enabled: z
+                        .boolean()
+                        .default(true)
+                        .describe(
+                            "Automatically append a compact <ctx-search-hint> to eligible user messages when relevant memories, conversation, or commits are found. Graduated from experimental.auto_search; on by default (set false to opt out). Independent of memory.enabled.",
+                        ),
+                    score_threshold: z
+                        .number()
+                        .min(0.3)
+                        .max(0.95)
+                        .default(0.6)
+                        .describe(
+                            "Top hit score must exceed this threshold for the hint to fire (min: 0.3, max: 0.95, default: 0.60)",
+                        ),
+                    min_prompt_chars: z
+                        .number()
+                        .min(5)
+                        .max(500)
+                        .default(20)
+                        .describe(
+                            "Skip hint when user message is shorter than this (min: 5, max: 500, default: 20)",
+                        ),
+                })
+                .default({ enabled: true, score_threshold: 0.6, min_prompt_chars: 20 })
+                .describe(
+                    "Auto-search hint: transform-time mmc_search on each new user message; when the top hit clears the threshold, append a compact <ctx-search-hint> block of vague fragments to that user message. Does NOT inject full content. Graduated from experimental.auto_search; enabled by default (set enabled: false to opt out). Independent of memory.enabled.",
+                ),
+        })
+        .default({
+            enabled: true,
+            injection_budget_tokens: 4000,
+            auto_promote: true,
+            auto_search: { enabled: true, score_threshold: 0.6, min_prompt_chars: 20 },
+        })
+        .describe("Cross-session memory configuration"),
+    maintenance: z
+        .object({
+            enabled: z
+                .boolean()
+                .default(true)
+                .describe(
+                    "Enable the automatic memory-maintenance task (default: true). USER-LEVEL ONLY — the whole maintenance group is stripped from project-tier config.",
+                ),
+            budgets: z
+                .object({
+                    inputTokens: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .default(400_000)
+                        .describe(
+                            "Per-run input-token budget (input + cacheRead + cacheWrite pricing dimensions). Default 400000.",
+                        ),
+                    outputTokens: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .default(32_000)
+                        .describe("Per-run output-token budget. Default 32000."),
+                    toolSteps: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .default(60)
+                        .describe("Per-run tool-step budget. Default 60."),
+                    wallMs: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .default(900_000)
+                        .describe(
+                            "Per-run wall-clock budget in milliseconds. Default 900000 (15 minutes).",
+                        ),
+                })
+                .default({
+                    inputTokens: 400_000,
+                    outputTokens: 32_000,
+                    toolSteps: 60,
+                    wallMs: 900_000,
+                })
+                .describe(
+                    "Run-level four-dimensional budget (decision 9). Provisional defaults — calibrated against real-model samples in P3/P4.",
+                ),
+            cooldowns: z
+                .object({
+                    interRunMs: z
+                        .number()
+                        .int()
+                        .min(0)
+                        .default(1_800_000)
+                        .describe(
+                            "Minimum cooldown between two runs of the same project. Default 1800000 (30 minutes).",
+                        ),
+                    backoffScheduleMs: z
+                        .array(z.number().int().min(0))
+                        .min(1)
+                        .default([900_000, 3_600_000, 14_400_000])
+                        .describe(
+                            "Failure-backoff schedule in milliseconds, applied in order (default 15m -> 1h -> 4h).",
+                        ),
+                    backoffCapMs: z
+                        .number()
+                        .int()
+                        .min(0)
+                        .default(86_400_000)
+                        .describe("Upper bound for backoff delays. Default 86400000 (24 hours)."),
+                    maxRetries: z
+                        .number()
+                        .int()
+                        .min(0)
+                        .default(3)
+                        .describe(
+                            "Failed attempts before the task re-arms behind a cooldown instead of backing off further (never permanently abandoned). Default 3.",
+                        ),
+                })
+                .default({
+                    interRunMs: 1_800_000,
+                    backoffScheduleMs: [900_000, 3_600_000, 14_400_000],
+                    backoffCapMs: 86_400_000,
+                    maxRetries: 3,
+                })
+                .describe(
+                    "Inter-run cooldown and failure-backoff schedule (decision 10). Provisional defaults.",
+                ),
+            anomalyThreshold: z
+                .object({
+                    absoluteRows: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .default(10)
+                        .describe(
+                            "Anomaly guard: absolute number of changed rows in one run that trips the pause-and-report gate.",
+                        ),
+                    poolFraction: z
+                        .number()
+                        .min(0)
+                        .max(1)
+                        .default(0.25)
+                        .describe(
+                            "Anomaly guard: changed-row fraction of the memory pool that trips the gate (either bound trips).",
+                        ),
+                })
+                .default({ absoluteRows: 10, poolFraction: 0.25 })
+                .describe(
+                    "Single-run anomaly dual gate (decision 11). PROVISIONAL defaults: these are the P1/P2 test values, promoted unchanged to production. Real-model sensitivity calibration (gate-4 finding S2, plan 10 §11.3) was deferred to P4 — legal-but-aggressive pool sampling is in progress; tune only against that calibration evidence.",
+                ),
+        })
+        .default({
+            enabled: true,
+            budgets: {
+                inputTokens: 400_000,
+                outputTokens: 32_000,
+                toolSteps: 60,
+                wallMs: 900_000,
+            },
+            cooldowns: {
+                interRunMs: 1_800_000,
+                backoffScheduleMs: [900_000, 3_600_000, 14_400_000],
+                backoffCapMs: 86_400_000,
+                maxRetries: 3,
+            },
+            anomalyThreshold: { absoluteRows: 10, poolFraction: 0.25 },
+        })
+        .describe(
+            "Automatic memory-maintenance run controls (dreamer replacement). USER-LEVEL ONLY: the whole group is stripped from project-tier config so a cloned repository cannot raise budgets, relax cooldowns, or loosen the anomaly guard.",
+        ),
+});
+
+/** Settings whose fresh values can be used by later agent runs without changing rendered prompt bytes. */
+export const LIVE_RELOAD_CONFIG_PATHS = [
+    "toast_duration_ms",
+    "historian.opencode.model",
+    "historian.opencode.fallback_models",
+    "historian.opencode.variant",
+    "historian.pi.model",
+    "historian.pi.fallback_models",
+    "historian.pi.thinking_level",
+    "historian.two_pass",
+    "historian.expand_tools",
+    "historian.maxTokens",
+    "historian_timeout_ms",
+    "commit_cluster_trigger.enabled",
+    "commit_cluster_trigger.min_clusters",
+    "memory.auto_promote",
+] as const;
+
+// Mark the input schema nodes, not their parsed defaults, so the JSON schema,
+// runtime projection, docs and dashboard all share one policy source.
+for (const path of LIVE_RELOAD_CONFIG_PATHS) {
+    let node: z.ZodType = MagicContextConfigSchema;
+    for (const part of path.split(".")) {
+        while (
+            node instanceof z.ZodOptional ||
+            node instanceof z.ZodDefault ||
+            node instanceof z.ZodNullable
+        ) {
+            node = node.unwrap() as z.ZodType;
+        }
+        if (!(node instanceof z.ZodObject) || !(part in node.shape)) {
+            throw new Error(`Unknown live config path: ${path}`);
+        }
+        node = node.shape[part] as z.ZodType;
+    }
+    z.globalRegistry.add(node, { ...node.meta(), "x-mc-live-reload": true });
+}
+
+/**
+ * Derived default protected_tokens formula:
+ * clamp(round(0.05 × usableSoft), min(16000, round(0.08 × usableSoft)), 64000)
+ *
+ * Sizing table:
+ *   100k -> 8,000
+ *   200k -> 16,000
+ *   372k -> 18,600
+ *   872k -> 43,600
+ *   1M   -> 50,000
+ */
+export function deriveDefaultProtectedTokens(usableSoft: number): number {
+    const clampedUsable = Math.max(0, usableSoft);
+    const lowerBound = Math.min(16_000, Math.round(0.08 * clampedUsable));
+    const target = Math.round(0.05 * clampedUsable);
+    return Math.min(64_000, Math.max(lowerBound, target));
+}