viber-channel 0.7.2 → 0.8.1

package/lib/agent_tools.ts

@@ -17,7 +17,7 @@
  * MCP tool-result shape. It does NOT hold state.
  */
 import { postMessage, parseArtifact, type Artifact } from "./messages.js";
-import { listPeers, openDm, type OpenDmResult } from "./peers.js";
+import { listPeersAuto, openDm, type OpenDmResult } from "./peers.js";
 import { ConversationTokenExpiredError } from "./messages.js";
 
 /** MCP tool-result shape (text content + optional error flag). */
@@ -66,22 +66,36 @@ function errorText(s: string): AgentToolResult {
 }
 
 /**
- * list_agents — return this project's other agents so the model can pick one to
- * message. Guards the startup window: an empty instance token means "channel not
- * ready" rather than hitting the peers endpoint with no credential.
+ * list_agents — return the other agents so the model can pick one to message.
+ * Guards the startup window: an empty instance token means "channel not ready"
+ * rather than hitting the peers endpoint with no credential.
+ *
+ * #307: the listing runs at the widest allowed scope (listPeersAuto) — an
+ * ORCHESTRATOR instance sees the agents of ALL its owner's projects (each
+ * 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> {
   if (!ctx.instanceToken()) {
     return errorText("Channel not ready: no instance identity yet.");
   }
   try {
-    const peers = await listPeers(ctx.baseUrl(), ctx.instanceToken());
+    const { peers, scope } = await listPeersAuto(ctx.baseUrl(), ctx.instanceToken());
     // 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) => ({ id: p.id, label: p.label, kind: p.kind, online: p.online }));
+    const summary = peers.map((p) => ({
+      id: p.id,
+      label: p.label,
+      kind: p.kind,
+      online: p.online,
+      // Present only in the user-scoped (orchestrator) listing.
+      ...(p.project_name !== undefined ? { project: p.project_name } : {}),
+    }));
     const body =
       summary.length === 0
-        ? "No other agents are currently registered in this project."
+        ? 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);
   } catch (err) {

package/lib/bridge_core.ts

@@ -841,14 +841,23 @@ export function buildAgentIdentityInstructions(opts: {
 
 /**
  * Read the agent identity from the spawn env and build the identity line.
- * `VIBER_AGENT_NAME_EXPLICIT === "1"` gates whether `VIBER_CODEX_BRIDGE_LABEL`
- * is treated as an explicit name (the label is always set — even for auto ids —
- * so the separate flag is the only safe signal). Shared by every bridge.
+ * `VIBER_AGENT_NAME_EXPLICIT === "1"` gates whether the spawn label is treated as
+ * an explicit name (the label is always set — even for auto ids — so the separate
+ * flag is the only safe signal). Shared by every runtime:
+ *   - the codex/gemma bridges set `VIBER_CODEX_BRIDGE_LABEL`;
+ *   - a Claude terminal session (#328) has no bridge — its label is
+ *     `VIBER_CHANNEL_LABEL` (set by buildClaudeLaunchSpec) — so fall back to it.
  */
 export function agentIdentityFromEnv(): string {
 	const explicit = process.env.VIBER_AGENT_NAME_EXPLICIT === "1";
+	// A BLANK bridge label counts as absent (defense in depth, #328): the terminal
+	// launcher wipes an inherited VIBER_CODEX_BRIDGE_LABEL to "", so a Claude
+	// session falls through to its own VIBER_CHANNEL_LABEL instead of a leaked
+	// parent bridge name.
+	const bridgeLabel = process.env.VIBER_CODEX_BRIDGE_LABEL?.trim();
+	const label = bridgeLabel || process.env.VIBER_CHANNEL_LABEL;
 	return buildAgentIdentityInstructions({
-		explicitName: explicit ? process.env.VIBER_CODEX_BRIDGE_LABEL : undefined,
+		explicitName: explicit ? label : undefined,
 		role: process.env.VIBER_AGENT_ROLE,
 	});
 }

package/lib/bridge_tool_host.ts

