viber-channel 0.8.15 → 0.8.17

package/lib/agent_tools.ts

@@ -17,8 +17,9 @@
  * MCP tool-result shape. It does NOT hold state.
  */
 import { postMessage, parseArtifact, type Artifact } from "./messages.js";
-import { listPeersAuto, openDm, type OpenDmResult } from "./peers.js";
+import { listPeersAuto, openDm, type OpenDmResult, type PeerFilters } 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
@@ -75,12 +98,27 @@ function errorText(s: string): AgentToolResult {
  * entry then carries a `project` field); a regular instance transparently
  * falls back to its own project (unchanged behaviour, no `project` field).
  */
-export async function listAgents(ctx: AgentToolsContext): Promise<AgentToolResult> {
+export async function listAgents(
+  ctx: AgentToolsContext,
+  args: Record<string, unknown> = {},
+): Promise<AgentToolResult> {
   if (!ctx.instanceToken()) {
     return errorText("Channel not ready: no instance identity yet.");
   }
+  // #501 step-05 — optional filters, applied SERVER-side. Without them a
+  // dev-lead looking for its two reviewers pulls every agent the project ever
+  // created (30 rows for 5 live ones, measured), in a loop.
+  const filters: PeerFilters = {};
+  if (args.online === true) filters.online = true;
+  if (typeof args.label_prefix === "string" && args.label_prefix !== "") {
+    filters.labelPrefix = args.label_prefix;
+  }
   try {
-    const { peers, scope } = await listPeersAuto(ctx.baseUrl(), ctx.instanceToken());
+    const { peers, scope, presenceStatus } = await listPeersAuto(
+      ctx.baseUrl(),
+      ctx.instanceToken(),
+      filters,
+    );
     // Project only what the model needs to pick a peer (drop last_seen /
     // active_conversation_id — available over the wire if a future tool needs them).
     const summary = peers.map((p) => ({
@@ -91,13 +129,22 @@ export async function listAgents(ctx: AgentToolsContext): Promise<AgentToolResul
       // Present only in the user-scoped (orchestrator) listing.
       ...(p.project_name !== undefined ? { project: p.project_name } : {}),
     }));
+    // An `online` filter under an unreadable presence source would come back
+    // empty and read as "nobody is alive" — the false green in listing form.
+    // The server drops the filter in that case; say so rather than let the
+    // caller believe it was applied.
+    const presenceWarning =
+      filters.online === true && presenceStatus === "unavailable"
+        ? "WARNING: the presence source is unavailable, so the `online` filter was NOT applied — " +
+          "`online` values below are unknown, not observed.\n\n"
+        : "";
     const body =
       summary.length === 0
         ? scope === "user"
           ? "No other agents are currently registered in any of your projects."
           : "No other agents are currently registered in this project."
         : JSON.stringify(summary, null, 2);
-    return text(body);
+    return text(`${presenceWarning}${body}`);
   } catch (err) {
     return errorText(`list_agents failed: ${String(err)}`);
   }

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";
@@ -91,8 +92,19 @@ export const TOOL_DEFS = [
       "List the OTHER agents (instances) you can DM. Returns each agent's id, " +
       "label, runtime kind, and whether it is online. Use it to find an id before message_agent. " +
       "Normally project-scoped; an ORCHESTRATOR instance (#307) sees all the owner's projects, " +
-      "each entry tagged with a `project` field.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      "each entry tagged with a `project` field. " +
+      "FILTER instead of listing everything (#501): `online: true` for live agents only, " +
+      "`label_prefix` for one team (e.g. \"501-\"). Both are applied server-side. " +
+      "If the presence source is unreachable the `online` filter is DROPPED and the answer " +
+      "says so — an empty list would wrongly read as \"no agent is alive\".",
+    inputSchema: {
+      type: "object",
+      properties: {
+        online: { type: "boolean", description: "Only agents currently seen online." },
+        label_prefix: { type: "string", description: 'Only labels starting with this, e.g. "501-".' },
+      },
+      additionalProperties: false,
+    },
   },
   {
     name: "message_agent",
@@ -145,7 +157,7 @@ export async function dispatchBridgeTool(
 ): Promise<AgentToolResult> {
   let result: AgentToolResult;
   if (name === "list_agents") {
-    result = await listAgents(opts.ctx);
+    result = await listAgents(opts.ctx, args);
   } else if (name === "message_agent") {
     result = await messageAgent(opts.ctx, args);
   } else if (name === "send_message") {
@@ -166,7 +178,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/claude_tool_defs.ts

@@ -71,10 +71,24 @@ export const CLAUDE_TOOL_DEFS = [
       "Use this to find the id of an agent (e.g. 'Codex Review') before calling message_agent. " +
       "Normally scoped to this project; if the owner designated this instance an ORCHESTRATOR " +
       "(#307), the list covers ALL the owner's projects and each entry carries a `project` field. " +
-      "You are never in the list.",
+      "You are never in the list. " +
+      "FILTER instead of listing everything (#501): `online: true` returns only agents the server " +
+      'currently sees online, `label_prefix` only those whose label starts with it (e.g. "501-" ' +
+      "for one team). Both are applied server-side, so an unfiltered call in a loop is the " +
+      "expensive path. If the presence source is unreachable the `online` filter is DROPPED and " +
+      'the answer says so — an empty list would wrongly read as "no agent is alive".',
     inputSchema: {
       type: "object" as const,
-      properties: {},
+      properties: {
+        online: {
+          type: "boolean",
+          description: "Only agents the server currently sees online.",
+        },
+        label_prefix: {
+          type: "string",
+          description: 'Only agents whose label starts with this prefix, e.g. "501-".',
+        },
+      },
       required: [],
       additionalProperties: false,
     },

package/lib/instance.ts

@@ -193,6 +193,16 @@ export interface AcquiredInstance {
  *   3. `auth.json` `instance_token` — reused (durable identity, D4 → same id).
  *   4. register a NEW instance with the stable project_token, persisted back to
  *      auth.json (self-healing migration — no forced manual reconnect).
+ *
+ * ⚠ #501 DEPENDS ON THE PRIORITY ORDER ABOVE. vibe-master's readiness gate proves
+ * an agent came up by watching for an instance id that did NOT exist before the
+ * launch. Only route 2 mints one: routes 1 and 3 REUSE an id, so a launch that
+ * took either would be reported as "never registered" while being perfectly
+ * healthy — a false red. vibe-master's spawns take route 2 because
+ * `vibe-master/lib/terminal.ts` scrubs `VIBER_INSTANCE_TOKEN`/`_ID` from the
+ * child environment; the guarantee lives there, and this comment exists so a
+ * change here is not made unaware of it. Locked by the route-precedence tests in
+ * `test/instance.test.ts`.
  */
 export async function acquireInstance(
   baseUrl: string,