viber-channel 0.8.3 → 0.8.5

package/lib/auth.ts

@@ -33,21 +33,38 @@ export interface AuthJson {
   instance_id?: string;
 }
 
+/**
+ * The environment signal — SINGLE source of truth for every env-dependent
+ * behavior in the channel (auth file, agent-session yield, …). The DEV backend
+ * is the only non-default: anything else (unset / staging / prod) uses the
+ * STAGING defaults, so a missing or ambiguous signal can never accidentally
+ * pull dev behavior into staging. Derived from `VIBER_BASE_URL`, which the
+ * launcher always sets per env.
+ */
+export function isDevBackend(
+  baseUrl: string = process.env.VIBER_BASE_URL ?? "",
+): boolean {
+  return baseUrl.includes("viber-dev");
+}
+
 /**
  * Resolve the auth file path.
  *
- * Defaults to `<cwd>/.viber/auth.json`. The optional `VIBER_AUTH_FILE` env var
- * overrides it — absolute paths are used verbatim, relative paths are resolved
- * against `cwd`. This lets a local launcher point the channel at an alternate
- * credential file (e.g. `.viber/dev.auth.json`) WITHOUT swapping `auth.json`,
- * so the default consumer flow (env var unset) is completely unaffected.
+ * The optional `VIBER_AUTH_FILE` env var overrides everything — absolute paths
+ * verbatim, relative paths resolved against `cwd`. With no override the file is
+ * DERIVED from the environment (single source of truth, {@link isDevBackend}):
+ * the dev backend uses `.viber/dev.auth.json`, everything else defaults to
+ * `.viber/auth.json` (staging). This kills the class of bugs where a dev channel
+ * silently authenticated against the dev backend with STAGING creds (`-32000`)
+ * because only `VIBER_BASE_URL` was set and the auth file defaulted to staging.
  */
 export function authFilePath(cwd: string = process.cwd()): string {
   const override = process.env.VIBER_AUTH_FILE;
   if (override !== undefined && override.trim() !== "") {
     return isAbsolute(override) ? override : join(cwd, override);
   }
-  return join(cwd, ".viber", "auth.json");
+  const file = isDevBackend() ? "dev.auth.json" : "auth.json";
+  return join(cwd, ".viber", file);
 }
 
 export function loadAuth(cwd: string = process.cwd()): AuthJson {

package/lib/bridge_core.ts

@@ -27,7 +27,7 @@ import { buildSseUrl } from "./urls.js";
 import { cfAccessHeaders } from "./cfAccess.js";
 import { sessionFilePath, writeHandle } from "./channel_session.js";
 import type { AuthJson } from "./auth.js";
-import { acquireInstance, registerInstance, instanceKindFromEnv, type AcquiredInstance } from "./instance.js";
+import { acquireInstance, registerInstance, instanceKindFromEnv, maybeAttachTeam, type AcquiredInstance } from "./instance.js";
 import {
 	runPersistentControlStream,
 	sendInstanceHeartbeat,
@@ -897,6 +897,9 @@ export async function acquireBridgeInstance(opts: {
 	process.stderr.write(`${logPrefix} instance: registering fresh bridge instance\n`);
 	const reg = await registerInstance(baseUrl, auth.project_id, auth.project_token, fingerprint, label, instanceKindFromEnv() ?? kind);
 	process.stderr.write(`${logPrefix} instance: registered fresh bridge instance (id=${reg.instance_id})\n`);
+	// #398: best-effort self-attach to VIBER_INSTANCE_TEAM (codex/gemma path; the
+	// two branches above go through acquireInstance which already self-attaches).
+	await maybeAttachTeam(baseUrl, auth.project_id, auth.project_token, fingerprint, reg.instance_id, (m) => process.stderr.write(m));
 	return { instance_token: reg.instance_token, instance_key: reg.instance_id };
 }
 

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/lib/instance.ts

@@ -76,6 +76,77 @@ export function instanceKindFromEnv(): string | undefined {
   return raw !== undefined && raw.trim() !== "" ? raw.trim() : undefined;
 }
 
+/**
+ * The DB-backed team this process should join (#398), from `VIBER_INSTANCE_TEAM`
+ * (set by the spawn path — vibe-master's agent_spec). undefined when unset → the
+ * agent joins no team. Mirrors `instanceKindFromEnv`.
+ */
+export function instanceTeamFromEnv(): string | undefined {
+  const raw = process.env.VIBER_INSTANCE_TEAM;
+  return raw !== undefined && raw.trim() !== "" ? raw.trim() : undefined;
+}
+
+/**
+ * POST /api/projects/:id/teams/members — attach this instance to a team by name
+ * (#398). A SEPARATE authorized call AFTER register (the register payload never
+ * carries a client-declared team — same discipline as the orchestrator flag).
+ * Team is project-scoped metadata; the worker upserts it and verifies the
+ * instance belongs to the token's project. Throws InstanceRegisterError on !ok.
+ */
+export async function attachInstanceTeam(
+  baseUrl: string,
+  projectId: number,
+  projectToken: string,
+  fingerprint: string,
+  instanceId: string,
+  team: string,
+): Promise<void> {
+  const resp = await fetch(
+    `${baseUrl}/api/projects/${projectId}/teams/members`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${projectToken}`,
+        "X-Client-Fingerprint": fingerprint,
+        "Content-Type": "application/json",
+        ...cfAccessHeaders(),
+      },
+      body: JSON.stringify({ team, instance_id: instanceId }),
+    },
+  );
+  if (!resp.ok) {
+    const detail = await resp.text().catch(() => "");
+    throw new InstanceRegisterError(resp.status, detail);
+  }
+}
+
+/**
+ * Best-effort self-attach to `VIBER_INSTANCE_TEAM`, run AFTER a successful
+ * register/acquire (#398, R-CLAUDE: called from BOTH acquireInstance — claude/
+ * plain — and acquireBridgeInstance — codex/gemma). No-op when no team is
+ * requested or no server instance_id is known. A failure (legacy worker 404,
+ * validation, network) is logged and swallowed — the agent still works,
+ * un-teamed (forward-compatible). NOT retried.
+ */
+export async function maybeAttachTeam(
+  baseUrl: string,
+  projectId: number,
+  projectToken: string,
+  fingerprint: string,
+  instanceId: string | undefined,
+  log: (msg: string) => void = (m) => process.stderr.write(m),
+): Promise<void> {
+  const team = instanceTeamFromEnv();
+  if (team === undefined || instanceId === undefined) return;
+  try {
+    await attachInstanceTeam(baseUrl, projectId, projectToken, fingerprint, instanceId, team);
+    log(`[viber-channel] team: attached instance ${instanceId.slice(0, 8)} to team "${team}"\n`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log(`[viber-channel] team: self-attach to "${team}" failed (non-fatal): ${msg}\n`);
+  }
+}
+
 export interface AcquiredInstance {
   instance_token: string;
   /**
@@ -116,6 +187,10 @@ export async function acquireInstance(
   log: (msg: string) => void = (m) => process.stderr.write(m),
   cwd: string = process.cwd(),
 ): Promise<AcquiredInstance> {
+  // Resolve the identity into `result` (one of the four paths), then run the
+  // #398 team self-attach ONCE at the single exit — covers every path (incl. the
+  // claude/plain register paths) without scattering the call (R-CLAUDE).
+  let result: AcquiredInstance;
   const envToken = process.env.VIBER_INSTANCE_TOKEN;
   if (envToken !== undefined && envToken.trim() !== "") {
     const token = envToken.trim();
@@ -123,42 +198,44 @@ export async function acquireInstance(
     const realId = envId !== undefined && envId.trim() !== "" ? envId.trim() : undefined;
     const key = realId ?? token;
     log(`[viber-channel] instance: using VIBER_INSTANCE_TOKEN (env-injected)\n`);
-    return { instance_token: token, instance_key: key, instance_id: realId };
-  }
-
-  const envLabel = process.env.VIBER_CHANNEL_LABEL;
-  if (envLabel !== undefined && envLabel.trim() !== "") {
-    const label = envLabel.trim();
-    log(`[viber-channel] instance: registering fresh labelled instance "${label}"\n`);
-    const reg = await registerInstance(
-      baseUrl,
-      auth.project_id,
-      auth.project_token,
-      fingerprint,
-      label,
-      instanceKindFromEnv(),
-    );
-    return { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
-  }
-
-  if (auth.instance_token !== undefined && auth.instance_token.trim() !== "") {
-    const realId =
-      auth.instance_id !== undefined && auth.instance_id.trim() !== "" ? auth.instance_id : undefined;
-    const key = realId ?? auth.instance_token;
-    log(`[viber-channel] instance: reusing persisted instance_token (id=${auth.instance_id ?? "?"})\n`);
-    return { instance_token: auth.instance_token, instance_key: key, instance_id: realId };
+    result = { instance_token: token, instance_key: key, instance_id: realId };
+  } else {
+    const envLabel = process.env.VIBER_CHANNEL_LABEL;
+    if (envLabel !== undefined && envLabel.trim() !== "") {
+      const label = envLabel.trim();
+      log(`[viber-channel] instance: registering fresh labelled instance "${label}"\n`);
+      const reg = await registerInstance(
+        baseUrl,
+        auth.project_id,
+        auth.project_token,
+        fingerprint,
+        label,
+        instanceKindFromEnv(),
+      );
+      result = { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
+    } else if (auth.instance_token !== undefined && auth.instance_token.trim() !== "") {
+      const realId =
+        auth.instance_id !== undefined && auth.instance_id.trim() !== "" ? auth.instance_id : undefined;
+      const key = realId ?? auth.instance_token;
+      log(`[viber-channel] instance: reusing persisted instance_token (id=${auth.instance_id ?? "?"})\n`);
+      result = { instance_token: auth.instance_token, instance_key: key, instance_id: realId };
+    } else {
+      log(`[viber-channel] instance: none found — registering a new one via the project_token\n`);
+      const reg = await registerInstance(
+        baseUrl,
+        auth.project_id,
+        auth.project_token,
+        fingerprint,
+        undefined,
+        instanceKindFromEnv(),
+      );
+      persistInstanceCredentials(authFilePath(cwd), reg.instance_id, reg.instance_token, log);
+      log(`[viber-channel] instance: registered + persisted (id=${reg.instance_id})\n`);
+      result = { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
+    }
   }
 
-  log(`[viber-channel] instance: none found — registering a new one via the project_token\n`);
-  const reg = await registerInstance(
-    baseUrl,
-    auth.project_id,
-    auth.project_token,
-    fingerprint,
-    undefined,
-    instanceKindFromEnv(),
-  );
-  persistInstanceCredentials(authFilePath(cwd), reg.instance_id, reg.instance_token, log);
-  log(`[viber-channel] instance: registered + persisted (id=${reg.instance_id})\n`);
-  return { instance_token: reg.instance_token, instance_key: reg.instance_id, instance_id: reg.instance_id };
+  // #398: best-effort self-attach to VIBER_INSTANCE_TEAM (no-op when unset).
+  await maybeAttachTeam(baseUrl, auth.project_id, auth.project_token, fingerprint, result.instance_id, log);
+  return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "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,18 +31,18 @@ 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";
 import { startParentWatchdog } from "./lib/parent_watchdog.ts";
-import { acquireInstance, registerInstance } from "./lib/instance.ts";
+import { acquireInstance, maybeAttachTeam, registerInstance } from "./lib/instance.ts";
 import {
   runPersistentControlStream,
   sendInstanceHeartbeat,
@@ -71,7 +71,17 @@ import { capabilitiesText } from "./lib/capabilities.ts";
   // 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.
+  //
+  // BUT the yield is a STAGING/PROD-only behavior: the plugin channel only runs
+  // there (it is disabled in the Viber dev repo, #365). On the DEV backend there
+  // is NO plugin to yield to, so yielding = no channel at all (`-32000`, no
+  // registration). Derive this from the environment (single source of truth,
+  // isDevBackend) instead of relying on VIBER_CHANNEL_AGENT_SESSION not leaking
+  // from the parent shell into the spawned dev terminal (the real bug: that var
+  // leaked and terminal.ts never cleared it, so the dev channel silently bowed
+  // out). Default (non-dev) behavior is unchanged.
   if (
+    !isDevBackend() &&
     process.env.VIBER_CHANNEL_AGENT_SESSION === "1" &&
     process.env.VIBER_CHANNEL_PLUGIN !== "1"
   ) {
@@ -159,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;
 })();
@@ -307,7 +323,12 @@ process.stdin.on("end", () => {
 
 // ---- Auth from .viber/auth.json ----
 
-import { authFilePath, loadAuth, persistInstanceCredentials } from "./lib/auth.ts";
+import {
+  authFilePath,
+  isDevBackend,
+  loadAuth,
+  persistInstanceCredentials,
+} from "./lib/auth.ts";
 import { handleConversationTokenExpired } from "./lib/channel_errors.ts";
 import { buildSseUrl } from "./lib/urls.ts";
 
@@ -644,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(
@@ -663,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`,
@@ -678,17 +751,32 @@ try {
       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,
-      );
+      // #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);
+      // #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;
     }
@@ -737,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

@@ -18,7 +18,7 @@ import {
 } from "./lib/conversation.ts";
 import { sessionFilePath, writeHandle } from "./lib/channel_session.ts";
 import { clientFingerprint } from "./lib/fingerprint.ts";
-import { acquireInstance, instanceKindFromEnv, registerInstance } from "./lib/instance.ts";
+import { acquireInstance, instanceKindFromEnv, maybeAttachTeam, registerInstance } from "./lib/instance.ts";
 import {
   acquireBridgeLock as coreAcquireBridgeLock,
   agentIdentityFromEnv,
@@ -820,6 +820,9 @@ async function acquireBridgeInstance(
   process.stderr.write("[viber-codex-bridge] instance: registering fresh bridge instance\n");
   const reg = await registerInstance(baseUrl, auth.project_id, auth.project_token, fingerprint, label, instanceKindFromEnv() ?? "codex");
   process.stderr.write(`[viber-codex-bridge] instance: registered fresh bridge instance (id=${reg.instance_id})\n`);
+  // #398 (R-CODEX-FRESH): self-attach here too so codex is teamed structurally,
+  // not only via the VIBER_INSTANCE_TOKEN branch above (parity with claude).
+  await maybeAttachTeam(baseUrl, auth.project_id, auth.project_token, fingerprint, reg.instance_id);
   return { instance_token: reg.instance_token, instance_key: reg.instance_id };
 }
 
@@ -885,6 +888,8 @@ async function acquireTargetConversation(
       const reg = await registerInstance(BASE_URL, auth.project_id, auth.project_token, fingerprint, label, instanceKindFromEnv() ?? "codex");
       instanceToken = reg.instance_token;
       instanceKey = reg.instance_id;
+      // #398: re-attach the fresh (post-revocation) codex instance to its team.
+      await maybeAttachTeam(BASE_URL, auth.project_id, auth.project_token, fingerprint, reg.instance_id);
       // Identity changed → re-key the lock onto the new instance. Acquire the new
       // lock BEFORE releasing the old one: if acquisition throws, the old lock is
       // still held and the outer catch releases exactly it (no dangling reference).
@@ -1254,10 +1259,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 {