mixdog 0.8.0 → 0.9.0

package/src/runtime/agent/orchestrator/tools/patch-tool-defs.mjs

@@ -1,15 +1,44 @@
+export const APPLY_PATCH_LARK_GRAMMAR = `start: begin_patch hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch: "*** End Patch" LF?
+
+hunk: add_hunk | delete_hunk | update_hunk
+add_hunk: "*** Add File: " filename LF add_line+
+delete_hunk: "*** Delete File: " filename LF
+update_hunk: "*** Update File: " filename LF change_move? change?
+
+filename: /(.+)/
+add_line: "+" /(.*)/ LF -> line
+
+change_move: "*** Move to: " filename LF
+change: (change_context | change_line)+ eof_line?
+change_context: ("@@" | "@@ " /(.+)/) LF
+change_line: ("+" | "-" | " ") /(.*)/ LF
+eof_line: "*** End of File" LF
+
+%import common.LF
+`;
+
+export const APPLY_PATCH_FREEFORM_DESCRIPTION = 'Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.';
+
 export const PATCH_TOOL_DEFS = [
   {
     name: 'apply_patch',
     title: 'Mixdog Apply Patch',
     annotations: { title: 'Mixdog Apply Patch', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false, compressible: false, compressibleLossless: true },
-    description: 'Apply file patches. Prefer V4A with one file block per target file and exact current context around each edit.',
+    description: 'Apply file patches. Prefer V4A envelope with exact current context.',
+    freeformDescription: APPLY_PATCH_FREEFORM_DESCRIPTION,
+    freeform: {
+      type: 'grammar',
+      syntax: 'lark',
+      definition: APPLY_PATCH_LARK_GRAMMAR,
+    },
     inputSchema: {
       type: 'object',
       properties: {
-        patch: { type: 'string', description: 'Patch text only. V4A preferred: `*** Begin Patch` envelope and `*** Update/Add/Delete File: <path>` blocks. Use one block per target file, combining all hunks for that file. Copy exact current context around edits.' },
-        format: { type: 'string', enum: ['unified', 'v4a'], description: 'Auto-detected. Prefer v4a; unified needs counted @@ headers.' },
-        base_path: { type: 'string', description: 'Repo root so a/... paths resolve.' },
+        patch: { type: 'string', description: 'Patch text. V4A preferred: `*** Begin Patch`; one file block per target file; exact current context.' },
+        format: { type: 'string', enum: ['unified', 'v4a'], description: 'Auto-detected.' },
+        base_path: { type: 'string', description: 'Repo root.' },
         dry_run: { type: 'boolean', description: 'Default false. true = validate only, no write.' },
       },
       required: ['patch'],

package/src/runtime/agent/orchestrator/tools/patch.mjs

@@ -47,7 +47,7 @@ import {
   withBuiltinPathLocks,
 } from './builtin.mjs';
 import { withAdvisoryLocks } from './builtin/advisory-lock.mjs';
-import { markCodeGraphDirtyPaths } from './code-graph.mjs';
+import { markCodeGraphDirtyPaths } from './code-graph-state.mjs';
 import { wrapMutationRouteOutput } from './mutation-planner.mjs';
 import { getPluginData } from '../config.mjs';
 import { ensurePatchBinary, findCachedPatchBinary } from './patch-binary-fetcher.mjs';
@@ -527,6 +527,56 @@ function classifyEntry(entry) {
   return 'modify';
 }
 
+function parsedEntryTargetKey(entry, basePath) {
+  if (classifyEntry(entry) !== 'modify') return '';
+  const headerName = entry.oldFileName || entry.newFileName;
+  if (!headerName || DEV_NULL.test(headerName)) return '';
+  const fullPath = resolveEntryPath(basePath, headerName);
+  return process.platform === 'win32' ? fullPath.toLowerCase() : fullPath;
+}
+
+function mergeDuplicateParsedModifyEntries(parsed, basePath) {
+  const out = [];
+  const byTarget = new Map();
+  let changed = false;
+  for (const entry of parsed || []) {
+    const key = parsedEntryTargetKey(entry, basePath);
+    if (!key) {
+      out.push(entry);
+      continue;
+    }
+    const existing = byTarget.get(key);
+    if (!existing) {
+      byTarget.set(key, entry);
+      out.push(entry);
+      continue;
+    }
+    existing.hunks.push(...(entry.hunks || []));
+    changed = true;
+  }
+  return { parsed: out, changed };
+}
+
+function unifiedRange(start, lines) {
+  const s = Math.max(0, Number(start) || 0);
+  const n = Math.max(0, Number(lines) || 0);
+  return `${s},${n}`;
+}
+
+function renderParsedUnifiedPatch(parsed) {
+  const out = [];
+  for (const entry of parsed || []) {
+    out.push(`--- ${entry.oldFileName || '/dev/null'}`);
+    out.push(`+++ ${entry.newFileName || '/dev/null'}`);
+    for (const hunk of entry.hunks || []) {
+      const section = hunk.section ? ` ${hunk.section}` : '';
+      out.push(`@@ -${unifiedRange(hunk.oldStart, hunk.oldLines)} +${unifiedRange(hunk.newStart, hunk.newLines)} @@${section}`);
+      for (const line of hunk.lines || []) out.push(line);
+    }
+  }
+  return `${out.join('\n')}\n`;
+}
+
 function isPatchErrorText(text) {
   return /^Error:/i.test(String(text ?? '').trimStart());
 }
@@ -637,7 +687,27 @@ async function preValidateNativeBatch(parsed, basePath) {
     const kind = classifyEntry(entry);
     const headerName = kind === 'create' ? entry.newFileName : entry.oldFileName;
     if (!nativeHeaderSupported(entry, basePath)) {
-      const display = headerName ? normalizeOutputPath(stripDiffPrefix(headerName)) : '(unknown)';
+      // Two distinct failure modes share nativeHeaderSupported()===false:
+      //   (a) no usable target path could be parsed from the section header
+      //       (oldFileName/newFileName empty or /dev/null) — a SHAPE problem,
+      //   (b) a parsed path that escapes base_path (`..` segment / out-of-base
+      //       absolute) — a SECURITY refusal.
+      // Collapsing both into the "path escapes base_path or contains `..`"
+      // message mislabels (a) as (b): the model sees a nonsensical reason for a
+      // patch that uses no `..`, cannot self-correct, and re-submits the same
+      // patch until the iteration cap. Emit a shape-specific, actionable hint
+      // for (a) so the loop breaks on the first failure.
+      const hasUsableHeader = headerName && !DEV_NULL.test(headerName);
+      if (!hasUsableHeader) {
+        throw new Error(
+          'apply_patch: a file section header could not be parsed (no target path). '
+          + 'Each section must start with a valid header: `*** Update File: <path>` / '
+          + '`*** Add File: <path>` / `*** Delete File: <path>` (V4A), or a '
+          + '`--- a/<path>` + `+++ b/<path>` pair (unified). Wrap multi-hunk V4A '
+          + 'edits in a `*** Begin Patch` / `*** End Patch` envelope and pass format:"v4a".',
+        );
+      }
+      const display = normalizeOutputPath(stripDiffPrefix(headerName));
       throw new Error(`apply_patch: header ${display} is unsupported (path escapes base_path or contains \`..\`).`);
     }
     if (kind !== 'delete' && !(entry.hunks?.length > 0)) {
@@ -1240,8 +1310,15 @@ async function dispatchNativePatch({ entries, basePath, nativePatchStr, fuzz, re
     : `${verbLabel} ${countLabel(writtenEntries.length, 'File')} (Native)${dryRun ? ' Dry Run' : ''}`;
   const lines = [summary];
   for (const entry of writtenEntries) {
-    const detail = `+${countLabel(entry.added || 0, 'Line')} · -${countLabel(entry.removed || 0, 'Line')}`;
-    lines.push(`  OK ${kindLabel(entry.kind)} ${entry.displayPath} — ${detail}`);
+    const added = entry.added || 0;
+    const removed = entry.removed || 0;
+    const parts = [];
+    if (added > 0) parts.push(`+${countLabel(added, 'Line')}`);
+    if (removed > 0) parts.push(`-${countLabel(removed, 'Line')}`);
+    const detail = parts.join(' · ');
+    lines.push(detail
+      ? `  OK ${kindLabel(entry.kind)} ${entry.displayPath} — ${detail}`
+      : `  OK ${kindLabel(entry.kind)} ${entry.displayPath}`);
   }
   for (const f of stats.failures || []) {
     lines.push(`  SKIP ${f.path || '(unknown)'} — ${f.reason}${formatNativeFailureContext(parsed, basePath, f.path, { fuzz })}`);
@@ -1711,7 +1788,7 @@ function longestCommonSubstringLen(a, b, cap = 4000) {
 }
 
 // Normalize common typographic code-points to their ASCII equivalents, then
-// trim. Mirrors the Rust mixdog-patch normalize_typographic() and Codex
+// trim. Mirrors the Rust mixdog-patch normalize_typographic() and V4A
 // apply_patch's normalise() so V4A->unified anchor resolution stays consistent
 // across engines: an ASCII-authored patch can still anchor on source that
 // carries curly quotes, em/en dashes, NBSP and other exotic spaces.
@@ -2643,7 +2720,7 @@ async function apply_patch(args, cwd, options = {}) {
     parsed = parsePatch(normalizedPatchStr);
   } catch (err) {
     if (!canFallbackCountedUnified(patchStr, requestedFormat, err)) {
-      throw new Error(`apply_patch: parse failed — ${err?.message || String(err)}; prefer Codex/V4A envelope for multi-hunk edits (no @@ line counts)`);
+      throw new Error(`apply_patch: parse failed — ${err?.message || String(err)}; prefer V4A envelope for multi-hunk edits (no @@ line counts)`);
     }
     try {
       inputPatchStr = await convertUnifiedCountedToUnifiedPatchViaV4A(patchStr, basePath, v4aConvertOpts);
@@ -2661,6 +2738,13 @@ async function apply_patch(args, cwd, options = {}) {
   if (!v4aRenameOnly && (!Array.isArray(parsed) || parsed.length === 0)) {
     return 'Error: patch contained no file sections';
   }
+  if (!v4aRenameOnly) {
+    const merged = mergeDuplicateParsedModifyEntries(parsed, basePath);
+    if (merged.changed) {
+      parsed = merged.parsed;
+      normalizedPatchStr = renderParsedUnifiedPatch(parsed);
+    }
+  }
 
   // Pre-validate paths / duplicates / symlink escapes — throws on any
   // unsupported entry. Throws bubble out to the tool dispatcher as clean

package/src/runtime/agent/orchestrator/tools/progress-message.mjs

@@ -1,11 +1,11 @@
-// Per-tool live-status message builder (ported from claude-code's progress
+// Per-tool live-status message builder (ported from a reference agent's progress
 // generalization / getActivityDescription). Dependency-light and
 // side-effect-free: given a tool name + its raw args, return a short
 // human-readable "what's happening now" string. Used by the central dispatch
 // path to emit a single start-of-tool progress notification. Every tool gets a
 // meaningful verb; `running ${name}` is only the last-resort fallback.
 //
-// Verbs are kept symmetric with claude-code's wording: Read→"reading",
+// Verbs are kept symmetric with common agent wording: Read→"reading",
 // Edit→"editing", Write→"writing", Grep→"searching for", Glob→"finding",
 // web search→"searching web for", web fetch→"fetching".
 
@@ -45,6 +45,8 @@ export function formatToolStartProgress(name, args = {}) {
             return Array.isArray(a.pattern) ? `searching for ${_plural(a.pattern.length, 'pattern')}` : `searching for ${_t(a.pattern)}`;
         case 'glob':
             return Array.isArray(a.pattern) ? `finding ${_plural(a.pattern.length, 'glob')}` : `finding ${_t(a.pattern)}`;
+        case 'find':
+            return `finding ${_t(a.query || 'files')}`;
         case 'list':
             return a.mode === 'find' ? 'finding files' : `listing ${_t(a.path || 'cwd')}`;
         case 'code_graph':
@@ -57,12 +59,12 @@ export function formatToolStartProgress(name, args = {}) {
         case 'web_fetch':
             return Array.isArray(a.url) ? `fetching ${_plural(a.url.length, 'URL')}` : `fetching ${_t(a.url)}`;
 
-        // ── agent module: explore / bridge / models ──────────────────────
+        // ── agent module: explore / agent / models ───────────────────────
         case 'explore': {
             const n = Array.isArray(a.query) ? a.query.length : (a.query ? 1 : 0);
             return `exploring ${_plural(n, 'query', 'queries')}`;
         }
-        case 'bridge': {
+        case 'agent': {
             const route = [a.preset, [a.provider, a.model].filter(Boolean).join('/')].filter(Boolean).join(' ');
             const suffix = route ? ` (${_t(route, 32)})` : '';
             if (a.role) return `dispatching ${_t(a.role)}${suffix}`;

package/src/runtime/agent/orchestrator/tools/result-compression.mjs

@@ -33,7 +33,7 @@
  */
 
 import * as nodeUtil from 'node:util';
-import { traceBridgeCompress, traceBridgeBatch } from '../bridge-trace.mjs';
+import { traceAgentCompress, traceAgentBatch } from '../agent-trace.mjs';
 import { BUILTIN_TOOLS } from './builtin.mjs';
 import { PATCH_TOOL_DEFS } from './patch-tool-defs.mjs';
 import { CODE_GRAPH_TOOL_DEFS } from './code-graph-tool-defs.mjs';
@@ -137,7 +137,7 @@ function normalizeTrailingNewlines(text) {
     return text.replace(/\n+$/, '\n');
 }
 
-// Retained as named exports for non-tool-result consumers (bridge
+// Retained as named exports for non-tool-result consumers (agent
 // aggregated worker bodies in ai-wrapped-dispatch). These functions are
 // NO LONGER part of the tool-result compression chain — that chain is
 // lossless-only.
@@ -192,7 +192,7 @@ export function compressToolResult(toolName, args, result, ctx) {
     out = normalizeTrailingNewlines(out);
     if (out.length >= before) return result;
     if (ctx?.sessionId) {
-        try { traceBridgeCompress({ sessionId: ctx.sessionId, toolName, before, after: out.length }); } catch { /* trace best-effort */ }
+        try { traceAgentCompress({ sessionId: ctx.sessionId, toolName, before, after: out.length }); } catch { /* trace best-effort */ }
     }
     return out;
 }
@@ -205,7 +205,7 @@ export function compressToolResult(toolName, args, result, ctx) {
 export function recordToolBatch(sessionId, toolCallCount) {
     const n = Number(toolCallCount);
     if (!sessionId || !Number.isFinite(n) || n <= 0) return;
-    try { traceBridgeBatch({ sessionId, toolCallCount: n }); } catch { /* trace best-effort */ }
+    try { traceAgentBatch({ sessionId, toolCallCount: n }); } catch { /* trace best-effort */ }
 }
 
 export const _internals = {

package/src/runtime/agent/orchestrator/tools/shell-command.mjs

@@ -53,7 +53,7 @@ const SHELL_OUTPUT_DISK_CAP = 100 * 1024 * 1024;
 
 // Background-task disk watchdog cadence. The size guard polls the spilled
 // stdout/stderr files every interval and SIGKILLs the child once the
-// combined size exceeds SHELL_OUTPUT_DISK_CAP. 5 s matches Claude Code's
+// combined size exceeds SHELL_OUTPUT_DISK_CAP. 5 s matches reference agent
 // upstream cadence — short enough that a runaway loop is caught within a
 // few seconds, long enough that the stat overhead is negligible.
 const SIZE_WATCHDOG_INTERVAL_MS = 1_000;
@@ -585,6 +585,13 @@ export function execShellCommand({
         cwd,
         windowsHide: true,
         stdio: ['ignore', 'pipe', 'pipe'],
+        // NOTE (child-spawn-gate): intentionally NOT routed through
+        // src/runtime/shared/child-spawn-gate.mjs. bash/pwsh commands can run
+        // for minutes (or auto-background), so holding a finite gate slot for
+        // the whole lifetime would let a few long shells starve rg/code_graph —
+        // the opposite of the gate's intent. TODO: if shell saturation becomes
+        // a problem, gate only the brief spawn burst (release on first output /
+        // adoption), not the full run.
         // POSIX: detached gives the child its own process group so treeKill can
         // signal the whole group. The child is still CLI-owned because we do
         // not unref it after adoption. Windows detached has different console

package/src/runtime/agent/orchestrator/tools/shell-snapshot.mjs

@@ -8,7 +8,7 @@
 // pyenv / mise / asdf / direnv setup the user gets in their interactive
 // terminal — without paying a fresh login-shell startup on every call.
 //
-// Mirrors Claude Code upstream (src/utils/bash/ShellSnapshot.ts:413,
+// Mirrors upstream shell snapshot pattern (reference ShellSnapshot.ts:413,
 // createAndSaveSnapshot). Simpler scope: bash and zsh only, no embedded
 // search-tool injection (mixdog ships its own grep/glob helpers).
 
@@ -34,7 +34,7 @@ const _cache = new Map();
 // command. Cleared on process exit (process-scoped Set).
 const _failedShells = new Set();
 
-// Mirrors Claude Code's cleanupRegistry pattern (refs/claude-code/utils/
+// Mirrors reference cleanupRegistry pattern (utils/
 // cleanupRegistry.ts + ShellSnapshot.ts:534-545). Snapshot files are
 // session-scoped and must be unlinked on graceful shutdown — otherwise
 // they pile up forever (each rc-file mtime change creates a new file).
@@ -155,7 +155,7 @@ function _runSnapshot(shellPath, snapshotPath, configFileExists) {
   return new Promise((resolve) => {
     const script = getSnapshotScript(shellPath, snapshotPath, configFileExists);
     let stderrBuf = '';
-    // Mirror Claude Code (refs/claude-code/utils/bash/ShellSnapshot.ts:458):
+    // Mirror reference implementation (bash/ShellSnapshot.ts:458):
     // `-c -l` (login non-interactive). Earlier `-ic` (interactive command)
     // forced bash-completion to load — Git's completion loader spawns `find`
     // in subshells (__git_find_on_cmdline etc.) which detach on Windows when
@@ -163,7 +163,7 @@ function _runSnapshot(shellPath, snapshotPath, configFileExists) {
     // mode runs .bash_profile / .profile (which typically sources .bashrc)
     // without triggering completion init. The script also explicitly sources
     // the rc file, so the interactive-guard `[[ $- == *i* ]] && return` is
-    // accepted as a known tradeoff (matches Claude Code's choice).
+    // accepted as a known tradeoff (matches the reference choice).
     const child = spawn(shellPath, ['-c', '-l', script], {
       // P3 fix: blank prompts so an interactive sourcing in -ic does not
       // print PS1 / PS2 / RPROMPT / PROMPT noise to stderr (which our

package/src/runtime/channels/index.mjs

@@ -170,6 +170,8 @@ if (process.env.MIXDOG_CHANNELS_NO_CONNECT) {
 }
 const _isWorkerMode = process.env.MIXDOG_WORKER_MODE === '1'
 const _isCliOwnedMode = process.env.MIXDOG_CLI_OWNED === '1'
+const _isChannelDaemonMode = process.env.MIXDOG_CHANNEL_DAEMON === '1'
+const CHANNEL_DAEMON_IDLE_TTL_MS = Math.max(0, Number(process.env.MIXDOG_CHANNEL_IDLE_TTL_MS) || 60_000)
 const _bootLogEarly = path.join(
   DATA_DIR || path.join(os.tmpdir(), "mixdog"),
   "boot.log"
@@ -225,7 +227,7 @@ try {
 // GC stale ephemeral session files. closeSession plants a closed=true
 // tombstone, but bench / smoke / probe drivers historically created sessions
 // without ever calling closeSession, leaving 175-byte placeholders behind.
-// 7-day TTL is safe because live bridge sessions touch their JSON file on
+// 7-day TTL is safe because live agent sessions touch their JSON file on
 // every ask iteration, so any file older than 7 days is provably abandoned.
 const _SESSIONS_DIR = path.join(DATA_DIR, 'sessions');
 const _STALE_SESSION_TTL_MS = 7 * 24 * 60 * 60 * 1000;
@@ -327,24 +329,56 @@ const INSTRUCTIONS = "";
 // never `connect()`ed to any transport, so `.notification()` silently
 // threw 'Not connected' inside the SDK and every call was dropped by an
 // outer `.catch(() => {})`. That regression is what this path replaces.
-function sendNotifyToParent(method, params) {
-  if (!process.send) {
-    try { process.stderr.write(`mixdog channels: notify dropped (no IPC): ${method}\n`); } catch {}
-    return;
-  }
-  // CC channel schema requires meta: Record<string,string> (channelNotification.ts).
-  // Coerce every meta value to string so a non-string (e.g. a Discord
-  // interaction.type number) can't fail zod and silently drop the notify.
-  // silent_to_agent stays boolean — an internal routing flag the daemon
-  // router / agentNotify consume (=== true) before the CC zod boundary.
-  let outParams = params;
+let _channelNotifyBusSeq = 0;
+const CHANNEL_NOTIFY_BUS_FILE = path.join(RUNTIME_ROOT, 'channel-notifications.jsonl');
+const CHANNEL_NOTIFY_BUS_MAX_BYTES = 5 * 1024 * 1024;
+
+function normalizeChannelNotifyParams(method, params) {
   if (method === 'notifications/claude/channel' && params && params.meta) {
     const m = {};
     for (const [k, v] of Object.entries(params.meta)) {
       if (v === undefined || v === null) continue;
       m[k] = k === 'silent_to_agent' ? (v === true || v === 'true') : String(v);
     }
-    outParams = { ...params, meta: m };
+    return { ...params, meta: m };
+  }
+  return params;
+}
+
+function publishChannelNotify(method, params) {
+  try {
+    fs.mkdirSync(RUNTIME_ROOT, { recursive: true });
+    try {
+      const st = fs.statSync(CHANNEL_NOTIFY_BUS_FILE);
+      if (st.size > CHANNEL_NOTIFY_BUS_MAX_BYTES) {
+        try { fs.unlinkSync(CHANNEL_NOTIFY_BUS_FILE + '.1'); } catch {}
+        try { fs.renameSync(CHANNEL_NOTIFY_BUS_FILE, CHANNEL_NOTIFY_BUS_FILE + '.1'); } catch {}
+      }
+    } catch {}
+    const item = {
+      id: `${Date.now()}-${process.pid}-${++_channelNotifyBusSeq}`,
+      ts: Date.now(),
+      pid: process.pid,
+      method,
+      params,
+    };
+    fs.appendFileSync(CHANNEL_NOTIFY_BUS_FILE, JSON.stringify(item) + '\n');
+  } catch (err) {
+    try { process.stderr.write(`mixdog channels: notify bus write failed: ${err && err.message || err}\n`); } catch {}
+  }
+}
+
+function sendNotifyToParent(method, params) {
+  // CC channel schema requires meta: Record<string,string> (channelNotification.ts).
+  // Coerce every meta value to string so a non-string (e.g. a Discord
+  // interaction.type number) can't fail zod and silently drop the notify.
+  // silent_to_agent stays boolean — an internal routing flag the daemon
+  // router / agentNotify consume (=== true) before the CC zod boundary.
+  const outParams = normalizeChannelNotifyParams(method, params);
+  publishChannelNotify(method, outParams);
+  if (!process.send) {
+    try { process.stderr.write(`mixdog channels: notify queued on bus (no IPC): ${method}\n`); } catch {}
+    return;
   }
   try {
     process.send({ type: 'notify', method, params: outParams });
@@ -612,6 +646,98 @@ const ACTIVE_OWNER_STALE_MS = 1e4;
 // never blocks process exit. Single JSON atomic write, no measurable load.
 const OWNER_HEARTBEAT_INTERVAL_MS = 5e3;
 let ownerHeartbeatTimer = null;
+let channelDaemonIdleTimer = null;
+let channelDaemonLastClientAt = Date.now();
+let channelDaemonBackgroundLogAt = 0;
+const CHANNEL_CLIENT_DIR = path.join(RUNTIME_ROOT, 'channel-clients');
+
+function pidAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch (e) {
+    return e?.code === 'EPERM';
+  }
+}
+
+function countLiveChannelClients() {
+  let live = 0;
+  const now = Date.now();
+  try {
+    fs.mkdirSync(CHANNEL_CLIENT_DIR, { recursive: true });
+    for (const file of fs.readdirSync(CHANNEL_CLIENT_DIR)) {
+      if (!file.endsWith('.json')) continue;
+      const full = path.join(CHANNEL_CLIENT_DIR, file);
+      let item = null;
+      let st = null;
+      try {
+        st = fs.statSync(full);
+        item = JSON.parse(fs.readFileSync(full, 'utf8'));
+      } catch {
+        try { fs.unlinkSync(full); } catch {}
+        continue;
+      }
+      const pid = Number(item?.pid ?? file.replace(/\.json$/, ''));
+      const fresh = now - Math.max(Number(item?.updatedAt) || 0, st.mtimeMs) < 20_000;
+      if (pidAlive(pid) && fresh) {
+        live += 1;
+      } else {
+        try { fs.unlinkSync(full); } catch {}
+      }
+    }
+  } catch {}
+  return live;
+}
+
+function hasChannelBackgroundWork() {
+  if (!channelBridgeActive || !bridgeRuntimeConnected) return false;
+  if (config.webhook?.enabled === true) return true;
+  if (Array.isArray(config.events?.rules) && config.events.rules.length > 0) return true;
+  if (Array.isArray(config.nonInteractive) && config.nonInteractive.length > 0) return true;
+  if (Array.isArray(config.interactive) && config.interactive.length > 0) return true;
+  return false;
+}
+
+function checkChannelDaemonIdle() {
+  if (!_isChannelDaemonMode || CHANNEL_DAEMON_IDLE_TTL_MS <= 0) return;
+  const liveClients = countLiveChannelClients();
+  if (liveClients > 0) {
+    channelDaemonLastClientAt = Date.now();
+    return;
+  }
+  if (hasChannelBackgroundWork()) {
+    const now = Date.now();
+    if (now - channelDaemonBackgroundLogAt > 60_000) {
+      channelDaemonBackgroundLogAt = now;
+      try { process.stderr.write('[channels-worker] daemon idle: keeping alive for configured background work\n'); } catch {}
+    }
+    channelDaemonLastClientAt = Date.now();
+    return;
+  }
+  if (Date.now() - channelDaemonLastClientAt < CHANNEL_DAEMON_IDLE_TTL_MS) return;
+  try { process.stderr.write(`[channels-worker] daemon idle TTL elapsed (${CHANNEL_DAEMON_IDLE_TTL_MS}ms) — shutting down\n`); } catch {}
+  stop()
+    .then(() => process.exit(0))
+    .catch((e) => {
+      try { process.stderr.write(`[channels-worker] daemon idle shutdown failed: ${e?.message || e}\n`); } catch {}
+      process.exit(1);
+    });
+}
+
+function startChannelDaemonIdleMonitor() {
+  if (!_isChannelDaemonMode || CHANNEL_DAEMON_IDLE_TTL_MS <= 0 || channelDaemonIdleTimer) return;
+  channelDaemonLastClientAt = Date.now();
+  channelDaemonIdleTimer = setInterval(checkChannelDaemonIdle, 5000);
+  channelDaemonIdleTimer.unref?.();
+}
+
+function stopChannelDaemonIdleMonitor() {
+  if (!channelDaemonIdleTimer) return;
+  clearInterval(channelDaemonIdleTimer);
+  channelDaemonIdleTimer = null;
+}
 // Owner gating here is multi-process runtime coordination: only the active
 // bindingReady gates all send paths until the boot-time refreshBridgeOwnership
 // ({ restoreBinding: true }) call completes. Without this, scheduler/webhook
@@ -870,7 +996,7 @@ const OWNER_ROUTES = {
   },
   "/trigger-schedule": async (req, res, body) => {
     // Native fallback for `mcp__trigger_schedule` so out-of-band
-    // verification works when the MCP stdio bridge is down (Claude Code
+    // verification works when the MCP stdio bridge is down (host agent
     // disconnected, supervisor restart pending, etc.). Same authz as
     // /inject — x-owner-token must equal INSTANCE_ID.
     if (req.method !== "POST") { res.writeHead(405); res.end(JSON.stringify({ error: "POST required" })); return; }
@@ -1241,7 +1367,7 @@ function getBridgeOwnershipSnapshot() {
 // MIXDOG_PIN_OWNER=1 in the owning process writes `pinned:true` into
 // active-instance.json. Pinned owners ignore the 10 s stale window — they
 // only relinquish ownership when their OS process actually dies. Set per
-// session (env var on the Claude Code shell) to lock that Lead as the
+// session (env var on the host agent shell) to lock that Lead as the
 // schedule/webhook receiver across multi-session use.
 function canStealOwnership(active) {
   if (!active) return true;
@@ -1730,14 +1856,14 @@ function injectAndRecord(channelId, name, content, options) {
   // outbound body. Markers are
   // intentionally prepended onto tool RESULTS upstream (tool-loop-guard.mjs
   // build*Warn) so the model
-  // self-corrects, but bridge roles commonly echo them and we don't want them
+  // self-corrects, but agent roles commonly echo them and we don't want them
   // surfacing in Discord / Lead channel push.
   if (typeof content === 'string') content = stripSoftWarns(content);
-  // Skip-protocol guard: bridge agents (webhook-handler / scheduler-task)
+  // Skip-protocol guard: agents (webhook-handler / scheduler-task)
   // prefix `[meta:silent]` on the first line to opt out
   // of Lead inject for genuine no-op results (label-only events, dedup,
   // "nothing to report"). The body still goes to Discord for audit; only
-  // the Lead-context inject is suppressed. See rules/bridge/20-skip-protocol.md.
+  // the Lead-context inject is suppressed. See rules/agent/20-skip-protocol.md.
   if (typeof content === 'string') {
     const m = content.match(/^\s*\[meta:silent\][^\n]*\n?([\s\S]*)$/);
     if (m) {
@@ -1829,7 +1955,7 @@ function wireWebhookHandlers() {
       + ". Relay the finding to the user naturally — summarize clearly, call out any issues, and note what needs a decision.";
     const notifyFn = (text, meta = {}) => {
       if (!text) return;
-      // Webhook skip protocol: when the bridge worker emits a `[meta:silent]`
+      // Webhook skip protocol: when the agent worker emits a `[meta:silent]`
       // marker (optionally behind model/role tag prefixes), the event is a
       // no-op (label-only, dedup, "nothing to report"). Drop the message
       // entirely — neither Lead inject nor Discord forward — instead of the
@@ -1979,7 +2105,7 @@ try {
           }
         }
         // No matching pending request — leave the signal on disk so a
-        // bridge role hook (or other consumer) gets a chance to claim it.
+        // agent role hook (or other consumer) gets a chance to claim it.
         if (!oldestKey || !oldestEntry) return;
         if (oldestEntry.channelId && oldestEntry.messageId) {
           try {
@@ -2022,7 +2148,7 @@ try {
 backend.onInteraction = (interaction) => {
   // Channel-route permission reply. Custom_id format: perm-ch-{request_id}-{allow|session|deny}.
   // request_id is the 5-letter short ID CC generates via shortRequestId().
-  // Emit notifications/claude/channel/permission back to Claude Code; the race
+  // Emit notifications/claude/channel/permission back to the MCP host; the race
   // logic in interactiveHandler.ts resolves the pending request and dismisses
   // every other racer (local dialog, bridge, hook, classifier).
   if (interaction.customId?.startsWith("perm-ch-")) {
@@ -2989,6 +3115,7 @@ async function init(_sharedMcp) {
   });
 }
 async function start() {
+  startChannelDaemonIdleMonitor();
   channelBridgeActive = true;
   writeBridgeState(true);
   if (_isCliOwnedMode) {
@@ -3012,6 +3139,7 @@ async function start() {
   })();
 }
 async function stop() {
+  stopChannelDaemonIdleMonitor();
   try { await stopVoiceWhisperServer(); } catch {}
   await stopOwnedRuntime("unified server stop");
   cleanupInstanceRuntimeFiles(INSTANCE_ID);
@@ -3182,16 +3310,16 @@ if (_isWorkerMode && process.send) {
       } catch { /* best-effort */ }
       return;
     }
-    // Claude Code permission request → Discord Allow/Deny prompt.
+    // Host permission request → Discord Allow/Deny prompt.
     // Parent (server.mjs) receives notifications/claude/channel/permission_request
-    // from Claude Code and forwards the params here. We post a buttoned message;
+    // from the MCP host and forwards the params here. We post a buttoned message;
     // button clicks are handled in backend.onInteraction and sent back to CC as
     // notifications/claude/channel/permission via sendNotifyToParent.
     if (msg && msg.type === 'permission_request_inbound') {
       try {
         const { request_id, tool_name, description, input_preview } = msg.params || {};
         // tool_input arrives via the passthrough() schema in server.mjs when
-        // Claude Code includes it in the permission_request notification.
+        // The host includes it in the permission_request notification.
         // Used to bind the pendingPermRequest to a specific file so two
         // concurrent Edit/Write requests cannot cross-approve via the
         // terminal signal.