chainlesschain 0.166.126 → 0.166.128

package/src/data/changelog.json

@@ -1,6 +1,32 @@
 {
   "source": "CHANGELOG.md",
   "releases": [
+    {
+      "productVersion": null,
+      "cliVersion": "0.166.128",
+      "cliVersions": ["0.166.128"],
+      "date": "2026-10-27",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Fixed - cc CLI 0.166.128: goal verification, tool discovery and memory queries (candidate, 2026-10-27)",
+          "body": "- Bind default goal evaluation to tool and artifact evidence, and stop automatic continuation when a reliable goal checkpoint cannot be saved.\n- Share new-connection model recommendations and protocol-aware probes across CLI and IDE integrations; retain existing model aliases and per-conversation model overrides.\n- Improve multilingual MCP and Skills descriptor discovery. Add an opt-in compact MCP provider catalog while retaining the full host execution ceiling, permission checks and revoked-schema handling.\n- Avoid unnecessary Memory posting unions when a narrower filter is already available. Preserve ordering, pagination, scope/sink filters, disk verification and generation-bound caches.\n- Add explicit headless `--review-changes` for a one-shot completion review after successful write/edit changes, with subsequent repairs inside the existing request and cost budgets. Suppress provisional text/thinking deltas and do not append review after incomplete usage. Default off; self-review is not independent task acceptance.\n- Retain published child package pins. Publish only through GitHub Actions OIDC after exact-source Linux, Windows and macOS CLI CI and Strict Sandbox pass; publish paired IDEs and clients only after upstream public readback.\n- Keep real task and billing acceptance separate from local synthetic benchmarks. Cumulative acceptance remains 32/45; NOT_PAID_READY / NOT_ADMITTED / HOLD remain."
+        }
+      ]
+    },
+    {
+      "productVersion": null,
+      "cliVersion": "0.166.127",
+      "cliVersions": ["0.166.127"],
+      "date": "2026-10-27",
+      "title": "",
+      "sections": [
+        {
+          "heading": "Added - cc CLI 0.166.127: optional self-evolution controls (2026-10-27)",
+          "body": "- Default fresh installations and older automatically generated local deployments to self-evolution off. Share the boolean `evolution.enabled` setting across CLI, cc ui, VS Code and JetBrains; explicit false overrides inherited deployment environment variables, while absent settings preserve manually selected deployments.\n- Enable and disable through configuration or deployment commands, initialize the local signed runtime on explicit enable, and retain deployment and trust history when disabled. Require a restart for running Agent sessions and reread the setting for new UI model requests.\n- Keep ordinary Agent, ask, chat, session resume and UI intent confirmation available while off. Retain strict signature and evidence checks for enabled deployments and prevent unrelated configuration writes from changing an absent Evolution choice.\n- Add shared configuration documentation and regression coverage. CLI 0.166.127 is public through OIDC after exact-source three-OS CLI CI and Strict Sandbox. Public Open VSX 0.37.165 and JetBrains 0.4.182 recommend .127; archive readback passed. Child dependency pins are unchanged. Microsoft Marketplace remains unpublished.\n- Publish mobile and PC v5.0.3.142 from frozen source c9881a2b71 after verified CLI and IDE releases. Five-platform builds, 22 public assets and three desktop updater metadata sets passed verification. No new live model-task acceptance: 32/45 accepted, 13 unfinished; NOT_PAID_READY / NOT_ADMITTED / HOLD remain.\n- Require exact-source Linux, Windows and macOS CLI CI and Strict Sandbox before GitHub Actions OIDC publication and public package readback. Automatic candidate promotion remains HOLD; this switch does not start a full RRSI campaign or claim new live model-task acceptance."
+        }
+      ]
+    },
     {
       "productVersion": null,
       "cliVersion": "0.166.126",

package/src/gateways/ws/action-protocol.js

@@ -1,3 +1,5 @@
+import { resolveServerEvolutionFactory } from "../../lib/evolution/optional-ui-model-turn.js";
+
 // Track running cowork tasks for cancellation
 const _runningTasks = new Map();
 
@@ -54,7 +56,7 @@ export async function handleCoworkTask(server, id, ws, message) {
       files,
       cwd: server.projectRoot || process.cwd(),
       llmOptions: {},
-      evolutionCompositionFactory: server.evolutionCompositionFactory ?? null,
+      evolutionCompositionFactory: await resolveServerEvolutionFactory(server),
       signal: ac.signal,
       ...(message.mcpSessionId ? { mcpSessionId: message.mcpSessionId } : {}),
       ...(useParallel
@@ -205,8 +207,9 @@ export async function handleCoworkHistory(server, id, ws, message) {
 
 export async function handleCoworkTemplates(server, id, ws) {
   try {
-    const { getTemplatesForUI } =
-      await import("../../lib/cowork-task-templates.js");
+    const { getTemplatesForUI } = await import(
+      "../../lib/cowork-task-templates.js"
+    );
     const templates = getTemplatesForUI();
     server._send(ws, { id, type: "cowork:templates", templates });
   } catch (err) {
@@ -240,15 +243,16 @@ export async function handleOrchestrate(server, id, ws, message) {
   }
 
   try {
-    const { Orchestrator, TASK_SOURCE } =
-      await import("../../lib/orchestrator.js");
+    const { Orchestrator, TASK_SOURCE } = await import(
+      "../../lib/orchestrator.js"
+    );
 
     const orch = new Orchestrator({
       cwd: cwd || server.projectRoot || process.cwd(),
       maxParallel: Math.min(parseInt(agents, 10) || 3, 10),
       ciCommand: ci,
       agents: strategy ? { strategy } : undefined,
-      evolutionCompositionFactory: server.evolutionCompositionFactory ?? null,
+      evolutionCompositionFactory: await resolveServerEvolutionFactory(server),
       verbose: false,
     });
 
@@ -389,8 +393,9 @@ async function _resolveWorkflowExecutionAuthority(server, sessionId) {
     }
     provider = descriptor.value;
   } else {
-    ({ getVerifiedSessionExecutionLocationAuthority: provider } =
-      await import("../../harness/jsonl-session-store.js"));
+    ({ getVerifiedSessionExecutionLocationAuthority: provider } = await import(
+      "../../harness/jsonl-session-store.js"
+    ));
   }
   if (typeof provider !== "function") {
     const error = new Error(
@@ -507,8 +512,9 @@ export async function handleWorkflowSave(server, id, ws, message) {
     );
   }
   try {
-    const { getWorkflowRecord, validateWorkflow, saveWorkflow } =
-      await import("../../lib/cowork-workflow.js");
+    const { getWorkflowRecord, validateWorkflow, saveWorkflow } = await import(
+      "../../lib/cowork-workflow.js"
+    );
     const result = validateWorkflow(workflow);
     if (!result.valid) {
       return _sendError(
@@ -595,8 +601,9 @@ export async function handleWorkflowRun(server, id, ws, message) {
   try {
     const { getWorkflowRecord, getWorkflowVersion, executeWorkflow } =
       await import("../../lib/cowork-workflow.js");
-    const { executeDynamicWorkflowWithAdmission } =
-      await import("../../lib/dynamic-workflow-facade.js");
+    const { executeDynamicWorkflowWithAdmission } = await import(
+      "../../lib/dynamic-workflow-facade.js"
+    );
     let workflowRunTask;
     if (Object.hasOwn(server, "workflowRunTask")) {
       const descriptor = Object.getOwnPropertyDescriptor(
@@ -608,8 +615,9 @@ export async function handleWorkflowRun(server, id, ws, message) {
       }
       workflowRunTask = descriptor.value;
     } else {
-      ({ runCoworkTask: workflowRunTask } =
-        await import("../../lib/cowork-task-runner.js"));
+      ({ runCoworkTask: workflowRunTask } = await import(
+        "../../lib/cowork-task-runner.js"
+      ));
     }
     if (typeof workflowRunTask !== "function") {
       throw new Error("Workflow task runner is unavailable");

package/src/gateways/ws/chat-intent-protocol.js

@@ -17,6 +17,7 @@ import {
   classifyFollowupIntent,
 } from "../../lib/chat-intent-service.js";
 import { resolveLlmCreds } from "./llm-creds.js";
+import { resolveServerEvolutionFactory } from "../../lib/evolution/optional-ui-model-turn.js";
 
 /**
  * Look up LLM creds for the intent flow.
@@ -60,7 +61,8 @@ export async function handleChatIntentUnderstand(server, id, ws, message) {
       contextMode: message.contextMode || "global",
       history,
       llmOptions,
-      evolutionCompositionFactory: server.evolutionCompositionFactory ?? null,
+      evolutionCompositionFactory: await resolveServerEvolutionFactory(server),
+      prepareModelTurn: server.prepareUiModelTurn,
     });
     server._send(ws, {
       id,
@@ -118,7 +120,8 @@ export async function handleChatIntentUnderstandStream(
       contextMode: message.contextMode || "global",
       history,
       llmOptions,
-      evolutionCompositionFactory: server.evolutionCompositionFactory ?? null,
+      evolutionCompositionFactory: await resolveServerEvolutionFactory(server),
+      prepareModelTurn: server.prepareUiModelTurn,
     })) {
       if (event.type === "token") {
         server._send(ws, {
@@ -171,7 +174,8 @@ export async function handleChatIntentClassifyFollowup(
       input,
       context: message.context || {},
       llmOptions,
-      evolutionCompositionFactory: server.evolutionCompositionFactory ?? null,
+      evolutionCompositionFactory: await resolveServerEvolutionFactory(server),
+      prepareModelTurn: server.prepareUiModelTurn,
     });
     server._send(ws, {
       id,

package/src/gateways/ws/llm-chat-protocol.js

@@ -180,7 +180,14 @@ export async function handleLlmChat(server, id, ws, message) {
   ws?.once?.("close", disconnect);
   try {
     const turn = await waitForChatPhase(
-      prepareGovernedModelTurn(server.evolutionCompositionFactory ?? null, {
+      (
+        server.prepareUiModelTurn ||
+        ((context) =>
+          prepareGovernedModelTurn(
+            server.evolutionCompositionFactory ?? null,
+            context,
+          ))
+      )({
         mode: "ws-llm-chat",
         messages: message.messages,
         signal: controller.signal,
@@ -189,7 +196,7 @@ export async function handleLlmChat(server, id, ws, message) {
       "initialization",
     );
     const streamOptions = {
-      requireCompletion: turn.governed,
+      requireCompletion: true,
       signal: controller.signal,
     };
     // Tell the browser the configured deadline even when waiting hints are

package/src/gateways/ws/ws-server.js

@@ -124,10 +124,7 @@ import {
 } from "./artifact-protocol.js";
 import { executionBroker } from "../../lib/process-execution-broker/index.js";
 import { collectWorkspacePluginBinSandboxPolicy } from "../../lib/plugin-runtime/bin.js";
-import {
-  loadConfig,
-  loadUserConfig,
-} from "../../lib/config-manager.js";
+import { loadConfig, loadUserConfig } from "../../lib/config-manager.js";
 
 export const _deps = {
   spawn: (...args) => executionBroker.spawn(...args),
@@ -200,11 +197,9 @@ function boundedInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER) {
 }
 
 function loadCurrentLlmConfig() {
-  const savedLlm =
-    loadUserConfig({ failIfUnavailable: true }).llm || {};
+  const savedLlm = loadUserConfig({ failIfUnavailable: true }).llm || {};
   const resolvedLlm = loadConfig({ failIfUnavailable: true }).llm || {};
-  const confirmedLlm =
-    loadUserConfig({ failIfUnavailable: true }).llm || {};
+  const confirmedLlm = loadUserConfig({ failIfUnavailable: true }).llm || {};
   const provider =
     typeof savedLlm.provider === "string" && savedLlm.provider.trim()
       ? savedLlm.provider.trim()
@@ -378,6 +373,21 @@ export class ChainlessChainWSServer extends EventEmitter {
     }
     this.evolutionCompositionFactory =
       options.evolutionCompositionFactory || null;
+    if (
+      options.prepareUiModelTurn != null &&
+      typeof options.prepareUiModelTurn !== "function"
+    )
+      throw new TypeError("prepareUiModelTurn must be a function");
+    this.prepareUiModelTurn = options.prepareUiModelTurn || null;
+    if (
+      options.resolveEvolutionCompositionFactory != null &&
+      typeof options.resolveEvolutionCompositionFactory !== "function"
+    )
+      throw new TypeError(
+        "resolveEvolutionCompositionFactory must be a function",
+      );
+    this.resolveEvolutionCompositionFactory =
+      options.resolveEvolutionCompositionFactory || null;
     this.runtimeAdmissionDependencies =
       captureSkillRuntimeDependencies(options);
     this.skillOutcomeIndex =
@@ -827,8 +837,9 @@ export class ChainlessChainWSServer extends EventEmitter {
   /** Read the same static + scoped authority used by the Agent Core. */
   async _handlePermissionRulesGet(id, ws) {
     try {
-      const { loadPermissionAuthority } =
-        await import("../../lib/permission-authority.js");
+      const { loadPermissionAuthority } = await import(
+        "../../lib/permission-authority.js"
+      );
       const loaded = loadPermissionAuthority({ cwd: this.projectRoot });
       this._send(ws, {
         id,
@@ -1588,8 +1599,9 @@ export class ChainlessChainWSServer extends EventEmitter {
   /** @private — ping/pong heartbeat to detect dead connections */
   async _ensureTaskManager() {
     if (this._taskManager) return this._taskManager;
-    const { BackgroundTaskManager } =
-      await import("../../harness/background-task-manager.js");
+    const { BackgroundTaskManager } = await import(
+      "../../harness/background-task-manager.js"
+    );
     this._taskManager = new BackgroundTaskManager({
       recoverOnStart: true,
       policyCwd: this.projectRoot,

package/src/lib/bm25-search.js

@@ -129,11 +129,14 @@ export class BM25Search {
    * @param {number} [options.k1=1.5] - Term frequency saturation parameter
    * @param {number} [options.b=0.75] - Length normalization parameter
    * @param {string} [options.language="auto"] - Language for tokenization
+   * @param {function(string): string[]} [options.tokenizer] - Optional domain tokenizer
    */
   constructor(options = {}) {
     this.k1 = options.k1 || 1.5;
     this.b = options.b || 0.75;
     this.language = options.language || "auto";
+    this._tokenize =
+      options.tokenizer || ((text) => tokenize(text, this.language));
 
     // Index state
     this.documents = []; // Array of { id, tokens, originalDoc }
@@ -152,7 +155,7 @@ export class BM25Search {
 
     for (const doc of documents) {
       const text = [doc.title || "", doc.content || ""].join(" ");
-      const tokens = tokenize(text, this.language);
+      const tokens = this._tokenize(text);
 
       this.documents.push({
         id: doc.id,
@@ -183,7 +186,7 @@ export class BM25Search {
    */
   addDocument(doc) {
     const text = [doc.title || "", doc.content || ""].join(" ");
-    const tokens = tokenize(text, this.language);
+    const tokens = this._tokenize(text);
 
     this.documents.push({
       id: doc.id,
@@ -251,7 +254,7 @@ export class BM25Search {
 
     if (this.totalDocs === 0) return [];
 
-    const queryTokens = tokenize(query, this.language);
+    const queryTokens = this._tokenize(query);
     if (queryTokens.length === 0) return [];
 
     const scores = [];

package/src/lib/chat-intent-service.js

@@ -40,7 +40,13 @@ async function waitForIntentOperation(operation, signal) {
   }
 }
 
-async function* intentModelStream(messages, options, factory, mode) {
+async function* intentModelStream(
+  messages,
+  options,
+  factory,
+  mode,
+  prepareModelTurn,
+) {
   const controller = new AbortController();
   const timeoutMs = resolveIntentTimeout(options);
   const timer =
@@ -57,7 +63,10 @@ async function* intentModelStream(messages, options, factory, mode) {
   let completed = false;
   try {
     const turn = await waitForIntentOperation(
-      prepareGovernedModelTurn(factory, {
+      (
+        prepareModelTurn ||
+        ((context) => prepareGovernedModelTurn(factory, context))
+      )({
         mode,
         messages,
         signal: controller.signal,
@@ -87,13 +96,20 @@ async function* intentModelStream(messages, options, factory, mode) {
   }
 }
 
-async function intentModelText(messages, options, factory, mode) {
+async function intentModelText(
+  messages,
+  options,
+  factory,
+  mode,
+  prepareModelTurn,
+) {
   let content = "";
   for await (const event of intentModelStream(
     messages,
     options,
     factory,
     mode,
+    prepareModelTurn,
   )) {
     if (event.type === "response-complete") content = event.content;
   }
@@ -213,6 +229,7 @@ export async function understandIntent({
   history,
   llmOptions,
   evolutionCompositionFactory = null,
+  prepareModelTurn,
 }) {
   if (!userInput || !userInput.trim()) {
     throw new Error("userInput required");
@@ -249,6 +266,7 @@ export async function understandIntent({
       },
       evolutionCompositionFactory,
       "intent-understand",
+      prepareModelTurn,
     );
 
     const jsonText = extractJson(fullContent);
@@ -297,6 +315,7 @@ export async function* understandIntentStream({
   history,
   llmOptions,
   evolutionCompositionFactory = null,
+  prepareModelTurn,
 }) {
   if (!userInput || !userInput.trim()) {
     throw new Error("userInput required");
@@ -321,7 +340,7 @@ export async function* understandIntentStream({
   let buffer = "";
   try {
     // Every model-backed intent stream uses an abortable per-call deadline and
-    // authenticated composition; the rule-only path above stays local.
+    // host-selected Evolution policy; the rule-only path above stays local.
     for await (const event of intentModelStream(
       [
         { role: "system", content: systemPrompt },
@@ -330,6 +349,7 @@ export async function* understandIntentStream({
       { ...llmOptions, temperature: 0.3, maxTokens: 500 },
       evolutionCompositionFactory,
       "intent-understand-stream",
+      prepareModelTurn,
     )) {
       if (event.type === "response-token") {
         buffer += event.token;
@@ -575,6 +595,7 @@ async function llmBasedClassify(
   context,
   llmOptions,
   evolutionCompositionFactory,
+  prepareModelTurn,
 ) {
   const { systemPrompt, userPrompt } = buildFollowupPrompts(userInput, context);
   const fullContent = await intentModelText(
@@ -589,6 +610,7 @@ async function llmBasedClassify(
     },
     evolutionCompositionFactory,
     "intent-classify",
+    prepareModelTurn,
   );
   const jsonText = extractJson(fullContent);
   if (!jsonText) throw new Error("LLM response missing JSON");
@@ -618,6 +640,7 @@ export async function classifyFollowupIntent({
   context = {},
   llmOptions,
   evolutionCompositionFactory = null,
+  prepareModelTurn,
 }) {
   const startTime = Date.now();
   const ruleResult = ruleBasedClassify(input);
@@ -644,6 +667,7 @@ export async function classifyFollowupIntent({
       context,
       llmOptions,
       evolutionCompositionFactory,
+      prepareModelTurn,
     );
     return {
       ...llmResult,

package/src/lib/coding-task-guidance.js

@@ -3,7 +3,7 @@ export const CODING_TASK_QUALITY_GUIDANCE = `Coding task quality:
 - Read the actual implementation and its exported API before writing a caller or test. Check parameter order, return shapes, asynchronous lifecycle and fixture requirements against the source; an example in another directory can have different relative imports.
 - Keep progress explanations to one or two sentences. Once the relevant API and behavior are clear, make the next tool call; resolve a remaining uncertainty with a targeted read. Put implementation code directly in write/edit tool arguments instead of rehearsing the code or repeatedly analyzing the same source in ordinary assistant text.
 - Resolve each relative import from the destination file's directory. Read back the completed file and fix newDiagnostics from write/edit results before finishing. A successful write confirms persistence, not syntax, test execution or acceptance.
-- Regression tests need a working positive control and a negative control that exercises the requested behavior through the real production entry point. Assert observable effects; avoid mocks or alternate calls that bypass the behavior under test. Complete the current worker/request when testing cancellation and replacement.
+- Before finishing a regression task, map each explicit acceptance requirement to a concrete fixture, production call path and observable assertion in the deliverable. Positive and negative controls must exercise the same requested behavior and differ in the intended condition. Resolve uncovered requirements with permitted tools, or report the specific gap. Avoid mocks or alternate calls that bypass the behavior under test. Complete the current worker/request when testing cancellation and replacement.
 - For boundary regressions, derive expected defaults, computed values and rejection rules from the implementation or the explicit requested contract. Inject mismatched, tampered or stale input through the real entry point while keeping other prerequisites valid; verify that the fixture reaches the intended check rather than failing during setup. Compare observable results with independent expected values or authoritative state, not a helper that merely recomputes the same result.
 - Trace rejection before asserting its aftermath: a request can be rejected before registration or persistence. Check whether state stays unchanged, a failed record is saved, or an event is emitted; do not assume every rejection creates a failed task. When testing attribution, verify independently recorded identities and provenance as well as message contents; identical text can still be attributed to the wrong source.
 - Use available execution tools for a focused check when permitted. When execution tools are unavailable, inspect imports, API contracts and fixtures using the available file tools, and clearly say that tests were not run. Never describe a read-back or static check as a passing test or end-to-end verification.
@@ -14,3 +14,8 @@ export const HERMETIC_CODING_SYSTEM_PROMPT = `You are a hermetic coding assistan
 ${CODING_TASK_QUALITY_GUIDANCE}
 
 Return a concise, evidence-based completion message within these tool limits.`;
+
+/** Optional runtime follow-up; contains no task-specific acceptance information. */
+export const CODING_CHANGE_REVIEW_PROMPT = `Runtime change review: the original user task, authorized scope, tools and remaining budgets still apply; this message grants no new permissions.
+Before finishing, check the changed deliverable against each explicit requirement. For regression tests, identify the concrete fixture, actual production call path and observable assertion for each requirement. Confirm that positive and negative controls reach the intended behavior with valid prerequisites and differ in the intended condition. Similar field names and unrelated rejection paths do not establish coverage.
+Use permitted tools to inspect and repair any gap. Run focused checks only when execution tools are available. If a requirement remains uncovered or a check cannot be run, report that specific limitation. This review is not evidence that tests or independent acceptance passed. Give a concise final answer when finished.`;

package/src/lib/config-manager.js

@@ -30,6 +30,16 @@ import {
 // `_deps.warn` to assert it fired.
 const _warnedConfigPaths = new Set();
 const _loadedSecretRefs = new Map();
+const _implicitEvolutionDefaults = new WeakSet();
+
+function trackImplicitEvolutionDefault(config, raw = {}) {
+  if (
+    raw.evolution?.enabled === undefined &&
+    config.evolution?.enabled === false
+  )
+    _implicitEvolutionDefaults.add(config.evolution);
+  return config;
+}
 export const _deps = {
   createSecretStore: () => createSecretStore(),
   warn: (msg) => {
@@ -72,8 +82,11 @@ function assertNotSymbolicLink(target, label = "configuration path") {
   return stat;
 }
 
-function readConfigDocument({ failIfUnavailable = false } = {}) {
-  const configPath = getConfigPath();
+function readConfigDocument({
+  failIfUnavailable = false,
+  ...pathOptions
+} = {}) {
+  const configPath = getConfigPath(pathOptions);
   if (!existsSync(configPath)) return {};
   try {
     assertNotSymbolicLink(configPath, "config.json");
@@ -182,9 +195,9 @@ function resolveSecretReferences(value, prefix = "", state = {}) {
   return value;
 }
 
-function restoreSecretReferences(config) {
+function restoreSecretReferences(config, configPath = getConfigPath()) {
   const out = structuredClone(config);
-  const prefix = `${getConfigPath()}\0`;
+  const prefix = `${configPath}\0`;
   for (const [cacheKey, saved] of _loadedSecretRefs) {
     if (!cacheKey.startsWith(prefix)) continue;
     const key = cacheKey.slice(prefix.length);
@@ -199,17 +212,21 @@ function restoreSecretReferences(config) {
 export function loadConfig({
   failIfUnavailable = false,
   resolveSecrets = true,
+  ...pathOptions
 } = {}) {
-  const configPath = getConfigPath();
+  const configPath = getConfigPath(pathOptions);
   if (!existsSync(configPath)) {
-    return { ...structuredClone(DEFAULT_CONFIG) };
+    return trackImplicitEvolutionDefault(structuredClone(DEFAULT_CONFIG));
   }
   try {
-    const parsed = readConfigDocument({ failIfUnavailable });
+    const parsed = readConfigDocument({ ...pathOptions, failIfUnavailable });
     const effective = deepMerge(structuredClone(DEFAULT_CONFIG), parsed);
-    return resolveSecrets
-      ? resolveSecretReferences(effective, "", { configPath })
-      : effective;
+    return trackImplicitEvolutionDefault(
+      resolveSecrets
+        ? resolveSecretReferences(effective, "", { configPath })
+        : effective,
+      parsed,
+    );
   } catch (err) {
     if (failIfUnavailable) {
       const error = new Error(
@@ -255,12 +272,12 @@ export function loadConfig({
           `Fix the JSON to restore them.${backupNote}\n`,
       );
     }
-    return { ...structuredClone(DEFAULT_CONFIG) };
+    return trackImplicitEvolutionDefault(structuredClone(DEFAULT_CONFIG));
   }
 }
 
 export function saveConfig(config, options = {}) {
-  const configPath = getConfigPath();
+  const configPath = getConfigPath(options);
   ensurePrivateDirectory(dirname(configPath), {
     applyWindowsAcl: true,
     failIfUnavailable: true,
@@ -276,7 +293,18 @@ export function saveConfig(config, options = {}) {
     const persisted =
       options.preserveSecretRefs === false
         ? structuredClone(config)
-        : restoreSecretReferences(config);
+        : restoreSecretReferences(config, configPath);
+    // An inherited default must not become an explicit opt-out when unrelated
+    // settings are saved. Track the child object so top-level spreads preserve
+    // this distinction too; explicit writes via setConfigValue clear it.
+    if (
+      _implicitEvolutionDefaults.has(config.evolution) &&
+      persisted.evolution?.enabled === false
+    ) {
+      delete persisted.evolution.enabled;
+      if (Object.keys(persisted.evolution).length === 0)
+        delete persisted.evolution;
+    }
     assertSafeConfigObject(persisted);
     writeFileSync(tmp, JSON.stringify(persisted, null, 2) + "\n", {
       encoding: "utf-8",
@@ -390,7 +418,7 @@ export function setConfigValue(key, value, options = {}) {
   // `cc config set` invocations would otherwise each load, mutate, and write
   // back, silently losing one update. Configuration can carry credentials and
   // permission policy, so bounded lock failure must never write unlocked.
-  const configPath = getConfigPath();
+  const configPath = getConfigPath(options);
   ensurePrivateDirectory(dirname(configPath), {
     applyWindowsAcl: true,
     failIfUnavailable: true,
@@ -398,9 +426,14 @@ export function setConfigValue(key, value, options = {}) {
   return withFileLock(
     configPath,
     () => {
-      const config = loadConfig({ failIfUnavailable: true });
+      const config = loadConfig({
+        ...options,
+        failIfUnavailable: true,
+      });
       setNestedValue(config, key, parsedValue);
-      saveConfig(config);
+      if (key === "evolution.enabled")
+        _implicitEvolutionDefaults.delete(config.evolution);
+      saveConfig(config, options);
       return config;
     },
     { failIfUnavailable: true },

package/src/lib/config-schema.js

@@ -22,6 +22,11 @@ const descriptor = (key, type, options = {}) => ({
 });
 
 const DESCRIPTORS = [
+  descriptor("evolution.enabled", "boolean", {
+    default: DEFAULT_CONFIG.evolution.enabled,
+    description:
+      "Enable optional self-evolution for new Agent sessions (off by default)",
+  }),
   descriptor("setupCompleted", "boolean", {
     default: DEFAULT_CONFIG.setupCompleted,
     description: "Whether initial CLI setup has completed",

package/src/lib/context-memory-kernel/memory-query-index.js

@@ -125,31 +125,49 @@ export function matchesListQuery(row, query) {
 // before applying the remaining predicates; no full-record scan or top-k before
 // permission filtering. Recall uses these gates but retains kernel ranking.
 export function* selectQueryRows(index, query, after = null) {
-  const candidates = [];
-  const union = (field, keys) => {
+  let positions = null;
+  let shortest = index.rows.length;
+  const unions = [];
+  const consider = (posting) => {
+    if (posting.length < shortest) {
+      positions = posting;
+      shortest = posting.length;
+    }
+  };
+  const considerUnion = (field, keys) => {
     const lists = keys
       .map((key) => index.postings[field].get(key))
       .filter(Boolean);
-    return lists.length < 2
-      ? lists[0] || []
-      : [...new Set(lists.flat())].sort((a, b) => a - b);
+    if (lists.length < 2) consider(lists[0] || []);
+    else unions.push(lists);
   };
   if (query.category)
-    candidates.push(index.postings.category.get(query.category) || []);
+    consider(index.postings.category.get(query.category) || []);
   if (query.scopeAdmissions)
-    candidates.push(
-      union(
-        "scope",
-        query.scopeAdmissions.map((scope) =>
-          scopeKey(scope.scope, scope.scopeId),
-        ),
+    considerUnion(
+      "scope",
+      query.scopeAdmissions.map((scope) =>
+        scopeKey(scope.scope, scope.scopeId),
       ),
     );
-  if (query.states) candidates.push(union("state", query.states));
-  if (query.tags?.length) candidates.push(union("tag", query.tags));
-  if (query.sink) candidates.push(union("sink", ["*", query.sink]));
-  candidates.sort((a, b) => a.length - b.length);
-  const positions = candidates[0];
+  if (query.states) considerUnion("state", query.states);
+  if (query.tags?.length) considerUnion("tag", query.tags);
+  if (query.sink) considerUnion("sink", ["*", query.sink]);
+  // A union cannot be shorter than its longest constituent. Inspect lengths
+  // before expanding broad permissions/tags when a selective posting exists.
+  // Stop building a union as soon as it cannot improve the current choice.
+  nextUnion: for (const lists of unions) {
+    if (shortest === 0) return;
+    if (lists.some((list) => list.length >= shortest)) continue;
+    const unique = new Set();
+    for (const list of lists) {
+      for (const position of list) {
+        unique.add(position);
+        if (unique.size >= shortest) continue nextUnion;
+      }
+    }
+    consider([...unique].sort((a, b) => a - b));
+  }
   const length = positions ? positions.length : index.rows.length;
   const rowAt = (offset) => index.rows[positions ? positions[offset] : offset];
   let start = 0;