gossipcat 0.4.19 → 0.4.20

package/dist-mcp/mcp-server.js

@@ -51,6 +51,7 @@ var init_mcp_context = __esm({
       skillEngine: null,
       nativeTaskMap: /* @__PURE__ */ new Map(),
       nativeResultMap: /* @__PURE__ */ new Map(),
+      nativeUtilityResultMap: /* @__PURE__ */ new Map(),
       nativeAgentConfigs: /* @__PURE__ */ new Map(),
       identityRegistry: /* @__PURE__ */ new Map(),
       pendingConsensusRounds: /* @__PURE__ */ new Map(),
@@ -13675,7 +13676,10 @@ function extractFrontmatterField(content, field) {
     if (colonIdx === -1) continue;
     const key = line.slice(0, colonIdx).trim();
     if (key !== field) continue;
-    const value = line.slice(colonIdx + 1).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    if (value.length >= 2 && (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
     return value.length > 0 ? value : null;
   }
   return null;
@@ -16545,7 +16549,8 @@ ${safeSnippet}
         const trailing = relSegs.slice(relSegs.length - refSegs.length);
         return trailing.every((seg, i) => seg === refSegs[i]);
       }
-      async findFile(dir, fileName, validRoots, anchorRoot, fileRef) {
+      async findFile(dir, fileName, validRoots, anchorRoot, fileRef, depth = 0) {
+        if (depth >= 10) return null;
         try {
           const entries = await (0, import_promises3.readdir)(dir, { withFileTypes: true });
           for (const entry of entries) {
@@ -16566,7 +16571,7 @@ ${safeSnippet}
               return real;
             }
             if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== ".git") {
-              const found = await this.findFile(fullPath, fileName, validRoots, anchorRoot, fileRef);
+              const found = await this.findFile(fullPath, fileName, validRoots, anchorRoot, fileRef, depth + 1);
               if (found) return found;
             }
           }
@@ -25107,6 +25112,18 @@ var init_auth = __esm({
   }
 });
 
+// packages/relay/src/dashboard/utility-agents.ts
+function isUtilityAgent(agentId) {
+  return UTILITY_AGENT_IDS.has(agentId);
+}
+var UTILITY_AGENT_IDS;
+var init_utility_agents = __esm({
+  "packages/relay/src/dashboard/utility-agents.ts"() {
+    "use strict";
+    UTILITY_AGENT_IDS = /* @__PURE__ */ new Set(["_utility"]);
+  }
+});
+
 // packages/relay/src/dashboard/api-overview.ts
 function readSkillStatus(path2) {
   try {
@@ -25212,6 +25229,7 @@ async function overviewHandler(projectRoot, ctx2) {
         try {
           const ev = JSON.parse(line);
           if (ev.type === "task.created") {
+            if (ev.agentId && isUtilityAgent(ev.agentId)) continue;
             if (ev.taskId && ev.agentId) {
               created.set(ev.taskId, { agentId: ev.agentId, timestamp: ev.timestamp || "" });
             }
@@ -25318,6 +25336,7 @@ var init_api_overview = __esm({
     "use strict";
     import_fs42 = require("fs");
     import_path45 = require("path");
+    init_utility_agents();
   }
 });
 
@@ -25504,6 +25523,7 @@ function readTaskGraphByAgent(projectRoot) {
   }
   for (const [taskId, createdData] of created) {
     const { agentId, task, timestamp } = createdData;
+    if (isUtilityAgent(agentId)) continue;
     if (!result.has(agentId)) {
       result.set(agentId, { totalTokens: 0, lastTask: null });
     }
@@ -25620,6 +25640,7 @@ var init_api_agents = __esm({
     init_skill_index();
     import_fs44 = require("fs");
     import_path47 = require("path");
+    init_utility_agents();
     DEFAULT_SCORE = {
       agentId: "",
       accuracy: 0.5,
@@ -26292,6 +26313,7 @@ async function tasksHandler(projectRoot, query) {
   }
   const tasks = [];
   for (const [taskId, info] of created) {
+    if (isUtilityAgent(info.agentId)) continue;
     const result = completed.get(taskId);
     tasks.push({
       taskId,
@@ -26314,6 +26336,7 @@ var init_api_tasks = __esm({
     "use strict";
     import_fs53 = require("fs");
     import_path56 = require("path");
+    init_utility_agents();
   }
 });
 
@@ -26329,6 +26352,7 @@ async function activeTasksHandler(projectRoot) {
       try {
         const ev = JSON.parse(line);
         if (ev.type === "task.created" && ev.taskId) {
+          if (isUtilityAgent(ev.agentId)) continue;
           created.set(ev.taskId, { agentId: ev.agentId || "", task: ev.task || "", timestamp: ev.timestamp || "" });
         } else if (ev.type === "task.completed" || ev.type === "task.failed" || ev.type === "task.cancelled") {
           finished.add(ev.taskId);
@@ -26357,6 +26381,7 @@ var init_api_active_tasks = __esm({
     "use strict";
     import_fs54 = require("fs");
     import_path57 = require("path");
+    init_utility_agents();
   }
 });
 
@@ -43403,6 +43428,14 @@ function recordTimeoutSignal(taskId, agentId) {
   } catch {
   }
 }
+var UTILITY_RESULT_TTL_MS = 24 * 60 * 60 * 1e3;
+function scheduleNativeTaskEviction(intervalMs = 60 * 60 * 1e3) {
+  const timer = setInterval(evictStaleNativeTasks, intervalMs);
+  timer.unref();
+  return {
+    stop: () => clearInterval(timer)
+  };
+}
 function evictStaleNativeTasks() {
   const now = Date.now();
   let changed = false;
@@ -43418,6 +43451,11 @@ function evictStaleNativeTasks() {
       changed = true;
     }
   }
+  for (const [id, info] of [...ctx.nativeUtilityResultMap]) {
+    if (now - info.startedAt > UTILITY_RESULT_TTL_MS) {
+      ctx.nativeUtilityResultMap.delete(id);
+    }
+  }
   if (changed) persistNativeTaskMap();
 }
 function persistNativeTaskMap() {
@@ -43588,7 +43626,7 @@ async function handleNativeRelay(task_id, result, error48, agentStartedAt, relay
   const effectiveError = auditBlockError || error48;
   const effectiveResult = auditBlockError ? void 0 : error48 ? void 0 : result ? (auditPrefix + result).slice(0, 5e4) : result;
   ctx.nativeTaskMap.delete(task_id);
-  ctx.nativeResultMap.set(task_id, {
+  const resultRecord = {
     id: task_id,
     agentId: taskInfo.agentId,
     task: taskInfo.task,
@@ -43597,7 +43635,12 @@ async function handleNativeRelay(task_id, result, error48, agentStartedAt, relay
     error: effectiveError || void 0,
     startedAt: effectiveStart,
     completedAt: Date.now()
-  });
+  };
+  if (taskInfo.utilityType === "skill_develop") {
+    ctx.nativeUtilityResultMap.set(task_id, resultRecord);
+  } else {
+    ctx.nativeResultMap.set(task_id, resultRecord);
+  }
   if (auditBlockError) error48 = auditBlockError;
   persistNativeTaskMap();
   evictStaleNativeTasks();
@@ -43634,8 +43677,9 @@ async function handleNativeRelay(task_id, result, error48, agentStartedAt, relay
     } catch {
     }
   }
+  const completionResult = taskInfo.utilityType === "skill_develop" ? `[utility] ${taskInfo.task} \u2192 ${(result || "").length} chars` : result;
   try {
-    ctx.mainAgent.recordNativeTaskCompleted(task_id, result, error48 || void 0, elapsed ?? void 0, taskInfo.memoryQueryCalled);
+    ctx.mainAgent.recordNativeTaskCompleted(task_id, completionResult, error48 || void 0, elapsed ?? void 0, taskInfo.memoryQueryCalled);
   } catch {
   }
   if (taskInfo.writeMode && !taskInfo.utilityType && agentId !== "_utility") {
@@ -43723,7 +43767,7 @@ async function handleNativeRelay(task_id, result, error48, agentStartedAt, relay
   }
   if (!error48 && taskInfo.utilityType) {
     const utilityLabel = taskInfo.utilityType === "summary" ? "cognitive-summary" : taskInfo.utilityType === "gossip" ? "gossip-publish" : taskInfo.utilityType;
-    const utilDurationLabel = elapsed !== null ? `${(elapsed / 1e3).toFixed(1)}s` : "duration=unknown";
+    const utilDurationLabel = elapsed !== null ? `${(elapsed / 1e3).toFixed(1)}s since dispatch` : "duration=unknown";
     process.stderr.write(`[gossipcat] \u2705 utility \u2190 ${utilityLabel} [${task_id}] OK (${utilDurationLabel})
 `);
   }
@@ -45707,9 +45751,11 @@ async function doBoot() {
   };
   process.once("exit", cleanupPid);
   let shuttingDown = false;
+  const eviction = scheduleNativeTaskEviction();
   process.once("SIGTERM", async () => {
     if (shuttingDown) return;
     shuttingDown = true;
+    eviction.stop();
     process.stderr.write(`[relay] shutdown reason=SIGTERM pid=${process.pid}
 `);
     try {
@@ -45722,6 +45768,7 @@ async function doBoot() {
   process.once("SIGINT", async () => {
     if (shuttingDown) return;
     shuttingDown = true;
+    eviction.stop();
     process.stderr.write(`[relay] shutdown reason=SIGINT pid=${process.pid}
 `);
     try {
@@ -48129,7 +48176,8 @@ ${sections.join("\n\n")}` }] };
       if (_utility_task_id) {
         const stashedMeta = _pendingSkillData.get(_utility_task_id);
         _pendingSkillData.delete(_utility_task_id);
-        const utilityResult = ctx.nativeResultMap.get(_utility_task_id);
+        const utilityResult = ctx.nativeUtilityResultMap.get(_utility_task_id) ?? ctx.nativeResultMap.get(_utility_task_id);
+        ctx.nativeUtilityResultMap.delete(_utility_task_id);
         ctx.nativeResultMap.delete(_utility_task_id);
         ctx.nativeTaskMap.delete(_utility_task_id);
         const _guardBefore = _utilityGuardSnapshots.get(_utility_task_id);
@@ -48195,6 +48243,10 @@ ${preview}` }]
             timeoutMs: 12e4,
             utilityType: "skill_develop"
           });
+          try {
+            ctx.mainAgent.recordNativeTask(taskId, "_utility", `skill_develop:${category}`);
+          } catch {
+          }
           spawnTimeoutWatcher(taskId, ctx.nativeTaskMap.get(taskId));
           const modelShort = ctx.nativeUtilityConfig.model;
           return {

package/docs/HANDBOOK.md

@@ -114,6 +114,25 @@ The `verify-the-premise` skill (premise-verification Stage 1) auto-binds to ever
 - The change is documentation, CSS, test data adjustments, or log-string-only
 - Under 10 lines, no side effects on shared state, no security surface
 
+### When to gate merges on consensus — impact-adjacency, not just LOC
+
+Pre-merge consensus is cheap; bugs in trust-boundary-adjacent code are expensive. Run `gossip_dispatch(mode: "consensus", ...)` on a PR **regardless of size** when the diff touches any of:
+
+- **Shared in-memory state with lifecycle hooks** — any `Map`, `Set`, or cache where entries are added in one path and removed (or expire) in another. Race conditions and memory leaks hide here even in small diffs.
+- **Background cleanup / TTL / timer logic** — scheduled eviction, session expiry, job-queue draining, or any timer whose firing sequence is observable externally. A missed edge case silently accumulates state.
+- **Serialization at persistence boundaries** — code that writes or parses structured files (JSON config, YAML frontmatter, append-only logs, DB migrations). A format regression is invisible until a downstream reader breaks, and the blast radius is multiplicative.
+- **Authentication / authorization boundaries** — middleware, token validation, permission checks, or any decorator that gates access. A single missing condition opens the full surface behind it.
+- **Signal or event pipelines** — pub/sub routing, queue producers/consumers, or any path where message loss, duplication, or ordering is externally observable. Subtle ordering bugs are hard to reproduce after the fact.
+- **Install / bootstrap / initialization paths** — postinstall hooks, config writers, seeding scripts, or startup sequences. These run once and their failures are often silent or hard to roll back.
+
+**Why LOC alone misses these:** risk is proportional to how many concurrent systems depend on implicit assumptions, not to code size. A 40-line change to a cache eviction path or a config merge routine can introduce a memory leak or clobber user state just as easily as a 500-line feature. Let impact adjacency — not file count — trigger consensus.
+
+**Exceptions within impact-adjacent areas:**
+- Small mirror-of-existing-pattern changes (applying a previously-reviewed fix to a sibling file) don't need a fresh round; the pattern is already validated.
+- Pure log-string or comment edits inside these files are fine.
+
+**Remediation when missed:** run post-hoc consensus on the merged diff, file follow-up PRs if findings surface, and document the gap as feedback.
+
 ### Consensus protocol — 3 steps
 
 When you dispatch with `mode: "consensus"`, the orchestrator follows **three** steps. Phase 2 cross-review runs server-side automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gossipcat",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "Multi-agent orchestration for Claude Code — parallel review, consensus, adaptive dispatch",
   "mcpName": "io.github.ataberk-xyz/gossipcat",
   "repository": {

package/scripts/postinstall.js

@@ -6,7 +6,7 @@
  * Never shipped in the package tarball — always regenerated per machine.
  */
 const { join, resolve } = require('path');
-const { existsSync, writeFileSync } = require('fs');
+const { existsSync, readFileSync, writeFileSync, statSync } = require('fs');
 
 const scriptDir = __dirname;          // .../gossipcat/scripts/
 const packageRoot = resolve(scriptDir, '..'); // .../gossipcat/
@@ -19,29 +19,95 @@ const mcpServerPath = join(packageRoot, 'dist-mcp', 'mcp-server.js');
 const isGlobal = process.env.npm_config_global === 'true';
 const isGitClone = existsSync(join(packageRoot, '.git'));
 
-// For git clones: skip if .mcp.json already exists (developer already set up)
+// For git clones: skip writing if .mcp.json already exists. Still warn if the
+// built server is older than package.json — stale-build warning is the most
+// valuable signal on a developer re-running npm install after a pull.
 if (isGitClone && existsSync(join(packageRoot, '.mcp.json'))) {
+  if (existsSync(mcpServerPath)) {
+    try {
+      const serverMtime = statSync(mcpServerPath).mtime;
+      const pkgMtime = statSync(join(packageRoot, 'package.json')).mtime;
+      if (serverMtime < pkgMtime) {
+        console.log("gossipcat: dist-mcp/ is older than package.json — run 'npm run build:mcp' to rebuild");
+      }
+    } catch (_) { /* stat failure is non-fatal */ }
+  }
   console.log('gossipcat: .mcp.json already exists — skipping (git clone)');
   process.exit(0);
 }
 
 // For project-local installs: write .mcp.json into the consumer project root,
-// not into node_modules/gossipcat. Detect consumer root by walking up from
-// node_modules to the directory that contains it.
+// not into node_modules/gossipcat. Walk up from __dirname until a package.json
+// with a "workspaces" field is found OR filesystem root is reached.
 let outputDir = packageRoot; // default: package dir (global or git clone)
 if (!isGlobal && !isGitClone) {
-  // node_modules/gossipcat → node_modules → project root
-  const nodeModulesDir = resolve(packageRoot, '..');   // node_modules/
-  const projectRoot = resolve(nodeModulesDir, '..');   // project root
-  if (existsSync(join(nodeModulesDir, '..', 'package.json'))) {
-    outputDir = projectRoot;
+  let found = false;
+  // Start the walk ONE level ABOVE packageRoot so we skip gossipcat's own
+  // package.json (which has a "workspaces" field for its own monorepo layout
+  // and would otherwise match on iteration 1, writing .mcp.json into
+  // node_modules/gossipcat/ instead of the consumer's project root).
+  let dir = resolve(packageRoot, '..');
+  while (true) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(require('fs').readFileSync(pkgPath, 'utf8'));
+        if (pkg.workspaces) {
+          outputDir = dir;
+          found = true;
+          break;
+        }
+      } catch (_) { /* unparseable package.json — keep walking */ }
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+  if (!found) {
+    // Fallback: two-level walk-up from node_modules (original heuristic)
+    const nodeModulesDir = resolve(packageRoot, '..');
+    const projectRoot = resolve(nodeModulesDir, '..');
+    if (existsSync(join(projectRoot, 'package.json'))) {
+      outputDir = projectRoot;
+    } else {
+      outputDir = process.cwd();
+    }
   }
 }
 
 const mcpConfig = join(outputDir, '.mcp.json');
 
+// Preserve existing user-added MCP server entries. An existing .mcp.json may
+// carry servers other than gossipcat (e.g. another MCP tool the user has
+// installed). Unconditional overwrite would silently clobber those entries
+// on every npm install. Merge strategy:
+//   - Parse existing file if present. On JSON error, skip the write (don't
+//     destroy what we can't parse; user can fix manually).
+//   - Preserve every top-level field via spread, preserve every existing
+//     mcpServers entry, and refresh (or insert) the gossipcat entry.
+let existing = {};
+if (existsSync(mcpConfig)) {
+  try {
+    const raw = readFileSync(mcpConfig, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      existing = parsed;
+    }
+  } catch (_) {
+    console.warn(`gossipcat: existing .mcp.json at ${mcpConfig} is malformed — skipping update to avoid clobbering user config`);
+    process.exit(0);
+  }
+}
+
+const existingServers =
+  existing.mcpServers && typeof existing.mcpServers === 'object' && !Array.isArray(existing.mcpServers)
+    ? existing.mcpServers
+    : {};
+
 const config = {
+  ...existing,
   mcpServers: {
+    ...existingServers,
     gossipcat: {
       command: 'node',
       args: [mcpServerPath],
@@ -54,14 +120,37 @@ try {
   const method = isGlobal ? 'global npm' : isGitClone ? 'git clone' : 'local install';
   console.log(`gossipcat: wrote .mcp.json (${method}) → ${mcpServerPath}`);
 } catch (e) {
+  // Soft-fail on write errors: global npm installs often target root-owned dirs
+  // where EACCES is expected. Hard-exiting here would abort `npm install -g`
+  // for every user without sudo — users can re-run `gossipcat setup` after.
+  // Regression guard: tests/cli/install-packaging.test.ts:133-140.
   console.warn(`gossipcat: postinstall could not write .mcp.json (${e.code || e.message}). Run 'gossipcat setup' after install to configure.`);
 }
 
+// Staleness check: warn if dist-mcp/ is older than package.json
+if (existsSync(mcpServerPath)) {
+  try {
+    const serverMtime = statSync(mcpServerPath).mtime;
+    const pkgMtime = statSync(join(packageRoot, 'package.json')).mtime;
+    if (serverMtime < pkgMtime) {
+      console.log("gossipcat: dist-mcp/ is older than package.json — run 'npm run build:mcp' to rebuild");
+    }
+  } catch (_) { /* stat failure is non-fatal */ }
+}
+
 if (!existsSync(mcpServerPath)) {
   if (isGitClone) {
-    console.log('gossipcat: dist-mcp/mcp-server.js not built yet — run: npm run build:mcp');
+    // Git clone: build is required — run it automatically
+    const { execSync } = require('child_process');
+    console.log('gossipcat: dist-mcp/mcp-server.js not built yet — running npm run build:mcp...');
+    try {
+      execSync('npm run build:mcp', { stdio: 'inherit', cwd: packageRoot });
+    } catch (e) {
+      console.error('gossipcat: build failed. Run "npm run build:mcp" manually to complete setup.');
+      process.exit(1);
+    }
   } else {
-    console.error('gossipcat: FATAL — dist-mcp/mcp-server.js missing from package. Install is corrupted.');
+    console.error('gossipcat: FATAL — dist-mcp/mcp-server.js missing from package. Install is corrupted; reinstall with `npm install -g gossipcat` or clone the repo and run `npm install && npm run build:mcp`.');
     process.exit(1);
   }
 }