memorix 1.5.1 → 1.6.1

package/dist/cli/index.js

@@ -2,7 +2,18 @@
 import {spawnSync as __ms} from "node:child_process";
 import {fileURLToPath as __fu} from "node:url";
 if(!process.env.__MEMORIX_HEAP){process.env.__MEMORIX_HEAP="1";
-let r=__ms(process.execPath,["--max-old-space-size=4096",__fu(import.meta.url),...process.argv.slice(2)],{stdio:"inherit",env:process.env,windowsHide:true});
+const __args=process.argv.slice(2);
+let __cmd;
+for(let __i=0;__i<__args.length;__i++){
+const __a=__args[__i];
+if(__a==="--")break;
+if(__a.startsWith("-")){if(!__a.includes("=")&&__args[__i+1]&&!__args[__i+1].startsWith("-"))__i++;continue;}
+__cmd=__a;break;}
+const __fallback=__cmd==="hook"?512:4096;
+const __raw=__cmd==="hook"?process.env.MEMORIX_HOOK_HEAP_MB:process.env.MEMORIX_HEAP_MB;
+const __n=Number(__raw);
+const __heap=(Number.isFinite(__n)&&__n>=64&&__n<=16384)?String(Math.floor(__n)):String(__fallback);
+let r=__ms(process.execPath,["--max-old-space-size="+__heap,__fu(import.meta.url),...process.argv.slice(2)],{stdio:"inherit",env:process.env,windowsHide:true});
 process.exit(r.status??1);}
 import {createRequire as __memorix_cjsRequire} from "module";
 const require = __memorix_cjsRequire(import.meta.url);
