quadwork 1.19.2 → 2.0.0

package/server/index.js

@@ -6,21 +6,23 @@ const os = require("os");
 const { WebSocketServer, WebSocket } = require("ws");
 const pty = require("node-pty");
 const { spawn } = require("child_process");
-const { readConfig, resolveAgentCwd, resolveAgentCommand, resolveProjectChattr, resolveChattrSpawn, syncChattrToken, CONFIG_PATH, ensureSecureDir, writeSecureFile, writeConfig } = require("./config");
+const { readConfig, resolveAgentCwd, resolveAgentCommand, CONFIG_PATH, ensureSecureDir, writeSecureFile, writeConfig } = require("./config");
 const routes = require("./routes");
-const {
-  patchAgentchattrConfigForDiscordBridge,
-  patchAgentchattrConfigForTelegramBridge,
-  projectAgentchattrConfigPath,
-} = routes;
-const { waitForAgentChattrReady, registerAgent, registerAgentWithRetry, deregisterAgent, startHeartbeat, stopHeartbeat } = require("./agentchattr-registry");
-const { patchAgentchattrCss, patchCrashTimeout } = require("./install-agentchattr");
-const { startQueueWatcher, stopQueueWatcher } = require("./queue-watcher");
+const fileChat = require("./file-chat");
+const { dispatchToAgentPTY, cleanupSession: cleanupPtyDispatcher } = require("./pty-dispatcher");
+const { runAcMigration } = require("./migrate-ac");
 
 const net = require("net");
 const config = readConfig();
 const PORT = config.port || 8400;
 
+function emitSystemMessage(projectId, text) {
+  try {
+    if (routes.getProjectChatMode(projectId) !== "file") return;
+    fileChat.appendMessage(projectId, { sender: "system", type: "system", text });
+  } catch {}
+}
+
 const app = express();
 // #412 / quadwork#279: bump the global JSON body limit to 10mb so
 // POST /api/project-history can accept full chat exports. The
@@ -33,6 +35,14 @@ app.use(express.json({ limit: "10mb" }));
 // --- Mount migrated API routes (from Next.js) ---
 app.use(routes);
 
+// #730: wire PTY injection dispatcher into the chat route
+routes.setPtyDispatchCallback((projectId, msg) => {
+  dispatchToAgentPTY(projectId, msg, agentSessions, {
+    isLoopGuardPaused: fileChat.isLoopGuardPaused,
+    safeWrite,
+  });
+});
+
 const server = http.createServer(app);
 
 // --- REST endpoints ---
