viber-channel 0.8.4 → 0.8.6

package/lib/channel_session.ts

@@ -50,6 +50,89 @@ export function sessionFilePath(
   return join(dir, `channel-session-${suffix}.json`);
 }
 
+/**
+ * Session file path for a **named** channel agent (#400), namespaced by
+ * `(baseUrl, projectId, name)` instead of the server `instance_id`.
+ *
+ * Why a separate key: an agent launched by vibe-master carries a stable
+ * `VIBER_CHANNEL_LABEL` (its name) but re-registers a FRESH, non-persisted
+ * `instance_id` on every start (`acquireInstance` path 2). Keying the handle by
+ * that ephemeral id means it is never found on the next start → the channel
+ * mints a new conversation every time (the #400 accumulation). The NAME is the
+ * only key that survives across re-spawns and MCP reconnects, so a named agent
+ * namespaces its handle by name and finds — and reattaches — its previous
+ * conversation.
+ *
+ * `projectId` is folded in so the same name in two different projects (or
+ * worktrees connected to different projects) never collide on one handle file.
+ * The plain (un-named) channel keeps `sessionFilePath` keyed by the persisted
+ * `instance_id` — do NOT merge the two paths (#269 isolation on plain channel).
+ */
+export function sessionFilePathForName(
+  baseUrl: string,
+  projectId: number,
+  name: string,
+  dir: string,
+): string {
+  const suffix = createHash("sha256")
+    .update(`${baseUrl}\n${projectId}\n${name}`)
+    .digest("hex")
+    .slice(0, 8);
+  return join(dir, `channel-session-${suffix}.json`);
+}
+
+/**
+ * Pick the session-handle path for this channel process (#400), applying the
+ * named-vs-plain rule in ONE testable place (no `as` cast at the call site).
+ *
+ * A NAMED agent — a non-empty `channelLabel` (`VIBER_CHANNEL_LABEL`) AND no
+ * env-injected `instanceToken` (`VIBER_INSTANCE_TOKEN`) — keys its handle by the
+ * stable NAME (`sessionFilePathForName`), because `acquireInstance` path 2
+ * re-registers a fresh instance_id every start. Otherwise (plain channel, or an
+ * orchestrator-injected stable instance token = path 1) the handle stays keyed
+ * by the durable `instanceKey` (`sessionFilePath`) — #269 isolation preserved.
+ *
+ * Precedence mirrors `acquireInstance`: an env instance token (path 1) wins over
+ * a label (path 2), so `instanceToken` present ⇒ instance-keyed even if a label
+ * is also set.
+ */
+/**
+ * The stable resume NAME for a named agent session (#400), or `null` for a plain
+ * / orchestrator-injected session.
+ *
+ * A NAMED agent = a non-empty `channelLabel` (VIBER_CHANNEL_LABEL) AND no
+ * env-injected `instanceToken` (VIBER_INSTANCE_TOKEN). Such an agent re-registers
+ * a fresh instance_id every start (acquireInstance path 2), so its stable
+ * identity is the NAME: it keys its handle by name AND resumes by name. An
+ * env-injected token (path 1, orchestrator) means a durable instance → NOT a
+ * named-resume session (returns null). Single source of truth for both the
+ * handle-namespacing and resume-by-name decisions; returns the trimmed name so
+ * callers avoid re-deriving it (and no `as` cast is needed).
+ */
+export function namedAgentLabel(
+  channelLabel: string | undefined,
+  instanceToken: string | undefined,
+): string | null {
+  const name = channelLabel?.trim();
+  if (name === undefined || name === "") return null;
+  if ((instanceToken ?? "").trim() !== "") return null;
+  return name;
+}
+
+export function resolveSessionFilePath(opts: {
+  baseUrl: string;
+  projectId: number;
+  channelLabel: string | undefined;
+  instanceToken: string | undefined;
+  instanceKey: string;
+  dir: string;
+}): string {
+  const name = namedAgentLabel(opts.channelLabel, opts.instanceToken);
+  return name !== null
+    ? sessionFilePathForName(opts.baseUrl, opts.projectId, name, opts.dir)
+    : sessionFilePath(opts.baseUrl, opts.instanceKey, opts.dir);
+}
+
 /**
  * Read a persisted handle from `path`.
  *

package/lib/control_stream.ts

@@ -36,17 +36,29 @@ export function buildControlStreamUrl(baseUrl: string, instanceId: string): stri
  *
  * 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).
+ * still alive behind the Cloudflare tunnel, but this beat can. Bounded by a
+ * per-POST timeout so a hung tunnel socket can't stack beats (mirrors #298).
+ *
+ * #400 (recadrage): when `conversationId` is given, the server RENEWS this
+ * instance's conversation lease and reports `lease_active` — `true` (still held),
+ * `false` (a new holder took over → the channel must close), or `null`
+ * (indeterminate: not checked, or a D1 error — never a false "still yours").
  */
+export interface HeartbeatResult {
+  /** true on 2xx, false on any non-2xx / network error. */
+  ok: boolean;
+  /** Lease state from the server (#400): true=held, false=lost, null=indeterminate. */
+  leaseActive: boolean | null;
+}
+
 export async function sendInstanceHeartbeat(
   baseUrl: string,
   instanceId: string,
   instanceToken: string,
+  conversationId: string | null = null,
   timeoutMs = 20_000,
   fetchImpl: typeof fetch = fetch,
-): Promise<boolean> {
+): Promise<HeartbeatResult> {
   try {
     const resp = await fetchImpl(`${baseUrl}/api/instances/${instanceId}/heartbeat`, {
       method: "POST",
@@ -55,12 +67,22 @@ export async function sendInstanceHeartbeat(
         "Content-Type": "application/json",
         ...cfAccessHeaders(),
       },
-      body: "{}",
+      body: JSON.stringify(conversationId !== null ? { conversation_id: conversationId } : {}),
       signal: AbortSignal.timeout(timeoutMs),
     });
-    return resp.ok;
+    if (!resp.ok) return { ok: false, leaseActive: null };
+    let leaseActive: boolean | null = null;
+    try {
+      const body = (await resp.json()) as { lease_active?: boolean | null };
+      if (body.lease_active === true || body.lease_active === false) {
+        leaseActive = body.lease_active;
+      }
+    } catch {
+      // no/invalid body — leave indeterminate
+    }
+    return { ok: true, leaseActive };
   } catch {
-    return false;
+    return { ok: false, leaseActive: null };
   }
 }
 

package/lib/conversation.ts

@@ -40,6 +40,25 @@ export class ConversationMintError extends Error {
   }
 }
 
+/**
+ * #400 (recadrage) — an EXPLICIT `--conversation <id>` (VIBER_TARGET_CONVERSATION_ID)
+ * could not be loaded, and the operator asked for THAT conversation specifically:
+ * we must NOT invent a different one (that would recreate the very session clutter
+ * #400 removes). The channel catches this and exits cleanly (clear message,
+ * non-zero) — NEVER a fresh mint, never an uncaught stack trace. Distinct from
+ * name-resume, which is a heuristic allowed to fall back to a fresh mint.
+ */
+export class ExplicitTargetUnavailableError extends Error {
+  conversationId: string;
+  reason: string;
+  constructor(conversationId: string, reason: string) {
+    super(`Requested conversation ${conversationId} ${reason}`);
+    this.name = "ExplicitTargetUnavailableError";
+    this.conversationId = conversationId;
+    this.reason = reason;
+  }
+}
+
 export async function mintConversation(
   baseUrl: string,
   projectId: number,
@@ -121,13 +140,54 @@ export async function reattachConversation(
       }
       throw new ReattachFailedError(code);
     }
+    // Non-409 non-2xx (401 revoked, 503 lease-unavailable, other 5xx): throw a
+    // typed error carrying the status so the caller can react (401 → re-register;
+    // 5xx → explicit-target hard-fail / graceful fallback). #400 (recadrage).
     const detail = await resp.text();
-    throw new Error(`Failed to reattach conversation (HTTP ${resp.status}): ${detail}`);
+    throw new ConversationMintError(resp.status, detail);
   }
 
   return (await resp.json()) as ConversationMintResponse;
 }
 
+export interface ResumeCandidate {
+  conversation_id: string;
+  created_at: number;
+}
+
+/**
+ * GET /api/instances/resume-candidates?label=<name> (#400) — ask the server
+ * which channel-attached conversations carry `label` (the resume-by-name lookup
+ * for a named agent that lost its local handle). Auth: instance_token; the owner
+ * + project are derived server-side from the validated instance, so `label` is
+ * the only input. Returns the candidate list (may be empty). NEVER throws for an
+ * empty result — only for a real HTTP/network failure, which the caller treats
+ * as "no resume → mint".
+ */
+export async function resumeCandidatesByLabel(
+  baseUrl: string,
+  instanceToken: string,
+  fingerprint: string,
+  label: string,
+): Promise<ResumeCandidate[]> {
+  const resp = await fetch(
+    `${baseUrl}/api/instances/resume-candidates?label=${encodeURIComponent(label)}`,
+    {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${instanceToken}`,
+        "X-Client-Fingerprint": fingerprint,
+        ...cfAccessHeaders(),
+      },
+    },
+  );
+  if (!resp.ok) {
+    throw new Error(`resume-candidates lookup failed (HTTP ${resp.status})`);
+  }
+  const body = (await resp.json()) as { candidates?: ResumeCandidate[] };
+  return Array.isArray(body.candidates) ? body.candidates : [];
+}
+
 export interface RefreshTokenResponse {
   conversation_token: string;
   expires_at: number;
@@ -232,8 +292,14 @@ export function defaultLabel(folderPath: string): string {
 }
 
 /**
- * Default reattach window in seconds — matches the server's CONVERSATION_TTL_SECONDS.
- * A handle older than this points at an expired conversation that cannot be reattached.
+ * Legacy reattach window in seconds (kept for tests / explicit opt-in).
+ *
+ * NOTE (#400): this is NO LONGER the channel default. The server `handleReattach`
+ * reattaches a conversation of any age (only the token expires; the row persists),
+ * so the channel now defaults to an UNBOUNDED window (always attempt reattach) and
+ * only caps it when `VIBER_REATTACH_WINDOW_SECONDS` is set to a finite value. The
+ * old comment ("a handle older than this points at an expired conversation") was
+ * incorrect and was the reason a channel minted a fresh conversation after 1h.
  */
 export const DEFAULT_REATTACH_WINDOW_SECONDS = 3600;
 
@@ -268,8 +334,68 @@ export async function acquireConversation(
   targetConversationId?: string | null,
   reattachWindowSeconds: number = DEFAULT_REATTACH_WINDOW_SECONDS,
   log: (msg: string) => void = (msg) => process.stderr.write(msg),
+  /**
+   * #400 resume-by-name key: the conversation label a NAMED agent minted with
+   * (VIBER_CONVERSATION_LABEL). When non-null AND no local handle reattaches, the
+   * server is asked which channel-attached conversation carries this name; a
+   * UNIQUE match is reattached, 0/collision → mint. null (plain channel /
+   * timestamped label) disables the lookup. Last param so existing positional
+   * callers/tests (…, window, log) are unaffected.
+   */
+  resumeLabel: string | null = null,
+  /**
+   * #400 (recadrage) — EXPLICIT per-agent target conversation id (env
+   * `VIBER_TARGET_CONVERSATION_ID`, injected by vibe-master `spawn --conversation`).
+   * HIGHEST priority: bind THIS conversation by id. On success → use it. On ANY
+   * failure (conversation_in_use / revoked-or-missing / 5xx server-unavailable) →
+   * HARD FAIL via ExplicitTargetUnavailableError (the channel exits cleanly): NO
+   * mint, NO heuristic fallback — the operator asked for a SPECIFIC conversation,
+   * so inventing a different one would recreate the clutter #400 removes. A 401
+   * (token revoked) still propagates so the outer loop re-registers. (Contrast:
+   * name-resume is a heuristic allowed to mint gracefully on failure.) Last param
+   * → existing positional callers unaffected.
+   */
+  envTargetConversationId: string | null = null,
 ): Promise<ConversationMintResponse> {
   const nowSeconds = Math.floor(Date.now() / 1000);
+
+  // #400 (recadrage) — EXPLICIT per-agent target wins over every heuristic AND
+  // never invents a different conversation. The operator asked for THIS id: bind
+  // it, or FAIL cleanly (no fresh mint — that would recreate the clutter #400
+  // removes). A 401 still propagates so the outer loop re-registers.
+  if (envTargetConversationId !== null) {
+    log(`[viber-channel] startup: explicit target ${envTargetConversationId} (VIBER_TARGET_CONVERSATION_ID), attempting reattach\n`);
+    try {
+      const result = await reattachConversation(baseUrl, projectId, instanceToken, fingerprint, envTargetConversationId);
+      log(`[viber-channel] startup: explicit-target reattach OK, conv_id=${result.conversation_id}\n`);
+      try {
+        writeHandle(sessionPath, result.conversation_id);
+      } catch (writeErr) {
+        log(`[viber-channel] Warning: failed to write session handle after explicit-target reattach: ${String(writeErr)}\n`);
+      }
+      return result;
+    } catch (err) {
+      // 401 (token revoked) → let the outer handler re-register and retry.
+      if (err instanceof ConversationMintError && err.status === 401) throw err;
+      let reason: string;
+      if (err instanceof ReattachFailedError) {
+        reason =
+          err.code === "conversation_in_use"
+            ? "is already in use by a live agent"
+            : err.code === "reattach_revoked" || err.code === "reattach_not_found"
+              ? "was revoked or no longer exists"
+              : `could not be reattached (${err.code})`;
+      } else if (err instanceof ConversationMintError && err.status >= 500) {
+        reason = "could not be verified — the server was unavailable (try again)";
+      } else {
+        reason = `could not be loaded (${String(err)})`;
+      }
+      // HARD FAIL — no mint, no heuristic fallback. The channel catches this and
+      // exits cleanly with a clear message (never a fresh conversation).
+      throw new ExplicitTargetUnavailableError(envTargetConversationId, reason);
+    }
+  }
+
   const handle = readHandle(sessionPath);
 
   // Branch on `handle` directly so TS narrows it to non-null inside — readHandle
@@ -292,10 +418,13 @@ export async function acquireConversation(
       } catch (err) {
         // Reattach failure is NEVER fatal. Everything (ReattachFailedError 409,
         // unexpected 5xx, network errors from a thrown fetch) falls through to
-        // mint below, which surfaces a 401 to the caller if the token is dead.
+        // the resume-by-name lookup then mint below (which surfaces a 401 to the
+        // caller if the token is dead). A 409 (handle points at a dead/revoked
+        // conv) is the realistic case: resume-by-name then finds the LIVE conv of
+        // the same name instead of minting.
         const reason = err instanceof ReattachFailedError ? err.code : String(err);
-        log(`[viber-channel] startup: reattach failed (${reason}), falling back to mint\n`);
-        // Fall through to mint below
+        log(`[viber-channel] startup: reattach failed (${reason}), falling back to resume-by-name / mint\n`);
+        // Fall through to resume-by-name / mint below
       }
     } else {
       log(`[viber-channel] startup: session handle stale (conv_id=${handle.conversation_id}, age=${handleAge}s >= ${reattachWindowSeconds}s window), minting fresh\n`);
@@ -304,8 +433,72 @@ export async function acquireConversation(
     log(`[viber-channel] startup: no session handle found, minting fresh\n`);
   }
 
-  // Mint a new conversation
-  const result = await mintConversation(baseUrl, projectId, instanceToken, fingerprint, label, targetConversationId ?? null);
+  // #400 resume-by-name (handle-absent path): a named agent re-registers a fresh
+  // instance_id each start, so on a new machine / cleared tmp / MCP reconnect the
+  // handle above is missing. Ask the server which channel-attached conversation
+  // carries this name; a UNIQUE match is reattached (reuse instead of mint), a
+  // collision (≥2) or no match falls through to mint — never guess. Lookup
+  // failure is non-fatal → mint.
+  if (resumeLabel !== null) {
+    try {
+      const candidates = await resumeCandidatesByLabel(baseUrl, instanceToken, fingerprint, resumeLabel);
+      if (candidates.length === 1) {
+        const targetId = candidates[0].conversation_id;
+        log(`[viber-channel] startup: resume-by-name "${resumeLabel}" → unique match ${targetId}, attempting reattach\n`);
+        try {
+          const result = await reattachConversation(baseUrl, projectId, instanceToken, fingerprint, targetId);
+          log(`[viber-channel] startup: resume-by-name reattach OK, conv_id=${result.conversation_id}\n`);
+          try {
+            writeHandle(sessionPath, result.conversation_id);
+          } catch (writeErr) {
+            log(`[viber-channel] Warning: failed to write session handle after resume-by-name reattach: ${String(writeErr)}\n`);
+          }
+          return result;
+        } catch (err) {
+          const reason = err instanceof ReattachFailedError ? err.code : String(err);
+          log(`[viber-channel] startup: resume-by-name reattach failed (${reason}), minting fresh\n`);
+        }
+      } else if (candidates.length > 1) {
+        const ids = candidates.map((c) => c.conversation_id).join(", ");
+        log(`[viber-channel] startup: resume-by-name "${resumeLabel}" → label collision (${candidates.length} candidates: ${ids}), minting fresh\n`);
+      } else {
+        log(`[viber-channel] startup: resume-by-name "${resumeLabel}" → no match, minting fresh\n`);
+      }
+    } catch (err) {
+      log(`[viber-channel] startup: resume-by-name lookup failed (${String(err)}), minting fresh\n`);
+    }
+  }
+
+  // Mint a new conversation.
+  //
+  // #400 sticky-target safety: target_conversation_id in auth.json is STICKY
+  // (written once by the reconnect/attach flow, never cleared — connect.ts). When
+  // that target is later REVOKED (e.g. by the #400 batch cleanup, or unit
+  // revocation), the server routes target → handleReattach → 409 reattach_revoked
+  // / reattach_not_found, and mintConversation throws ConversationMintError. Since
+  // viber-channel.ts only catches 401 (re-register), an un-tolerated 409 here
+  // would CRASH startup — and the two #400 features (reconnect + cleanup) combine
+  // to make it reachable. So: on a 409 from the TARGET path, fall back to a fresh
+  // mint WITHOUT the (dead) target. A 401 still propagates (token revoked →
+  // caller re-registers); other errors still propagate.
+  let result: ConversationMintResponse;
+  try {
+    result = await mintConversation(baseUrl, projectId, instanceToken, fingerprint, label, targetConversationId ?? null);
+  } catch (err) {
+    if (
+      targetConversationId != null &&
+      err instanceof ConversationMintError &&
+      (err.status === 409 || err.status >= 500)
+    ) {
+      // 409 = dead/revoked/in-use target; 5xx = transient server/lease fault. The
+      // auth.json target is a STICKY folder-level hint (not an explicit operator
+      // request), so a graceful fresh mint is correct — never crash on it (Opus).
+      log(`[viber-channel] startup: sticky target ${targetConversationId} not reattachable (${err.message}), minting fresh without target\n`);
+      result = await mintConversation(baseUrl, projectId, instanceToken, fingerprint, label, null);
+    } else {
+      throw err;
+    }
+  }
   log(`[viber-channel] startup: mint OK, conv_id=${result.conversation_id}\n`);
   try {
     writeHandle(sessionPath, result.conversation_id);

package/lib/heartbeat.ts

@@ -13,10 +13,18 @@
  * was removed in #315 once "Active" derived from instance liveness.)
  */
 
-import { sendInstanceHeartbeat } from "./control_stream.ts";
+import { type HeartbeatResult, sendInstanceHeartbeat } from "./control_stream.ts";
 
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
 
+/**
+ * #400 (recadrage) — consecutive INDETERMINATE lease beats tolerated before the
+ * channel closes. A definite `lease_active:false` closes immediately; `null`
+ * (D1 error / no body) is tolerated up to this many beats so a transient fault
+ * doesn't kill a live agent, then we close (the margin Codex asked for).
+ */
+export const DEFAULT_MAX_INDETERMINATE_LEASE_BEATS = 3;
+
 /**
  * Resolve the beat interval from the environment (seconds), defaulting to 25s.
  * Must stay comfortably under the server timeout (VIBER_CHANNEL_PRESENCE_TIMEOUT,
@@ -44,8 +52,26 @@ export interface InstanceHeartbeatOptions {
   log?: (line: string) => void;
   setTimer?: (fn: () => void, ms: number) => unknown;
   clearTimer?: (handle: unknown) => void;
+  /**
+   * #400 — the conversation this agent is attached to, read each tick so the beat
+   * renews its lease. null (plain channel / not yet bound) → no lease renewal.
+   */
+  getConversationId?: () => string | null;
+  /**
+   * #400 — called when the agent has DEFINITELY lost its conversation lease
+   * (a new holder took over, or too many consecutive indeterminate beats). The
+   * channel closes to avoid two live agents on one conversation.
+   */
+  onLeaseLost?: () => void;
+  /** Consecutive indeterminate beats tolerated before closing (default 3). */
+  maxIndeterminateLeaseBeats?: number;
   /** Injectable beat fn for tests. Defaults to sendInstanceHeartbeat. */
-  beat?: (baseUrl: string, instanceId: string, instanceToken: string) => Promise<boolean>;
+  beat?: (
+    baseUrl: string,
+    instanceId: string,
+    instanceToken: string,
+    conversationId: string | null,
+  ) => Promise<HeartbeatResult>;
 }
 
 /**
@@ -64,15 +90,41 @@ export function startInstanceHeartbeat(opts: InstanceHeartbeatOptions): Heartbea
     opts.clearTimer ??
     ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>));
   const beat = opts.beat ?? sendInstanceHeartbeat;
+  const getConversationId = opts.getConversationId ?? (() => null);
+  const maxIndeterminate =
+    opts.maxIndeterminateLeaseBeats ?? DEFAULT_MAX_INDETERMINATE_LEASE_BEATS;
 
   let inFlight = false;
+  let indeterminateStreak = 0;
+  let leaseLostFired = false;
+  const fireLeaseLost = (why: string) => {
+    if (leaseLostFired) return;
+    leaseLostFired = true;
+    log(`[viber-channel] conversation lease lost (${why}) — closing channel\n`);
+    opts.onLeaseLost?.();
+  };
+
   const handle = setTimer(() => {
     if (inFlight) return;
     inFlight = true;
-    void beat(opts.baseUrl, opts.instanceId, opts.getInstanceToken())
-      .then((ok) => {
-        if (!ok) {
+    const conversationId = getConversationId();
+    void beat(opts.baseUrl, opts.instanceId, opts.getInstanceToken(), conversationId)
+      .then((result) => {
+        if (!result.ok) {
           log("[viber-channel] instance heartbeat failed (will retry next interval)\n");
+          return; // a failed beat never reached the server — not a lease signal
+        }
+        // #400 lease state — only meaningful when we asked about a conversation.
+        if (conversationId === null) return;
+        if (result.leaseActive === false) {
+          fireLeaseLost("a new holder took over");
+        } else if (result.leaseActive === null) {
+          indeterminateStreak += 1;
+          if (indeterminateStreak >= maxIndeterminate) {
+            fireLeaseLost(`${indeterminateStreak} consecutive indeterminate beats`);
+          }
+        } else {
+          indeterminateStreak = 0; // true → still ours, reset the margin
         }
       })
       .finally(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
   "type": "module",
   "bin": {

package/viber-channel.ts

@@ -31,13 +31,13 @@ import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { runConnect } from "./lib/connect.ts";
 import { lockFilePath, lockSessionId } from "./lib/lockfile.ts";
-import { sessionFilePath, clearHandle } from "./lib/channel_session.ts";
+import { resolveSessionFilePath, namedAgentLabel, 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,
+  ExplicitTargetUnavailableError,
   type ConversationMintResponse,
 } from "./lib/conversation.ts";
 import { startInstanceHeartbeat } from "./lib/heartbeat.ts";
@@ -169,22 +169,28 @@ const LOCK_FILE = lockFilePath(LOCK_BASE_URL, LOCK_FINGERPRINT, LOCK_SESSION_ID,
 // 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.
-// Parsed once, mirroring the VIBER_REFRESH_LEAD_SECONDS pattern below: validate
-// finite && >= 0, log invalid→ignore, log override, fall back to the default.
+// Reattach window (#400): NEUTRALISED BY DEFAULT. The server `handleReattach`
+// is the contract of truth — it reattaches any non-revoked channel conversation
+// of the right owner/project REGARDLESS OF AGE (only the token expires, the row
+// persists). The old 1h default (DEFAULT_REATTACH_WINDOW_SECONDS) was a purely
+// client-side guard whose "stale handle points at an expired conversation"
+// rationale is FALSE per the server code, and it was the reason a channel minted
+// a fresh conversation after 1h instead of reattaching. Default is now
+// unbounded (Infinity) → always attempt reattach when a handle exists; the
+// server rejects (409) if the conversation is genuinely gone → fall back to mint.
+// VIBER_REATTACH_WINDOW_SECONDS still caps the window if a finite value is set.
 const REATTACH_WINDOW_SECONDS: number = (() => {
   const raw = process.env.VIBER_REATTACH_WINDOW_SECONDS;
-  if (raw === undefined) return DEFAULT_REATTACH_WINDOW_SECONDS;
+  if (raw === undefined) return Number.POSITIVE_INFINITY;
   const parsed = Number.parseInt(raw, 10);
   if (!Number.isFinite(parsed) || parsed < 0) {
     process.stderr.write(
-      `[viber-channel] Invalid VIBER_REATTACH_WINDOW_SECONDS=${raw}, ignoring.\n`
+      `[viber-channel] Invalid VIBER_REATTACH_WINDOW_SECONDS=${raw}, ignoring (window unbounded).\n`
     );
-    return DEFAULT_REATTACH_WINDOW_SECONDS;
+    return Number.POSITIVE_INFINITY;
   }
   process.stderr.write(
-    `[viber-channel] reattach window overridden to ${parsed}s via VIBER_REATTACH_WINDOW_SECONDS\n`
+    `[viber-channel] reattach window capped to ${parsed}s via VIBER_REATTACH_WINDOW_SECONDS\n`
   );
   return parsed;
 })();
@@ -659,14 +665,60 @@ try {
   // 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`);
+  // #400: a NAMED agent (VIBER_CHANNEL_LABEL, no env-injected VIBER_INSTANCE_TOKEN)
+  // re-registers a FRESH instance_id on every start (acquireInstance path 2), so
+  // namespacing the handle by instance_id never finds it on the next start → mint
+  // loop. resolveSessionFilePath keys such an agent by the STABLE NAME (project-
+  // scoped) so a re-spawn / MCP reconnect reattaches its previous conversation;
+  // the plain channel (or a path-1 injected token) keeps the instance_id key —
+  // #269 isolation. Selection logic lives in the pure helper (unit-tested).
+  const computeSessionFile = (instanceKey: string): string =>
+    resolveSessionFilePath({
+      baseUrl: LOCK_BASE_URL,
+      projectId: auth.project_id,
+      channelLabel: process.env.VIBER_CHANNEL_LABEL,
+      instanceToken: process.env.VIBER_INSTANCE_TOKEN,
+      instanceKey,
+      dir: LOCK_DIR,
+    });
+  SESSION_FILE = computeSessionFile(acquired.instance_key);
+
+  // #400 resume-by-name lookup key: EXACTLY the label the mint writes into
+  // conversations.label, i.e. VIBER_CONVERSATION_LABEL (see `label` above:
+  // `VIBER_CONVERSATION_LABEL ?? defaultLabel(cwd)`). Only meaningful when it is
+  // explicitly set AND this is a named agent — otherwise the mint uses the
+  // timestamped defaultLabel, which is NOT resumable, so the lookup is disabled
+  // (null). No VIBER_CHANNEL_LABEL fallback: that would query a value the mint
+  // never wrote (Opus review B — query exactly what the mint writes).
+  const namedSession = namedAgentLabel(process.env.VIBER_CHANNEL_LABEL, process.env.VIBER_INSTANCE_TOKEN) !== null;
+  const explicitConvLabel = process.env.VIBER_CONVERSATION_LABEL?.trim();
+  const RESUME_LABEL: string | null = namedSession && explicitConvLabel ? explicitConvLabel : null;
+
+  // #400 (recadrage) — EXPLICIT per-agent target conversation, injected by
+  // vibe-master `spawn --conversation <id>` / the TUI "load" picker. Highest
+  // priority in acquireConversation: bind THIS conversation by id (never via the
+  // shared folder auth.json). null when not spawned onto a specific conversation.
+  const ENV_TARGET_CONVERSATION_ID = process.env.VIBER_TARGET_CONVERSATION_ID?.trim() || null;
+
+  process.stderr.write(`[viber-channel] startup: acquiring conversation (project=${auth.project_id}, target=${auth.target_conversation_id ?? "null"}, session=${SESSION_FILE}, resume_label=${RESUME_LABEL ?? "none"})\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.
+  // #400 (recadrage): an explicit `--conversation <id>` that can't be loaded is a
+  // CLEAN, non-zero exit with a readable message — never a fresh conversation,
+  // never an uncaught stack trace.
+  const exitExplicitTargetUnavailable = (err: ExplicitTargetUnavailableError): never => {
+    process.stderr.write(
+      `[viber-channel] cannot load requested conversation ${err.conversationId}: ${err.reason}. Agent NOT started.\n`,
+    );
+    scheduler?.cancel();
+    releaseLock();
+    process.exit(1);
+  };
+
   let minted: ConversationMintResponse;
   try {
     minted = await acquireConversation(
@@ -678,8 +730,14 @@ try {
       label,
       auth.target_conversation_id ?? null,
       REATTACH_WINDOW_SECONDS,
+      undefined, // log — use the default stderr writer
+      RESUME_LABEL,
+      ENV_TARGET_CONVERSATION_ID,
     );
   } catch (err) {
+    if (err instanceof ExplicitTargetUnavailableError) {
+      exitExplicitTargetUnavailable(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`,
@@ -695,17 +753,30 @@ try {
       OWN_INSTANCE_ID = reg.instance_id;
       // #398: re-attach the fresh (post-revocation) instance to its team.
       await maybeAttachTeam(BASE_URL, auth.project_id, auth.project_token, auth.client_fingerprint, 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,
-      );
+      // #400: keep the SAME namespacing rule after a post-revocation re-register.
+      // A named agent stays keyed by its stable name (not the new instance_id),
+      // so its handle survives; the plain channel re-keys to the fresh id.
+      SESSION_FILE = computeSessionFile(reg.instance_id);
+      try {
+        minted = await acquireConversation(
+          SESSION_FILE,
+          BASE_URL,
+          auth.project_id,
+          instanceToken,
+          auth.client_fingerprint,
+          label,
+          auth.target_conversation_id ?? null,
+          REATTACH_WINDOW_SECONDS,
+          undefined, // log — use the default stderr writer
+          RESUME_LABEL,
+          ENV_TARGET_CONVERSATION_ID,
+        );
+      } catch (retryErr) {
+        if (retryErr instanceof ExplicitTargetUnavailableError) {
+          exitExplicitTargetUnavailable(retryErr);
+        }
+        throw retryErr;
+      }
     } else {
       throw err;
     }
@@ -754,6 +825,16 @@ try {
       baseUrl: BASE_URL,
       instanceId: OWN_INSTANCE_ID,
       getInstanceToken: () => INSTANCE_TOKEN,
+      // #400 (recadrage): renew this agent's conversation lease each beat. If the
+      // server reports the lease was taken over (a new holder), or too many
+      // consecutive indeterminate beats, close the channel — never stay a second
+      // live agent on a conversation another agent now owns.
+      getConversationId: () => CONVERSATION_ID || null,
+      onLeaseLost: () => {
+        scheduler?.cancel();
+        releaseLock();
+        process.exit(0);
+      },
     });
     // Stop beating once the control stream ends (revoke / 401 / abort) so a
     // doomed instance doesn't keep beating (Opus review).

package/viber-codex-bridge.ts

@@ -7,6 +7,7 @@
  * Codex's final assistant reply back into Viber.
  */
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { authFilePath, loadAuth } from "./lib/auth.ts";
@@ -242,33 +243,81 @@ function buildReply(receivedContent: string, msg: ConversationMessage | undefine
 // the shared runConversationStream now owns token refresh, so the bridge no
 // longer wires it directly.
 
-// #280 step-12: the state file is per AGENT. Several agents on one machine each own
-// their own file, so concurrent read-modify-write of a single shared JSON can't drop
-// another agent's thread entry (Codex review P2-A). An explicit
-// VIBER_CODEX_BRIDGE_STATE override still wins (single file, caller's responsibility).
-function stateFilePath(instanceId?: string, cwd: string = process.cwd()): string {
+// #409: monotonic (perf) timing for diagnosing codex spawn / first-response
+// latency. Structured, greppable `timing:` lines — the user's "codex is slow" is
+// largely INHERENT (app-server initialize + first model turn), so we MEASURE where
+// the time goes rather than guess. NOT a behaviour change.
+const nowMs = (): number => performance.now();
+// #409 (Codex): classify a conversation's turn as first vs subsequent and RESERVE
+// the "first" label atomically (before any await), so two near-simultaneous
+// messages can't both be logged `which=first`. Pure/testable.
+export function classifyTurn(
+  seen: Set<string>,
+  convId: string,
+): "first" | "subsequent" {
+  if (seen.has(convId)) return "subsequent";
+  seen.add(convId);
+  return "first";
+}
+function logTiming(phase: string, ms: number, extra = ""): void {
+  process.stderr.write(
+    `[viber-codex-bridge] timing: ${phase} ms=${Math.round(ms)}${extra ? ` ${extra}` : ""}\n`,
+  );
+}
+
+// #414: the persistent thread identity. #280 keyed the thread by the server-issued
+// instanceId so multiple agents sharing one conversation each get their own Codex
+// thread — but the instanceId is FRESH on every register (#269), so a same-name
+// re-spawn never found its predecessor's thread (thread/start instead of resume,
+// runtime memory lost). Fix: when an EXPLICIT VIBER_CODEX_BRIDGE_LABEL is set (the
+// stable logical name — vibe-master always sets it to the agent id), key by
+// sha256(label) so a re-spawn under the same name resumes; distinct labels stay
+// isolated (#280 preserved). No explicit label → fall back to the instanceId (no
+// resume, but #280 isolation kept — the DEFAULT `Codex bridge • <cwd>` label is NOT
+// a unique identity, and an empty label must never collapse everyone onto
+// hash("")). The hash is filename-safe (hex) and doesn't leak the label.
+export function threadIdentity(
+  instanceId: string,
+  label: string | undefined,
+): { key: string; fileSuffix: string } {
+  const trimmed = label?.trim();
+  if (trimmed) {
+    const h = createHash("sha256").update(trimmed, "utf8").digest("hex");
+    return { key: `label:${h}`, fileSuffix: `label-${h}` };
+  }
+  return { key: `instance:${instanceId}`, fileSuffix: `instance-${instanceId}` };
+}
+
+// #280 step-12 / #414: the state file is per AGENT IDENTITY (stable label when set,
+// else instanceId). It lives in the workspace's `.viber` dir (per-folder), so two
+// folders — even a cross-project #307 pair using the same explicit label — write
+// DIFFERENT files; the fingerprint in stateKey is defence-in-depth. Concurrent RMW
+// of one file across agents can't drop another's entry (distinct identities →
+// distinct files). An explicit VIBER_CODEX_BRIDGE_STATE override still wins.
+function stateFilePath(
+  instanceId: string,
+  label: string | undefined,
+  cwd: string = process.cwd(),
+): string {
   const override = process.env.VIBER_CODEX_BRIDGE_STATE;
   if (override !== undefined && override.trim() !== "") return override;
-  // Full instance id in the filename (server-issued opaque hex): a truncated id
-  // could collide and reintroduce the shared-file write race this split avoids.
-  const name =
-    instanceId && instanceId.trim() !== ""
-      ? `codex-bridge-threads-${instanceId}.json`
-      : "codex-bridge-threads.json";
-  return join(dirname(authFilePath(cwd)), name);
+  const { fileSuffix } = threadIdentity(instanceId, label);
+  return join(dirname(authFilePath(cwd)), `codex-bridge-threads-${fileSuffix}.json`);
 }
 
-// #280 step-12: the key is per (conversation, AGENT), not per conversation. With
-// several agents sharing one conversation, a conversation-only key would make them
-// resume/clobber the same Codex thread. Including the instance id gives each agent
-// its own persisted thread.
+// #280/#414: the key is per (project, folder, conversation, AGENT IDENTITY). The
+// conversationId is KEPT (a same agent on TWO conversations must not share one
+// runtime thread — cross-conversation contamination); the fingerprint scopes it
+// per folder; the identity is the stable label (or instanceId fallback).
 export function stateKey(
   projectId: number,
   fingerprint: string,
   conversationId: string,
   instanceId: string,
+  label: string | undefined,
 ): string {
-  return `${projectId}:${fingerprint}:${conversationId}:${instanceId}`;
+  const { key } = threadIdentity(instanceId, label);
+  return `${projectId}:${fingerprint}:${conversationId}:${key}`;
 }
 
 function readThreadState(path: string): ThreadState {
@@ -584,11 +633,13 @@ class CodexAppServer {
   }
 
   async initialize(): Promise<void> {
+    const t0 = nowMs(); // #409: measure the app-server init (a big share of spawn latency)
     await this.request("initialize", {
       clientInfo: { name: "viber-codex-bridge", title: "Viber Codex Bridge", version: "0.1.0" },
       capabilities: { experimentalApi: true },
     });
     this.notify("initialized");
+    logTiming("codex.initialize", nowMs() - t0);
   }
 
   async ensureThread(options: {
@@ -598,18 +649,25 @@ class CodexAppServer {
     instanceKey: string;
     newThread: boolean;
   }): Promise<string> {
-    const path = stateFilePath(options.instanceKey);
+    // #414: prefer the STABLE explicit label over the fresh instanceId so a
+    // same-name re-spawn resumes its own thread (see threadIdentity).
+    const label = process.env.VIBER_CODEX_BRIDGE_LABEL;
+    const path = stateFilePath(options.instanceKey, label);
     const state = readThreadState(path);
     const key = stateKey(
       options.auth.project_id,
       options.fingerprint,
       options.conversationId,
       options.instanceKey,
+      label,
     );
     const existing = state.threads[key]?.thread_id;
+    const t0 = nowMs(); // #409: measure thread resume/start (the first-DM cost)
+    let resumeAttempted = false;
 
     if (existing && !options.newThread) {
       try {
+        resumeAttempted = true;
         process.stderr.write(`[viber-codex-bridge] codex: resuming persisted thread ${existing}\n`);
         const resumed = await this.request("thread/resume", {
           threadId: existing,
@@ -620,7 +678,11 @@ class CodexAppServer {
           developerInstructions: AGENT_INSTRUCTIONS,
           excludeTurns: true,
         });
-        return extractThreadId(resumed);
+        // #409 (Codex): validate/extract the id BEFORE logging success — a malformed
+        // response must NOT be logged as resume then again as resume-failed→start.
+        const resumedId = extractThreadId(resumed);
+        logTiming("ensureThread", nowMs() - t0, "outcome=resume");
+        return resumedId;
       } catch (err) {
         process.stderr.write(
           `[viber-codex-bridge] codex: resume failed (${safeErrorMessage(err)}), starting a fresh thread\n`,
@@ -651,6 +713,11 @@ class CodexAppServer {
     };
     writeThreadState(path, state);
     process.stderr.write(`[viber-codex-bridge] codex: persisted thread ${threadId} in ${path}\n`);
+    logTiming(
+      "ensureThread",
+      nowMs() - t0,
+      `outcome=${resumeAttempted ? "resume-failed→start" : "start"}`,
+    );
     return threadId;
   }
 
@@ -1166,9 +1233,15 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
 
   // codex's per-conversation adapter for the shared runConversationStream:
   // ensureThread (keyed by conversation+agent) then the tracked, queued codex turn.
+  // #409: which conversations have already run their FIRST model turn, so we can
+  // report the (expensive) first turn distinctly from the fast subsequent ones.
+  const firstTurnDone = new Set<string>();
   const makeCodexAdapter = (codex: CodexAppServer, instanceKey: string): MakeRunTurn =>
     async (convId, runtime) => {
+      // #409: time join → thread ready (the eager ensureThread on a fresh join).
+      const tJoin = nowMs();
       let threadPromise = threadCache.get(convId);
+      const cached = threadPromise !== undefined;
       if (!threadPromise) {
         threadPromise = codex
           .ensureThread({ auth, fingerprint, conversationId: convId, instanceKey, newThread: options.newThread })
@@ -1179,8 +1252,22 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
         threadCache.set(convId, threadPromise);
       }
       const codexThreadId = await threadPromise;
+      if (!cached) logTiming("join→thread-ready", nowMs() - tJoin, `conv=${convId.slice(0, 8)}`);
       process.stderr.write(`${LOG_PREFIX} codex thread ready for ${convId} (thread ${codexThreadId})\n`);
-      return makeCodexRunTurn(codex, codexThreadId, runtime, options, queue, tracker);
+      const runTurn = makeCodexRunTurn(codex, codexThreadId, runtime, options, queue, tracker);
+      // #409: wrap to measure the FIRST model turn (cold: the biggest perceived
+      // latency) apart from subsequent turns. Pure instrumentation, same behaviour.
+      return async (content, msg, signal) => {
+        // #409 (Codex): reserve first/subsequent BEFORE the await so concurrent
+        // turns can't both be classified `first`.
+        const which = classifyTurn(firstTurnDone, convId);
+        const tTurn = nowMs();
+        try {
+          return await runTurn(content, msg, signal);
+        } finally {
+          logTiming("turn", nowMs() - tTurn, `which=${which} conv=${convId.slice(0, 8)}`);
+        }
+      };
     };
 
   if (options.awaitInvite) {
@@ -1259,10 +1346,20 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
     logCodexSafety();
     process.stderr.write(`${LOG_PREFIX} ready: joined ${res.minted.conversation_id} as instance ${res.instanceKey.slice(0, 8)}\n`);
     // #315: no control stream here, so beat the instance liveness directly.
+    // #400 (recadrage): this bridge holds a lease on its ONE joined conversation
+    // (acquired via reattachConversation → handleReattach). RENEW it each beat, or
+    // it expires after the TTL while the agent is alive and the conversation
+    // falsely frees → another agent could load onto it. On a definite loss (a new
+    // holder took over), shut down so we never double-attach.
     const ihb = startInstanceHeartbeat({
       baseUrl: BASE_URL,
       instanceId: res.instanceKey,
       getInstanceToken: () => res.instanceToken,
+      getConversationId: () => res.minted.conversation_id,
+      onLeaseLost: () =>
+        shutdown.abort(
+          new BridgeShutdownError("conversation lease lost (taken over)", 0),
+        ),
     });
     shutdown.signal.addEventListener("abort", () => ihb.stop(), { once: true });
     try {