@@ -3221,7 +3232,7 @@ ${import_picocolors.default.gray(m3)}  ${s4}
 
 // src/cli/version.ts
 function getCliVersion() {
-  return true ? "1.5.1" : pkg.version;
+  return true ? "1.6.1" : pkg.version;
 }
 var init_version = __esm({
   "src/cli/version.ts"() {
@@ -3231,7 +3242,7 @@ var init_version = __esm({
 });
 
 // src/cli/invocation.ts
-import { existsSync as existsSync2, statSync } from "fs";
+import { existsSync as existsSync2, realpathSync, statSync } from "fs";
 import { resolve as resolve2 } from "path";
 function readOption(argument) {
   const equals = argument.indexOf("=");
@@ -3261,10 +3272,11 @@ function normalizeCliInvocation(argv2 = process.argv) {
     if (inlineValue === void 0) index += 1;
   }
   if (invocation.projectRoot) {
-    const projectRoot = resolve2(invocation.projectRoot);
-    if (!existsSync2(projectRoot) || !statSync(projectRoot).isDirectory()) {
-      throw new Error(`CLI project directory does not exist: ${projectRoot}`);
+    const resolvedProjectRoot = resolve2(invocation.projectRoot);
+    if (!existsSync2(resolvedProjectRoot) || !statSync(resolvedProjectRoot).isDirectory()) {
+      throw new Error(`CLI project directory does not exist: ${resolvedProjectRoot}`);
     }
+    const projectRoot = realpathSync(resolvedProjectRoot);
     process.chdir(projectRoot);
     process.env.MEMORIX_CLI_PROJECT_ROOT = projectRoot;
     invocation.projectRoot = projectRoot;
@@ -22778,6 +22790,7 @@ __export(provider_exports, {
   MAX_INLINE_EMBEDDING_BYTES: () => MAX_INLINE_EMBEDDING_BYTES,
   UnsupportedEmbeddingModalityError: () => UnsupportedEmbeddingModalityError,
   getEmbeddingProvider: () => getEmbeddingProvider,
+  getEmbeddingRuntimeHealth: () => getEmbeddingRuntimeHealth,
   isEmbeddingExplicitlyDisabled: () => isEmbeddingExplicitlyDisabled,
   isVectorSearchAvailable: () => isVectorSearchAvailable,
   resetProvider: () => resetProvider,
@@ -22885,13 +22898,36 @@ function isTemporaryEmbeddingFailure(error40) {
   if (!(error40 instanceof Error)) return false;
   return /embedding api error \(401\)/i.test(error40.message) || /invalid_api_key/i.test(error40.message) || /incorrect api key/i.test(error40.message) || /unauthorized/i.test(error40.message) || /embedding api timeout/i.test(error40.message) || /embedding api error \((402|429|5\d\d)\)/i.test(error40.message) || /quota exceeded/i.test(error40.message) || /account balance/i.test(error40.message) || /fetch failed/i.test(error40.message) || /econnreset/i.test(error40.message) || /econnrefused/i.test(error40.message) || /temporarily unavailable/i.test(error40.message);
 }
+function classifyEmbeddingFailure(error40) {
+  const message = error40 instanceof Error ? error40.message : String(error40);
+  if (/embedding api error \(401\)|invalid_api_key|incorrect api key|unauthorized/i.test(message)) {
+    return "authorization";
+  }
+  if (/embedding api error \(402\)|quota exceeded|account balance/i.test(message)) {
+    return "billing";
+  }
+  if (/embedding api timeout|abort/i.test(message)) {
+    return "timeout";
+  }
+  return "upstream";
+}
 function markTemporaryFailure(reason) {
   provider = null;
   initPromise = null;
   lastInitWasTemporaryFailure = true;
   lastFailureTimestamp = Date.now();
+  lastEmbeddingFailure = {
+    kind: classifyEmbeddingFailure(reason),
+    occurredAt: lastFailureTimestamp
+  };
   const message = reason instanceof Error ? reason.message : String(reason);
-  warnOnce(`[memorix] Embedding provider temporarily unavailable at runtime: ${message}`);
+  warnOnce(`[memorix] Embedding provider unavailable at runtime: ${message}`);
+}
+function markProviderReady(candidate2) {
+  provider = wrapProvider(candidate2);
+  lastInitWasTemporaryFailure = false;
+  lastEmbeddingFailure = null;
+  return provider;
 }
 async function createFastEmbedProvider() {
   try {
@@ -23007,35 +23043,35 @@ async function getEmbeddingProvider(options = {}) {
     if (mode === "fastembed") {
       const initialized = await createFastEmbedProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
     if (mode === "transformers") {
       const initialized = await createTransformersProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
     if (mode === "api") {
       const initialized = await createAPIProvider(options);
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
     if (hasAPIEmbeddingConfig()) {
       const initialized = await createAPIProvider(options);
       if (initialized) {
-        provider = wrapProvider(initialized);
+        provider = markProviderReady(initialized);
         warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
         return provider;
       }
     }
     const localFallback = await createLocalFallbackProvider();
     if (localFallback) {
-      provider = wrapProvider(localFallback);
+      provider = markProviderReady(localFallback);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -23057,6 +23093,27 @@ async function isVectorSearchAvailable() {
   const p3 = await getEmbeddingProvider();
   return p3 !== null;
 }
+function getEmbeddingRuntimeHealth() {
+  const mode = getEmbeddingMode2();
+  if (mode === "off") return { status: "disabled" };
+  if (lastInitWasTemporaryFailure && lastEmbeddingFailure) {
+    return {
+      status: "degraded",
+      failure: {
+        kind: lastEmbeddingFailure.kind,
+        occurredAt: new Date(lastEmbeddingFailure.occurredAt).toISOString(),
+        retryAfterMs: Math.max(0, RETRY_COOLDOWN_MS - (Date.now() - lastEmbeddingFailure.occurredAt))
+      }
+    };
+  }
+  if (provider) {
+    return {
+      status: "ready",
+      provider: { name: provider.name, dimensions: provider.dimensions }
+    };
+  }
+  return { status: "uninitialized" };
+}
 function isEmbeddingExplicitlyDisabled() {
   return getEmbeddingMode2() === "off";
 }
@@ -23065,10 +23122,11 @@ function resetProvider() {
   initPromise = null;
   lastInitWasTemporaryFailure = false;
   lastFailureTimestamp = 0;
+  lastEmbeddingFailure = null;
   lastEmbeddingWarning = "";
   lastEmbeddingWarningAt = 0;
 }
-var EmbeddingInputError, UnsupportedEmbeddingModalityError, MAX_INLINE_EMBEDDING_BYTES, provider, initPromise, lastInitWasTemporaryFailure, lastEmbeddingWarning, lastEmbeddingWarningAt, WARNING_COOLDOWN_MS, RETRY_COOLDOWN_MS, lastFailureTimestamp;
+var EmbeddingInputError, UnsupportedEmbeddingModalityError, MAX_INLINE_EMBEDDING_BYTES, provider, initPromise, lastInitWasTemporaryFailure, lastEmbeddingFailure, lastEmbeddingWarning, lastEmbeddingWarningAt, WARNING_COOLDOWN_MS, RETRY_COOLDOWN_MS, lastFailureTimestamp;
 var init_provider = __esm({
   "src/embedding/provider.ts"() {
     "use strict";
@@ -23093,6 +23151,7 @@ var init_provider = __esm({
     provider = null;
     initPromise = null;
     lastInitWasTemporaryFailure = false;
+    lastEmbeddingFailure = null;
     lastEmbeddingWarning = "";
     lastEmbeddingWarningAt = 0;
     WARNING_COOLDOWN_MS = 3e4;
@@ -182078,6 +182137,7 @@ var init_task_lens = __esm({
 var workflows_exports = {};
 __export(workflows_exports, {
   WORKFLOW_ADAPTER_TARGETS: () => WORKFLOW_ADAPTER_TARGETS,
+  WORKFLOW_AGENT_TARGETS: () => WORKFLOW_AGENT_TARGETS,
   applyWorkflowAdapter: () => applyWorkflowAdapter,
   importWindsurfWorkflows: () => importWindsurfWorkflows,
   parseWorkflowMarkdown: () => parseWorkflowMarkdown,
@@ -182143,7 +182203,7 @@ function optionalStatus(data) {
   return value;
 }
 function normalizeAgents(values) {
-  const unknown2 = values.filter((value) => !KNOWN_AGENTS.includes(value));
+  const unknown2 = values.filter((value) => !WORKFLOW_AGENT_TARGETS.includes(value));
   if (unknown2.length > 0) {
     throw new Error("workflow frontmatter has unsupported agent: " + unknown2[0]);
   }
@@ -182419,7 +182479,7 @@ function taskScore(workflow, task) {
   return { score, reasons: [...new Set(reasons)] };
 }
 function selectWorkflows(input) {
-  const selected = input.workflows.filter((workflow) => workflow.status === "active").map((workflow) => {
+  const selected = input.workflows.filter((workflow) => workflow.status === "active" && (!input.agent || workflow.compatibleAgents.includes(input.agent))).map((workflow) => {
     const match2 = taskScore(workflow, input.task);
     const cautions = input.store && input.projectId ? input.store.recentFailureCautions(input.projectId, workflow.id) : [];
     return {
@@ -182699,7 +182759,7 @@ async function selectWorkspaceWorkflows(input) {
     errors: synced.errors
   };
 }
-var KNOWN_AGENTS, WORKFLOW_ADAPTER_TARGETS, STATUS_VALUES, LENS_TERMS, GENERIC_WORKFLOW_LENSES, GENERIC_WORKFLOW_TERMS;
+var WORKFLOW_AGENT_TARGETS, WORKFLOW_ADAPTER_TARGETS, STATUS_VALUES, LENS_TERMS, GENERIC_WORKFLOW_LENSES, GENERIC_WORKFLOW_TERMS;
 var init_workflows2 = __esm({
   "src/knowledge/workflows.ts"() {
     "use strict";
@@ -182711,7 +182771,7 @@ var init_workflows2 = __esm({
     init_workflow_store();
     init_outcome_store();
     init_task_lens();
-    KNOWN_AGENTS = [
+    WORKFLOW_AGENT_TARGETS = [
       "windsurf",
       "cursor",
       "claude-code",
@@ -191131,8 +191191,8 @@ var init_official_skills = __esm({
           "",
           "| Situation | Prefer | CLI fallback |",
           "|---|---|---|",
-          '| Starting a coding task and needing the best task-lensed project map | `memorix_project_context` with the user\'s task | `memorix context "<task>" --json` |',
-          '| Continuing prior project work | `memorix_project_context` with the user\'s task | `memorix resume "<task>" --json` |',
+          '| Starting a coding task and needing the best task-lensed project map | `memorix_project_context` with the user\'s task | `memorix context "<task>" --brief-json` |',
+          '| Continuing prior project work | `memorix_project_context` with the user\'s task | `memorix resume "<task>" --brief-json` |',
           '| Need structured refs/freshness for code-bound memories | `memorix_context_pack` | `memorix codegraph context-pack --task "<topic>"` |',
           '| Explicit memory graph question | `memorix_graph_context` | `memorix memory graph-context --query "<topic>"` |',
           '| Specific past decision, bug, file, or change | `memorix_search` | `memorix memory search --query "<topic>"` |',
@@ -191145,7 +191205,7 @@ var init_official_skills = __esm({
           "",
           "- Default first step for non-trivial coding work: call `memorix_project_context` before progress files, dev-log reads, ad-hoc file reads, or git archaeology. Pass the user's actual task so Memorix can choose a bugfix, feature, release, onboarding, refactor, docs, test, or general brief. Start by reading its suggested files.",
           "- In Claude Code headless/print-mode, an initial MCP `pending` status is not a failure by itself. Prefer MCP first: use the client's tool discovery/dynamic loading to find `memorix_project_context` when it is not in the first visible tool list.",
-          '- Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run `memorix resume "<task>" --json` exactly once before inspecting files, Git history, progress notes, or guessing. The absence of `.memorix` or visible memory files never proves project memory is empty. For a new task, use `memorix context "<task>" --json` instead. If that one command fails, report it and proceed normally; do not probe help, enumerate commands, or chain broad searches.',
+          '- Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run `memorix resume "<task>" --brief-json` exactly once before inspecting files, Git history, progress notes, or guessing. The absence of `.memorix` or visible memory files never proves project memory is empty. For a new task, use `memorix context "<task>" --brief-json` instead. Use `--json` only when a diagnostic needs the detailed legacy payload. If that one command fails, report it and proceed normally; do not probe help, enumerate commands, or chain broad searches.',
           "- After a successful `memorix_project_context`, the brief is the default retrieval boundary. Do not call more Memorix retrieval tools after a complete brief. Use Context Pack, search, or detail only when the brief lacks a specific reference, freshness field, or fact needed for the task, or when the user explicitly asks for deeper history. In MCP, name that missing fact in `purpose` when intentionally expanding beyond the brief. Do not retrieve the same decision twice just to confirm an already-complete brief.",
           "- If the user asks for read-only work or says not to modify files, do not call `memorix_store` just to record an assessment. Store only when the user explicitly asks to preserve it.",
           "- Use `memorix_search` for a specific decision, bug, file, or prior change that the project context did not answer. Fetch detail only for a result you still need after the brief.",
@@ -192404,7 +192464,7 @@ alwaysApply: true
     "",
     `Default first step for non-trivial coding work: call \`memorix_project_context\` with the user's actual task before progress files, dev-log reads, ad-hoc file reads, or git archaeology. Memorix will choose a task-lensed brief (bugfix, feature, release, onboarding, refactor, docs, test, or general). When the task is continuing prior work, the same brief also includes a bounded prior-work projection. Treat its "Start here" files as the first ${contextNoun} files to inspect.`,
     "",
-    'If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select `memorix_project_context` first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user\'s real task before inspecting files, Git history, progress notes, or guessing: `memorix resume "<task>" --json`. For a new task, use `memorix context "<task>" --json` instead. The absence of `.memorix` or visible memory files never proves project memory is empty. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax.',
+    'If the MCP tool is not visible yet but the client supports tool discovery or dynamic loading, search/select `memorix_project_context` first. Continuation fallback is mandatory: when the user asks to continue, resume, take over, or explain prior work and MCP cannot be called in this turn, run exactly one CLI brief with the user\'s real task before inspecting files, Git history, progress notes, or guessing: `memorix resume "<task>" --brief-json`. For a new task, use `memorix context "<task>" --brief-json` instead. The absence of `.memorix` or visible memory files never proves project memory is empty. Use `--json` only when a diagnostic needs the detailed legacy payload. If that one command fails, report it and proceed normally. Do not probe help, enumerate commands, chain broad searches, wait indefinitely on MCP startup, or hand-write tool-call syntax.',
     "",
     "After a successful `memorix_project_context` result, the brief is the default retrieval boundary. Do not call more Memorix retrieval tools after a complete brief. Use `memorix_context_pack`, `memorix_search`, or `memorix_detail` only when the brief lacks a specific reference, freshness field, or fact needed for the task, or when the user explicitly asks for deeper history. In MCP, name that missing fact in `purpose` when intentionally expanding beyond the brief. Do not retrieve the same decision twice just to confirm an already-complete brief.",
     "If the user asks for read-only work or says not to modify files, do not call `memorix_store` just to record an assessment. Store only when the user explicitly asks to preserve it.",
@@ -194446,6 +194506,15 @@ function workflowOutput(selection) {
     cautions: selection.cautions.map((caution) => short(caution, 22))
   };
 }
+function workflowLoadout(agent, selections) {
+  if (!agent) return void 0;
+  return {
+    agent,
+    workflowIds: selections.map((selection) => selection.workflow.id),
+    requiredContext: unique(selections.flatMap((selection) => selection.workflow.requiredContext)).map((item) => short(item, 18)).slice(0, 4),
+    allowedTools: unique(selections.flatMap((selection) => selection.workflow.allowedTools)).map((item) => short(item, 12)).slice(0, 6)
+  };
+}
 function appendLine(lines, candidate2, maxTokens, omitted, omittedKind, selected, receiptSelection) {
   const next = lines.length ? lines.join("\n") + "\n" + candidate2 : candidate2;
   if (countTextTokens(next) <= maxTokens) {
@@ -194906,6 +194975,22 @@ function renderTaskWorksetPrompt(input) {
       );
     }
   }
+  if (input.agentLoadout) {
+    appendLine(lines, "", maxTokens, omitted, "agent-loadout-heading");
+    appendLine(lines, "Agent loadout (" + input.agentLoadout.agent + ")", maxTokens, omitted, "agent-loadout-heading");
+    for (const required2 of input.agentLoadout.requiredContext.slice(0, 2)) {
+      appendLine(lines, "- Need: " + required2, maxTokens, omitted, "agent-loadout-context");
+    }
+    if (input.agentLoadout.allowedTools.length > 0) {
+      appendLine(
+        lines,
+        "- Workflow tools: " + input.agentLoadout.allowedTools.join(", "),
+        maxTokens,
+        omitted,
+        "agent-loadout-tools"
+      );
+    }
+  }
   if (input.verification.length > 0) {
     appendLine(lines, "", maxTokens, omitted, "verification-heading");
     appendLine(lines, "Verify", maxTokens, omitted, "verification-heading");
@@ -194997,6 +195082,7 @@ async function buildTaskWorkset(input) {
   let workspace;
   let pages = [];
   let workflows = [];
+  let workflowSelections = [];
   try {
     workspace = await preferredWorkspace(input.projectId, input.dataDir);
     if (workspace) {
@@ -195013,14 +195099,15 @@ async function buildTaskWorkset(input) {
       if (task) {
         const workflowStore = new WorkflowStore();
         await workflowStore.init(input.dataDir);
-        const selected = selectWorkflows({
+        workflowSelections = selectWorkflows({
           workflows: workflowStore.listWorkflows(workspace.id, "active"),
           task,
           projectId: input.projectId,
           store: workflowStore,
+          ...input.agent ? { agent: input.agent } : {},
           limit: 2
         });
-        workflows = selected.map(workflowOutput);
+        workflows = workflowSelections.map(workflowOutput);
         for (const workflow of workflows) {
           for (const caution of workflow.cautions) {
             cautions.push({ kind: "workflow-failed-verification", message: caution });
@@ -195042,6 +195129,10 @@ async function buildTaskWorkset(input) {
     workflows
   });
   const governedDurableIds = new Set(governed.durableMemory.map((memory) => memory.id));
+  const agentLoadout = workflowLoadout(
+    input.agent,
+    workflowSelections.filter((selection2) => governed.workflows.some((workflow) => workflow.id === selection2.workflow.id))
+  );
   const evidenceIds = unique(governed.claims.flatMap((claim) => evidenceIdsForClaim(
     claim,
     evidenceByClaim.get(claim.id) ?? []
@@ -195086,6 +195177,7 @@ async function buildTaskWorkset(input) {
     pages: pages.filter((page) => page.claimIds.some((claimId) => governed.claims.some((claim) => claim.id === claimId))),
     durableMemory: governed.durableMemory,
     workflows: governed.workflows,
+    ...agentLoadout ? { agentLoadout } : {},
     cautions: normalizedCautions,
     verification,
     evidenceIds,
@@ -195304,10 +195396,12 @@ var init_current_facts = __esm({
 var external_provider_exports = {};
 __export(external_provider_exports, {
   DEFAULT_EXTERNAL_CODEGRAPH_TIMEOUT_MS: () => DEFAULT_EXTERNAL_CODEGRAPH_TIMEOUT_MS,
+  EXTERNAL_CODEGRAPH_LIFECYCLE_TIMEOUT_MS: () => EXTERNAL_CODEGRAPH_LIFECYCLE_TIMEOUT_MS,
   MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES: () => MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES,
   MAX_EXTERNAL_CODEGRAPH_TIMEOUT_MS: () => MAX_EXTERNAL_CODEGRAPH_TIMEOUT_MS,
   getExternalCodeGraphContext: () => getExternalCodeGraphContext,
-  inspectExternalCodeGraph: () => inspectExternalCodeGraph
+  inspectExternalCodeGraph: () => inspectExternalCodeGraph,
+  runExternalCodeGraphLifecycle: () => runExternalCodeGraphLifecycle
 });
 import { spawn as spawn5 } from "child_process";
 import { existsSync as existsSync16, readFileSync as readFileSync9 } from "fs";
@@ -195506,6 +195600,66 @@ async function inspectExternalCodeGraph(input) {
   const health = healthFromStatus(status);
   return { health, quality: providerQuality({ mode, health }) };
 }
+async function runExternalCodeGraphLifecycle(input) {
+  const mode = input.mode ?? "auto";
+  if (mode === "off") {
+    const health = { state: "disabled", reason: "External CodeGraph is disabled by configuration." };
+    return {
+      action: input.action,
+      performed: false,
+      message: "External CodeGraph is disabled by configuration.",
+      health,
+      quality: providerQuality({ mode, health })
+    };
+  }
+  const indexPath = join23(input.projectRoot, ".codegraph");
+  if (input.action === "sync" && !existsSync16(indexPath)) {
+    const health = { state: "not-detected", reason: "No local .codegraph index is present for this project." };
+    return {
+      action: input.action,
+      performed: false,
+      message: 'Initialize CodeGraph first with "memorix codegraph init".',
+      health,
+      quality: providerQuality({ mode, health })
+    };
+  }
+  if (input.action === "init" && existsSync16(indexPath)) {
+    const inspected2 = await inspectExternalCodeGraph(input);
+    return {
+      action: input.action,
+      performed: false,
+      message: "A local CodeGraph directory already exists; no initialization was performed.",
+      ...inspected2
+    };
+  }
+  const result = await runSafely(input.runner ?? defaultRunner, {
+    command: input.command,
+    args: input.action === "init" ? ["init", input.projectRoot] : ["sync", input.projectRoot, "--quiet"],
+    cwd: input.projectRoot,
+    // A context read must stay fast; an explicit user-requested index sync is
+    // a different operation and gets its own bounded maintenance window.
+    timeoutMs: EXTERNAL_CODEGRAPH_LIFECYCLE_TIMEOUT_MS,
+    maxOutputBytes: MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES
+  });
+  if (!result.ok) {
+    const health = unavailableHealth(result);
+    return {
+      action: input.action,
+      performed: false,
+      message: "CodeGraph " + input.action + " did not complete: " + (health.reason ?? "unknown local error"),
+      health,
+      quality: providerQuality({ mode, health })
+    };
+  }
+  const inspected = await inspectExternalCodeGraph(input);
+  const remainsStale = inspected.health.state === "stale";
+  return {
+    action: input.action,
+    performed: true,
+    message: input.action === "init" ? 'Local CodeGraph initialization completed. Run "memorix codegraph sync" when source changes.' : remainsStale ? "Local CodeGraph synchronization completed, but the graph remains stale against the current worktree; this task will use Lite evidence." : "Local CodeGraph synchronization completed and is ready for task-scoped semantic context.",
+    ...inspected
+  };
+}
 function safeRelativePath(projectRoot, value, exclude) {
   const path47 = safeText(value, 1024);
   if (!path47 || isAbsolute2(path47)) return void 0;
@@ -195631,7 +195785,7 @@ async function getExternalCodeGraphContext(input) {
     quality: providerQuality({ mode, health: inspected.health, ...contributes ? { selected: "external" } : {} })
   };
 }
-var DEFAULT_EXTERNAL_CODEGRAPH_TIMEOUT_MS, MAX_EXTERNAL_CODEGRAPH_TIMEOUT_MS, MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES, MAX_EXTERNAL_NODE_COUNT, MAX_EXTERNAL_EDGE_COUNT, MAX_EXTERNAL_FILE_COUNT, MAX_EXTERNAL_TEXT_LENGTH, LITE_SUPPORTED_LANGUAGES, defaultRunner;
+var DEFAULT_EXTERNAL_CODEGRAPH_TIMEOUT_MS, MAX_EXTERNAL_CODEGRAPH_TIMEOUT_MS, EXTERNAL_CODEGRAPH_LIFECYCLE_TIMEOUT_MS, MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES, MAX_EXTERNAL_NODE_COUNT, MAX_EXTERNAL_EDGE_COUNT, MAX_EXTERNAL_FILE_COUNT, MAX_EXTERNAL_TEXT_LENGTH, LITE_SUPPORTED_LANGUAGES, defaultRunner;
 var init_external_provider = __esm({
   "src/codegraph/external-provider.ts"() {
     "use strict";
@@ -195641,6 +195795,7 @@ var init_external_provider = __esm({
     init_ids();
     DEFAULT_EXTERNAL_CODEGRAPH_TIMEOUT_MS = 1200;
     MAX_EXTERNAL_CODEGRAPH_TIMEOUT_MS = 5e3;
+    EXTERNAL_CODEGRAPH_LIFECYCLE_TIMEOUT_MS = 3e4;
     MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES = 256 * 1024;
     MAX_EXTERNAL_NODE_COUNT = 16;
     MAX_EXTERNAL_EDGE_COUNT = 24;
@@ -197363,6 +197518,7 @@ async function buildAutoProjectContext(input) {
     projectId: input.project.id,
     dataDir: input.dataDir,
     ...task ? { task } : {},
+    ...input.agent ? { agent: input.agent } : {},
     lens: lens.id,
     startHere,
     ...alwaysOn.profile.length > 0 || alwaysOn.state || alwaysOn.durable.length > 0 ? { alwaysOn } : {},
@@ -197699,6 +197855,34 @@ var init_auto_context = __esm({
   }
 });
 
+// src/knowledge/context-receipt.ts
+var context_receipt_exports = {};
+__export(context_receipt_exports, {
+  buildBoundedContextReceipt: () => buildBoundedContextReceipt
+});
+function buildBoundedContextReceipt(input) {
+  const provider2 = input.providerQuality ?? input.workset.provenance.codeProvider;
+  return {
+    schemaVersion: "1",
+    task: input.workset.task,
+    brief: input.workset.prompt,
+    receipt: input.workset.receipt,
+    code: {
+      selected: provider2?.selected ?? "lite",
+      quality: provider2?.selectedQuality ?? "heuristic",
+      externalState: provider2?.external.state ?? "not-detected",
+      ...input.workset.provenance.snapshotId ? { snapshotId: input.workset.provenance.snapshotId } : {}
+    },
+    ...input.workset.agentLoadout ? { loadout: input.workset.agentLoadout } : {}
+  };
+}
+var init_context_receipt = __esm({
+  "src/knowledge/context-receipt.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/cli/commands/context.ts
 var context_exports = {};
 __export(context_exports, {
@@ -197709,6 +197893,12 @@ function coerceRefreshMode(input) {
   if (value === "always" || value === "never" || value === "auto") return value;
   throw new Error("refresh must be one of: auto, always, never");
 }
+function coerceAgentTarget(input) {
+  const value = input?.trim().toLowerCase();
+  if (!value) return void 0;
+  if (WORKFLOW_AGENT_TARGETS.includes(value)) return value;
+  throw new Error("agent must be one of: " + WORKFLOW_AGENT_TARGETS.join(", "));
+}
 var context_default;
 var init_context2 = __esm({
   "src/cli/commands/context.ts"() {
@@ -197718,6 +197908,8 @@ var init_context2 = __esm({
     init_auto_context();
     init_observations();
     init_visibility();
+    init_context_receipt();
+    init_workflows2();
     init_operator_shared();
     context_default = defineCommand({
       meta: {
@@ -197733,10 +197925,12 @@ var init_context2 = __esm({
         },
         resume: { type: "boolean", description: "Always include the bounded prior-work projection" },
         refresh: { type: "string", description: "Project scan policy: auto, always, or never" },
-        json: { type: "boolean", description: "Emit machine-readable JSON output" }
+        agent: { type: "string", description: "Optional target agent for compatible workflow selection" },
+        json: { type: "boolean", description: "Emit machine-readable JSON output" },
+        briefJson: { type: "boolean", description: "Emit only the bounded agent brief and receipt JSON" }
       },
       run: async ({ args }) => {
-        const asJson = !!args.json;
+        const asJson = !!args.json || !!args.briefJson;
         const task = args.task?.trim() || args.input?.trim() || void 0;
         try {
           const { project, dataDir, reader } = await getCliProjectContext();
@@ -197745,23 +197939,25 @@ var init_context2 = __esm({
             dataDir,
             observations: filterReadableObservations(getAllObservations(), reader),
             task,
+            agent: coerceAgentTarget(args.agent),
             refresh: coerceRefreshMode(args.refresh),
             reader,
             ...args.resume ? { continuation: "always" } : {}
           });
+          const detailed = {
+            project,
+            lens: context.lens,
+            brief: buildAutoProjectBrief(context),
+            currentFacts: context.currentFacts,
+            overview: context.overview,
+            refresh: context.refresh,
+            providerQuality: context.providerQuality,
+            workset: context.workset,
+            ...context.task ? { task: context.task } : {},
+            ...context.continuation ? { continuation: context.continuation } : {}
+          };
           emitResult(
-            {
-              project,
-              lens: context.lens,
-              brief: buildAutoProjectBrief(context),
-              currentFacts: context.currentFacts,
-              overview: context.overview,
-              refresh: context.refresh,
-              providerQuality: context.providerQuality,
-              workset: context.workset,
-              ...context.task ? { task: context.task } : {},
-              ...context.continuation ? { continuation: context.continuation } : {}
-            },
+            args.briefJson ? buildBoundedContextReceipt({ workset: context.workset, providerQuality: context.providerQuality }) : detailed,
             formatAutoProjectContextPrompt(context),
             asJson
           );
@@ -197793,7 +197989,9 @@ var init_resume = __esm({
       args: {
         task: { type: "positional", description: "Current continuation task", required: false },
         refresh: { type: "string", description: "Project scan policy: auto, always, or never" },
-        json: { type: "boolean", description: "Emit machine-readable JSON output" }
+        agent: { type: "string", description: "Optional target agent for compatible workflow selection" },
+        json: { type: "boolean", description: "Emit machine-readable JSON output" },
+        briefJson: { type: "boolean", description: "Emit only the bounded agent brief and receipt JSON" }
       },
       async run({ args }) {
         await context_default.run?.({
@@ -197801,7 +197999,9 @@ var init_resume = __esm({
             _: [],
             input: args.task,
             refresh: args.refresh,
+            agent: args.agent,
             json: args.json,
+            briefJson: args.briefJson,
             resume: true
           },
           rawArgs: [],
@@ -198081,6 +198281,7 @@ async function attachTaskWorkset(input) {
     projectId: input.projectId,
     dataDir: input.dataDir,
     task: input.pack.task,
+    ...input.agent ? { agent: input.agent } : {},
     lens: input.lens,
     currentFacts: input.currentFacts ?? [],
     ...input.codeState ? { codeState: input.codeState } : {},
@@ -198189,7 +198390,8 @@ function formatStatus(status, quality) {
     status.indexedAt ? `- Indexed at: ${status.indexedAt}` : "- Indexed at: never",
     ...quality ? [
       `- Persistent provider: ${status.provider} (heuristic local index)`,
-      `- External semantic CodeGraph: ${quality.external.state}` + (quality.external.reason ? ` (${quality.external.reason})` : "")
+      `- External semantic CodeGraph: ${quality.external.state}` + (quality.external.reason ? ` (${quality.external.reason})` : ""),
+      `- Task-scoped provider: ${quality.selected} (${quality.selectedQuality})`
     ] : []
   ].join("\n");
 }
@@ -198197,6 +198399,8 @@ function formatUsageHint() {
   return [
     "Usage:",
     "  memorix codegraph refresh",
+    "  memorix codegraph init       # explicit local CodeGraph initialization",
+    "  memorix codegraph sync       # explicit local CodeGraph synchronization",
     "  memorix codegraph status --json",
     "  memorix codegraph diff [--from <snapshot>] [--to <snapshot>]",
     "  memorix codegraph impact --path <relative-source-path>",
@@ -198251,6 +198455,12 @@ function compactFacts(project) {
   facts.push(formatGitFact(current.git));
   return { facts, dirty: current.git.dirty };
 }
+function coerceAgentTarget2(input) {
+  const value = input?.trim().toLowerCase();
+  if (!value) return void 0;
+  if (WORKFLOW_AGENT_TARGETS.includes(value)) return value;
+  throw new Error("agent must be one of: " + WORKFLOW_AGENT_TARGETS.join(", "));
+}
 var codegraph_default;
 var init_codegraph = __esm({
   "src/cli/commands/codegraph.ts"() {
@@ -198265,6 +198475,8 @@ var init_codegraph = __esm({
     init_task_lens();
     init_external_provider();
     init_resolved_config();
+    init_context_receipt();
+    init_workflows2();
     init_observations();
     init_visibility();
     init_operator_shared();
@@ -198274,19 +198486,21 @@ var init_codegraph = __esm({
         description: "Inspect and refresh CodeGraph Memory for the current project"
       },
       args: {
-        action: { type: "string", description: "Action: status, refresh, diff, impact, or context-pack" },
+        action: { type: "string", description: "Action: status, refresh, diff, impact, init, sync, or context-pack" },
         task: { type: "string", description: "Task text for context-pack" },
         path: { type: "string", description: "Indexed relative source path for impact" },
         limit: { type: "string", description: "Max active memories to inspect for context-pack" },
         from: { type: "string", description: "Earlier CodeGraph snapshot id for diff" },
         to: { type: "string", description: "Later CodeGraph snapshot id for diff" },
         impactLimit: { type: "string", description: "Maximum graph relations to inspect for diff impact" },
-        json: { type: "boolean", description: "Emit machine-readable JSON output" }
+        agent: { type: "string", description: "Optional target agent for compatible workflow selection" },
+        json: { type: "boolean", description: "Emit machine-readable JSON output" },
+        briefJson: { type: "boolean", description: "Emit only the bounded agent brief and receipt JSON for context-pack" }
       },
       run: async ({ args }) => {
         const positional = args._ ?? [];
         const action = (positional[0] || args.action || "status").toLowerCase();
-        const asJson = !!args.json;
+        const asJson = !!args.json || !!args.briefJson;
         try {
           const { project, dataDir, reader } = await getCliProjectContext();
           const store2 = new CodeGraphStore();
@@ -198353,6 +198567,26 @@ ${formatUsageHint()}`;
               );
               return;
             }
+            case "init":
+            case "sync": {
+              const lifecycle = await runExternalCodeGraphLifecycle({
+                action,
+                projectRoot: project.rootPath,
+                mode: codegraphConfig.externalContext,
+                command: codegraphConfig.externalCommand,
+                timeoutMs: codegraphConfig.externalTimeoutMs
+              });
+              emitResult(
+                { project, lifecycle, providerQuality: lifecycle.quality },
+                [
+                  lifecycle.message,
+                  `- External semantic CodeGraph: ${lifecycle.health.state}`,
+                  `- Task-scoped provider: ${lifecycle.quality.selected} (${lifecycle.quality.selectedQuality})`
+                ].join("\n"),
+                asJson
+              );
+              return;
+            }
             case "diff": {
               const snapshots = store2.listSnapshots(project.id, 2);
               const fromSnapshotId = args.from?.trim() || snapshots[1]?.id;
@@ -198437,13 +198671,18 @@ ${formatUsageHint()}`;
                 ...external.outline ? { semanticCode: external.outline } : {},
                 providerQuality: external.quality,
                 ...external.caution ? { runtimeCautions: [{ kind: "external-codegraph-fallback", message: external.caution }] } : {},
-                reader
+                reader,
+                agent: coerceAgentTarget2(args.agent)
               });
-              emitResult({ project, pack, providerQuality: external.quality }, buildContextPackPrompt(pack), asJson);
+              emitResult(
+                args.briefJson && pack.workset ? buildBoundedContextReceipt({ workset: pack.workset, providerQuality: external.quality }) : { project, pack, providerQuality: external.quality },
+                buildContextPackPrompt(pack),
+                asJson
+              );
               return;
             }
             default:
-              emitError(`unknown codegraph action "${action}". Use "status", "refresh", "diff", "impact", or "context-pack".`, asJson);
+              emitError(`unknown codegraph action "${action}". Use "status", "refresh", "init", "sync", "diff", "impact", or "context-pack".`, asJson);
           }
         } catch (error40) {
           emitError(error40 instanceof Error ? error40.message : String(error40), asJson);
@@ -258844,7 +259083,7 @@ The path should point to a directory containing a .git folder.`
   };
   const server = existingServer ?? new McpServer({
     name: "memorix",
-    version: true ? "1.5.1" : "1.0.1"
+    version: true ? "1.6.1" : "1.0.1"
   });
   const originalRegisterTool = server.registerTool.bind(server);
   server.registerTool = ((name, ...args) => {
@@ -259678,13 +259917,28 @@ _Search mode: ${getLastSearchMode2(project.id)}_`;
         refresh: external_exports2.enum(["auto", "always", "never"]).optional().default("auto").describe(
           "Code Memory refresh policy. auto refreshes only when missing or stale."
         ),
-        format: external_exports2.enum(["prompt", "summary", "json"]).optional().default("prompt").describe(
-          'Output format. "prompt" is agent-ready; "summary" is human-readable; "json" is structured.'
+        format: external_exports2.enum(["prompt", "summary", "json", "receipt"]).optional().default("prompt").describe(
+          'Output format. "prompt" is agent-ready; "summary" is human-readable; "receipt" is bounded JSON; "json" is detailed diagnostics.'
         ),
+        agent: external_exports2.enum([
+          "windsurf",
+          "cursor",
+          "claude-code",
+          "codex",
+          "copilot",
+          "antigravity",
+          "gemini-cli",
+          "openclaw",
+          "hermes",
+          "omp",
+          "kiro",
+          "opencode",
+          "trae"
+        ]).optional().describe("Optional target agent for compatible workflow selection."),
         limit: external_exports2.number().optional().describe("Reserved for future source limits; current prompt stays compact by default.")
       }
     },
-    async ({ task, refresh, format }) => {
+    async ({ task, refresh, format, agent }) => {
       const unresolved = requireResolvedProject("build project context for the current project");
       if (unresolved) return unresolved;
       const [
@@ -259696,12 +259950,14 @@ _Search mode: ${getLastSearchMode2(project.id)}_`;
         },
         { getObservationStore: getObservationStore2 },
         { MaintenanceJobStore: MaintenanceJobStore2 },
-        { enqueueCodegraphRefresh: enqueueCodegraphRefresh2 }
+        { enqueueCodegraphRefresh: enqueueCodegraphRefresh2 },
+        { buildBoundedContextReceipt: buildBoundedContextReceipt2 }
       ] = await Promise.all([
         Promise.resolve().then(() => (init_auto_context(), auto_context_exports)),
         Promise.resolve().then(() => (init_obs_store(), obs_store_exports)),
         Promise.resolve().then(() => (init_maintenance_jobs(), maintenance_jobs_exports)),
-        Promise.resolve().then(() => (init_lifecycle(), lifecycle_exports))
+        Promise.resolve().then(() => (init_lifecycle(), lifecycle_exports)),
+        Promise.resolve().then(() => (init_context_receipt(), context_receipt_exports))
       ]);
       const observations2 = filterReadableObservations(
         await getObservationStore2().loadByProject(project.id, { status: "active" }),
@@ -259712,6 +259968,7 @@ _Search mode: ${getLastSearchMode2(project.id)}_`;
         dataDir: projectDir2,
         observations: observations2,
         task,
+        agent,
         refresh: refresh ?? "auto",
         reader: getObservationReader(),
         enqueueRefresh: () => {
@@ -259724,7 +259981,10 @@ _Search mode: ${getLastSearchMode2(project.id)}_`;
           });
         }
       });
-      const text2 = format === "json" ? JSON.stringify({ ...context, brief: buildAutoProjectBrief2(context) }, null, 2) : format === "summary" ? formatAutoProjectContextSummary2(context) : formatAutoProjectContextPrompt2(context);
+      const text2 = format === "json" ? JSON.stringify({ ...context, brief: buildAutoProjectBrief2(context) }, null, 2) : format === "receipt" ? JSON.stringify(buildBoundedContextReceipt2({
+        workset: context.workset,
+        providerQuality: context.providerQuality
+      }), null, 2) : format === "summary" ? formatAutoProjectContextSummary2(context) : formatAutoProjectContextPrompt2(context);
       autopilotRetrievalBoundary = {
         projectId: project.id,
         issuedAt: Date.now(),
@@ -265691,6 +265951,7 @@ var init_control_plane_maintenance = __esm({
 var serve_http_exports = {};
 __export(serve_http_exports, {
   DEFAULT_SESSION_TIMEOUT_MS: () => DEFAULT_SESSION_TIMEOUT_MS,
+  EXPIRED_SESSION_TTL_MS: () => EXPIRED_SESSION_TTL_MS,
   _testing: () => _testing2,
   default: () => serve_http_default,
   parseSessionTimeoutMs: () => parseSessionTimeoutMs,
@@ -265700,7 +265961,7 @@ function parseSessionTimeoutMs(raw) {
   const value = raw?.trim();
   if (!value) return DEFAULT_SESSION_TIMEOUT_MS;
   const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_SESSION_TIMEOUT_MS;
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_SESSION_TIMEOUT_MS;
   return Math.floor(parsed);
 }
 function resolveServeHttpDefaults(argsPort, configured) {
@@ -265712,7 +265973,7 @@ function resolveServeHttpDefaults(argsPort, configured) {
   const transportNotice = configured.transport === "stdio" ? '[memorix] config server.transport = "stdio"; serve-http continues on HTTP (the explicit command wins).' : void 0;
   return { port, transportNotice };
 }
-var DEFAULT_SESSION_TIMEOUT_MS, serve_http_default, _testing2;
+var DEFAULT_SESSION_TIMEOUT_MS, EXPIRED_SESSION_TTL_MS, serve_http_default, _testing2;
 var init_serve_http = __esm({
   "src/cli/commands/serve-http.ts"() {
     "use strict";
@@ -265724,7 +265985,8 @@ var init_serve_http = __esm({
     init_visibility();
     init_port();
     init_mcp_root_path();
-    DEFAULT_SESSION_TIMEOUT_MS = 30 * 60 * 1e3;
+    DEFAULT_SESSION_TIMEOUT_MS = 12 * 60 * 60 * 1e3;
+    EXPIRED_SESSION_TTL_MS = 10 * 60 * 1e3;
     serve_http_default = defineCommand({
       meta: {
         name: "serve-http",
@@ -265783,7 +266045,9 @@ var init_serve_http = __esm({
         console.error(`[memorix] HTTP transport starting on ${host}:${port}`);
         console.error(`[memorix] Project root: ${projectRoot}`);
         const sessionTimeoutMs = parseSessionTimeoutMs(process.env.MEMORIX_SESSION_TIMEOUT_MS);
-        console.error(`[memorix] HTTP session idle timeout: ${Math.round(sessionTimeoutMs / 6e4)}min (${sessionTimeoutMs}ms)`);
+        console.error(
+          sessionTimeoutMs === 0 ? "[memorix] HTTP session idle timeout: disabled" : `[memorix] HTTP session idle timeout: ${Math.round(sessionTimeoutMs / 6e4)}min (${sessionTimeoutMs}ms)`
+        );
         const teamStoreCache = /* @__PURE__ */ new Map();
         const { initTeamStore: initTeamStore2 } = await Promise.resolve().then(() => (init_team_store(), team_store_exports));
         async function getTeamStore2(dataDir) {
@@ -265800,6 +266064,7 @@ var init_serve_http = __esm({
         const sharedTeamStore = await getTeamStore2(teamDataDir);
         const sessions = /* @__PURE__ */ new Map();
         const sessionLastActivity = /* @__PURE__ */ new Map();
+        const expiredSessions = /* @__PURE__ */ new Map();
         let suppressedProbeCount = 0;
         let lastProbeSummaryTime = Date.now();
         const PROBE_SUMMARY_INTERVAL_MS = 6e4;
@@ -265812,6 +266077,26 @@ var init_serve_http = __esm({
             lastProbeSummaryTime = Date.now();
           }
         }
+        function forgetExpiredSessions(now3 = Date.now()) {
+          for (const [sessionId, expiresAt] of expiredSessions) {
+            if (expiresAt <= now3) expiredSessions.delete(sessionId);
+          }
+        }
+        function sendUnknownSession(res, sessionId, jsonRpc = false) {
+          const expired = Boolean(sessionId && expiredSessions.has(sessionId));
+          const message = expired ? "MCP session expired after inactivity. Initialize a new session and retry the request." : "MCP session not found. Initialize a new session and retry the request.";
+          if (jsonRpc) {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+              jsonrpc: "2.0",
+              error: { code: -32001, message },
+              id: null
+            }));
+            return;
+          }
+          res.writeHead(404, { "Content-Type": "text/plain" });
+          res.end(message);
+        }
         function parseBody(req) {
           return new Promise((resolve6, reject) => {
             const chunks = [];
@@ -265928,6 +266213,10 @@ var init_serve_http = __esm({
             await sessions.get(sessionId).transport.handleRequest(req, res, body);
             return;
           }
+          if (sessionId) {
+            sendUnknownSession(res, sessionId, true);
+            return;
+          }
           if (!sessionId && isInitializeRequest2(body)) {
             let createdState = null;
             const transport = new StreamableHTTPServerTransport2({
@@ -266026,8 +266315,12 @@ var init_serve_http = __esm({
         async function handleGet(req, res) {
           const sessionId = req.headers["mcp-session-id"];
           if (!sessionId || !sessions.has(sessionId)) {
-            res.writeHead(400, { "Content-Type": "text/plain" });
-            res.end("Invalid or missing session ID");
+            if (!sessionId) {
+              res.writeHead(400, { "Content-Type": "text/plain" });
+              res.end("Missing MCP session ID");
+              return;
+            }
+            sendUnknownSession(res, sessionId);
             return;
           }
           await sessions.get(sessionId).transport.handleRequest(req, res);
@@ -266035,8 +266328,12 @@ var init_serve_http = __esm({
         async function handleDelete(req, res) {
           const sessionId = req.headers["mcp-session-id"];
           if (!sessionId || !sessions.has(sessionId)) {
-            res.writeHead(400, { "Content-Type": "text/plain" });
-            res.end("Invalid or missing session ID");
+            if (!sessionId) {
+              res.writeHead(400, { "Content-Type": "text/plain" });
+              res.end("Missing MCP session ID");
+              return;
+            }
+            sendUnknownSession(res, sessionId);
             return;
           }
           await sessions.get(sessionId).transport.handleRequest(req, res);
@@ -266785,13 +267082,15 @@ var init_serve_http = __esm({
           }
           const url2 = new URL(req.url || "/", `http://localhost:${port}`);
           if (url2.pathname === "/health") {
+            const { getEmbeddingRuntimeHealth: getEmbeddingRuntimeHealth2 } = await Promise.resolve().then(() => (init_provider(), provider_exports));
             res.writeHead(200, { "Content-Type": "application/json" });
             res.end(JSON.stringify({
               status: "ok",
               mode: "control-plane",
               port,
               uptime: Math.round(process.uptime()),
-              pid: process.pid
+              pid: process.pid,
+              embedding: getEmbeddingRuntimeHealth2()
             }));
             return;
           }
@@ -266849,6 +267148,8 @@ var init_serve_http = __esm({
           }
           await serveDashStatic(req, res);
         });
+        httpServer.keepAliveTimeout = 6e4;
+        httpServer.headersTimeout = 65e3;
         httpServer.listen(port, host, () => {
           try {
             const memorixDir = (process.env.HOME || process.env.USERPROFILE || "").replace(/\\/g, "/") + "/.memorix";
@@ -266872,10 +267173,13 @@ var init_serve_http = __esm({
         const gcInterval = setInterval(() => {
           maybeProbeSummary();
           const now3 = Date.now();
+          forgetExpiredSessions(now3);
+          if (SESSION_TIMEOUT_MS === 0) return;
           for (const [sid, state] of sessions) {
             const lastActive = sessionLastActivity.get(sid) ?? 0;
             if (now3 - lastActive > SESSION_TIMEOUT_MS) {
               console.error(`[memorix] Session ${sid.slice(0, 8)}\u2026 timed out (idle ${Math.round((now3 - lastActive) / 6e4)}min), closing`);
+              expiredSessions.set(sid, now3 + EXPIRED_SESSION_TTL_MS);
               state.transport.close().catch(() => {
               });
               sessions.delete(sid);
@@ -268514,6 +268818,144 @@ var init_pattern_detector = __esm({
   }
 });
 
+// src/hooks/lifecycle.ts
+var lifecycle_exports2 = {};
+__export(lifecycle_exports2, {
+  DEFAULT_HOOK_STDIN_TIMEOUT_MS: () => DEFAULT_HOOK_STDIN_TIMEOUT_MS,
+  DEFAULT_HOOK_TIMEOUT_MS: () => DEFAULT_HOOK_TIMEOUT_MS,
+  MAX_HOOK_STDIN_TIMEOUT_MS: () => MAX_HOOK_STDIN_TIMEOUT_MS,
+  MAX_HOOK_TIMEOUT_MS: () => MAX_HOOK_TIMEOUT_MS,
+  MIN_HOOK_STDIN_TIMEOUT_MS: () => MIN_HOOK_STDIN_TIMEOUT_MS,
+  MIN_HOOK_TIMEOUT_MS: () => MIN_HOOK_TIMEOUT_MS,
+  hookObservationRuntimeOptions: () => hookObservationRuntimeOptions,
+  readHookStdin: () => readHookStdin,
+  resolveHookStdinTimeoutMs: () => resolveHookStdinTimeoutMs,
+  resolveHookTimeoutMs: () => resolveHookTimeoutMs,
+  runHookWithDeadline: () => runHookWithDeadline
+});
+function parseBoundedMs(raw, fallback, min, max) {
+  const value = raw?.trim();
+  if (!value) return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+function resolveHookTimeoutMs(env3 = process.env) {
+  return parseBoundedMs(
+    env3.MEMORIX_HOOK_TIMEOUT_MS,
+    DEFAULT_HOOK_TIMEOUT_MS,
+    MIN_HOOK_TIMEOUT_MS,
+    MAX_HOOK_TIMEOUT_MS
+  );
+}
+function resolveHookStdinTimeoutMs(env3 = process.env) {
+  return parseBoundedMs(
+    env3.MEMORIX_HOOK_STDIN_TIMEOUT_MS,
+    DEFAULT_HOOK_STDIN_TIMEOUT_MS,
+    MIN_HOOK_STDIN_TIMEOUT_MS,
+    MAX_HOOK_STDIN_TIMEOUT_MS
+  );
+}
+function hookObservationRuntimeOptions(projectRoot) {
+  return {
+    embeddingWriteMode: "deferred",
+    projectRoot
+  };
+}
+async function readHookStdin(stdin2, timeoutMs) {
+  return new Promise((resolve6) => {
+    const chunks = [];
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      stdin2.removeListener("data", onData);
+      stdin2.removeListener("end", finish);
+      stdin2.removeListener("error", finish);
+      stdin2.pause?.();
+      if (!stdin2.isTTY) {
+        stdin2.destroy?.();
+      } else {
+        stdin2.unref?.();
+      }
+      resolve6(Buffer.concat(chunks).toString("utf-8").trim());
+    };
+    const onData = (chunk) => {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    stdin2.on("data", onData);
+    stdin2.on("end", finish);
+    stdin2.on("error", finish);
+  });
+}
+function writeContinue(stdout2) {
+  try {
+    stdout2.write(JSON.stringify({ continue: true }));
+  } catch {
+  }
+}
+async function runHookWithDeadline(options) {
+  const stdout2 = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const exit = options.exit ?? ((code) => {
+    process.exit(code);
+  });
+  await new Promise((resolve6) => {
+    let finished2 = false;
+    const settle = () => {
+      if (finished2) return;
+      finished2 = true;
+      clearTimeout(timer);
+      resolve6();
+    };
+    const timer = setTimeout(() => {
+      if (finished2) return;
+      try {
+        stderr.write(`[memorix] hook timed out after ${options.timeoutMs}ms
+`);
+      } catch {
+      }
+      writeContinue(stdout2);
+      exit(0);
+      settle();
+    }, options.timeoutMs);
+    options.run().then(
+      () => {
+        if (finished2) return;
+        exit(0);
+        settle();
+      },
+      (error40) => {
+        if (finished2) return;
+        try {
+          const message = error40 instanceof Error ? error40.message : String(error40);
+          stderr.write(`[memorix] hook failed: ${message}
+`);
+        } catch {
+        }
+        writeContinue(stdout2);
+        exit(0);
+        settle();
+      }
+    );
+  });
+}
+var DEFAULT_HOOK_TIMEOUT_MS, MIN_HOOK_TIMEOUT_MS, MAX_HOOK_TIMEOUT_MS, DEFAULT_HOOK_STDIN_TIMEOUT_MS, MIN_HOOK_STDIN_TIMEOUT_MS, MAX_HOOK_STDIN_TIMEOUT_MS;
+var init_lifecycle2 = __esm({
+  "src/hooks/lifecycle.ts"() {
+    "use strict";
+    init_esm_shims();
+    DEFAULT_HOOK_TIMEOUT_MS = 2e4;
+    MIN_HOOK_TIMEOUT_MS = 1e3;
+    MAX_HOOK_TIMEOUT_MS = 12e4;
+    DEFAULT_HOOK_STDIN_TIMEOUT_MS = 3e3;
+    MIN_HOOK_STDIN_TIMEOUT_MS = 100;
+    MAX_HOOK_STDIN_TIMEOUT_MS = 3e4;
+  }
+});
+
 // src/hooks/handler.ts
 var handler_exports = {};
 __export(handler_exports, {
@@ -268993,26 +269435,7 @@ function formatHookOutput(agent, rawEventName, output) {
   return finalOutput;
 }
 async function runHook(agentOverride, eventOverride) {
-  const rawInput = await new Promise((resolve6) => {
-    const chunks = [];
-    const finish = () => resolve6(Buffer.concat(chunks).toString("utf-8").trim());
-    const timer = setTimeout(() => {
-      process.stdin.removeAllListeners("data");
-      process.stdin.removeAllListeners("end");
-      finish();
-    }, 3e3);
-    process.stdin.on("data", (chunk) => {
-      chunks.push(chunk);
-    });
-    process.stdin.on("end", () => {
-      clearTimeout(timer);
-      finish();
-    });
-    process.stdin.on("error", () => {
-      clearTimeout(timer);
-      finish();
-    });
-  });
+  const rawInput = await readHookStdin(process.stdin, resolveHookStdinTimeoutMs());
   if (!rawInput) {
     process.stdout.write(JSON.stringify({ continue: true }));
     return;
@@ -269062,7 +269485,7 @@ async function runHook(agentOverride, eventOverride) {
       await initObservationStore2(dataDir);
       await initMSStore(dataDir);
       await initSessStore(dataDir);
-      await initObservations2(dataDir);
+      await initObservations2(dataDir, hookObservationRuntimeOptions(rawProject.rootPath));
       await storeObservation2({ ...observation, projectId, sourceDetail: "hook" });
     } catch (storeErr) {
       console.error("[memorix] hook store failed:", storeErr?.message ?? storeErr);
@@ -269108,6 +269531,7 @@ var init_handler = __esm({
     init_normalizer();
     init_pattern_detector();
     init_significance_filter();
+    init_lifecycle2();
     TYPE_EMOJI2 = {
       "gotcha": "[GOTCHA]",
       "decision": "[DECISION]",
@@ -269164,7 +269588,11 @@ var init_hook = __esm({
       },
       run: async ({ args }) => {
         const { runHook: runHook2 } = await Promise.resolve().then(() => (init_handler(), handler_exports));
-        await runHook2(args.agent, args.event);
+        const { resolveHookTimeoutMs: resolveHookTimeoutMs2, runHookWithDeadline: runHookWithDeadline2 } = await Promise.resolve().then(() => (init_lifecycle2(), lifecycle_exports2));
+        await runHookWithDeadline2({
+          timeoutMs: resolveHookTimeoutMs2(),
+          run: () => runHook2(args.agent, args.event)
+        });
       }
     });
   }
@@ -271930,7 +272358,7 @@ __export(agent_integrations_exports, {
   repairAgentIntegrations: () => repairAgentIntegrations
 });
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync28 } from "fs";
+import { existsSync as existsSync28, realpathSync as realpathSync2 } from "fs";
 import { mkdir as mkdir8, readFile as readFile9, writeFile as writeFile9 } from "fs/promises";
 import { basename as basename5, dirname as dirname8, resolve as resolve4 } from "path";
 import { homedir as homedir34 } from "os";
@@ -272324,10 +272752,15 @@ function sanitizeServer(server) {
   };
 }
 function normalizeProjectKey(projectRoot) {
-  return resolve4(projectRoot).replace(/\\/g, "/").toLowerCase();
+  return canonicalProjectPath(projectRoot).toLowerCase();
 }
 function defaultClaudeProjectKey(projectRoot) {
-  return resolve4(projectRoot).replace(/\\/g, "/");
+  return canonicalProjectPath(projectRoot);
+}
+function canonicalProjectPath(projectRoot) {
+  const resolved = resolve4(projectRoot);
+  const canonical = existsSync28(resolved) ? realpathSync2(resolved) : resolved;
+  return canonical.replace(/\\/g, "/");
 }
 function getClaudeLocalConfigPath() {
   return `${homedir34()}/.claude.json`;
@@ -272936,6 +273369,7 @@ var init_doctor = __esm({
         let bgRunning = false;
         let bgPort = 0;
         let bgPid = 0;
+        let backgroundHealthy = false;
         try {
           if (existsSync33(bgStatePath)) {
             const bgState = JSON.parse(readFileSync22(bgStatePath, "utf-8"));
@@ -272953,7 +273387,7 @@ var init_doctor = __esm({
           lines.push(ok(`Background control plane running (PID ${bgPid}, port ${bgPort})`));
           try {
             const http3 = await import("http");
-            const healthy = await new Promise((resolve6) => {
+            backgroundHealthy = await new Promise((resolve6) => {
               const req = http3.request({ hostname: "127.0.0.1", port: bgPort, path: "/api/team", timeout: 3e3 }, (res) => {
                 res.resume();
                 resolve6(res.statusCode === 200);
@@ -272965,7 +273399,7 @@ var init_doctor = __esm({
               });
               req.end();
             });
-            if (healthy) {
+            if (backgroundHealthy) {
               lines.push(ok("Health check: OK"));
             } else {
               lines.push(warn2("Health check: FAILED (process alive but not responding)"));
@@ -272973,8 +273407,9 @@ var init_doctor = __esm({
             }
           } catch {
             lines.push(warn2("Health check: could not connect"));
+            issues.push('Background process is alive but its health endpoint could not be reached. Try "memorix background restart".');
           }
-          report.mode = { type: "background", pid: bgPid, port: bgPort, healthy: true };
+          report.mode = { type: "background", pid: bgPid, port: bgPort, healthy: backgroundHealthy };
         } else {
           lines.push(info2("Background control plane: not running"));
           lines.push(info2("Current invocation: CLI (stdio)"));
@@ -273015,18 +273450,39 @@ var init_doctor = __esm({
             report.embedding = { mode: "off", status: "disabled" };
           } else {
             lines.push(ok(`Mode: ${mode}`));
-            const { getEmbeddingProvider: getEmbeddingProvider2 } = await Promise.resolve().then(() => (init_provider(), provider_exports));
-            const provider2 = await getEmbeddingProvider2();
-            if (provider2) {
-              lines.push(ok(`Provider: ${provider2.name} (${provider2.dimensions}d)`));
-              lines.push(ok("Status: ready"));
-              lines.push(info2("Search: hybrid (BM25 + vector)"));
-              report.embedding = { mode, status: "ready", provider: provider2.name, dimensions: provider2.dimensions };
+            let controlPlaneEmbedding;
+            if (bgRunning) {
+              try {
+                const response = await fetch(`http://127.0.0.1:${bgPort}/health`, { signal: AbortSignal.timeout(3e3) });
+                if (response.ok) {
+                  const health = await response.json();
+                  controlPlaneEmbedding = health.embedding;
+                }
+              } catch {
+              }
+            }
+            if (controlPlaneEmbedding?.status === "degraded") {
+              const kind = controlPlaneEmbedding.failure?.kind ?? "upstream";
+              const retryAfterMs = controlPlaneEmbedding.failure?.retryAfterMs;
+              const retry2 = typeof retryAfterMs === "number" && retryAfterMs > 0 ? `; retry in ${Math.ceil(retryAfterMs / 1e3)}s` : "";
+              lines.push(warn2(`Status: degraded in the running control plane (${kind}${retry2})`));
+              lines.push(info2("Search: degraded to BM25 fulltext until the provider recovers"));
+              issues.push("The running control plane has an unavailable embedding provider. Check provider credentials, billing, or connectivity.");
+              report.embedding = { mode, status: "degraded", failure: kind };
             } else {
-              lines.push(warn2("Status: temporarily unavailable"));
-              lines.push(info2("Search: degraded to BM25 fulltext (no vector similarity)"));
-              issues.push(`Embedding mode is "${mode}" but provider failed to initialize. Check API keys/connectivity.`);
-              report.embedding = { mode, status: "temporarily_unavailable" };
+              const { getEmbeddingProvider: getEmbeddingProvider2 } = await Promise.resolve().then(() => (init_provider(), provider_exports));
+              const provider2 = await getEmbeddingProvider2();
+              if (provider2) {
+                lines.push(ok(`Provider: ${provider2.name} (${provider2.dimensions}d)`));
+                lines.push(ok("Status: ready"));
+                lines.push(info2("Search: hybrid (BM25 + vector)"));
+                report.embedding = { mode, status: "ready", provider: provider2.name, dimensions: provider2.dimensions };
+              } else {
+                lines.push(warn2("Status: temporarily unavailable"));
+                lines.push(info2("Search: degraded to BM25 fulltext (no vector similarity)"));
+                issues.push(`Embedding mode is "${mode}" but provider failed to initialize. Check API keys/connectivity.`);
+                report.embedding = { mode, status: "temporarily_unavailable" };
+              }
             }
             try {
               const cachePath = join34(memorixDir, "embedding-cache.json");