@cortexkit/opencode-magic-context 0.49.10 → 0.49.12

package/dist/v2/{server-988cqjme.js → server-rrqpvwqd.js}

@@ -1,12 +1,12 @@
 import {
   estimateTokens
-} from "./server-s6jqh8bj.js";
+} from "./server-0ppsweh6.js";
 import {
   getHarness2
 } from "./server-pavzsdc6.js";
 import {
   log2
-} from "./server-9e5r8y60.js";
+} from "./server-f2xf5gcb.js";
 import {
   inRootAsyncContext2
 } from "./server-wafzvyhg.js";

package/dist/v2/{server-4easnf78.js → server-sz8jj92q.js}

@@ -6,11 +6,11 @@ import {
 } from "./server-wafzvyhg.js";
 import {
   DEFAULT_LOCAL_EMBEDDING_MODEL
-} from "./server-7e087rvk.js";
+} from "./server-th4y11y7.js";
 import {
   isUserHomeDirectory,
   setBootQuietPeriodForTests
-} from "./server-njnx39q2.js";
+} from "./server-gvkm8xaj.js";
 import {
   isEmbeddingHostBusy2
 } from "./server-qt1qqasc.js";
@@ -20,17 +20,18 @@ import {
 import {
   sanitizeDiagnosticText,
   log2
-} from "./server-9e5r8y60.js";
+} from "./server-f2xf5gcb.js";
 import {
   estimateTokens
-} from "./server-s6jqh8bj.js";
+} from "./server-0ppsweh6.js";
 import {
   SYNAPSE_DEFAULT_MODEL,
   isSynapseEmbeddingTruncated,
   getSynapseBatchRequestKey,
   SynapseEmbeddingProvider
-} from "./server-988cqjme.js";
+} from "./server-rrqpvwqd.js";
 import {
+  DEFAULT_COMPARTMENT_CHUNK_MAX_INPUT_TOKENS,
   CHUNK_WINDOW_SAFETY_RATIO,
   normalizeCompartmentChunkMaxInputTokens,
   buildCanonicalChunkTextFromFts,
@@ -44,8 +45,9 @@ import {
   chunkWindowSourceKey,
   loadUnembeddedSessionChunkCandidatesPolite,
   countSessionCompartmentEmbedCoverage,
+  countSessionCompartmentEmbedCoveragePolite,
   countUnembeddedSessionCompartmentsPolite
-} from "./server-9a6bwc12.js";
+} from "./server-vknbt0gq.js";
 import {
   saveEmbeddingIfHashMatches,
   getMemoryEmbedCoverage,
@@ -57,10 +59,10 @@ import {
   resolveEmbeddingTextPrefixes,
   getEmbeddingProviderIdentity,
   LocalEmbeddingProvider
-} from "./server-44ryn9rb.js";
+} from "./server-2x42esxd.js";
 import {
   logSlowWriteTransaction
-} from "./server-7dv9wt9r.js";
+} from "./server-6pmqg9m4.js";
 
 // src/shared/background-batch-drain.ts
 async function drainBackgroundBatches(step, options = {}) {
@@ -141,7 +143,7 @@ function pruneSynapseBatchLedgerForProject(db, projectIdentity, ttlMs = SYNAPSE_
 }
 
 // src/features/magic-context/project-embedding-registry.ts
-import { createHash as createHash2, randomUUID } from "node:crypto";
+import { createHash as createHash3, randomUUID } from "node:crypto";
 
 // src/features/magic-context/git-commits/storage-git-commit-embeddings.ts
 var saveStatements = new WeakMap;
@@ -461,6 +463,9 @@ function releaseGitSweepLease(db, projectPath, holderId) {
   });
 }
 
+// src/features/magic-context/memory/embedding-openai.ts
+import { createHash as createHash2 } from "node:crypto";
+
 // src/features/magic-context/memory/embedding-ssrf.ts
 var METADATA_HOSTNAMES = new Set(["metadata.google.internal", "metadata.goog"]);
 var IPV6_METADATA_HOSTS = new Set(["fd00:ec2::254"]);
@@ -560,6 +565,55 @@ var FAILURE_THRESHOLD = 3;
 var FAILURE_WINDOW_MS = 60000;
 var OPEN_DURATION_MS = 5 * 60000;
 var FETCH_TIMEOUT_MS = 30000;
