viber-channel 0.6.0 → 0.7.0

package/lib/bridge_spawn.ts

@@ -69,12 +69,29 @@ export function createBridgeSpawn(opts: BridgeSpawnOptions = {}): SpawnFn {
 		// Force a fresh per-agent instance (see file header).
 		delete env.VIBER_INSTANCE_TOKEN;
 		delete env.VIBER_INSTANCE_ID;
+		// #309 step-17: NEVER inherit the identity flag/role from the parent
+		// supervisor — a leaked VIBER_AGENT_NAME_EXPLICIT would make an auto id
+		// (agent-1) claim itself as an explicit name. Strip them here and re-derive
+		// authoritatively below (codex-309-review blocking #1).
+		delete env.VIBER_AGENT_NAME_EXPLICIT;
+		delete env.VIBER_AGENT_ROLE;
 		env.VIBER_AGENT_TIER = spec.tier;
+		if (spec.env) Object.assign(env, spec.env);
+		// Identity is set LAST, AFTER spec.env, so neither the inherited env nor a
+		// config `env` block can spoof the explicit-name flag or the role — the
+		// spec fields are the only source of truth (codex-309-review blocking #1).
 		// Surface the agent id as the bridge's Viber instance label so distinct
 		// agents are identifiable in the control plane (participants strip / recipient
 		// picker) instead of all showing the same generic "Codex bridge" label.
 		env.VIBER_CODEX_BRIDGE_LABEL = spec.agentId;
-		if (spec.env) Object.assign(env, spec.env);
+		// Only an EXPLICIT name is claimed as the agent's name (the label is always
+		// set, even for auto ids); the separate flag is the safe signal. `else delete`
+		// closes the spoof path even if spec.env smuggled the flag in.
+		if (spec.nameExplicit) env.VIBER_AGENT_NAME_EXPLICIT = "1";
+		else delete env.VIBER_AGENT_NAME_EXPLICIT;
+		// The role is untrusted text the bridge sanitizes before injecting it.
+		if (spec.role !== undefined) env.VIBER_AGENT_ROLE = spec.role;
+		else delete env.VIBER_AGENT_ROLE;
 
 		const child = spawnImpl(command, [...baseArgs, ...spec.args], {
 			env,

package/lib/bridge_tool_host.ts

@@ -0,0 +1,191 @@
+/**
+ * bridge_tool_host.ts — in-process MCP tool host for the Codex bridge (#317 iii).
+ *
+ * The bridge hosts a streamable-HTTP MCP server on loopback; `codex app-server`
+ * connects to it BY URL (mcp_servers.<name>.url). Because the server runs INSIDE
+ * the bridge process (no child spawn), the tools read the bridge's LIVE context
+ * (rotating token, current-turn conversation) by reference — never a snapshot.
+ * This is the same `agent_tools.ts` the Claude MCP uses: one source, no double
+ * maintenance.
+ *
+ * Security (viber-dev-315): the server binds to 127.0.0.1 only and requires an
+ * ephemeral bearer token, so no other local process can post into the channel
+ * through it.
+ *
+ * Anti-double-post (#317 #D): the bridge auto-posts a turn's final text only when
+ * NO outbound tool succeeded that turn. The host reports a SUCCESSFUL
+ * send_message / message_agent via `onOutboundSuccess` so the caller can suppress
+ * the auto-post. A FAILED outbound does NOT report success → the auto-post
+ * fallback still fires (no silent void). list_agents is read-only and never
+ * reports outbound.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import {
+  listAgents,
+  messageAgent,
+  sendMessage,
+  type AgentToolsContext,
+  type AgentToolResult,
+} from "./agent_tools.js";
+
+/** The three channel tools, named so codex (and the elicitation whitelist) match. */
+export const BRIDGE_TOOL_NAMES = ["send_message", "list_agents", "message_agent"] as const;
+export type BridgeToolName = (typeof BRIDGE_TOOL_NAMES)[number];
+
+/** Outbound tools whose SUCCESS suppresses the bridge's final auto-post. */
+const OUTBOUND_TOOLS: ReadonlySet<string> = new Set(["send_message", "message_agent"]);
+
+const TOOL_DEFS = [
+  {
+    name: "send_message",
+    description:
+      "Post your reply into the current Viber conversation. `text` is the conversational reply — " +
+      "read aloud AND shown as Markdown, so keep it short and natural but use light Markdown (short " +
+      "lists, numbered steps, **bold**) for readability; put actions/questions here, visibly. " +
+      "`artifact` is optional HEAVY/LONG content (big code, large tables, long analyses, json, " +
+      "sanitized html) shown in a side viewer; when used, keep `text` a brief summary pointing to it. " +
+      "Calling this IS your reply for the turn.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Spoken/conversational reply. Plain sentences." },
+        artifact: {
+          type: "object",
+          properties: {
+            content: { type: "string" },
+            format: { type: "string", enum: ["markdown", "code", "json", "html"] },
+          },
+          required: ["content"],
+          additionalProperties: false,
+        },
+      },
+      required: ["text"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_agents",
+    description:
+      "List the OTHER agents (instances) in this project you can DM. Returns each agent's id, " +
+      "label, runtime kind, and whether it is online. Use it to find an id before message_agent.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "message_agent",
+    description:
+      "Send a direct message to another agent in this project. Pass the target agent's instance id " +
+      "(from list_agents) and the text. Opens or reuses a private 1:1 DM and posts your message; " +
+      "the agent's reply arrives back on this channel. Fails if the target agent is offline.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        instance_id: { type: "string", description: "Target agent's instance id (from list_agents)." },
+        text: { type: "string", description: "Message to send to the target agent." },
+      },
+      required: ["instance_id", "text"],
+      additionalProperties: false,
+    },
+  },
+] as const;
+
+export interface BridgeToolHost {
+  /** URL codex connects to: http://127.0.0.1:<port>/mcp */
+  url: string;
+  /** Ephemeral bearer token value the host requires (pass to codex via env). */
+  bearerToken: string;
+  /** Stop the HTTP server. */
+  stop(): void;
+}
+
+export interface BridgeToolHostOptions {
+  /** Live bridge context (per-turn conversation, rotating token, DM streaming). */
+  ctx: AgentToolsContext;
+  /** Called with the tool name when an OUTBOUND tool (send_message/message_agent) SUCCEEDS. */
+  onOutboundSuccess: (tool: BridgeToolName) => void;
+  /** stderr-style logger. */
+  log: (line: string) => void;
+  /** Generate the ephemeral bearer token (injected for testability). */
+  makeToken: () => string;
+}
+
+/**
+ * Dispatch a single tool call to the shared lib and, on a successful outbound,
+ * report it. Exported for unit testing without spinning up the HTTP server.
+ */
+export async function dispatchBridgeTool(
+  name: string,
+  args: Record<string, unknown>,
+  opts: Pick<BridgeToolHostOptions, "ctx" | "onOutboundSuccess">,
+): Promise<AgentToolResult> {
+  let result: AgentToolResult;
+  if (name === "list_agents") {
+    result = await listAgents(opts.ctx);
+  } else if (name === "message_agent") {
+    result = await messageAgent(opts.ctx, args);
+  } else if (name === "send_message") {
+    result = await sendMessage(opts.ctx, args);
+  } else {
+    return { isError: true, content: [{ type: "text", text: `Unknown tool: ${name}` }] };
+  }
+  // Only a SUCCESSFUL outbound suppresses the auto-post (#317 #D: success, not attempt).
+  if (OUTBOUND_TOOLS.has(name) && result.isError !== true) {
+    opts.onOutboundSuccess(name as BridgeToolName);
+  }
+  return result;
+}
+
+function buildServer(opts: BridgeToolHostOptions): Server {
+  const mcp = new Server({ name: "viber-channel-tools", version: "0.1.0" }, { capabilities: { tools: {} } });
+  mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFS as unknown as object[] }));
+  mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const args = (request.params.arguments ?? {}) as Record<string, unknown>;
+    try {
+      return await dispatchBridgeTool(request.params.name, args, opts);
+    } catch (err) {
+      // The shared lib rethrows ConversationTokenExpiredError (host-specific
+      // teardown). In the bridge we surface it as a tool error rather than
+      // killing the turn mid-flight: the stream's own next op hits 401 and the
+      // refresh/abort path handles renewal. NOT reported as outbound success.
+      opts.log(`[bridge-tool-host] tool ${request.params.name} threw: ${String(err)}\n`);
+      return { isError: true, content: [{ type: "text", text: `Tool error: ${String(err)}` }] };
+    }
+  });
+  return mcp;
+}
+
+/**
+ * Start the loopback MCP HTTP host. Returns the URL + bearer for codex config.
+ * Stateless transport → a fresh Server+transport per request (SDK requirement).
+ */
+export function startBridgeToolHost(opts: BridgeToolHostOptions): BridgeToolHost {
+  const bearerToken = opts.makeToken();
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    async fetch(req) {
+      const auth = req.headers.get("authorization") ?? "";
+      if (auth !== `Bearer ${bearerToken}`) {
+        return new Response(JSON.stringify({ error: "unauthorized" }), {
+          status: 401,
+          headers: { "content-type": "application/json" },
+        });
+      }
+      const mcp = buildServer(opts);
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+      });
+      await mcp.connect(transport);
+      return transport.handleRequest(req);
+    },
+  });
+  const url = `http://127.0.0.1:${server.port}/mcp`;
+  opts.log(`[bridge-tool-host] MCP tools on ${url} (loopback, bearer-guarded)\n`);
+  return {
+    url,
+    bearerToken,
+    stop: () => server.stop(true),
+  };
+}

package/lib/control_stream.ts

@@ -31,6 +31,39 @@ export function buildControlStreamUrl(baseUrl: string, instanceId: string): stri
   return `${baseUrl}/api/instances/${instanceId}/events`;
 }
 
+/**
+ * POST /api/instances/:id/heartbeat — instance control-stream liveness (#311).
+ *
+ * The agent beats on a fixed interval so the server's #311 sweeper never purges a
+ * live-but-idle agent: a server→client SSE keepalive can't prove this process is
+ * still alive behind the Cloudflare tunnel, but this beat can. Best-effort —
+ * `true` on 2xx, `false` on any non-2xx / network error. Bounded by a per-POST
+ * timeout so a hung tunnel socket can't stack beats (mirrors #298).
+ */
+export async function sendInstanceHeartbeat(
+  baseUrl: string,
+  instanceId: string,
+  instanceToken: string,
+  timeoutMs = 20_000,
+  fetchImpl: typeof fetch = fetch,
+): Promise<boolean> {
+  try {
+    const resp = await fetchImpl(`${baseUrl}/api/instances/${instanceId}/heartbeat`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${instanceToken}`,
+        "Content-Type": "application/json",
+        ...cfAccessHeaders(),
+      },
+      body: "{}",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
 export interface ControlStreamOptions {
   baseUrl: string;
   instanceId: string;
@@ -204,6 +237,13 @@ export interface PersistentControlStreamHandlers {
    * The agent should shut down. NOT called on transient drops (those reconnect).
    */
   onStop?: (reason: "stopped" | "unauthorized") => void;
+  /**
+   * Called on a `beat_now` event (#311): the server is actively probing this
+   * agent's liveness — respond with an IMMEDIATE instance heartbeat so a live
+   * agent is confirmed within seconds (and a dead one, which never gets here, is
+   * force-offlined at the probe deadline).
+   */
+  onBeatNow?: () => void;
   log?: (msg: string) => void;
   /** Backoff before reconnecting after a drop / clean end. Default 2000ms. */
   reconnectDelayMs?: number;
@@ -270,6 +310,10 @@ export function runPersistentControlStream(
               handlers.onStop?.("stopped");
               return;
             }
+            if (ev.event === "beat_now") {
+              handlers.onBeatNow?.();
+              continue;
+            }
             if (ev.event !== "join") continue; // connected / ping / unknown
             const minted = parseJoinPayload(ev.data, log);
             if (!minted) continue;

package/lib/dm_stream.ts

@@ -0,0 +1,287 @@
+/**
+ * dm_stream — consume an agent↔agent DM conversation's SSE stream (#288 step-04).
+ *
+ * When the control stream pushes a `join` (a peer opened a DM with us, step-02),
+ * the channel runs ONE of these per DM, IN PARALLEL with the main conversation
+ * SSE — coexistence, not takeover (the reviewed step-04 decision): the main
+ * conversation keeps working while DMs are surfaced alongside it.
+ *
+ * This is intentionally narrow: it only forwards `message` events to `onMessage`
+ * (the caller maps them to a Claude notification with provenance). `stop` ends
+ * the stream; transient drops reconnect with backoff; a 401 ends it (the DM
+ * token expired — the peer can re-open the DM, which re-pushes a fresh join).
+ *
+ * Side-effect-free and runtime-agnostic so it can be unit-tested with a mock
+ * fetch — mirrors the shape of control_stream.ts.
+ */
+import { cfAccessHeaders } from "./cfAccess.js";
+import { buildSseUrl } from "./urls.js";
+import { ConversationTokenExpiredError, fetchMessages } from "./messages.js";
+
+/** A conversation message as it arrives on the SSE `message` event. */
+export interface DmMessage {
+  content: string;
+  id?: string;
+  source?: string;
+  sender_instance_id?: string | null;
+  artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+}
+
+/** Signature of the catch-up fetch (mirrors messages.ts `fetchMessages`). */
+export type FetchMessagesFn = (
+  baseUrl: string,
+  conversationId: string,
+  conversationToken: string,
+) => Promise<Array<Record<string, unknown>>>;
+
+export interface DmStreamOptions {
+  wsUrl: string;
+  conversationId: string;
+  conversationToken: string;
+  onMessage: (msg: DmMessage) => void | Promise<void>;
+  log?: (msg: string) => void;
+  signal?: AbortSignal;
+  /** Backoff before reconnecting after a transient drop. Default 2000ms. */
+  reconnectDelayMs?: number;
+  /**
+   * Cap on CONSECUTIVE connection errors before giving up (#291 step-04). A
+   * clean end (normal SSE recycle) resets the counter, so a healthy stream that
+   * recycles forever never trips it; only a persistent failure (5xx/network)
+   * does. When the cap is hit the stream stops — the peer re-opening the DM
+   * re-pushes a fresh join, so it is not a permanent dead end. Default 8.
+   */
+  maxConsecutiveErrors?: number;
+  /** Injectable for tests; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /**
+   * Injectable catch-up fetch; defaults to messages.ts `fetchMessages`. On each
+   * (re)connect the DM SSE has NO replay, so we re-read the message list and
+   * forward anything published while we were disconnected (#291 step-03).
+   */
+  fetchMessagesImpl?: FetchMessagesFn;
+}
+
+/** Resolve after `ms`, or early when `signal` aborts. */
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Forward one message to `onMessage` exactly once. `handledIds` makes this
+ * idempotent across the catch-up fetch AND the live SSE (a message can arrive
+ * by both paths around a reconnect) — dedup keys on the message id, coerced to
+ * a string so a numeric API id and a string SSE id match (#291 review, Codex).
+ *
+ * Unlike the codex bridge, dm_stream does NOT prime/seed history: a DM is
+ * freshly opened by the peer, so the message that TRIGGERED the join must be
+ * delivered, not swallowed (#291 prime-on-join). Own messages are filtered
+ * downstream in the onMessage handler (self-echo), so forwarding all unseen
+ * messages here is safe.
+ */
+async function forwardMessage(
+  opts: DmStreamOptions,
+  handledIds: Set<string>,
+  msg: DmMessage,
+): Promise<void> {
+  const idStr =
+    msg.id !== undefined && msg.id !== null && String(msg.id).length > 0
+      ? String(msg.id)
+      : undefined;
+  if (idStr && handledIds.has(idStr)) return; // already forwarded (live or catch-up)
+  // Content guard BEFORE consuming the id: a content-less payload must not burn
+  // its id in handledIds, or a later (correctly-populated) catch-up of the same
+  // id would be suppressed forever (review: Opus #4).
+  if (!msg.content) return;
+  // Normalize id to a string so downstream meta (message_id) is set consistently
+  // regardless of whether it arrived as a number (GET) or string (SSE).
+  const normalized: DmMessage = idStr ? { ...msg, id: idStr } : msg;
+  // onMessage errors must NOT look like a connection failure (which would
+  // trigger an endless fast reconnect) — catch them separately. Mark the id
+  // handled ONLY after a successful delivery: at-least-once beats at-most-once
+  // for a delivery-reliability fix, so a transient handler failure is retried on
+  // the next catch-up rather than silently dropped (review: Codex exactly-once).
+  try {
+    await opts.onMessage(normalized);
+    if (idStr) handledIds.add(idStr);
+  } catch (handlerErr) {
+    opts.log?.(
+      `[dm-stream] onMessage handler error: ${handlerErr instanceof Error ? handlerErr.message : String(handlerErr)}\n`,
+    );
+  }
+}
+
+/**
+ * Catch up on messages published before/while we were (re)connecting. Runs
+ * AFTER the SSE subscription is established (resp.ok) but BEFORE reading live
+ * events, mirroring the codex bridge: the subscription is registered server-side
+ * by the time the response resolves, so any message published between this fetch
+ * and the first live read is still delivered on the stream — `handledIds` dedups
+ * the overlap. A 401 here means the DM token expired → surface as a terminal
+ * DmStreamAuthError (same as the SSE 401). Other fetch failures are logged and
+ * swallowed (the live stream may still deliver).
+ */
+async function catchUp(opts: DmStreamOptions, handledIds: Set<string>): Promise<void> {
+  const doFetch = opts.fetchMessagesImpl ?? fetchMessages;
+  let msgs: Array<Record<string, unknown>>;
+  try {
+    msgs = await doFetch(opts.wsUrl, opts.conversationId, opts.conversationToken);
+  } catch (err) {
+    if (err instanceof ConversationTokenExpiredError) throw new DmStreamAuthError();
+    opts.log?.(
+      `[dm-stream] ${opts.conversationId} catch-up fetch failed: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return;
+  }
+  for (const raw of msgs) {
+    // Abort is terminal: this DM session ends here. Any ids already added to
+    // handledIds are intentionally dropped — a future DM uses a fresh
+    // runDmStream with its own handledIds (review: Opus #2).
+    if (opts.signal?.aborted) return;
+    await forwardMessage(opts, handledIds, raw as unknown as DmMessage);
+  }
+}
+
+/**
+ * One SSE connection attempt: yields each parsed `message` payload until the
+ * stream ends, `stop` arrives, or the signal aborts. Returns "stop" if the
+ * server signalled stop, "end" on a clean close (caller reconnects), and throws
+ * on 401 (token expired) or connection failure. `handledIds` is shared across
+ * reconnects so catch-up and live delivery stay idempotent.
+ */
+async function consumeOnce(
+  opts: DmStreamOptions,
+  handledIds: Set<string>,
+): Promise<"stop" | "end"> {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const url = buildSseUrl(opts.wsUrl, opts.conversationId);
+  const resp = await doFetch(url, {
+    headers: {
+      Authorization: `Bearer ${opts.conversationToken}`,
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      ...cfAccessHeaders(),
+    },
+    signal: opts.signal,
+  });
+  if (resp.status === 401) throw new DmStreamAuthError();
+  if (!resp.ok || !resp.body) {
+    throw new Error(`DM stream connection failed: HTTP ${resp.status}`);
+  }
+
+  // Subscription is live → replay anything missed before reading live events.
+  await catchUp(opts, handledIds);
+
+  const reader = resp.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return "end";
+      buffer += decoder
+        .decode(value, { stream: true })
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n");
+
+      while (true) {
+        const eventEnd = buffer.indexOf("\n\n");
+        if (eventEnd === -1) break;
+        const block = buffer.slice(0, eventEnd);
+        buffer = buffer.slice(eventEnd + 2);
+        if (block.startsWith(":")) continue; // keepalive comment
+
+        let event = "";
+        const dataLines: string[] = [];
+        for (const line of block.split("\n")) {
+          if (line.startsWith(":")) continue; // per-line comment / keepalive
+          if (line.startsWith("event:")) event = line.slice(6).trimStart();
+          // SSE allows multiple `data:` lines per event → join with "\n".
+          else if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+        }
+        if (event === "stop") return "stop";
+        const data = dataLines.join("\n");
+        if (event !== "message" || !data) continue;
+        let msg: DmMessage | null = null;
+        try {
+          msg = JSON.parse(data) as DmMessage;
+        } catch {
+          opts.log?.(`[dm-stream] ignored malformed message payload\n`);
+        }
+        if (msg) await forwardMessage(opts, handledIds, msg);
+      }
+    }
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {
+      /* already closed / aborted */
+    }
+  }
+}
+
+/** Raised when the DM SSE returns 401 — the DM conversation_token has expired. */
+export class DmStreamAuthError extends Error {
+  constructor() {
+    super("DM stream unauthorized (conversation token expired)");
+    this.name = "DmStreamAuthError";
+  }
+}
+
+/**
+ * Run a DM conversation SSE for as long as it stays open, reconnecting on
+ * transient drops. Resolves when the stream terminates for good (stop, 401, or
+ * abort). Never throws — terminal reasons are logged.
+ */
+export async function runDmStream(opts: DmStreamOptions): Promise<void> {
+  const log = opts.log ?? (() => {});
+  const delayMs = opts.reconnectDelayMs ?? 2000;
+  const maxErrors = opts.maxConsecutiveErrors ?? 8;
+  const signal = opts.signal;
+  // Shared across reconnects so catch-up + live delivery dedup by message id.
+  const handledIds = new Set<string>();
+  // CONSECUTIVE connection errors. A clean end resets it to 0, so a normally
+  // recycling stream never trips the cap — only a persistent failure does.
+  let consecutiveErrors = 0;
+
+  while (true) {
+    if (signal?.aborted) return;
+    try {
+      const reason = await consumeOnce(opts, handledIds);
+      consecutiveErrors = 0; // clean end (or stop) → reset the retry budget
+      if (reason === "stop") {
+        log(`[dm-stream] ${opts.conversationId} stopped\n`);
+        return;
+      }
+      // Clean end → reconnect after backoff.
+    } catch (err) {
+      if (err instanceof DmStreamAuthError) {
+        log(`[dm-stream] ${opts.conversationId} token expired — ending (peer can re-open)\n`);
+        return;
+      }
+      if (signal?.aborted) return;
+      consecutiveErrors += 1;
+      log(
+        `[dm-stream] ${opts.conversationId}: ${err instanceof Error ? err.message : String(err)}, reconnecting (${consecutiveErrors}/${maxErrors})...\n`,
+      );
+      if (consecutiveErrors >= maxErrors) {
+        log(
+          `[dm-stream] ${opts.conversationId} giving up after ${maxErrors} consecutive errors — ending (peer can re-open)\n`,
+        );
+        return;
+      }
+    }
+    if (signal?.aborted) return;
+    await abortableDelay(delayMs, signal);
+  }
+}

package/lib/fingerprint.ts

@@ -8,7 +8,7 @@ import { realpathSync } from "node:fs";
 // computed at bootstrap time and at channel start time would never match.
 export function normalizePath(absPath: string): string {
   if (process.platform !== "win32") return absPath;
-  // C:\Users\jeanp\... → /c/Users/jeanp/...
+  // C:\Users\<user>\... → /c/Users/<user>/...
   let p = absPath.replace(/\\/g, "/");
   const driveMatch = p.match(/^([A-Za-z]):\/(.*)$/);
   if (driveMatch) {

package/lib/heartbeat.ts

@@ -0,0 +1,95 @@
+/**
+ * Instance liveness heartbeat scheduler (#311) — shared by every channel-kind
+ * client (viber-channel.ts AND viber-codex-bridge.ts).
+ *
+ * An agent (instance) is online as long as its instance heartbeat is fresh; the
+ * server's sweeper purges any instance whose heartbeat goes stale. So EVERY
+ * channel client must beat, or the sweeper will (correctly, by its rules) drop
+ * it from the Agents sidebar and signal its streams to stop. This module
+ * centralizes the beat so the two clients can't diverge.
+ *
+ * The token is read through a getter on every tick so the beat follows token
+ * refresh (#237) without re-wiring. (The legacy per-conversation heartbeat #298
+ * was removed in #315 once "Active" derived from instance liveness.)
+ */
+
+import { sendInstanceHeartbeat } from "./control_stream.ts";
+
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
+
+/**
+ * Resolve the beat interval from the environment (seconds), defaulting to 25s.
+ * Must stay comfortably under the server timeout (VIBER_CHANNEL_PRESENCE_TIMEOUT,
+ * default 90s) so a single missed beat never trips the sweeper.
+ */
+export function resolveHeartbeatIntervalMs(
+  env: Record<string, string | undefined> = process.env,
+): number {
+  const raw = env.VIBER_CHANNEL_HEARTBEAT_INTERVAL_SECONDS;
+  const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isFinite(n) && n > 0 ? n * 1000 : DEFAULT_HEARTBEAT_INTERVAL_MS;
+}
+
+export interface HeartbeatHandle {
+  /** Cancel the scheduler. Idempotent. */
+  stop: () => void;
+}
+
+export interface InstanceHeartbeatOptions {
+  baseUrl: string;
+  instanceId: string;
+  /** Current instance token — read each tick (follows refresh). */
+  getInstanceToken: () => string;
+  intervalMs?: number;
+  log?: (line: string) => void;
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+  /** Injectable beat fn for tests. Defaults to sendInstanceHeartbeat. */
+  beat?: (baseUrl: string, instanceId: string, instanceToken: string) => Promise<boolean>;
+}
+
+/**
+ * Start beating the INSTANCE control-stream liveness (#311). Instance-scoped: an
+ * agent is online as long as its instance heartbeat is fresh, independent of any
+ * conversation (it can be in await-invite with no conversation, or in several).
+ * Single-flight + unref'd timer so the beat never keeps a doomed process alive on
+ * its own.
+ */
+export function startInstanceHeartbeat(opts: InstanceHeartbeatOptions): HeartbeatHandle {
+  const intervalMs = opts.intervalMs ?? resolveHeartbeatIntervalMs();
+  const log = opts.log ?? ((line: string) => process.stderr.write(line));
+  const setTimer =
+    opts.setTimer ?? ((fn: () => void, ms: number) => setInterval(fn, ms) as unknown);
+  const clearTimer =
+    opts.clearTimer ??
+    ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>));
+  const beat = opts.beat ?? sendInstanceHeartbeat;
+
+  let inFlight = false;
+  const handle = setTimer(() => {
+    if (inFlight) return;
+    inFlight = true;
+    void beat(opts.baseUrl, opts.instanceId, opts.getInstanceToken())
+      .then((ok) => {
+        if (!ok) {
+          log("[viber-channel] instance heartbeat failed (will retry next interval)\n");
+        }
+      })
+      .finally(() => {
+        inFlight = false;
+      });
+  }, intervalMs);
+
+  if (handle && typeof (handle as { unref?: () => void }).unref === "function") {
+    (handle as { unref: () => void }).unref();
+  }
+
+  let stopped = false;
+  return {
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      clearTimer(handle);
+    },
+  };
+}