viber-channel 0.8.34 → 0.8.36

package/lib/capabilities.ts

@@ -13,6 +13,7 @@
  *
  * Pure (no I/O) so it is trivially testable and identical across hosts.
  */
+import { CODEX_DEFAULT_PAIR } from "./codex_default.js";
 
 export function capabilitiesText(channelVersion: string | null = null): string {
 	return [
@@ -87,20 +88,34 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"  after launching is NOT a failure. Wait simply: call list_agents with",
 		"  label_prefix \"<prefix>-\" and online: true every ~10 s, for at most ~60 s; past",
 		"  that, check that the Viber app is running.",
-		"ONE AGENT ALONE = a one-role WEB template. KNOWN LIMIT: launch-team has no --name:",
-		"the owner creates the template on the web (or an orchestrator agent does, with",
-		"team_roles + team_templates, ONLY on the owner's explicit request), then you launch it:",
-		"  role (team_roles create, if the library lacks it): {\"name\":\"dev\",",
-		"        \"runtime\":\"claude\",\"permission\":\"read-write\",\"rolePrompt\":\"You are the dev of {prefix}.\"}",
-		"  template (team_templates create): spec {\"roles\":[{\"role\":\"dev\"}]}  named e.g. solo",
-		"  viber-gateway launch-team solo --prefix g1 --team g1-solo",
-		"                                   → agent \"g1-dev\", team \"g1-solo\"",
+		"LAUNCH ONE AGENT from a role of the owner's ROLE LIBRARY — no template, no team to",
+		"edit (#673). Same folder and auth file as launch-team:",
+		"  viber-gateway launch-agent <role> --name <n> [--team <t>] [--env dev|staging]",
+		"                             [--cwd <dir>]",
+		"  → <role> is a NAME in the library (team_roles list). The agent is named exactly <n>",
+		"    ([A-Za-z0-9-], ≤ 32). --team defaults to <n>: the agent then forms its own team —",
+		"    give it YOUR team only if it must join it (same --team TRAP as above). Example:",
+		"    launch-agent review-codex --name i700-review-2 --team i700 → agent",
+		"    \"i700-review-2\" in team \"i700\". Everything else is launch-team's: read from the",
+		"    web only, staging by default, tracked by the runner, relaunchable from the web,",
+		"    same output lines (keep the launch-id for dissolve --agent), same online delay.",
+		"  The name is REFUSED when an agent of that name is online in the project or being",
+		"  launched from the web — and, on THIS machine, while the same name in the same team",
+		"  has a launch not yet dissolved (\"already has attempt\": dissolve it first, or",
+		"  relaunch it from the web). Across machines, or under another --team, two launches",
+		"  of one name can both pass (the server's check is A CHECK, not a reservation): the",
+		"  later one holds the web relaunch settings; stop the other with dissolve --agent",
+		"  <its launch-id>.",
+		"  A role the library lacks: the owner creates it on the web (or an orchestrator agent",
+		"  does, with team_roles create, ONLY on the owner's explicit request), e.g.",
+		"    {\"name\":\"dev\",\"runtime\":\"claude\",\"permission\":\"read-write\",",
+		"     \"rolePrompt\":\"You are the dev of {prefix}.\"}",
 		"  runtime: claude|codex|gemma · permission: read-only|read-write (gemma: read-only",
 		"  only; all roles of one template must share one permission) · count optional;",
 		"  model/effort: on claude leave them OUT (runtime default) UNLESS the owner asks:",
 		"  model opus|sonnet|haiku|fable, effort low|medium|high|xhigh|max. On codex BOTH are",
-		"  REQUIRED: gpt-5.6-sol / low unless the owner asks for another listed pair.",
-		"  (On the web, sidebar ⋯ → Add agent launches ONE named agent without a template edit.)",
+		`  REQUIRED: ${CODEX_DEFAULT_PAIR} unless the owner asks for another listed pair.`,
+		"  (On the web, sidebar ⋯ → Add agent launches ONE named agent from the same library.)",
 		"",
 		"DISSOLVE (stops the processes, then revokes the proven-stopped instances):",
 		"  viber-gateway dissolve --team <t> | --agent <launch-id>  --dir <registry>",
@@ -120,7 +135,7 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"  what it says (kill a launcher, re-run dissolve, or web sidebar ⋯ → Revoke).",
 		"",
 		"ON THE WEB (owner, sidebar \"⋯\"): project row → Add agent (one named agent from a",
-		"template role, into an existing or new team) / New team; team row → Add agent;",
+		"library role, into an existing or new team) / New team; team row → Add agent;",
 		"agent row → Revoke (confirmation; works online or offline). Both launches need an",
 		"ONLINE runner (the Viber app). Project page → \"Grand ménage\" (clean up offline agents):",
 		"revokes the offline instances, then PERMANENTLY deletes the agent↔agent DMs and agent",
@@ -143,7 +158,8 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"the owner's reusable roles; team templates REFERENCE them by name. Only on the",
 		"owner's explicit request, never on a request relayed by an agent. Editing a role",
 		"changes EVERY template that references it (its used_by), so what their next launch",
-		"runs: say so to the owner first. A role launches nothing by itself. ROLE fields:",
+		"runs: say so to the owner first. A role launches through launch-agent (one agent) or",
+		"a template that references it (a team). ROLE fields:",
 		"    name        REQUIRED  lowercase ^[a-z0-9][a-z0-9_.-]*$, ≤ 80, unique per owner;",
 		"                      it is the agent's name in a team unless the team gives `as`",
 		"                      (a name with a dot, e.g. dev.2, always needs `as`)",
@@ -159,7 +175,7 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"                      max except gpt-5.5, ultra except the luna models and gpt-5.5;",
 		"                      gemma: refused",
 		"                      claude: leave model/effort OUT (runtime default) unless the",
-		"                      owner asks; codex: gpt-5.6-sol / low unless the owner asks",
+		`                      owner asks; codex: ${CODEX_DEFAULT_PAIR} unless the owner asks`,
 		"  update: send ONLY the fields you change plus expected_version (required); model or",
 		"    effort null clears it. 409 role_version_conflict: get, re-apply. 409 role_in_use",
 		"    (delete): templates still reference it — remove it from them first. Other 409:",
@@ -189,16 +205,16 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"    launch was queued (template_changed).",
 		"LAUNCHING ONE OF THESE TEMPLATES: launch-team reads exactly these (the web is the only",
 		"source, #660) — an edit here is what the next launch-team launches. Agents still cannot",
-		"launch through the API: launch-team on a machine, or the owner from the web (sidebar",
-		"⋯ → New team / Add agent).",
+		"launch through the API: launch-team / launch-agent on a machine, or the owner from the",
+		"web (sidebar ⋯ → New team / Add agent).",
 		"",
 		"CODEX agents, observed today: their Viber MCP calls, message_agent included, have",
 		"been rejected by their approval policy (#609), so they cannot open an exchange — write",
 		"to them FIRST and read their reply on that DM. Their `gh` has no usable token in",
 		"the sandbox (#525): run gh (labels, PR comments) for them.",
 		"",
-		"Never launch agents by calling vibe-master yourself: launch-team (or the web) is the",
-		"ONLY launch path (#660), the one the runner supervises and relaunches.",
+		"Never launch agents by calling vibe-master yourself: launch-team / launch-agent (or the",
+		"web) is the ONLY launch path (#660), the one the runner supervises and relaunches.",
 		"viber-gateway has no --help: an unknown verb runs the startup command (exit 2",
 		"without --dir; with --dir it runs startup on that registry).",
 	].join("\n");

package/lib/claude_tool_defs.ts

@@ -127,7 +127,7 @@ export const CLAUDE_TOOL_DEFS = [
     name: "capabilities",
     description:
       "On-demand: how Viber launches, supervises and dissolves OTHER agents (Codex, " +
-      "Claude, Gemma) — install, the Viber app/runner, viber-gateway launch-team and " +
+      "Claude, Gemma) — install, the Viber app/runner, viber-gateway launch-team, launch-agent and " +
       "dissolve, the web sidebar, orchestrator template admin, Codex limits. " +
       "Call this only when orchestrating other agents is relevant; it is not part " +
       "of the default context. Returns a short usage reference.",

package/lib/codex_default.ts

@@ -0,0 +1,11 @@
+/**
+ * The codex model/effort pair an agent uses when the owner names none (#665) — ONE
+ * place in the channel. It was written as prose three times (capabilities twice, the
+ * team_roles description once; debt noted in PR 675, closed in #673). It must equal the
+ * API's `CODEX_DEFAULT_MODEL` / `CODEX_DEFAULT_EFFORT` (viber-api/src/db/roleFields.ts):
+ * a test reads them from there.
+ */
+export const CODEX_DEFAULT_MODEL = "gpt-5.6-sol";
+export const CODEX_DEFAULT_EFFORT = "low";
+/** As the texts write it: `gpt-5.6-sol / low`. */
+export const CODEX_DEFAULT_PAIR = `${CODEX_DEFAULT_MODEL} / ${CODEX_DEFAULT_EFFORT}`;

package/lib/connect.ts

@@ -22,6 +22,7 @@ import { dirname, isAbsolute, join, relative } from "node:path";
 import { connectAuthPath, isQaBackend } from "./auth.js";
 import { clientFingerprint } from "./fingerprint.js";
 import { cfAccessHeaders } from "./cfAccess.js";
+import { type RecordOutcome, recordConnectedFolder } from "./machine_projects.js";
 
 interface InitResponse {
   confirm_url: string;
@@ -88,6 +89,13 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/** #674 D8 (a): one line on where the Viber app will launch this project's agents. Never fails the connect. */
+export function folderLine(o: RecordOutcome): string {
+  if (o.kind === "recorded") return `The Viber app will launch this project's agents in ${o.folder}`;
+  if (o.kind === "skipped") return `Folder not recorded for the Viber app: ${o.reason}`;
+  return `Folder not recorded for the Viber app (${o.reason}) — it will ask for it at the first launch`;
+}
+
 function writeAuthJson(
   cwd: string,
   data: ConsumedResponse,
@@ -212,7 +220,8 @@ export async function runConnect(
       writeAuthJson(cwd, data, fingerprint, authPath);
       process.stdout.write(
         `\n✓ Connected as ${data.user_email} to project '${data.project_name}'.\n` +
-          `  Wrote ${authPath}\n\n` +
+          `  Wrote ${authPath}\n` +
+          `  ${folderLine(recordConnectedFolder(data.project_id, cwd, authPath))}\n\n` +
           (isQaBackend(baseUrl) ? QA_NEXT_STEPS : DEFAULT_NEXT_STEPS),
       );
       return;

package/lib/fingerprint.ts

@@ -41,7 +41,14 @@ export function getMachineId(): string {
 }
 
 export function clientFingerprint(folderPath: string): string {
-  const machineId = getMachineId();
+  return clientFingerprintWith(getMachineId(), folderPath);
+}
+
+/**
+ * The same fingerprint with the machine id read ONCE by the caller (#674): on Windows
+ * `getMachineId` spawns `reg query`, and the Viber app checks several folders in a row.
+ */
+export function clientFingerprintWith(machineId: string, folderPath: string): string {
   const absPath = normalizePath(realpathSync(folderPath) as string);
   return createHash("sha256").update(`${machineId}:${absPath}`).digest("hex").slice(0, 32);
 }

package/lib/machine_projects.ts

@@ -0,0 +1,344 @@
+/**
+ * machine_projects.ts — the Viber app's project -> folder table, and who may write it (#674, D8).
+ *
+ * The table lives in the app's home (`<home>/projects.json`); the app's runner reads it to know
+ * where to launch a project's agents. It is written where the folder is KNOWN: at
+ * `viber-channel connect` (which writes `.viber/<auth>` IN that folder), once by the app's
+ * catch-up for projects connected before, and by the folder picker. It lives here, not in the
+ * gateway, because the channel is published alone on npm and cannot import the gateway; the
+ * gateway re-exports it.
+ *
+ * ⚠ Bound to ONE backend identity: project ids of dev and staging overlap (measured: 4 and 6), so
+ * a table read for another identity (a home re-enrolled elsewhere) is EMPTY — never a folder of
+ * another backend. ⚠ Several processes write it (connect, the app): every write is serialized by
+ * a lock file and lands by rename, so the table is never read half-written.
+ */
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isDevBackend, isQaBackend } from "./auth.js";
+import { identityBaseUrl } from "./base_urls.js";
+import type { RunnerAuthLite } from "./runner_exec.js";
+import { execFileSync } from "./hidden_proc.js";
+
+/** `%LOCALAPPDATA%\Viber`, or `VIBER_APP_HOME` (tests, a second dev instance). */
+export function appHome(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.VIBER_APP_HOME?.trim();
+  if (override) return override;
+  const local = env.LOCALAPPDATA?.trim();
+  if (!local) throw new Error("LOCALAPPDATA is not set: cannot place the Viber app state");
+  return join(local, "Viber");
+}
+
+export function runnerJsonPath(home: string): string {
+  return join(home, ".viber", "runner.json");
+}
+
+/**
+ * The identity a table belongs to: the enrolled host, else the DEFAULT — never guessed from the
+ * calling process's env: a `connect` run with `VIBER_BASE_URL=dev` must not reinterpret the
+ * app's pre-#627 `runner.json` (the app, started from the Start menu, has no such variable).
+ */
+export function tableIdentity(auth: Pick<RunnerAuthLite, "identity_base_url">): string {
+  return auth.identity_base_url ?? identityBaseUrl({});
+}
+
+/** The identity of the app enrolled in `home`, or undefined when it is not enrolled. */
+export function appIdentity(home: string): string | undefined {
+  const path = runnerJsonPath(home);
+  if (!existsSync(path)) return undefined;
+  return tableIdentity(JSON.parse(readFileSync(path, "utf-8")) as Pick<RunnerAuthLite, "identity_base_url">);
+}
+
+/**
+ * The auth file of a backend, from its identity ALONE. Never `authFilePath()`: it honours
+ * `VIBER_AUTH_FILE`, which would make every folder answer through one same file.
+ */
+export function authFileNameFor(identity: string): string {
+  if (isDevBackend(identity)) return "dev.auth.json";
+  if (isQaBackend(identity)) return "qa.auth.json";
+  return "auth.json";
+}
+
+const LOCK_WAIT_MS = 5000;
+const LOCK_RETRY_MS = 25;
+/** A write holds the lock for milliseconds: no OS query before this. NOT a proof of death. */
+const LOCK_JUDGE_AFTER_MS = 1000;
+/** `performance.timeOrigin` is the runtime start, a little after the OS creation time. */
+const START_TOLERANCE_MS = 5000;
+
+function pause(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * When the process `pid` was created (epoch ms), `null` when there is no such process, `NaN` when
+ * it exists but its creation time cannot be read. A pid ALONE does not identify a process on
+ * Windows: pids are recycled (repo sheet, trap 5).
+ */
+export function processStart(pid: number): number | null {
+  if (process.platform === "win32") {
+    try {
+      const out = execFileSync(
+        "powershell",
+        ["-NoProfile", "-Command", `$p = Get-Process -Id ${pid} -ErrorAction SilentlyContinue; if ($p) { $p.StartTime.ToUniversalTime().ToString('o') }; exit 0`],
+        { encoding: "utf-8" },
+      ).trim();
+      // `exit 0`: a missing pid makes Get-Process fail even when silenced (measured: exit 1).
+      return out === "" ? null : Date.parse(out);
+    } catch {
+      return Number.NaN;
+    }
+  }
+  try {
+    process.kill(pid, 0);
+    return Number.NaN;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM" ? Number.NaN : null;
+  }
+}
+
+export interface TableFs {
+  rename: (from: string, to: string) => void;
+  processStart: (pid: number) => number | null;
+  /** This process: its pid and its creation time, written into the lock. */
+  self: { pid: number; start: number };
+}
+
+const INTEGER_KEY = /^\d+$/;
+
+function integerEntries(o: unknown): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (typeof o === "object" && o !== null) {
+    for (const [k, v] of Object.entries(o)) if (INTEGER_KEY.test(k) && typeof v === "string") out[k] = v;
+  }
+  return out;
+}
+
+interface Table {
+  /** Folders of THIS identity, read at launch. */
+  folders: Record<string, string>;
+  /** Entries of the flat format of before #674: no identity, never read at launch, settled by the catch-up. */
+  unverified: Record<string, string>;
+}
+
+/** The project -> local folder table: recorded at connect (or picked), then read at launch. */
+export class ProjectFolders {
+  private readonly path: string;
+  constructor(
+    home: string,
+    private readonly identity: string,
+    private readonly fs: TableFs = { rename: renameSync, processStart, self: { pid: process.pid, start: Math.round(performance.timeOrigin) } },
+  ) {
+    this.path = join(home, "projects.json");
+  }
+
+  /** A damaged file fails closed: it is neither re-asked nor overwritten. */
+  private table(): Table {
+    if (!existsSync(this.path)) return { folders: {}, unverified: {} };
+    const raw: unknown = JSON.parse(readFileSync(this.path, "utf-8"));
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new Error(`${this.path} is not a JSON object`);
+    const r = raw as Record<string, unknown>;
+    if (typeof r.folders !== "object" || r.folders === null) {
+      // The flat format (an old binary may also have left an `identity` key in it: integer keys only).
+      return { folders: {}, unverified: integerEntries(r) };
+    }
+    if (r.identity !== this.identity) return { folders: {}, unverified: {} }; // another backend's table
+    return { folders: integerEntries(r.folders), unverified: integerEntries(r.unverified) };
+  }
+
+  all(): Record<string, string> {
+    return this.table().folders;
+  }
+
+  unverified(): Record<string, string> {
+    return this.table().unverified;
+  }
+
+  get(projectId: number): string | undefined {
+    return this.table().folders[String(projectId)];
+  }
+
+  set(projectId: number, folder: string): void {
+    this.locked(() => {
+      const t = this.table();
+      t.folders[String(projectId)] = folder;
+      this.write(t);
+    });
+  }
+
+  /**
+   * The catch-up's single write (D8 b): adds each found folder whose id has no LIVE entry (re-read
+   * under the lock — a connect may have written meanwhile), and settles the unverified entries.
+   */
+  settleCatchUp(found: Record<string, string>, exists: (folder: string) => boolean): string[] {
+    const added: string[] = [];
+    this.locked(() => {
+      const t = this.table();
+      for (const [id, folder] of Object.entries(found)) {
+        const current = t.folders[id];
+        if (current !== undefined && exists(current)) continue;
+        t.folders[id] = folder;
+        added.push(id);
+      }
+      this.write({ folders: t.folders, unverified: {} });
+    });
+    return added;
+  }
+
+  private write(t: Table): void {
+    const body: Record<string, unknown> = { identity: this.identity, folders: t.folders };
+    if (Object.keys(t.unverified).length > 0) body.unverified = t.unverified;
+    const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(body, null, 2)}\n`);
+    try {
+      this.fs.rename(tmp, this.path);
+    } catch (err) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        /* nothing left behind */
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * The lock is PUBLISHED COMPLETE (review Codex/Opus): its content is written to a unique temp
+   * file, then hard-linked to the canonical name, which fails if it exists. A crash can therefore
+   * never leave an empty or half-written lock of ours behind.
+   */
+  private locked(work: () => void): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const lock = `${this.path}.lock`;
+    const mine = JSON.stringify({ pid: this.fs.self.pid, start: this.fs.self.start, at: Date.now(), nonce: Math.random() });
+    const draft = `${lock}.${this.fs.self.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+    writeFileSync(draft, mine);
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    try {
+      for (;;) {
+        try {
+          linkSync(draft, lock);
+          break;
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+          // A takeover may take a while (the OS probe): retry at once, before judging the deadline.
+          if (this.takeOverIfDead(lock)) continue;
+          if (Date.now() > deadline) {
+            throw new Error(`${lock} is held by another writer — if no Viber process is running, delete that file`);
+          }
+          pause(LOCK_RETRY_MS);
+        }
+      }
+    } finally {
+      try {
+        unlinkSync(draft);
+      } catch {
+        /* best effort */
+      }
+    }
+    try {
+      work();
+    } finally {
+      // Only OUR lock: never remove one a taker re-created after judging ours dead.
+      try {
+        if (readFileSync(lock, "utf-8") === mine) unlinkSync(lock);
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+
+
+  /**
+   * A lock is taken over only when its holder is GONE: its pid no longer exists, or that pid now
+   * belongs to a process created at another time (recycled). Never on age alone — a suspended or
+   * sleeping writer is alive. By RENAME to a unique name, then checked to be the very lock judged
+   * dead: two takers cannot both win, and a lock re-taken meanwhile is put back.
+   */
+  private takeOverIfDead(lock: string): boolean {
+    let judged: string;
+    try {
+      judged = readFileSync(lock, "utf-8");
+    } catch {
+      return true; // released meanwhile: retry at once
+    }
+    let owner: { pid?: unknown; start?: unknown; at?: unknown } | undefined;
+    try {
+      owner = JSON.parse(judged) as typeof owner;
+    } catch {
+      owner = undefined;
+    }
+    if (owner === undefined || typeof owner !== "object" || owner === null || typeof owner.pid !== "number") {
+      // Unreadable: never one of OURS (published complete) — a crash of an older writer, or damage.
+      // Not "being written": dead once it is older than a write could take (review Opus).
+      try {
+        if (Date.now() - statSync(lock).mtimeMs < LOCK_JUDGE_AFTER_MS) return false;
+      } catch {
+        return true; // gone meanwhile
+      }
+    } else {
+      if (typeof owner.at === "number" && Date.now() - owner.at < LOCK_JUDGE_AFTER_MS) return false;
+      const now = this.fs.processStart(owner.pid);
+      const recycled =
+        now !== null && !Number.isNaN(now) && typeof owner.start === "number" && Math.abs(now - owner.start) > START_TOLERANCE_MS;
+      if (now !== null && !recycled) return false; // alive, or unknown: alive
+    }
+    const grave = `${lock}.${process.pid}.${Date.now()}.dead`;
+    try {
+      this.fs.rename(lock, grave);
+    } catch {
+      return true; // another taker won: retry at once
+    }
+    let taken = "";
+    try {
+      taken = readFileSync(grave, "utf-8");
+    } catch {
+      /* unreadable: treat as not ours */
+    }
+    const ours = taken === judged;
+    if (!ours) {
+      try {
+        linkSync(grave, lock); // put the live writer's lock back, only if none was created since
+      } catch {
+        /* a new lock exists: leave it */
+      }
+    }
+    try {
+      unlinkSync(grave);
+    } catch {
+      /* best effort */
+    }
+    return ours;
+  }
+}
+
+export type RecordOutcome =
+  | { kind: "recorded"; home: string; folder: string }
+  | { kind: "skipped"; reason: string }
+  | { kind: "failed"; reason: string };
+
+/**
+ * D8 (a): after a connect wrote `<folder>/.viber/<authFile>`, record `projectId -> folder` in the
+ * app's table — ONLY when the app serves that backend. The connect is the authority: it replaces
+ * an older entry. The folder is its realpath, the form the fingerprint hashes. Never throws: a
+ * connect must succeed even when this does not.
+ */
+export function recordConnectedFolder(
+  projectId: number,
+  folder: string,
+  authPath: string,
+  env: NodeJS.ProcessEnv = process.env,
+): RecordOutcome {
+  try {
+    const home = appHome(env);
+    const identity = appIdentity(home);
+    if (identity === undefined) return { kind: "skipped", reason: "the Viber app is not enrolled on this machine" };
+    const served = authFileNameFor(identity);
+    if (basename(authPath) !== served) return { kind: "skipped", reason: `the Viber app serves another backend (${identity})` };
+    const real = realpathSync(folder);
+    new ProjectFolders(home, identity).set(projectId, real);
+    return { kind: "recorded", home, folder: real };
+  } catch (err) {
+    return { kind: "failed", reason: (err as Error).message };
+  }
+}

package/lib/team_role_tool.ts

@@ -7,11 +7,12 @@
  * (one tool, an `action`, one definition shared verbatim by the Claude server and
  * the Codex bridge) and the same owner-consent rule.
  *
- * A role is a DEFINITION: this tool launches nothing (launching one agent from a
- * role is #673, not here) — the description must not suggest otherwise.
+ * A role is a DEFINITION: this tool launches nothing — one agent is launched from a
+ * role by `viber-gateway launch-agent` (#673) or the web's Add agent, never here.
  */
 import type { AgentToolResult, AgentToolsContext } from "./agent_tools.js";
 import { callAgentAdmin, errorText, type AdminRequest } from "./agent_admin_call.js";
+import { CODEX_DEFAULT_PAIR } from "./codex_default.js";
 
 export const TEAM_ROLE_ACTIONS = ["list", "get", "create", "update", "delete"] as const;
 type Action = (typeof TEAM_ROLE_ACTIONS)[number];
@@ -29,7 +30,7 @@ export const TEAM_ROLES_TOOL_DEF = {
   name: "team_roles",
   description:
     "Administer the owner's ROLE LIBRARY (#671): reusable role definitions (name, runtime, permission, rolePrompt, model, effort) " +
-    "that team templates reference by name. A role launches nothing by itself; a team template that references it does. " +
+    "that team templates reference by name. This tool launches nothing: a role is launched by `viber-gateway launch-agent` (one agent, see the capabilities tool) or by a team template that references it. " +
     "action: list | get | create | update | delete. " +
     ROLE_OWNER_CONSENT_RULE +
     " Updating a role changes EVERY team template that references it (list shows them in `used_by`), and so what the runner " +
@@ -63,7 +64,7 @@ export const TEAM_ROLES_TOOL_DEF = {
         type: ["string", "null"],
         description:
           "claude: leave model and effort OUT (the runtime picks its own default) UNLESS the owner explicitly asks; model is a family (opus, sonnet, haiku or fable). " +
-          "codex: model AND effort are REQUIRED — use gpt-5.6-sol / low unless the owner asks for another listed model and an effort it accepts. Full rules: the capabilities tool.",
+          `codex: model AND effort are REQUIRED — use ${CODEX_DEFAULT_PAIR} unless the owner asks for another listed model and an effort it accepts. Full rules: the capabilities tool.`,
       },
       effort: {
         type: ["string", "null"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.34",
+  "version": "0.8.36",
   "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": {