memorix 1.5.1 → 1.6.1

package/src/cli/commands/context.ts

@@ -7,6 +7,9 @@ import {
 } from '../../codegraph/auto-context.js';
 import { getAllObservations } from '../../memory/observations.js';
 import { filterReadableObservations } from '../../memory/visibility.js';
+import { buildBoundedContextReceipt } from '../../knowledge/context-receipt.js';
+import { WORKFLOW_AGENT_TARGETS } from '../../knowledge/workflows.js';
+import type { AgentTarget } from '../../types.js';
 import { emitError, emitResult, getCliProjectContext } from './operator-shared.js';
 
 function coerceRefreshMode(input?: string): AutoContextRefreshMode {
@@ -15,6 +18,13 @@ function coerceRefreshMode(input?: string): AutoContextRefreshMode {
   throw new Error('refresh must be one of: auto, always, never');
 }
 
+function coerceAgentTarget(input?: string): AgentTarget | undefined {
+  const value = input?.trim().toLowerCase();
+  if (!value) return undefined;
+  if (WORKFLOW_AGENT_TARGETS.includes(value as AgentTarget)) return value as AgentTarget;
+  throw new Error('agent must be one of: ' + WORKFLOW_AGENT_TARGETS.join(', '));
+}
+
 export default defineCommand({
   meta: {
     name: 'context',
@@ -29,10 +39,12 @@ export default defineCommand({
     },
     resume: { type: 'boolean', description: 'Always include the bounded prior-work projection' },
     refresh: { type: 'string', description: 'Project scan policy: auto, always, or never' },
+    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 as string | undefined)?.trim()
       || (args.input as string | undefined)?.trim()
       || undefined;
@@ -44,13 +56,13 @@ export default defineCommand({
         dataDir,
         observations: filterReadableObservations(getAllObservations(), reader),
         task,
+        agent: coerceAgentTarget(args.agent as string | undefined),
         refresh: coerceRefreshMode(args.refresh as string | undefined),
         reader,
         ...(args.resume ? { continuation: 'always' as const } : {}),
       });
 
-      emitResult(
-        {
+      const detailed = {
           project,
           lens: context.lens,
           brief: buildAutoProjectBrief(context),
@@ -61,7 +73,11 @@ export default defineCommand({
           workset: context.workset,
           ...(context.task ? { task: context.task } : {}),
           ...(context.continuation ? { continuation: context.continuation } : {}),
-        },
+      };
+      emitResult(
+        args.briefJson
+          ? buildBoundedContextReceipt({ workset: context.workset, providerQuality: context.providerQuality })
+          : detailed,
         formatAutoProjectContextPrompt(context),
         asJson,
       );

package/src/cli/commands/doctor.ts

@@ -131,6 +131,7 @@ export default defineCommand({
     let bgRunning = false;
     let bgPort = 0;
     let bgPid = 0;
+    let backgroundHealthy = false;
 
     try {
       if (existsSync(bgStatePath)) {
@@ -148,7 +149,7 @@ export default defineCommand({
       // Health check
       try {
         const http = await import('node:http');
-        const healthy = await new Promise<boolean>((resolve) => {
+        backgroundHealthy = await new Promise<boolean>((resolve) => {
           const req = http.request({ hostname: '127.0.0.1', port: bgPort, path: '/api/team', timeout: 3000 }, (res) => {
             res.resume();
             resolve(res.statusCode === 200);
@@ -157,7 +158,7 @@ export default defineCommand({
           req.on('timeout', () => { req.destroy(); resolve(false); });
           req.end();
         });
-        if (healthy) {
+        if (backgroundHealthy) {
           lines.push(ok('Health check: OK'));
         } else {
           lines.push(warn('Health check: FAILED (process alive but not responding)'));
@@ -165,8 +166,9 @@ export default defineCommand({
         }
       } catch {
         lines.push(warn('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(info('Background control plane: not running'));
       lines.push(info('Current invocation: CLI (stdio)'));
@@ -210,20 +212,49 @@ export default defineCommand({
       } else {
         lines.push(ok(`Mode: ${mode}`));
 
-        // Try to initialize provider to check real status
-        const { getEmbeddingProvider } = await import('../../embedding/provider.js');
-        const provider = await getEmbeddingProvider();
+        // A running control plane is the source of truth for runtime health.
+        // A fresh doctor process must not overwrite a live 401/402/timeout
+        // diagnosis with a static "configured = ready" result.
+        let controlPlaneEmbedding: {
+          status?: string;
+          provider?: { name?: string; dimensions?: number };
+          failure?: { kind?: string; retryAfterMs?: number };
+        } | undefined;
+        if (bgRunning) {
+          try {
+            const response = await fetch(`http://127.0.0.1:${bgPort}/health`, { signal: AbortSignal.timeout(3_000) });
+            if (response.ok) {
+              const health = await response.json() as { embedding?: typeof controlPlaneEmbedding };
+              controlPlaneEmbedding = health.embedding;
+            }
+          } catch { /* health is advisory; fall back to a local probe */ }
+        }
 
-        if (provider) {
-          lines.push(ok(`Provider: ${provider.name} (${provider.dimensions}d)`));
-          lines.push(ok('Status: ready'));
-          lines.push(info('Search: hybrid (BM25 + vector)'));
-          report.embedding = { mode, status: 'ready', provider: provider.name, dimensions: provider.dimensions };
+        if (controlPlaneEmbedding?.status === 'degraded') {
+          const kind = controlPlaneEmbedding.failure?.kind ?? 'upstream';
+          const retryAfterMs = controlPlaneEmbedding.failure?.retryAfterMs;
+          const retry = typeof retryAfterMs === 'number' && retryAfterMs > 0
+            ? `; retry in ${Math.ceil(retryAfterMs / 1000)}s`
+            : '';
+          lines.push(warn(`Status: degraded in the running control plane (${kind}${retry})`));
+          lines.push(info('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(warn('Status: temporarily unavailable'));
-          lines.push(info('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 } = await import('../../embedding/provider.js');
+          const provider = await getEmbeddingProvider();
+
+          if (provider) {
+            lines.push(ok(`Provider: ${provider.name} (${provider.dimensions}d)`));
+            lines.push(ok('Status: ready'));
+            lines.push(info('Search: hybrid (BM25 + vector)'));
+            report.embedding = { mode, status: 'ready', provider: provider.name, dimensions: provider.dimensions };
+          } else {
+            lines.push(warn('Status: temporarily unavailable'));
+            lines.push(info('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' };
+          }
         }
 
         // Check cached embeddings count

package/src/cli/commands/hook.ts

@@ -4,8 +4,16 @@
  * Entry point called by agent hooks via stdin/stdout.
  * Reads agent's JSON from stdin, normalizes, auto-stores, outputs response.
  *
+ * This command is short-lived. A leftover `memorix hook` process is a bug:
+ * hosts invoke it on every event, and hung copies exhaust RAM.
+ *
  * Usage (called by agent hook configs, not by users directly):
  *   memorix hook
+ *
+ * Env:
+ *   MEMORIX_HOOK_TIMEOUT_MS — wall-clock budget (default 20000)
+ *   MEMORIX_HOOK_STDIN_TIMEOUT_MS — stdin idle budget (default 3000)
+ *   MEMORIX_HOOK_HEAP_MB — V8 heap for this command only (default 512)
  */
 
 import { defineCommand } from 'citty';
@@ -29,6 +37,10 @@ export default defineCommand({
   },
   run: async ({ args }) => {
     const { runHook } = await import('../../hooks/handler.js');
-    await runHook(args.agent as string | undefined, args.event as string | undefined);
+    const { resolveHookTimeoutMs, runHookWithDeadline } = await import('../../hooks/lifecycle.js');
+    await runHookWithDeadline({
+      timeoutMs: resolveHookTimeoutMs(),
+      run: () => runHook(args.agent as string | undefined, args.event as string | undefined),
+    });
   },
 });

package/src/cli/commands/resume.ts

@@ -13,7 +13,9 @@ export default defineCommand({
   args: {
     task: { type: 'positional', description: 'Current continuation task', required: false },
     refresh: { type: 'string', description: 'Project scan policy: auto, always, or never' },
+    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 contextCommand.run?.({
@@ -21,7 +23,9 @@ export default defineCommand({
         _: [],
         input: args.task,
         refresh: args.refresh,
+        agent: args.agent,
         json: args.json,
+        briefJson: args.briefJson,
         resume: true,
       },
       rawArgs: [],

package/src/cli/commands/serve-http.ts

@@ -29,13 +29,19 @@ import { canManageObservation, filterReadableObservations } from '../../memory/v
 import { parseTcpPortOrReport } from '../port.js';
 import { mcpFileUriToPath } from '../mcp-root-path.js';
 
-export const DEFAULT_SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * HTTP MCP is a shared control plane. A normal thinking break should not
+ * silently invalidate a client session. Operators can choose a shorter GC
+ * window, or set 0 to disable idle GC entirely.
+ */
+export const DEFAULT_SESSION_TIMEOUT_MS = 12 * 60 * 60 * 1000;
+export const EXPIRED_SESSION_TTL_MS = 10 * 60 * 1000;
 
 export function parseSessionTimeoutMs(raw: string | undefined): number {
   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);
 }
 
@@ -132,7 +138,11 @@ export default defineCommand({
     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 / 60000)}min (${sessionTimeoutMs}ms)`);
+    console.error(
+      sessionTimeoutMs === 0
+        ? '[memorix] HTTP session idle timeout: disabled'
+        : `[memorix] HTTP session idle timeout: ${Math.round(sessionTimeoutMs / 60000)}min (${sessionTimeoutMs}ms)`,
+    );
 
     // Per-project TeamStore cache (Option B) — each dataDir gets its own TeamStore instance.
     // This ensures true isolation between projects in HTTP control-plane mode.
@@ -166,6 +176,9 @@ export default defineCommand({
 
     // Session activity tracking (for GC timeout)
     const sessionLastActivity = new Map<string, number>();
+    // Keep a short-lived tombstone so an expired client gets an actionable
+    // reinitialize response instead of a generic bad request.
+    const expiredSessions = new Map<string, number>();
 
     // Probe session noise reduction: defer init logs, suppress short-lived sessions
     let suppressedProbeCount = 0;
@@ -182,6 +195,30 @@ export default defineCommand({
       }
     }
 
+    function forgetExpiredSessions(now = Date.now()): void {
+      for (const [sessionId, expiresAt] of expiredSessions) {
+        if (expiresAt <= now) expiredSessions.delete(sessionId);
+      }
+    }
+
+    function sendUnknownSession(res: ServerResponse, sessionId: string | undefined, jsonRpc = false): void {
+      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);
+    }
+
     /**
      * Parse JSON body from IncomingMessage
      */
@@ -360,6 +397,11 @@ export default defineCommand({
         return;
       }
 
+      if (sessionId) {
+        sendUnknownSession(res, sessionId, true);
+        return;
+      }
+
       if (!sessionId && isInitializeRequest(body)) {
         // New session — create transport + server
         let createdState: SessionState | null = null;
@@ -488,8 +530,12 @@ export default defineCommand({
     async function handleGet(req: IncomingMessage, res: ServerResponse) {
       const sessionId = req.headers['mcp-session-id'] as string | undefined;
       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;
       }
 
@@ -502,8 +548,12 @@ export default defineCommand({
     async function handleDelete(req: IncomingMessage, res: ServerResponse) {
       const sessionId = req.headers['mcp-session-id'] as string | undefined;
       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;
       }
 
@@ -1414,6 +1464,7 @@ export default defineCommand({
       // Lightweight health check — responds immediately, no heavy init required.
       // This is the readiness signal for background start / status.
       if (url.pathname === '/health') {
+        const { getEmbeddingRuntimeHealth } = await import('../../embedding/provider.js');
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
           status: 'ok',
@@ -1421,6 +1472,7 @@ export default defineCommand({
           port,
           uptime: Math.round(process.uptime()),
           pid: process.pid,
+          embedding: getEmbeddingRuntimeHealth(),
         }));
         return;
       }
@@ -1491,6 +1543,12 @@ export default defineCommand({
       await serveDashStatic(req, res);
     });
 
+    // MCP session continuity is independent from one TCP socket. Keep Node's
+    // socket timeout above its 5s default while the session map remains the
+    // actual continuity boundary.
+    httpServer.keepAliveTimeout = 60_000;
+    httpServer.headersTimeout = 65_000;
+
     httpServer.listen(port, host, () => {
       // Write readiness file — background start polls this for out-of-band readiness detection
       try {
@@ -1521,10 +1579,13 @@ export default defineCommand({
     const gcInterval = setInterval(() => {
       maybeProbeSummary(); // Flush suppressed probe count periodically
       const now = Date.now();
+      forgetExpiredSessions(now);
+      if (SESSION_TIMEOUT_MS === 0) return;
       for (const [sid, state] of sessions) {
         const lastActive = sessionLastActivity.get(sid) ?? 0;
         if (now - lastActive > SESSION_TIMEOUT_MS) {
           console.error(`[memorix] Session ${sid.slice(0, 8)}… timed out (idle ${Math.round((now - lastActive) / 60000)}min), closing`);
+          expiredSessions.set(sid, now + EXPIRED_SESSION_TTL_MS);
           state.transport.close().catch(() => {});
           sessions.delete(sid);
           sessionLastActivity.delete(sid);

package/src/cli/heap.ts

@@ -0,0 +1,76 @@
+/**
+ * CLI heap selection for the tsup respawn banner.
+ *
+ * `memorix serve` and other long-lived commands need a large V8 heap for
+ * embeddings and the in-memory index. `memorix hook` is a per-event
+ * lifecycle process and must not reserve a 4 GB heap — copies accumulate.
+ */
+
+export const DEFAULT_CLI_HEAP_MB = 4096;
+export const DEFAULT_HOOK_HEAP_MB = 512;
+export const MIN_HEAP_MB = 64;
+export const MAX_HEAP_MB = 16_384;
+
+function parseHeapMb(raw: string | undefined, fallback: number): number {
+  if (raw === undefined || raw.trim() === '') return fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return fallback;
+  const mb = Math.floor(parsed);
+  if (mb < MIN_HEAP_MB || mb > MAX_HEAP_MB) return fallback;
+  return mb;
+}
+
+/**
+ * True when the CLI argv selects the short-lived `hook` command.
+ * `hooks` (install/status) is a different command and keeps the large heap.
+ */
+export function isHookCliInvocation(argv: string[]): boolean {
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--') break;
+    if (argument.startsWith('-')) {
+      if (!argument.includes('=') && argv[index + 1] && !argv[index + 1].startsWith('-')) {
+        index += 1;
+      }
+      continue;
+    }
+    return argument === 'hook';
+  }
+  return false;
+}
+
+export function resolveCliHeapMb(
+  argv: string[],
+  env: NodeJS.ProcessEnv = process.env,
+): number {
+  if (isHookCliInvocation(argv)) {
+    return parseHeapMb(env.MEMORIX_HOOK_HEAP_MB, DEFAULT_HOOK_HEAP_MB);
+  }
+  return parseHeapMb(env.MEMORIX_HEAP_MB, DEFAULT_CLI_HEAP_MB);
+}
+
+/**
+ * Self-contained JS prepended to the bundled CLI. It runs before the bundle
+ * loads, so the selection logic is inlined rather than imported.
+ */
+export function buildCliHeapBannerPrelude(): string {
+  return [
+    '#!/usr/bin/env node',
+    '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";',
+    '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"?${DEFAULT_HOOK_HEAP_MB}:${DEFAULT_CLI_HEAP_MB};`,
+    '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>=${MIN_HEAP_MB}&&__n<=${MAX_HEAP_MB})?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);}',
+  ].join('\n');
+}

package/src/cli/invocation.ts

@@ -1,4 +1,4 @@
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 export interface CliInvocation {
@@ -88,10 +88,13 @@ export function normalizeCliInvocation(argv: string[] = process.argv): CliInvoca
   }
 
   if (invocation.projectRoot) {
-    const projectRoot = resolve(invocation.projectRoot);
-    if (!existsSync(projectRoot) || !statSync(projectRoot).isDirectory()) {
-      throw new Error(`CLI project directory does not exist: ${projectRoot}`);
+    const resolvedProjectRoot = resolve(invocation.projectRoot);
+    if (!existsSync(resolvedProjectRoot) || !statSync(resolvedProjectRoot).isDirectory()) {
+      throw new Error(`CLI project directory does not exist: ${resolvedProjectRoot}`);
     }
+    // Keep one project identity when an OS exposes the same directory through
+    // two paths (for example /var and /private/var on macOS).
+    const projectRoot = realpathSync(resolvedProjectRoot);
     process.chdir(projectRoot);
     process.env.MEMORIX_CLI_PROJECT_ROOT = projectRoot;
     invocation.projectRoot = projectRoot;

package/src/codegraph/auto-context.ts

@@ -10,7 +10,7 @@ import {
 } from '../knowledge/workset.js';
 import type { ContextDeliveryTarget } from '../knowledge/context-assembly.js';
 import { sanitizeCredentials } from '../memory/secret-filter.js';
-import type { ObservationReader, ProjectInfo } from '../types.js';
+import type { AgentTarget, ObservationReader, ProjectInfo } from '../types.js';
 import { backfillMissingObservationCodeRefs, type CodeRefBackfillResult } from './binder.js';
 import { collectCurrentProjectFacts, formatGitFact, type CurrentProjectFacts } from './current-facts.js';
 import { refreshProjectLite } from './lite-provider.js';
@@ -189,6 +189,8 @@ export async function buildAutoProjectContext(input: {
   dataDir: string;
   observations: ProjectContextObservation[];
   task?: string;
+  /** Explicit host target for task-compatible workflow selection. */
+  agent?: AgentTarget;
   refresh?: AutoContextRefreshMode;
   maxAgeMs?: number;
   now?: Date;
@@ -426,6 +428,7 @@ export 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

package/src/codegraph/context-pack.ts

@@ -10,7 +10,7 @@ import type {
 } from './types.js';
 import type { CodeGraphStore } from './store.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
-import type { ObservationReader } from '../types.js';
+import type { AgentTarget, ObservationReader } from '../types.js';
 
 export interface ContextPackMemory {
   id: number;
@@ -278,6 +278,7 @@ export async function attachTaskWorkset(input: {
   providerQuality?: CodeGraphProviderQuality;
   runtimeCautions?: WorksetCaution[];
   reader?: ObservationReader;
+  agent?: AgentTarget;
 }): Promise<ContextPack> {
   const semanticStartHere = input.semanticCode
     ? [...input.semanticCode.relatedFiles, ...input.semanticCode.entryPoints.map(entry => entry.path)]
@@ -286,6 +287,7 @@ export 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 } : {}),

package/src/codegraph/external-provider.ts

@@ -17,6 +17,8 @@ import type {
 // Keep the default useful in real sessions while still bounding a local call.
 export const DEFAULT_EXTERNAL_CODEGRAPH_TIMEOUT_MS = 1_200;
 export const MAX_EXTERNAL_CODEGRAPH_TIMEOUT_MS = 5_000;
+/** Explicit index maintenance is opt-in and may legitimately take longer. */
+export const EXTERNAL_CODEGRAPH_LIFECYCLE_TIMEOUT_MS = 30_000;
 export const MAX_EXTERNAL_CODEGRAPH_OUTPUT_BYTES = 256 * 1024;
 const MAX_EXTERNAL_NODE_COUNT = 16;
 const MAX_EXTERNAL_EDGE_COUNT = 24;
@@ -85,6 +87,19 @@ export interface ExternalCodeGraphContextResult extends InspectExternalCodeGraph
   caution?: string;
 }
 
+/** Explicit lifecycle operations. Memorix never calls CodeGraph's `install`. */
+export type ExternalCodeGraphLifecycleAction = 'init' | 'sync';
+
+export interface ExternalCodeGraphLifecycleInput extends InspectExternalCodeGraphInput {
+  action: ExternalCodeGraphLifecycleAction;
+}
+
+export interface ExternalCodeGraphLifecycleResult extends InspectExternalCodeGraphResult {
+  action: ExternalCodeGraphLifecycleAction;
+  performed: boolean;
+  message: string;
+}
+
 interface RawExternalStatus {
   initialized: boolean;
   projectPath: string;
@@ -437,6 +452,84 @@ export async function inspectExternalCodeGraph(input: InspectExternalCodeGraphIn
   return { health, quality: providerQuality({ mode, health }) };
 }
 
+/**
+ * Run only a user-requested local lifecycle operation and re-inspect the
+ * result. This deliberately does not alter agent MCP files or invoke the
+ * upstream `codegraph install` command.
+ */
+export async function runExternalCodeGraphLifecycle(
+  input: ExternalCodeGraphLifecycleInput,
+): Promise<ExternalCodeGraphLifecycleResult> {
+  const mode = input.mode ?? 'auto';
+  if (mode === 'off') {
+    const health: ExternalCodeGraphHealth = { 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 = join(input.projectRoot, '.codegraph');
+  if (input.action === 'sync' && !existsSync(indexPath)) {
+    const health: ExternalCodeGraphHealth = { 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' && existsSync(indexPath)) {
+    const inspected = await inspectExternalCodeGraph(input);
+    return {
+      action: input.action,
+      performed: false,
+      message: 'A local CodeGraph directory already exists; no initialization was performed.',
+      ...inspected,
+    };
+  }
+
+  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: string, value: unknown, exclude?: string[]): string | undefined {
   const path = safeText(value, 1_024);
   if (!path || isAbsolute(path)) return undefined;