@@ -163,9 +173,6 @@ app.get("/api/caffeinate/status", (_req, res) => {
 // PTY (term) is the source of truth for "running". WS is optional (attaches to view terminal).
 const agentSessions = new Map();
 
-// AgentChattr server processes — per-project (key = projectId)
-const chattrProcesses = new Map();
-
 // #631: Butler session — single global PTY (not per-project, no AC integration)
 let butlerSession = { term: null, viewers: new Set(), viewerDims: new Map(), lastDims: null, state: "stopped", error: null, scrollback: Buffer.alloc(0) };
 
@@ -317,6 +324,27 @@ function writeMcpConfigFile(projectId, agentId, mcpHttpPort, token) {
   return filePath;
 }
 
+function writeFileChatMcpConfig(projectId, agentId, serverPort) {
+  const os = require("os");
+  const crypto = require("crypto");
+  const configDir = path.join(os.homedir(), ".quadwork", projectId);
+  ensureSecureDir(configDir);
+  const filePath = path.join(configDir, `mcp-${agentId}.json`);
+  const shimPath = path.join(__dirname, "mcp-chat-shim.js");
+  const token = crypto.randomBytes(16).toString("hex");
+  fileChat.registerShimToken(projectId, agentId, token);
+  const config = {
+    mcpServers: {
+      chat: {
+        command: "node",
+        args: [shimPath, "--project", projectId, "--agent", agentId, "--port", String(serverPort), "--token", token],
+      },
+    },
+  };
+  writeSecureFile(filePath, JSON.stringify(config, null, 2));
+  return { filePath, token };
+}
+
 /**
  * Build extra launch args for an agent (permission flags + MCP injection).
  * Async because Codex proxy_flag mode needs to await proxy startup.
@@ -324,16 +352,12 @@ function writeMcpConfigFile(projectId, agentId, mcpHttpPort, token) {
 async function buildAgentArgs(projectId, agentId) {
   const cfg = readConfig();
   const project = cfg.projects?.find((p) => p.id === projectId);
-  if (!project) return { args: [], acRegistrationName: null, acServerPort: null, acRegistrationToken: null, acInjectMode: null, acMcpHttpPort: null };
+  if (!project) return { args: [] };
 
   const agentCfg = project.agents?.[agentId] || {};
   const command = agentCfg.command || "claude";
-  const cliBase = command.split("/").pop().split(" ")[0]; // extract base CLI name
+  const cliBase = command.split("/").pop().split(" ")[0];
   const args = [];
-  let acRegistrationName = null;
-  let acServerPort = null;
-  let acRegistrationToken = null;
-  let acInjectMode = null;
 
   // Permission bypass flags
   if (agentCfg.auto_approve !== false) {
@@ -367,93 +391,22 @@ async function buildAgentArgs(projectId, agentId) {
     }
   }
 
-  // MCP config injection
-  const mcpHttpPort = project.mcp_http_port;
-  const token = project.agentchattr_token;
-  if (mcpHttpPort) {
-    const injectMode = agentCfg.mcp_inject || (cliBase === "codex" ? "proxy_flag" : cliBase === "gemini" ? "env" : "flag");
-    acInjectMode = injectMode;
-    if (injectMode === "flag") {
-      // Claude/Kimi: register with AgentChattr to obtain a per-agent
-      // token (#239 — session_token is browser auth, not MCP auth) and
-      // write that into the per-agent MCP config file.
-      const chattrInfo = resolveProjectChattr(projectId);
-      acServerPort = Number(new URL(chattrInfo.url).port) || 8300;
-      // #565: extend timeout to 30s — first setup may need AC to install
-      // (git clone + venv + pip install) before it can bind a port.
-      const acReady = await waitForAgentChattrReady(acServerPort, 30000);
-      if (!acReady) {
-        console.warn(`[#565] Agent ${agentId}: AC not reachable on port ${acServerPort} after 30s. Spawning without chat integration.`);
-        // #565: preserve acServerPort and acInjectMode so deferred
-        // recovery in spawnAgentPty can retry registration later.
-        return { args, acRegistrationName: null, acServerPort, acRegistrationToken: null, acInjectMode: injectMode, acMcpHttpPort: mcpHttpPort || null };
-      }
-      // #242: best-effort deregister any stale registration of the
-      // canonical name (left over by a crashed previous QuadWork
-      // session) so the fresh register lands at slot 1 instead of
-      // head-2 / re2-2. We need the previous agent's bearer
-      // token because app.py:2123 requires authenticated agent
-      // session for family names — load it from disk (persisted
-      // across restarts). Failures are non-fatal.
-      const stalePersistedToken = readPersistedAgentToken(projectId, agentId);
-      if (stalePersistedToken) {
-        await deregisterAgent(acServerPort, agentId, stalePersistedToken).catch(() => {});
-        clearPersistedAgentToken(projectId, agentId);
-      }
-      // #478: force-replace so AC expires any ghost slots for this base
-      // #565: retry with backoff and degrade gracefully if AC is not ready
-      const registration = await registerAgentWithRetry(acServerPort, agentId, agentCfg.display_name || null, { force: true });
-      if (!registration) {
-        console.warn(`[#565] Agent ${agentId}: AC registration failed after retries (${registerAgent.lastError}). Spawning without chat integration.`);
-      } else {
-        acRegistrationName = registration.name;
-        acRegistrationToken = registration.token;
-        writePersistedAgentToken(projectId, agentId, registration.token);
-        const mcpConfigPath = writeMcpConfigFile(projectId, agentId, mcpHttpPort, registration.token);
-        const flag = agentCfg.mcp_flag || "--mcp-config";
-        args.push(flag, mcpConfigPath);
-      }
-    } else if (injectMode === "proxy_flag") {
-      // Codex: register with AgentChattr first (#240) so the proxy
-      // injects a real per-agent token, not the global session token.
-      // Resolve via resolveProjectChattr so legacy/global-config
-      // projects without a per-project agentchattr_url still work.
-      const chattrInfo = resolveProjectChattr(projectId);
-      acServerPort = Number(new URL(chattrInfo.url).port) || 8300;
-      // #565: extend timeout to 30s for first-setup scenario
-      const acReady = await waitForAgentChattrReady(acServerPort, 30000);
-      if (!acReady) {
-        console.warn(`[#565] Agent ${agentId}: AC not reachable on port ${acServerPort} after 30s. Spawning without chat integration.`);
-        // #565: preserve acServerPort and acInjectMode so deferred
-        // recovery in spawnAgentPty can retry registration later.
-        return { args, acRegistrationName: null, acServerPort, acRegistrationToken: null, acInjectMode: injectMode, acMcpHttpPort: mcpHttpPort || null };
-      }
-      // #242: best-effort deregister stale canonical name first using
-      // the persisted bearer token from a previous session.
-      const stalePersistedToken = readPersistedAgentToken(projectId, agentId);
-      if (stalePersistedToken) {
-        await deregisterAgent(acServerPort, agentId, stalePersistedToken).catch(() => {});
-        clearPersistedAgentToken(projectId, agentId);
-      }
-      // #478: force-replace so AC expires any ghost slots for this base
-      // #565: retry with backoff and degrade gracefully if AC is not ready
-      const registration = await registerAgentWithRetry(acServerPort, agentId, agentCfg.display_name || null, { force: true });
-      if (!registration) {
-        console.warn(`[#565] Agent ${agentId}: AC registration failed after retries (${registerAgent.lastError}). Spawning without chat integration.`);
-      } else {
-        acRegistrationName = registration.name;
-        acRegistrationToken = registration.token;
-        writePersistedAgentToken(projectId, agentId, registration.token);
-        const upstreamUrl = `http://127.0.0.1:${mcpHttpPort}`;
-        const proxyUrl = await startMcpProxy(projectId, agentId, upstreamUrl, registration.token);
-        if (proxyUrl) {
-          args.push("-c", `mcp_servers.agentchattr.url="${proxyUrl}"`);
-        }
-      }
-    }
+  // MCP config injection — file-chat shim
+  const injectMode = agentCfg.mcp_inject || (cliBase === "codex" ? "proxy_flag" : cliBase === "gemini" ? "env" : "flag");
+  if (injectMode === "flag") {
+    const { filePath: mcpConfigPath } = writeFileChatMcpConfig(projectId, agentId, PORT);
+    const mcpFlag = agentCfg.mcp_flag || "--mcp-config";
+    args.push(mcpFlag, mcpConfigPath);
+  } else if (injectMode === "proxy_flag") {
+    const { token: shimToken } = writeFileChatMcpConfig(projectId, agentId, PORT);
+    const shimPath = path.join(__dirname, "mcp-chat-shim.js");
+    args.push(
+      "-c", `mcp_servers.chat.command="node"`,
+      "-c", `mcp_servers.chat.args=["${shimPath}","--project","${projectId}","--agent","${agentId}","--port","${PORT}","--token","${shimToken}"]`,
+    );
   }
-
-  return { args, acRegistrationName, acServerPort, acRegistrationToken, acInjectMode, acMcpHttpPort: mcpHttpPort || null };
+  // env mode (Gemini) handled in buildAgentEnv
+  return { args };
 }
 
 /**
@@ -470,18 +423,19 @@ function buildAgentEnv(projectId, agentId) {
   const env = {};
 
   // Gemini: inject MCP via env var
-  if (cliBase === "gemini" && project.mcp_http_port) {
+  if (cliBase === "gemini") {
     const os = require("os");
     const configDir = path.join(os.homedir(), ".quadwork", projectId);
     ensureSecureDir(configDir);
     const settingsPath = path.join(configDir, `mcp-${agentId}-settings.json`);
-    const url = `http://127.0.0.1:${project.mcp_http_port}/mcp`;
+
+    const { token: shimToken } = writeFileChatMcpConfig(projectId, agentId, PORT);
+    const shimPath = path.join(__dirname, "mcp-chat-shim.js");
     const settings = {
       mcpServers: {
-        agentchattr: {
-          type: "http",
-          url,
-          ...(project.agentchattr_token ? { headers: { Authorization: `Bearer ${project.agentchattr_token}` } } : {}),
+        chat: {
+          command: "node",
+          args: [shimPath, "--project", projectId, "--agent", agentId, "--port", String(PORT), "--token", shimToken],
         },
       },
     };
@@ -492,76 +446,8 @@ function buildAgentEnv(projectId, agentId) {
   return env;
 }
 
-/**
- * #394 / quadwork#253: recover from a heartbeat 409 (AgentChattr was
- * restarted, in-memory registry wiped, our token is now stale). Mirrors
- * wrapper.py:732-741. Re-registers the running agent, swaps the
- * tracked name/token on the live session so the heartbeat interval
- * picks up the new credentials on its next tick, refreshes whichever
- * MCP transport this agent uses (Claude config file vs Codex proxy),
- * and restarts the queue watcher in case the assigned name changed
- * (multi-instance slot bump).
- *
- * Best-effort: any failure here just means the next 5s heartbeat will
- * fail again and we'll re-enter recovery — no tight retry loop because
- * startHeartbeat guards re-entry with `recovering`.
- */
-async function recoverFrom409(projectId, agentId, session) {
-  if (!session.acServerPort) return;
-  const cfg = readConfig();
-  const project = cfg.projects?.find((p) => p.id === projectId);
-  const agentCfg = project?.agents?.[agentId] || {};
-  // AC may need a moment to come back up after a restart — wait briefly.
-  await waitForAgentChattrReady(session.acServerPort, 10000);
-
-  // Best-effort cleanup of the stale registration on disk so the
-  // fresh register isn't shoved into a slot 2 by leftover state.
-  const stale = readPersistedAgentToken(projectId, agentId);
-  if (stale) {
-    await deregisterAgent(session.acServerPort, agentId, stale).catch(() => {});
-    clearPersistedAgentToken(projectId, agentId);
-  }
-
-  // #478: force-replace so AC expires any ghost slots for this base
-  const replacement = await registerAgent(session.acServerPort, agentId, agentCfg.display_name || null, { force: true });
-  if (!replacement) return;
-
-  const previousName = session.acRegistrationName;
-  session.acRegistrationName = replacement.name;
-  session.acRegistrationToken = replacement.token;
-  writePersistedAgentToken(projectId, agentId, replacement.token);
-
-  // Refresh whichever MCP transport this agent uses so subsequent
-  // tool calls (and the queue-watcher's `mcp read` injections) hit
-  // AC with the new bearer token instead of the now-rejected one.
-  if (session.acInjectMode === "flag" && session.acMcpHttpPort) {
-    try { writeMcpConfigFile(projectId, agentId, session.acMcpHttpPort, replacement.token); } catch {}
-  } else if (session.acInjectMode === "proxy_flag") {
-    // Codex is pinned to the original ephemeral proxy URL, so we
-    // can't tear the listener down — mutate the token in place.
-    try { updateMcpProxyToken(projectId, agentId, replacement.token); } catch {}
-  }
-
-  // If the assigned name changed (e.g. multi-instance slot collision)
-  // the queue watcher is now polling the wrong file. Restart it
-  // against the new name so chat reaches the right agent.
-  if (replacement.name !== previousName && session.term) {
-    if (session.queueWatcherHandle) {
-      stopQueueWatcher(session.queueWatcherHandle);
-      session.queueWatcherHandle = null;
-    }
-    try {
-      const { dir: acDir } = resolveProjectChattr(projectId);
-      if (acDir) {
-        const dataDir = path.join(acDir, "data");
-        session.queueWatcherHandle = startQueueWatcher(dataDir, replacement.name, session.term);
-      }
-    } catch {}
-  }
-}
-
 // Helper: spawn a PTY for a project/agent and register in agentSessions
-async function spawnAgentPty(project, agent) {
+async function spawnAgentPty(project, agent, opts = {}) {
   const key = `${project}/${agent}`;
 
   const cwd = resolveAgentCwd(project, agent);
@@ -593,13 +479,7 @@ async function spawnAgentPty(project, agent) {
       lastDims: null,
       state: "running",
       error: null,
-      acRegistrationName: built.acRegistrationName,
-      acServerPort: built.acServerPort,
-      acRegistrationToken: built.acRegistrationToken,
-      acInjectMode: built.acInjectMode,
-      acMcpHttpPort: built.acMcpHttpPort,
-      acHeartbeatHandle: null,
-      queueWatcherHandle: null,
+      lastOutputAt: Date.now(),
       // #418: ring buffer of recent PTY output so reconnecting WS
       // clients see the terminal state instead of a blank panel.
       // #538: scrollback is scrubbed of likely secrets before replay.
@@ -607,11 +487,16 @@ async function spawnAgentPty(project, agent) {
     };
     agentSessions.set(key, session);
 
+    if (!opts.suppressLifecycleMsg) {
+      emitSystemMessage(project, `${agent} joined`);
+    }
+
     // #418: capture PTY output into the scrollback ring buffer (64KB).
     // This runs independently of WS — even when no client is connected,
     // the buffer accumulates so the next connect gets replay.
     const SCROLLBACK_SIZE = 64 * 1024;
     term.onData((data) => {
+      session.lastOutputAt = Date.now();
       const chunk = Buffer.from(data);
       session.scrollback = Buffer.concat([session.scrollback, chunk]);
       if (session.scrollback.length > SCROLLBACK_SIZE) {
@@ -619,72 +504,10 @@ async function spawnAgentPty(project, agent) {
       }
     });
 
-    // #391 / quadwork#250: keep this agent alive in AgentChattr by
-    // POSTing /api/heartbeat/{name} every 5s. Without it, AC's 60s
-    // crash-detection window deregisters the agent and chat messages
-    // never reach it. Mirrors wrapper.py:_heartbeat (lines 715-748).
-    if (session.acRegistrationName && session.acServerPort && session.acRegistrationToken) {
-      // #394 / quadwork#253: pass getters (not raw values) so the 409
-      // recovery path below can swap acRegistrationName/Token in place
-      // and the very next heartbeat tick uses the replacement
-      // credentials without us having to tear down + restart the
-      // interval.
-      session.acHeartbeatHandle = startHeartbeat(
-        session.acServerPort,
-        () => session.acRegistrationName,
-        () => session.acRegistrationToken,
-        { onConflict: () => recoverFrom409(project, agent, session) },
-      );
-    }
-
-    // #393 / quadwork#251: queue watcher — the actual mechanism by
-    // which agents pick up chat. Without this an agent can be
-    // registered + heartbeating yet still never respond, because
-    // AgentChattr only writes to {data_dir}/{name}_queue.jsonl and
-    // expects the agent side to poll + inject `mcp read`.
-    if (session.acRegistrationName && session.term) {
-      try {
-        const { dir: acDir } = resolveProjectChattr(project);
-        if (acDir) {
-          const dataDir = path.join(acDir, "data");
-          session.queueWatcherHandle = startQueueWatcher(
-            dataDir,
-            session.acRegistrationName,
-            session.term,
-          );
-        }
-      } catch {
-        // best-effort — failure here just means no chat injection
-      }
-    }
-
-    // #565: deferred restart — if the agent spawned without AC
-    // registration (AC wasn't ready or registration failed), wait for
-    // AC to come up then stop + respawn the agent so it gets the full
-    // MCP CLI args (--mcp-config / -c mcp_servers...url) that can only
-    // be set at process launch time.
-    if (!session.acRegistrationName && session.acServerPort && session.acInjectMode) {
-      const deferredRestart = async () => {
-        const ready = await waitForAgentChattrReady(session.acServerPort, 60000);
-        if (!ready) {
-          // #572: log timeout so operators know the health monitor will
-          // handle recovery when AC eventually comes up.
-          console.log(`[#565] Agent ${agent}: AC not reachable after 60s — health monitor will restart agent when AC recovers.`);
-          return;
-        }
-        // Guard: agent may have been stopped manually while we waited.
-        const current = agentSessions.get(key);
-        if (!current || !current.term || current.state !== "running") return;
-        console.log(`[#565] Agent ${agent}: AC is now reachable — restarting agent to gain chat integration.`);
-        await stopAgentSession(key);
-        await spawnAgentPty(project, agent);
-      };
-      deferredRestart().catch(() => {});
-    }
-
     term.onExit(({ exitCode }) => {
       const current = agentSessions.get(key);
       if (current && current.term === term) {
+        cleanupPtyDispatcher(key);
         current.state = "stopped";
         current.error = exitCode ? `exit:${exitCode}` : null;
         current.term = null;
@@ -692,27 +515,6 @@ async function spawnAgentPty(project, agent) {
           if (v.readyState <= 1) v.close(1000, `exited:${exitCode}`);
         }
         current.viewers.clear();
-        // #391 / quadwork#250: a crashed PTY must also clear its
-        // heartbeat interval (otherwise it leaks and a later /start
-        // double-registers) and free the AgentChattr slot (otherwise
-        // the agent stays falsely `active` forever and the next
-        // register lands at slot 2). Deregister is best-effort.
-        if (current.acHeartbeatHandle) {
-          stopHeartbeat(current.acHeartbeatHandle);
-          current.acHeartbeatHandle = null;
-        }
-        if (current.queueWatcherHandle) {
-          stopQueueWatcher(current.queueWatcherHandle);
-          current.queueWatcherHandle = null;
-        }
-        if (current.acRegistrationName && current.acServerPort) {
-          deregisterAgent(current.acServerPort, current.acRegistrationName).catch(() => {});
-          if (current.projectId && current.agentId) {
-            try { clearPersistedAgentToken(current.projectId, current.agentId); } catch {}
-          }
-          current.acRegistrationName = null;
-          current.acRegistrationToken = null;
-        }
       }
     });
 
@@ -723,16 +525,16 @@ async function spawnAgentPty(project, agent) {
   }
 }
 
-// Helper: stop an agent session — kill PTY, close WS, deregister.
-// Async because deregister must complete before a restart re-registers,
-// otherwise the old slot stays occupied and a fresh register lands at
-// head-2 instead of slot 1 (#241).
 async function stopAgentSession(key) {
   const session = agentSessions.get(key);
   if (!session) {
     agentSessions.set(key, { projectId: null, agentId: null, term: null, viewers: new Set(), viewerDims: new Map(), lastDims: null, state: "stopped", error: null });
     return;
   }
+  if (session.projectId && session.agentId && !session._suppressLifecycleMsg) {
+    emitSystemMessage(session.projectId, `${session.agentId} left`);
+  }
+  cleanupPtyDispatcher(key);
   if (session.term) {
     try { session.term.kill(); } catch {}
     session.term = null;
@@ -743,33 +545,6 @@ async function stopAgentSession(key) {
   session.viewers.clear();
   session.state = "stopped";
   session.error = null;
-  // Stop heartbeat before deregister so we don't race a final POST
-  // against AgentChattr removing the name (#391 / quadwork#250).
-  if (session.acHeartbeatHandle) {
-    stopHeartbeat(session.acHeartbeatHandle);
-    session.acHeartbeatHandle = null;
-  }
-  // Stop queue watcher (#393 / quadwork#251) — the PTY is gone,
-  // injecting into a dead term would throw on the next tick.
-  if (session.queueWatcherHandle) {
-    stopQueueWatcher(session.queueWatcherHandle);
-    session.queueWatcherHandle = null;
-  }
-  // Best-effort deregister from AgentChattr (#241) so the slot frees
-  // and the next register lands at slot 1 instead of head-2.
-  if (session.acRegistrationName && session.acServerPort) {
-    try {
-      await deregisterAgent(session.acServerPort, session.acRegistrationName);
-    } catch {
-      // best-effort — failures are non-fatal
-    }
-    if (session.projectId && session.agentId) {
-      clearPersistedAgentToken(session.projectId, session.agentId);
-    }
-    session.acRegistrationName = null;
-    session.acRegistrationToken = null;
-  }
-  // Clean up MCP auth proxy if running
   const [projectId, agentId] = key.split("/");
   if (projectId && agentId) stopMcpProxy(projectId, agentId);
 }
@@ -779,487 +554,15 @@ app.get("/api/agents", (_req, res) => {
   for (const [key, session] of agentSessions) {
     agents[key] = { state: session.state, error: session.error || null };
   }
-  for (const [pid, proc] of chattrProcesses) {
-    agents[`_agentchattr/${pid}`] = { state: proc.state, error: proc.error };
-  }
   res.json(agents);
 });
 
-// #424 / quadwork#304: best-effort auto-snapshot of chat history
-// before any AgentChattr restart. Defense-in-depth against
-// destructive ops like /clear that rewrite AC's JSONL log in place
-// — per #303 the log itself IS persistent across normal restarts,
-// so the snapshot's job is to give the operator a point-in-time
-// rollback if the log gets clobbered, not to prevent history loss
-// on ordinary lifecycle events.
-//
-// Snapshot contents = the same envelope GET /api/project-history
-// returns, so an operator (or a future "restore" button) can feed
-// the file straight into POST /api/project-history for replay.
-const HISTORY_SNAPSHOT_LIMIT = 5;
-
-async function snapshotProjectHistory(projectId) {
-  try {
-    const snapDir = path.join(require("os").homedir(), ".quadwork", projectId, "history-snapshots");
-    ensureSecureDir(snapDir);
-    const res = await fetch(`http://127.0.0.1:${PORT}/api/project-history?project=${encodeURIComponent(projectId)}`, {
-      signal: AbortSignal.timeout(30000),
-    });
-    if (!res.ok) {
-      console.warn(`[snapshot] ${projectId} history fetch returned ${res.status}; skipping snapshot`);
-      return false;
-    }
-    const text = await res.text();
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const outPath = path.join(snapDir, `${stamp}.json`);
-    fs.writeFileSync(outPath, text);
-    console.log(`[snapshot] ${projectId} → ${outPath}`);
-    // Prune to the newest HISTORY_SNAPSHOT_LIMIT files so the
-    // directory can't grow unbounded across weeks of restarts.
-    try {
-      const entries = fs.readdirSync(snapDir)
-        .filter((f) => f.endsWith(".json"))
-        .map((f) => ({ f, t: fs.statSync(path.join(snapDir, f)).mtimeMs }))
-        .sort((a, b) => b.t - a.t);
-      for (const old of entries.slice(HISTORY_SNAPSHOT_LIMIT)) {
-        try { fs.unlinkSync(path.join(snapDir, old.f)); } catch {}
-      }
-    } catch {
-      // non-fatal — stale snapshots just linger
-    }
-    return true;
-  } catch (err) {
-    console.warn(`[snapshot] ${projectId} snapshot failed: ${err.message || err}`);
-    return false;
-  }
-}
-
-// Per-project AgentChattr lifecycle: /api/agentchattr/:project/:action
-// Backward compat: /api/agentchattr/:action uses first project
-async function handleAgentChattr(req, res) {
-  let projectId, action;
-  if (req.params.action) {
-    projectId = req.params.projectOrAction;
-    action = req.params.action;
-  } else {
-    // Backward compat: single-param = action, use first project
-    action = req.params.projectOrAction;
-    const cfg = readConfig();
-    projectId = cfg.projects?.[0]?.id || "_default";
-  }
-
-  const { url: chattrUrl } = resolveProjectChattr(projectId);
-  const chattrPort = new URL(chattrUrl).port || "8300";
-
-  // Find per-project config.toml. Phase 2E / #181: prefer the
-  // per-project AgentChattr clone ROOT (where the web/CLI wizards now
-  // write it as of #184/#185 — and where run.py actually reads it from).
-  // Fall back to the legacy <working_dir>/agentchattr/config.toml for
-  // v1 setups that haven't been migrated yet (#188).
-  const cfg = readConfig();
-  const project = cfg.projects?.find((p) => p.id === projectId);
-  const { dir: resolvedAcDir } = resolveProjectChattr(projectId);
-  let projectConfigToml = null;
-  if (resolvedAcDir && fs.existsSync(path.join(resolvedAcDir, "config.toml"))) {
-    projectConfigToml = path.join(resolvedAcDir, "config.toml");
-  } else if (project?.working_dir) {
-    const legacyToml = path.join(project.working_dir, "agentchattr", "config.toml");
-    if (fs.existsSync(legacyToml)) projectConfigToml = legacyToml;
-  }
-
-  function getProc() {
-    return chattrProcesses.get(projectId) || { process: null, state: "stopped", error: null };
-  }
-  function setProc(val) {
-    chattrProcesses.set(projectId, val);
-  }
-
-  function regenerateConfigToml() {
-    // If project has a config.toml, update the port to match current config
-    if (!projectConfigToml || !fs.existsSync(projectConfigToml)) return;
-    try {
-      let content = fs.readFileSync(projectConfigToml, "utf-8");
-      content = content.replace(/^port = \d+/m, `port = ${chattrPort}`);
-      writeSecureFile(projectConfigToml, content);
-    } catch {}
-  }
-
-  async function spawnChattr() {
-    // Sync config.toml port before starting
-    regenerateConfigToml();
-
-    // Use project config.toml if available (isolated data dir + ports), otherwise fall back to --port
-    const extraArgs = (projectConfigToml && fs.existsSync(projectConfigToml))
-      ? []
-      : ["--port", chattrPort];
-
-    // Resolve AgentChattr from its cloned directory
-    const { dir: acDir } = resolveProjectChattr(projectId);
-    // #394: backfill sender-overflow CSS/JS patch on every spawn so
-    // existing installs receive the fix without manual update.
-    patchAgentchattrCss(acDir);
-    const acSpawn = resolveChattrSpawn(acDir);
-    if (!acSpawn) {
-      setProc({ process: null, state: "error", error: `AgentChattr not installed. Clone it: git clone https://github.com/bcurts/agentchattr.git ${acDir}` });
-      return null;
-    }
-
-    // #569: redirect AC stdout/stderr to a log file so operators can
-    // diagnose startup failures. Append mode preserves restart history.
-    const acLogDir = path.join(os.homedir(), ".quadwork", projectId);
-    try { fs.mkdirSync(acLogDir, { recursive: true, mode: 0o700 }); } catch {}
-    const acLogPath = path.join(acLogDir, "agentchattr.log");
-    const acLogFd = fs.openSync(acLogPath, "a");
-    const child = spawn(acSpawn.command, [...acSpawn.args, ...extraArgs], {
-      cwd: acSpawn.cwd,
-      env: process.env,
-      stdio: ["ignore", acLogFd, acLogFd],
-      detached: true,
-    });
-
-    // Close our copy of the log fd — child inherits its own copy.
-    fs.closeSync(acLogFd);
-
-    // If pid is undefined, spawn failed
-    if (!child.pid) {
-      setProc({ process: null, state: "error", error: "Failed to start AgentChattr — check that Python venv is set up in " + acDir + ". Log: " + acLogPath });
-      child.on("error", () => {});
-      return null;
-    }
-
-    child.unref();
-    child.on("error", (err) => {
-      setProc({ process: null, state: "error", error: err.message });
-    });
-    child.on("exit", (code) => {
-      const cur = getProc();
-      if (cur.process === child) {
-        setProc({ process: null, state: "stopped", error: code ? `exit:${code}` : null });
-      }
-    });
-    // #580: wait for AC to actually bind the port before declaring success.
-    // On fast-start installs this resolves in 1-2s; prevents false-down
-    // detection on slow starts that triggered ghost agent cascades.
-    const ready = await waitForAgentChattrReady(chattrPort, 30000);
-    if (ready) {
-      setProc({ process: child, state: "running", error: null, runningSince: Date.now() });
-      return child;
-    } else {
-      setProc({ process: child, state: "error", error: "AgentChattr did not become ready within 30s" });
-      return null;
-    }
-  }
-
-  // #386: Kill any process listening on the AC port. Handles orphaned
-  // processes that survive QuadWork restarts (detached + unref'd spawns
-  // lose their tracked reference when the Node process recycles).
-  function killProcessOnPort(port, signal = "SIGTERM") {
-    try {
-      const pids = execFileSync("lsof", ["-ti", `TCP:${port}`, "-sTCP:LISTEN"], {
-        encoding: "utf-8",
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-      }).trim();
-      if (!pids) return;
-      for (const line of pids.split("\n")) {
-        const pid = parseInt(line, 10);
-        if (pid > 0) {
-          try { process.kill(pid, signal); } catch {}
-        }
-      }
-    } catch {
-      // lsof exits non-zero when no matching process — expected
-    }
-  }
-
-  // #386: Poll until the port is free or timeout expires.
-  function waitForPortFree(port, timeoutMs = 3000) {
-    const start = Date.now();
-    return new Promise((resolve) => {
-      function check() {
-        try {
-          execFileSync("lsof", ["-ti", `TCP:${port}`, "-sTCP:LISTEN"], {
-            encoding: "utf-8",
-            timeout: 2000,
-            stdio: ["pipe", "pipe", "pipe"],
-          });
-          // Still occupied — retry if within budget
-          if (Date.now() - start < timeoutMs) {
-            setTimeout(check, 200);
-          } else {
-            resolve(false);
-          }
-        } catch {
-          // lsof found nothing — port is free
-          resolve(true);
-        }
-      }
-      check();
-    });
-  }
-
-  if (action === "start") {
-    const proc = getProc();
-    if (proc.state === "running" && proc.process) {
-      return res.json({ ok: true, state: "running", message: "Already running" });
-    }
-    // #401: validate AgentChattr is installed BEFORE killing anything on
-    // the port. Without this guard, clicking Start when AC is missing
-    // kills an unrelated process then fails with "not installed".
-    const { dir: acDir } = resolveProjectChattr(projectId);
-    const acSpawn = resolveChattrSpawn(acDir);
-    if (!acSpawn) {
-      const errMsg = `AgentChattr not installed. Clone it: git clone https://github.com/bcurts/agentchattr.git ${acDir}`;
-      setProc({ process: null, state: "error", error: errMsg });
-      return res.status(500).json({ ok: false, state: "error", error: errMsg });
-    }
-
-    // #393: kill any orphaned process on the port before spawning
-    // (same pattern as restart/stop from #386).
-    killProcessOnPort(chattrPort);
-    const portFree = await waitForPortFree(chattrPort, 3000);
-    if (!portFree) {
-      console.warn(`[agentchattr] ${projectId} port ${chattrPort} still occupied after 3s — spawning anyway`);
-    }
-    try {
-      const child = await spawnChattr();
-      if (!child) {
-        const errProc = getProc();
-        return res.status(500).json({ ok: false, state: "error", error: errProc.error || "Failed to start AgentChattr" });
-      }
-      // Sync token after AgentChattr starts (it generates its own)
-      setTimeout(() => syncChattrToken(projectId), 2000);
-      res.json({ ok: true, state: "running", pid: child.pid });
-    } catch (err) {
-      setProc({ process: null, state: "error", error: err.message });
-      res.status(500).json({ ok: false, state: "error", error: err.message });
-    }
-  } else if (action === "stop") {
-    const proc = getProc();
-    if (proc.process) {
-      try { proc.process.kill("SIGTERM"); } catch {}
-    }
-    // #386: also kill any orphaned process holding the port
-    killProcessOnPort(chattrPort);
-    setProc({ process: null, state: "stopped", error: null });
-    res.json({ ok: true, state: "stopped" });
-  } else if (action === "restart") {
-    // #424 / quadwork#304: snapshot history before killing the
-    // process. Best-effort and non-blocking-on-failure so a flaky
-    // snapshot doesn't leave the operator unable to restart AC.
-    await snapshotProjectHistory(projectId).catch(() => {});
-    // #424 / quadwork#304 Phase 3: latch the opt-in BEFORE the
-    // spawn so a restart that itself clears the flag can't starve
-    // the auto-restore. We capture the snapshot filename we just
-    // wrote + the project's auto_restore_after_restart flag and
-    // replay it in the post-spawn tick below if both are set.
-    const preRestartCfg = readConfig();
-    const preRestartProject = preRestartCfg.projects?.find((p) => p.id === projectId);
-    const shouldAutoRestore = !!(preRestartProject && preRestartProject.auto_restore_after_restart);
-    const proc = getProc();
-    if (proc.process) {
-      console.log(`[agentchattr] ${projectId} restart: killing AC (PID: ${proc.process.pid})`);
-      try { proc.process.kill("SIGTERM"); } catch {}
-    }
-    // #386: also kill any orphaned process holding the port (handles
-    // detached processes that survived a QuadWork restart).
-    killProcessOnPort(chattrPort);
-    setProc({ process: null, state: "stopped", error: null });
-    // #582: wait up to 5s for the port to be free, then SIGKILL
-    // any remaining process as a fallback before spawning.
-    let portFree = await waitForPortFree(chattrPort, 5000);
-    if (!portFree) {
-      console.warn(`[agentchattr] ${projectId} port ${chattrPort} still occupied after 5s — sending SIGKILL`);
-      killProcessOnPort(chattrPort, "SIGKILL");
-      portFree = await waitForPortFree(chattrPort, 3000);
-      if (!portFree) {
-        const portErr = `Port ${chattrPort} still occupied — cannot restart`;
-        console.error(`[agentchattr] ${projectId} ${portErr}`);
-        setProc({ process: null, state: "error", error: portErr });
-        return res.status(500).json({ ok: false, state: "error", error: portErr });
-      }
-    }
-    console.log(`[agentchattr] ${projectId} restart: port ${chattrPort} is free, spawning AC`);
-    try {
-      const child = await spawnChattr();
-      if (!child) {
-        const errProc = getProc();
-        console.error(`[agentchattr] ${projectId} restart: spawnChattr failed — ${errProc.error || "unknown error"}`);
-        return res.status(500).json({ ok: false, state: "error", error: errProc.error || "Failed to start AgentChattr" });
-      }
-      console.log(`[agentchattr] ${projectId} restart: AC spawned and ready (PID: ${child.pid})`);
-      // Sync token after AgentChattr restarts
-      setTimeout(() => syncChattrToken(projectId), 2000);
-      // #424 / quadwork#304 Phase 3: optional auto-restore.
-      // Fire the restore 3s after spawn so AC's ws is ready.
-      // Best-effort: never blocks the restart response or
-      // rolls back on error.
-      if (shouldAutoRestore) {
-        setTimeout(async () => {
-          try {
-            const snapDir = path.join(require("os").homedir(), ".quadwork", projectId, "history-snapshots");
-            if (!fs.existsSync(snapDir)) return;
-            const newest = fs.readdirSync(snapDir)
-              .filter((f) => f.endsWith(".json"))
-              .map((f) => ({ f, t: fs.statSync(path.join(snapDir, f)).mtimeMs }))
-              .sort((a, b) => b.t - a.t)[0];
-            if (!newest) return;
-            const r = await fetch(`http://127.0.0.1:${PORT}/api/project-history/restore?project=${encodeURIComponent(projectId)}&name=${encodeURIComponent(newest.f)}`, {
-              method: "POST",
-            });
-            if (r.ok) console.log(`[snapshot] ${projectId} auto-restored ${newest.f}`);
-            else console.warn(`[snapshot] ${projectId} auto-restore returned ${r.status}`);
-          } catch (err) {
-            console.warn(`[snapshot] ${projectId} auto-restore failed: ${err.message || err}`);
-          }
-        }, 3000);
-      }
-      res.json({ ok: true, state: "running", pid: child.pid });
-      // #447: auto-reset all agents after AC restart so they get
-      // fresh MCP tokens. #581: mark reset as scheduled immediately
-      // so the health monitor skips its own reset while ours is in-flight.
-      // #579: also skip if a reset already succeeded within the last 30s.
-      // Multiple restart sources (bridge-migrate, health monitor, dashboard)
-      // can fire in rapid succession — only the first should trigger a reset.
-      const existingReset = _acHealth.resetState.get(projectId);
-      const resetRecentlyDone = existingReset &&
-        (existingReset.status === "succeeded" || existingReset.status === "scheduled") &&
-        Date.now() - existingReset.timestamp < 30_000;
-      if (resetRecentlyDone) {
-        console.log(`[agentchattr] ${projectId} skipping auto-reset — one already ${existingReset.status} ${Math.round((Date.now() - existingReset.timestamp) / 1000)}s ago`);
-      } else {
-      _acHealth.resetState.set(projectId, { status: "scheduled", timestamp: Date.now() });
-      }
-      if (!resetRecentlyDone) setTimeout(async () => {
-        try {
-          const resetResp = await fetch(`http://127.0.0.1:${PORT}/api/agents/${encodeURIComponent(projectId)}/reset`, {
-            method: "POST",
-          });
-          if (resetResp.ok) {
-            const resetData = await resetResp.json();
-            _acHealth.resetState.set(projectId, { status: "succeeded", timestamp: Date.now() });
-            console.log(`[agentchattr] ${projectId} auto-reset ${resetData.restarted} agent(s) after AC restart`);
-          } else {
-            _acHealth.resetState.set(projectId, { status: "failed", timestamp: Date.now() });
-            console.warn(`[agentchattr] ${projectId} agent reset after AC restart returned ${resetResp.status}`);
-          }
-        } catch (err) {
-          _acHealth.resetState.set(projectId, { status: "failed", timestamp: Date.now() });
-          console.warn(`[agentchattr] ${projectId} agent reset after AC restart failed: ${err.message || err}`);
-        }
-      }, 2000);
-    } catch (err) {
-      setProc({ process: null, state: "error", error: err.message });
-      res.status(500).json({ ok: false, state: "error", error: err.message });
-    }
-  } else if (action === "update") {
-    // Update AgentChattr: stop → git pull → pip install → restart
-    const { dir: acDir } = resolveProjectChattr(projectId);
-    if (!acDir || !fs.existsSync(path.join(acDir, "run.py"))) {
-      return res.status(400).json({ ok: false, error: "AgentChattr not installed at " + (acDir || "unknown") });
-    }
-    try {
-      // Stop running process before pulling. Snapshot first so a
-      // botched git pull can still be rolled back from disk.
-      // #424 / quadwork#304: best-effort.
-      await snapshotProjectHistory(projectId).catch(() => {});
-      // Latch the auto-restore opt-in BEFORE stop, same as the
-      // explicit restart branch above — a config mutation during
-      // the git pull shouldn't starve the replay.
-      const updateCfgPre = readConfig();
-      const updateProjectPre = updateCfgPre.projects?.find((p) => p.id === projectId);
-      const updateShouldAutoRestore = !!(updateProjectPre && updateProjectPre.auto_restore_after_restart);
-      const proc = getProc();
-      const wasRunning = proc.process && proc.state === "running";
-      if (wasRunning) {
-        try { proc.process.kill("SIGTERM"); } catch {}
-      }
-      // #386: kill orphaned processes on the port too
-      killProcessOnPort(chattrPort);
-      if (wasRunning) {
-        setProc({ process: null, state: "stopped", error: null });
-        // Wait for the port to be released before pulling/restarting
-        await waitForPortFree(chattrPort, 3000);
-      }
-
-      const pullResult = execFileSync("git", ["pull"], { cwd: acDir, encoding: "utf-8", timeout: 30000, stdio: "pipe" }).trim();
-      // #388: re-apply sender-overflow CSS patch after git pull
-      patchAgentchattrCss(acDir);
-      // #629: re-apply crash timeout patch after git pull (pull may revert app.py)
-      patchCrashTimeout(acDir);
-      const venvPython = path.join(acDir, ".venv", "bin", "python");
-      let pipResult = "";
-      const reqFile = path.join(acDir, "requirements.txt");
-      if (fs.existsSync(venvPython) && fs.existsSync(reqFile)) {
-        pipResult = execFileSync(venvPython, ["-m", "pip", "install", "-r", "requirements.txt"], { cwd: acDir, encoding: "utf-8", timeout: 120000, stdio: "pipe" }).trim();
-      }
-
-      // Restart if it was running before the update
-      let restarted = false;
-      if (wasRunning) {
-        const child = await spawnChattr();
-        restarted = !!child;
-        if (child) {
-          setTimeout(() => syncChattrToken(projectId).catch(() => {}), 2000);
-          // #424 / quadwork#304 Phase 3: auto-restore after an
-          // update-triggered restart too (t2a re-review). Same
-          //3s wait + newest-snapshot-by-mtime path as the explicit
-          // restart branch, using the pre-stop latched opt-in.
-          if (updateShouldAutoRestore) {
-            setTimeout(async () => {
-              try {
-                const snapDir = path.join(require("os").homedir(), ".quadwork", projectId, "history-snapshots");
-                if (!fs.existsSync(snapDir)) return;
-                const newest = fs.readdirSync(snapDir)
-                  .filter((f) => f.endsWith(".json"))
-                  .map((f) => ({ f, t: fs.statSync(path.join(snapDir, f)).mtimeMs }))
-                  .sort((a, b) => b.t - a.t)[0];
-                if (!newest) return;
-                const r = await fetch(`http://127.0.0.1:${PORT}/api/project-history/restore?project=${encodeURIComponent(projectId)}&name=${encodeURIComponent(newest.f)}`, {
-                  method: "POST",
-                });
-                if (r.ok) console.log(`[snapshot] ${projectId} auto-restored ${newest.f} after update`);
-                else console.warn(`[snapshot] ${projectId} post-update auto-restore returned ${r.status}`);
-              } catch (err) {
-                console.warn(`[snapshot] ${projectId} post-update auto-restore failed: ${err.message || err}`);
-              }
-            }, 3000);
-          }
-        }
-      }
+// Per-project AgentChattr lifecycle (removed in #723 — AC stack deleted)
 
-      res.json({ ok: true, pull: pullResult, pip: pipResult, restarted });
-    } catch (err) {
-      res.status(500).json({ ok: false, error: err.message });
-    }
-  } else {
-    res.status(400).json({ error: "Unknown action" });
-  }
+// Stub endpoints — return 410 Gone so dashboard code degrades gracefully
+async function handleAgentChattr(_req, res) {
+  return res.status(410).json({ ok: false, error: "AgentChattr removed in Phase 3" });
 }
-app.post("/api/agentchattr/:projectOrAction/:action", handleAgentChattr);
-app.post("/api/agentchattr/:projectOrAction", handleAgentChattr);
-
-// --- Reset agents: deregister all registered slots ---
-// AgentChattr doesn't expose staleness metadata, so this clears all slots.
-// Agents' wrapper heartbeat will auto-re-register with clean names.
-
-// #416: AC health status endpoint — returns the health monitor state
-// for a project so the dashboard can surface auto-restart events.
-app.get("/api/agentchattr/:project/health", (req, res) => {
-  const projectId = req.params.project;
-  const proc = chattrProcesses.get(projectId);
-  const health = _acHealth.state.get(projectId) || { lastRestart: 0, consecutiveFailures: 0 };
-  res.json({
-    state: proc?.state || "unknown",
-    error: proc?.error || null,
-    autoRestart: {
-      lastRestart: health.lastRestart || null,
-      consecutiveFailures: health.consecutiveFailures,
-      gaveUp: health.consecutiveFailures >= 3,
-    },
-  });
-});
-
 app.post("/api/agents/:project/reset", async (req, res) => {
   const projectId = req.params.project;
 
@@ -1291,6 +594,8 @@ app.post("/api/agents/:project/reset", async (req, res) => {
 
     // Stop all agents first (handles deregistration best-effort)
     for (const agentId of allAgentIds) {
+      const s = agentSessions.get(`${projectId}/${agentId}`);
+      if (s) s._suppressLifecycleMsg = true;
       await stopAgentSession(`${projectId}/${agentId}`);
     }
 
@@ -1298,8 +603,9 @@ app.post("/api/agents/:project/reset", async (req, res) => {
     let restarted = 0;
     const errors = [];
     for (const agentId of allAgentIds) {
-      const result = await spawnAgentPty(projectId, agentId);
+      const result = await spawnAgentPty(projectId, agentId, { suppressLifecycleMsg: true });
       if (result.ok) {
+        emitSystemMessage(projectId, `${agentId} restarted`);
         restarted++;
       } else {
         errors.push(`${agentId}: ${result.error}`);
@@ -1317,7 +623,7 @@ app.post("/api/agents/:project/reset", async (req, res) => {
   }
 });
 
-// --- Full Reset: restart all AC + agents across all projects (#657) ---
+// --- Full Reset: restart all agents across all projects (#657) ---
 
 app.post("/api/full-reset", async (_req, res) => {
   const start = Date.now();
@@ -1326,42 +632,21 @@ app.post("/api/full-reset", async (_req, res) => {
     const cfg = readConfig();
     const projects = (cfg.projects || []).filter((p) => !p.archived);
 
-    // 1. Stop all agent sessions
     console.log("[full-reset] stopping all agent sessions...");
     const sessionKeys = [...agentSessions.keys()];
     for (const key of sessionKeys) {
       await stopAgentSession(key);
     }
 
-    // 2. Stop Butler if running
     console.log("[full-reset] stopping Butler...");
     stopButlerPty();
 
-    // 3. Re-run startup migrations
     console.log("[full-reset] running startup migrations...");
     runStartupMigrations(cfg);
 
-    // 4. Restart each project's AC + agents
     let totalAgents = 0;
     const errors = [];
     for (const project of projects) {
-      console.log(`[full-reset] restarting AC for ${project.id}...`);
-      // Pre-mark reset as scheduled so AC restart's auto-reset timer is suppressed
-      _acHealth.resetState.set(project.id, { status: "scheduled", timestamp: Date.now() });
-      try {
-        const acResp = await fetch(`http://127.0.0.1:${PORT}/api/agentchattr/${encodeURIComponent(project.id)}/restart`, {
-          method: "POST",
-        });
-        if (!acResp.ok) {
-          const errData = await acResp.json().catch(() => ({}));
-          errors.push(`${project.id}: AC restart failed — ${errData.error || acResp.status}`);
-          continue;
-        }
-      } catch (err) {
-        errors.push(`${project.id}: AC — ${err.message}`);
-        continue;
-      }
-      // Explicitly reset agents and await result
       try {
         const resetResp = await fetch(`http://127.0.0.1:${PORT}/api/agents/${encodeURIComponent(project.id)}/reset`, {
           method: "POST",
@@ -1377,7 +662,6 @@ app.post("/api/full-reset", async (_req, res) => {
       }
     }
 
-    // 5. Restart Butler if enabled
     if (cfg.butler?.enabled) {
       console.log("[full-reset] restarting Butler...");
       const result = spawnButlerPty();
@@ -1435,16 +719,45 @@ app.post("/api/agents/:project/:agent/restart", async (req, res) => {
 
   // #241: must await deregister before respawn so the slot frees and
   // the fresh register lands at slot 1 instead of head-2.
+  const existing = agentSessions.get(key);
+  if (existing) existing._suppressLifecycleMsg = true;
   await stopAgentSession(key);
 
-  const result = await spawnAgentPty(project, agent);
+  const result = await spawnAgentPty(project, agent, { suppressLifecycleMsg: true });
   if (result.ok) {
+    emitSystemMessage(project, `${agent} restarted`);
     res.json({ ok: true, state: "running", pid: result.pid });
   } else {
     res.status(500).json({ ok: false, state: "error", error: result.error });
   }
 });
 
+// --- #706: Manual interrupt — send Ctrl+C to agent PTY ---
+
+app.post("/api/agents/:project/:agent/interrupt", (req, res) => {
+  const key = `${req.params.project}/${req.params.agent}`;
+  const session = agentSessions.get(key);
+  if (!session || !session.term) {
+    return res.json({ ok: false, error: "Agent not running" });
+  }
+  safeWrite(session.term, "\x03");
+  console.log(`[interrupt] ${key}: operator sent Ctrl+C`);
+  res.json({ ok: true });
+});
+
+app.post("/api/agents/:project/interrupt-all", (req, res) => {
+  const { project } = req.params;
+  let count = 0;
+  for (const [key, session] of agentSessions) {
+    if (!key.startsWith(`${project}/`)) continue;
+    if (session.state !== "running" || !session.term) continue;
+    safeWrite(session.term, "\x03");
+    count++;
+  }
+  console.log(`[interrupt] ${project}: operator sent Ctrl+C to ${count} agent(s)`);
+  res.json({ ok: true, interrupted: count });
+});
+
 // --- Sessions tracking (for /api/projects dashboard) ---
 
 // Expose agentSessions to migrated routes
@@ -2380,327 +1693,35 @@ setInterval(autoStopPollingTick, AUTO_STOP_POLL_INTERVAL_MS);
 // delay is tens of seconds. Skipping projects without the opt-in
 // keeps the poller cheap for single-project setups.
 
-const _loopGuardPausedState = new Map(); // projectId -> { paused: bool, scheduled: Timeout? }
-const LOOP_GUARD_POLL_INTERVAL_MS = 10000;
-
-async function checkLoopGuardPause(project) {
-  if (!project || !project.auto_continue_loop_guard) return;
-  const { url: base, token: sessionToken } = resolveProjectChattr(project.id);
-  if (!base) return;
-  let paused = false;
-  try {
-    const r = await fetch(`${base}/api/status`, {
-      headers: sessionToken ? { "x-session-token": sessionToken } : {},
-      signal: AbortSignal.timeout(5000),
-    });
-    if (!r.ok) return;
-    const data = await r.json();
-    paused = !!(data && data.paused);
-  } catch {
-    return;
-  }
-  const state = _loopGuardPausedState.get(project.id) || { paused: false, scheduled: null };
-  // Transition false → true: schedule an auto-continue after the delay.
-  if (paused && !state.paused && !state.scheduled) {
-    const delaySec = Number.isFinite(project.auto_continue_delay_sec) && project.auto_continue_delay_sec >= 5
-      ? project.auto_continue_delay_sec
-      : 30;
-    console.log(`[loop-guard] ${project.id} paused — auto-continue in ${delaySec}s`);
-    state.scheduled = setTimeout(async () => {
-      try {
-        // Re-check the opt-in at fire time so a checkbox disable
-        // mid-wait actually stops the auto-continue.
-        const freshCfg = readConfig();
-        const fresh = freshCfg.projects?.find((p) => p.id === project.id);
-        if (!fresh || !fresh.auto_continue_loop_guard) {
-          console.log(`[loop-guard] ${project.id} auto-continue cancelled (opt-in disabled during wait)`);
-        } else {
-          // Re-check the router's pause state at fire time too. The
-          // 10s status poller may not have seen a manual operator
-          // /continue yet when the delay window (5–9s) is shorter
-          // than the poll interval — without this, a manual resume
-          // inside a 5s wait would be followed by a stale auto
-          // /continue that clobbers hop_count on an already-running
-          // chain (router.continue_routing resets the counter
-          // unconditionally). The re-check closes the race.
-          let stillPaused = false;
-          try {
-            const { url: freshBase, token: freshToken } = resolveProjectChattr(project.id);
-            if (freshBase) {
-              const sr = await fetch(`${freshBase}/api/status`, {
-                headers: freshToken ? { "x-session-token": freshToken } : {},
-                signal: AbortSignal.timeout(5000),
-              });
-              if (sr.ok) {
-                const sd = await sr.json();
-                stillPaused = !!(sd && sd.paused);
-              }
-            }
-          } catch {
-            // Status re-check failed — fall back to "don't fire".
-            // Stuck pause will still be caught on the next 10s tick.
-          }
-          if (!stillPaused) {
-            console.log(`[loop-guard] ${project.id} auto-continue cancelled (router already resumed)`);
-          } else {
-            const res = await fetch(`http://127.0.0.1:${PORT}/api/chat?project=${encodeURIComponent(project.id)}`, {
-              method: "POST",
-              headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({ text: "/continue", channel: "general" }),
-            });
-            if (res.ok) console.log(`[loop-guard] ${project.id} auto-continued`);
-            else console.warn(`[loop-guard] ${project.id} auto-continue POST returned ${res.status}`);
-          }
-        }
-      } catch (err) {
-        console.warn(`[loop-guard] ${project.id} auto-continue failed: ${err.message || err}`);
-      }
-      const s2 = _loopGuardPausedState.get(project.id);
-      if (s2) s2.scheduled = null;
-    }, delaySec * 1000);
-  }
-  // Transition true → false: clear any pending timer.
-  if (!paused && state.paused && state.scheduled) {
-    clearTimeout(state.scheduled);
-    state.scheduled = null;
-  }
-  state.paused = paused;
-  _loopGuardPausedState.set(project.id, state);
-}
-
-function runLoopGuardPollingTick() {
-  try {
-    const cfg = readConfig();
-    for (const p of (cfg.projects || [])) {
-      if (p && p.auto_continue_loop_guard) checkLoopGuardPause(p);
-    }
-  } catch {
-    // config unreadable — next tick will retry
-  }
-}
-
-setInterval(runLoopGuardPollingTick, LOOP_GUARD_POLL_INTERVAL_MS);
-
 // --- Start ---
 
-// ---------------------------------------------------------------------------
-// #416: AC health monitor — auto-restart AgentChattr on crash detection.
-// Runs a TCP connect probe every 30s for each project with a "running" AC
-// process. If the port is dead, auto-restarts (reusing the existing restart
-// logic). Rate-limited to one restart per 60s per project; gives up after
-// 3 consecutive failures and surfaces a persistent error.
-// ---------------------------------------------------------------------------
-// #572: restart agents that are running without AC registration after AC
-// recovers from a crash. Scans agentSessions for the given project,
-// finds agents missing acRegistrationName, and stop+respawns them so
-// they get MCP CLI flags at launch time.
-async function restartUnregisteredAgents(projectId) {
-  const toRestart = [];
-  for (const [key, session] of agentSessions) {
-    if (session.projectId !== projectId) continue;
-    if (session.acRegistrationName) continue; // already registered
-    if (session.state !== "running") continue;
-    if (!session.acServerPort || !session.acInjectMode) continue;
-    toRestart.push({ key, agentId: session.agentId });
-  }
-
-  if (toRestart.length === 0) return;
-  const samplePort = agentSessions.get(toRestart[0].key)?.acServerPort || "?";
-  console.log(`[health] AC recovered on port ${samplePort} — restarting ${toRestart.length} agent(s) for chat integration`);
-
-  for (const { key, agentId } of toRestart) {
-    try {
-      console.log(`[health] Restarting agent ${agentId} for project ${projectId} to gain chat integration`);
-      await stopAgentSession(key);
-      await spawnAgentPty(projectId, agentId);
-    } catch (err) {
-      console.error(`[health] Failed to restart agent ${agentId}: ${err.message}`);
-    }
-  }
-}
+// #705: auto-interrupt agents stuck with no PTY output for 10 minutes.
+const WATCHDOG_TIMEOUT_MS = 10 * 60 * 1000;
+let _watchdogHandle = null;
 
-const _acHealth = {
-  // Per-project: { lastRestart: timestamp, consecutiveFailures: number }
-  state: new Map(),
-  intervalHandle: null,
-  // #581: per-project reset state — prevents duplicate resets per restart event.
-  // Values: { status: "scheduled"|"succeeded"|"failed", timestamp: number }
-  resetState: new Map(),
-  // #579: per-project grace period. Projects whose AC entered "running"
-  // within the last 60s are skipped by the health monitor so startup
-  // migrations (bridge-migrate, ghost-fix) and fresh spawns can settle.
-  // Tracked via `runningSince` in chattrProcesses entries.
-};
-
-function isPortAlive(port) {
-  return new Promise((resolve) => {
-    const sock = net.createConnection({ port, host: "127.0.0.1" }, () => {
-      sock.destroy();
-      resolve(true);
-    });
-    sock.on("error", () => resolve(false));
-    sock.setTimeout(2000, () => { sock.destroy(); resolve(false); });
-  });
-}
-
-async function acHealthCheck() {
-  const cfg = readConfig();
-  for (const project of (cfg.projects || [])) {
-    const proc = chattrProcesses.get(project.id);
-    // Only monitor projects that were explicitly started (state === "running"
-    // or had a process). Skip intentionally stopped projects.
-    if (!proc || proc.state === "stopped") continue;
-    // #579: per-project grace period — skip projects whose AC entered
-    // "running" within the last 60s. This lets cmdStart spawns and
-    // startup migrations (bridge-migrate, ghost-fix) settle before the
-    // monitor acts, regardless of when the project was created.
-    if (proc.runningSince && Date.now() - proc.runningSince < 60_000) continue;
-
-    const { url } = resolveProjectChattr(project.id);
-    const portMatch = url.match(/:(\d+)/);
-    const port = portMatch ? parseInt(portMatch[1], 10) : 8300;
-
-    const alive = await isPortAlive(port);
-    const health = _acHealth.state.get(project.id) || { lastRestart: 0, consecutiveFailures: 0 };
-
-    if (alive) {
-      // Healthy — reset failure counter
-      if (health.consecutiveFailures > 0) {
-        console.log(`[health] AC for ${project.id} recovered (port ${port} alive)`);
-        // #572: restart agents that are running without chat integration.
-        // These are agents where the #565 deferred restart timed out, or
-        // agents spawned while AC was down. MCP flags are set at process
-        // launch, so a full stop+respawn is required.
-        // #581: dedupe — skip if a reset is in-flight or succeeded within 60s.
-        // If "scheduled" (in-flight), keep consecutiveFailures=1 so the next
-        // healthy tick re-enters this branch and retries if state became "failed".
-        const rs = _acHealth.resetState.get(project.id);
-        const resetSucceeded = rs && rs.status === "succeeded" && Date.now() - rs.timestamp < 60000;
-        const resetInFlight = rs && rs.status === "scheduled";
-        if (resetSucceeded) {
-          // Already handled — clear failures normally
-        } else if (resetInFlight) {
-          // In-flight — preserve failures so we retry next tick if it fails
-          health.consecutiveFailures = 1;
-          _acHealth.state.set(project.id, health);
-          continue;
-        } else {
-          // No recent reset or previous attempt failed — fire one
-          _acHealth.resetState.set(project.id, { status: "scheduled", timestamp: Date.now() });
-          restartUnregisteredAgents(project.id).then(() => {
-            _acHealth.resetState.set(project.id, { status: "succeeded", timestamp: Date.now() });
-          }).catch((err) => {
-            _acHealth.resetState.set(project.id, { status: "failed", timestamp: Date.now() });
-            console.error(`[health] Failed to restart unregistered agents for ${project.id}:`, err.message);
-          });
-        }
-      }
-      health.consecutiveFailures = 0;
-      _acHealth.state.set(project.id, health);
-      continue;
-    }
-
-    // Port is dead — check rate limits
-    if (health.consecutiveFailures >= 3) {
-      // Already gave up — don't spam restarts. The error state persists
-      // in chattrProcesses for the dashboard to surface.
-      continue;
-    }
-
-    const now = Date.now();
-    if (now - health.lastRestart < 60_000) {
-      // Too soon since last restart attempt
-      continue;
-    }
-
-    health.consecutiveFailures++;
-    health.lastRestart = now;
-    _acHealth.state.set(project.id, health);
-
-    console.warn(`[health] AC for ${project.id} on port ${port} is down (failure ${health.consecutiveFailures}/3) — auto-restarting`);
-
-    // Call the existing restart endpoint internally so we reuse the
-    // hardened path (killProcessOnPort, waitForPortFree, snapshot,
-    // auto-restore) instead of reimplementing spawn logic inline.
-    try {
-      const resp = await fetch(`http://127.0.0.1:${PORT}/api/agentchattr/${encodeURIComponent(project.id)}/restart`, {
-        method: "POST",
-        timeout: 15000,
-      });
-      if (resp.ok) {
-        const data = await resp.json();
-        console.log(`[health] AC for ${project.id} auto-restarted (PID: ${data.pid})`);
-        // #447: agent reset is now chained inside the restart endpoint
-        // itself (fires on a 2s timer), so no separate call needed here.
-      } else {
-        const body = await resp.text().catch(() => "");
-        console.error(`[health] AC auto-restart failed for ${project.id}: ${resp.status} ${body.slice(0, 120)}`);
-        chattrProcesses.set(project.id, { process: null, state: "error", error: `Auto-restart failed: ${resp.status}` });
-      }
-    } catch (err) {
-      console.error(`[health] AC auto-restart failed for ${project.id}:`, err.message);
-      chattrProcesses.set(project.id, { process: null, state: "error", error: `Auto-restart failed: ${err.message}` });
+function watchdogCheck() {
+  for (const [key, session] of agentSessions) {
+    if (session.state !== "running" || !session.term) continue;
+    if (!session.lastOutputAt) continue;
+    // #732: skip file-chat projects — idle is normal, PTY dispatch wakes them
+    if (routes.getProjectChatMode(session.projectId) === "file") continue;
+    if (Date.now() - session.lastOutputAt > WATCHDOG_TIMEOUT_MS) {
+      console.log(`[watchdog] ${key}: no output for 10m — sending Ctrl+C`);
+      safeWrite(session.term, "\x03");
+      session.lastOutputAt = Date.now();
     }
   }
 }
 
-function startAcHealthMonitor() {
-  if (_acHealth.intervalHandle) return;
-  _acHealth.intervalHandle = setInterval(acHealthCheck, 30_000);
-  console.log("[health] AC health monitor started (30s interval, per-project 60s grace)");
+function startWatchdog() {
+  if (_watchdogHandle) return;
+  _watchdogHandle = setInterval(watchdogCheck, 60_000);
+  console.log("[watchdog] stuck-agent watchdog started (60s interval, 10m threshold)");
 }
 
 // #657: extracted startup migrations so full-reset can re-run them
 function runStartupMigrations(cfg) {
   const projects = (cfg.projects || []).filter((p) => !p.archived);
-  const acRestartNeeded = [];
-
-  // bridge-migrate
-  for (const p of projects) {
-    const acPath = projectAgentchattrConfigPath(p.id);
-    if (!fs.existsSync(acPath)) continue;
-    try {
-      const before = fs.readFileSync(acPath, "utf-8");
-      const hadOldDc = /^\[agents\.discord-bridge\]\s*$/m.test(before);
-      const hadOldTg = /^\[agents\.telegram-bridge\]\s*$/m.test(before);
-      const dc = patchAgentchattrConfigForDiscordBridge(before);
-      const tg = patchAgentchattrConfigForTelegramBridge(dc.text);
-      if (dc.changed || tg.changed) {
-        fs.writeFileSync(acPath, tg.text);
-        console.log(`[bridge-migrate] ${p.id}: migrated AC config slugs`);
-        if (hadOldDc || hadOldTg) {
-          if (!acRestartNeeded.includes(p.id)) acRestartNeeded.push(p.id);
-        }
-      }
-    } catch {}
-  }
-
-  // bridge-refresh
-  const DISCORD_BRIDGE_SRC = path.join(__dirname, "..", "bridges", "discord", "discord_bridge.py");
-  const DISCORD_BRIDGE_DEST = path.join(os.homedir(), ".quadwork", "agentchattr-discord", "discord_bridge.py");
-  if (fs.existsSync(DISCORD_BRIDGE_SRC) && fs.existsSync(path.dirname(DISCORD_BRIDGE_DEST))) {
-    try {
-      fs.copyFileSync(DISCORD_BRIDGE_SRC, DISCORD_BRIDGE_DEST);
-      console.log("[bridge-refresh] refreshed Discord bridge script from package");
-    } catch (err) {
-      console.warn(`[bridge-refresh] failed to refresh Discord bridge script: ${err.message || err}`);
-    }
-  }
-
-  // bridge slug patches
-  const BRIDGE_SLUG_PATCHES = [
-    { file: path.join(os.homedir(), ".quadwork", "agentchattr-telegram", "telegram_bridge.py"), old: '"telegram-bridge"', replacement: '"tg"' },
-    { file: path.join(os.homedir(), ".quadwork", "agentchattr-discord", "discord_bridge.py"), old: '"discord-bridge"', replacement: '"dc"' },
-  ];
-  for (const { file, old, replacement } of BRIDGE_SLUG_PATCHES) {
-    try {
-      if (!fs.existsSync(file)) continue;
-      const content = fs.readFileSync(file, "utf-8");
-      if (!content.includes(old)) continue;
-      fs.writeFileSync(file, content.replaceAll(old, replacement));
-      console.log(`[bridge-migrate] patched stale bridge_sender in ${path.basename(file)}`);
-    } catch {}
-  }
 
   // reseed stale slugs
   const SLUG_FIXES = [
@@ -2736,109 +1757,6 @@ function runStartupMigrations(cfg) {
     }
   }
 
-  // ghost-fix + idle-fix
-  for (const p of projects) {
-    const acDir = resolveProjectChattr(p.id).dir;
-    const regPath = path.join(acDir, "registry.py");
-    if (fs.existsSync(regPath)) {
-      try {
-        let reg = fs.readFileSync(regPath, "utf-8");
-        if (!reg.includes("force: bool")) {
-          reg = reg.replace(
-            /def register\(self, base: str, label: str \| None = None\) -> dict \| None:/,
-            "def register(self, base: str, label: str | None = None, force: bool = False) -> dict | None:",
-          );
-          reg = reg.replace(
-            "            self._expire_reserved()\n\n            # Find next free slot",
-            "            self._expire_reserved()\n\n" +
-            "            # quadwork#478 + #502: force-replace\n" +
-            "            if force:\n" +
-            "                ghosts = [n for n, i in self._instances.items() if i.base == base]\n" +
-            "                for name in ghosts:\n" +
-            "                    del self._instances[name]\n" +
-            "                stale_reserved = [rn for rn in self._reserved\n" +
-            "                                  if self._parse_name(rn)[0] == base]\n" +
-            "                for rn in stale_reserved:\n" +
-            "                    del self._reserved[rn]\n\n" +
-            "            # Find next free slot",
-          );
-          fs.writeFileSync(regPath, reg);
-          console.log(`[ghost-fix] ${p.id}: patched registry.py with force-replace support`);
-        } else if (!reg.includes("stale_reserved")) {
-          reg = reg.replace(
-            /( +)for name in ghosts:\n\1    del self\._instances\[name\]\n\1    self\._reserved\[name\] = time\.time\(\)/,
-            "$1for name in ghosts:\n$1    del self._instances[name]\n" +
-            "$1stale_reserved = [rn for rn in self._reserved\n" +
-            "$1                  if self._parse_name(rn)[0] == base]\n" +
-            "$1for rn in stale_reserved:\n" +
-            "$1    del self._reserved[rn]",
-          );
-          fs.writeFileSync(regPath, reg);
-          console.log(`[ghost-fix] ${p.id}: upgraded registry.py force-replace to clear _reserved (#502)`);
-        }
-      } catch (err) {
-        console.warn(`[ghost-fix] ${p.id}: failed to patch registry.py: ${err.message}`);
-      }
-    }
-    const appPath = path.join(acDir, "app.py");
-    if (fs.existsSync(appPath)) {
-      try {
-        let app = fs.readFileSync(appPath, "utf-8");
-        if (!app.includes("force = bool(body.get(\"force\"")) {
-          app = app.replace(
-            "    result = registry.register(base, label)\n",
-            "    force = bool(body.get(\"force\", False))\n    result = registry.register(base, label, force=force)\n",
-          );
-          fs.writeFileSync(appPath, app);
-          console.log(`[ghost-fix] ${p.id}: patched app.py with force-replace support`);
-        }
-      } catch (err) {
-        console.warn(`[ghost-fix] ${p.id}: failed to patch app.py: ${err.message}`);
-      }
-    }
-    if (fs.existsSync(appPath)) {
-      try {
-        const app = fs.readFileSync(appPath, "utf-8");
-        if (app.includes("_CRASH_TIMEOUT = 15")) {
-          patchCrashTimeout(acDir);
-          console.log(`[idle-fix] ${p.id}: crash timeout patched on disk`);
-          acRestartNeeded.push(p.id);
-        }
-      } catch (err) {
-        console.warn(`[idle-fix] ${p.id}: failed to patch app.py crash timeout: ${err.message}`);
-      }
-    }
-  }
-
-  // CLI-based agent sections
-  for (const p of projects) {
-    const acPath = projectAgentchattrConfigPath(p.id);
-    if (!fs.existsSync(acPath)) continue;
-    try {
-      let toml = fs.readFileSync(acPath, "utf-8");
-      const cliSections = new Set();
-      for (const [, agentCfg] of Object.entries(p.agents || {})) {
-        const cmd = agentCfg.command || "claude";
-        const cli = cmd.split("/").pop().split(" ")[0];
-        cliSections.add(cli);
-      }
-      let changed = false;
-      for (const cli of cliSections) {
-        if (!new RegExp(`^\\[agents\\.${cli}\\]`, "m").test(toml)) {
-          const injectMode = cli === "codex" ? "proxy_flag" : cli === "gemini" ? "env" : "flag";
-          toml += `\n[agents.${cli}]\ncommand = "${cli}"\nlabel = "${cli}"\nmcp_inject = "${injectMode}"\n`;
-          changed = true;
-        }
-      }
-      if (changed) {
-        fs.writeFileSync(acPath, toml);
-        console.log(`[#596] ${p.id}: added CLI-based agent sections to config.toml`);
-      }
-    } catch (err) {
-      console.warn(`[#596] ${p.id}: config.toml migration failed: ${err.message}`);
-    }
-  }
-
   // #690: seed DESIGN-GUIDE.md into existing agent worktrees
   const designGuideSrc = path.join(__dirname, "..", "templates", "seeds", "DESIGN-GUIDE.md");
   if (fs.existsSync(designGuideSrc)) {
@@ -2859,97 +1777,66 @@ function runStartupMigrations(cfg) {
     }
   }
 
-  return acRestartNeeded;
 }
 
 server.listen(PORT, "127.0.0.1", async () => {
   console.log(`QuadWork server listening on http://127.0.0.1:${PORT}`);
   syncTriggersFromConfig();
-  // #579: detect AC processes already running (spawned by cmdStart before
-  // the server module loaded). Without this, chattrProcesses is empty on
-  // boot and the health monitor can't track cmdStart-spawned ACs, while
-  // the dashboard's Start button would redundantly kill+respawn them.
   const startupCfg = readConfig();
-  for (const p of (startupCfg.projects || [])) {
-    const { url: acUrl } = resolveProjectChattr(p.id);
-    const acPortMatch = acUrl.match(/:(\d+)/);
-    const acPort = acPortMatch ? parseInt(acPortMatch[1], 10) : 8300;
-    const alive = await isPortAlive(acPort);
-    if (alive && !chattrProcesses.has(p.id)) {
-      // AC is already running (e.g. spawned by cmdStart). Record it so
-      // the health monitor can track it and the dashboard shows the
-      // correct state. process is null because we don't own the child.
-      chattrProcesses.set(p.id, { process: null, state: "running", error: null, runningSince: Date.now() });
-      console.log(`[startup] ${p.id}: AC already alive on port ${acPort} — tracking`);
+
+  // #719: Migrate AC chat history to JSONL before initializing file-chat.
+  const migrationFailed = new Set(runAcMigration(startupCfg));
+
+  // #722: One-time switchover — set all projects to file-based chat.
+  if (!startupCfg.file_chat_switchover_done) {
+    let switched = false;
+    for (const p of (startupCfg.projects || [])) {
+      if (p.chat_mode !== "file" && !migrationFailed.has(p.id)) {
+        p.chat_mode = "file";
+        switched = true;
+        console.log(`[startup] ${p.id}: switched to file-based chat`);
+      }
     }
+    startupCfg.file_chat_switchover_done = true;
+    writeConfig(startupCfg);
+    if (switched) console.log("[startup] file-chat switchover complete");
   }
-  // Sync AgentChattr tokens for all projects on startup and backfill
-  // the sender-overflow CSS/JS patch (#402) so already-running AC
-  // instances receive the fix without requiring a restart.
-  // #448: retry after 5s for projects where AC isn't up yet at boot.
+
+  // Initialize file-chat engine for all projects.
   for (const p of (startupCfg.projects || [])) {
-    syncChattrToken(p.id).catch(() => {
-      setTimeout(() => syncChattrToken(p.id).catch(() => {}), 5000);
-    });
-    const { dir: acDir } = resolveProjectChattr(p.id);
-    if (acDir) patchAgentchattrCss(acDir);
-  }
-  const acRestartNeeded = runStartupMigrations(startupCfg);
-  startupCfg._acRestartNeeded = acRestartNeeded.length > 0 ? acRestartNeeded : undefined;
-  // #629: restart AC for projects where idle-fix patched the on-disk file
-  // so the running Python process picks up _CRASH_TIMEOUT = 120.
-  // Use port-alive check instead of chattrProcesses — AC may be running
-  // from a previous QuadWork instance (tracked with process: null).
-  if (startupCfg._acRestartNeeded) {
-    for (const projectId of startupCfg._acRestartNeeded) {
-      const { url } = resolveProjectChattr(projectId);
-      const portMatch = url.match(/:(\d+)/);
-      const port = portMatch ? parseInt(portMatch[1], 10) : 8300;
-      isPortAlive(port).then((alive) => {
-        if (!alive) return;
-        console.log(`[idle-fix] ${projectId}: restarting AC (port ${port}) so running process observes _CRASH_TIMEOUT = 120 (#629)`);
-        return fetch(`http://127.0.0.1:${PORT}/api/agentchattr/${encodeURIComponent(projectId)}/restart`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ action: "restart" }),
-        });
-      }).then((r) => {
-        if (r && r.ok) console.log(`[idle-fix] ${projectId}: AC restarted successfully`);
-        else if (r) console.warn(`[idle-fix] ${projectId}: AC restart returned ${r.status}`);
-      }).catch((err) => {
-        console.warn(`[idle-fix] ${projectId}: AC restart failed: ${err.message}`);
-      });
+    if (p.chat_mode === "file") {
+      if (migrationFailed.has(p.id)) {
+        console.error(`[startup] ${p.id}: migration failed — skipping file-chat init`);
+        continue;
+      }
+      try {
+        fileChat.initProject(p.id);
+        console.log(`[startup] ${p.id}: file-chat engine initialized`);
+      } catch (err) {
+        console.error(`[startup] FATAL: ${p.id}: ${err.message}`);
+        process.exit(1);
+      }
     }
   }
-  // #631 + #632: auto-start Butler if enabled + auto_start
+
+  runStartupMigrations(startupCfg);
+
   if (startupCfg.butler && startupCfg.butler.enabled && startupCfg.butler.auto_start) {
     const result = spawnButlerPty();
     if (result.ok) console.log(`[butler] auto-started (PID: ${result.pid})`);
     else console.warn(`[butler] auto-start failed: ${result.error}`);
   }
-  // #416: start the AC health monitor
-  startAcHealthMonitor();
+  startWatchdog();
 });
 
-/**
- * Send SIGTERM to every AgentChattr child currently tracked by the
- * server. Exported so bin/quadwork.js (`cmdInit` / `cmdStart`) can
- * call it from its own SIGINT handler — AgentChattr children spawned
- * by the dashboard's /api/agentchattr/{id}/start endpoint live in
- * this process's in-memory `chattrProcesses` Map and are otherwise
- * invisible to the CLI. Without this, a Ctrl+C in the foreground
- * quadwork terminal would exit the Node process and orphan every
- * dashboard-started python run.py. See review on quadwork#213.
- */
-function shutdownChattrProcesses() {
-  for (const [, proc] of chattrProcesses) {
-    if (proc && proc.process) {
-      try { proc.process.kill("SIGTERM"); } catch {}
+function shutdown() {
+  stopButlerPty();
+  const cfg = readConfig();
+  for (const p of (cfg.projects || [])) {
+    if (p.chat_mode === "file") {
+      try { fileChat.shutdownProject(p.id); } catch {}
     }
   }
-  chattrProcesses.clear();
-  // #631: stop Butler PTY on shutdown
-  stopButlerPty();
 }
 
-module.exports = { shutdownChattrProcesses };
+module.exports = { shutdown };