quadwork 1.2.3 → 1.2.5

package/server/index.js

@@ -8,7 +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 } = require("./agentchattr-registry");
+const { waitForAgentChattrReady, registerAgent, deregisterAgent, startHeartbeat, stopHeartbeat } = require("./agentchattr-registry");
+const { startQueueWatcher, stopQueueWatcher } = require("./queue-watcher");
 
 const net = require("net");
 const config = readConfig();
@@ -146,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"];
 
@@ -180,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);
@@ -267,7 +289,7 @@ 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 };
+  if (!project) return { args: [], acRegistrationName: null, acServerPort: null, acRegistrationToken: null, acInjectMode: null, acMcpHttpPort: null };
 
   const agentCfg = project.agents?.[agentId] || {};
   const command = agentCfg.command || "claude";
@@ -275,6 +297,8 @@ async function buildAgentArgs(projectId, agentId) {
   const args = [];
   let acRegistrationName = null;
   let acServerPort = null;
+  let acRegistrationToken = null;
+  let acInjectMode = null;
 
   // Permission bypass flags
   if (agentCfg.auto_approve !== false) {
@@ -287,6 +311,7 @@ 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: register with AgentChattr to obtain a per-agent
       // token (#239 — session_token is browser auth, not MCP auth) and
@@ -311,6 +336,7 @@ async function buildAgentArgs(projectId, agentId) {
         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";
@@ -335,6 +361,7 @@ async function buildAgentArgs(projectId, agentId) {
         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, registration.token);
@@ -344,7 +371,7 @@ async function buildAgentArgs(projectId, agentId) {
     }
   }
 
-  return { args, acRegistrationName, acServerPort };
+  return { args, acRegistrationName, acServerPort, acRegistrationToken, acInjectMode, acMcpHttpPort: mcpHttpPort || null };
 }
 
 /**
@@ -383,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}`;
@@ -413,9 +507,53 @@ async function spawnAgentPty(project, agent) {
       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) {
@@ -427,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;
+        }
       }
     });
 
@@ -457,6 +616,18 @@ async 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) {
@@ -469,6 +640,7 @@ async function stopAgentSession(key) {
       clearPersistedAgentToken(session.projectId, session.agentId);
     }
     session.acRegistrationName = null;
+    session.acRegistrationToken = null;
   }
   // Clean up MCP auth proxy if running
   const [projectId, agentId] = key.split("/");

package/server/queue-watcher.js

@@ -0,0 +1,125 @@
+/**
+ * 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, " ");
+      // Inject text and Enter as SEPARATE writes with a delay between.
+      // Codex's TUI does not submit when text + "\r" arrive in one chunk —
+      // it needs the text to render, then a separate Enter keystroke.
+      // Claude Code accepts either form. Mirrors wrapper_unix.py inject():
+      // tmux send-keys -l <text> ; sleep ; tmux send-keys Enter.
+      // Delay scales with prompt length so longer prompts get more time
+      // to render before submit.
+      ptyTerm.write(flat);
+      const submitDelayMs = Math.max(300, flat.length);
+      setTimeout(() => {
+        try { ptyTerm.write("\r"); } catch { /* swallow */ }
+      }, submitDelayMs);
+    } 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: