viber-channel 0.5.3 → 0.7.0

package/viber-channel.ts

@@ -30,14 +30,25 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprot
 import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { runConnect } from "./lib/connect.ts";
-import { lockFilePath } from "./lib/lockfile.ts";
+import { lockFilePath, lockSessionId } from "./lib/lockfile.ts";
 import { sessionFilePath, clearHandle } from "./lib/channel_session.ts";
 import { clientFingerprint } from "./lib/fingerprint.ts";
 import { MessageDedup } from "./lib/message_dedup.ts";
 import {
   acquireConversation,
+  ConversationMintError,
   DEFAULT_REATTACH_WINDOW_SECONDS,
+  type ConversationMintResponse,
 } from "./lib/conversation.ts";
+import { startInstanceHeartbeat } from "./lib/heartbeat.ts";
+import { startParentWatchdog } from "./lib/parent_watchdog.ts";
+import { acquireInstance, registerInstance } from "./lib/instance.ts";
+import {
+  runPersistentControlStream,
+  sendInstanceHeartbeat,
+} from "./lib/control_stream.ts";
+import { runDmStream } from "./lib/dm_stream.ts";
+import { isOwnMessage } from "./lib/self_echo.ts";
 import {
   createTokenRefreshScheduler,
   type TokenRefreshScheduler,
@@ -50,6 +61,22 @@ import { awaitStableStartup } from "./lib/startup_gate.ts";
 // exits — it does not start the MCP server. Any other invocation (no args, or
 // the unknown subcommand) falls through to the MCP server below.
 {
+  // #280 step-29: in an AGENT session (vibe-master terminal), the channel must
+  // be the PLUGIN copy (`--channels plugin:viber-channel@…` — only it can
+  // inject inbound messages). The manually-registered viber-dev-channel MCP
+  // loads in the same session with the same env; instead of racing it for the
+  // channel lock, it bows out deterministically here. Normal sessions
+  // (no VIBER_CHANNEL_AGENT_SESSION) are unaffected.
+  if (
+    process.env.VIBER_CHANNEL_AGENT_SESSION === "1" &&
+    process.env.VIBER_CHANNEL_PLUGIN !== "1"
+  ) {
+    process.stderr.write(
+      "[viber-channel] agent session: yielding to the plugin channel copy (manual MCP registration exits)\n",
+    );
+    process.exit(0);
+  }
+
   const sub = process.argv[2];
   if (sub === "--help" || sub === "-h") {
     process.stdout.write(
@@ -100,10 +127,23 @@ const LOCK_DIR =
     ? join(process.env.APPDATA, "viber")
     : join(process.env.HOME ?? "/tmp", ".config", "viber");
 const LOCK_BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
-const LOCK_SESSION_ID = process.env.VIBER_CHANNEL_SESSION_ID ?? "";
+// #269: a fleet's parallel agents each carry their own VIBER_INSTANCE_TOKEN but
+// often no VIBER_CHANNEL_SESSION_ID. Fold a HASH of the instance token into the
+// lock's session axis so distinct env-injected instances get distinct locks
+// (parallel same-folder agents no longer collide) — without reordering instance
+// acquisition before the lock, which would defeat the #257 stability gate. An
+// explicit VIBER_CHANNEL_SESSION_ID still wins (back-compat). The token is
+// hashed (never raw) because LOCK_SESSION_ID is logged as a prefix below.
+// Lock session-id axis (#259/#269/#293): explicit session id > env instance
+// token > VIBER_CHANNEL_LABEL > "". A labelled 2nd agent in the same folder gets
+// its own lock (and its own fresh identity via acquireInstance); a plain launch
+// keeps sessionId="" so accidental duplicates stay blocked. See lockSessionId.
+const LOCK_SESSION_ID = lockSessionId(process.env);
 const LOCK_FINGERPRINT = clientFingerprint(process.cwd());
 const LOCK_FILE = lockFilePath(LOCK_BASE_URL, LOCK_FINGERPRINT, LOCK_SESSION_ID, LOCK_DIR);
-const SESSION_FILE = sessionFilePath(LOCK_BASE_URL, LOCK_FINGERPRINT, LOCK_SESSION_ID, LOCK_DIR);
+// SESSION_FILE (the conversation handle path) is computed AFTER the instance is
+// acquired (#269) — it is namespaced by the server-issued instance, not the
+// local fingerprint/sessionId. Declared as a `let` near the mint below.
 
 // VIBER_REATTACH_WINDOW_SECONDS overrides the default TTL-based window.
 // A handle older than this cannot point at a live conversation — skip reattach.
@@ -186,9 +226,14 @@ function acquireLock(): number | null {
         continue;
       }
 
-      // Another live channel is running
+      // Another live channel holds this folder's lock. This blocks accidental
+      // duplicate spawns (#166/#259) — but it also blocks a deliberate 2nd agent
+      // in the same folder (#293). Make the message actionable: a labelled launch
+      // gets its own identity AND lock (see LOCK_SESSION_ID above).
       process.stderr.write(
-        `[viber-channel] Another instance already running (PID ${existingPid}), exiting.\n`
+        `[viber-channel] Another Viber agent holds this folder (PID ${existingPid}), exiting. ` +
+          `To run a SECOND agent here, set VIBER_CHANNEL_LABEL=<name> in this MCP server's env ` +
+          `(it gets its own identity + lock) and relaunch.\n`
       );
       return existingPid;
     }
@@ -248,7 +293,7 @@ process.stdin.on("end", () => {
 
 // ---- Auth from .viber/auth.json ----
 
-import { authFilePath, loadAuth } from "./lib/auth.ts";
+import { authFilePath, loadAuth, persistInstanceCredentials } from "./lib/auth.ts";
 import { handleConversationTokenExpired } from "./lib/channel_errors.ts";
 import { buildSseUrl } from "./lib/urls.ts";
 
@@ -274,7 +319,13 @@ import {
   RefreshHttpError,
   RefreshNetworkError,
 } from "./lib/conversation.ts";
-import { postMessage, ConversationTokenExpiredError, parseArtifact } from "./lib/messages.ts";
+import { ConversationTokenExpiredError } from "./lib/messages.ts";
+import {
+  listAgents as libListAgents,
+  messageAgent as libMessageAgent,
+  sendMessage as libSendMessage,
+  type AgentToolsContext,
+} from "./lib/agent_tools.ts";
 import { cfAccessHeaders } from "./lib/cfAccess.ts";
 
 const BASE_URL = process.env.VIBER_BASE_URL ?? "https://viber.dgypx.dev";
@@ -291,12 +342,14 @@ const mcp = new Server(
     },
     instructions: [
       'Voice transcripts arrive as <channel source="viber-channel"> events carrying the user\'s microphone speech.',
-      "Reply with send_message. The `text` field is read aloud to the user, so keep it a short, natural spoken sentence — no markdown symbols, no bullet lists, no tables, no code blocks.",
-      "Exception for inline identifiers: when mentioning a file name, hostname, variable, or other short token inline (auth.json, viber-dev.dgypx.dev, CONVERSATION_TOKEN), write the literal form with its real dots and dashes — do NOT spell them out as 'point' or 'dash'. The 'no markdown' rule is about visual clutter (`**bold**`, `- bullets`, code fences, tables, long path lists), not the punctuation that's naturally part of identifiers.",
-      "Put technical content (code, lists, JSON, tables, command output, long file paths) in the optional `artifact` field with the matching `format`; it renders in a side viewer the user can read.",
-      "Available formats: `markdown` (default), `code`, `json`, `html`.",
-      "Use `html` only when the rendering needs structural HTML markdown can't express (styled cards, badges, mixed layouts). Scripts and event handlers are stripped server-side; don't try to send executable JS.",
-      "Rule of thumb: if it would sound bad read aloud, it belongs in the artifact, not the text.",
+      "Reply with send_message. You are talking to a human who both LISTENS (the `text` is read aloud by TTS) AND READS it on screen (the `text` is ALSO rendered as Markdown in the UI). So aim for both: it must sound natural read aloud AND be easy to read. Lead with the answer, no preamble or recap.",
+      "USE light Markdown in `text` when it makes the message easier to read: short bullet lists (`- `), numbered steps (`1.`), checklists, **bold** for key terms. A short list reads aloud just fine — a spoken list is natural. Don't cram several points into one dense paragraph; break them out. Avoid heavy/awkward-to-speak markup (big tables, code blocks, long fenced snippets) in `text` — that belongs in the artifact.",
+      "ACTIONS and QUESTIONS belong in `text`, made visible — never bury them in the artifact. If you need a decision, ask it clearly in `text` (a short bullet list of the options is good); the artifact may hold supporting detail but the question itself must be in `text` where it jumps out.",
+      "The `artifact` is for HEAVY or LONG content only: big code, large tables, long multi-point analyses, review dumps, JSON, file lists. When you use an artifact, keep `text` a brief spoken summary that points to it ('details on the side') — don't read the heavy content aloud.",
+      "Write identifiers LITERALLY with their real characters (288, auth.json, viber-dev.dgypx.dev, CONVERSATION_TOKEN) — never spell them out as 'point'/'dash' and never as awkward digit-by-digit text. A lone long token or path is better placed in the artifact than spoken.",
+      "Artifact formats: `markdown` (default), `code`, `json`, `html`. Use `html` only when the rendering needs structural HTML Markdown can't express (styled cards, badges, mixed layouts). Scripts and event handlers are stripped server-side; don't send executable JS.",
+      "NO EMOJI in `text` — it is read aloud, so an emoji becomes spoken noise (a check mark is read as 'check mark'). Use plain Markdown (bullets, bold) for structure instead. Emoji are tolerable only inside an artifact (not spoken).",
+      "Rule of thumb: short and conversational, but readable — break points into a list rather than a wall of text; reserve the artifact for what is genuinely long or heavy.",
       "On exit intent (bye, au revoir, stop) call stop_conversation(), speak a brief farewell, and stop.",
     ].join(" "),
   }
@@ -310,8 +363,8 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "send_message",
       description:
         "Send a message into the Viber conversation this channel is bound to. " +
-        "`text` is the spoken/conversational reply (read aloud — keep it short and natural, no markdown). " +
-        "`artifact` is optional and carries technical content (markdown, code, JSON, or sanitized HTML) rendered in a side viewer. " +
+        "`text` is the conversational reply — it is BOTH read aloud (TTS) AND rendered as Markdown on screen, so keep it short and natural but use light Markdown (short bullet/numbered lists, **bold**) when it aids readability. Put any ACTIONS or QUESTIONS for the user here, visibly. " +
+        "`artifact` is optional and carries HEAVY/LONG content (big code, large tables, long analyses, JSON, sanitized HTML) rendered in a side viewer; when used, keep `text` a brief summary that points to it. " +
         "Use `html` only when structural HTML markdown can't express is required; scripts and event handlers are stripped before display.",
       inputSchema: {
         type: "object" as const,
@@ -319,7 +372,7 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
           text: {
             type: "string",
             minLength: 1,
-            description: "Spoken/conversational reply. Plain sentences, no markdown symbols or lists.",
+            description: "Conversational reply, read aloud AND shown as Markdown. Short and natural, but use light Markdown (short lists, numbered steps, **bold**) for readability. Actions/questions go here, visibly. NO emoji (it gets read aloud).",
           },
           artifact: {
             type: "object",
@@ -345,44 +398,101 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["text"],
       },
     },
+    {
+      name: "list_agents",
+      description:
+        "List the OTHER agents (instances) in this project you can talk to directly (#288). " +
+        "Returns each agent's id, label, runtime kind, and whether it is currently online. " +
+        "Use this to find the id of an agent (e.g. 'Codex Review') before calling message_agent. " +
+        "Only agents in the same project are returned; you are never in the list.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {},
+        required: [],
+        additionalProperties: false,
+      },
+    },
+    {
+      name: "message_agent",
+      description:
+        "Send a direct message to another agent in this project (#288). " +
+        "Pass the target agent's instance id (from list_agents, or the from_instance_id of a DM you received) " +
+        "and the message text. Opens or reuses a private 1:1 DM with that agent and posts your message; " +
+        "the agent's reply arrives back on this channel tagged source=agent-dm. " +
+        "Fails if the target agent is offline.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          instance_id: {
+            type: "string",
+            minLength: 1,
+            description: "The target agent's instance id (from list_agents or a received DM's from_instance_id).",
+          },
+          text: {
+            type: "string",
+            minLength: 1,
+            description: "The message to send to the target agent.",
+          },
+        },
+        required: ["instance_id", "text"],
+        additionalProperties: false,
+      },
+    },
   ],
 }));
 
+// Live, by-reference view of this channel's runtime state for the shared tool
+// logic (#317, lib/agent_tools.ts). Every getter reads the current module var at
+// call time — never a snapshot — so token refresh / re-mint are picked up. The
+// Codex bridge implements the same AgentToolsContext against its own runtime,
+// so both hosts run ONE tool implementation (no double maintenance).
+const channelToolsCtx: AgentToolsContext = {
+  baseUrl: () => BASE_URL,
+  instanceToken: () => INSTANCE_TOKEN,
+  voiceBaseUrl: () => VOICE_BASE_URL,
+  // send_message posts into the main conversation for the Claude MCP.
+  sendConversationId: () => CONVERSATION_ID,
+  sendConversationToken: () => CONVERSATION_TOKEN,
+  // Stream the opened DM so the peer's reply surfaces here (deduped by the Map;
+  // a re-join replaces the stream). ws_url is the main conversation's voice host.
+  startDmStream: (dm) =>
+    startDmStream({
+      conversation_id: dm.conversation_id,
+      conversation_token: dm.conversation_token,
+      ws_url: VOICE_BASE_URL,
+      expires_at: dm.expires_at,
+    }),
+};
+
 // NOTE: CONVERSATION_TOKEN, CONVERSATION_ID, BASE_URL are populated after
 // mintConversation() runs (below). The handler closure captures the variables
 // by reference — by the time Claude Code calls the tool, they are populated.
 mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
-  if (request.params.name !== "send_message") {
-    return {
-      isError: true,
-      content: [{ type: "text" as const, text: `Unknown tool: ${request.params.name}` }],
-    };
+  const args = (request.params.arguments ?? {}) as Record<string, unknown>;
+
+  if (request.params.name === "list_agents") {
+    return libListAgents(channelToolsCtx);
   }
 
-  const args = (request.params.arguments ?? {}) as Record<string, unknown>;
-  const text = args.text;
-  if (typeof text !== "string" || text.trim().length === 0) {
-    return {
-      isError: true,
-      content: [{ type: "text" as const, text: "Invalid input: text must be a non-empty string" }],
-    };
+  if (request.params.name === "message_agent") {
+    return libMessageAgent(channelToolsCtx, args);
   }
 
-  const parsed = parseArtifact(args.artifact);
-  if (!parsed.ok) {
+  if (request.params.name !== "send_message") {
     return {
       isError: true,
-      content: [{ type: "text" as const, text: `Invalid input: ${parsed.error}` }],
+      content: [{ type: "text" as const, text: `Unknown tool: ${request.params.name}` }],
     };
   }
-  const artifact = parsed.artifact;
 
-  let result;
+  // send_message: the shared lib validates input, guards the startup window, and
+  // posts (with artifact). It rethrows ConversationTokenExpiredError because the
+  // teardown policy is host-specific — here, Claude is notified and the process
+  // exits 3 (the bridge handles the same error as a controlled shutdown).
   try {
-    result = await postMessage(BASE_URL, CONVERSATION_ID, CONVERSATION_TOKEN, text, artifact);
+    return await libSendMessage(channelToolsCtx, args);
   } catch (err) {
     if (err instanceof ConversationTokenExpiredError) {
-      // Notify Claude (and the user) that the channel token has expired
       await handleConversationTokenExpired(mcp);
       // handleConversationTokenExpired calls process.exit(3) — unreachable, but
       // TypeScript needs a return to satisfy the type checker.
@@ -396,17 +506,6 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [{ type: "text" as const, text: `Unexpected error: ${String(err)}` }],
     };
   }
-
-  if (!result.ok) {
-    return {
-      isError: true,
-      content: [{ type: "text" as const, text: result.detail }],
-    };
-  }
-
-  return {
-    content: [{ type: "text" as const, text: `Message sent: ${result.message_id}` }],
-  };
 });
 
 // Prevent duplicate instances (#166); fingerprint namespacing for different
@@ -440,6 +539,27 @@ if (blockingPid !== null) {
   process.exit(1);
 }
 
+// ---- Parent-liveness watchdog (#298) ----
+//
+// Start it HERE — right after mcp.connect(), BEFORE the stability gate and the
+// (slow) conversation mint — so the agent (claude.exe) is still alive when we
+// read the process table to resolve it. Starting it late (after the mint) opened
+// a window where, if Claude died first, resolveAgentPid couldn't find claude.exe
+// and (pre-fix) fell back to a surviving shim → permanent zombie (#298 P2a).
+//
+// The heartbeat proves the PROCESS is alive — not that the AGENT is. If Claude
+// dies but this process lingers (Windows stdin-EOF can fail to propagate through
+// the cmd.exe/bunx spawn chain), it becomes a zombie that keeps beating and shows
+// "online" with no one answering. The watchdog watches the agent PID+identity and
+// exits the instant it's gone — the reliable backstop to the stdin "end" handler.
+startParentWatchdog({
+  onParentGone: () => {
+    scheduler?.cancel();
+    releaseLock();
+    process.exit(0);
+  },
+});
+
 // ---- Stability gate (#257): defer conversation creation so a doomed process exits first ----
 //
 // Claude Code respawns the channel on transport reconnects; a process that dies
@@ -460,29 +580,138 @@ process.stderr.write(`[viber-channel] startup: stability gate passed (${STABILIT
 
 // ---- Acquire conversation token (reattach or mint, after mcp.connect so a token-rejected notification can be sent) ----
 
-let CONVERSATION_TOKEN: string;
-let VOICE_BASE_URL: string;
-let CONVERSATION_ID: string;
+// Empty until the conversation is acquired below (after mcp.connect + the
+// stability gate). Initialised (not bare `let x: string`) so the send_message
+// handler can safely guard on them during the startup window without hitting a
+// temporal-dead-zone ReferenceError if a tool call lands before this point.
+let CONVERSATION_TOKEN = "";
+let VOICE_BASE_URL = "";
+let CONVERSATION_ID = "";
+let SESSION_FILE = "";
+// This channel's own server-issued instance id (#280 step-16). Used by the
+// self-echo guard: messages posted by this instance are NOT surfaced back to
+// Claude when the conversation SSE replays them.
+let OWN_INSTANCE_ID = "";
+// This channel's durable instance_token (#288). Captured at startup so the
+// agent-facing MCP tools (list_agents, message_agent) can authenticate to the
+// peers / DM endpoints. Empty until acquireInstance runs below.
+let INSTANCE_TOKEN = "";
+
+// Agent↔agent DM conversations we are actively streaming (#288 step-04), keyed
+// by conversation_id → the AbortController for its SSE loop. A re-pushed `join`
+// (peer re-opened the DM, e.g. with a fresh token) ABORTS the old stream and
+// starts a new one, so a stuck/stale stream can never block a fresh join.
+const activeDmStreams = new Map<string, AbortController>();
 
-process.stderr.write(`[viber-channel] startup: acquiring conversation (project=${auth.project_id}, target=${auth.target_conversation_id ?? "null"}, session=${SESSION_FILE})\n`);
 try {
-  const minted = await acquireConversation(
-    SESSION_FILE,
-    BASE_URL,
-    auth.project_id,
-    auth.project_token,
-    auth.client_fingerprint,
-    label,
-    auth.target_conversation_id ?? null,
-    REATTACH_WINDOW_SECONDS,
-  );
+  // #269: acquire this channel's server-issued instance identity — env-injected
+  // VIBER_INSTANCE_TOKEN > persisted auth.json instance_token > register a new
+  // one with the stable project_token (self-healing auth.json). The conversation
+  // handle is namespaced by the instance, not the local fingerprint/sessionId.
+  const acquired = await acquireInstance(BASE_URL, auth, auth.client_fingerprint);
+  let instanceToken = acquired.instance_token;
+  // Self-echo guard (#280 step-16) needs the REAL server instance id — never the
+  // token that instance_key may fall back to (Codex review P1). Undefined → ""
+  // → the guard is a no-op (delivers everything), which is the safe default.
+  OWN_INSTANCE_ID = acquired.instance_id ?? "";
+  SESSION_FILE = sessionFilePath(LOCK_BASE_URL, acquired.instance_key, LOCK_DIR);
+
+  process.stderr.write(`[viber-channel] startup: acquiring conversation (project=${auth.project_id}, target=${auth.target_conversation_id ?? "null"}, session=${SESSION_FILE})\n`);
+
+  // Join the conversation with the instance_token. A 401 means the instance was
+  // revoked (the token is durable — no expiry case): re-register a fresh instance
+  // ONCE (a NEW instance_id, the correct post-revocation outcome) and retry. A
+  // second failure falls through to the catch below.
+  let minted: ConversationMintResponse;
+  try {
+    minted = await acquireConversation(
+      SESSION_FILE,
+      BASE_URL,
+      auth.project_id,
+      instanceToken,
+      auth.client_fingerprint,
+      label,
+      auth.target_conversation_id ?? null,
+      REATTACH_WINDOW_SECONDS,
+    );
+  } catch (err) {
+    if (err instanceof ConversationMintError && err.status === 401) {
+      process.stderr.write(
+        `[viber-channel] instance token rejected (401 revoked) — re-registering a fresh instance once\n`,
+      );
+      const reg = await registerInstance(
+        BASE_URL,
+        auth.project_id,
+        auth.project_token,
+        auth.client_fingerprint,
+      );
+      persistInstanceCredentials(authFilePath(), reg.instance_id, reg.instance_token);
+      instanceToken = reg.instance_token;
+      OWN_INSTANCE_ID = reg.instance_id;
+      SESSION_FILE = sessionFilePath(LOCK_BASE_URL, reg.instance_id, LOCK_DIR);
+      minted = await acquireConversation(
+        SESSION_FILE,
+        BASE_URL,
+        auth.project_id,
+        instanceToken,
+        auth.client_fingerprint,
+        label,
+        auth.target_conversation_id ?? null,
+        REATTACH_WINDOW_SECONDS,
+      );
+    } else {
+      throw err;
+    }
+  }
 
-  // project_token is now a stable, long-lived handshake credential (#274). It is
-  // never rotated by the mint response, so auth.json is never rewritten here.
+  // project_token / instance_token are stable, long-lived credentials (#274/#269);
+  // neither is rotated by the mint response. The membership conversation_token
+  // (below) is the short-lived tier and self-refreshes.
 
   CONVERSATION_TOKEN = minted.conversation_token;
   VOICE_BASE_URL = minted.ws_url;
   CONVERSATION_ID = minted.conversation_id;
+  // Capture the durable instance_token for the agent-facing MCP tools (#288).
+  INSTANCE_TOKEN = instanceToken;
+
+  // #280 step-27: hold the instance control stream open for the WHOLE session —
+  // it IS the "online" presence signal (step-02). Without it this agent never
+  // shows online in the control plane (sidebar Agents) and is not invitable.
+  // A pushed `join` is an agent↔agent DM invite (#288 step-04): we run a DM SSE
+  // for it IN PARALLEL with the main conversation (coexistence — the main
+  // conversation stays bound to its own SSE, option A). A `stop` (revoke) is
+  // logged only: the conversation-token path already fails closed.
+  if (OWN_INSTANCE_ID !== "") {
+    const controlStream = runPersistentControlStream(
+      { baseUrl: BASE_URL, instanceId: OWN_INSTANCE_ID, instanceToken },
+      {
+        log: (m) => process.stderr.write(m),
+        onJoin: (pushed) => startDmStream(pushed),
+        onStop: (reason) =>
+          process.stderr.write(`[viber-channel] control stream stopped (${reason})\n`),
+        // #311: the server is probing — answer with an immediate instance heartbeat.
+        onBeatNow: () => {
+          void sendInstanceHeartbeat(BASE_URL, OWN_INSTANCE_ID, INSTANCE_TOKEN);
+        },
+      },
+    );
+    // Presence-only consumer: firstJoin ALWAYS settles (rejected at loop end) —
+    // observe it so an ignored join/stop never becomes an unhandled rejection.
+    controlStream.firstJoin.catch(() => {});
+    controlStream.done.catch(() => {});
+    // #311: beat the INSTANCE control-stream liveness so the server's sweeper
+    // never keeps this agent "online" after it dies (the control SSE can stay
+    // half-open behind the tunnel). The instance_token is durable (#269/#274),
+    // read via closure so a re-register is picked up. unref'd internally.
+    const instanceHeartbeat = startInstanceHeartbeat({
+      baseUrl: BASE_URL,
+      instanceId: OWN_INSTANCE_ID,
+      getInstanceToken: () => INSTANCE_TOKEN,
+    });
+    // Stop beating once the control stream ends (revoke / 401 / abort) so a
+    // doomed instance doesn't keep beating (Opus review).
+    controlStream.done.finally(() => instanceHeartbeat.stop());
+  }
 
   // Schedule silent token refresh ahead of expiry (#237 step-03). On success
   // we mutate CONVERSATION_TOKEN in place — getHeaders() reads it by closure,
@@ -600,9 +829,13 @@ try {
 // ---- Channel ready banner ----
 
 process.stderr.write(
-  `[viber-channel] Channel ready: 1 tool (send_message), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
+  `[viber-channel] Channel ready: 3 tools (send_message, list_agents, message_agent), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
 );
 
+// Channel liveness is proven by the INSTANCE heartbeat (#311, started above), not
+// a per-conversation beat — the legacy conversation heartbeat (#298) was removed
+// in #315 once "Active" derived from instance liveness.
+
 // ---- URLs and auth headers ----
 
 /** Primary SSE endpoint: conversation-scoped event bus (step-03 / #221). */
@@ -653,14 +886,33 @@ const messageDedup = new MessageDedup();
  * so downstream consumers (step-03 React viewer) can opt-in without a second
  * round-trip; the channel itself does no special rendering of it yet.
  */
-async function pushMessage(msg: {
-  content: string;
-  id?: string | null;
-  source?: string;
-  artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
-}): Promise<void> {
+async function pushMessage(
+  msg: {
+    content: string;
+    id?: string | null;
+    source?: string;
+    artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+    sender_instance_id?: string | null;
+  },
+  // Provenance for an agent↔agent DM (#288 step-04): when set, the message is
+  // tagged as coming from a peer DM so the model knows which conversation it is
+  // and which instance to reply to (via message_agent), distinct from the main
+  // conversation's voice/text flow.
+  origin?: { conversationId: string },
+): Promise<void> {
   process.stderr.write(`[viber-channel] pushMessage ENTER: "${msg.content.slice(0, 60)}"\n`);
-  if (messageDedup.isDuplicate(msg)) {
+  // Never echo this channel's OWN posted messages back to Claude (#280 step-16):
+  // send_message posts as this instance, and the conversation SSE replays it.
+  if (isOwnMessage(msg.sender_instance_id, OWN_INSTANCE_ID)) {
+    process.stderr.write(`[viber-channel] dropping own posted message (self-echo)\n`);
+    return;
+  }
+  // The dedup is for the main conversation's ephemeral+persisted DOUBLE delivery
+  // of user voice transcripts. DM messages (origin set) don't have that problem,
+  // and the dedup keys on content alone — running DMs through it would let a DM
+  // and a main-conversation message with identical short text (e.g. "ok") drop
+  // each other within the TTL (Codex + reviewer P1). So skip dedup for DMs.
+  if (!origin && messageDedup.isDuplicate(msg)) {
     process.stderr.write(
       `[viber-channel] dropping duplicate persisted message (already delivered ephemerally)\n`,
     );
@@ -668,7 +920,20 @@ async function pushMessage(msg: {
   }
   // MCP notification handler (Claude Code v2.1.143) validates meta with Zod;
   // null fields are rejected as invalid type. Omit message_id when missing.
-  const meta: Record<string, unknown> = { source: msg.source ?? "conversation" };
+  const meta: Record<string, unknown> = origin
+    ? { source: "agent-dm", conversation_id: origin.conversationId }
+    : { source: msg.source ?? "conversation" };
+  if (origin && typeof msg.sender_instance_id === "string" && msg.sender_instance_id.length > 0) {
+    // The id the model passes to message_agent to reply to this peer.
+    meta.from_instance_id = msg.sender_instance_id;
+  } else if (origin) {
+    // No sender id on a DM message → the model can still see conversation_id but
+    // has no instance to reply to. Server-posted DM messages always carry
+    // sender_instance_id today; this branch is a guard for malformed payloads.
+    process.stderr.write(
+      `[viber-channel] DM message on ${origin.conversationId} has no sender_instance_id — reply not routable\n`,
+    );
+  }
   if (typeof msg.id === "string" && msg.id.length > 0) {
     meta.message_id = msg.id;
   }
@@ -687,6 +952,45 @@ async function pushMessage(msg: {
   }
 }
 
+/**
+ * Start streaming an agent↔agent DM (#288 step-04) pushed via the control
+ * stream. Dedups by conversation_id; surfaces each incoming message to the
+ * model with DM provenance (origin). Runs for the DM's lifetime in parallel
+ * with the main conversation; clears its dedup slot when the stream ends.
+ */
+function startDmStream(minted: ConversationMintResponse): void {
+  // A re-pushed join for a live DM means the peer re-opened it (likely a fresh
+  // token). Abort the old stream and start a new one with the new credentials,
+  // rather than ignoring the join and leaving a possibly-stale stream running.
+  const prior = activeDmStreams.get(minted.conversation_id);
+  if (prior) {
+    process.stderr.write(
+      `[viber-channel] DM ${minted.conversation_id} re-joined — replacing existing stream\n`,
+    );
+    prior.abort();
+  }
+  const controller = new AbortController();
+  activeDmStreams.set(minted.conversation_id, controller);
+  process.stderr.write(`[viber-channel] joining agent DM ${minted.conversation_id}\n`);
+  // The agent's liveness (and thus the DM's presence in the "Active" sidebar) is
+  // proven by the INSTANCE heartbeat, not a per-conversation beat — the legacy
+  // per-DM conversation heartbeat (#298) was removed in #315.
+  void runDmStream({
+    wsUrl: minted.ws_url,
+    conversationId: minted.conversation_id,
+    conversationToken: minted.conversation_token,
+    log: (m) => process.stderr.write(m),
+    signal: controller.signal,
+    onMessage: (msg) => pushMessage(msg, { conversationId: minted.conversation_id }),
+  }).finally(() => {
+    // Only evict if WE are still the registered controller — a newer join may
+    // have replaced us, and it must keep its slot.
+    if (activeDmStreams.get(minted.conversation_id) === controller) {
+      activeDmStreams.delete(minted.conversation_id);
+    }
+  });
+}
+
 /** SSE stream — preferred method (#170) */
 async function sseLoop(): Promise<void> {
   const headers = getHeaders();
@@ -776,6 +1080,7 @@ async function sseLoop(): Promise<void> {
                 role?: string;
                 timestamp?: string;
                 artifact?: { content: string; format?: "markdown" | "code" | "json" | "html" } | null;
+                sender_instance_id?: string | null;
               };
               if (msg.content) {
                 await pushMessage(msg);