archgraph-argo 0.20.5 → 0.20.7

package/argo/scripts/argo-mcp-server.js

@@ -369,6 +369,13 @@ function resolveWorkspaceRoot(args) {
 
 async function callTool(name, args = {}, progressToken = null, dependencies = undefined) {
   loadRepositoryArgoEnvironment(resolveWorkspaceRoot(args));
+  try {
+    const crash = require('./graph-rag/mcpCrashDiagnostics.js');
+    crash.installCrashDiagnostics(resolveWorkspaceRoot(args));
+    crash.markPhase('tool:' + name);
+  } catch {
+    // diagnostics are best-effort; never block a tool call
+  }
   if (name === 'initializeWorkspace') {
     const workspace = await initializeWorkspace(resolveWorkspaceRoot(args));
     // Deterministic argo-init harness report (Neo4j structural sync, semantic
@@ -777,6 +784,12 @@ async function main() {
   // server starts, rebuild the index in the BACKGROUND (async, logged) so the
   // first query rarely pays the multi-second reconstruction. No-op when aligned.
   if (process.env.ARGO_REPO_ROOT && process.env.ARGO_REPO_ROOT.trim() !== '') {
+    try {
+      require('./graph-rag/mcpCrashDiagnostics.js')
+        .installCrashDiagnostics(process.env.ARGO_REPO_ROOT);
+    } catch {
+      // diagnostics are best-effort; never block server startup
+    }
     try {
       require('./graph-rag/semanticAlignmentRunner.js')
         .preheatSemanticAlignment(process.env.ARGO_REPO_ROOT);

package/argo/scripts/graph-rag/defaultSemanticRetrieval.js

@@ -32,6 +32,9 @@ const {
 const {
   runSemanticAlignment,
 } = require('./semanticAlignmentRunner.js');
+const {
+  markPhase,
+} = require('./mcpCrashDiagnostics.js');
 
 const APPROVED_SOURCE_KEYS = Object.freeze([
   'ARGO_EMBEDDING_BASE_URL',
@@ -233,7 +236,9 @@ async function executeWpP2Retrieval({
     configuration: configurationEvidence.configuration,
     transport: composition.transport,
   });
+  markPhase('retrieval:embed:start');
   const vector = await provider.embed(request.intent);
+  markPhase('retrieval:embed:done');
   requireQualifiedVector(vector);
   const purpose = request && typeof request.purpose === 'string' ? request.purpose : '';
   const strict = AUDIT_PURPOSES.has(purpose);
@@ -250,6 +255,7 @@ async function executeWpP2Retrieval({
   const pool = rerank ? Math.max(topK, rerankOptions.poolSize) : topK;
   const channelSeeds = [];
   for (const channel of CHANNELS) {
+    markPhase('retrieval:vector:' + channel.channel);
     const vectorSeeds = await exhaustChannel({
       channel,
       neo4jDriver: composition.neo4jDriver,
@@ -260,6 +266,7 @@ async function executeWpP2Retrieval({
     });
     let seeds = vectorSeeds;
     if (hybrid) {
+      markPhase('retrieval:lexical:' + channel.channel);
       const lexicalSeeds = await exhaustLexicalChannel({
         channel,
         neo4jDriver: composition.neo4jDriver,
@@ -272,6 +279,7 @@ async function executeWpP2Retrieval({
     channelSeeds.push({ channel, seeds });
   }
   if (rerank) {
+    markPhase('retrieval:rerank:start');
     // Rerank every channel CONCURRENTLY: the LLM calls dominate latency and are
     // independent, so parallelizing turns the cost from sum(channels) into
     // ~one call. fail-open: a null/empty order keeps the original ordering.
@@ -287,6 +295,7 @@ async function executeWpP2Retrieval({
         : seeds
     )));
     channelSeeds.forEach((entry, index) => { entry.seeds = rerankedSeeds[index]; });
+    markPhase('retrieval:rerank:done');
   }
   const seedsByType = {};
   for (const { channel, seeds } of channelSeeds) {
@@ -736,6 +745,7 @@ async function exhaustChannel({
   const effectiveMax = Number.isInteger(maxSeeds) && maxSeeds > 0 ? maxSeeds : Number.POSITIVE_INFINITY;
   let offset = 0;
   while (accepted.length < effectiveMax) {
+    markPhase('retrieval:vector-window:' + channel.channel);
     const parameters = Object.freeze({
       indexName: channel.indexName,
       channel: channel.channel,

package/argo/scripts/graph-rag/mcpCrashDiagnostics.js

@@ -0,0 +1,112 @@
+'use strict';
+
+// Crash diagnostics for the ARGO MCP server. A native abort (libuv assertion) or
+// an uncaught error currently kills the server with no trace in the host log.
+// This module:
+//   - persists a "phase breadcrumb" synchronously on every phase change, so the
+//     LAST phase before a crash is always recoverable (even for native aborts
+//     that never fire JS handlers);
+//   - appends uncaught-exception (incl. unhandled-rejection, which Node raises as
+//     an uncaught exception) and process-exit records to a per-workspace crash
+//     log.
+// It uses `uncaughtExceptionMonitor` (which logs WITHOUT changing Node's default
+// crash behaviour) and never logs secret values.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+let installed = false;
+let crashLogPath = null;
+let phasePath = null;
+let currentPhase = 'startup';
+const startedAt = Date.now();
+
+function tempPath(workspaceRoot, name) {
+  return path.join(workspaceRoot, '.argo', 'temp', name);
+}
+
+function crashLogFilePath() {
+  return crashLogPath;
+}
+
+function appendCrash(entry) {
+  if (!crashLogPath) {
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(crashLogPath), { recursive: true });
+    const error = entry && entry.error;
+    const line = JSON.stringify({
+      at: new Date().toISOString(),
+      pid: process.pid,
+      uptimeMs: Date.now() - startedAt,
+      phase: currentPhase,
+      kind: entry && entry.kind,
+      ...(entry && entry.origin ? { origin: entry.origin } : {}),
+      ...(entry && entry.code !== undefined ? { code: entry.code } : {}),
+      ...(entry && entry.signal !== undefined ? { signal: entry.signal } : {}),
+      ...(error ? {
+        category: error.category,
+        message: String(error.message || error).slice(0, 1000),
+        stack: String(error.stack || '').slice(0, 4000),
+      } : {}),
+    }) + '\n';
+    fs.appendFileSync(crashLogPath, line, 'utf8');
+  } catch {
+    // best-effort diagnostics only; never throw from the crash path
+  }
+}
+
+function installCrashDiagnostics(workspaceRoot) {
+  if (workspaceRoot) {
+    crashLogPath = tempPath(workspaceRoot, 'mcp-crash.log');
+    phasePath = tempPath(workspaceRoot, 'mcp-phase.json');
+    markPhase(currentPhase);
+  }
+  if (installed) {
+    return;
+  }
+  installed = true;
+  // Logs without altering Node's default crash behaviour (unlike a bare
+  // 'uncaughtException' listener, which would swallow the crash).
+  process.on('uncaughtExceptionMonitor', (error, origin) => {
+    appendCrash({ kind: 'uncaughtException', origin, error });
+  });
+  process.on('exit', (code, signal) => {
+    appendCrash({ kind: 'exit', code: code === undefined ? null : code, signal: signal === undefined ? null : signal });
+  });
+}
+
+// Synchronous breadcrumb: guarantees the last phase survives a hard abort.
+function markPhase(phase) {
+  currentPhase = String(phase === undefined || phase === null ? '' : phase);
+  if (!phasePath) {
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(phasePath), { recursive: true });
+    fs.writeFileSync(phasePath, JSON.stringify({
+      phase: currentPhase,
+      at: new Date().toISOString(),
+      pid: process.pid,
+    }) + '\n', 'utf8');
+  } catch {
+    // best-effort
+  }
+}
+
+function readLastPhase(workspaceRoot) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(tempPath(workspaceRoot, 'mcp-phase.json'), 'utf8'));
+    return parsed && typeof parsed.phase === 'string' ? parsed.phase : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  installCrashDiagnostics,
+  markPhase,
+  readLastPhase,
+  crashLogFilePath,
+};

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -1,6 +1,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
-const { spawn } = require('node:child_process');
+const { spawn, spawnSync } = require('node:child_process');
+const { markPhase } = require('./graph-rag/mcpCrashDiagnostics.js');
 const readline = require('node:readline');
 const crypto = require('node:crypto');
 
@@ -1768,6 +1769,7 @@ function removeEntries(existing, removals) {
 }
 
 async function buildMutationResult(context, mutations, write, dependencies) {
+  markPhase('mutation:' + (write ? 'apply' : 'preview'));
   const beforeSummary = summarizeDocument(context.document);
   let mutationResult;
   try {
@@ -1855,6 +1857,7 @@ async function buildMutationResult(context, mutations, write, dependencies) {
   // but ALWAYS reported on the result (passed / failed / noop+reason) so a missing EA
   // update is never silent.
   {
+    markPhase('mutation:qeaProjection');
     const resolved = resolveQeaProjectionTarget(context);
     const qeaTarget = resolved && resolved.target;
     if (qeaTarget) {
@@ -1883,6 +1886,7 @@ async function buildMutationResult(context, mutations, write, dependencies) {
   }
 
   if (shouldSyncCanonicalGraphToNeo4j(context.graphPath.relativePath)) {
+    markPhase('mutation:neo4jSync');
     try {
       const syncResult = await syncArchitectureToNeo4j({
         architecturePath: context.graphPath.relativePath,
@@ -1907,7 +1911,9 @@ async function buildMutationResult(context, mutations, write, dependencies) {
     }
   }
 
+  markPhase('mutation:embeddingLifecycle');
   await attachMutationEmbeddingLifecycle(context, result, mutationResult.document);
+  markPhase('mutation:done');
 
   return result;
 }
@@ -2127,33 +2133,35 @@ function resolveQeaProjectionTarget(context) {
 }
 
 function runQeaProjection(target) {
-  return new Promise((resolve) => {
-    const script = path.join(__dirname, 'ea-qea-sync.js');
-    if (!fs.existsSync(script)) {
-      resolve({ ok: false, error: 'argo/scripts/ea-qea-sync.js missing', ms: 0 });
-      return;
-    }
-    const snapshotDir = path.join(target.workspaceRoot, '.argo', 'temp', 'qea-backups');
-    // -y enables the projection-owned delete reconcile: objects that carry a schema anchor
-    // (t_object.Alias / t_connectortag schema_id) but are no longer in canonical are removed
-    // from the .qea, so a graph-side deletion actually disappears from EA on the next
-    // projection. Human-drawn (un-anchored) content is never a delete candidate.
-    const args = [script, '--mode', 'sync', '--graph', target.graphPath, '--qea', target.qeaPath, '--snapshot-dir', snapshotDir, '-y'];
-    const started = Date.now();
-    let stderr = '';
-    let child;
-    try {
-      child = spawn(process.execPath, args, { cwd: target.workspaceRoot, windowsHide: true });
-    } catch (error) {
-      resolve({ ok: false, error: String(error && error.message ? error.message : error), ms: Date.now() - started });
-      return;
-    }
-    child.stderr.on('data', (d) => { stderr += String(d); });
-    child.on('error', (err) => resolve({ ok: false, error: String(err && err.message ? err.message : err), ms: Date.now() - started, stderr: stderr.slice(0, 600) }));
-    child.on('close', (code) => {
-      resolve({ ok: code === 0, code, ms: Date.now() - started, stderr: stderr.slice(0, 600) });
-    });
-  });
+  // Synchronous child: this runs right before the async Neo4j sync + embedding
+  // lifecycle. An async child leaves a libuv handle closing while subsequent
+  // async I/O (fetch / neo4j-driver) proceeds, which on Windows can trip a
+  // native `UV_HANDLE_CLOSING` assertion and abort the whole MCP. spawnSync has
+  // no lingering handle (~150ms, bounded); the caller's `await` still applies.
+  const script = path.join(__dirname, 'ea-qea-sync.js');
+  const started = Date.now();
+  if (!fs.existsSync(script)) {
+    return { ok: false, error: 'argo/scripts/ea-qea-sync.js missing', ms: 0 };
+  }
+  const snapshotDir = path.join(target.workspaceRoot, '.argo', 'temp', 'qea-backups');
+  // -y enables the projection-owned delete reconcile: objects that carry a schema anchor
+  // (t_object.Alias / t_connectortag schema_id) but are no longer in canonical are removed
+  // from the .qea, so a graph-side deletion actually disappears from EA on the next
+  // projection. Human-drawn (un-anchored) content is never a delete candidate.
+  const args = [script, '--mode', 'sync', '--graph', target.graphPath, '--qea', target.qeaPath, '--snapshot-dir', snapshotDir, '-y'];
+  try {
+    const res = spawnSync(process.execPath, args, { cwd: target.workspaceRoot, windowsHide: true, encoding: 'utf8', timeout: 120000 });
+    const ok = res.status === 0;
+    return {
+      ok,
+      code: res.status,
+      ms: Date.now() - started,
+      stderr: String(res.stderr || '').slice(0, 600),
+      ...(ok ? {} : { error: String((res.stderr || '').slice(0, 600) || ('exit ' + res.status)) }),
+    };
+  } catch (error) {
+    return { ok: false, error: String(error && error.message ? error.message : error), ms: Date.now() - started };
+  }
 }
 
 function writeGraph(graphPath, document) {
@@ -2764,6 +2772,7 @@ function evaluateSemanticDedupGate(advisory, mutations) {
 }
 
 async function buildSemanticDedupAdvisory(context, mutations, dependencies) {
+  markPhase('mutation:semanticDedup');
   if (process.env.ARGO_MCP_SEMANTIC_DEDUP === '0') {
     return undefined;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.20.5",
+  "version": "0.20.7",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {