archgraph-argo 0.20.4 → 0.20.6

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/ensureArgoHarnessEnvironment.js

@@ -38,7 +38,13 @@ const REQUIRED_TOOL_NAMES = [
 // `includeBootstrap` is true for the standalone CLI (it calls initializeWorkspace
 // to bootstrap the workspace); the initializeWorkspace MCP tool passes false
 // because it already bootstrapped — avoids re-entrancy through ensureWorkspaceBootstrap.
-async function buildHarnessReport({ checkOnly = false, workspaceRoot, includeBootstrap = true }) {
+async function buildHarnessReport(options = {}) {
+  const { checkOnly = false, workspaceRoot, includeBootstrap = true } = options;
+  const { withAlignmentLock } = require('./graph-rag/semanticAlignmentLock.js');
+  return withAlignmentLock(workspaceRoot, () => runHarnessReport({ checkOnly, workspaceRoot, includeBootstrap }));
+}
+
+async function runHarnessReport({ checkOnly, workspaceRoot, includeBootstrap }) {
   const reportPath = path.join(workspaceRoot, '.argo', 'temp', 'argo-harness-init-report.json');
   const report = {
     status: 'ok',

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,6 +236,7 @@ async function executeWpP2Retrieval({
     configuration: configurationEvidence.configuration,
     transport: composition.transport,
   });
+  markPhase('retrieval:embed');
   const vector = await provider.embed(request.intent);
   requireQualifiedVector(vector);
   const purpose = request && typeof request.purpose === 'string' ? request.purpose : '';
@@ -272,6 +276,7 @@ async function executeWpP2Retrieval({
     channelSeeds.push({ channel, seeds });
   }
   if (rerank) {
+    markPhase('retrieval:rerank');
     // 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.

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/graph-rag/semanticAlignmentLock.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// Cross-process, single-flight lock for the heavy semantic-index alignment
+// (workspace bootstrap + semantic backfill + Neo4j sync + EA projection). Any
+// invocation that can rebuild the index -- the MCP startup preheat, the
+// query-path auto-alignment, and an explicit `argo init` (initializeWorkspace),
+// in this process or another -- acquires this lock, so they serialize instead of
+// racing (duplicate embeddings, concurrent Neo4j upserts, concurrent .qea
+// rebuild, readiness/report races).
+//
+// The lock is a regular file created with `wx` under <workspace>/.argo/temp. A
+// holder that crashes leaves a stale file; a lock older than `staleMs` is stolen.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCK_RELATIVE_PATH = path.join('.argo', 'temp', 'semantic-alignment.lock');
+const DEFAULT_WAIT_MS = 10 * 60 * 1000;
+const DEFAULT_STALE_MS = 15 * 60 * 1000;
+
+function alignmentLockPath(repositoryRoot) {
+  return path.join(repositoryRoot, ...LOCK_RELATIVE_PATH.split(path.sep));
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function withAlignmentLock(repositoryRoot, action, options = {}) {
+  const waitMs = Number.isFinite(options.waitMs) && options.waitMs > 0 ? options.waitMs : DEFAULT_WAIT_MS;
+  const staleMs = Number.isFinite(options.staleMs) && options.staleMs > 0 ? options.staleMs : DEFAULT_STALE_MS;
+  const file = alignmentLockPath(repositoryRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const deadline = Date.now() + waitMs;
+  let fd = null;
+  for (;;) {
+    try {
+      fd = fs.openSync(file, 'wx');
+      break;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') {
+        throw error;
+      }
+      let stale = false;
+      try {
+        stale = (Date.now() - fs.statSync(file).mtimeMs) > staleMs;
+      } catch {
+        stale = true;
+      }
+      if (stale) {
+        try { fs.unlinkSync(file); } catch { /* raced with another stealer */ }
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        const timeout = new Error('SEMANTIC_ALIGNMENT_LOCK_TIMEOUT');
+        timeout.category = 'SEMANTIC_ALIGNMENT_LOCK_TIMEOUT';
+        timeout.message = 'Another semantic alignment is already running and did not finish in time.';
+        timeout.action = 'Wait for the running alignment (argo init) to finish, then retry.';
+        throw timeout;
+      }
+      await sleep(250);
+    }
+  }
+  try {
+    try { fs.writeSync(fd, String(process.pid)); } catch { /* best-effort owner marker */ }
+    return await action();
+  } finally {
+    try { fs.closeSync(fd); } catch { /* ignore */ }
+    try { fs.unlinkSync(file); } catch { /* already gone */ }
+  }
+}
+
+module.exports = {
+  withAlignmentLock,
+  alignmentLockPath,
+};

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

@@ -34,6 +34,18 @@ function isSemanticReady(repositoryRoot) {
   }
 }
 
+// A project is "initialized" once its canonical graph exists. The startup
+// preheat must NEVER bootstrap a brand-new project: creating files / running a
+// full backfill for an unknown workspace in the background is surprising and
+// would race an explicit `argo init`. New projects initialize explicitly.
+function isProjectInitialized(repositoryRoot) {
+  try {
+    return fs.existsSync(path.join(repositoryRoot, 'design', 'KG', 'SystemArchitecture.json'));
+  } catch {
+    return false;
+  }
+}
+
 function alignmentError() {
   const error = new Error('SEMANTIC_AUTO_ALIGNMENT_FAILED');
   error.category = 'SEMANTIC_AUTO_ALIGNMENT_FAILED';
@@ -79,7 +91,7 @@ function runSemanticAlignment(repositoryRoot = getWorkspaceRoot()) {
 // otherwise it starts the rebuild in the background so the first query rarely
 // pays for it. Safe to call repeatedly (guarded + de-duplicated).
 function preheatSemanticAlignment(repositoryRoot = getWorkspaceRoot()) {
-  if (preheated || !repositoryRoot || isSemanticReady(repositoryRoot)) {
+  if (preheated || !repositoryRoot || !isProjectInitialized(repositoryRoot) || isSemanticReady(repositoryRoot)) {
     return;
   }
   preheated = true;
@@ -91,5 +103,6 @@ module.exports = {
   runSemanticAlignment,
   preheatSemanticAlignment,
   isSemanticReady,
+  isProjectInitialized,
   readinessRecordPath,
 };

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.4",
+  "version": "0.20.6",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {