memorix 1.8.4 → 1.8.5

package/src/cli/commands/background.ts

@@ -42,6 +42,10 @@ interface BackgroundState {
   startCwd?: string;
 }
 
+const BACKGROUND_LOCK_STALE_MS = 15_000;
+const BACKGROUND_LOCK_ACQUIRE_TIMEOUT_MS = 10_000;
+const BACKGROUND_LOCK_HEARTBEAT_MS = 2_000;
+
 export function resolveBackgroundCwd(cwd: string, homeDir: string = os.homedir()): string {
   if (!isHomeDirectory(cwd, homeDir)) return cwd;
   const inherited = inheritProjectRootFromHome({
@@ -71,6 +75,10 @@ function getLogFilePath(): string {
   return getMemorixDir() + '/background.log';
 }
 
+function getBackgroundLockPath(): string {
+  return getMemorixDir() + '/background.lock';
+}
+
 function parseBoundedPositiveInteger(value: string | undefined, fallback: number, label: string, maximum: number): number {
   const raw = value ?? String(fallback);
   if (!/^[0-9]+$/u.test(raw)) {
@@ -276,20 +284,21 @@ async function startWindowsBackgroundService(options: WindowsBackgroundLaunchOpt
 }
 
 async function healthCheck(port: number, timeoutMs = 3000): Promise<{ ok: boolean; data?: any; error?: string }> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
     // Use /health endpoint — lightweight, no TeamStore or heavy init required.
     // Responds immediately once the HTTP server has bound the port.
     const res = await fetch(`http://127.0.0.1:${port}/health`, {
       signal: controller.signal,
     });
-    clearTimeout(timer);
     if (!res.ok) return { ok: false, error: `HTTP ${res.status}` };
     const data = await res.json();
     return { ok: true, data };
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : 'Unknown error' };
+  } finally {
+    clearTimeout(timer);
   }
 }
 
@@ -299,10 +308,95 @@ async function isPortInUse(port: number): Promise<boolean> {
 }
 
 // ============================================================
+// Background start lock
+// ============================================================
+
+interface BackgroundLock {
+  fd: number | null;
+  acquired: boolean;
+  path: string;
+  token: string;
+  heartbeat?: ReturnType<typeof setInterval>;
+}
+
+/**
+ * Hold an exclusive lock across the complete check/spawn/readiness sequence.
+ * The heartbeat prevents a normal slow startup from being mistaken for a
+ * crashed caller; an old lock without a live heartbeat can still be reclaimed.
+ */
+async function acquireBackgroundLock(
+  lockPath: string,
+  staleMs: number = BACKGROUND_LOCK_STALE_MS,
+  timeoutMs: number = BACKGROUND_LOCK_ACQUIRE_TIMEOUT_MS,
+): Promise<BackgroundLock> {
+  const lockDir = path.dirname(lockPath);
+  if (!fs.existsSync(lockDir)) fs.mkdirSync(lockDir, { recursive: true });
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      const token = `${process.pid}:${randomBytes(12).toString('hex')}`;
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, acquiredAt: Date.now(), token }));
+      const heartbeat = setInterval(() => {
+        try {
+          const now = new Date();
+          // Update the inode held by this descriptor. If an operator or a
+          // recovering caller replaced the path, an old owner must not touch
+          // the replacement lock's mtime and keep it alive forever.
+          fs.futimesSync(fd, now, now);
+        } catch {
+          // The owner will fail naturally if its lock was removed by an operator.
+        }
+      }, BACKGROUND_LOCK_HEARTBEAT_MS);
+      heartbeat.unref();
+      return { fd, acquired: true, path: lockPath, token, heartbeat };
+    } catch (err) {
+      if (!(err && (err as NodeJS.ErrnoException).code === 'EEXIST')) throw err;
+      try {
+      if (Date.now() - fs.statSync(lockPath).mtimeMs > staleMs) {
+          let ownerAlive = false;
+          try {
+            const raw = fs.readFileSync(lockPath, 'utf8');
+            const owner = JSON.parse(raw) as { pid?: unknown };
+            ownerAlive = typeof owner.pid === 'number'
+              && owner.pid > 0
+              && isProcessRunning(owner.pid);
+          } catch {
+            // A malformed old lock has no trustworthy owner and can be reclaimed.
+          }
+          if (!ownerAlive) {
+            fs.unlinkSync(lockPath);
+            continue;
+          }
+        }
+      } catch {
+        // Another caller may have released or reclaimed it; retry the exclusive open.
+      }
+      await new Promise(resolve => setTimeout(resolve, 200));
+    }
+  }
+
+  throw new Error(
+    `Another Memorix background start is still in progress (${lockPath}). `
+    + 'Wait a few seconds and retry; no second control plane was started.',
+  );
+}
+
+function releaseBackgroundLock(lock: BackgroundLock): void {
+  if (!lock.acquired) return;
+  if (lock.heartbeat) clearInterval(lock.heartbeat);
+  try { if (lock.fd !== null) fs.closeSync(lock.fd); } catch { /* already closed */ }
+  try {
+    const current = JSON.parse(fs.readFileSync(lock.path, 'utf8')) as { token?: unknown };
+    if (current.token === lock.token) fs.unlinkSync(lock.path);
+  } catch { /* already released, reclaimed, or malformed */ }
+}
+
 // Subcommands
 // ============================================================
 
-export async function doStart(port: number): Promise<void> {
+async function doStartUnlocked(port: number): Promise<void> {
   // 1. Check if already running — validate both PID existence AND HTTP health
   const state = loadState();
   if (state) {
@@ -491,6 +585,15 @@ export async function doStart(port: number): Promise<void> {
   process.stderr.write(footer + '\n');
 }
 
+export async function doStart(port: number): Promise<void> {
+  const lock = await acquireBackgroundLock(getBackgroundLockPath());
+  try {
+    await doStartUnlocked(port);
+  } finally {
+    releaseBackgroundLock(lock);
+  }
+}
+
 export async function doStop(): Promise<void> {
   const state = loadState();
 
@@ -559,13 +662,24 @@ export async function doStop(): Promise<void> {
   console.log('[OK] Control plane stopped.');
 }
 
-async function doStatus(): Promise<void> {
+async function doStatus(asJson = false): Promise<void> {
   const state = loadState();
 
   if (!state) {
     // No background.json — but check if port has an unmanaged foreground instance
     const portHealth = await healthCheck(3211, 2000);
     if (portHealth.ok) {
+      if (asJson) {
+        console.log(JSON.stringify({
+          status: 'unmanaged',
+          managed: false,
+          port: 3211,
+          dashboard: 'http://127.0.0.1:3211/',
+          mcp: 'http://127.0.0.1:3211/mcp',
+          health: portHealth.data ?? null,
+        }, null, 2));
+        return;
+      }
       console.log('');
       console.log('No background control plane is registered,');
       console.log('but a Memorix instance IS running on port 3211 (likely a foreground "memorix serve-http").');
@@ -585,6 +699,10 @@ async function doStatus(): Promise<void> {
       console.log('    2. Run "memorix background start"');
       console.log('');
     } else {
+      if (asJson) {
+        console.log(JSON.stringify({ status: 'stopped', managed: false, port: 3211 }, null, 2));
+        return;
+      }
       console.log('No background control plane is registered.');
       console.log('');
       console.log('Start one with:  memorix background start');
@@ -600,6 +718,36 @@ async function doStatus(): Promise<void> {
   // PID reuse detection: PID alive but /health fails or returns different PID
   const pidMismatch = health.ok && health.data?.pid && health.data.pid !== state.pid;
   const probablyReused = running && !health.ok;
+  const status = health.ok && !pidMismatch
+    ? 'running'
+    : pidMismatch
+      ? 'pid-mismatch'
+      : probablyReused
+        ? 'pid-reused'
+        : running
+          ? 'starting'
+          : 'stopped';
+
+  if (asJson) {
+    if (pidMismatch || probablyReused || !running) {
+      clearState();
+      try { fs.unlinkSync(getMemorixDir() + '/background.ready'); } catch { /* best effort */ }
+    }
+    console.log(JSON.stringify({
+      status,
+      managed: true,
+      pid: state.pid,
+      port: state.port,
+      startedAt: state.startedAt,
+      instance: state.instanceToken ? `${state.instanceToken.slice(0, 8)}…` : null,
+      dashboard: `http://127.0.0.1:${state.port}/`,
+      mcp: `http://127.0.0.1:${state.port}/mcp`,
+      logFile: normalizePath(state.logFile),
+      health: health.ok ? health.data ?? null : null,
+      error: health.ok ? null : health.error ?? (running ? 'Health check failed' : 'Process not running'),
+    }, null, 2));
+    return;
+  }
 
   console.log('');
   console.log('Memorix Background Control Plane');
@@ -629,6 +777,9 @@ async function doStatus(): Promise<void> {
     console.log(`    PID:        ${d.pid ?? 'unknown'}`);
     console.log(`    Uptime:     ${d.uptime ?? 0}s`);
     console.log(`    Mode:       ${d.mode ?? 'unknown'}`);
+    console.log(`    Profile:    ${d.profile ?? 'unknown'}`);
+    console.log(`    Project:    ${d.projectId ?? 'unresolved'}${d.projectName ? ` (${d.projectName})` : ''}`);
+    console.log(`    Ready at:   ${d.readyAt ?? 'unknown'}`);
   }
 
   if (pidMismatch) {
@@ -770,6 +921,11 @@ export default defineCommand({
       description: 'Number of log lines to show (default: 50)',
       required: false,
     },
+    json: {
+      type: 'boolean',
+      description: 'Emit a machine-readable status receipt',
+      required: false,
+    },
   },
   run: async ({ args }) => {
     try {
@@ -784,7 +940,7 @@ export default defineCommand({
           await doStop();
           break;
         case 'status':
-          await doStatus();
+          await doStatus(!!args.json);
           break;
         case 'restart':
           await doRestart(port);
@@ -813,6 +969,7 @@ export default defineCommand({
           console.log('  --port <port>   HTTP port (default: 3211)');
           console.log('  --follow, -f    Follow log output in real-time (for "logs")');
           console.log('  --lines, -n     Number of log lines to show (default: 50)');
+          console.log('  --json          Emit a machine-readable status receipt (for "status")');
           console.log('');
           console.log('Mode distinction:');
           console.log('  Quick Mode       = stdio / single project / zero friction');
@@ -838,4 +995,7 @@ export const _testing = {
   resolveBackgroundCliEntry,
   resolveBackgroundCliEntryFrom,
   resolveBackgroundCwd,
+  acquireBackgroundLock,
+  releaseBackgroundLock,
+  getBackgroundLockPath,
 };

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

@@ -27,6 +27,7 @@ import { scopeKnowledgeGraphToProject } from '../../memory/graph-scope.js';
 import { projectObservationRetention, summarizeRetentionProjections } from '../../memory/retention.js';
 import { canManageObservation, filterReadableObservations } from '../../memory/visibility.js';
 import { CURRENT_MCP_PROTOCOL_VERSION, MCP_SERVER_NAME, getMcpDiagnostics } from '../../server/mcp-diagnostics.js';
+import { createMcpStartupDiscoverResult, getMcpServerInfo } from '../../server/mcp-discovery.js';
 import { parseTcpPortOrReport } from '../port.js';
 import { mcpFileUriToPath } from '../mcp-root-path.js';
 
@@ -130,6 +131,9 @@ export default defineCommand({
     // node:fs from being evaluated before their mock factories initialize.
     const { McpBindingStore } = await import('../../server/mcp-binding-store.js');
     const { MemoryFeedbackStore } = await import('../../memory/feedback.js');
+    const { createModernMcpBridge } = await import('../../server/modern-mcp-bridge.js');
+    const { createMcpHandler } = await import('@modelcontextprotocol/server');
+    const { toNodeHandler } = await import('@modelcontextprotocol/node');
 
     // The [server] config section feeds startup defaults; CLI flags win.
     let configuredDefaults: ServeHttpConfiguredDefaults = {};
@@ -197,6 +201,32 @@ export default defineCommand({
     const statelessBindingStore = new McpBindingStore();
     await statelessBindingStore.init(persistMod.getBaseDataDir());
 
+    // Modern MCP (2026-07-28) is stateless at the protocol layer. The official
+    // v2 handler owns discovery, per-request envelopes, result metadata,
+    // subscriptions, and version errors. Product tools are bridged to the
+    // existing v1 implementation so business semantics stay in one place.
+    const modernMcpHandler = createMcpHandler(async ({ requestInfo }) => {
+      const handleId = requestInfo?.headers.get('mcp-project-handle') ?? undefined;
+      const persisted = handleId ? statelessBindingStore.touch(handleId) : undefined;
+      const requestedRoot = requestInfo?.headers.get('mcp-project-root') ?? undefined;
+      const root = persisted?.projectRoot ?? requestedRoot ?? projectRoot;
+      return createModernMcpBridge({
+        projectRoot: root,
+        allowUntrackedFallback: false,
+        deferProjectInitUntilBound: true,
+        deferProjectRuntimeInit: true,
+        dashboardMode: 'control-plane',
+        dashboardPort: port,
+        toolProfile,
+      });
+    }, {
+      // Legacy requests are routed to the existing sessionful implementation
+      // below; this handler is strict modern-only by construction.
+      legacy: 'reject',
+      responseMode: 'auto',
+    });
+    const modernNodeHandler = toNodeHandler(modernMcpHandler);
+
     type SessionState = {
       transport: InstanceType<typeof StreamableHTTPServerTransport>;
       server: Awaited<ReturnType<typeof createMemorixServer>>['server'];
@@ -418,85 +448,6 @@ export default defineCommand({
       res.setHeader('Mcp-Name', MCP_SERVER_NAME);
     }
 
-    /** Handle one 2026 stateless MCP request with a fresh server/transport. */
-    async function handleStatelessPost(req: IncomingMessage, res: ServerResponse, body: unknown): Promise<void> {
-      const handleId = typeof req.headers['mcp-project-handle'] === 'string'
-        ? req.headers['mcp-project-handle']
-        : undefined;
-      const persisted = handleId ? statelessBindingStore.touch(handleId) : undefined;
-      if (handleId && !persisted) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32001, message: 'MCP project handle not found or expired; initialize again.' }, id: null }));
-        return;
-      }
-      const requestedRoot = typeof req.headers['mcp-project-root'] === 'string'
-        ? req.headers['mcp-project-root']
-        : undefined;
-      const root = persisted?.projectRoot ?? requestedRoot ?? projectRoot;
-
-      const { createMemorixServer } = await import('../../server.js');
-      const { createProjectBindingController } = await import('../../server/request-context.js');
-      const binding = createProjectBindingController(root);
-      const { server, projectId, handleTransportClose } = await createMemorixServer(
-        root,
-        undefined,
-        undefined,
-        {
-          allowUntrackedFallback: false,
-          deferProjectInitUntilBound: true,
-          deferProjectRuntimeInit: true,
-          dashboardMode: 'control-plane',
-          dashboardPort: port,
-          toolProfile,
-          projectBinding: binding,
-        },
-      );
-      const transport = new StreamableHTTPServerTransport({
-        // No Mcp-Session-Id: the protocol state is carried by our explicit
-        // durable project handle and reconstructed on every request.
-        sessionIdGenerator: undefined,
-        enableJsonResponse: true,
-      });
-      try {
-        await server.connect(transport);
-        let effectiveHandle = persisted;
-        if (!effectiveHandle && projectId !== '__unresolved__' && isInitializeRequest(body)) {
-          effectiveHandle = statelessBindingStore.create({
-            projectId,
-            projectRoot: root,
-            dataDir: await persistMod.getProjectDataDir(projectId),
-          });
-        }
-        if (effectiveHandle) res.setHeader('Mcp-Project-Handle', effectiveHandle.handleId);
-        // The 1.30 SDK predates the 2026-07-28 version string. Keep the
-        // external stateless headers at the current contract, but normalize
-        // only the SDK-facing request and initialize params to its newest
-        // accepted wire version. This is a real compatibility adapter, not a
-        // claim that the pinned SDK implements newer optional extensions.
-        const sdkBody = body && typeof body === 'object'
-          ? JSON.parse(JSON.stringify(body)) as Record<string, any>
-          : body;
-        const sdkRequest = sdkBody as Record<string, any> | undefined;
-        if (sdkRequest && typeof sdkRequest === 'object' && sdkRequest.method === 'initialize' && sdkRequest.params) {
-          sdkRequest.params.protocolVersion = MCP_SDK_COMPAT_PROTOCOL_VERSION;
-        }
-        if (req.headers['mcp-protocol-version']) {
-          req.headers['mcp-protocol-version'] = MCP_SDK_COMPAT_PROTOCOL_VERSION;
-          for (let i = 0; i < req.rawHeaders.length; i += 2) {
-            if (req.rawHeaders[i].toLowerCase() === 'mcp-protocol-version') {
-              req.rawHeaders[i + 1] = MCP_SDK_COMPAT_PROTOCOL_VERSION;
-              break;
-            }
-          }
-        }
-        patchMcpResponse(res);
-        await transport.handleRequest(req, res, sdkBody);
-      } finally {
-        handleTransportClose();
-        await transport.close().catch(() => undefined);
-      }
-    }
-
     /**
      * Handle POST /mcp — JSON-RPC requests from agents
      */
@@ -504,13 +455,49 @@ export default defineCommand({
       const sessionId = req.headers['mcp-session-id'] as string | undefined;
       const body = await parseBody(req);
 
+      // Keep the pre-2026 startup probe compatible. Older MCP clients sent a
+      // claim-less server/discover before initialize and expect a plain JSON
+      // response; modern requests carry the _meta envelope and go to v2.
+      const params = body && typeof body === 'object' && !Array.isArray(body)
+        ? (body as { params?: unknown }).params
+        : undefined;
+      const claimlessDiscovery = !sessionId
+        && isServerDiscoverRequest(body)
+        && !req.headers['mcp-protocol-version']
+        && !req.headers['mcp-method']
+        && req.headers['mcp-stateless'] !== 'true'
+        && (params === undefined
+          || (typeof params === 'object' && params !== null && !Array.isArray(params)
+            && !Object.prototype.hasOwnProperty.call(params, '_meta')));
+      if (claimlessDiscovery) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          jsonrpc: '2.0',
+          id: (body as { id?: string | number | null }).id ?? null,
+          result: createMcpStartupDiscoverResult(getMcpServerInfo()),
+        }));
+        return;
+      }
+
       const requestedProtocol = req.headers['mcp-protocol-version'];
       const statelessRequested = req.headers['mcp-stateless'] === 'true'
         || requestedProtocol === CURRENT_MCP_PROTOCOL_VERSION
         || typeof req.headers['mcp-project-handle'] === 'string'
         || isServerDiscoverRequest(body);
       if (!sessionId && statelessRequested) {
-        await handleStatelessPost(req, res, body);
+        const handleId = typeof req.headers['mcp-project-handle'] === 'string'
+          ? req.headers['mcp-project-handle']
+          : undefined;
+        if (handleId && !statelessBindingStore.touch(handleId)) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            jsonrpc: '2.0',
+            error: { code: -32001, message: 'MCP project handle not found or expired; initialize again.' },
+            id: null,
+          }));
+          return;
+        }
+        await modernNodeHandler(req, res, body);
         return;
       }
 
@@ -1684,6 +1671,7 @@ export default defineCommand({
       }
     }
 
+    let httpReadyAt: string | null = null;
     const httpServer = createServer(async (req, res) => {
       setCorsHeaders(req, res);
 
@@ -1704,9 +1692,13 @@ export default defineCommand({
         res.end(JSON.stringify({
           status: 'ok',
           mode: 'control-plane',
+          profile: toolProfile,
           port,
           uptime: Math.round(process.uptime()),
           pid: process.pid,
+          projectId: defaultProject?.id ?? '__unresolved__',
+          projectName: defaultProject?.name ?? null,
+          readyAt: httpReadyAt,
           embedding: getEmbeddingRuntimeHealth(),
         }));
         return;
@@ -1791,6 +1783,7 @@ export default defineCommand({
     httpServer.headersTimeout = 65_000;
 
     httpServer.listen(port, host, () => {
+      httpReadyAt = new Date().toISOString();
       // Write readiness file — background start polls this for out-of-band readiness detection
       try {
         const memorixDir = (process.env.HOME || process.env.USERPROFILE || '').replace(/\\/g, '/') + '/.memorix';