quadwork 1.5.1 → 1.5.3

package/out/setup.txt

@@ -11,7 +11,7 @@ d:I[11717,["/_next/static/chunks/04_t39bv8y9pe.js","/_next/static/chunks/0ox7p_s
 f:I[92243,["/_next/static/chunks/04_t39bv8y9pe.js","/_next/static/chunks/0ox7p_szjhn69.js"],"default",1]
 :HL["/_next/static/chunks/0ccoe1hsu70ql.css","style"]
 :HL["/_next/static/media/797e433ab948586e-s.p.0.q-h669a_dqa.woff2","font",{"crossOrigin":"","type":"font/woff2"}]
-0:{"P":null,"c":["","setup"],"q":"","i":false,"f":[[["",{"children":["setup",{"children":["__PAGE__",{}]}]},"$undefined","$undefined",16],[["$","$1","c",{"children":[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/chunks/0ccoe1hsu70ql.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}],["$","script","script-0",{"src":"/_next/static/chunks/04_t39bv8y9pe.js","async":true,"nonce":"$undefined"}],["$","script","script-1",{"src":"/_next/static/chunks/0ox7p_szjhn69.js","async":true,"nonce":"$undefined"}]],["$","html",null,{"lang":"en","className":"geist_mono_8d43a2aa-module__8Li5zG__variable h-full","children":["$","body",null,{"className":"h-full flex flex-col","children":[["$","$L2",null,{}],["$","div",null,{"className":"flex flex-1 min-h-0","children":[["$","$L3",null,{}],["$","main",null,{"className":"flex-1 min-w-0 overflow-auto","children":["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":404}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],[]],"forbidden":"$undefined","unauthorized":"$undefined"}]}]]}]]}]}]]}],{"children":[["$","$1","c",{"children":[null,["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","forbidden":"$undefined","unauthorized":"$undefined"}]]}],{"children":[["$","$1","c",{"children":[["$","$L6",null,{}],[["$","script","script-0",{"src":"/_next/static/chunks/084lff9v4p_vh.js","async":true,"nonce":"$undefined"}]],["$","$L7",null,{"children":["$","$8",null,{"name":"Next.MetadataOutlet","children":"$@9"}]}]]}],{},null,false,null]},null,false,"$@a"]},null,false,null],["$","$1","h",{"children":[null,["$","$Lb",null,{"children":"$Lc"}],["$","div",null,{"hidden":true,"children":["$","$Ld",null,{"children":["$","$8",null,{"name":"Next.Metadata","children":"$Le"}]}]}],["$","meta",null,{"name":"next-size-adjust","content":""}]]}],false]],"m":"$undefined","G":["$f",[["$","link","0",{"rel":"stylesheet","href":"/_next/static/chunks/0ccoe1hsu70ql.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}]]],"S":true,"h":null,"s":"$undefined","l":"$undefined","p":"$undefined","d":"$undefined","b":"wxXtT0v8ALxniu3OdJwt5"}
+0:{"P":null,"c":["","setup"],"q":"","i":false,"f":[[["",{"children":["setup",{"children":["__PAGE__",{}]}]},"$undefined","$undefined",16],[["$","$1","c",{"children":[[["$","link","0",{"rel":"stylesheet","href":"/_next/static/chunks/0ccoe1hsu70ql.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}],["$","script","script-0",{"src":"/_next/static/chunks/04_t39bv8y9pe.js","async":true,"nonce":"$undefined"}],["$","script","script-1",{"src":"/_next/static/chunks/0ox7p_szjhn69.js","async":true,"nonce":"$undefined"}]],["$","html",null,{"lang":"en","className":"geist_mono_8d43a2aa-module__8Li5zG__variable h-full","children":["$","body",null,{"className":"h-full flex flex-col","children":[["$","$L2",null,{}],["$","div",null,{"className":"flex flex-1 min-h-0","children":[["$","$L3",null,{}],["$","main",null,{"className":"flex-1 min-w-0 overflow-auto","children":["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":404}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],[]],"forbidden":"$undefined","unauthorized":"$undefined"}]}]]}]]}]}]]}],{"children":[["$","$1","c",{"children":[null,["$","$L4",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L5",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","forbidden":"$undefined","unauthorized":"$undefined"}]]}],{"children":[["$","$1","c",{"children":[["$","$L6",null,{}],[["$","script","script-0",{"src":"/_next/static/chunks/084lff9v4p_vh.js","async":true,"nonce":"$undefined"}]],["$","$L7",null,{"children":["$","$8",null,{"name":"Next.MetadataOutlet","children":"$@9"}]}]]}],{},null,false,null]},null,false,"$@a"]},null,false,null],["$","$1","h",{"children":[null,["$","$Lb",null,{"children":"$Lc"}],["$","div",null,{"hidden":true,"children":["$","$Ld",null,{"children":["$","$8",null,{"name":"Next.Metadata","children":"$Le"}]}]}],["$","meta",null,{"name":"next-size-adjust","content":""}]]}],false]],"m":"$undefined","G":["$f",[["$","link","0",{"rel":"stylesheet","href":"/_next/static/chunks/0ccoe1hsu70ql.css","precedence":"next","crossOrigin":"$undefined","nonce":"$undefined"}]]],"S":true,"h":null,"s":"$undefined","l":"$undefined","p":"$undefined","d":"$undefined","b":"X4zdS6Y6HkLOaElNeHwnq"}
 10:[]
 a:"$W10"
 c:[["$","meta","0",{"charSet":"utf-8"}],["$","meta","1",{"name":"viewport","content":"width=device-width, initial-scale=1"}]]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quadwork",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Unified dashboard for multi-agent coding teams — 4 AI agents, one terminal",
   "bin": {
     "quadwork": "./bin/quadwork.js"

package/server/routes.chatWsSend.test.js

@@ -0,0 +1,161 @@
+// #236 / quadwork#236: sendViaWebSocket ack/body/error regression.
+// Stands up a minimal fake AgentChattr ws server that mirrors app.py's
+// `type:"message"` handler behavior (accept the frame, assign an id +
+// timestamp, broadcast `{type:"message", data: msg}` back to the
+// sender) and verifies:
+//
+//   1. Successful send resolves with {ok:true, message:{id,…}} — the
+//      echoed broadcast frame, not a fake {ok:true}.
+//   2. Attachments survive the round trip.
+//   3. History replay on connect does NOT satisfy the ack (the echo
+//      must come AFTER the send, not before).
+//   4. A premature close without an echo rejects with an error (the
+//      old fire-and-forget path silently resolved).
+//   5. Close code 4003 rejects with err.code === "EAGENTCHATTR_401"
+//      so the /api/chat handler can surface a proper 401.
+//
+// Run with: node server/routes.chatWsSend.test.js
+
+const assert = require("node:assert/strict");
+const http = require("node:http");
+const { WebSocketServer } = require("ws");
+const { sendViaWebSocket } = require("./routes");
+
+function startFakeAc({ historyBeforeAck = [], rejectWithCode = null, dropBeforeAck = false } = {}) {
+  const server = http.createServer();
+  const wss = new WebSocketServer({ noServer: true });
+  server.on("upgrade", (req, socket, head) => {
+    if (rejectWithCode === 4003) {
+      // Accept the upgrade, then immediately close with 4003 the way
+      // AC's /ws handler does on invalid token.
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        ws.close(4003, "forbidden: invalid session token");
+      });
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      // Simulate history replay on connect — these must NOT satisfy
+      // the ack, even if they match (sender,text,channel).
+      let historyMaxId = 0;
+      for (const msg of historyBeforeAck) {
+        ws.send(JSON.stringify({ type: "message", data: msg }));
+        if (typeof msg.id === "number" && msg.id > historyMaxId) historyMaxId = msg.id;
+      }
+      // Mirror AC: emit one `type:"status"` frame after history so the
+      // client knows the replay is done. See agentchattr/app.py
+      // `broadcast_status()` call in the /ws handler (line ~1082).
+      ws.send(JSON.stringify({ type: "status", data: { ready: true } }));
+      let nextId = Math.max(9000, historyMaxId + 1);
+      ws.on("message", (raw) => {
+        const frame = JSON.parse(raw.toString());
+        if (frame.type !== "message") return;
+        if (dropBeforeAck) {
+          ws.close();
+          return;
+        }
+        // Mirror store.add: assign id + timestamp, rebroadcast.
+        const echoed = {
+          id: nextId++,
+          sender: frame.sender,
+          text: frame.text,
+          channel: frame.channel || "general",
+          attachments: frame.attachments || [],
+          reply_to: frame.reply_to ?? null,
+          timestamp: Date.now() / 1000,
+        };
+        ws.send(JSON.stringify({ type: "message", data: echoed }));
+      });
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve({ url: `http://127.0.0.1:${port}`, close: () => new Promise((r) => server.close(() => r())) });
+    });
+  });
+}
+
+(async () => {
+  // 1 + 2) Success path: echo carries server id + attachments preserved.
+  {
+    const ac = await startFakeAc();
+    const result = await sendViaWebSocket(ac.url, "fake-token", {
+      text: "hello from test",
+      sender: "user",
+      channel: "general",
+      attachments: [{ url: "/uploads/x.png", name: "x.png" }],
+    });
+    assert.equal(result.ok, true);
+    assert.ok(result.message, "expected echoed message object");
+    assert.equal(typeof result.message.id, "number");
+    assert.ok(result.message.id >= 9000);
+    assert.equal(result.message.text, "hello from test");
+    assert.equal(result.message.sender, "user");
+    assert.equal(result.message.attachments.length, 1);
+    assert.equal(result.message.attachments[0].name, "x.png");
+    await ac.close();
+  }
+
+  // 3) Stale history replay must NOT satisfy the ack — even when the
+  //    history contains a message that is IDENTICAL (sender, text,
+  //    channel, reply_to) and has a recent timestamp (e.g. a retry of
+  //    the same message sent <1s ago). Prior heuristic matcher was
+  //    vulnerable to this; the fix uses the (1) status-frame history
+  //    boundary and (2) strictly-greater-id correlation baseline so
+  //    the historical echo is definitionally rejected. Reviewer1
+  //    flagged this race on PR #382 round 1.
+  {
+    const stale = {
+      id: 42, sender: "user", text: "same words",
+      channel: "general", attachments: [], reply_to: null,
+      timestamp: Date.now() / 1000, // RIGHT NOW — old heuristic would accept this
+    };
+    const ac = await startFakeAc({ historyBeforeAck: [stale] });
+    const result = await sendViaWebSocket(ac.url, "fake-token", {
+      text: "same words",
+      sender: "user",
+      channel: "general",
+      attachments: [],
+    });
+    assert.ok(result.message.id > 42, `expected live echo id > 42, got ${result.message.id}`);
+    await ac.close();
+  }
+
+  // 4) Premature close without ack rejects.
+  {
+    const ac = await startFakeAc({ dropBeforeAck: true });
+    let threw = false;
+    try {
+      await sendViaWebSocket(ac.url, "fake-token", {
+        text: "will drop", sender: "user", channel: "general", attachments: [],
+      });
+    } catch (err) {
+      threw = true;
+      assert.match(err.message, /closed before ack|websocket/);
+      assert.notEqual(err.code, "EAGENTCHATTR_401");
+    }
+    assert.equal(threw, true, "expected sendViaWebSocket to reject on premature close");
+    await ac.close();
+  }
+
+  // 5) 4003 (bad token) rejects with EAGENTCHATTR_401.
+  {
+    const ac = await startFakeAc({ rejectWithCode: 4003 });
+    let threw = false;
+    try {
+      await sendViaWebSocket(ac.url, "bad-token", {
+        text: "denied", sender: "user", channel: "general", attachments: [],
+      });
+    } catch (err) {
+      threw = true;
+      assert.equal(err.code, "EAGENTCHATTR_401");
+    }
+    assert.equal(threw, true, "expected sendViaWebSocket to reject with EAGENTCHATTR_401");
+    await ac.close();
+  }
+
+  console.log("routes.chatWsSend.test.js: all assertions passed (5 cases)");
+})().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/server/routes.js

@@ -148,11 +148,41 @@ router.get("/api/chat", async (req, res) => {
 const { WebSocket: NodeWebSocket } = require("ws");
 const { syncChattrToken } = require("./config");
 
+// #236: wait for AgentChattr to echo our message back over the same ws
+// connection before resolving, instead of fire-and-forgetting. AC's
+// /ws handler does this on every connect:
+//   1. Replays history as N `{type:"message", data: msg}` frames.
+//   2. Sends one `{type:"status", data: …}` frame (broadcast_status).
+//   3. Enters the receive loop and accepts our outgoing frame.
+// After our `type:"message"` is processed, AC calls `store.add()`
+// which broadcasts the stored record back to all clients (including
+// us) as another `{type:"message", data: msg}`.
+//
+// To get a race-free ack we therefore:
+//   A. Wait for the first `type:"status"` frame to confirm the
+//      history replay is done — any `type:"message"` frame seen
+//      BEFORE that is historical and must be ignored.
+//   B. Only then send our message and record the highest message
+//      id observed so far as a correlation baseline.
+//   C. Accept the first post-send `type:"message"` whose payload
+//      matches (sender, text, channel, reply_to) AND whose id is
+//      strictly greater than the baseline (AC ids are monotonically
+//      increasing from store.add). This eliminates the risk a
+//      reviewer flagged on #382 round 1: a historical identical
+//      message from <1.5s ago could have satisfied the old
+//      heuristic matcher.
+// On timeout / early close / 4003, we surface a proper error so the
+// /api/chat handler can return a 5xx (or 401) instead of a silent
+// {ok:true}.
 function sendViaWebSocket(baseUrl, sessionToken, message) {
   return new Promise((resolve, reject) => {
     const wsUrl = `${baseUrl.replace(/^http/, "ws")}/ws?token=${encodeURIComponent(sessionToken || "")}`;
     const ws = new NodeWebSocket(wsUrl);
     let settled = false;
+    let historyFlushed = false;
+    let sent = false;
+    let maxIdAtSend = -Infinity;
+    let maxHistoryId = -Infinity;
     const finish = (err, value) => {
       if (settled) return;
       settled = true;
@@ -160,14 +190,56 @@ function sendViaWebSocket(baseUrl, sessionToken, message) {
       if (err) reject(err); else resolve(value);
     };
     const giveUp = setTimeout(() => finish(new Error("websocket send timeout")), 4000);
-    ws.on("open", () => {
+    const doSend = () => {
+      if (sent || settled) return;
       try {
+        maxIdAtSend = maxHistoryId;
         ws.send(JSON.stringify({ type: "message", ...message }));
-        // Server acks via broadcast, but the dashboard's POST /api/chat
-        // contract only needs to know the message was accepted. Wait
-        // ~250ms for the server to enqueue + close cleanly.
-        setTimeout(() => { clearTimeout(giveUp); finish(null, { ok: true }); }, 250);
+        sent = true;
       } catch (err) { clearTimeout(giveUp); finish(err); }
+    };
+    ws.on("open", () => {
+      // Do NOT send yet. Wait for the status frame that marks the
+      // end of history replay so we have a clean correlation
+      // baseline. A safety timer covers the (unlikely) case of an
+      // AC build that doesn't emit status on connect — after 750ms
+      // we fall back to sending anyway, using whatever max id we
+      // collected from history so far as the baseline.
+      setTimeout(() => {
+        if (!historyFlushed) {
+          historyFlushed = true;
+          doSend();
+        }
+      }, 750);
+    });
+    ws.on("message", (raw) => {
+      if (settled) return;
+      let frame;
+      try { frame = JSON.parse(raw.toString()); } catch { return; }
+      if (!frame || !frame.type) return;
+      if (frame.type === "status" && !historyFlushed) {
+        historyFlushed = true;
+        doSend();
+        return;
+      }
+      if (frame.type !== "message" || !frame.data) return;
+      const d = frame.data;
+      // Track the highest message id we have observed, whether from
+      // history replay or from other live broadcasts. Used as the
+      // baseline for the post-send correlation check.
+      if (typeof d.id === "number" && d.id > maxHistoryId) {
+        maxHistoryId = d.id;
+      }
+      if (!sent) return; // anything before our send is history
+      if (typeof d.id !== "number" || d.id <= maxIdAtSend) return;
+      if (d.sender !== message.sender) return;
+      if (d.text !== message.text) return;
+      if ((d.channel || "general") !== (message.channel || "general")) return;
+      const wantReply = message.reply_to ?? null;
+      const gotReply = d.reply_to ?? null;
+      if (wantReply !== gotReply) return;
+      clearTimeout(giveUp);
+      finish(null, { ok: true, message: d });
     });
     ws.on("error", (err) => { clearTimeout(giveUp); finish(err); });
     ws.on("close", (code, reason) => {
@@ -179,6 +251,15 @@ function sendViaWebSocket(baseUrl, sessionToken, message) {
         const e = new Error(msg);
         e.code = "EAGENTCHATTR_401";
         finish(e);
+        return;
+      }
+      // Any other premature close after we sent but before we saw
+      // the echo is an error — the old code path would have claimed
+      // success, silently swallowing a server-side reject.
+      if (!settled) {
+        clearTimeout(giveUp);
+        const r = (reason && reason.toString()) || "";
+        finish(new Error(`websocket closed before ack (code=${code}${r ? ", reason=" + r : ""})`));
       }
     });
   });
@@ -861,8 +942,12 @@ router.post("/api/chat", async (req, res) => {
   const attemptSend = () => sendViaWebSocket(base, sessionToken, message);
 
   try {
-    await attemptSend();
-    return res.json({ ok: true });
+    // #236: sendViaWebSocket now waits for AC's broadcast echo and
+    // returns `{ok, message}` where `message` is the stored record
+    // (with server-assigned id/timestamp). Pass it through so
+    // callers regain parity with the old /api/send response body.
+    const result = await attemptSend();
+    return res.json({ ok: true, message: result.message });
   } catch (err) {
     // If the cached session_token is stale (AgentChattr regenerates
     // one on every restart) the ws closes with code 4003 — re-sync
@@ -876,8 +961,8 @@ router.post("/api/chat", async (req, res) => {
       const { token: refreshed } = getChattrConfig(projectId);
       if (refreshed && refreshed !== sessionToken) {
         try {
-          await sendViaWebSocket(base, refreshed, message);
-          return res.json({ ok: true, resynced: true });
+          const retry = await sendViaWebSocket(base, refreshed, message);
+          return res.json({ ok: true, resynced: true, message: retry.message });
         } catch (retryErr) {
           console.warn(`[chat] retry after token resync failed: ${retryErr.message}`);
           return res.status(401).json({ error: "AgentChattr auth failed (token resync did not help)", detail: retryErr.message });
@@ -2300,6 +2385,63 @@ function telegramConfigToml(projectId) {
   return path.join(CONFIG_DIR, `telegram-${projectId}.toml`);
 }
 
+// #383: path to a project's AgentChattr config.toml. The install
+// handler patches this file to declare the `telegram-bridge` agent
+// so AC's registry accepts the bridge's register call.
+function projectAgentchattrConfigPath(projectId) {
+  return path.join(CONFIG_DIR, projectId, "agentchattr", "config.toml");
+}
+
+// #383 Bug 1: prefer the per-project agentchattr_url. Every project
+// after the first uses a distinct port (8301, 8302, ...), so reading
+// the global default silently routed bridge traffic to the wrong AC
+// instance.
+function resolveProjectAgentchattrUrl(cfg, project) {
+  return (
+    (project && project.agentchattr_url) ||
+    (cfg && cfg.agentchattr_url) ||
+    "http://127.0.0.1:8300"
+  );
+}
+
+// #383 Bug 2: the upstream bridge only reads `agentchattr_url` from
+// inside `[telegram]`. A separate `[agentchattr]` section is silently
+// ignored and the bridge falls back to its hardcoded :8300 default.
+function buildTelegramBridgeToml(tg) {
+  return (
+    `[telegram]\n` +
+    `bot_token = "${tg.bot_token}"\n` +
+    `chat_id = "${tg.chat_id}"\n` +
+    `agentchattr_url = "${tg.agentchattr_url}"\n`
+  );
+}
+
+// #383 Bug 3: AC's registry rejects any base name not pre-declared
+// in config.toml with `400 unknown base`. The bridge registers as
+// `telegram-bridge`, so every per-project AC config must declare it.
+// Idempotent: only appends if the section is not already present.
+function patchAgentchattrConfigForTelegramBridge(tomlText) {
+  if (/^\[agents\.telegram-bridge\]\s*$/m.test(tomlText)) {
+    return { text: tomlText, changed: false };
+  }
+  const sep = tomlText.length === 0 || tomlText.endsWith("\n") ? "" : "\n";
+  const block = `\n[agents.telegram-bridge]\nlabel = "Telegram Bridge"\n`;
+  return { text: tomlText + sep + block, changed: true };
+}
+
+// #383 Bug 4: the upstream bridge treats env vars as higher
+// precedence than TOML values. If the parent shell exported
+// TELEGRAM_BOT_TOKEN for a different bot, the bridge silently ran
+// as the wrong identity. Scrub those keys from the child's env so
+// the TOML is the single source of truth.
+function buildTelegramBridgeSpawnEnv(parentEnv) {
+  const env = { ...parentEnv };
+  delete env.TELEGRAM_BOT_TOKEN;
+  delete env.TELEGRAM_CHAT_ID;
+  delete env.AGENTCHATTR_URL;
+  return env;
+}
+
 // #353: per-project log file for the bridge subprocess. The start
 // handler redirects stdout + stderr here so crashes (ImportError,
 // config parse, auth failure) are recoverable instead of
@@ -2339,7 +2481,12 @@ function readLastLines(filePath, n) {
 // otherwise. Keep the import list small and close to what the
 // bridge actually needs; add modules here if the bridge gains new
 // hard deps.
-function checkTelegramBridgePythonDeps() {
+// #380: `pythonPath` defaults to bare `python3` for backward-compat,
+// but the production call sites (install, start) MUST pass the
+// dedicated bridge venv's interpreter (`<BRIDGE_DIR>/.venv/bin/python3`)
+// so the import check runs against the same interpreter the spawn will
+// use. See #379 research ticket for root cause.
+function checkTelegramBridgePythonDeps(pythonPath = "python3") {
   try {
     // Only check the third-party module the bridge actually needs
     // at import time — `requests`. Toml parsing differs between
@@ -2347,7 +2494,7 @@ function checkTelegramBridgePythonDeps() {
     // genuine toml import failure will now be captured in the
     // bridge log file on spawn, so this pre-flight stays narrow
     // and avoids false negatives on older Python installs.
-    execFileSync("python3", ["-c", "import requests"], {
+    execFileSync(pythonPath, ["-c", "import requests"], {
       encoding: "utf-8",
       timeout: 10000,
       stdio: ["ignore", "pipe", "pipe"],
@@ -2412,7 +2559,8 @@ function getProjectTelegram(projectId) {
     return {
       bot_token: resolveToken(project.telegram.bot_token || ""),
       chat_id: project.telegram.chat_id || "",
-      agentchattr_url: cfg.agentchattr_url || "http://127.0.0.1:8300",
+      // #383 Bug 1: prefer per-project URL over the global default.
+      agentchattr_url: resolveProjectAgentchattrUrl(cfg, project),
     };
   } catch {
     return null;
@@ -2503,39 +2651,76 @@ router.post("/api/telegram", async (req, res) => {
       }
     }
     case "install": {
-      // #353: pip3 can exit 0 on some systems (PEP 668 externally-
-      // managed environments, non-writable site-packages) even when
-      // the subsequent import still fails. After the pip step, run
-      // a post-install import check and surface both the pip output
-      // and the import error together if the check fails — that's
-      // the signal the operator needs to know whether to pick a
-      // virtualenv, use --user, or --break-system-packages.
+      // #380: create a dedicated bridge venv at
+      // `<BRIDGE_DIR>/.venv` and install requirements into it using
+      // that venv's pip. All bridge subprocesses then spawn with
+      // `<BRIDGE_DIR>/.venv/bin/python3` by absolute path. See #379
+      // research ticket for the root cause — bare `python3` / `pip3`
+      // resolve to Homebrew Python on modern macOS where `requests`
+      // is not available, producing a ModuleNotFoundError on Start.
+      // Idempotent: existing installs missing a `.venv` get the venv
+      // created on top of the existing clone without re-cloning.
+      const venvDir = path.join(BRIDGE_DIR, ".venv");
+      const venvPython = path.join(venvDir, "bin", "python3");
+      const venvPip = path.join(venvDir, "bin", "pip");
       let pipOutput = "";
       try {
         if (!fs.existsSync(BRIDGE_DIR)) {
           execFileSync("gh", ["repo", "clone", "realproject7/agentchattr-telegram", BRIDGE_DIR], { encoding: "utf-8", timeout: 30000 });
         }
+        // #380: create the dedicated venv if missing. `python3 -m venv`
+        // builds a fresh isolated environment that bypasses PEP 668
+        // externally-managed markers, so this works even on Homebrew
+        // Python where bare `pip3 install` would be blocked.
+        if (!fs.existsSync(venvPython)) {
+          execFileSync("python3", ["-m", "venv", venvDir], { encoding: "utf-8", timeout: 60000 });
+        }
         pipOutput = execFileSync(
-          "pip3",
+          venvPip,
           ["install", "-r", path.join(BRIDGE_DIR, "requirements.txt")],
-          { encoding: "utf-8", timeout: 60000 },
+          { encoding: "utf-8", timeout: 120000 },
         );
       } catch (err) {
-        return res.json({ ok: false, error: err.message || "Install failed" });
+        const stderr = (err && err.stderr && err.stderr.toString && err.stderr.toString()) || "";
+        return res.json({ ok: false, error: (stderr.trim() || err.message || "Install failed") });
       }
-      const depCheck = checkTelegramBridgePythonDeps();
+      const depCheck = checkTelegramBridgePythonDeps(venvPython);
       if (!depCheck.ok) {
         return res.json({
           ok: false,
           error:
-            "pip3 reported success but the bridge's Python deps still fail to import. " +
-            "This usually means pip installed into a location python3 cannot see " +
-            "(externally-managed environment / PEP 668 / mismatched interpreter).\n\n" +
+            "pip reported success but the bridge venv's Python deps still fail to import. " +
+            "This is unexpected for a freshly-created venv — check disk space and permissions " +
+            `on ${venvDir}.\n\n` +
             `Import error: ${depCheck.error}\n\n` +
             `pip output tail:\n${pipOutput.split("\n").slice(-10).join("\n")}`,
         });
       }
-      return res.json({ ok: true });
+      // #383 Bug 3: ensure every known project's AC config declares
+      // the `telegram-bridge` agent. Without this, AC's registry
+      // rejects the bridge's register call with `400 unknown base`
+      // and the bridge enters an infinite re-register loop.
+      // Idempotent — append-only, skips configs that already have
+      // the section. Does NOT restart AC servers; the operator
+      // must click SERVER → Restart to load the new agent slug.
+      const patched = [];
+      try {
+        const cfgAll = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+        for (const proj of cfgAll.projects || []) {
+          if (!proj || !proj.id) continue;
+          const acPath = projectAgentchattrConfigPath(proj.id);
+          if (!fs.existsSync(acPath)) continue;
+          try {
+            const before = fs.readFileSync(acPath, "utf-8");
+            const { text, changed } = patchAgentchattrConfigForTelegramBridge(before);
+            if (changed) {
+              fs.writeFileSync(acPath, text);
+              patched.push(proj.id);
+            }
+          } catch {}
+        }
+      } catch {}
+      return res.json({ ok: true, patched_projects: patched });
     }
     case "start": {
       const projectId = body.project_id;
@@ -2543,17 +2728,31 @@ router.post("/api/telegram", async (req, res) => {
       if (isTelegramRunning(projectId)) return res.json({ ok: true, running: true, message: "Already running" });
       const bridgeScript = path.join(BRIDGE_DIR, "telegram_bridge.py");
       if (!fs.existsSync(bridgeScript)) return res.json({ ok: false, error: "Bridge not installed. Click Install Bridge first." });
+      // #380: resolve the dedicated venv's python3 by absolute path.
+      // Do NOT activate the venv or set VIRTUAL_ENV in the parent —
+      // calling the venv's python3 directly is sufficient because
+      // Python's sys.executable bootstrap resolves the venv
+      // automatically. See #379 research ticket.
+      const venvPython = path.join(BRIDGE_DIR, ".venv", "bin", "python3");
+      if (!fs.existsSync(venvPython)) {
+        return res.json({
+          ok: false,
+          error: "Bridge venv missing. Click \"Install Bridge\" to create it.",
+        });
+      }
       const tg = getProjectTelegram(projectId);
       if (!tg || !tg.bot_token || !tg.chat_id) return res.json({ ok: false, error: "Save bot_token and chat_id in project settings first." });
       const tomlPath = telegramConfigToml(projectId);
-      const tomlContent = `[telegram]\nbot_token = "${tg.bot_token}"\nchat_id = "${tg.chat_id}"\n\n[agentchattr]\nurl = "${tg.agentchattr_url}"\n`;
+      // #383 Bug 2: write agentchattr_url inside [telegram]; the
+      // bridge's load_config only reads from that section.
+      const tomlContent = buildTelegramBridgeToml(tg);
       fs.writeFileSync(tomlPath, tomlContent, { mode: 0o600 });
       fs.chmodSync(tomlPath, 0o600);
       // #353: pre-flight import check so a fresh install with no
       // `requests` module produces a readable error instead of the
       // Start → Running → Stopped flicker that the v1 code path
       // produced with `stdio: "ignore"`.
-      const depCheck = checkTelegramBridgePythonDeps();
+      const depCheck = checkTelegramBridgePythonDeps(venvPython);
       if (!depCheck.ok) {
         // #372: persist the pre-flight failure to the bridge log
         // file so the GET /api/telegram `last_error` tail picks it
@@ -2562,8 +2761,8 @@ router.post("/api/telegram", async (req, res) => {
         // local error state, producing the "silent fail" symptom
         // (pill flips back to Stopped with no trace of why).
         const msg =
-          "Bridge Python dependencies not installed. Click \"Install Bridge\" to install them, " +
-          "or run: pip3 install -r " + path.join(BRIDGE_DIR, "requirements.txt") + "\n\n" +
+          "Bridge Python dependencies not installed in the dedicated venv. " +
+          "Click \"Install Bridge\" to (re)create the venv and install them.\n\n" +
           `Import error: ${depCheck.error}`;
         try {
           fs.writeFileSync(
@@ -2595,9 +2794,15 @@ router.post("/api/telegram", async (req, res) => {
       }
       let child;
       try {
-        child = spawn("python3", [bridgeScript, "--config", tomlPath], {
+        // #383 Bug 4: scrub TELEGRAM_*/AGENTCHATTR_URL from the child
+        // env so an operator shell that exports a different bot's
+        // token (common on machines running AC2) can't silently
+        // override the TOML. Makes the TOML the single source of
+        // truth for the bridge's identity.
+        child = spawn(venvPython, [bridgeScript, "--config", tomlPath], {
           detached: true,
           stdio: ["ignore", outFd, errFd],
+          env: buildTelegramBridgeSpawnEnv(process.env),
         });
         child.unref();
         if (child.pid) fs.writeFileSync(telegramPidFile(projectId), String(child.pid));
@@ -2780,3 +2985,16 @@ module.exports.buildNoPrRow = buildNoPrRow;
 module.exports.summarizeItems = summarizeItems;
 // #353: expose readLastLines for the telegram-bridge test.
 module.exports.readLastLines = readLastLines;
+// #380: expose checkTelegramBridgePythonDeps so the bridge test can
+// exercise the venv-path interpreter argument round trip.
+module.exports.checkTelegramBridgePythonDeps = checkTelegramBridgePythonDeps;
+// #383: pure helpers exposed for unit tests in
+// routes.telegramBridge.test.js. No production callers outside
+// this file.
+module.exports.resolveProjectAgentchattrUrl = resolveProjectAgentchattrUrl;
+module.exports.buildTelegramBridgeToml = buildTelegramBridgeToml;
+module.exports.patchAgentchattrConfigForTelegramBridge = patchAgentchattrConfigForTelegramBridge;
+module.exports.buildTelegramBridgeSpawnEnv = buildTelegramBridgeSpawnEnv;
+// #236: expose sendViaWebSocket so the chat-ws-send regression test
+// can verify the ack/body/error paths against a fake AC ws server.
+module.exports.sendViaWebSocket = sendViaWebSocket;