viber-channel 0.8.14 → 0.8.16

package/lib/agent_tools.ts

@@ -19,6 +19,7 @@
 import { postMessage, parseArtifact, type Artifact } from "./messages.js";
 import { listPeersAuto, openDm, type OpenDmResult } from "./peers.js";
 import { ConversationTokenExpiredError } from "./messages.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
 /** MCP tool-result shape (text content + optional error flag). */
 export interface AgentToolResult {
@@ -26,6 +27,28 @@ export interface AgentToolResult {
   content: { type: "text"; text: string }[];
 }
 
+/**
+ * #489 step-04 — adapt a tool result to what the MCP SDK's handler signature wants.
+ *
+ * The SDK's `CallToolResult` carries an index signature (the MCP result object is
+ * open: `_meta` and future fields pass through), so `AgentToolResult` was NOT
+ * assignable to the SDK handler type — the TS2345 at `lib/bridge_tool_host.ts` and
+ * `viber-channel.ts`. Verified against the SDK schema, not against our output:
+ * `{ content: [{ type: "text", text }], isError }` IS a valid `CallToolResult`. The
+ * missing openness was the ONLY incompatibility, so there is no protocol divergence.
+ *
+ * The openness lives HERE, at the SDK boundary, and NOT on `AgentToolResult` — review
+ * measured that opening our own interface silently disables excess-property checking
+ * on it, so `{ content: […], isErorr: true }` would compile. Keeping our type closed
+ * preserves that check at every construction site; the single unavoidable widening is
+ * named, commented, and confined to this function.
+ */
+export function toMcpToolResult(result: AgentToolResult): CallToolResult {
+  // No cast: the spread is a FRESH object type, which TypeScript grants an implicit
+  // index signature when assigning to the SDK's open result type.
+  return { ...result };
+}
+
 /**
  * Live, by-reference access to the host channel's runtime state. Implemented by
  * both hosts so the shared tool logic never reads a stale snapshot. Every getter

package/lib/bridge_core.ts

@@ -16,6 +16,7 @@
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { createTokenRefreshScheduler, type TokenRefreshScheduler } from "./token_refresh.js";
 import type { ApiBaseUrlResolver } from "./base_urls.js";
+import { acquireLockFile, isProcessAlive } from "./bridge_lock.js";
 import { lockFilePath } from "./lockfile.js";
 import {
 	type ConversationMintResponse,
@@ -159,24 +160,24 @@ export function planAwaitInviteFirstPass<T>(msgs: T[]): { forward: T[]; seed: T[
 	return { forward: [msgs[msgs.length - 1]], seed: msgs.slice(0, -1) };
 }
 
-/** True if a PID names a live process (EPERM counts as alive). */
-export function isProcessAlive(pid: number): boolean {
-	if (!Number.isInteger(pid) || pid <= 0) return false;
-	try {
-		process.kill(pid, 0);
-		return true;
-	} catch (err) {
-		if (typeof err === "object" && err !== null && "code" in err && err.code === "EPERM") return true;
-		return false;
-	}
-}
+/**
+ * #489 step-02: re-exported from `lib/bridge_lock.ts`, which is now the single
+ * implementation. Kept exported here because callers and tests already import it
+ * from this module.
+ */
+export { isProcessAlive };
 
 /**
- * Acquire the per-agent bridge lock (a PID file). `sessionId` is the identity
- * axis (e.g. `codex-agent:<instanceId>` / `gemma-agent:<instanceId>`), so two
- * processes with the SAME identity cannot both run. A stale lock (dead PID) is
- * reclaimed; a live one throws a BridgeShutdownError. `logPrefix` keeps each
- * bridge's log lines under its own tag.
+ * Acquire the per-agent bridge lock (a PID file). `sessionId` is the identity axis
+ * (e.g. `codex-agent:<instanceId>` / `gemma-agent:<instanceId>`), so two processes
+ * with the SAME identity cannot both run. A stale lock (dead PID) is reclaimed; a
+ * live one throws a BridgeShutdownError. `logPrefix` keeps each bridge's log lines
+ * under its own tag.
+ *
+ * #489 step-02: a thin adapter now. The loop, the payload and the reclaim decision
+ * live in `lib/bridge_lock.ts`, shared with the MCP client — the duplication was one
+ * of the defects of #489. What stays HERE is this site's error protocol: throw, so
+ * the bridge dies rather than reporting a pid to a human.
  */
 export function acquireBridgeLock(opts: {
 	/**
@@ -190,49 +191,37 @@ export function acquireBridgeLock(opts: {
 	sessionId: string;
 	lockDir: string;
 	logPrefix: string;
+	/** Called if the lock is lost mid-run — the caller tears the bridge down. */
+	onLost?: (reason: string) => void;
 }): BridgeLock {
 	const { identityBaseUrl, fingerprint, sessionId, lockDir, logPrefix } = opts;
-	mkdirSync(lockDir, { recursive: true });
 	const path = lockFilePath(identityBaseUrl, fingerprint, sessionId, lockDir);
-	const release = (): void => {
-		try {
-			unlinkSync(path);
-		} catch {
-			// Best effort: the file may already be gone.
-		}
-	};
-
-	for (let attempt = 0; attempt < 2; attempt++) {
-		try {
-			writeFileSync(path, `${process.pid}\n`, { flag: "wx" });
-			process.stderr.write(`${logPrefix} lock acquired: ${path}\n`);
-			return { path, release };
-		} catch (err) {
-			if (typeof err !== "object" || err === null || !("code" in err) || err.code !== "EEXIST") {
-				throw err;
-			}
-
-			let existingPid = Number.NaN;
-			try {
-				existingPid = Number.parseInt(readFileSync(path, "utf-8").trim(), 10);
-			} catch {
-				release();
-				continue;
-			}
-
-			if (!Number.isFinite(existingPid) || !isProcessAlive(existingPid)) {
-				release();
-				continue;
-			}
-
-			throw new BridgeShutdownError(
-				`Another bridge already holds the lock ${sessionId} (PID ${existingPid})`,
-				1,
-			);
-		}
+	const result = acquireLockFile({
+		lockFile: path,
+		// #489 step-03 (review): losing the lock is a FENCING signal, not a log line. A
+		// dispossessed bridge that keeps running has no authority over its identity, which
+		// is the unbounded duplicate this design promises not to create. Withdraw the same
+		// way the parent watchdog does: request shutdown and let the normal teardown run.
+		onLost: (reason) => {
+			process.stderr.write(`${logPrefix} ${reason} — withdrawing
+`);
+			opts.onLost?.(reason);
+		},
+	});
+	if (result.ok) {
+		process.stderr.write(`${logPrefix} lock acquired: ${path}
+`);
+		// The release closure captures the path it actually took — it never
+		// recomputes it from the environment (#489 step-02, raised in review).
+		return { path, release: result.release };
 	}
-
-	throw new BridgeShutdownError(`Failed to acquire bridge lock ${sessionId}`, 1);
+	if (result.blockedBy === -1) {
+		throw new BridgeShutdownError(`Failed to acquire bridge lock ${sessionId}`, 1);
+	}
+	throw new BridgeShutdownError(
+		`Another bridge already holds the lock ${sessionId} (PID ${result.blockedBy})`,
+		1,
+	);
 }
 
 /** Optional VIBER_REFRESH_LEAD_SECONDS override (clamped to ≥ 0). */
@@ -1159,6 +1148,12 @@ export async function acquireBridgeIdentity(opts: {
 		sessionId: `${sessionTag}-agent:${acquired.instance_key}`,
 		lockDir,
 		logPrefix,
+		// #489 step-03 (review A): fencing — a dispossessed bridge must not keep running.
+		onLost: (reason) => {
+			process.stderr.write(`${logPrefix} ${reason} — withdrawing to avoid a duplicate
+`);
+			process.exit(1);
+		},
 	});
 	return {
 		instanceKey: acquired.instance_key,

package/lib/bridge_lock.ts

@@ -0,0 +1,323 @@
+/**
+ * bridge_lock.ts — the ONE implementation of the per-folder / per-agent lock
+ * (#489 step-02).
+ *
+ * Before this file, the same invariant was implemented TWICE, with real divergences:
+ *
+ *   |                | viber-channel.ts (MCP client) | lib/bridge_core.ts (bridges) |
+ *   |----------------|-------------------------------|------------------------------|
+ *   | liveness probe | local isProcessAlive          | exported isProcessAlive      |
+ *   | `pid <= 0`     | ABSENT                        | present                      |
+ *   | on conflict    | returns the blocking pid      | throws BridgeShutdownError    |
+ *
+ * Fixing only the bridge would have left the Claude MCP client broken, so both go
+ * through here. The two error protocols are PRESERVED on purpose and NOT unified:
+ * the MCP client prints the blocking pid for the user, the bridge dies. Only the
+ * decision — is this lock reclaimable? — is shared, and it is a PURE function so it
+ * can be exhausted by tests without touching a filesystem.
+ *
+ * Dependencies (liveness, clock, fs) are injected with real defaults: step-03 needs
+ * to drive them, and a probe hard-wired to `process.kill` is precisely what made the
+ * recycled-PID case untestable.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import lockfile from "proper-lockfile";
+import { classifyLegacyHolder, processStartTime } from "./process_start.js";
+import { lockTimingOptions } from "./lock_timing.js";
+
+/** True if a PID names a live process (EPERM counts as alive: it exists, it is not ours). */
+export function isProcessAlive(pid: number): boolean {
+  // The `pid <= 0` guard came from the bridge side only; the MCP client lacked it.
+  // Negative/zero pids have platform-specific meanings in kill(2) (process groups),
+  // none of which is "the holder of this lock".
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (typeof err === "object" && err !== null && "code" in err && err.code === "EPERM") return true;
+    return false;
+  }
+}
+
+/** What a reader concludes about an existing lock file. */
+export type LockVerdict =
+  | { kind: "reclaimable"; why: string }
+  | { kind: "held"; pid: number };
+
+/** Everything the decision needs, so it stays pure and fully testable. */
+export interface LockDecisionInput {
+  /** Raw file contents, or `null` when unreadable/absent. */
+  payload: string | null;
+  isAlive: (pid: number) => boolean;
+}
+
+/**
+ * Decide whether an existing lock can be taken over. PURE — no I/O, no clock.
+ *
+ * Today's rule is exactly the historical one, so step-02 stays a refactor: a lock is
+ * reclaimable when its payload is unreadable or its PID is not alive. Step-03 changes
+ * THIS function, and the tests it already has become the regression net.
+ */
+export function decideLock(input: LockDecisionInput): LockVerdict {
+  const { payload, isAlive } = input;
+  if (payload === null) return { kind: "reclaimable", why: "unreadable" };
+  const pid = Number.parseInt(payload.trim(), 10);
+  if (!Number.isFinite(pid)) return { kind: "reclaimable", why: "malformed payload" };
+  if (!isAlive(pid)) return { kind: "reclaimable", why: `pid ${pid} is not alive` };
+  return { kind: "held", pid };
+}
+
+export interface AcquireLockFileOptions {
+  /** Absolute path of the lock file. */
+  lockFile: string;
+  /**
+   * Liveness probe, used ONLY for the legacy-payload path below. The authoritative
+   * mechanism no longer looks at PIDs at all — see the module header.
+   */
+  isAlive?: (pid: number) => boolean;
+  /**
+   * Process start time for a PID, epoch ms, or `undefined` when unknowable. Resolves
+   * the legacy/recycled ambiguity documented below BY PROOF, not by resemblance.
+   */
+  startTimeOf?: (pid: number) => number | undefined;
+  /**
+   * Called when the library reports our lock COMPROMISED (its directory vanished under
+   * us — someone reclaimed it after the staleness window). The default logs; every real
+   * caller passes a controlled withdrawal, because continuing without authority is the
+   * duplicate this design promises to bound.
+   */
+  onLost?: (reason: string) => void;
+  /** PID written for diagnostics and for older clients to see. Defaults to ours. */
+  pid?: number;
+  /**
+   * Staleness regime. Defaults to the PINNED values of `lib/lock_timing.ts`; injected
+   * only by tests, which cannot wait 5 minutes to prove that a crashed holder's lock
+   * becomes reclaimable.
+   */
+  timing?: { stale: number; update: number };
+}
+
+export type AcquireLockFileResult =
+  | { ok: true; release: () => void }
+  | { ok: false; blockedBy: number };
+
+/**
+ * Read the legacy PID payload, if any. `null` when absent or unusable.
+ */
+function readLegacyPid(lockFile: string): number | null {
+  try {
+    const pid = Number.parseInt(readFileSync(lockFile, "utf-8").trim(), 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Take the lock.
+ *
+ * TWO mechanisms, on purpose, and the order matters:
+ *
+ *  1. **Legacy PID file, checked FIRST.** A client from before #489 advertises itself
+ *     only by writing its PID into `lockFile`; it knows nothing about the directory
+ *     `proper-lockfile` uses. If we skipped this check, a new client would see no
+ *     `.lock` directory, acquire, and run ALONGSIDE a live old holder — #311 re-opened
+ *     for the whole duration of a mixed deployment (and mixed versions do exist here:
+ *     the embedded plugin and vibe-master run the same source, npm is the only
+ *     authority — #503). So: legacy payload + LIVE pid = held. Reviewers required
+ *     exactly this, and only on a live pid — a dead one is reclaimable, which is what
+ *     makes the 81 residual locks disappear.
+ *
+ *  2. **`proper-lockfile` for everything else** — the authority. Its lock carries NO
+ *     PID: mutual exclusion is a `mkdir` CAS and liveness is the mtime it refreshes.
+ *     That is why the #489 defect does not come back — a recycled PID cannot make a
+ *     dead holder look alive, because no PID is consulted at all.
+ *
+ * After acquiring we still WRITE our pid into `lockFile`, for two reasons: an older
+ * client must be able to see that the folder is taken, and the message shown to a human
+ * ("another agent holds this folder, PID N") stays useful. That PID is diagnostic
+ * only — it is never read as a liveness signal by this code.
+ */
+export function acquireLockFile(opts: AcquireLockFileOptions): AcquireLockFileResult {
+  const { lockFile } = opts;
+  const isAlive = opts.isAlive ?? isProcessAlive;
+  const pid = opts.pid ?? process.pid;
+  const onLost = opts.onLost ?? ((reason: string) => process.stderr.write(`[viber-lock] ${reason}
+`));
+
+  mkdirSync(dirname(lockFile), { recursive: true });
+
+  const legacyPid = readLegacyPid(lockFile);
+  if (legacyPid !== null && !existsSync(`${lockFile}.lock`) && isAlive(legacyPid)) {
+    // ── The one genuinely ambiguous state, and how it is settled ──────────────
+    //
+    // On disk these are IDENTICAL: a pre-#489 client still running (pid file, no lock
+    // directory, pid alive) and a leftover pid file whose number the OS recycled. Both
+    // reviewer requirements land here and pull opposite ways — "respect a live legacy
+    // holder" vs "never block permanently on a recycled pid", the latter being why #489
+    // exists at all, since the reported case WAS a leftover file.
+    //
+    // Settled by PROOF, not resemblance. A first attempt compared process NAMES, and
+    // review demolished it with a measurement: 110 live bun/node processes on the dev
+    // machine, so a recycled pid landing on any other bun was read as a live holder and
+    // the lock stayed immortal — the #489 bug surviving in its likeliest case.
+    //
+    // The proof is a timestamp the same query already returns: a real holder existed
+    // BEFORE it wrote its lock file; a recycled pid started AFTER the file was written.
+    // See lib/process_start.ts.
+    const probe = opts.startTimeOf ?? processStartTime;
+    let fileMtimeMs = 0;
+    try {
+      fileMtimeMs = statSync(lockFile).mtimeMs;
+    } catch {
+      fileMtimeMs = 0;
+    }
+    const verdict = classifyLegacyHolder({ startedAt: probe(legacyPid), fileMtimeMs });
+    // "unknown" stays conservative: refusing to start is recoverable, two agents on one
+    // identity is not.
+    if (verdict !== "recycled") {
+      return { ok: false, blockedBy: legacyPid };
+    }
+  }
+
+  let release: () => void;
+  try {
+    release = lockfile.lockSync(lockFile, {
+      ...(opts.timing ?? lockTimingOptions()),
+      retries: 0,
+      /**
+       * MUST be provided. `proper-lockfile`'s default handler THROWS when its lock
+       * directory disappears under a live holder (another process reclaimed it after
+       * the staleness window, or something cleaned the directory). That throw happens
+       * inside the library's own refresh timer, i.e. outside any of our try/catch —
+       * an uncaught exception that would take the whole agent down. Hit for real while
+       * building the crash-reclaim test.
+       *
+       * But swallowing it is just as wrong: a dispossessed holder that keeps running has
+       * no authority over its identity while another process may already hold it — the
+       * unbounded duplicate this design promises not to create. So we hand it to
+       * `onLost`, and every entry point wires that to a controlled withdrawal (the shape
+       * `onParentGone` uses in viber-channel.ts).
+       */
+      onCompromised: (err: Error) => {
+        onLost(`lock compromised: ${err.message}`);
+      },
+      // The target need not exist: we lock a PATH, and the pid file below is written
+      // only once the lock is ours.
+      realpath: false,
+    });
+  } catch (err) {
+    if (typeof err === "object" && err !== null && "code" in err && err.code === "ELOCKED") {
+      // Held by a live holder. Report its pid when the diagnostic file has one.
+      return { ok: false, blockedBy: readLegacyPid(lockFile) ?? -1 };
+    }
+    throw err;
+  }
+
+  try {
+    writeFileSync(lockFile, `${pid}\n`);
+  } catch {
+    // Diagnostics only — never fail an acquisition over it.
+  }
+
+  // #489 step-03 (review C): REPAIR the diagnostic pid file periodically.
+  //
+  // Review measured the real severity of losing it: the library's directory still holds
+  // the authority, but a pre-#489 client reads ONLY this file — so if it disappears,
+  // that old client walks in and stays for B's whole lifetime, not for microseconds.
+  // Re-creating it on a beat bounds the exposure to one interval. Same cadence as the
+  // library's own refresh; `unref` so it can never keep a process alive.
+  const repair = setInterval(() => {
+    try {
+      if (readLegacyPid(lockFile) !== pid) writeFileSync(lockFile, `${pid}
+`);
+    } catch {
+      // Diagnostic only.
+    }
+  }, (opts.timing ?? lockTimingOptions()).update);
+  repair.unref?.();
+
+  let released = false;
+  return {
+    ok: true,
+    release: () => {
+      // Idempotent: exit handlers can fire twice, and releasing twice must not throw.
+      if (released) return;
+      released = true;
+      clearInterval(repair);
+      try {
+        release();
+      } catch {
+        // Already gone / reclaimed elsewhere.
+      }
+      // #489 step-03 (review): remove the diagnostic pid file ONLY IF IT IS STILL OURS.
+      //
+      // Review asked for no unlink at all, to close this window: we release the
+      // library's lock, B acquires and writes ITS pid, and our unlink would delete B's
+      // file — after which an old client, which only reads that file, would miss B and
+      // start in parallel.
+      //
+      // Measured consequence of never unlinking, though: our own pid file survives our
+      // release, our process is still alive and STARTED BEFORE the file, so the
+      // start-time proof classifies us as a live legacy holder — and the folder is
+      // blocked for good. A DETERMINISTIC immortal lock, i.e. the #489 bug re-created by
+      // its own fix. Two tests caught it.
+      //
+      // So: compare, then unlink. The residual race is a read-then-unlink of a few
+      // microseconds whose worst outcome is a MISSING diagnostic file (bounded, and the
+      // library's directory still holds the authority), against a permanent block. The
+      // window is stated rather than hidden.
+      try {
+        if (readLegacyPid(lockFile) === pid) unlinkSync(lockFile);
+      } catch {
+        // Diagnostic only — never fail a release over it.
+      }
+    },
+  };
+}
+
+/**
+ * Hold the release of a lock we ACTUALLY took — nothing else (#489 step-02).
+ *
+ * This exists because of a real bug in the pre-#489 code, found in review and
+ * verified on `e67a2e0`:
+ *
+ *   - `process.on("exit", … releaseLock())` was registered at MODULE scope
+ *     (`viber-channel.ts:335`), therefore BEFORE `acquireLock()` ran (l.523);
+ *   - the old `releaseLock()` did an UNCONDITIONAL `unlinkSync(LOCK_FILE)`;
+ *   - a launch that LOST the race went on to `process.exit(1)`, firing that handler.
+ *
+ * So every accidental duplicate ended by DELETING THE WINNER'S LOCK: the folder went
+ * unprotected while the winner was still running, and a third launch acquired freely.
+ * The invariant this lock exists to hold (#166/#311) was broken by its own error path.
+ *
+ * The slot makes the guarantee structural instead of incidental: `releaseIfHeld()` is
+ * a no-op unless an acquisition succeeded and handed over its release. Kept HERE, in
+ * the tested module, rather than as a bare `let` in the entry point that no test can
+ * import.
+ */
+export interface LockSlot {
+  /** Record the release of a successful acquisition. */
+  adopt: (release: () => void) => void;
+  /** Release only if we hold it. Idempotent — exit handlers can fire twice. */
+  releaseIfHeld: () => void;
+  /** True once an acquisition has been adopted and not yet released. */
+  isHeld: () => boolean;
+}
+
+export function createLockSlot(): LockSlot {
+  let release: (() => void) | null = null;
+  return {
+    adopt: (r) => {
+      release = r;
+    },
+    releaseIfHeld: () => {
+      const r = release;
+      release = null;
+      r?.();
+    },
+    isHeld: () => release !== null,
+  };
+}

package/lib/bridge_tool_host.ts

@@ -27,6 +27,7 @@ import {
   messageAgent,
   sendMessage,
   type AgentToolsContext,
+  toMcpToolResult,
   type AgentToolResult,
 } from "./agent_tools.js";
 import { CONTRACT_STYLE_NEUTRAL, CONTRACT_STYLE_TOOLS } from "./channel_instructions.js";
@@ -166,7 +167,7 @@ function buildServer(opts: BridgeToolHostOptions): Server {
   mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     const args = (request.params.arguments ?? {}) as Record<string, unknown>;
     try {
-      return await dispatchBridgeTool(request.params.name, args, opts);
+      return toMcpToolResult(await dispatchBridgeTool(request.params.name, args, opts));
     } catch (err) {
       // The shared lib rethrows ConversationTokenExpiredError (host-specific
       // teardown). In the bridge we surface it as a tool error rather than

package/lib/lock_dir.ts

@@ -0,0 +1,62 @@
+/**
+ * lock_dir.ts — resolve the directory holding this machine's channel locks and
+ * conversation handles (#489 step-01).
+ *
+ * Three entry points (`viber-channel.ts`, `viber-codex-bridge.ts`,
+ * `viber-gemma-bridge.ts`) each carried the SAME copy-pasted expression as a
+ * module-level `const`. Two consequences, both paid by #489:
+ *
+ *   1. resolved at IMPORT time, so nothing could redirect it afterwards — a test
+ *      importing any of those modules read and WROTE the real `%APPDATA%/viber`,
+ *      took a real lock, and never released it;
+ *   2. three copies to keep in step.
+ *
+ * Resolution is therefore LAZY (called at each use) and lives here once.
+ *
+ * ⚠ This directory holds more than locks: the conversation handles of #269
+ * (`sessionFilePath`) live here too. Redirecting it moves the handles as well, and
+ * an agent that loses its handle RE-MINTS its conversation. That is why the
+ * override is opt-in, and why it is logged when set.
+ */
+import { join } from "node:path";
+
+/** Env var that redirects locks + handles. Tests set it; production never does. */
+export const LOCK_DIR_ENV = "VIBER_LOCK_DIR";
+
+let announced = false;
+
+/**
+ * The lock/handle directory: `$VIBER_LOCK_DIR` when set and non-blank, else the
+ * historical default — `%APPDATA%/viber` on Windows, `~/.config/viber` elsewhere.
+ *
+ * The default is byte-for-byte what the three copies computed before this file
+ * existed: a lock path that shifts re-opens the #311/#293 duplicate window, and a
+ * handle path that shifts makes agents re-mint their conversations (#269).
+ *
+ * A blank value is treated as ABSENT, not as "the current directory" — a launcher
+ * exporting an empty variable must not silently scatter locks into the cwd.
+ */
+export function resolveLockDir(
+  env: NodeJS.ProcessEnv = process.env,
+  log: (msg: string) => void = (m) => process.stderr.write(m),
+): string {
+  const override = env[LOCK_DIR_ENV];
+  if (override !== undefined && override.trim() !== "") {
+    // Announce ONCE per process. A stray variable in an environment would
+    // otherwise split the locks in silence and re-open #311 with no trace in the
+    // logs — the failure mode is invisible, so the log line is the safety net.
+    if (!announced) {
+      announced = true;
+      log(`[viber-lock] ${LOCK_DIR_ENV} set — locks and handles under ${override.trim()}\n`);
+    }
+    return override.trim();
+  }
+  return env.APPDATA
+    ? join(env.APPDATA, "viber")
+    : join(env.HOME ?? "/tmp", ".config", "viber");
+}
+
+/** Test seam: forget that the override was announced. */
+export function resetLockDirAnnounce(): void {
+  announced = false;
+}

package/lib/lock_timing.ts

@@ -0,0 +1,39 @@
+/**
+ * lock_timing.ts — the two numbers that decide when a lock is considered abandoned
+ * (#489 step-03).
+ *
+ * They live in their own named module, and they are passed EXPLICITLY to
+ * `proper-lockfile`, because the library derives `update` from `stale` when you omit
+ * it. The regime that ships must be the one we chose and wrote down — a review
+ * requirement, and the same reasoning that made us justify the TTL of the rejected
+ * home-grown protocol.
+ */
+
+/**
+ * How long a lock may go un-refreshed before another process may take it over.
+ *
+ * 5 minutes. The trade-off, stated plainly: a holder frozen longer than this loses its
+ * lock, which re-opens the #311/#293 duplicate window for that process. The window is
+ * bounded and self-healing, and it replaces a failure that was PERMANENT — the #489
+ * bug, where a recycled PID made a dead holder look alive forever. Bounded beats
+ * infinite.
+ *
+ * Not shorter: a machine under load (three agent teams + Whisper on one GPU box, which
+ * is this project's normal state) can stall a process for tens of seconds.
+ */
+export const LOCK_STALE_MS = 5 * 60 * 1000;
+
+/**
+ * How often the holder refreshes its lock's mtime.
+ *
+ * 60 s — one twelfth of `LOCK_STALE_MS`, so five consecutive missed refreshes are
+ * needed before a live holder can be dispossessed. Explicit rather than inherited:
+ * `proper-lockfile` would default it to `stale / 2`, i.e. 150 s here, leaving only two
+ * refreshes of margin.
+ */
+export const LOCK_UPDATE_MS = 60 * 1000;
+
+/** Both values in the shape `proper-lockfile` expects. */
+export function lockTimingOptions(): { stale: number; update: number } {
+  return { stale: LOCK_STALE_MS, update: LOCK_UPDATE_MS };
+}

package/lib/lockfile.ts

@@ -43,11 +43,14 @@ export function lockFilePath(
   sessionId: string,
   lockDir: string,
 ): string {
-  // #480: this repo has NO typecheck over viber-channel (no tsconfig), so a
-  // caller omitting the field in an object literal ships silently and we hash
-  // the string "undefined" — every agent then converges on the SAME lock and
-  // handle, cross-talking between projects. Cheap runtime guard instead of
-  // trusting a compiler that never runs.
+  // #480 wrote this guard because "this repo has NO typecheck over viber-channel".
+  // #489 added one (tsconfig.json + `bun run typecheck`, enforced in CI), so that
+  // justification is gone — but the guard STAYS, for reasons the compiler cannot
+  // cover: a JS caller, a value crossing a JSON/env boundary, or any `unknown`
+  // narrowed wrongly still reaches here at runtime. If a field is omitted we hash
+  // the string "undefined", and every agent converges on the SAME lock and handle,
+  // cross-talking between projects. That failure is silent and expensive; the check
+  // is one comparison.
   assertHashKey(baseUrl, "lockFilePath(baseUrl)", { allowEmpty: false });
   assertHashKey(fingerprint, "lockFilePath(fingerprint)");
   assertHashKey(sessionId, "lockFilePath(sessionId)");

package/lib/process_start.ts

@@ -0,0 +1,156 @@
+/**
+ * process_start.ts — when did a PID's process actually start? (#489 step-03, review)
+ *
+ * This is what turns "is this a recycled PID?" from a guess into a proof.
+ *
+ * The first attempt classified a legacy lock holder by process NAME (`bun`/`node`).
+ * Review killed it with a measurement: 110 live bun/node processes on the dev machine,
+ * so a recycled PID landing on ANY other bun — an agent, the vctl daemon, a bridge,
+ * vite — was classified as a live legacy holder and the lock stayed immortal. That is
+ * the #489 bug surviving in its most likely case.
+ *
+ * The decisive signal costs nothing extra, because the same CIM query already returns
+ * it:
+ *
+ *   - a REAL legacy holder existed BEFORE it wrote its lock file
+ *       → its start time is EARLIER than the file's mtime;
+ *   - a RECYCLED pid started AFTER the file was written — that is what recycling means
+ *       → its start time is LATER than the file's mtime.
+ *
+ * Implemented on both platform families so the guarantee is universal: on Windows the
+ * CIM `CreationDate`, on Linux `/proc/<pid>/stat` field 22 against `/proc/stat` btime.
+ * Returning `undefined` anywhere keeps the caller's conservative answer, but it is now
+ * the exception rather than the rule off Windows.
+ */
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+/**
+ * Filesystem mtimes and OS start-times do not share a clock granularity, and a real
+ * holder writes its lock file milliseconds after starting. Allow a few seconds before
+ * calling a process "younger than the file".
+ */
+export const START_TIME_TOLERANCE_MS = 5_000;
+
+/** Parse a WMI/CIM datetime (`20260730031245.123456+000`) into epoch ms. */
+export function parseCimDate(raw: string): number | undefined {
+  const m = raw.trim().match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{6})([+-]\d+)?$/);
+  if (!m) {
+    // Some locales/PowerShell versions hand back a printable date instead.
+    const parsed = Date.parse(raw.trim());
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  const [, y, mo, d, h, mi, s, us, tz] = m;
+  const offsetMinutes = tz === undefined ? 0 : Number.parseInt(tz, 10);
+  const utc = Date.UTC(
+    Number(y), Number(mo) - 1, Number(d),
+    Number(h), Number(mi), Number(s),
+    Math.floor(Number(us) / 1000),
+  );
+  return utc - offsetMinutes * 60_000;
+}
+
+/**
+ * Windows: CreationDate via a filtered CIM query (the probe #298 P2b already uses).
+ *
+ * ⚠ We ask PowerShell for the EPOCH, not for a date, and that is deliberate: on this
+ * machine CIM renders `CreationDate` in the system LOCALE — measured, it printed
+ * `15 juillet 2026 03:16:03`. Parsing that text is a locale trap that would return
+ * `undefined` on some machines and a wrong instant on others, making the lock's verdict
+ * depend on the OS language. Letting PowerShell convert removes the ambiguity.
+ */
+/**
+ * Absolute path to PowerShell when the OS root is known.
+ *
+ * Not paranoia: running the whole suite, this probe started failing in ~5 ms — far too
+ * fast for a spawn — with `powershell` unresolvable. Resolving from `SystemRoot` removes
+ * the dependency on `PATH` entirely; the repo fights the same class of problem in
+ * `codex_shell_path.ts`. `SystemRoot` is read ONCE at module load, before anything can
+ * rewrite it. (No `env:` is passed to `execSync` — the absolute path is what makes the
+ * PATH irrelevant, and claiming more than that would be inaccurate.)
+ */
+const OS_ROOT_AT_STARTUP = process.env.SystemRoot ?? process.env.windir;
+
+function powershellCommand(): string {
+  return OS_ROOT_AT_STARTUP === undefined
+    ? "powershell"
+    : `"${OS_ROOT_AT_STARTUP}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"`;
+}
+
+function startTimeWin32(pid: number): number | undefined {
+  try {
+    const out = execSync(
+      `${powershellCommand()} -NoProfile -Command "$p = Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}'; ` +
+        `if ($p) { [int64]($p.CreationDate.ToUniversalTime() - [datetime]'1970-01-01').TotalMilliseconds }"`,
+      { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const line = out.split(/\r?\n/).find((l) => l.trim() !== "");
+    if (line === undefined) return undefined;
+    const ms = Number.parseInt(line.trim(), 10);
+    return Number.isFinite(ms) && ms > 0 ? ms : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Linux: field 22 of /proc/<pid>/stat (ticks since boot) + /proc/stat btime. */
+function startTimeLinux(pid: number): number | undefined {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+    // The comm field can contain spaces and parentheses — split after the last ')'.
+    const after = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    // After comm+state, field 22 (starttime) is index 19 of the remainder.
+    const ticks = Number.parseInt(after[19] ?? "", 10);
+    if (!Number.isFinite(ticks)) return undefined;
+    const btimeLine = readFileSync("/proc/stat", "utf-8")
+      .split("\n")
+      .find((l) => l.startsWith("btime "));
+    if (btimeLine === undefined) return undefined;
+    const btime = Number.parseInt(btimeLine.slice(6).trim(), 10);
+    if (!Number.isFinite(btime)) return undefined;
+    // USER_HZ is 100 on every Linux this project runs on (incl. the CI runners).
+    return btime * 1000 + (ticks / 100) * 1000;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Epoch ms at which `pid`'s process started, or `undefined` if it cannot be known. */
+export function processStartTime(pid: number, now: number = Date.now()): number | undefined {
+  if (!Number.isInteger(pid) || pid <= 0) return undefined;
+  const raw =
+    process.platform === "win32"
+      ? startTimeWin32(pid)
+      : process.platform === "linux"
+        ? startTimeLinux(pid)
+        : undefined;
+  if (raw === undefined) return undefined;
+  // A start time in the FUTURE is absurd, and it is the dangerous direction: the Linux
+  // path assumes USER_HZ = 100, and if a kernel used 1000 the computed instant would
+  // land ahead of now — `classifyLegacyHolder` would answer "recycled" and we would
+  // DISPOSSESS LIVE HOLDERS. That failure mode is fail-OPEN, so refuse the value and
+  // fall back to "unknown", which is fail-closed like every other unknown here.
+  if (raw > now + START_TIME_TOLERANCE_MS) return undefined;
+  return raw;
+}
+
+export type HolderVerdict = "recycled" | "legacy-holder" | "unknown";
+
+/**
+ * Decide what a live PID in a legacy lock file actually is. PURE — the two timestamps
+ * are supplied, so every branch is unit-testable without a real process.
+ */
+export function classifyLegacyHolder(input: {
+  /** Process start time, or undefined when unknowable. */
+  startedAt: number | undefined;
+  /** mtime of the lock file that names this pid. */
+  fileMtimeMs: number;
+  toleranceMs?: number;
+}): HolderVerdict {
+  const { startedAt, fileMtimeMs } = input;
+  const tolerance = input.toleranceMs ?? START_TIME_TOLERANCE_MS;
+  if (startedAt === undefined) return "unknown";
+  // Started measurably AFTER the file was written → it cannot be the writer.
+  if (startedAt > fileMtimeMs + tolerance) return "recycled";
+  return "legacy-holder";
+}

package/lib/spawn_reason.ts

@@ -175,7 +175,13 @@ export function parseSpawnResult(
  */
 export function messageForReason(
   reason: SpawnReason,
-  detail?: string,
+  // #489 step-04: `detail` was declared OPTIONAL before the REQUIRED `roster`
+  // (TS1016), which no compiler ever saw here. Latent but armed: any caller
+  // omitting `detail` would have shifted `roster` into it. Today's callers all
+  // pass three arguments (lib/runner_exec.ts:517 + the tests), so nothing was
+  // broken — the trap was set for the next caller. Made required, which matches
+  // every existing call site.
+  detail: string | undefined,
   roster: readonly string[],
   logRef?: string,
 ): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.14",
+  "version": "0.8.16",
   "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": {
@@ -38,9 +38,16 @@
   "scripts": {
     "start": "bun run viber-channel.ts",
     "start:codex-bridge": "bun run viber-codex-bridge.ts",
-    "test": "bun test"
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "proper-lockfile": "^4.1.2"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "@types/proper-lockfile": "^4.1.4",
+    "typescript": "5.9.3"
   }
 }

package/viber-channel.ts

@@ -6,7 +6,10 @@
  * from the npm registry to decide whether a machine's global install has drifted (#503).
  * It is therefore a PUBLISHED contract, not just a number: the `channel-v*` tag, the
  * package version and vibe-master's `EXPECTED_VIBER_CHANNEL_VERSION` floor move together
- * (#423), and any version published here reaches clients without a vibe-master release.
+ * (#423). From vibe-master 0.7.7 on, that contract lets a version published here reach
+ * clients WITHOUT a vibe-master release: the floor only sets the minimum, the registry
+ * sets the target. Measured evidence belongs in the issue/plan that measures it — not in
+ * the package whose publication is what makes the measurement possible.
  *
  * Reads .viber/auth.json for authentication, then connects to
  * /api/conversations/<id>/events SSE stream and pushes transcripts and
@@ -68,6 +71,8 @@ import { CLAUDE_TOOL_DEFS } from "./lib/claude_tool_defs.ts";
 import { warnIfStale } from "./lib/version_check.ts";
 import { capabilitiesText } from "./lib/capabilities.ts";
 import { BOW_OUT_MESSAGE, shouldBowOutToPlugin } from "./lib/cli_bow_out.ts";
+import { resolveLockDir } from "./lib/lock_dir.ts";
+import { acquireLockFile, createLockSlot } from "./lib/bridge_lock.ts";
 
 // ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
 //
@@ -182,10 +187,10 @@ void warnIfStale();
 // LOCK_FINGERPRINT is computed from the current folder (process.cwd()) rather
 // than read from auth.json so the lock paths are available before loadAuth();
 // it is verified equal to auth.client_fingerprint below — a mismatch exits.
-const LOCK_DIR =
-  process.env.APPDATA
-    ? join(process.env.APPDATA, "viber")
-    : join(process.env.HOME ?? "/tmp", ".config", "viber");
+// #489 step-01: LAZY, not a module-level const — a const froze the path at import,
+// so nothing could redirect it and tests wrote into the real %APPDATA%/viber. Default
+// is unchanged, byte for byte. See lib/lock_dir.ts.
+const LOCK_DIR = (): string => resolveLockDir();
 // #480: the lock hash is keyed on the LOGICAL backend identity, never on the
 // (possibly redirected, possibly normalized) API host — see lib/base_urls.ts.
 const LOCK_BASE_URL = identityBaseUrl();
@@ -202,7 +207,10 @@ const LOCK_BASE_URL = identityBaseUrl();
 // keeps sessionId="" so accidental duplicates stay blocked. See lockSessionId.
 const LOCK_SESSION_ID = lockSessionId(process.env);
 const LOCK_FINGERPRINT = clientFingerprint(process.cwd());
-const LOCK_FILE = lockFilePath(LOCK_BASE_URL, LOCK_FINGERPRINT, LOCK_SESSION_ID, LOCK_DIR);
+// #489 step-01: lazy, like LOCK_DIR — computing it at import froze the directory
+// before anything could redirect it.
+const LOCK_FILE = (): string =>
+  lockFilePath(LOCK_BASE_URL, LOCK_FINGERPRINT, LOCK_SESSION_ID, LOCK_DIR());
 // SESSION_FILE (the conversation handle path) is computed AFTER the instance is
 // acquired (#269) — it is namespaced by the server-issued instance, not the
 // local fingerprint/sessionId. Declared as a `let` near the mint below.
@@ -256,67 +264,60 @@ const STABILITY_DELAY_MS: number = (() => {
   return parsed;
 })();
 
-function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err: any) {
-    if (err?.code === "EPERM") return true; // Process exists, no permission to signal
-    return false; // ESRCH or anything Bun-specific — treat as dead
-  }
-}
 
 /** Try to acquire lock. Returns null on success, or the blocking PID on conflict. */
-function acquireLock(): number | null {
-  mkdirSync(LOCK_DIR, { recursive: true });
-  const ourPid = String(process.pid);
-
-  for (let attempt = 0; attempt < 2; attempt++) {
-    try {
-      writeFileSync(LOCK_FILE, ourPid + "\n", { flag: "wx" });
-      return null; // Lock acquired
-    } catch (err: any) {
-      if (err?.code !== "EEXIST") throw err;
-
-      // Lock file exists — check if the holder is still alive
-      let existingPid: number;
-      try {
-        existingPid = parseInt(readFileSync(LOCK_FILE, "utf-8").trim(), 10);
-      } catch {
-        // Corrupt or unreadable — treat as stale
-        releaseLock();
-        continue;
-      }
-
-      if (isNaN(existingPid) || !isProcessAlive(existingPid)) {
-        // Stale lock — remove and retry
-        releaseLock();
-        continue;
-      }
-
-      // Another live channel holds this folder's lock. This blocks accidental
-      // duplicate spawns (#166/#259) — but it also blocks a deliberate 2nd agent
-      // in the same folder (#293). Make the message actionable: a labelled launch
-      // gets its own identity AND lock (see LOCK_SESSION_ID above).
-      process.stderr.write(
-        `[viber-channel] Another Viber agent holds this folder (PID ${existingPid}), exiting. ` +
-          `To run a SECOND agent here, set VIBER_CHANNEL_LABEL=<name> in this MCP server's env ` +
-          `(it gets its own identity + lock) and relaunch.\n`
-      );
-      return existingPid;
-    }
+/**
+ * #489 step-02: thin adapter over `lib/bridge_lock.ts`. The loop, the payload and the
+ * reclaim decision now live there, shared with the bridges — this site keeps only its
+ * OWN error protocol: return the blocking pid so the message below can name it.
+ *
+ * The acquired path is CAPTURED in `lockRelease`, and `releaseLock()` calls that
+ * closure. It used to recompute `LOCK_FILE()` on every exit path (8 of them: the
+ * `exit`/SIGINT/SIGTERM handlers plus 5 inline returns), which re-read `process.env`
+ * — so once step-01 made the directory redirectable, a variable changing between
+ * acquisition and exit would have unlinked a DIFFERENT path: the real lock leaking and
+ * a foreign lock deleted. Raised by both reviewers; the capture is the fix.
+ */
+const lockSlot = createLockSlot();
+
+function acquireLock(lockFile: string = LOCK_FILE()): number | null {
+  const result = acquireLockFile({
+    lockFile,
+    // #489 step-03 (review A): losing the lock mid-run is a FENCING signal — another
+    // process may already hold this folder's identity, so continuing would be the
+    // unbounded duplicate the design promises not to create. Withdraw on exactly the
+    // path onParentGone uses below; exit(1) because this is not a clean shutdown.
+    onLost: (reason) => {
+      process.stderr.write(`[viber-channel] ${reason} — withdrawing to avoid a duplicate
+`);
+      scheduler?.cancel();
+      releaseLock();
+      process.exit(1);
+    },
+  });
+  if (result.ok) {
+    lockSlot.adopt(result.release);
+    return null;
   }
-
-  process.stderr.write("[viber-channel] Failed to acquire lock after retries, exiting.\n");
-  return -1; // Failed to acquire
+  if (result.blockedBy === -1) {
+    process.stderr.write("[viber-channel] Failed to acquire lock after retries, exiting.\n");
+    return -1;
+  }
+  // Another live channel holds this folder's lock. This blocks accidental duplicate
+  // spawns (#166/#259) — but it also blocks a deliberate 2nd agent in the same folder
+  // (#293). Keep the message actionable: a labelled launch gets its own identity AND
+  // lock (see LOCK_SESSION_ID above).
+  process.stderr.write(
+    `[viber-channel] Another Viber agent holds this folder (PID ${result.blockedBy}), exiting. ` +
+      `To run a SECOND agent here, set VIBER_CHANNEL_LABEL=<name> in this MCP server's env ` +
+      `(it gets its own identity + lock) and relaunch.\n`
+  );
+  return result.blockedBy;
 }
 
+/** Release the lock we actually took. Never recomputes the path — see above. */
 function releaseLock(): void {
-  try {
-    unlinkSync(LOCK_FILE);
-  } catch {
-    // Best-effort — file may already be gone
-  }
+  lockSlot.releaseIfHeld();
 }
 
 // Token-refresh scheduler — null until the initial mint succeeds. Declared at
@@ -398,6 +399,8 @@ import {
   listAgents as libListAgents,
   messageAgent as libMessageAgent,
   sendMessage as libSendMessage,
+  toMcpToolResult,
+  type AgentToolResult,
   type AgentToolsContext,
 } from "./lib/agent_tools.ts";
 import { cfAccessHeaders } from "./lib/cfAccess.ts";
@@ -463,7 +466,12 @@ const channelToolsCtx: AgentToolsContext = {
 // NOTE: CONVERSATION_TOKEN and CONVERSATION_ID are populated after
 // mintConversation() runs (below). The handler closure captures the variables
 // by reference — by the time Claude Code calls the tool, they are populated.
-mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
+// #489 step-04: the dispatch keeps returning our CLOSED `AgentToolResult`, so every
+// `return` below is still excess-property checked. Only the registration crosses to
+// the SDK's open result type, through the named adapter — see toMcpToolResult.
+async function handleCallTool(
+  request: { params: { name: string; arguments?: Record<string, unknown> } },
+): Promise<AgentToolResult> {
   const args = (request.params.arguments ?? {}) as Record<string, unknown>;
 
   if (request.params.name === "list_agents") {
@@ -507,7 +515,9 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [{ type: "text" as const, text: `Unexpected error: ${String(err)}` }],
     };
   }
-});
+}
+
+mcp.setRequestHandler(CallToolRequestSchema, async (request) => toMcpToolResult(await handleCallTool(request)));
 
 // Prevent duplicate instances (#166); fingerprint namespacing for different
 // projects (#267); session-id namespacing for concurrent launches of the same
@@ -648,7 +658,7 @@ try {
       channelLabel: process.env.VIBER_CHANNEL_LABEL,
       instanceToken: process.env.VIBER_INSTANCE_TOKEN,
       instanceKey,
-      dir: LOCK_DIR,
+      dir: LOCK_DIR(),
     });
   SESSION_FILE = computeSessionFile(acquired.instance_key);
 

package/viber-codex-bridge.ts

@@ -23,7 +23,7 @@ import { ApiBaseUrlResolver, identityBaseUrl } from "./lib/base_urls.ts";
 import { isTrustedViberOrigin } from "./lib/urls.ts";
 import { sessionFilePath, writeHandle } from "./lib/channel_session.ts";
 import { clientFingerprint } from "./lib/fingerprint.ts";
-import { acquireInstance, instanceKindFromEnv, maybeAttachTeam, registerInstance } from "./lib/instance.ts";
+import { acquireInstance, instanceKindFromEnv, maybeAttachTeam, registerInstance, type AcquiredInstance } from "./lib/instance.ts";
 import {
   acquireBridgeLock as coreAcquireBridgeLock,
   agentIdentityFromEnv,
@@ -70,6 +70,7 @@ import { startInstanceHeartbeat } from "./lib/heartbeat.ts";
 import { startBridgeToolHost, type BridgeToolHost } from "./lib/bridge_tool_host.ts";
 import type { AgentToolsContext } from "./lib/agent_tools.ts";
 import type { OpenDmResult } from "./lib/peers.ts";
+import { resolveLockDir } from "./lib/lock_dir.ts";
 
 // #480: transport host vs logical identity. IDENTITY_URL is what the session and
 // bridge-lock hashes are keyed on (this file builds several of them, below) —
@@ -77,10 +78,10 @@ import type { OpenDmResult } from "./lib/peers.ts";
 const API = new ApiBaseUrlResolver(isTrustedViberOrigin);
 const apiBase = (): string => API.current();
 const IDENTITY_URL = identityBaseUrl();
-const LOCK_DIR =
-  process.env.APPDATA
-    ? join(process.env.APPDATA, "viber")
-    : join(process.env.HOME ?? "/tmp", ".config", "viber");
+// #489 step-01: LAZY, not a module-level const — a const froze the path at import,
+// so nothing could redirect it and tests wrote into the real %APPDATA%/viber. Default
+// is unchanged, byte for byte. See lib/lock_dir.ts.
+const LOCK_DIR = (): string => resolveLockDir();
 
 interface BridgeOptions {
   conversationId: string;
@@ -236,7 +237,26 @@ export function parseArgs(argv: string[], env: NodeJS.ProcessEnv = process.env):
 // pass IDENTITY_URL. Named accordingly so a future edit can't quietly hand it
 // apiBase() and move every lock path.
 function acquireBridgeLock(identityBaseUrl: string, fingerprint: string, sessionId: string): BridgeLock {
-  return coreAcquireBridgeLock({ identityBaseUrl, fingerprint, sessionId, lockDir: LOCK_DIR, logPrefix: LOG_PREFIX });
+  return coreAcquireBridgeLock({
+    identityBaseUrl,
+    fingerprint,
+    sessionId,
+    lockDir: LOCK_DIR(),
+    logPrefix: LOG_PREFIX,
+    // #489 step-03 (review A): losing the lock mid-run is a FENCING signal. A
+    // dispossessed bridge has no authority over its identity any more, and another
+    // process may already hold it — continuing would be the unbounded duplicate this
+    // design promises not to create. Withdraw exactly as the parent watchdog does.
+    // There is no process-wide shutdown controller on this path (the AbortControllers
+    // are per-conversation), so withdraw the same way the channel's watchdog does:
+    // announce, drop the lock, exit non-zero. The supervisor restarts a bridge that
+    // exits, which is the self-healing half of "bounded duplicate".
+    onLost: (reason) => {
+      process.stderr.write(`${LOG_PREFIX} ${reason} — withdrawing to avoid a duplicate
+`);
+      process.exit(1);
+    },
+  });
 }
 
 // shouldHandleMessage, planAwaitInviteFirstPass, senderLabel moved to
@@ -918,7 +938,14 @@ async function acquireBridgeInstance(
   fingerprint: string,
   label: string,
   options: BridgeOptions,
-): Promise<{ instance_token: string; instance_key: string }> {
+  // #489 step-04: this used to be typed `{ instance_token; instance_key }`, which
+  // DROPPED `api_base_url` — and the fresh-register path below dropped it at
+  // runtime too. Callers then did `API.offer(acquired.api_base_url)` with
+  // undefined, and `offer()` accepts undefined silently (lib/base_urls.ts), so the
+  // #480 announced-host adoption never happened at register time on this path. It
+  // self-healed at the next mint/join offer, which is why nobody saw it. Found by
+  // the typecheck this step introduces.
+): Promise<AcquiredInstance> {
   if (process.env.VIBER_INSTANCE_TOKEN !== undefined && process.env.VIBER_INSTANCE_TOKEN.trim() !== "") {
     process.stderr.write("[viber-codex-bridge] instance: using VIBER_INSTANCE_TOKEN from env\n");
     return acquireInstance(baseUrl, auth, fingerprint);
@@ -937,7 +964,14 @@ async function acquireBridgeInstance(
   // #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 };
+  // api_base_url: the host the server just announced. Dropping it here is what
+  // silently killed the #480 adoption on this path (see the return type above).
+  return {
+    instance_token: reg.instance_token,
+    instance_key: reg.instance_id,
+    instance_id: reg.instance_id,
+    api_base_url: reg.api_base_url,
+  };
 }
 
 function loadBridgeAuthAndFingerprint(): { auth: AuthJson; fingerprint: string } {
@@ -964,7 +998,7 @@ async function acquireTargetConversation(
   auth: AuthJson;
   bridgeLock: BridgeLock;
 }> {
-  mkdirSync(LOCK_DIR, { recursive: true });
+  mkdirSync(LOCK_DIR(), { recursive: true });
 
   const label = process.env.VIBER_CODEX_BRIDGE_LABEL ?? `Codex bridge • ${defaultLabel(process.cwd())}`;
   const acquired = await acquireBridgeInstance(apiBase(), auth, fingerprint, label, options);
@@ -973,7 +1007,7 @@ async function acquireTargetConversation(
   API.offer(acquired.api_base_url);
   let instanceToken = acquired.instance_token;
   let instanceKey = acquired.instance_key;
-  let sessionPath = sessionFilePath(IDENTITY_URL, `${instanceKey}:codex:${targetConversationId}`, LOCK_DIR);
+  let sessionPath = sessionFilePath(IDENTITY_URL, `${instanceKey}:codex:${targetConversationId}`, LOCK_DIR());
   // #280 step-12: take the per-agent lock BEFORE reattach. reattach rotates the
   // per-membership token, so a losing duplicate launch of the SAME identity must be
   // stopped before it can rotate the winner's token (Codex review P2-B).
@@ -1015,7 +1049,7 @@ async function acquireTargetConversation(
       const reLock = acquireBridgeLock(IDENTITY_URL, fingerprint, `codex-agent:${instanceKey}`);
       bridgeLock.release();
       bridgeLock = reLock;
-      sessionPath = sessionFilePath(IDENTITY_URL, `${instanceKey}:codex:${targetConversationId}`, LOCK_DIR);
+      sessionPath = sessionFilePath(IDENTITY_URL, `${instanceKey}:codex:${targetConversationId}`, LOCK_DIR());
       const minted = await reattachConversation(
         apiBase(),
         auth.project_id,
@@ -1107,7 +1141,7 @@ async function acquireBridgeIdentity(
   auth: AuthJson,
   fingerprint: string,
 ): Promise<{ instanceKey: string; instanceToken: string; bridgeLock: BridgeLock }> {
-  mkdirSync(LOCK_DIR, { recursive: true });
+  mkdirSync(LOCK_DIR(), { recursive: true });
   const label = process.env.VIBER_CODEX_BRIDGE_LABEL ?? `Codex bridge • ${defaultLabel(process.cwd())}`;
   const acquired = await acquireBridgeInstance(apiBase(), auth, fingerprint, label, options);
   // #480: this exported helper starts a control stream + heartbeat right after,
@@ -1160,7 +1194,7 @@ export async function acquireConversationViaInvite(
     {
       log: (m) => process.stderr.write(m),
       onJoin: (minted) => {
-        const sessionPath = sessionFilePath(IDENTITY_URL, `${instanceKey}:codex:${minted.conversation_id}`, LOCK_DIR);
+        const sessionPath = sessionFilePath(IDENTITY_URL, `${instanceKey}:codex:${minted.conversation_id}`, LOCK_DIR());
         API.offer(minted.api_base_url);
     writeHandle(sessionPath, minted.conversation_id);
       },
@@ -1339,7 +1373,7 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
     await runAwaitInviteBridge({
       api: API,
       identityBaseUrl: IDENTITY_URL,
-      lockDir: LOCK_DIR,
+      lockDir: LOCK_DIR(),
       logPrefix: LOG_PREFIX,
       sessionTag: "codex",
       label: process.env.VIBER_CODEX_BRIDGE_LABEL ?? `Codex bridge • ${defaultLabel(process.cwd())}`,
@@ -1395,7 +1429,7 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
       parentSignal: shutdown.signal,
       api: API,
       identityBaseUrl: IDENTITY_URL,
-      lockDir: LOCK_DIR,
+      lockDir: LOCK_DIR(),
       logPrefix: LOG_PREFIX,
       sessionTag: "codex",
     } satisfies Omit<ConversationStreamDeps, "makeRunTurn">;

package/viber-gemma-bridge.ts

@@ -30,6 +30,7 @@ import {
   type RunTurn,
   runAwaitInviteBridge,
 } from "./lib/bridge_core.ts";
+import { resolveLockDir } from "./lib/lock_dir.ts";
 import {
   DEFAULT_GEMMA_MODEL,
   type ChatMessage,
@@ -43,10 +44,10 @@ const LOG_PREFIX = "[viber-gemma-bridge]";
 const API = new ApiBaseUrlResolver(isTrustedViberOrigin);
 const apiBase = (): string => API.current();
 const IDENTITY_URL = identityBaseUrl();
-const LOCK_DIR =
-  process.env.APPDATA
-    ? join(process.env.APPDATA, "viber")
-    : join(process.env.HOME ?? "/tmp", ".config", "viber");
+// #489 step-01: LAZY, not a module-level const — a const froze the path at import,
+// so nothing could redirect it and tests wrote into the real %APPDATA%/viber. Default
+// is unchanged, byte for byte. See lib/lock_dir.ts.
+const LOCK_DIR = (): string => resolveLockDir();
 
 /**
  * Concise voice-friendly system prompt (ported from viber/standalone_ai.py).
@@ -167,7 +168,7 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
   await runAwaitInviteBridge({
     api: API,
     identityBaseUrl: IDENTITY_URL,
-    lockDir: LOCK_DIR,
+    lockDir: LOCK_DIR(),
     logPrefix: LOG_PREFIX,
     sessionTag: "gemma",
     label,