+var RETRY_AFTER_CAP_MS = 60000;
+var RATE_LIMIT_BACKOFF_BASE_MS = 1000;
+var RATE_LIMIT_BACKOFF_CAP_MS = 30000;
+var RATE_LIMIT_BACKOFF_JITTER = 0.25;
+var rateLimitStates = new Map;
+function rateLimitStateKey(endpoint, apiKey) {
+  const keyHash = apiKey ? createHash2("sha256").update(apiKey).digest("hex").slice(0, 16) : "";
+  return `${endpoint}\x00${keyHash}`;
+}
+function parseRetryAfterMs(value, nowMs) {
+  const trimmed = value?.trim() ?? "";
+  if (!trimmed)
+    return null;
+  let delayMs;
+  if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+    delayMs = Number(trimmed) * 1000;
+  } else {
+    const at = Date.parse(trimmed);
+    if (!Number.isFinite(at))
+      return null;
+    delayMs = at - nowMs;
+  }
+  if (!(delayMs > 0))
+    return null;
+  return Math.min(Math.ceil(delayMs), RETRY_AFTER_CAP_MS);
+}
+function rateLimitBackoffMs(consecutive, random = Math.random) {
+  const exponent = Math.min(Math.max(0, Math.floor(consecutive)), 30);
+  const nominal = Math.min(RATE_LIMIT_BACKOFF_CAP_MS, RATE_LIMIT_BACKOFF_BASE_MS * 2 ** exponent);
+  const jitter = Math.min(1, Math.max(0, random())) * RATE_LIMIT_BACKOFF_JITTER;
+  return Math.min(RATE_LIMIT_BACKOFF_CAP_MS, Math.round(nominal * (1 + jitter)));
+}
+function sleepUnlessAborted(ms, signal) {
+  if (signal?.aborted)
+    return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve(false);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve(true);
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var RATE_LIMITED = Symbol("rate-limited");
+var maxInputTokensWarnings = new Set;
 
 class OpenAICompatibleEmbeddingProvider {
   modelId;
@@ -580,6 +634,7 @@ class OpenAICompatibleEmbeddingProvider {
   lastFailureReason = null;
   halfOpenProbeInFlight = false;
   queryTruncationLogged = false;
+  rateLimitKey;
   constructor(options) {
     this.endpoint = normalizeEndpoint(options.endpoint);
     this.model = options.model?.trim() ?? "";
@@ -590,7 +645,16 @@ class OpenAICompatibleEmbeddingProvider {
     this.queryPrefix = prefixes.queryPrefix;
     this.documentPrefix = prefixes.documentPrefix;
     this.truncate = options.truncate?.trim() ?? "";
-    this.maxInputTokens = typeof options.maxInputTokens === "number" && Number.isFinite(options.maxInputTokens) ? Math.max(1, Math.floor(options.maxInputTokens)) : 512;
+    this.rateLimitKey = rateLimitStateKey(this.endpoint, this.apiKey);
+    const maxInputTokensSet = typeof options.maxInputTokens === "number" && Number.isFinite(options.maxInputTokens);
+    this.maxInputTokens = maxInputTokensSet ? Math.max(1, Math.floor(options.maxInputTokens)) : DEFAULT_COMPARTMENT_CHUNK_MAX_INPUT_TOKENS;
+    if (!maxInputTokensSet && this.endpoint && this.model) {
+      const warningKey = `${this.endpoint}\x00${this.model}`;
+      if (!maxInputTokensWarnings.has(warningKey)) {
+        maxInputTokensWarnings.add(warningKey);
+        log2(`[magic-context] embedding.max_input_tokens is not set for openai-compatible model "${sanitizeDiagnosticText(this.model)}"; chunk embeddings use the ${DEFAULT_COMPARTMENT_CHUNK_MAX_INPUT_TOKENS}-token default, which is sized for the bundled local model and splits history into small pieces. Set embedding.max_input_tokens to the model's input limit (changing it re-embeds stored chunks once).`);
+      }
+    }
     this.modelId = getEmbeddingProviderIdentity({
       provider: "openai-compatible",
       endpoint: this.endpoint,
@@ -648,6 +712,23 @@ class OpenAICompatibleEmbeddingProvider {
     if (signal?.aborted) {
       return Array.from({ length: texts.length }, () => null);
     }
+    const isQuery = purpose === "query";
+    for (;; ) {
+      if (Date.now() < this.rateLimit.until) {
+        if (isQuery)
+          return Array.from({ length: texts.length }, () => null);
+        if (!await this.waitForRateLimitCooldown(signal)) {
+          return Array.from({ length: texts.length }, () => null);
+        }
+      }
+      const outcome = await this.requestOnce(texts, requestTexts, signal, purpose);
+      if (outcome !== RATE_LIMITED)
+        return outcome;
+      if (isQuery)
+        return Array.from({ length: texts.length }, () => null);
+    }
+  }
+  async requestOnce(texts, requestTexts, signal, purpose) {
     let isProbe = false;
     let internalController;
     let timeoutHandle;
@@ -680,9 +761,14 @@ class OpenAICompatibleEmbeddingProvider {
         redirect: "error",
         signal: internalController.signal
       });
+      if (response.status === 429) {
+        await response.text().catch(() => "");
+        this.noteRateLimit(response.headers.get("retry-after"));
+        return RATE_LIMITED;
+      }
       if (!response.ok) {
         const excerpt = await response.text().catch(() => "");
-        const failure = this.failure("http_error", `HTTP ${response.status} from endpoint${this.bodyExcerpt(excerpt)}`, response.status >= 500 || response.status === 408 || response.status === 429);
+        const failure = this.failure("http_error", `HTTP ${response.status} from endpoint${this.bodyExcerpt(excerpt)}`, response.status >= 500 || response.status === 408);
         log2(`[magic-context] openai-compatible embedding request failed: ${failure.reason}`);
         this.recordFailure(isProbe, failure);
         return Array.from({ length: texts.length }, () => null);
@@ -781,6 +867,36 @@ class OpenAICompatibleEmbeddingProvider {
   isLoaded() {
     return this.initialized;
   }
+  get rateLimit() {
+    let state = rateLimitStates.get(this.rateLimitKey);
+    if (!state) {
+      state = { until: 0, consecutive: 0 };
+      rateLimitStates.set(this.rateLimitKey, state);
+    }
+    return state;
+  }
+  async waitForRateLimitCooldown(signal) {
+    for (;; ) {
+      const remaining = this.rateLimit.until - Date.now();
+      if (remaining <= 0)
+        return true;
+      if (!await sleepUnlessAborted(remaining, signal))
+        return false;
+    }
+  }
+  noteRateLimit(retryAfter) {
+    const state = this.rateLimit;
+    const now = Date.now();
+    const headerDelayMs = parseRetryAfterMs(retryAfter, now);
+    const delayMs = headerDelayMs ?? rateLimitBackoffMs(state.consecutive);
+    state.consecutive += 1;
+    const alreadyCoolingDown = now < state.until;
+    state.until = Math.max(state.until, now + delayMs);
+    const seconds = Math.ceil(delayMs / 1000);
+    if (!alreadyCoolingDown) {
+      log2(`[magic-context] openai-compatible embedding rate limited (HTTP 429): pausing requests for ${seconds}s (${headerDelayMs !== null ? "Retry-After" : "backoff"}); background embedding resumes after the pause and searches run lexical-only until then`);
+    }
+  }
   claimProbeOrShortCircuit() {
     if (this.circuitOpenUntil === 0) {
       return "allow";
@@ -835,6 +951,7 @@ class OpenAICompatibleEmbeddingProvider {
     this.circuitOpenUntil = 0;
     this.openLogged = false;
     this.lastFailureReason = null;
+    this.rateLimit.consecutive = 0;
   }
   getLastFailureReason() {
     return this.lastFailureReason;
@@ -850,6 +967,9 @@ class OpenAICompatibleEmbeddingProvider {
   _getFailureCount() {
     return this.failureTimes.length;
   }
+  _getRateLimitedUntil() {
+    return this.rateLimit.until;
+  }
   _resetCircuit() {
     this.failureTimes = [];
     this.circuitOpenUntil = 0;
@@ -1304,10 +1424,10 @@ function stableStringify(value) {
   return JSON.stringify(value);
 }
 function sha256Prefix(value, length = 16) {
-  return createHash2("sha256").update(value).digest("hex").slice(0, length);
+  return createHash3("sha256").update(value).digest("hex").slice(0, length);
 }
 function contentSha2562(value) {
-  return createHash2("sha256").update(value).digest("hex");
+  return createHash3("sha256").update(value).digest("hex");
 }
 function getRuntimeFingerprint(config) {
   if (config.provider === "off") {
@@ -2631,7 +2751,7 @@ async function drainCommitBacklogForProject2(db, projectIdentity, deadline) {
   }
   return total;
 }
-async function embedCompartmentChunkBatch(db, projectIdentity, batchSize) {
+async function embedCompartmentChunkBatch(db, projectIdentity, batchSize, signal) {
   const snapshot = getProjectEmbeddingSnapshot2(projectIdentity);
   if (!snapshot?.historyEnabled || snapshot.chunkModelId === "off")
     return 0;
@@ -2639,7 +2759,7 @@ async function embedCompartmentChunkBatch(db, projectIdentity, batchSize) {
   const candidates = await loadUnembeddedCompartmentChunkCandidatesPolite(db, projectIdentity, snapshot.chunkModelId, batchSize, getProjectEmbeddingMaxInputTokens2(projectIdentity), true);
   if (candidates.length === 0)
     return 0;
-  const { embedded } = await embedCandidateChunkBatch(db, projectIdentity, snapshot.chunkModelId, candidates);
+  const { embedded } = await embedCandidateChunkBatch(db, projectIdentity, snapshot.chunkModelId, candidates, signal);
   return embedded;
 }
 function getLastEmbeddingFailureForProject(projectIdentity) {
@@ -2776,6 +2896,9 @@ async function drainCompartmentChunkBacklogForProject(db, projectIdentity, deadl
   }
   let total = 0;
   let leaseLost = false;
+  const drainAbort = new AbortController;
+  const deadlineTimer = setTimeout(() => drainAbort.abort(), Math.max(0, deadline - Date.now()));
+  deadlineTimer.unref?.();
   const renewal = inRootAsyncContext2(() => setInterval(() => {
     try {
       if (!renewGitSweepLease(db, projectIdentity, holderId))
@@ -2784,8 +2907,8 @@ async function drainCompartmentChunkBacklogForProject(db, projectIdentity, deadl
   }, SESSION_EMBED_LEASE_RENEWAL_MS));
   renewal.unref?.();
   try {
-    while (!leaseLost && !isEmbeddingHostBusy2() && Date.now() < deadline && total < CHUNK_DRAIN_MAX_PER_SWEEP) {
-      const embedded = await embedCompartmentChunkBatch(db, projectIdentity, CHUNK_DRAIN_BATCH_SIZE);
+    while (!leaseLost && !drainAbort.signal.aborted && !isEmbeddingHostBusy2() && Date.now() < deadline && total < CHUNK_DRAIN_MAX_PER_SWEEP) {
+      const embedded = await embedCompartmentChunkBatch(db, projectIdentity, CHUNK_DRAIN_BATCH_SIZE, drainAbort.signal);
       if (!renewGitSweepLease(db, projectIdentity, holderId))
         leaseLost = true;
       if (leaseLost || embedded === 0)
@@ -2795,6 +2918,7 @@ async function drainCompartmentChunkBacklogForProject(db, projectIdentity, deadl
         break;
     }
   } finally {
+    clearTimeout(deadlineTimer);
     clearInterval(renewal);
     releaseGitSweepLease(db, projectIdentity, holderId);
   }
@@ -2940,6 +3064,14 @@ function getEmbeddingCoverageStatus2(db, projectIdentity, sessionId) {
     shadowBackfillStalls: listShadowBackfillStalls2(db, projectIdentity)
   };
 }
+async function getAutoEmbeddingSessionCoverage2(db, projectIdentity, sessionId) {
+  const snapshot = getProjectEmbeddingSnapshot2(projectIdentity);
+  if (!snapshot?.historyEnabled || snapshot.chunkModelId === "off") {
+    return { enabled: false, embedded: 0, total: 0 };
+  }
+  const coverage = await countSessionCompartmentEmbedCoveragePolite(db, projectIdentity, sessionId, snapshot.chunkModelId, getProjectEmbeddingMaxInputTokens2(projectIdentity));
+  return { enabled: true, ...coverage };
+}
 async function sweepAllRegisteredProjects2(db, batchSize = 10) {
   if (projectSweepInProgress || isEmbeddingHostBusy2()) {
     log2("[magic-context] project embedding sweep already in progress, skipping this tick");
@@ -3020,4 +3152,4 @@ function _resetProjectEmbeddingRegistryForTests2() {
   setBootQuietPeriodForTests(null);
 }
 
-export { drainBackgroundBatches, recordEmbeddingMeasurement, saveCommitEmbedding, loadProjectCommitEmbeddings, loadUnembeddedCommits, countEmbeddedCommits, upsertCommits, getLatestIndexedCommitSha, enforceProjectCap, GIT_SWEEP_LEASE_RENEWAL_MS, acquireGitSweepLease, renewGitSweepLease, markGitSweepSuccessAndRelease, parkGitSweepNonIndexable, releaseGitSweepLease, OpenAICompatibleEmbeddingProvider, recordSessionProjectIdentity, hasRecordedSessionProjectIdentity, describeShadowBackfillWriteRefusal2, listShadowBackfillStalls2, getShadowBackfillStopReason2, markProjectLoadUntrusted2, contentSha2562, drainProjectEmbeddingIdentityMaintenance2, drainStaleEmbeddingIdentitiesForProject2, registerProjectEmbedding2, registerProjectShadowEmbedding2, getShadowEmbeddingMeasurementCohort2, getPrimaryEmbeddingMeasurementCohort2, embedShadowTextForProject2, enqueueShadowEmbeddingItems2, getShadowBackfillRemaining2, flushShadowEmbeddingBacklog2, registerProjectInObservationMode2, unregisterProjectShadowEmbedding2, unregisterProjectEmbedding2, getProjectEmbeddingSnapshot2, installProjectEmbeddingSearchBridge2, getProjectChunkEmbeddingModelId2, getProjectEmbeddingMaxInputTokens2, embedTextForProject2, embedBatchForProject2, embedItemsForProject2, embedUnembeddedMemoriesForProject2, embedUnembeddedMemoriesForProjectOutcome2, drainCommitBacklogForProject2, embedUnembeddedCompartmentChunksForProject2, embedSessionCompartmentChunks2, getEmbeddingCoverageStatus2, sweepAllRegisteredProjects2, _setTestProviderFactoryForProject2, _resetProjectEmbeddingRegistryForTests2 };
+export { drainBackgroundBatches, recordEmbeddingMeasurement, saveCommitEmbedding, loadProjectCommitEmbeddings, loadUnembeddedCommits, countEmbeddedCommits, upsertCommits, getLatestIndexedCommitSha, enforceProjectCap, GIT_SWEEP_LEASE_RENEWAL_MS, acquireGitSweepLease, renewGitSweepLease, markGitSweepSuccessAndRelease, parkGitSweepNonIndexable, releaseGitSweepLease, OpenAICompatibleEmbeddingProvider, recordSessionProjectIdentity, hasRecordedSessionProjectIdentity, describeShadowBackfillWriteRefusal2, listShadowBackfillStalls2, getShadowBackfillStopReason2, markProjectLoadUntrusted2, contentSha2562, drainProjectEmbeddingIdentityMaintenance2, drainStaleEmbeddingIdentitiesForProject2, registerProjectEmbedding2, registerProjectShadowEmbedding2, getShadowEmbeddingMeasurementCohort2, getPrimaryEmbeddingMeasurementCohort2, embedShadowTextForProject2, enqueueShadowEmbeddingItems2, getShadowBackfillRemaining2, flushShadowEmbeddingBacklog2, registerProjectInObservationMode2, unregisterProjectShadowEmbedding2, unregisterProjectEmbedding2, getProjectEmbeddingSnapshot2, installProjectEmbeddingSearchBridge2, getProjectChunkEmbeddingModelId2, getProjectEmbeddingMaxInputTokens2, embedTextForProject2, embedBatchForProject2, embedItemsForProject2, embedUnembeddedMemoriesForProject2, embedUnembeddedMemoriesForProjectOutcome2, drainCommitBacklogForProject2, embedUnembeddedCompartmentChunksForProject2, embedSessionCompartmentChunks2, getEmbeddingCoverageStatus2, getAutoEmbeddingSessionCoverage2, sweepAllRegisteredProjects2, _setTestProviderFactoryForProject2, _resetProjectEmbeddingRegistryForTests2 };

package/dist/v2/{server-7e087rvk.js → server-th4y11y7.js}

@@ -5659,7 +5659,7 @@ var DreamTasksSchema = object({
     max_tokens: 12000
   })),
   "evaluate-smart-notes": DreamTaskBaseConfigSchema.default(() => DreamTaskBaseConfigSchema.parse(defaultTaskConfig("evaluate-smart-notes"))),
-  "review-user-memories": ReviewUserMemoriesTaskConfigSchema.default(() => ReviewUserMemoriesTaskConfigSchema.parse(defaultTaskConfig("review-user-memories"))),
+  "review-user-memories": ReviewUserMemoriesTaskConfigSchema.default(() => ReviewUserMemoriesTaskConfigSchema.parse(defaultTaskConfig("review-user-memories"))).describe("Promote recurring user observations into the <user-profile> block. A non-empty schedule also makes the historian collect user observations, but only while the dreamer is runnable (dreamer.disable not true); collection and review follow that one gate and do not depend on memory.enabled."),
   "promote-primers": PromotePrimersTaskConfigSchema.default(() => PromotePrimersTaskConfigSchema.parse(defaultTaskConfig("promote-primers"))),
   "refresh-primers": DreamTaskBaseConfigSchema.default(() => DreamTaskBaseConfigSchema.parse(defaultTaskConfig("refresh-primers")))
 }).describe("Harness-independent task metadata. schedule, promotion_threshold, and other task metadata remain here; execution settings live under dreamer.opencode.tasks, dreamer.pi.tasks, or dreamer.omp.tasks.");
@@ -5677,13 +5677,13 @@ var AgentMetadataSchema = AgentOverrideConfigSchema.pick({
   maxTokens: true
 });
 var DreamerConfigSchema = AgentMetadataSchema.extend({
-  disable: boolean2().optional().describe("Disable this agent"),
+  disable: boolean2().optional().describe("Disable the dreamer: no scheduled or manual dream task runs. Also turns off smart notes (ctx_note drops surface_condition even with smart_notes.enabled true) and the historian's collection of user observations for review-user-memories. dreamer.inject_docs still applies."),
   runner: _enum(["broca", "host"]).optional().describe(`Which side runs the dreamer completions the Rust module routes (classify-memories) in Rust transform mode: "host" runs them on this process's carrier, "broca" routes them to the Broca module. When unset, historian.runner applies, and when that is unset too the harness decides the same way it does for the historian. User-level config only.`),
   opencode: DreamerOpenCodeHarnessBlockSchema.optional(),
   pi: DreamerPiHarnessBlockSchema.optional(),
   omp: DreamerOmpHarnessBlockSchema.optional(),
   tasks: DreamTasksSchema.default(() => DreamTasksSchema.parse({})),
-  inject_docs: boolean2().default(true).describe("Inject ARCHITECTURE.md and STRUCTURE.md into the m[0] `<project-docs>` block (default true)")
+  inject_docs: boolean2().default(true).describe("Inject ARCHITECTURE.md and STRUCTURE.md into the m[0] `<project-docs>` block (default true). Not a dreamer setting despite its place under dreamer: it applies on every host, also with dreamer.disable true.")
 });
 var HistorianConfigSchema = AgentMetadataSchema.extend({
   expand_tools: record(string(), union([
@@ -5822,9 +5822,9 @@ var MagicContextConfigSchema = object({
   profile: 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/dreamer model, fallback_models, OpenCode variant, and Pi/OMP thinking_level fields; task execution policy (including timeout_minutes) is excluded. Project configs may select a name but cannot define profiles."),
   historian: HistorianConfigSchema.describe("Historian metadata plus independent strict OpenCode, Pi, and OMP execution blocks. Retained metadata stays at historian; model, fallback_models, variant, and thinking_level belong only in historian.opencode, historian.pi, or historian.omp."),
-  dreamer: DreamerConfigSchema.optional().describe("Dreamer metadata and scheduling plus independent strict OpenCode, Pi, and OMP execution blocks. schedule and promotion_threshold stay at dreamer.tasks; model, fallback_models, variant, thinking_level, and timeout_minutes belong only in the matching harness block."),
+  dreamer: DreamerConfigSchema.optional().describe("Dreamer metadata and scheduling plus independent strict OpenCode, Pi, and OMP execution blocks. schedule and promotion_threshold stay at dreamer.tasks; model, fallback_models, variant, thinking_level, and timeout_minutes belong only in the matching harness block. Each task follows the setting it serves: memory tasks need memory.enabled, evaluate-smart-notes needs smart_notes.enabled, review-user-memories needs its schedule, maintain-docs only a runnable dreamer."),
   smart_notes: object({
-    enabled: boolean2().default(true).describe("Enable smart-note authoring and condition evaluation. User-level only: tool definitions are process-wide. Changes require a host restart and rebuild each session's cached prompt once. Pending notes remain stored and unchecked; already-ready notes still surface."),
+    enabled: boolean2().default(true).describe("Enable smart-note authoring and condition evaluation. Needs a runnable dreamer, which evaluates the conditions: with dreamer.disable true (or no dreamer block) ctx_note offers no surface_condition whatever this says. User-level only: tool definitions are process-wide. Changes require a host restart and rebuild each session's cached prompt once. Pending notes remain stored and unchecked; already-ready notes still surface."),
     retina_handoff: boolean2().default(false).describe("When true, dreamer skips smart notes whose surface conditions compiled to retina provider configs at authoring time. Default false keeps both paths active until the retina consumer is deployed.")
   }).default({ enabled: true, retina_handoff: false }).describe("Smart-note ownership transition controls."),
   cache_ttl: union([string(), object({ default: string() }).catchall(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, then default). User and project settings, including an explicit "5m" or object default, apply on the next pass. Only built-in defaults are frozen per session, including across restarts: when unset, GPT-5.6 and later (including gpt-6*, through any provider prefix) use 30m, other models use 5m. /ctx-status shows the effective TTL and whether it comes from your config or a frozen built-in default. Editing the TTL does not itself rewrite prompt bytes; a lowered TTL rebuilds only after normal idle expiry. 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).`),
@@ -5852,11 +5852,11 @@ var MagicContextConfigSchema = object({
     object({ default: number2().int().min(0).max(1e6).optional() }).catchall(number2().int().min(0).max(1e6))
   ]).optional().describe("Reasoning tokens to keep on rebuilding passes. Number or per-model object; exact, shorter model keys, provider/*, then default. Omitted: fixed 10,000. 0 removes all eligible historical reasoning; newest and exempt steps always stay."),
   history_budget_percentage: number2().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: number2().min(60000).default(DEFAULT_HISTORIAN_TIMEOUT_MS).describe("Timeout for each historian prompt call in both TypeScript and Rust transform modes, in milliseconds (default: 600000)"),
+  historian_timeout_ms: number2().min(60000).default(DEFAULT_HISTORIAN_TIMEOUT_MS).describe("Timeout for each historian prompt call in both TypeScript and Rust transform modes, in milliseconds (default: 600000). A historian setting kept at the top level for compatibility; no effect while historian.disable is true or compaction.enabled is false."),
   commit_cluster_trigger: object({
     enabled: boolean2().default(true).describe("Enable commit-cluster based historian triggering (default: true)"),
     min_clusters: number2().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"),
+  }).default({ enabled: true, min_clusters: 3 }).describe("Commit-cluster trigger: fire historian when enough commit clusters accumulate in the unsummarized tail. A historian setting kept at the top level for compatibility; no effect while historian.disable is true or compaction.enabled is false."),
   system_prompt_injection: object({
     enabled: boolean2().default(true).describe("When false, NO injection happens for ANY agent — global escape hatch. (default: true)"),
     skip_signatures: array(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.`)
@@ -5901,20 +5901,20 @@ var MagicContextConfigSchema = object({
     min_chars: number2().min(100).max(1e4).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: object({
-    enabled: boolean2().default(true).describe("Enable cross-session memory (default: true). Does not affect history embedding or semantic ctx_search over session history; set embedding.provider to 'off' to stop all embedding."),
+    enabled: boolean2().default(true).describe("Enable cross-session project memory (default: true). Also gates the dreamer's project-memory tasks: while false, map-memories, verify, verify-broad, curate, compress-cues, classify-memories, retrospective, promote-primers and refresh-primers neither run on schedule nor through /ctx-dream; maintain-docs, evaluate-smart-notes and review-user-memories still run. memory.auto_search and memory.git_commit_indexing do not depend on it. Does not affect history embedding or semantic ctx_search over session history; set embedding.provider to 'off' to stop all embedding."),
     injection_budget_tokens: number2().min(500).max(20000).default(4000).describe("Token budget for memory injection on session start (min: 500, max: 20000, default: 4000)"),
-    auto_promote: boolean2().default(true).describe("Automatically promote eligible session facts into memory (default: true)"),
-    retrieval_count_promotion_threshold: number2().min(1).default(3).describe("retrieval_count threshold for promoting memory to permanent status (min: 1, default: 3)"),
+    auto_promote: boolean2().default(true).describe("Automatically promote eligible session facts into memory (default: true). No effect while memory.enabled is false."),
+    retrieval_count_promotion_threshold: number2().min(1).default(3).describe("Currently has no effect: no code reads this value, and memories are not promoted to permanent by retrieval count. Kept so existing configs stay valid (min: 1, default: 3)."),
     auto_search: object({
-      enabled: boolean2().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."),
+      enabled: boolean2().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 despite its place under memory: with memory off it still searches past conversation and commits, only the memory source is skipped."),
       score_threshold: number2().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: number2().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 ctx_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, score_threshold: 0.6, min_prompt_chars: 20 }).describe("Auto-search hint: transform-time ctx_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 despite its place under memory: with memory off it still searches past conversation and commits."),
     git_commit_indexing: object({
-      enabled: boolean2().default(false).describe("Index HEAD git commits for ctx_search (git_commit source). Graduated from experimental.git_commit_indexing; opt-in, default off. Independent of memory.enabled."),
+      enabled: boolean2().default(false).describe("Index HEAD git commits for ctx_search (git_commit source). Graduated from experimental.git_commit_indexing; opt-in, default off. Independent of memory.enabled despite its place under memory."),
       since_days: number2().min(7).max(3650).default(365).describe("Days of HEAD history to index (min: 7, max: 3650, default: 365)"),
       max_commits: number2().min(100).max(20000).default(2000).describe("Max commits kept per project; oldest evicted (min: 100, max: 20000, default: 2000)")
-    }).default({ enabled: false, since_days: 365, max_commits: 2000 }).describe("Index git commit messages from HEAD into ctx_search. Commits become a 4th searchable source alongside memories and session history. Graduated from experimental.git_commit_indexing; opt-in, default off (per-project embedding cost). Independent of memory.enabled.")
+    }).default({ enabled: false, since_days: 365, max_commits: 2000 }).describe("Index git commit messages from HEAD into ctx_search. Commits become a 4th searchable source alongside memories and session history. Graduated from experimental.git_commit_indexing; opt-in, default off (per-project embedding cost). Independent of memory.enabled despite its place under memory.")
   }).default({
     enabled: true,
     injection_budget_tokens: 4000,
@@ -5922,7 +5922,7 @@ var MagicContextConfigSchema = object({
     retrieval_count_promotion_threshold: 3,
     auto_search: { enabled: true, score_threshold: 0.6, min_prompt_chars: 20 },
     git_commit_indexing: { enabled: false, since_days: 365, max_commits: 2000 }
-  }).describe("Cross-session memory configuration")
+  }).describe("Cross-session memory configuration. auto_search and git_commit_indexing sit here for history but work with memory.enabled false.")
 }).transform((data) => {
   return {
     ...data,
@@ -6001,4 +6001,4 @@ function deriveDefaultProtectedTokens(usableSoft) {
   return Math.min(64000, Math.max(lowerBound, target));
 }
 
-export { string, unknown, array, object, union, tuple, record, withContentLanguageDirective, buildPrimaryLanguageDirective, parseCron, nextOccurrence, nextDueAtMs, renderToolTemplate, promptSurfaceConfigIdentity, resolveModelConfigValue, resolvePromptSurface, DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE, DEFAULT_HISTORIAN_TIMEOUT_MS, PROTECTED_TOKENS_MIN, DEFAULT_LOCAL_EMBEDDING_MODEL, PER_HARNESS_MIGRATION_INVENTORY, PER_HARNESS_MODEL_KEYS, ConfigProfilesSchema, DREAM_TASK_PROMOTION_DEFAULTS, MagicContextConfigSchema, LIVE_RELOAD_CONFIG_PATHS, deriveDefaultProtectedTokens };
+export { string, unknown, array, object, union, tuple, record, isValidLanguageCode, withContentLanguageDirective, buildPrimaryLanguageDirective, parseCron, nextOccurrence, nextDueAtMs, renderToolTemplate, promptSurfaceConfigIdentity, resolveModelConfigValue, resolvePromptSurface, DEFAULT_EXECUTE_THRESHOLD_PERCENTAGE, DEFAULT_HISTORIAN_TIMEOUT_MS, PROTECTED_TOKENS_MIN, DEFAULT_LOCAL_EMBEDDING_MODEL, PER_HARNESS_MIGRATION_INVENTORY, PER_HARNESS_MODEL_KEYS, ConfigProfilesSchema, DREAM_TASK_PROMOTION_DEFAULTS, MagicContextConfigSchema, LIVE_RELOAD_CONFIG_PATHS, deriveDefaultProtectedTokens };