@@ -68,16 +68,20 @@ const TOOL_DEFS = [
   {
     name: "list_agents",
     description:
-      "List the OTHER agents (instances) in this project 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.",
+      "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 },
   },
   {
     name: "message_agent",
     description:
-      "Send a direct message to another agent in this project. Pass the target agent's instance id " +
+      "Send a direct message to another agent. Pass the target agent's instance id " +
       "(from list_agents) and the text. Opens or reuses a private 1:1 DM and posts your message; " +
-      "the agent's reply arrives back on this channel. Fails if the target agent is offline.",
+      "the agent's reply arrives back on this channel. Targets are normally same-project; an " +
+      "ORCHESTRATOR instance (#307) can also message agents of the owner's other projects. " +
+      "Fails if the target agent is offline.",
     inputSchema: {
       type: "object",
       properties: {

package/lib/capabilities.ts

@@ -0,0 +1,51 @@
+/**
+ * Control-plane capabilities help (#332).
+ *
+ * An agent connected via the channel does not otherwise know that a `vibe-master`
+ * control plane exists on the machine, nor how to spawn other agents with it. Per
+ * the issue + JP: this must be DISCOVERABLE ON DEMAND, never injected into every
+ * conversation. So the channel exposes a `capabilities` MCP tool that returns
+ * this text only when the agent chooses to call it; the channel instructions
+ * carry just a one-line pointer to the tool, not its contents.
+ *
+ * Pure (no I/O) so it is trivially testable and identical across hosts.
+ */
+
+export function capabilitiesText(): string {
+	return [
+		"Viber control plane (vibe-master) — orchestrate other agents from this machine.",
+		"",
+		"vibe-master is a CLI + TUI (installed on the operator machine) that spawns and",
+		"supervises agents which appear in the Viber web UI and answer in their own",
+		"conversations. Use it when you want to delegate to another agent (e.g. a Codex",
+		"reviewer, a second Claude, or a Gemma chat).",
+		"",
+		"Runtimes: codex (background, via vctl) · gemma (background) · claude (terminal).",
+		"(--runtime defaults to codex. Gemma is conversational/read-only only — it",
+		" rejects --permission read-write.)",
+		"",
+		"Spawn one agent (CLI, non-interactive):",
+		"  vibe-master spawn --permission <read-only|read-write> \\",
+		"                    [--runtime codex|claude|gemma] [--name <id>] [--scope <name>]",
+		"  → only --permission is required; --runtime and --name are optional",
+		"    (--name auto-generated if omitted). Prints the agent id; it registers",
+		"    in Viber and comes online.",
+		"",
+		"Multi-scope (#307): spawn into ANOTHER project by name. Register a project",
+		"folder once with `vibe-master scopes add <name> <path>`, then",
+		"`vibe-master spawn --scope <name> …` lands the agent in that project (its own",
+		".viber auth). `--scope` and `--cwd` are exclusive. `vibe-master scopes` lists them.",
+		"",
+		"Interactive: `vibe-master tui` (menu: + Add agent → runtime → permission → name).",
+		"Inspect / stop: `vibe-master list` · `vibe-master kill <id>`.",
+		"",
+		"Talk to a spawned agent from here with list_agents + message_agent.",
+		"Cross-project (#307): by default list_agents/message_agent see only THIS",
+		"project. If the OWNER marks this instance an ORCHESTRATOR (toggle on the web",
+		"project page — server-authorized, never self-declared), list_agents then covers",
+		"ALL the owner's projects (each entry tagged with its project) and message_agent",
+		"can DM an agent in another of those projects.",
+		"Requires vibe-master installed on the machine (see the Install page on the web).",
+		"Run `vibe-master --help` for the full command reference.",
+	].join("\n");
+}

package/lib/lockfile.ts

@@ -14,8 +14,8 @@
  * axis that isolates them for a normal bunx client, where sessionId is always
  * "" (the #259 sessionId axis below provides no isolation there).
  *
- * #259 adds the per-instance axis: when the launcher (e.g. viber-dev.ps1)
- * supplies a per-launch session id via VIBER_CHANNEL_SESSION_ID, the lock is
+ * #259 adds the per-instance axis: when a launcher supplies a per-launch session
+ * id via VIBER_CHANNEL_SESSION_ID, the lock is
  * additionally namespaced by it, so two concurrent launches of the *same*
  * project each get their own lock. Channel respawns within one launch inherit
  * the same env var and reuse the same lock — accidental duplicates are still

package/lib/peers.ts

@@ -11,7 +11,10 @@
 
 import { cfAccessHeaders } from "./cfAccess.js";
 
-/** A peer agent as returned by GET /api/instances/peers. */
+/** A peer agent as returned by GET /api/instances/peers.
+ *  project_id/project_name are present only in the user-scoped listing (#307):
+ *  an orchestrator sees peers across all its owner's projects, each tagged
+ *  with its project. */
 export interface PeerView {
   id: string;
   label: string | null;
@@ -19,17 +22,35 @@ export interface PeerView {
   online: boolean;
   last_seen: number | null;
   active_conversation_id: string | null;
+  project_id?: number;
+  project_name?: string;
+}
+
+/** Error carrying the HTTP status so callers can branch on 403 (#307). */
+export class PeersHttpError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+  ) {
+    super(message);
+    this.name = "PeersHttpError";
+  }
 }
 
 /**
  * List the OTHER active instances of this agent's project (self excluded).
- * Throws on a non-2xx response so the caller can surface a clear tool error.
+ * With scope "user" (#307), an ORCHESTRATOR instance lists the peers of ALL
+ * its owner's projects (the server returns 403 for a non-orchestrator).
+ * Throws PeersHttpError on a non-2xx response so the caller can surface a
+ * clear tool error — or fall back from user scope on a 403.
  */
 export async function listPeers(
   baseUrl: string,
   instanceToken: string,
+  scope?: "user",
 ): Promise<PeerView[]> {
-  const resp = await fetch(`${baseUrl}/api/instances/peers`, {
+  const qs = scope === "user" ? "?scope=user" : "";
+  const resp = await fetch(`${baseUrl}/api/instances/peers${qs}`, {
     method: "GET",
     headers: { Authorization: `Bearer ${instanceToken}`, ...cfAccessHeaders() },
   });
@@ -41,12 +62,33 @@ export async function listPeers(
     } catch {
       /* non-JSON body */
     }
-    throw new Error(`listPeers failed: ${detail}`);
+    throw new PeersHttpError(`listPeers failed: ${detail}`, resp.status);
   }
   const body = (await resp.json()) as { instances?: PeerView[] };
   return Array.isArray(body.instances) ? body.instances : [];
 }
 
+/**
+ * List peers at the WIDEST scope this instance is allowed (#307): try the
+ * user-scoped listing first; a 403 (non-orchestrator) transparently falls
+ * back to the project-scoped listing. Any other failure propagates. Single
+ * tool surface, zero client-side configuration: orchestrators see all their
+ * owner's projects, workers keep seeing their own project only.
+ */
+export async function listPeersAuto(
+  baseUrl: string,
+  instanceToken: string,
+): Promise<{ peers: PeerView[]; scope: "user" | "project" }> {
+  try {
+    return { peers: await listPeers(baseUrl, instanceToken, "user"), scope: "user" };
+  } catch (err) {
+    if (err instanceof PeersHttpError && err.status === 403) {
+      return { peers: await listPeers(baseUrl, instanceToken), scope: "project" };
+    }
+    throw err;
+  }
+}
+
 /** Result of opening (or reusing) a DM with a peer — carries the caller's own
  *  membership conversation_token so it can post into the DM. */
 export interface OpenDmResult {

package/lib/version_check.ts

@@ -0,0 +1,124 @@
+/**
+ * viber-channel stale-version guard (#330).
+ *
+ * A globally-installed `viber-channel` that a user placed by hand (old docs) can
+ * fall far behind npm `latest`. When a later refactor removes/renames a lib file,
+ * that stale install crashes with a raw `Cannot find module './lib/…'` instead of
+ * anything actionable. We can't fix an ALREADY-broken old install from here (its
+ * code predates this guard), so the useful move is PREVENTION: on every startup
+ * that still runs, check whether the installed version is behind `latest` and, if
+ * so, print a clear one-line nudge to update — BEFORE the user ever hits a
+ * breaking refactor. Best-effort and non-fatal: any error (offline, timeout, odd
+ * registry response) is swallowed so the channel starts normally.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const NPM_LATEST_URL = "https://registry.npmjs.org/viber-channel/latest";
+const DEFAULT_TIMEOUT_MS = 1500;
+
+/** Parse a `major.minor.patch` string to a numeric tuple; non-numeric → 0. */
+function parseVersion(v: string): [number, number, number] {
+	const parts = v
+		.trim()
+		.replace(/^v/, "")
+		.split(".")
+		.map((p) => Number.parseInt(p, 10));
+	return [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+}
+
+/** True iff `local` is strictly older than `latest` (major.minor.patch order). */
+export function isOlder(local: string, latest: string): boolean {
+	const a = parseVersion(local);
+	const b = parseVersion(latest);
+	for (let i = 0; i < 3; i++) {
+		if (a[i] < b[i]) return true;
+		if (a[i] > b[i]) return false;
+	}
+	return false;
+}
+
+/** Read this package's own version from its package.json (best-effort → null). */
+export function readLocalVersion(
+	readFile: (p: string) => string = (p) => readFileSync(p, "utf-8"),
+	dir: string = import.meta.dir,
+): string | null {
+	try {
+		const pkg = JSON.parse(readFile(join(dir, "..", "package.json")));
+		return typeof pkg.version === "string" ? pkg.version : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Fetch npm `latest` version with a short timeout; null on any failure. */
+export async function fetchLatestVersion(
+	timeoutMs: number = DEFAULT_TIMEOUT_MS,
+	fetchImpl: typeof fetch = fetch,
+): Promise<string | null> {
+	const ctrl = new AbortController();
+	const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+	try {
+		const res = await fetchImpl(NPM_LATEST_URL, { signal: ctrl.signal });
+		if (!res.ok) return null;
+		const body = (await res.json()) as { version?: unknown };
+		return typeof body.version === "string" ? body.version : null;
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+export interface StaleCheck {
+	local: string;
+	latest: string;
+	stale: boolean;
+}
+
+/** Compare the installed version against npm latest. Null when either is unknown. */
+export async function checkStaleVersion(opts?: {
+	localVersion?: string | null;
+	fetchLatest?: () => Promise<string | null>;
+}): Promise<StaleCheck | null> {
+	// Honor an EXPLICIT localVersion (incl. null = "unknown"); only read the real
+	// package.json when the caller didn't pass the key at all.
+	const local =
+		opts && "localVersion" in opts ? opts.localVersion : readLocalVersion();
+	if (!local) return null;
+	const latest = opts?.fetchLatest
+		? await opts.fetchLatest()
+		: await fetchLatestVersion();
+	if (!latest) return null;
+	return { local, latest, stale: isOlder(local, latest) };
+}
+
+/** The one-line nudge printed to stderr when the install is behind. */
+export function staleWarning(local: string, latest: string): string {
+	return (
+		`[viber-channel] version ${local} is behind latest ${latest}. ` +
+		`Update to avoid a broken install: bun add -g viber-channel@latest`
+	);
+}
+
+/**
+ * Best-effort: warn on stderr when this install is behind npm latest. Never
+ * throws, never blocks longer than the fetch timeout. Called at startup.
+ */
+export async function warnIfStale(opts?: {
+	localVersion?: string | null;
+	fetchLatest?: () => Promise<string | null>;
+	write?: (msg: string) => void;
+}): Promise<void> {
+	try {
+		const check = await checkStaleVersion(opts);
+		if (check?.stale) {
+			(opts?.write ?? ((m) => process.stderr.write(`${m}\n`)))(
+				staleWarning(check.local, check.latest),
+			);
+		}
+	} catch {
+		/* best-effort — never break startup on a version check */
+	}
+}

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "viber-channel",
-  "version": "0.7.2",
-  "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": {
-    "viber-channel": "./viber-channel.ts",
-    "viber-codex-bridge": "./viber-codex-bridge.ts",
-    "viber-gemma-bridge": "./viber-gemma-bridge.ts",
-    "viber-codex-supervisor": "./viber-codex-supervisor.ts"
-  },
-  "files": [
-    "viber-channel.ts",
-    "viber-codex-bridge.ts",
-    "viber-gemma-bridge.ts",
-    "viber-codex-supervisor.ts",
-    "lib/",
-    "README.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/dgx80/viber.git",
-    "directory": "viber-channel"
-  },
-  "homepage": "https://viber.dgypx.dev",
-  "bugs": {
-    "url": "https://github.com/dgx80/viber/issues"
-  },
-  "keywords": [
-    "viber",
-    "claude-code",
-    "mcp",
-    "channel",
-    "voice",
-    "transcription"
-  ],
-  "license": "MIT",
-  "scripts": {
-    "start": "bun run viber-channel.ts",
-    "start:codex-bridge": "bun run viber-codex-bridge.ts",
-    "test": "bun test"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
-  }
-}
+{
+  "name": "viber-channel",
+  "version": "0.8.1",
+  "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": {
+    "viber-channel": "./viber-channel.ts",
+    "viber-codex-bridge": "./viber-codex-bridge.ts",
+    "viber-gemma-bridge": "./viber-gemma-bridge.ts",
+    "viber-codex-supervisor": "./viber-codex-supervisor.ts"
+  },
+  "files": [
+    "viber-channel.ts",
+    "viber-codex-bridge.ts",
+    "viber-gemma-bridge.ts",
+    "viber-codex-supervisor.ts",
+    "lib/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dgx80/viber.git",
+    "directory": "viber-channel"
+  },
+  "homepage": "https://viber.dgypx.dev",
+  "bugs": {
+    "url": "https://github.com/dgx80/viber/issues"
+  },
+  "keywords": [
+    "viber",
+    "claude-code",
+    "mcp",
+    "channel",
+    "voice",
+    "transcription"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "start": "bun run viber-channel.ts",
+    "start:codex-bridge": "bun run viber-codex-bridge.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/viber-channel.ts

@@ -16,9 +16,9 @@
  *
  *   claude --dangerously-load-development-channels server:<name>
  *
- * Two PowerShell launchers wrap the right flag:
- *   - viber.ps1       → server:viber-channel (staging)
- *   - viber-dev.ps1   → server:viber-dev-channel (this repo, dev)
+ * For dev in this repo, vibe-master-dev.ps1 (the multi-agent TUI launcher) wraps
+ * the flag: `server:viber-dev-channel` against the dev backend. Staging sessions
+ * use the plain user-scoped `viber-channel` registration with no launcher flag.
  *
  * CLI subcommand: `bunx viber-channel connect <claim_url>` runs the one-shot
  * claim flow that writes .viber/auth.json without requiring any Claude Code
@@ -54,6 +54,9 @@ import {
   type TokenRefreshScheduler,
 } from "./lib/token_refresh.ts";
 import { awaitStableStartup } from "./lib/startup_gate.ts";
+import { agentIdentityFromEnv } from "./lib/bridge_core.ts";
+import { warnIfStale } from "./lib/version_check.ts";
+import { capabilitiesText } from "./lib/capabilities.ts";
 
 // ---- CLI subcommand dispatch (must happen before lock acquire + loadAuth) ----
 //
@@ -98,6 +101,11 @@ import { awaitStableStartup } from "./lib/startup_gate.ts";
       );
       process.exit(1);
     }
+    // #330: this is the exact path that crashed on a stale hand-placed install
+    // (`bunx viber-channel connect` → missing ./lib/peers.ts). Await the check
+    // here so the "you're behind, update" nudge shows BEFORE the connect work
+    // (best-effort — never throws, short timeout).
+    await warnIfStale();
     try {
       await runConnect(claimUrl);
       process.exit(0);
@@ -108,6 +116,11 @@ import { awaitStableStartup } from "./lib/startup_gate.ts";
   }
 }
 
+// Server path (fell through the dispatch block): warn if this install is behind
+// npm latest, but fire-and-forget so it never delays mcp.connect — the nudge
+// lands on stderr shortly after startup (#330).
+void warnIfStale();
+
 // Lock file path: %APPDATA%/viber/ (Windows) or ~/.config/viber/ (Linux/Mac).
 // Namespaced by (VIBER_BASE_URL, client_fingerprint, VIBER_CHANNEL_SESSION_ID) so:
 //   - channels at different backends (staging + dev) coexist (different base_url);
@@ -340,18 +353,32 @@ const mcp = new Server(
       experimental: { "claude/channel": {} },
       tools: {},
     },
+    // #369 truncation fix: Claude Code truncates long MCP `instructions`
+    // ("…[truncated]") and this blob was ~3 KB → the TAIL was dropped before the
+    // agent saw it (that hid the agent's name #328, and threatened the #332
+    // pointer + exit-intent). So: CRITICAL lines are FRONT-LOADED (identity →
+    // core reply → actions/questions → anti-deadlock → capabilities → exit) and
+    // the nice-to-have style notes live at the tail where a cut is harmless.
+    // Condensed vs the old prose (same substance — reviewed). Identity is "" for
+    // JP's own session (no explicit-name flag) → the identity LINE is filtered
+    // out for him; the rest of the (now shorter, reordered) blob applies to every
+    // session including his.
     instructions: [
-      'Voice transcripts arrive as <channel source="viber-channel"> events carrying the user\'s microphone speech.',
-      "Reply with send_message. You are talking to a human who both LISTENS (the `text` is read aloud by TTS) AND READS it on screen (the `text` is ALSO rendered as Markdown in the UI). So aim for both: it must sound natural read aloud AND be easy to read. Lead with the answer, no preamble or recap.",
-      "USE light Markdown in `text` when it makes the message easier to read: short bullet lists (`- `), numbered steps (`1.`), checklists, **bold** for key terms. A short list reads aloud just fine — a spoken list is natural. Don't cram several points into one dense paragraph; break them out. Avoid heavy/awkward-to-speak markup (big tables, code blocks, long fenced snippets) in `text` — that belongs in the artifact.",
-      "ACTIONS and QUESTIONS belong in `text`, made visible — never bury them in the artifact. If you need a decision, ask it clearly in `text` (a short bullet list of the options is good); the artifact may hold supporting detail but the question itself must be in `text` where it jumps out.",
-      "The `artifact` is for HEAVY or LONG content only: big code, large tables, long multi-point analyses, review dumps, JSON, file lists. When you use an artifact, keep `text` a brief spoken summary that points to it ('details on the side') — don't read the heavy content aloud.",
-      "Write identifiers LITERALLY with their real characters (288, auth.json, viber-dev.dgypx.dev, CONVERSATION_TOKEN) — never spell them out as 'point'/'dash' and never as awkward digit-by-digit text. A lone long token or path is better placed in the artifact than spoken.",
-      "Artifact formats: `markdown` (default), `code`, `json`, `html`. Use `html` only when the rendering needs structural HTML Markdown can't express (styled cards, badges, mixed layouts). Scripts and event handlers are stripped server-side; don't send executable JS.",
-      "NO EMOJI in `text` — it is read aloud, so an emoji becomes spoken noise (a check mark is read as 'check mark'). Use plain Markdown (bullets, bold) for structure instead. Emoji are tolerable only inside an artifact (not spoken).",
-      "Rule of thumb: short and conversational, but readable — break points into a list rather than a wall of text; reserve the artifact for what is genuinely long or heavy.",
+      agentIdentityFromEnv(),
+      // --- critical: front-loaded so truncation can never drop them ---
+      'Voice transcripts arrive as <channel source="viber-channel"> events (the user\'s microphone speech). Reply with send_message. The `text` is BOTH read aloud (TTS) AND shown as Markdown — make it natural aloud AND easy to read; lead with the answer, no preamble.',
+      "Put ACTIONS and QUESTIONS in `text`, visibly — never bury them in the artifact. Use light Markdown (short bullet/numbered lists, **bold**) to stay readable; a short spoken list is fine.",
+      // #343 anti-deadlock (hands-free: the user is NOT watching the terminal).
+      "CRITICAL — while this channel is active, NEVER block on a terminal prompt or AskUserQuestion: the user is hands-free and cannot see the terminal, so it deadlocks. Put EVERY question or choice in send_message `text` and take the answer from the next voice transcript.",
+      // #332 discoverability pointer (the how-to lives in the capabilities tool).
+      "To orchestrate or spawn OTHER agents (Codex, Claude, Gemma) on this machine, call the `capabilities` tool for how — only when relevant.",
       "On exit intent (bye, au revoir, stop) call stop_conversation(), speak a brief farewell, and stop.",
-    ].join(" "),
+      // --- nice-to-have style notes (safe near the tail) ---
+      "The `artifact` (format: markdown default, or code/json/html) is for HEAVY/LONG content (big code, large tables, long analyses, JSON, file lists); keep `text` a brief spoken summary that points to it ('details on the side'). Scripts/event handlers are stripped server-side.",
+      "NO EMOJI in `text` (read aloud — an emoji becomes spoken noise). Write identifiers LITERALLY (288, auth.json, viber-dev.dgypx.dev) — never spell out dots/dashes; a lone long token or path is better placed in the artifact.",
+    ]
+      .filter((line) => line.length > 0)
+      .join(" "),
   }
 );
 
@@ -401,10 +428,12 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "list_agents",
       description:
-        "List the OTHER agents (instances) in this project you can talk to directly (#288). " +
+        "List the OTHER agents (instances) you can talk to directly (#288). " +
         "Returns each agent's id, label, runtime kind, and whether it is currently online. " +
         "Use this to find the id of an agent (e.g. 'Codex Review') before calling message_agent. " +
-        "Only agents in the same project are returned; you are never in the list.",
+        "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.",
       inputSchema: {
         type: "object" as const,
         properties: {},
@@ -415,10 +444,12 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "message_agent",
       description:
-        "Send a direct message to another agent in this project (#288). " +
+        "Send a direct message to another agent (#288). " +
         "Pass the target agent's instance id (from list_agents, or the from_instance_id of a DM you received) " +
         "and the message text. Opens or reuses a private 1:1 DM with that agent and posts your message; " +
         "the agent's reply arrives back on this channel tagged source=agent-dm. " +
+        "Targets are normally same-project; an ORCHESTRATOR instance (#307) can also message agents " +
+        "of the owner's other projects (ids from its cross-project list_agents). " +
         "Fails if the target agent is offline.",
       inputSchema: {
         type: "object" as const,
@@ -438,6 +469,20 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         additionalProperties: false,
       },
     },
+    {
+      name: "capabilities",
+      description:
+        "On-demand: learn what the Viber control plane (vibe-master) can do on this " +
+        "machine — how to spawn and supervise OTHER agents (Codex, Claude, Gemma). " +
+        "Call this only when orchestrating other agents is relevant; it is not part " +
+        "of the default context. Returns a short usage reference.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {},
+        required: [],
+        additionalProperties: false,
+      },
+    },
   ],
 }));
 
@@ -478,6 +523,11 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     return libMessageAgent(channelToolsCtx, args);
   }
 
+  // #332: on-demand control-plane discovery — static help, no runtime state.
+  if (request.params.name === "capabilities") {
+    return { content: [{ type: "text" as const, text: capabilitiesText() }] };
+  }
+
   if (request.params.name !== "send_message") {
     return {
       isError: true,
@@ -829,7 +879,7 @@ try {
 // ---- Channel ready banner ----
 
 process.stderr.write(
-  `[viber-channel] Channel ready: 3 tools (send_message, list_agents, message_agent), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
+  `[viber-channel] Channel ready: 4 tools (send_message, list_agents, message_agent, capabilities), SSE on /api/conversations/${CONVERSATION_ID}/events\n`
 );
 
 // Channel liveness is proven by the INSTANCE heartbeat (#311, started above), not