u-foo 2.3.11 → 2.3.13

package/src/agent/ucodeBootstrap.js

@@ -1,6 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const { getUfooPaths } = require("../ufoo/paths");
+const { buildDefaultStartupBootstrapPrompt } = require("./defaultBootstrap");
 
 function readFileSafe(filePath = "") {
   if (!filePath) return "";
@@ -74,11 +75,27 @@ function buildBootstrapContent({
   return `${lines.join("\n")}\n`;
 }
 
+function hasUfooProtocolPrompt(promptText = "") {
+  const text = String(promptText || "");
+  return text.includes("ufoo protocol:") && text.includes("ufoo ctx decisions -l");
+}
+
+function mergeDefaultUfooProtocolPrompt(projectRoot = "", promptText = "") {
+  const currentPrompt = String(promptText || "").trim();
+  if (hasUfooProtocolPrompt(currentPrompt)) return currentPrompt;
+  const defaultPrompt = buildDefaultStartupBootstrapPrompt({
+    agentType: "ufoo-code",
+    projectRoot,
+  }).trim();
+  return [defaultPrompt, currentPrompt].filter(Boolean).join("\n\n");
+}
+
 function prepareUcodeBootstrap({
   projectRoot = process.cwd(),
   promptFile = "",
   promptText = "",
   targetFile = "",
+  includeDefaultProtocol = true,
 } = {}) {
   const resolvedProjectRoot = path.resolve(projectRoot);
   const resolvedPrompt = String(promptFile || "").trim();
@@ -86,11 +103,14 @@ function prepareUcodeBootstrap({
 
   const inlinePromptText = String(promptText || "").trim();
   const resolvedPromptText = inlinePromptText || readFileSafe(resolvedPrompt);
+  const finalPromptText = includeDefaultProtocol
+    ? mergeDefaultUfooProtocolPrompt(resolvedProjectRoot, resolvedPromptText)
+    : resolvedPromptText;
   const rules = resolveProjectRules(resolvedProjectRoot);
   const content = buildBootstrapContent({
     projectRoot: resolvedProjectRoot,
     promptFile: resolvedPrompt,
-    promptText: resolvedPromptText,
+    promptText: finalPromptText,
     rules,
   });
 
@@ -107,6 +127,8 @@ function prepareUcodeBootstrap({
 }
 
 module.exports = {
+  hasUfooProtocolPrompt,
+  mergeDefaultUfooProtocolPrompt,
   readFileSafe,
   resolveProjectRules,
   defaultBootstrapPath,

package/src/agent/ufooAgent.js

@@ -1,7 +1,5 @@
 const fs = require("fs");
 const path = require("path");
-const { runCliAgent } = require("./cliRunner");
-const { normalizeCliOutput } = require("./normalizeOutput");
 const { buildStatus } = require("../daemon/status");
 const { getUfooPaths } = require("../ufoo/paths");
 const { normalizeGateRouterResult } = require("../controller/gateRouter");
@@ -633,7 +631,6 @@ async function runUfooAgent({
   loopRuntime = null,
   controllerMode = null,
 }) {
-  const state = loadSessionState(projectRoot);
   const mode = String(routingMode || (routingContext && routingContext.mode) || "").trim().toLowerCase();
   const resolvedControllerMode = String(
     controllerMode
@@ -660,7 +657,6 @@ async function runUfooAgent({
   let res;
 
   const useDirectProvider = shouldUseDirectProvider(provider);
-  let usedDirectProvider = false;
 
   if (useDirectProvider) {
     res = await runNativeRouterCall({
@@ -671,47 +667,22 @@ async function runUfooAgent({
       model,
     });
     if (!res.ok) {
+      // eslint-disable-next-line no-console
+      console.error(`[ufoo-agent] native provider failed: ${res.error || "unknown error"}`);
       return { ok: false, error: res.error };
     } else {
-      usedDirectProvider = true;
       res = { ok: true, output: res.output, sessionId: "", provider: res.provider, model: res.model };
     }
   }
 
   if (!useDirectProvider) {
-    res = await runCliAgent({
-      provider,
-      model,
-      prompt: fullPrompt,
-      systemPrompt,
-      sessionId: state.data?.sessionId,
-      disableSession: provider === "claude-cli",
-      cwd: projectRoot,
-    });
-
-    if (!res.ok) {
-      const msg = (res.error || "").toLowerCase();
-      if (msg.includes("session id") || msg.includes("session-id") || msg.includes("already in use")) {
-        res = await runCliAgent({
-          provider,
-          model,
-          prompt: fullPrompt,
-          systemPrompt,
-          sessionId: undefined,
-          disableSession: provider === "claude-cli",
-          cwd: projectRoot,
-        });
-      }
-    }
-
-    if (!res.ok) {
-      return { ok: false, error: res.error };
-    }
+    const error = `unsupported ufoo-agent provider "${provider || ""}"; cliRunner fallback has been removed`;
+    // eslint-disable-next-line no-console
+    console.error(`[ufoo-agent] ${error}`);
+    return { ok: false, error };
   }
 
-  const rawText = usedDirectProvider
-    ? String(res.output || "").trim()
-    : normalizeCliOutput(res.output);
+  const rawText = String(res.output || "").trim();
   const text = stripMarkdownFence(rawText);
   let payload = null;
   try {

package/src/bus/index.js

@@ -60,7 +60,8 @@ class EventBus {
     this.queueManager = new QueueManager(this.busDir);
     this.subscriberManager = new SubscriberManager(
       this.busData,
-      this.queueManager
+      this.queueManager,
+      { agentsFile: this.agentsFile }
     );
     this.messageManager = new MessageManager(
       this.busDir,

package/src/bus/store.js

@@ -5,6 +5,7 @@ const path = require("path");
 const { getTimestamp, ensureDir, safeNameToSubscriber, getTtyProcessInfo } = require("./utils");
 const { getUfooPaths } = require("../ufoo/paths");
 const { loadAgentsData, saveAgentsData } = require("../ufoo/agentsStore");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 
 function readQueueTty(queueDir) {
   try {
@@ -25,7 +26,7 @@ function buildUsedNicknameSet(agents = {}) {
   return set;
 }
 
-function recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now) {
+function recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now, agentsFile) {
   if (!subscriber || data.agents[subscriber]) return false;
 
   if (subscriber === "ufoo-agent") {
@@ -45,6 +46,17 @@ function recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now) {
     };
     return true;
   }
+  appendAgentRegistryDiagnostic(
+    agentsFile,
+    "queue_entry_not_recovered",
+    {
+      source: "bus.store.recoverQueueEntry",
+      subscriber,
+      queue_dir: queueDir,
+      reason: "non_controller_queue_without_registry_entry",
+      used_nicknames: Array.from(usedNicknames || []).sort(),
+    }
+  );
   return false;
 }
 
@@ -112,20 +124,20 @@ class BusStore {
       if (!stat.isDirectory()) continue;
 
       const subscriber = safeNameToSubscriber(entry);
-      recovered = recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now) || recovered;
+      recovered = recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now, this.agentsFile) || recovered;
     }
 
     recovered = reconcileReservedControllerAliases(data, now) || recovered;
 
     if (recovered) {
-      saveAgentsData(this.agentsFile, data);
+      saveAgentsData(this.agentsFile, data, { source: "bus.store.load.recoverQueueEntry", trace: true });
     }
     return data;
   }
 
   save(busData) {
     if (busData) {
-      saveAgentsData(this.agentsFile, busData);
+      saveAgentsData(this.agentsFile, busData, { source: "bus.store.save" });
     }
   }
 
@@ -144,7 +156,7 @@ class BusStore {
         created_at: getTimestamp(),
         agents: {},
       };
-      saveAgentsData(this.agentsFile, busData);
+      saveAgentsData(this.agentsFile, busData, { source: "bus.store.init", trace: true });
     }
   }
 

package/src/bus/subscriber.js

@@ -2,6 +2,7 @@ const fs = require("fs");
 const { getTimestamp, isAgentPidAlive, isMetaActive, isValidTty, getTtyProcessInfo } = require("./utils");
 const NicknameManager = require("./nickname");
 const { spawnSync } = require("child_process");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 
 function detectTerminalAppFromEnv() {
   const termProgram = process.env.TERM_PROGRAM || "";
@@ -102,9 +103,14 @@ function hasProviderSession(meta) {
  * 订阅者管理
  */
 class SubscriberManager {
-  constructor(busData, queueManager) {
+  constructor(busData, queueManager, options = {}) {
     this.busData = busData;
     this.queueManager = queueManager;
+    this.agentsFile = options.agentsFile || "";
+  }
+
+  logRegistry(event, payload = {}) {
+    appendAgentRegistryDiagnostic(this.agentsFile, event, payload);
   }
 
   cleanupSubscriberArtifacts(subscriber) {
@@ -152,6 +158,15 @@ class SubscriberManager {
           inheritedNickname = meta.nickname;
         }
         // Remove stale subscriber using same tty
+        this.logRegistry("cleanup_duplicate_tty", {
+          source: "bus.subscriber.cleanupDuplicateTty",
+          subscriber: id,
+          replacement: currentSubscriber,
+          tty: ttyPath,
+          same_agent_type: sameAgentType,
+          status: meta?.status || "",
+          nickname: meta?.nickname || "",
+        });
         delete this.busData.agents[id];
         try {
           const queueDir = this.queueManager.getQueueDir(id);
@@ -420,6 +435,16 @@ class SubscriberManager {
         const recoverable = hasProviderSession(meta);
         if (meta.status === "inactive") {
           if (!recoverable) {
+            this.logRegistry("cleanup_inactive_delete", {
+              source: "bus.subscriber.cleanupInactive",
+              subscriber: id,
+              reason: "internal_already_inactive_without_provider_session",
+              status: meta.status || "",
+              launch_mode: meta.launch_mode || "",
+              pid: meta.pid || 0,
+              tty: meta.tty || "",
+              last_seen: meta.last_seen || "",
+            });
             delete this.busData.agents[id];
             this.cleanupSubscriberArtifacts(id);
           }
@@ -427,11 +452,31 @@ class SubscriberManager {
         }
         if (!isMetaActive(meta)) {
           if (recoverable) {
+            this.logRegistry("cleanup_inactive_mark", {
+              source: "bus.subscriber.cleanupInactive",
+              subscriber: id,
+              reason: "internal_inactive_but_recoverable_provider_session",
+              status: meta.status || "",
+              launch_mode: meta.launch_mode || "",
+              pid: meta.pid || 0,
+              tty: meta.tty || "",
+              last_seen: meta.last_seen || "",
+            });
             meta.status = "inactive";
             meta.activity_state = "";
             meta.last_seen = getTimestamp();
             this.cleanupSubscriberArtifacts(id);
           } else {
+            this.logRegistry("cleanup_inactive_delete", {
+              source: "bus.subscriber.cleanupInactive",
+              subscriber: id,
+              reason: "internal_inactive_without_provider_session",
+              status: meta.status || "",
+              launch_mode: meta.launch_mode || "",
+              pid: meta.pid || 0,
+              tty: meta.tty || "",
+              last_seen: meta.last_seen || "",
+            });
             delete this.busData.agents[id];
             this.cleanupSubscriberArtifacts(id);
           }
@@ -439,6 +484,17 @@ class SubscriberManager {
         continue;
       }
       if (meta.status === "active" && !isMetaActive(meta)) {
+        this.logRegistry("cleanup_inactive_mark", {
+          source: "bus.subscriber.cleanupInactive",
+          subscriber: id,
+          reason: "active_meta_failed_liveness",
+          status: meta.status || "",
+          launch_mode: meta.launch_mode || "",
+          pid: meta.pid || 0,
+          tty: meta.tty || "",
+          tty_shell_pid: meta.tty_shell_pid || 0,
+          last_seen: meta.last_seen || "",
+        });
         meta.status = "inactive";
         meta.activity_state = "";
         meta.last_seen = getTimestamp();

package/src/bus/utils.js

@@ -3,6 +3,7 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 const { redactSecrets } = require("../providerapi/redactor");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 
 /**
  * 获取当前 UTC 时间戳（ISO 8601 格式）
@@ -200,6 +201,11 @@ function readJSON(filePath, defaultValue = null) {
     const content = fs.readFileSync(filePath, "utf8");
     return JSON.parse(content);
   } catch (err) {
+    appendAgentRegistryDiagnostic(filePath, "read_json_failed", {
+      source: "bus.utils.readJSON",
+      error: err && err.message ? err.message : String(err || "unknown"),
+      default_returned: defaultValue === null ? "null" : typeof defaultValue,
+    });
     return defaultValue;
   }
 }

package/src/chat/daemonMessageRouter.js

@@ -442,7 +442,9 @@ function createDaemonMessageRouter(options = {}) {
   }
 
   function handleErrorMessage(msg) {
-    resolveStatusLine(`{gray-fg}✗{/gray-fg} Error: ${msg.error}`);
+    const error = String(msg.error || "unknown error");
+    resolveStatusLine(`{gray-fg}✗{/gray-fg} Error: ${error}`);
+    logMessage("error", `{white-fg}✗{/white-fg} ${escapeBlessed(error)}`);
     renderScreen();
     return false;
   }

package/src/chat/dashboardKeyController.js

@@ -1,4 +1,4 @@
-const DEFAULT_MODE_OPTIONS = ["auto", "host", "terminal", "tmux", "internal"];
+const DEFAULT_MODE_OPTIONS = ["auto", "host", "terminal", "tmux", "internal-pty", "internal"];
 
 function createDashboardKeyController(options = {}) {
   const {

package/src/chat/dashboardView.js

@@ -1,6 +1,6 @@
 const { clampAgentWindowWithSelection } = require("./agentDirectory");
 
-const DEFAULT_MODE_OPTIONS = ["auto", "host", "terminal", "tmux", "internal"];
+const DEFAULT_MODE_OPTIONS = ["auto", "host", "terminal", "tmux", "internal-pty", "internal"];
 
 function providerLabel(value) {
   if (value === "claude-cli") return "claude";

package/src/chat/index.js

@@ -65,7 +65,7 @@ const {
   pruneTransientAgentStates,
 } = require("./transientAgentState");
 
-const MODE_OPTIONS = ["auto", "host", "terminal", "tmux", "internal"];
+const MODE_OPTIONS = ["auto", "host", "terminal", "tmux", "internal-pty", "internal"];
 
 async function runChat(projectRoot, options = {}) {
   const globalMode = options && options.globalMode === true;

package/src/config.js

@@ -29,6 +29,7 @@ const DEFAULT_UCODE_CONFIG = {
 function normalizeLaunchMode(value) {
   if (value === "auto") return "auto";
   if (value === "internal") return "internal";
+  if (value === "internal-pty") return "internal-pty";
   if (value === "tmux") return "tmux";
   if (value === "terminal") return "terminal";
   if (value === "host") return "host";

package/src/daemon/ops.js

@@ -14,6 +14,7 @@ const {
 const {
   createSession: createHostSession,
 } = require("../terminal/adapters/hostAdapter");
+const { resolveDefaultManualBootstrap } = require("../agent/defaultBootstrap");
 
 function normalizeLaunchAgent(agent = "") {
   const value = String(agent || "").trim().toLowerCase();
@@ -44,6 +45,43 @@ function toTmuxBinary(agent = "") {
   return "";
 }
 
+function applyDefaultManagedBootstrap(projectRoot, normalizedAgent, args = [], extraEnv = {}) {
+  const agentType = toBusAgentType(normalizedAgent);
+  if (!agentType || agentType === "ufoo-code") {
+    return {
+      args: Array.isArray(args) ? args.slice() : [],
+      extraEnv: extraEnv && typeof extraEnv === "object" ? { ...extraEnv } : {},
+      applied: false,
+    };
+  }
+
+  const currentArgs = Array.isArray(args) ? args.slice() : [];
+  const currentExtraEnv = extraEnv && typeof extraEnv === "object" ? { ...extraEnv } : {};
+  const resolved = resolveDefaultManualBootstrap({
+    projectRoot,
+    agentType,
+    args: currentArgs,
+    env: {
+      ...process.env,
+      ...currentExtraEnv,
+    },
+  });
+
+  if (!resolved || resolved.mode === "skip") {
+    return { args: currentArgs, extraEnv: currentExtraEnv, applied: false };
+  }
+
+  return {
+    args: Array.isArray(resolved.args) ? resolved.args : currentArgs,
+    extraEnv: {
+      ...currentExtraEnv,
+      ...(resolved.env && typeof resolved.env === "object" ? resolved.env : {}),
+      UFOO_SKIP_DEFAULT_BOOTSTRAP: "1",
+    },
+    applied: true,
+  };
+}
+
 function resolveUfooRunnerPath() {
   return path.resolve(__dirname, "../../bin/ufoo.js");
 }
@@ -116,7 +154,7 @@ function resolveHostLaunchContext(options = {}) {
 
 function resolveConfiguredLaunchMode(configuredMode = "", options = {}) {
   const mode = normalizeOptionalString(configuredMode);
-  if (mode === "internal" || mode === "tmux" || mode === "terminal" || mode === "host") {
+  if (mode === "internal" || mode === "internal-pty" || mode === "tmux" || mode === "terminal" || mode === "host") {
     return mode;
   }
   const hostContext = resolveHostLaunchContext(options);
@@ -518,7 +556,9 @@ async function spawnManagedHostAgent(
     subscriberId = "";
   }
 
-  const args = Array.isArray(extraArgs) ? extraArgs : [];
+  const hostBootstrap = applyDefaultManagedBootstrap(projectRoot, normalizedAgent, extraArgs, extraEnv);
+  const args = hostBootstrap.args;
+  const hostExtraEnv = hostBootstrap.extraEnv;
   const argText = args.length > 0 ? ` ${args.map(shellEscape).join(" ")}` : "";
 
   const titleCmd = buildTitleCmd(nickname);
@@ -538,8 +578,8 @@ async function spawnManagedHostAgent(
     env.UFOO_NICKNAME = nickname;
   }
   // Parse extraEnv string (e.g., "UFOO_UCODE_BOOTSTRAP_FILE=/path/to/file") and add to env
-  if (extraEnv && typeof extraEnv === "object") {
-    for (const [key, value] of Object.entries(extraEnv)) {
+  if (hostExtraEnv && typeof hostExtraEnv === "object") {
+    for (const [key, value] of Object.entries(hostExtraEnv)) {
       if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(key || ""))) {
         env[String(key)] = String(value ?? "");
       }
@@ -645,7 +685,9 @@ async function spawnInternalAgent(
       ? (count > 1 ? `${nickname}-${i + 1}` : nickname)
       : "";
     const providerSessionId = typeof options.providerSessionId === "string" ? options.providerSessionId.trim() : "";
-    const usePty = process.env.UFOO_INTERNAL_PTY !== "0";
+    const usePty = typeof options.usePty === "boolean"
+      ? options.usePty
+      : process.env.UFOO_INTERNAL_PTY !== "0";
     const launchMode = usePty ? "internal-pty" : "internal";
 
     // 传递 launch_mode 和 parent PID 到 join
@@ -657,8 +699,9 @@ async function spawnInternalAgent(
     const finalNickname = joinResult.nickname || requestedNickname || "";
     bus.saveBusData();
 
+    const managedBootstrap = applyDefaultManagedBootstrap(projectRoot, normalizedAgent, extraArgs, extraEnv);
     const runnerCmd = usePty ? "agent-pty-runner" : "agent-runner";
-    const args = Array.isArray(extraArgs) ? extraArgs : [];
+    const args = managedBootstrap.args;
     const child = spawn(process.execPath, [runner, runnerCmd, agent, ...args], {
       // 关键改动：不使用 detached，daemon 作为父进程
       detached: false,
@@ -666,7 +709,7 @@ async function spawnInternalAgent(
       cwd: projectRoot,
       env: {
         ...process.env,
-        ...(extraEnv && typeof extraEnv === "object" ? extraEnv : {}),
+        ...(managedBootstrap.extraEnv && typeof managedBootstrap.extraEnv === "object" ? managedBootstrap.extraEnv : {}),
         UFOO_INTERNAL_AGENT: "1",
         UFOO_INTERNAL_PTY: usePty ? "1" : "0",
         UFOO_SUBSCRIBER_ID: subscriberId,  // 直接传递 subscriber ID
@@ -888,7 +931,8 @@ async function launchAgent(projectRoot, agent, count = 1, nickname = "", process
     throw new Error(`unsupported agent type: ${agent}`);
   }
 
-  if (mode === "internal") {
+  if (mode === "internal" || mode === "internal-pty") {
+    const usePty = mode === "internal-pty";
     const result = await spawnInternalAgent(
       projectRoot,
       normalizedAgent,
@@ -896,9 +940,10 @@ async function launchAgent(projectRoot, agent, count = 1, nickname = "", process
       nickname,
       processManager,
       launchEnvObject,
-      extraArgs
+      extraArgs,
+      { usePty }
     );
-    return { mode: "internal", launchScope, subscriberIds: result.subscriberIds };
+    return { mode, launchScope, subscriberIds: result.subscriberIds };
   }
   if (mode === "tmux") {
     // Check if tmux is available
@@ -1129,7 +1174,7 @@ async function resumeAgents(projectRoot, target = "", processManager = null) {
     const args = buildResumeArgs(item.agent, sessionId);
     let reused = false;
     let resumedId = item.id;
-    if (mode === "internal") {
+    if (mode === "internal" || mode === "internal-pty") {
       // Internal agents have no terminal/pane to reattach. Start a fresh
       // daemon-managed runner and replace the old recoverable registration.
       // The provider session is still reused via the normal provider args.
@@ -1142,7 +1187,7 @@ async function resumeAgents(projectRoot, target = "", processManager = null) {
         processManager,
         { UFOO_SKIP_SESSION_PROBE: "1" },
         args,
-        { replaceAgentId: item.id, providerSessionId: sessionId }
+        { replaceAgentId: item.id, providerSessionId: sessionId, usePty: mode === "internal-pty" }
       );
       resumedId = launchResult.subscriberIds && launchResult.subscriberIds[0]
         ? launchResult.subscriberIds[0]

package/src/ufoo/agentRegistryDiagnostics.js

@@ -0,0 +1,91 @@
+const fs = require("fs");
+const path = require("path");
+
+function isAgentsFile(filePath) {
+  return path.basename(filePath || "") === "all-agents.json"
+    && path.basename(path.dirname(filePath || "")) === "agent";
+}
+
+function getRegistryLogPath(agentsFilePath) {
+  const ufooRoot = path.dirname(path.dirname(agentsFilePath));
+  return path.join(ufooRoot, "run", "agent-registry-diagnostics.log");
+}
+
+function summarizeFile(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return {
+      exists: true,
+      size: stat.size,
+      mtime: stat.mtime.toISOString(),
+    };
+  } catch (err) {
+    return {
+      exists: false,
+      error: err && err.code ? err.code : String(err || "unknown"),
+    };
+  }
+}
+
+function summarizeAgents(data) {
+  const agents = data && typeof data === "object" && data.agents && typeof data.agents === "object"
+    ? data.agents
+    : {};
+  const ids = Object.keys(agents).sort();
+  const statuses = {};
+  const nicknames = {};
+  for (const id of ids) {
+    const meta = agents[id] || {};
+    const status = typeof meta.status === "string" && meta.status ? meta.status : "unknown";
+    statuses[status] = (statuses[status] || 0) + 1;
+    if (typeof meta.nickname === "string" && meta.nickname) {
+      nicknames[id] = meta.nickname;
+    }
+  }
+  return {
+    count: ids.length,
+    ids,
+    statuses,
+    nicknames,
+  };
+}
+
+function safePayload(payload = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(payload || {})) {
+    if (/token|secret|password|credential|auth/i.test(key)) {
+      out[key] = "[REDACTED]";
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function appendAgentRegistryDiagnostic(agentsFilePath, event, payload = {}) {
+  if (!agentsFilePath || !isAgentsFile(agentsFilePath)) return;
+  try {
+    const logPath = getRegistryLogPath(agentsFilePath);
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      pid: process.pid,
+      ppid: process.ppid,
+      event,
+      agents_file: agentsFilePath,
+      file: summarizeFile(agentsFilePath),
+      ...safePayload(payload),
+    });
+    fs.appendFileSync(logPath, `${line}\n`, "utf8");
+  } catch {
+    // Diagnostics must never affect agent liveness paths.
+  }
+}
+
+module.exports = {
+  appendAgentRegistryDiagnostic,
+  summarizeAgents,
+  summarizeFile,
+  isAgentsFile,
+  getRegistryLogPath,
+};