@cortexkit/opencode-magic-context 0.42.5 → 0.43.0

package/src/config/live-snapshot.ts

@@ -0,0 +1,191 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+
+import { detectConfigFile, parseJsoncRecovering } from "../shared/jsonc-parser";
+import {
+    cortexKitProjectConfigBasePath,
+    cortexKitUserConfigBasePath,
+} from "./migrate-config-location";
+
+export interface ConfigSnapshot<T> {
+    readonly generation: number;
+    readonly digest: string;
+    readonly adoptedAt: number;
+    readonly effective: T;
+}
+
+export interface ConfigReloadFailure {
+    readonly path: string;
+    readonly message: string;
+    readonly digest: string;
+}
+
+interface FileState {
+    metadata: string;
+    digest: string;
+}
+
+/**
+ * Publishes a project configuration only after the user and project files parse
+ * and the loader assembles the final effective configuration successfully.
+ */
+export class LiveConfigReader<T> {
+    private snapshot: ConfigSnapshot<T>;
+    private files = new Map<string, FileState>();
+    private initialized = false;
+    private warned = new Set<string>();
+    private failure: ConfigReloadFailure | undefined;
+
+    constructor(
+        private readonly directory: string,
+        initial: T,
+        private readonly load: () => T,
+        // Callers pass the host's log sink; the default is silent so a caller that
+        // forgets never writes into the host process's stderr.
+        private readonly onLog: (message: string) => void = () => {},
+        private readonly changedKeys: (previous: T, next: T) => readonly string[] = (
+            previous,
+            next,
+        ) =>
+            Object.keys(next as object).filter(
+                (key) =>
+                    JSON.stringify((previous as Record<string, unknown>)[key]) !==
+                    JSON.stringify((next as Record<string, unknown>)[key]),
+            ),
+    ) {
+        this.snapshot = {
+            generation: 1,
+            digest: "initial",
+            adoptedAt: Date.now(),
+            effective: initial,
+        };
+    }
+
+    current(): ConfigSnapshot<T> {
+        return this.snapshot;
+    }
+
+    lastFailure(): ConfigReloadFailure | undefined {
+        return this.failure;
+    }
+
+    poll(): ConfigSnapshot<T> {
+        const paths = [
+            cortexKitUserConfigBasePath(),
+            cortexKitProjectConfigBasePath(this.directory),
+        ].map((base) => detectConfigFile(base).path);
+        const next = new Map<string, FileState>();
+        let changed = paths.some((path) => !this.files.has(path));
+        for (const path of paths) {
+            let metadata: string;
+            try {
+                const stat = statSync(path);
+                metadata = `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+                    this.reportFailure(path, String(error), error);
+                    return this.snapshot;
+                }
+                metadata = "absent";
+            }
+            const previous = this.files.get(path);
+            if (previous?.metadata === metadata) {
+                next.set(path, previous);
+                continue;
+            }
+            let content: string;
+            try {
+                content = metadata === "absent" ? "" : readFileSync(path, "utf8");
+            } catch (error) {
+                this.reportFailure(path, String(error), error);
+                return this.snapshot;
+            }
+            const digest = createHash("sha256").update(content).digest("hex");
+            if (metadata !== "absent") {
+                const parsed = parseJsoncRecovering(content);
+                if (
+                    parsed.issues.length ||
+                    !parsed.value ||
+                    typeof parsed.value !== "object" ||
+                    Array.isArray(parsed.value)
+                ) {
+                    const issue = parsed.issues[0];
+                    this.reportFailure(
+                        path,
+                        digest,
+                        issue
+                            ? `${issue.line}:${issue.column}: ${issue.message}`
+                            : "expected an object",
+                    );
+                    return this.snapshot;
+                }
+            }
+            next.set(path, { metadata, digest });
+            changed ||= previous?.digest !== digest;
+        }
+        if (!changed) {
+            this.files = next;
+            return this.snapshot;
+        }
+        let effective: T;
+        try {
+            effective = this.load();
+        } catch (error) {
+            this.reportFailure(paths[0] ?? this.directory, "load", error);
+            return this.snapshot;
+        }
+        // The loader reads both tiers again. A concurrent writer must not let it
+        // publish a mixed user/project pair under the metadata staged above.
+        for (const path of paths) {
+            let metadata = "absent";
+            try {
+                const stat = statSync(path);
+                metadata = `${stat.mtimeMs}:${stat.size}:${stat.ino}`;
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+                    this.reportFailure(path, String(error), error);
+                    return this.snapshot;
+                }
+            }
+            if (metadata !== next.get(path)?.metadata) return this.snapshot;
+        }
+        const digest = createHash("sha256")
+            .update(paths.map((path) => `${path}:${next.get(path)?.digest}`).join("\n"))
+            .digest("hex");
+        this.files = next;
+        this.failure = undefined;
+        if (!this.initialized) {
+            this.initialized = true;
+            this.snapshot = {
+                generation: 1,
+                digest,
+                adoptedAt: this.snapshot.adoptedAt,
+                effective,
+            };
+        } else if (this.snapshot.digest !== digest) {
+            const keys = this.changedKeys(this.snapshot.effective, effective);
+            this.snapshot = {
+                generation: this.snapshot.generation + 1,
+                digest,
+                adoptedAt: Date.now(),
+                effective,
+            };
+            // A file can change (a save, a comment edit) without any setting changing;
+            // only a real change is worth a line.
+            if (keys.length > 0) {
+                this.onLog(
+                    `config reloaded gen=${this.snapshot.generation} keys=[${keys.join(",")}]`,
+                );
+            }
+        }
+        return this.snapshot;
+    }
+
+    private reportFailure(path: string, digest: string, error: unknown): void {
+        const message = error instanceof Error ? error.message : String(error);
+        this.failure = { path, message, digest };
+        if (this.warned.has(`${path}:${digest}`)) return;
+        this.warned.add(`${path}:${digest}`);
+        this.onLog(`config reload failed ${path}: ${message}`);
+    }
+}

package/src/config/protected-tokens.test.ts

@@ -188,6 +188,46 @@ describe("protected_tokens config and derivation", () => {
         });
     });
 
+    describe("protected_tokens below-minimum warning", () => {
+        it("emits the specific token-floor warning for a numeric value below the schema minimum", () => {
+            const recovered = parsePluginConfig({ protected_tokens: 20 });
+            const warnings = recovered.configWarnings ?? [];
+            expect(warnings.some((w) => w.includes("protected_tokens is a token floor"))).toBe(
+                true,
+            );
+            expect(warnings.some((w) => w.includes('"protected_tokens": invalid value'))).toBe(
+                false,
+            );
+        });
+
+        it("keeps the generic type message for a string value", () => {
+            const recovered = parsePluginConfig({ protected_tokens: "20" });
+            const warnings = recovered.configWarnings ?? [];
+            expect(warnings.some((w) => w.includes('"protected_tokens": invalid value'))).toBe(
+                true,
+            );
+            expect(warnings.some((w) => w.includes("protected_tokens is a token floor"))).toBe(
+                false,
+            );
+        });
+
+        it("keeps the generic above-max message for a value above the maximum", () => {
+            const recovered = parsePluginConfig({ protected_tokens: 2_000_000 });
+            const warnings = recovered.configWarnings ?? [];
+            expect(warnings.some((w) => w.includes('"protected_tokens": invalid value'))).toBe(
+                true,
+            );
+            expect(warnings.some((w) => w.includes("protected_tokens is a token floor"))).toBe(
+                false,
+            );
+        });
+
+        it("emits no warning when the key is absent", () => {
+            const recovered = parsePluginConfig({});
+            expect(recovered.configWarnings ?? []).toEqual([]);
+        });
+    });
+
     describe("protected_tags deprecation", () => {
         it("is parsed at any value (including 0 and 101) with parse succeeding and no numeric conversion", () => {
             resetProtectedTagsDeprecationWarningForTest();

package/src/config/raw-loader.test.ts

@@ -168,6 +168,7 @@ describe("per-harness raw config migration", () => {
         const taskRetained = {
             schedule: "0 3 * * *",
             promotion_threshold: 4,
+            recency_days: 30,
         };
         expect(Object.keys(historianRetained)).toEqual(
             PER_HARNESS_MIGRATION_INVENTORY.historian.retained,

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

@@ -191,12 +191,20 @@ describe("MagicContextConfigSchema", () => {
             expect(result.dreamer?.tasks.retrospective.schedule).toBe("0 5 * * *");
         });
 
-        it("defaults classify-memories and retrospective on daily in dreamer task metadata", () => {
-            const result = MagicContextConfigSchema.parse({
+        it("defaults retrospective to a 30-day source window and accepts an override", () => {
+            const defaults = MagicContextConfigSchema.parse({
                 dreamer: { opencode: { model: "x/y" } },
             });
-            expect(result.dreamer?.tasks["classify-memories"].schedule).toBe("0 6 * * *");
-            expect(result.dreamer?.tasks.retrospective.schedule).toBe("0 5 * * *");
+            expect(defaults.dreamer?.tasks["classify-memories"].schedule).toBe("0 6 * * *");
+            expect(defaults.dreamer?.tasks.retrospective.schedule).toBe("0 5 * * *");
+            expect(defaults.dreamer?.tasks.retrospective.recency_days).toBe(30);
+
+            const overridden = MagicContextConfigSchema.parse({
+                dreamer: {
+                    tasks: { retrospective: { schedule: "0 5 * * *", recency_days: 14 } },
+                },
+            });
+            expect(overridden.dreamer?.tasks.retrospective.recency_days).toBe(14);
         });
 
         it("parses both transform modes", () => {
@@ -449,7 +457,7 @@ describe("MagicContextConfigSchema", () => {
                     migrated_execution: ["model", "fallback_models", "variant", "thinking_level"],
                 },
                 task: {
-                    retained: ["schedule", "promotion_threshold"],
+                    retained: ["schedule", "promotion_threshold", "recency_days"],
                     migrated_execution: [
                         "model",
                         "fallback_models",

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

@@ -18,6 +18,11 @@ export const EXECUTE_THRESHOLD_CAP_MESSAGE =
 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;
+
 export const DEFAULT_LOCAL_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
 
 // Re-exported from the (DB-free) task registry so the schema and the runtime
@@ -151,7 +156,7 @@ export const PER_HARNESS_MIGRATION_INVENTORY = {
         migrated_execution: ["model", "fallback_models", "variant", "thinking_level"],
     },
     task: {
-        retained: ["schedule", "promotion_threshold"],
+        retained: ["schedule", "promotion_threshold", "recency_days"],
         migrated_execution: [
             "model",
             "fallback_models",
@@ -507,6 +512,15 @@ const ReviewUserMemoriesTaskConfigSchema = DreamTaskBaseConfigSchema.extend({
 const PromotePrimersTaskConfigSchema = DreamTaskBaseConfigSchema.extend({
     promotion_threshold: PrimerPromotionThresholdSchema,
 });
+const RetrospectiveTaskConfigSchema = DreamTaskBaseConfigSchema.extend({
+    recency_days: z
+        .number()
+        .int()
+        .min(1)
+        .max(3650)
+        .default(30)
+        .describe("retrospective: collect source messages from only the most recent N days"),
+});
 export type DreamTaskConfig = z.infer<typeof DreamTaskConfigSchema>;
 
 /** Default schedule per task. Preserves v1 behavior: verify runs nightly;
@@ -561,12 +575,22 @@ export const DreamTasksSchema = z
         "classify-memories": DreamTaskBaseConfigSchema.default(() =>
             DreamTaskBaseConfigSchema.parse(defaultTaskConfig("classify-memories")),
         ),
-        retrospective: DreamTaskBaseConfigSchema.default(() =>
-            DreamTaskBaseConfigSchema.parse(defaultTaskConfig("retrospective")),
-        ),
-        "maintain-docs": DreamTaskBaseConfigSchema.default(() =>
-            DreamTaskBaseConfigSchema.parse(defaultTaskConfig("maintain-docs")),
+        retrospective: RetrospectiveTaskConfigSchema.default(() =>
+            RetrospectiveTaskConfigSchema.parse(defaultTaskConfig("retrospective")),
         ),
+        "maintain-docs": DreamTaskBaseConfigSchema.extend({
+            max_tokens: z
+                .number()
+                .int()
+                .positive()
+                .default(12000)
+                .describe(
+                    "Maximum combined token count of proposed ARCHITECTURE.md and STRUCTURE.md",
+                ),
+        }).default(() => ({
+            ...DreamTaskBaseConfigSchema.parse(defaultTaskConfig("maintain-docs")),
+            max_tokens: 12000,
+        })),
         "evaluate-smart-notes": DreamTaskBaseConfigSchema.default(() =>
             DreamTaskBaseConfigSchema.parse(defaultTaskConfig("evaluate-smart-notes")),
         ),
@@ -920,7 +944,7 @@ export interface MagicContextConfig {
      *  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, dreamer, memory-migration) instead
+     *  own subagents (historian, dreamer) instead
      *  of deleting them on success. For short-term inspection/data collection;
      *  kept sessions accumulate until manually cleared. Default false. */
     keep_subagents: boolean;
@@ -1107,10 +1131,10 @@ export const MagicContextConfigSchema = 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", "model-id": "10m" }). 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).',
+                '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, then default). 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. On OpenCode and Pi, per-model routing applies to the guidance block only: tool descriptions are registered once per process, so they follow the default preset (a v1 plugin-surface limitation; per-model tool descriptions are planned for the OpenCode v2 plugin API once the SDK stabilizes).",
+            "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, Pi, and OMP register tool descriptions once per process (they follow the default preset). OpenCode 2 rewrites the five ctx_* descriptions per request from the draft model.",
         ),
         output_reserve: z
             .union([
@@ -1160,7 +1184,7 @@ export const MagicContextConfigSchema = z
         protected_tokens: z
             .number()
             .int()
-            .min(4000)
+            .min(PROTECTED_TOKENS_MIN)
             .max(1_000_000)
             .optional()
             .describe(
@@ -1190,7 +1214,9 @@ export const MagicContextConfigSchema = z
             .number()
             .min(60_000)
             .default(DEFAULT_HISTORIAN_TIMEOUT_MS)
-            .describe("Timeout for each historian prompt call in milliseconds (default: 600000)"),
+            .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
@@ -1306,7 +1332,7 @@ export const MagicContextConfigSchema = z
             .boolean()
             .default(false)
             .describe(
-                "Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, memory-migration) instead of deleting them on success. Useful for short-term inspection/data collection — 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.",
+                "Debug: keep every settled Magic Context child session instead of deleting it after success: historian, all Dreamer tasks, smart-note evaluation and compilation, user-memory review, and memory migration. Kept Dreamer 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, and only a Dreamer session none of whose runs settled is still deleted.",
             ),
         debug_rpc: z
             .boolean()
@@ -1326,7 +1352,7 @@ export const MagicContextConfigSchema = z
                     .boolean()
                     .default(true)
                     .describe(
-                        "When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed 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; ctx_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 magic-context.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 /ctx-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/docs 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. /ctx-wrapup, /ctx-recomp, /ctx-flush, and /ctx-session-upgrade refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.",
+                        "When false, Magic Context stops managing the context window and keeps its knowledge layer: memory and docs/user-profile/key-files injection through additive m[0]/m[1], raw-message FTS indexing, dreamer, notes, ctx_search, ctx_expand, ctx_memory, and /ctx-embed 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; ctx_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 magic-context.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 /ctx-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/docs 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. /ctx-wrapup, /ctx-recomp, and /ctx-flush refuse without context-management side effects; /ctx-embed remains functional. Raw content hidden by a native boundary before Magic Context's first pass is not retroactively indexed.",
                     ),
             })
             .default({ enabled: true })
@@ -1485,6 +1511,76 @@ export const MagicContextConfigSchema = z
         };
     });
 
+/** Settings whose fresh values can be used by later agent runs without changing rendered prompt bytes. */
+export const LIVE_RELOAD_CONFIG_PATHS = [
+    "mural.model",
+    "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.omp.model",
+    "historian.omp.fallback_models",
+    "historian.omp.thinking_level",
+    "historian.two_pass",
+    "historian_timeout_ms",
+    "commit_cluster_trigger.enabled",
+    "commit_cluster_trigger.min_clusters",
+    "memory.auto_promote",
+    "dreamer.opencode.model",
+    "dreamer.opencode.fallback_models",
+    "dreamer.opencode.variant",
+    "dreamer.opencode.tasks",
+    "dreamer.pi.model",
+    "dreamer.pi.fallback_models",
+    "dreamer.pi.thinking_level",
+    "dreamer.pi.tasks",
+    "dreamer.omp.model",
+    "dreamer.omp.fallback_models",
+    "dreamer.omp.thinking_level",
+    "dreamer.omp.tasks",
+    "dreamer.tasks.map-memories.schedule",
+    "dreamer.tasks.verify.schedule",
+    "dreamer.tasks.verify-broad.schedule",
+    "dreamer.tasks.curate.schedule",
+    "dreamer.tasks.compress-cues.schedule",
+    "dreamer.tasks.classify-memories.schedule",
+    "dreamer.tasks.retrospective.schedule",
+    "dreamer.tasks.retrospective.recency_days",
+    "dreamer.tasks.maintain-docs.schedule",
+    "dreamer.tasks.evaluate-smart-notes.schedule",
+    "dreamer.tasks.review-user-memories.schedule",
+    "dreamer.tasks.review-user-memories.promotion_threshold",
+    "dreamer.tasks.promote-primers.schedule",
+    "dreamer.tasks.promote-primers.promotion_threshold",
+    "dreamer.tasks.refresh-primers.schedule",
+    "memory.git_commit_indexing.enabled",
+    "memory.git_commit_indexing.since_days",
+    "memory.git_commit_indexing.max_commits",
+] 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._def.in as z.ZodType;
+    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)

package/src/features/magic-context/dreamer/task-registry.ts

@@ -29,25 +29,102 @@ export const CANONICAL_DREAM_TASKS = [
 
 export type DreamTaskName = (typeof CANONICAL_DREAM_TASKS)[number];
 
-export const DREAM_TASK_CAPABILITIES: Record<DreamTaskName, { requiresTools: boolean }> = {
+/**
+ * How a Dreamer task reaches its result, which is what decides whether a host
+ * without a tool loop can run it:
+ *  - "tool-loop": the task drives an agent that must call tools between model
+ *    turns (reading files, searching, writing memories through `ctx_memory`).
+ *  - "single-shot": one or more no-tool completions whose entire answer is the
+ *    returned text. Any transport that can deliver a prompt and return text runs
+ *    these, including a hidden completion carrier.
+ *  - "host-only": no model call at all. The task is database work done in this
+ *    process, so it needs no completion transport whatsoever.
+ */
+export type DreamTaskTransport = "tool-loop" | "single-shot" | "host-only";
+
+export interface DreamTaskCapability {
+    /** True only when the task cannot finish without a tool loop. */
+    requiresTools: boolean;
+    transport: DreamTaskTransport;
+    /**
+     * What the tool loop is needed FOR, as one clause a user can read. Present
+     * only on tool-loop tasks, where it becomes the named per-task reason shown
+     * when a host refuses the task instead of a single anonymous "filtered" list.
+     */
+    toolLoopPurpose?: string;
+}
+
+export const DREAM_TASK_CAPABILITIES: Record<DreamTaskName, DreamTaskCapability> = {
     // A single manifest is not a tool-free task: mapping and verification need
     // read-only tools to inspect backing code before they can change memory state.
-    "map-memories": { requiresTools: true },
-    verify: { requiresTools: true },
-    "verify-broad": { requiresTools: true },
-    curate: { requiresTools: true },
+    "map-memories": {
+        requiresTools: true,
+        transport: "tool-loop",
+        toolLoopPurpose: "needs read-only file tools to locate the code each memory describes",
+    },
+    verify: {
+        requiresTools: true,
+        transport: "tool-loop",
+        toolLoopPurpose: "needs read-only file tools to re-check each memory against the code",
+    },
+    "verify-broad": {
+        requiresTools: true,
+        transport: "tool-loop",
+        toolLoopPurpose: "needs read-only file tools to re-check each memory against the code",
+    },
+    curate: {
+        requiresTools: true,
+        transport: "tool-loop",
+        toolLoopPurpose: "needs the ctx_memory tool to apply its merge and archive decisions",
+    },
     // mural/compress-cues.ts is a zero-tool transform; its child transport
     // still needs substitution before the generate executor can dispatch it.
-    "compress-cues": { requiresTools: false },
-    "classify-memories": { requiresTools: false },
-    retrospective: { requiresTools: true },
-    "maintain-docs": { requiresTools: true },
-    "evaluate-smart-notes": { requiresTools: true },
-    "review-user-memories": { requiresTools: true },
-    "promote-primers": { requiresTools: true },
-    "refresh-primers": { requiresTools: true },
+    "compress-cues": { requiresTools: false, transport: "single-shot" },
+    "classify-memories": { requiresTools: false, transport: "single-shot" },
+    retrospective: {
+        requiresTools: true,
+        transport: "tool-loop",
+        toolLoopPurpose: "needs search tools to investigate the friction it finds in past sessions",
+    },
+    "maintain-docs": {
+        requiresTools: true,
+        transport: "tool-loop",
+        toolLoopPurpose: "needs file read and write tools to update project documentation",
+    },
+    // The evaluator is a no-tool compiler plus a no-tool confirmation prompt; the
+    // generated check runs in the local capability sandbox, never as model tools.
+    "evaluate-smart-notes": { requiresTools: false, transport: "single-shot" },
+    // The reviewer reads candidate text and answers with JSON; the host applies it.
+    "review-user-memories": { requiresTools: false, transport: "single-shot" },
+    // Promotion clusters existing candidates and writes rows. It calls no model.
+    "promote-primers": { requiresTools: false, transport: "host-only" },
+    "refresh-primers": {
+        requiresTools: true,
+        transport: "tool-loop",
+        toolLoopPurpose: "needs read-only investigation tools to answer each standing question",
+    },
 };
 
+/** Tasks a host without a tool loop cannot run, in canonical order. */
+export function toolLoopDreamTasks(): DreamTaskName[] {
+    return CANONICAL_DREAM_TASKS.filter((task) => DREAM_TASK_CAPABILITIES[task].requiresTools);
+}
+
+/**
+ * One line per refused task, naming the task, the stable code and what the tool
+ * loop is needed for. A user reading /ctx-dream or /ctx-status output should be
+ * able to tell which specific task is unavailable and why, rather than seeing a
+ * single anonymous "unsupported" list.
+ */
+export function formatUnsupportedDreamTasks(tasks: readonly DreamTaskName[], code: string): string {
+    return tasks
+        .map((task) => {
+            const purpose = DREAM_TASK_CAPABILITIES[task].toolLoopPurpose;
+            return `- ${task}: unavailable on this host (${code})${purpose ? ` — ${purpose}` : ""}`;
+        })
+        .join("\n");
+}
+
 /** Cheap, read-only work counts for one Dreamer task. */
 export interface DreamTaskBacklog {
     /** Items selected by the task's current backlog predicate. */
@@ -78,6 +155,53 @@ export function formatDreamTaskBacklogs(
         .join("\n");
 }
 
+/** One dreamer task whose last scheduled run failed. */
+export interface DreamTaskFailureState {
+    task: string;
+    /** The scheduler's recorded failure text. */
+    error: string;
+    /** Epoch ms of the last run that SUCCEEDED, or null if none ever has. A failed run
+     *  never advances `last_run_at`, so this says how long the task has been stuck, not
+     *  when it last failed — the scheduler keeps no failure timestamp. */
+    lastSucceededAt: number | null;
+    /** Consecutive retries queued so far; reset once the retry cap pushes the task to
+     *  its next cron slot, so a long-running failure oscillates rather than climbs. */
+    retryCount: number;
+}
+
+/** How much of a scheduler failure message a status line carries before eliding. */
+const FAILURE_TEXT_BUDGET = 180;
+
+function sinceLabel(lastSucceededAt: number | null, now: number): string {
+    if (lastSucceededAt === null || lastSucceededAt <= 0) return "never succeeded";
+    const hours = Math.max(0, Math.floor((now - lastSucceededAt) / 3_600_000));
+    if (hours < 1) return "last succeeded under an hour ago";
+    if (hours < 48) return `last succeeded ${hours}h ago`;
+    return `last succeeded ${Math.floor(hours / 24)}d ago`;
+}
+
+/**
+ * One line per failing task, shared by the status surfaces.
+ *
+ * The elapsed time is measured from the last SUCCESS, not the last failure: a failed
+ * run deliberately does not advance `last_run_at`, so that is the only timestamp the
+ * scheduler keeps and "stuck since" is what a reader needs anyway.
+ */
+export function formatDreamTaskFailures(
+    failures: readonly DreamTaskFailureState[],
+    now: number = Date.now(),
+): string {
+    return failures
+        .map((failure) => {
+            const error =
+                failure.error.length > FAILURE_TEXT_BUDGET
+                    ? `${failure.error.slice(0, FAILURE_TEXT_BUDGET)}…`
+                    : failure.error;
+            return `- ${failure.task}: failing (${sinceLabel(failure.lastSucceededAt, now)}) — ${error}`;
+        })
+        .join("\n");
+}
+
 /** Process-local progress for the task currently applying a run chunk. */
 export interface DreamTaskProgress {
     task: DreamTaskName;