quadwork 1.2.2 → 1.2.4

package/server/index.js

@@ -8,6 +8,8 @@ const pty = require("node-pty");
 const { spawn } = require("child_process");
 const { readConfig, resolveAgentCwd, resolveAgentCommand, resolveProjectChattr, resolveChattrSpawn, syncChattrToken, CONFIG_PATH } = require("./config");
 const routes = require("./routes");
+const { waitForAgentChattrReady, registerAgent, deregisterAgent, startHeartbeat, stopHeartbeat } = require("./agentchattr-registry");
+const { startQueueWatcher, stopQueueWatcher } = require("./queue-watcher");
 
 const net = require("net");
 const config = readConfig();
@@ -145,14 +147,20 @@ function startMcpProxy(projectId, agentId, upstreamUrl, token) {
   const existing = mcpProxies.get(key);
   if (existing) return Promise.resolve(`http://127.0.0.1:${existing.port}/mcp`);
 
+  // #394 / quadwork#253: token is mutable so the 409 recovery path can
+  // swap it via updateMcpProxyToken without rebinding the listener —
+  // Codex was launched with a fixed proxy URL on an ephemeral port and
+  // can't be told to use a new one mid-flight.
+  const tokenRef = { current: token };
   return new Promise((resolve, reject) => {
     const proxyServer = http.createServer((req, res) => {
       const parsedUrl = new URL(req.url, `http://127.0.0.1`);
       const targetUrl = `${upstreamUrl}${parsedUrl.pathname}${parsedUrl.search}`;
       const headers = { ...req.headers, host: new URL(upstreamUrl).host };
-      if (token) {
-        headers["authorization"] = `Bearer ${token}`;
-        headers["x-agent-token"] = token;
+      const tok = tokenRef.current;
+      if (tok) {
+        headers["authorization"] = `Bearer ${tok}`;
+        headers["x-agent-token"] = tok;
       }
       delete headers["content-length"];
 
@@ -179,12 +187,27 @@ function startMcpProxy(projectId, agentId, upstreamUrl, token) {
     proxyServer.on("error", (err) => reject(err));
     proxyServer.listen(0, "127.0.0.1", () => {
       const port = proxyServer.address().port;
-      mcpProxies.set(key, { server: proxyServer, port });
+      mcpProxies.set(key, { server: proxyServer, port, tokenRef });
       resolve(`http://127.0.0.1:${port}/mcp`);
     });
   });
 }
 
+/**
+ * Swap the bearer token of a running MCP proxy in place. Used by the
+ * sub-D 409 recovery path: rebinding the listener would change the
+ * ephemeral port and the running Codex process is pinned to the
+ * original URL, so we mutate the closure-captured tokenRef instead.
+ * Returns true if a proxy existed and was updated.
+ */
+function updateMcpProxyToken(projectId, agentId, newToken) {
+  const key = `${projectId}/${agentId}`;
+  const proxy = mcpProxies.get(key);
+  if (!proxy || !proxy.tokenRef) return false;
+  proxy.tokenRef.current = newToken;
+  return true;
+}
+
 function stopMcpProxy(projectId, agentId) {
   const key = `${projectId}/${agentId}`;
   const proxy = mcpProxies.get(key);
@@ -207,6 +230,39 @@ const PERMISSION_FLAGS = {
  * Generate a per-agent MCP config file for Claude (--mcp-config).
  * Returns the absolute path to the written JSON file.
  */
+/**
+ * Per-agent registration tokens persisted across QuadWork restarts so
+ * #242 stale-slot reclaim works after a crash. Without this the
+ * in-memory _tokenCache is empty on startup and the family-name
+ * deregister returns 403 (app.py:2123-2135).
+ */
+function _agentTokenPath(projectId, agentId) {
+  const configDir = path.join(os.homedir(), ".quadwork", projectId);
+  return path.join(configDir, `agent-token-${agentId}.txt`);
+}
+
+function readPersistedAgentToken(projectId, agentId) {
+  try {
+    return fs.readFileSync(_agentTokenPath(projectId, agentId), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function writePersistedAgentToken(projectId, agentId, token) {
+  try {
+    const configDir = path.join(os.homedir(), ".quadwork", projectId);
+    if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(_agentTokenPath(projectId, agentId), token, { mode: 0o600 });
+  } catch {
+    // non-fatal — stale-slot reclaim will degrade but registration still works
+  }
+}
+
+function clearPersistedAgentToken(projectId, agentId) {
+  try { fs.unlinkSync(_agentTokenPath(projectId, agentId)); } catch {}
+}
+
 function writeMcpConfigFile(projectId, agentId, mcpHttpPort, token) {
   const os = require("os");
   const configDir = path.join(os.homedir(), ".quadwork", projectId);
@@ -233,12 +289,16 @@ 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 [];
+  if (!project) return { args: [], acRegistrationName: null, acServerPort: null, acRegistrationToken: null, acInjectMode: null, acMcpHttpPort: null };
 
   const agentCfg = project.agents?.[agentId] || {};
   const command = agentCfg.command || "claude";
   const cliBase = command.split("/").pop().split(" ")[0]; // extract base CLI name
   const args = [];
+  let acRegistrationName = null;
+  let acServerPort = null;
+  let acRegistrationToken = null;
+  let acInjectMode = null;
 
   // Permission bypass flags
   if (agentCfg.auto_approve !== false) {
@@ -251,22 +311,67 @@ async function buildAgentArgs(projectId, agentId) {
   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: write config file, pass --mcp-config
-      const mcpConfigPath = writeMcpConfigFile(projectId, agentId, mcpHttpPort, token);
+      // 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;
+      await waitForAgentChattrReady(acServerPort);
+      // #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 / reviewer2-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);
+      }
+      const registration = await registerAgent(acServerPort, agentId, agentCfg.display_name || null);
+      if (!registration) {
+        throw new Error(`Failed to register ${agentId}: ${registerAgent.lastError}`);
+      }
+      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: start local auth proxy, pass proxy URL via -c 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;
+      await waitForAgentChattrReady(acServerPort);
+      // #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);
+      }
+      const registration = await registerAgent(acServerPort, agentId, agentCfg.display_name || null);
+      if (!registration) {
+        throw new Error(`Failed to register ${agentId}: ${registerAgent.lastError}`);
+      }
+      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, token);
+      const proxyUrl = await startMcpProxy(projectId, agentId, upstreamUrl, registration.token);
       if (proxyUrl) {
         args.push("-c", `mcp_servers.agentchattr.url="${proxyUrl}"`);
       }
     }
   }
 
-  return args;
+  return { args, acRegistrationName, acServerPort, acRegistrationToken, acInjectMode, acMcpHttpPort: mcpHttpPort || null };
 }
 
 /**
@@ -305,6 +410,73 @@ 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);
+  }
+
+  const replacement = await registerAgent(session.acServerPort, agentId, agentCfg.display_name || null);
+  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) {
   const key = `${project}/${agent}`;
@@ -313,7 +485,8 @@ async function spawnAgentPty(project, agent) {
   if (!cwd) return { ok: false, error: `Unknown agent: ${key}` };
 
   const command = resolveAgentCommand(project, agent) || (process.env.SHELL || "/bin/zsh");
-  const args = await buildAgentArgs(project, agent);
+  const built = await buildAgentArgs(project, agent);
+  const args = built.args;
   const extraEnv = buildAgentEnv(project, agent);
 
   try {
@@ -325,9 +498,62 @@ async function spawnAgentPty(project, agent) {
       env: { ...process.env, ...extraEnv },
     });
 
-    const session = { projectId: project, agentId: agent, term, ws: null, state: "running", error: null };
+    const session = {
+      projectId: project,
+      agentId: agent,
+      term,
+      ws: null,
+      state: "running",
+      error: null,
+      acRegistrationName: built.acRegistrationName,
+      acServerPort: built.acServerPort,
+      acRegistrationToken: built.acRegistrationToken,
+      acInjectMode: built.acInjectMode,
+      acMcpHttpPort: built.acMcpHttpPort,
+      acHeartbeatHandle: null,
+      queueWatcherHandle: null,
+    };
     agentSessions.set(key, session);
 
+    // #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
+      }
+    }
+
     term.onExit(({ exitCode }) => {
       const current = agentSessions.get(key);
       if (current && current.term === term) {
@@ -339,6 +565,27 @@ async function spawnAgentPty(project, agent) {
           current.ws.close(1000, `exited:${exitCode}`);
         }
         current.ws = null;
+        // #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;
+        }
       }
     });
 
@@ -349,8 +596,11 @@ async function spawnAgentPty(project, agent) {
   }
 }
 
-// Helper: stop an agent session — kill PTY, close WS
-function stopAgentSession(key) {
+// 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, ws: null, state: "stopped", error: null });
@@ -366,6 +616,32 @@ function stopAgentSession(key) {
   session.ws = null;
   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);
@@ -630,10 +906,10 @@ app.post("/api/agents/:project/:agent/start", async (req, res) => {
 
 // --- Lifecycle: stop kills PTY + closes WS ---
 
-app.post("/api/agents/:project/:agent/stop", (req, res) => {
+app.post("/api/agents/:project/:agent/stop", async (req, res) => {
   const { project, agent } = req.params;
   const key = `${project}/${agent}`;
-  stopAgentSession(key);
+  await stopAgentSession(key);
   res.json({ ok: true, state: "stopped" });
 });
 
@@ -643,16 +919,16 @@ app.post("/api/agents/:project/:agent/restart", async (req, res) => {
   const { project, agent } = req.params;
   const key = `${project}/${agent}`;
 
-  stopAgentSession(key);
+  // #241: must await deregister before respawn so the slot frees and
+  // the fresh register lands at slot 1 instead of head-2.
+  await stopAgentSession(key);
 
-  setTimeout(async () => {
-    const result = await spawnAgentPty(project, agent);
-    if (result.ok) {
-      res.json({ ok: true, state: "running", pid: result.pid });
-    } else {
-      res.status(500).json({ ok: false, state: "error", error: result.error });
-    }
-  }, 500);
+  const result = await spawnAgentPty(project, agent);
+  if (result.ok) {
+    res.json({ ok: true, state: "running", pid: result.pid });
+  } else {
+    res.status(500).json({ ok: false, state: "error", error: result.error });
+  }
 });
 
 // --- Sessions tracking (for /api/projects dashboard) ---

package/server/queue-watcher.js

@@ -0,0 +1,114 @@
+/**
+ * Per-agent queue watcher (#393 / quadwork#251).
+ *
+ * AgentChattr does NOT push chat to agents. When the operator types
+ * `@head` in chat, AC writes a job line to `{data_dir}/{name}_queue.jsonl`
+ * and walks away. Something on the agent side has to poll that file and
+ * inject an `mcp read` prompt into the running CLI's PTY so the agent
+ * picks up the chat. Without that injection the agent never responds,
+ * even when registration and heartbeats work.
+ *
+ * Reference: /Users/cho/Projects/agentchattr/wrapper.py lines 438-541
+ * (`_queue_watcher`). Polling (not fs.watch) is intentional: matches
+ * wrapper.py's behavior and avoids the cross-platform fs.watch
+ * footguns. The role/rules/identity-hint additions from wrapper.py
+ * lines 501-528 are intentionally out of scope for v1 per the issue.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const POLL_INTERVAL_MS = 1000;
+
+/**
+ * Start polling `{dataDir}/{agentName}_queue.jsonl`. When non-empty,
+ * read all lines, truncate the file (atomic-ish claim — same race the
+ * Python wrapper accepts), parse each JSON line, build a single
+ * injected prompt, and write it into the supplied PTY terminal.
+ *
+ * Returns an opaque interval handle. Pass it to stopQueueWatcher to
+ * cancel; safe to call with null.
+ */
+function startQueueWatcher(dataDir, agentName, ptyTerm) {
+  if (!dataDir || !agentName || !ptyTerm) return null;
+  const queueFile = path.join(dataDir, `${agentName}_queue.jsonl`);
+
+  const tick = () => {
+    try {
+      if (!fs.existsSync(queueFile)) return;
+      const stat = fs.statSync(queueFile);
+      if (stat.size === 0) return;
+
+      const content = fs.readFileSync(queueFile, "utf-8");
+      // Atomic claim: truncate immediately so the next AC write lands
+      // in an empty file and we don't double-process the same job on
+      // the next tick. There's a small race if AC writes between the
+      // read and the truncate; wrapper.py accepts the same race.
+      fs.writeFileSync(queueFile, "");
+
+      const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+      if (lines.length === 0) return;
+
+      let channel = "general";
+      let customPrompt = "";
+      let jobId = null;
+      let hasTrigger = false;
+      for (const line of lines) {
+        let data;
+        try {
+          data = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        hasTrigger = true;
+        if (data && typeof data === "object") {
+          if (typeof data.channel === "string") channel = data.channel;
+          // AgentChattr serializes job_id as an integer (agents.py
+          // defines `job_id: int | None`), so accept both numbers and
+          // strings here. Without this, job-thread triggers fall back
+          // to the channel prompt and the agent reads the wrong
+          // conversation. Cast to string for the prompt template.
+          if (typeof data.job_id === "number" || typeof data.job_id === "string") {
+            jobId = String(data.job_id);
+          }
+          if (typeof data.prompt === "string" && data.prompt.trim()) {
+            customPrompt = data.prompt.trim();
+          }
+        }
+      }
+      if (!hasTrigger) return;
+
+      let prompt;
+      if (customPrompt) {
+        prompt = customPrompt;
+      } else if (jobId) {
+        prompt = `mcp read job_id=${jobId} - you were mentioned in a job thread, take appropriate action`;
+      } else {
+        prompt = `mcp read #${channel} - you were mentioned, take appropriate action`;
+      }
+
+      // Flatten newlines: multi-line writes trigger paste detection in
+      // Claude Code (shows "[Pasted text +N]") and can break injection
+      // of long prompts. Mirrors wrapper.py:532.
+      const flat = prompt.replace(/\n/g, " ");
+      ptyTerm.write(flat + "\r");
+    } catch {
+      // Swallow — next tick will retry. Logging here would spam the
+      // server output once per second on a permission error.
+    }
+  };
+
+  return setInterval(tick, POLL_INTERVAL_MS);
+}
+
+/**
+ * Stop a watcher started by startQueueWatcher. Safe to call with null.
+ */
+function stopQueueWatcher(handle) {
+  if (handle) clearInterval(handle);
+}
+
+module.exports = {
+  startQueueWatcher,
+  stopQueueWatcher,
+};

package/server/routes.js

@@ -922,6 +922,44 @@ router.post("/api/setup", (req, res) => {
       // ~/.quadwork/{id}/OVERNIGHT-QUEUE.md.
       writeOvernightQueueFileSafe(id, name || id, repo);
 
+      // Batch 28 / #392 / quadwork#252: auto-spawn the per-project
+      // AgentChattr process. The CLI wizard's writeAgentChattrConfig
+      // does this; the web wizard previously left the install dormant
+      // until the user clicked Restart, so MCP fell through to a stale
+      // instance on port 8300. Mirror the loopback-restart pattern
+      // already used by the agentchattr-config branch above. Failures
+      // are non-fatal — the dashboard's Restart button is still
+      // available, and per the issue add-config must still return ok.
+      try {
+        const qwPort = cfg.port || 8400;
+        fetch(
+          `http://127.0.0.1:${qwPort}/api/agentchattr/${encodeURIComponent(id)}/restart`,
+          { method: "POST" },
+        )
+          .then(async (r) => {
+            // /restart reports spawn failures (e.g. port collision —
+            // server/index.js:650-668) as HTTP 500, so a resolved
+            // fetch is not the same thing as a successful spawn. Log
+            // non-2xx responses with status and body so the operator
+            // can see why the auto-spawn silently didn't take.
+            if (!r.ok) {
+              let detail = "";
+              try { detail = (await r.text()).slice(0, 500); } catch {}
+              console.warn(
+                `[setup] auto-spawn AgentChattr for ${id} returned HTTP ${r.status}: ${detail}`,
+              );
+            }
+          })
+          .catch((err) => {
+            console.warn(
+              `[setup] auto-spawn AgentChattr for ${id} failed:`,
+              err.message || err,
+            );
+          });
+      } catch (err) {
+        console.warn(`[setup] auto-spawn AgentChattr for ${id} skipped:`, err.message || err);
+      }
+
       return res.json({ ok: true });
     }
     default: