viber-channel 0.8.31 → 0.8.33

package/lib/bridge_spawn.ts

@@ -75,6 +75,9 @@ export function createBridgeSpawn(opts: BridgeSpawnOptions = {}): SpawnFn {
 		// authoritatively below (codex-309-review blocking #1).
 		delete env.VIBER_AGENT_NAME_EXPLICIT;
 		delete env.VIBER_AGENT_ROLE;
+		// #665: a parent's codex model/effort must never pin a fresh agent; spec.env may set them.
+		delete env.VIBER_CODEX_MODEL;
+		delete env.VIBER_CODEX_EFFORT;
 		env.VIBER_AGENT_TIER = spec.tier;
 		if (spec.env) Object.assign(env, spec.env);
 		// Identity is set LAST, AFTER spec.env, so neither the inherited env nor a

package/lib/capabilities.ts

@@ -64,7 +64,7 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"  project token); the web's New team / Add agent use the same templates. No local",
 		"  file, no built-in, no cache, no fallback: web unreachable, token refused or name",
 		"  unknown = an error, and NOTHING is launched (an unknown name lists the available",
-		"  ones). A leftover .viber/agent-teams.json is IGNORED (launch-team says so).",
+		"  ones).",
 		"  A template the spawn would refuse (its warnings, see below) is refused up front.",
 		"  Output is verbose; only these lines matter:",
 		"    team: verdict COMPLETE|INCOMPLET — N member(s)",
@@ -80,8 +80,10 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"  launch-<32 hex> (e.g. launch-03f927dc283f94f521b06ee573a9f582); from Viber app",
 		"  0.7.22 on, the bare 32 hex is accepted too (older: pass the launch- prefix);",
 		"  read it on the \"member launch-…: launched\" line.",
-		"  ONLINE DELAY: up to ~45 s after the agent has started, plus the runtime boot",
-		"  (runner beat every 30 s + coverage re-read every 15 s). An empty list_agents right",
+		"  ONLINE DELAY: about 25-35 s from launch-team to online (one agent ~25 s,",
+		"  three at once ~35 s), nearly all of it the runtime boot; the runner reports a",
+		"  new agent within ~4 s of its presence record being written. An older Viber app waits for its",
+		"  30 s beat instead: up to ~60 s. An empty list_agents right",
 		"  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.",
@@ -94,8 +96,9 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"                                   → agent \"g1-dev\", team \"g1-solo\"",
 		"  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: leave them OUT (runtime default) UNLESS the owner explicitly asks",
-		"  for one; claude only: model opus|sonnet|haiku|fable, effort low|medium|high|xhigh|max.",
+		"  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.)",
 		"",
 		"DISSOLVE (stops the processes, then revokes the proven-stopped instances):",
@@ -143,11 +146,16 @@ export function capabilitiesText(channelVersion: string | null = null): string {
 		"    runtime     REQUIRED  claude | codex | gemma",
 		"    permission  REQUIRED  read-only | read-write (gemma: read-only only)",
 		"    rolePrompt  REQUIRED  non-empty, ≤ 600 chars AFTER {prefix} expands to 32 chars",
-		"    model       optional  claude: opus | sonnet | haiku | fable (a family, never a",
-		"                      version); other runtimes: ≤ 64, stored but not applied",
-		"    effort      optional  claude only: low | medium | high | xhigh | max",
-		"                      model/effort: leave them OUT (runtime default) unless the",
-		"                      owner explicitly asks for one",
+		"    model       claude: optional, opus | sonnet | haiku | fable (a family, never a",
+		"                      version); codex: REQUIRED, one of gpt-6.1-sol gpt-6-astra",
+		"                      gpt-6-sol gpt-6-luna gpt-5.6-sol gpt-5.6-terra gpt-5.6-luna",
+		"                      gpt-5.5; gemma: ≤ 64, stored but not applied",
+		"    effort      claude: optional, low | medium | high | xhigh | max;",
+		"                      codex: REQUIRED, one the model accepts — low..xhigh on all,",
+		"                      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",
 		"    count       optional  integer 1..10",
 		"  name: non-empty, ≤ 80, unique per owner, case-insensitive (409 without code = taken).",
 		"  update: send ONLY the fields you change (name / spec / project_id) plus",

package/lib/codex_model_pair.ts

@@ -0,0 +1,166 @@
+/**
+ * #665 — the model and reasoning effort a codex agent runs with.
+ *
+ * vibe-master hands them to the bridge as `VIBER_CODEX_MODEL` / `VIBER_CODEX_EFFORT`: BOTH or
+ * NEITHER. Neither is a role stored before #665 — the bridge then behaves exactly as before (no
+ * catalogue call, no field on `thread/start` / `turn/start`). A pair is:
+ *   - checked ONCE at startup against the catalogue of THIS codex (`model/list`), before any
+ *     thread or turn exists — the target is the pair SET by the template, never the model a
+ *     resumed thread reports (that one is the OLD model);
+ *   - applied on `thread/start` (a fresh thread) and on EVERY `turn/start`, which also moves a
+ *     resumed thread onto the template's model.
+ * Anything it cannot honour stops the bridge with a message naming the pair: no silent fallback.
+ */
+
+export interface CodexPair {
+	model: string;
+	effort: string;
+}
+
+/** A page of `model/list`, as codex-cli 0.159.3 answers it (only the fields read here). */
+export interface ModelListPage {
+	data?: { id?: unknown; model?: unknown; supportedReasoningEfforts?: unknown }[];
+	nextCursor?: unknown;
+}
+
+export type ModelListFetch = (cursor: string | null) => Promise<ModelListPage>;
+
+/** Read the pair from the env: both, or neither (`""` is unset, the #411 convention). */
+export function readCodexPair(env: NodeJS.ProcessEnv): CodexPair | undefined {
+	const model = env.VIBER_CODEX_MODEL?.trim() ?? "";
+	const effort = env.VIBER_CODEX_EFFORT?.trim() ?? "";
+	if (model === "" && effort === "") return undefined;
+	if (model === "" || effort === "") {
+		throw new Error(
+			`codex model/effort must come together: got VIBER_CODEX_MODEL="${model}", VIBER_CODEX_EFFORT="${effort}" — ` +
+				"relaunch from a template that sets both",
+		);
+	}
+	return { model, effort };
+}
+
+/** The `thread/start` fields for a pair (codex has no direct effort field there: it is config). */
+export function threadStartPairParams(pair: CodexPair | undefined): Record<string, unknown> {
+	if (pair === undefined) return {};
+	return { model: pair.model, config: { model_reasoning_effort: pair.effort } };
+}
+
+/** The `turn/start` fields for a pair — they persist for later turns, resumed threads included. */
+export function turnStartPairParams(pair: CodexPair | undefined): Record<string, unknown> {
+	if (pair === undefined) return {};
+	return { model: pair.model, effort: pair.effort };
+}
+
+/** The efforts a catalogue entry accepts (`[{ reasoningEffort }]`, or bare strings). */
+function effortsOf(entry: { supportedReasoningEfforts?: unknown }): string[] {
+	const raw = entry.supportedReasoningEfforts;
+	if (!Array.isArray(raw)) throw new Error("model/list entry without supportedReasoningEfforts");
+	return raw.map((e) => {
+		const v = typeof e === "string" ? e : (e as { reasoningEffort?: unknown } | null)?.reasoningEffort;
+		if (typeof v !== "string") throw new Error("model/list entry with a malformed reasoning effort");
+		return v;
+	});
+}
+
+/** Walk every page of `model/list`; a repeated cursor is a loop, not a catalogue. */
+async function collectCatalogue(fetchPage: ModelListFetch, expired: () => boolean): Promise<Map<string, string[]>> {
+	const catalogue = new Map<string, string[]>();
+	const seen = new Set<string>();
+	let cursor: string | null = null;
+	do {
+		// Past the deadline the caller has already refused: stop asking, do not walk on in the dark.
+		if (expired()) throw new Error("model/list walk stopped at the deadline");
+		const page = await fetchPage(cursor);
+		if (!Array.isArray(page.data)) throw new Error("model/list answered without a data array");
+		for (const entry of page.data) {
+			// `model` is the slug `thread/start` / `turn/start` take, guaranteed by 0.159.3. `id` equals
+			// it today but is not read: an entry without `model` is malformed, not resolved by guess.
+			const id = entry.model;
+			if (typeof id !== "string") throw new Error("model/list entry without a model");
+			catalogue.set(id, effortsOf(entry));
+		}
+		const next = page.nextCursor;
+		if (next !== null && next !== undefined && typeof next !== "string") {
+			throw new Error("model/list answered a non-string nextCursor");
+		}
+		cursor = next ?? null;
+		if (cursor !== null) {
+			if (seen.has(cursor)) throw new Error(`model/list repeated the cursor "${cursor}"`);
+			seen.add(cursor);
+		}
+	} while (cursor !== null);
+	return catalogue;
+}
+
+/**
+ * Throw unless THIS codex's catalogue carries the pair. One deadline covers the whole pagination;
+ * an RPC failure, a malformed answer or the deadline all throw — the caller stops the bridge.
+ */
+export async function verifyCodexPair(
+	pair: CodexPair,
+	fetchPage: ModelListFetch,
+	timeoutMs: number,
+): Promise<void> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let expired = false;
+	const deadline = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => {
+			expired = true;
+			reject(new Error(`model/list did not answer within ${timeoutMs} ms`));
+		}, timeoutMs);
+	});
+	const walk = collectCatalogue(fetchPage, () => expired);
+	walk.catch(() => {}); // after the deadline its own rejection has nobody left to tell
+	let catalogue: Map<string, string[]>;
+	try {
+		catalogue = await Promise.race([walk, deadline]);
+	} catch (err) {
+		const why = err instanceof Error ? err.message : String(err);
+		throw new Error(`cannot check codex model ${pair.model} / effort ${pair.effort}: ${why}`);
+	} finally {
+		clearTimeout(timer);
+	}
+	const efforts = catalogue.get(pair.model);
+	if (efforts === undefined) {
+		throw new Error(
+			`codex model ${pair.model} is absent from the catalogue of THIS codex (has: ${[...catalogue.keys()].join(", ")}) — ` +
+				"update codex or re-edit the template",
+		);
+	}
+	if (!efforts.includes(pair.effort)) {
+		throw new Error(
+			`codex model ${pair.model} does not accept effort ${pair.effort} on THIS codex (accepts: ${efforts.join(", ")}) — ` +
+				"re-edit the template",
+		);
+	}
+}
+
+/**
+ * Why codex is NOT running the pair, judged from what `thread/start` / `thread/resume` answer
+ * (`model`, `reasoningEffort` — the thread's EFFECTIVE settings), or undefined when it is. A null
+ * effort is "not reported", not a mismatch. No pair: nothing to compare (pre-#665 behaviour).
+ */
+export function pairMismatch(
+	pair: CodexPair | undefined,
+	response: unknown,
+	method: string,
+): string | undefined {
+	if (pair === undefined) return undefined;
+	const r = (typeof response === "object" && response !== null ? response : {}) as {
+		model?: unknown;
+		reasoningEffort?: unknown;
+	};
+	if (r.model !== pair.model) {
+		return `codex ${method} runs model ${String(r.model)}, not the template's ${pair.model} — stopping rather than run the wrong model`;
+	}
+	// null = "not reported" (the field is nullable in 0.159.3); absent or any other type is a
+	// malformed answer, refused rather than read as a pass (Codex-2 review of cecd6ff7).
+	if (r.reasoningEffort === null) return undefined;
+	if (typeof r.reasoningEffort !== "string") {
+		return `codex ${method} answered a malformed reasoningEffort (${JSON.stringify(r.reasoningEffort) ?? "absent"}) — stopping rather than guess the effort`;
+	}
+	if (r.reasoningEffort !== pair.effort) {
+		return `codex ${method} runs effort ${r.reasoningEffort}, not the template's ${pair.effort} — stopping rather than run the wrong effort`;
+	}
+	return undefined;
+}

package/lib/coverage_watch.ts

@@ -8,7 +8,8 @@
  *   <presenceDir>/<instance_id>.coverage.json
  *     { lease_active: true|false|null, beat_id, conversation_id, written_at }
  *
- * Every 15 s this module re-reads it (a local read, zero network) and decides:
+ * Every 15 s this module re-reads it (a local read, zero network) — and at once when the file's
+ * mtime changes (#663, checked every second, also local) — and decides:
  *
  *   - fresh coverage, lease true          → ACTIVE;
  *   - lease false                         → the conversation was taken over: the
@@ -31,7 +32,7 @@
  * Freshness is judged on the LOCAL clock of the coverage write (`written_at`),
  * never on the server's beat id.
  */
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { DEFAULT_MAX_INDETERMINATE_LEASE_BEATS } from "./heartbeat.js";
 import { runnerStatePath, readRunnerState } from "./runner_registry.js";
 import { coveragePath } from "./runner_roster.js";
@@ -149,6 +150,26 @@ export interface CoverageWatchOptions {
   log?: (line: string) => void;
   setTimer?: (fn: () => void, ms: number) => unknown;
   clearTimer?: (handle: unknown) => void;
+  /** #663: how often the coverage file's mtime is checked (a local stat, no network). */
+  changeCheckMs?: number;
+  /** #663: the coverage file's mtime in ms, or `null` when absent/unreadable (tests inject it). */
+  coverageMtime?: (path: string) => number | null;
+}
+
+/**
+ * #663 — the agent re-read its coverage every 15 s, so after the runner's beat it could stay
+ * PAUSED (online on the web, yet unable to send or receive) for up to 15 s more. A cheap local
+ * check of the file's mtime now re-reads it as soon as the runner rewrites it. The 15 s re-read
+ * stays: it is what pauses an agent whose coverage went STALE, which no write announces.
+ */
+export const COVERAGE_CHANGE_CHECK_MS = 1_000;
+
+function fileMtime(path: string): number | null {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
 }
 
 export interface CoverageWatch {
@@ -236,9 +257,20 @@ export function startCoverageWatch(opts: CoverageWatchOptions): CoverageWatch {
 
   tick();
   const timer = setTimer(tick, opts.rereadMs ?? COVERAGE_REREAD_MS);
+  const mtimeOf = opts.coverageMtime ?? fileMtime;
+  let lastMtime = mtimeOf(covPath);
+  const changeTimer = setTimer(() => {
+    const m = mtimeOf(covPath);
+    if (m === lastMtime) return;
+    lastMtime = m;
+    if (m !== null) tick();
+  }, opts.changeCheckMs ?? COVERAGE_CHANGE_CHECK_MS);
   return {
     gate,
     tick,
-    stop: () => clearTimer(timer),
+    stop: () => {
+      clearTimer(timer);
+      clearTimer(changeTimer);
+    },
   };
 }

package/lib/gateway_result.ts

@@ -4,7 +4,8 @@
  * ## ⚠ WHY THIS IS A SEPARATE CONTRACT AND NOT AN EXTENSION OF `spawn_reason.ts`
  *
  * JP's decision of 2026-08-27: the gateway's result line is a marker of its OWN. ▶ Widening
- * `parseSpawnResult` to also accept a nonce-less or differently-shaped payload would have reopened
+ * `parseSpawnResult` (the `vibe-master team spawn` reader, removed in #662 once #660 had removed
+ * its emitter) to also accept a nonce-less or differently-shaped payload would have reopened
  * "the last valid marker wins" for `vibe-master`'s marker too — one relaxation, two contracts
  * weakened. ⚠ So the runner learns a SECOND reader rather than loosening the first.
  *
@@ -19,8 +20,8 @@
  * ```
  *
  * ▶▶ So a HALF-LAUNCHED team exits `0`, and a consumer deriving success from the exit code reports
- * `succeeded` — the browser then says "team spawn completed" while members are missing. ⚠ A
- * reason-only marker does not close that: it would be ABSENT on a `0`-exit INCOMPLET team, and an
+ * `succeeded` — the browser then said "team spawn completed" (now "team launch completed")
+ * while members were missing. ⚠ A reason-only marker does not close that: it would be ABSENT on a `0`-exit INCOMPLET team, and an
  * absence is indistinguishable from a success.
  *
  * ⚠ The gateway's exit codes are NOT the defect and are not touched: `0` there means *a result was
@@ -28,7 +29,7 @@
  *
  * ## ▶ THE FALLBACK IS A FAILURE, NEVER A SUCCESS
  *
- * `parseSpawnResult` returns `null` for "no marker" and the caller *degrades to the previous
+ * `parseSpawnResult` returned `null` for "no marker" and its caller *degraded to the previous
  * message* — correct there, because that path's success was already established by the exit code.
  * ⚠ **Here the exit code cannot establish success**, so a `null` must not be readable as one. Rules
  * entry 10: a fallback is only legitimate when its value is IMPOSSIBLE to confuse with a measurement.
@@ -36,8 +37,8 @@
 
 import { SPAWN_REASONS, type SpawnReason } from "./spawn_reason.js";
 
-/** Mirrors `../../viber-gateway/lib/result_marker.ts`. ⚠ Named separately from `VIBEMASTER_RESULT` so
- *  neither reader can be satisfied by the other's line. */
+/** Mirrors `../../viber-gateway/lib/result_marker.ts`. ⚠ Named separately from the former
+ *  `VIBEMASTER_RESULT` so that no reader could be satisfied by the other's line. */
 const GATEWAY_MARKER = "VIBERGATEWAY_RESULT";
 
 /** Bounded at both ends of the pipe, like `vibe-master`'s detail. */

package/lib/presence_trigger.ts

@@ -0,0 +1,112 @@
+/**
+ * presence_trigger.ts — #663: the runner beats when an agent APPEARS, not only on its 30 s tick.
+ *
+ * Measured (plan 663, step-01): an agent's presence record is on disk ~21 s after launch, and the
+ * runner then waited for the next tick of its 30 s beat — 3 to 26 s of pure waiting on 8 launches.
+ *
+ * JP's constraint (2026-10-01): **no more network than today when nothing changes.** So this module
+ * is LOCAL only: it re-lists the presence folder every `intervalMs` (a directory read and one stat
+ * per record — no request), and calls `onChange` when a record is NEW or REWRITTEN (an agent writes
+ * its record at registration, then again when its start time becomes known — the runner skips a
+ * record without one, so that rewrite must trigger too). The caller turns `onChange` into ONE extra
+ * beat, the same request as the periodic one.
+ *
+ * - **Deletions do not trigger.** The beat itself deletes the records the server acknowledged as
+ *   ended; reacting to that would make every such beat schedule another one.
+ * - **Coverage files and the `runner/` folder are ignored**: the beat writes them after each
+ *   acknowledgement, so they must not count as a change either.
+ * - **Debounced**: a team of three writes three records within a second — one beat, not three.
+ * - The first scan is the BASELINE: records already there when the runner starts are covered by the
+ *   runner's own start-up beat.
+ *
+ * ⚠ Why polling and not `fs.watch` (Opus, plan review): on Windows `fs.watch` duplicates events and
+ * reports an atomic write (tmp + rename) as a `rename`; a 2 s directory read is cheap and exact.
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const PRESENCE_SCAN_MS = 2_000;
+export const PRESENCE_DEBOUNCE_MS = 500;
+
+export interface PresenceTriggerOptions {
+  dir: string;
+  onChange: () => void;
+  intervalMs?: number;
+  debounceMs?: number;
+  /** Record file name → mtime (ms). `null` = folder unreadable or absent (treated as empty). */
+  list?: (dir: string) => Map<string, number> | null;
+  setInterval?: (fn: () => void, ms: number) => unknown;
+  clearInterval?: (handle: unknown) => void;
+  setTimeout?: (fn: () => void, ms: number) => unknown;
+  clearTimeout?: (handle: unknown) => void;
+}
+
+export interface PresenceTrigger {
+  /** One scan now (tests, and nothing else needs it). */
+  scan: () => void;
+  stop: () => void;
+}
+
+/** The agent records of a presence folder: `<instance_id>.json`, never `*.coverage.json`. */
+export function listPresenceRecords(dir: string): Map<string, number> | null {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const out = new Map<string, number>();
+  for (const name of names) {
+    if (!name.endsWith(".json") || name.endsWith(".coverage.json")) continue;
+    try {
+      out.set(name, statSync(join(dir, name)).mtimeMs);
+    } catch {
+      // Deleted between the listing and the stat: a deletion, which never triggers.
+    }
+  }
+  return out;
+}
+
+export function startPresenceTrigger(opts: PresenceTriggerOptions): PresenceTrigger {
+  const list = opts.list ?? listPresenceRecords;
+  const setIv = opts.setInterval ?? ((fn: () => void, ms: number) => unrefd(setInterval(fn, ms)));
+  const clearIv = opts.clearInterval ?? ((h: unknown) => clearInterval(h as ReturnType<typeof setInterval>));
+  const setTo = opts.setTimeout ?? ((fn: () => void, ms: number) => unrefd(setTimeout(fn, ms)));
+  const clearTo = opts.clearTimeout ?? ((h: unknown) => clearTimeout(h as ReturnType<typeof setTimeout>));
+  const debounceMs = opts.debounceMs ?? PRESENCE_DEBOUNCE_MS;
+
+  let known: Map<string, number> = list(opts.dir) ?? new Map();
+  let pending: unknown = null;
+  let stopped = false;
+
+  const scan = (): void => {
+    if (stopped) return;
+    const now = list(opts.dir) ?? new Map<string, number>();
+    let changed = false;
+    for (const [name, mtime] of now) {
+      if (known.get(name) !== mtime) changed = true;
+    }
+    known = now;
+    if (!changed || pending !== null) return;
+    pending = setTo(() => {
+      pending = null;
+      if (!stopped) opts.onChange();
+    }, debounceMs);
+  };
+
+  const timer = setIv(scan, opts.intervalMs ?? PRESENCE_SCAN_MS);
+  return {
+    scan,
+    stop: () => {
+      stopped = true;
+      clearIv(timer);
+      if (pending !== null) clearTo(pending);
+      pending = null;
+    },
+  };
+}
+
+function unrefd<T>(h: T): T {
+  (h as { unref?: () => void }).unref?.();
+  return h;
+}

package/lib/runner_exec.ts

@@ -5,9 +5,10 @@
  * Flow (per claimed command): validate the SERVER-VALIDATED role snapshot
  * against the machine's local DEFAULT-DENY policy (permissions = template ∩
  * local, never widened — C3) → report `starting` → shell
- * `vibe-master team spawn` via an argv ARRAY (execFile, never a shell string —
- * no injection) → report `succeeded`/`failed` (fencing-guarded). A 409 report
- * (re-claim/cancel) → cooperative abort (don't overwrite a newer outcome — C4).
+ * `viber-gateway team` via an argv ARRAY (execFile, never a shell string —
+ * no injection), which invokes `vibe-master spawn` once per member → report
+ * `succeeded`/`failed` (fencing-guarded). A 409 report (re-claim/cancel) →
+ * cooperative abort (don't overwrite a newer outcome — C4).
  *
  * Dependency-injected: `runTeamSpawn` (the launcher) and `apiFetch` are
  * injectable so the flow is unit-testable without shelling or a live server.
@@ -19,7 +20,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 import { join } from "node:path";
 import { cfAccessHeaders } from "./cfAccess.js";
 import { gatewayNothingToDo, gatewaySpawnOk, parseGatewayResult } from "./gateway_result.js";
-import { messageForReason, parseSpawnResult, rosterNames, type SpawnReason } from "./spawn_reason.js";
+import { messageForReason, rosterNames, type SpawnReason } from "./spawn_reason.js";
 import { identityBaseUrl } from "./base_urls.js";
 import { recordSpawn, registryPath, type SpawnForRegistry, updateRegistry } from "./runner_registry.js";
 import { relaunchInstance } from "./runner_relaunch.js";
@@ -246,12 +247,10 @@ export type TeamSpawnRunner = (
    * ⚠⚠ #590: **the LAUNCHER states whether the desired state was already in place** — the reader
    * no longer infers it from a bare `reason` string.
    *
-   * ▶ The same word reaches the reader from two launchers with two DIFFERENT guards, and the value
-   * that crossed this boundary carried neither the provenance nor the proof
-   * (`gwl10-review-codex-2`). Each runner now proves its own claim: the gateway through
-   * {@link gatewayNothingToDo} (roster coverage **and** verdict), `vibe-master` through
-   * `classifyCollision`, which emitted this word only when NO roster member was missing
-   * (removed in #660 with `vibe-master team spawn`; no vibe-master command emits it now).
+   * ▶ The value that crossed this boundary used to carry neither the provenance nor the proof
+   * (`gwl10-review-codex-2`). The launcher now proves its own claim: the gateway through
+   * {@link gatewayNothingToDo} (roster coverage **and** verdict). It is the only launcher that
+   * makes one since #660 removed `vibe-master team spawn`.
    *
    * ⚠ **OPTIONAL, and the reader FAILS CLOSED on absence** (`?? false`): an omitted field is *no
    * claim*, never *nothing to do*. ▶ This is deliberately unlike the `nonce` above, which is
@@ -311,10 +310,12 @@ export function vibeMasterBaseCmd(source: NodeJS.ProcessEnv = process.env): stri
   return parts.length > 0 ? parts : ["vibe-master"];
 }
 
-/** Default launcher: shell vibe-master via execFile with an ARGV ARRAY (never a
- *  shell string), a CURATED env, bounded time + output, and process-tree kill on
- *  timeout. The binary is resolved via VIBE_MASTER_CMD (default `vibe-master`). */
-export const execFileTeamSpawn: TeamSpawnRunner = (args, nonce) => {
+/** The single-agent launcher (relaunch path): shell `vibe-master spawn` via execFile
+ *  with an ARGV ARRAY (never a shell string), a CURATED env, bounded time + output,
+ *  and process-tree kill on timeout. The binary is resolved via VIBE_MASTER_CMD
+ *  (default `vibe-master`). `spawn` writes no outcome marker, so the exit code is
+ *  the whole verdict — the gateway path, which has one, is {@link execFileGatewayTeamSpawn}. */
+export const execFileVibeMasterSpawn = (args: string[]): Promise<{ ok: boolean; recap: string }> => {
   const base = vibeMasterBaseCmd();
   const bin = base[0] as string;
   return new Promise((resolve) => {
@@ -323,28 +324,7 @@ export const execFileTeamSpawn: TeamSpawnRunner = (args, nonce) => {
       [...base.slice(1), ...args],
       { timeout: 5 * 60 * 1000, killSignal: "SIGKILL", maxBuffer: 1024 * 1024, env: buildChildEnv() },
       (err, stdout, stderr) => {
-        // #496: read the outcome marker from RAW stderr, BEFORE redaction and
-        // before the 4 000-char cut. The marker is written last, so it is the
-        // first thing `.slice()` drops on a real (verbose) roster — parsing the
-        // recap would pass every test and fail every actual spawn. Redaction can
-        // also mangle the JSON. Both hazards disappear by reading first.
-        const parsed = parseSpawnResult(stderr ?? "", { nonce });
-        const recap = redactSecrets(`${stdout}\n${stderr}`.trim()).slice(0, 4000);
-        resolve({
-          ok: !err,
-          // ▶ #590: vibe-master's OWN guarantee, stated by the launcher that holds it.
-          // ⚠ MEASURED before #660 (`vibe-master/lib/teams.ts`, `classifyCollision`, removed with
-          // `team spawn`; `spawn` never emits a marker, so this now only reads an absent one): this word was emitted only
-          // when `missing.length === 0` — every roster name live — and a non-colliding call returns
-          // `null` before it, so an empty roster cannot produce it either. A partial team is
-          // `partial_team` and stays a failure. ▶ **The same roster-coverage property as the
-          // gateway's, by different code** — so promoting only the gateway path would turn a
-          // CORRECT de-duplication here back into a red, which is the defect JP arbitrated away.
-          nothingToDo: parsed?.reason === "already_running",
-          recap,
-          ...(parsed?.reason ? { reason: parsed.reason } : {}),
-          ...(parsed?.detail ? { detail: parsed.detail } : {}),
-        });
+        resolve({ ok: !err, recap: redactSecrets(`${stdout}\n${stderr}`.trim()).slice(0, 4000) });
       },
     );
   });
@@ -524,7 +504,7 @@ export function buildGatewayTeamArgs(cmd: {
 /**
  * The gateway launcher. ⚠⚠ **`ok` is derived from the MARKER, never from the exit
  * code**, and that is the whole reason this function exists beside
- * {@link execFileTeamSpawn}.
+ * {@link execFileVibeMasterSpawn}.
  *
  * ```
  * viber-gateway/lib/team_spawn_command.ts:358
@@ -532,7 +512,7 @@ export function buildGatewayTeamArgs(cmd: {
  * ```
  *
  * ▶▶ So `ok = !err` would report `succeeded` on a HALF-LAUNCHED team, and the
- * browser would say *team spawn completed* while members are missing. ⚠ The
+ * browser would say *team launch completed* while members are missing. ⚠ The
  * gateway's exit codes are right — `0` means *a result was produced* — and are not
  * touched; what changes is that this consumer stops reading that as *the team is
  * there*.
@@ -758,7 +738,7 @@ async function report(
 
 /**
  * Execute one already-claimed command. Validates against local policy, reports
- * starting → runs the team spawn → reports the outcome (fencing-guarded). A 409
+ * starting → runs the team launch → reports the outcome (fencing-guarded). A 409
  * on the `starting` report means the claim is no longer ours (re-claim/cancel)
  * → cooperative abort BEFORE spawning (never launch on a lost claim). Returns
  * the terminal status the runner recorded (or "aborted").
@@ -768,11 +748,9 @@ export async function executeClaim(
   cmd: ClaimedCommand,
   deps: ExecDeps = {},
 ): Promise<"succeeded" | "failed" | "aborted"> {
-  // ⚠⚠ THE DEFAULT IS THE GATEWAY NOW — that swap IS the junction, and leaving
-  // `execFileTeamSpawn` as the default behind a flag would have been a mechanism
-  // delivered without a junction, the exact shape this workshop has paid for twice.
-  // ▶ `execFileTeamSpawn` stays EXPORTED: it is still the launcher for anything that
-  // talks to `vibe-master` directly, and its witnesses keep measuring that contract.
+  // ⚠⚠ THE DEFAULT IS THE GATEWAY — that swap IS the junction (#590). The only
+  // direct `vibe-master` launcher left is the single-agent relaunch
+  // ({@link execFileVibeMasterSpawn}).
   const runTeamSpawn = deps.runTeamSpawn ?? execFileGatewayTeamSpawn;
   const fetchImpl = deps.apiFetch ?? fetch;
   if (cmd.kind === "relaunch") return executeRelaunchClaim(auth, cmd, deps, fetchImpl);
@@ -860,8 +838,9 @@ export async function executeClaim(
   if (startingStatus < 200 || startingStatus >= 300) return "aborted";
 
   // P1-1: execute EXACTLY the server-validated snapshot. Serialize the already-
-  // validated roles to a temp spec file and invoke `team spawn --spec-file` — so
-  // vibe-master runs THOSE roles, never a name-resolved local template. Serialize
+  // validated roles to a temp spec file and hand it to `viber-gateway team
+  // --spec-file` — so the gateway launches THOSE roles, never a name-resolved
+  // template. Serialize
   // the validated object verbatim (no role rebuild). Cleaned up in `finally`.
   const spec = { name: cmd.template_name, roles: cmd.template_spec.roles };
   const { path: specPath, cleanup } = (deps.writeSpec ?? fsWriteSpec())(spec);
@@ -1004,7 +983,7 @@ export async function executeClaim(
       auth,
       cmd.id,
       ok
-        ? { fencing_token: cmd.fencing_token, status: "succeeded", result: { message: "team spawn completed", log: logPath } }
+        ? { fencing_token: cmd.fencing_token, status: "succeeded", result: { message: "team launch completed", log: logPath } }
         : nothingToDo
         ? {
             fencing_token: cmd.fencing_token,
@@ -1031,8 +1010,8 @@ export async function executeClaim(
                   logRef,
                 )
               : logRef
-                ? `team spawn failed — see ${logRef} on that machine`
-                : "team spawn failed, and the local log could not be written on that machine",
+                ? `team launch failed — see ${logRef} on that machine`
+                : "team launch failed, and the local log could not be written on that machine",
             ...(reason && !nameUnconfirmed ? { reason } : {}),
           },
       fetchImpl,
@@ -1081,7 +1060,7 @@ export async function reconcileOnce(auth: RunnerAuthLite, deps: ExecDeps = {}):
 /**
  * #627 step-07 — a RELAUNCH command: one agent, from this runner's registry. The
  * decision (refuse / re-attach / launch) is `relaunchInstance`'s; this reports it with
- * the same fencing-guarded reports as a team spawn. No automatic retry on failure.
+ * the same fencing-guarded reports as a team launch. No automatic retry on failure.
  */
 async function executeRelaunchClaim(
   auth: RunnerAuthLite,
@@ -1121,7 +1100,7 @@ async function executeRelaunchClaim(
     identity: runnerIdentity(auth),
     ...(deps.relaunchLockDir !== undefined ? { lockDir: deps.relaunchLockDir } : {}),
     ...(deps.relaunchEnumerate !== undefined ? { enumerate: deps.relaunchEnumerate } : {}),
-    runSpawn: deps.runSingleSpawn ?? ((args) => execFileTeamSpawn(args, randomBytes(8).toString("hex"))),
+    runSpawn: deps.runSingleSpawn ?? execFileVibeMasterSpawn,
     checkPolicy: (entry) =>
       validateAgainstPolicy(
         { ...cmd, env: entry.env, template_spec: { roles: [{ ...entry.role }] } },

package/lib/runner_registry.ts

@@ -74,7 +74,7 @@ export interface RegistryRole {
   permission: string;
   rolePrompt?: string;
   model?: string;
-  /** #656: claude reasoning effort, replayed as `--effort` on a relaunch. */
+  /** #656 claude / #665 codex reasoning effort, replayed as `--effort` on a relaunch. */
   effort?: string;
 }
 

package/lib/runner_roster.ts

@@ -350,23 +350,47 @@ export interface RosterBeatDeps {
  * A failed or non-2xx beat changes NOTHING on disk: the coverage then expires on its
  * own and the ended records go again next beat.
  */
-export async function runRosterBeat(auth: RosterBeatAuth, deps: RosterBeatDeps = {}): Promise<"ok" | "revoked"> {
+export function runRosterBeat(
+  auth: RosterBeatAuth,
+  deps: RosterBeatDeps = {},
+  opts: { queueIfBusy?: boolean } = {},
+): Promise<"ok" | "revoked"> {
   // SINGLE-FLIGHT. The enumeration alone can take up to 30 s — one heartbeat period —
   // so an overlapping beat is ordinary, and two answers arriving in reverse order
-  // would rewrite an older coverage over a newer one (Codex, step-03 review). A tick
-  // that finds a beat in flight is skipped: the running one covers it.
-  if (beatInFlight) {
-    noteOnce("a heartbeat was skipped: the previous one is still in flight", deps.log ?? ((l: string) => process.stderr.write(`${l}\n`)));
-    return "ok";
-  }
-  beatInFlight = true;
-  try {
-    return await rosterBeatOnce(auth, deps);
-  } finally {
-    beatInFlight = false;
+  // would rewrite an older coverage over a newer one (Codex, step-03 review). A
+  // PERIODIC tick that finds a beat in flight is skipped: the running one covers it.
+  if (beatInFlight !== null) {
+    if (!opts.queueIfBusy) {
+      noteOnce("a heartbeat was skipped: the previous one is still in flight", deps.log ?? ((l: string) => process.stderr.write(`${l}\n`)));
+      return Promise.resolve("ok");
+    }
+    // #663: a TRIGGERED beat (a presence record appeared or changed) is not dropped: the beat in
+    // flight may have collected its roster BEFORE that record existed, so skipping it would leave
+    // the agent waiting for the next 30 s tick — the very delay the trigger removes. ONE follow-up
+    // beat at most, whatever the number of triggers while busy (Codex, plan review).
+    // ⚠ Chained on the beat's OUTCOME, success or rejection (Opus + Codex review): chained on
+    // success only, a rejected beat left `queuedBeat` pinned to a dead promise for good, and every
+    // later trigger silently lost its follow-up. A `revoked` answer cancels the follow-up (Codex).
+    const followUp = (previous: "ok" | "revoked" | undefined): Promise<"ok" | "revoked"> => {
+      queuedBeat = null;
+      if (previous === "revoked") return Promise.resolve("revoked");
+      return runRosterBeat(auth, deps, { queueIfBusy: true });
+    };
+    queuedBeat ??= beatInFlight.then(followUp, () => followUp(undefined));
+    return queuedBeat;
   }
+  const run = (async () => {
+    try {
+      return await rosterBeatOnce(auth, deps);
+    } finally {
+      beatInFlight = null;
+    }
+  })();
+  beatInFlight = run;
+  return run;
 }
-let beatInFlight = false;
+let beatInFlight: Promise<"ok" | "revoked"> | null = null;
+let queuedBeat: Promise<"ok" | "revoked"> | null = null;
 let unappliedBeats = 0;
 /** #627 (decision A): pending beats before the runner says the handover is slow. */
 export const HANDOVER_WARN_AFTER = 10;

package/lib/runner_stream.ts

@@ -19,8 +19,10 @@ import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { cfAccessHeaders } from "./cfAccess.js";
 import { isTrustedViberOrigin } from "./urls.js";
-import { type ExecDeps, reconcileOnce } from "./runner_exec.js";
+import { type ExecDeps, reconcileOnce, runnerIdentity } from "./runner_exec.js";
 import { runRosterBeat } from "./runner_roster.js";
+import { presenceDir } from "./presence_record.js";
+import { startPresenceTrigger } from "./presence_trigger.js";
 
 /** Remove leftover temp spec files (`.viber/runner-specs/`) from a prior crash
  *  at daemon start — they may hold sensitive rolePrompts (Codex P1-1). The
@@ -127,8 +129,8 @@ async function safeReconcile(auth: RunnerAuth, deps: ExecDeps = {}): Promise<voi
  *
  *  #627: the beat now carries the machine's ROSTER — the only presence signal of
  *  the agents this runner vouches for (`runner_roster.ts`). */
-async function sendHeartbeat(auth: RunnerAuth): Promise<"ok" | "revoked"> {
-  return runRosterBeat(auth, { headers: cfAccessHeaders });
+async function sendHeartbeat(auth: RunnerAuth, queueIfBusy = false): Promise<"ok" | "revoked"> {
+  return runRosterBeat(auth, { headers: cfAccessHeaders }, { queueIfBusy });
 }
 
 export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
@@ -172,15 +174,28 @@ export async function runPersistentRunnerStream(
   // Shared abort so a heartbeat-detected revocation tears down the live SSE now,
   // instead of waiting for the next reconnect.
   let currentAbort: AbortController | null = null;
-  const heartbeatTimer = setInterval(() => {
-    void sendHeartbeat(auth).then((r) => {
-      if (r === "revoked") {
-        revoked = true;
-        stopped = true;
-        currentAbort?.abort();
-      }
-    });
-  }, HEARTBEAT_INTERVAL_MS);
+  const beat = (queueIfBusy: boolean): void => {
+    void sendHeartbeat(auth, queueIfBusy)
+      .then((r) => {
+        if (r === "revoked") {
+          revoked = true;
+          stopped = true;
+          currentAbort?.abort();
+        }
+      })
+      // A beat that throws (process enumeration, a disk read) is logged, never an unhandled
+      // rejection — and the next tick or trigger beats again (Opus review).
+      .catch((err) => process.stderr.write(`[runner] heartbeat error (non-fatal): ${String(err)}\n`));
+  };
+  const heartbeatTimer = setInterval(() => beat(false), HEARTBEAT_INTERVAL_MS);
+  // #663: one beat at START (agents already on the machine are covered at once, not after up to
+  // 30 s), then one more whenever a presence record appears or is rewritten — a LOCAL folder scan,
+  // no request unless something changed. The 30 s tick is unchanged.
+  beat(false);
+  const presenceTrigger = startPresenceTrigger({
+    dir: presenceDir(runnerIdentity(auth)),
+    onChange: () => beat(true),
+  });
   // Reconcile timer is a RE-JITTERED recursive setTimeout (not setInterval): each
   // tick draws a fresh crypto jitter so a fleet never re-synchronizes (Codex C6).
   let reconcileTimer: ReturnType<typeof setTimeout>;
@@ -231,6 +246,7 @@ export async function runPersistentRunnerStream(
     }
   } finally {
     clearInterval(heartbeatTimer);
+    presenceTrigger.stop();
     clearTimeout(reconcileTimer!);
   }
 }

package/lib/spawn_reason.ts

@@ -7,20 +7,19 @@
  * had nowhere to go. The cause existed — it was on the runner's stderr — and was
  * thrown away here.
  *
- * `vibe-master team spawn` emitted a machine line (`VIBEMASTER_RESULT {"reason":…}`);
- * #660 removed that command and its emitter. The live emitter of a team outcome is
- * now `viber-gateway/lib/result_marker.ts` (`VIBERGATEWAY_RESULT`, read by
- * `gateway_result.ts`); the reasons below remain its vocabulary. This module
- * extracts the old line and turns a reason into a sentence the web can show. The runner's OWN refusals (policy,
+ * The emitter of a team outcome is `viber-gateway/lib/result_marker.ts`
+ * (`VIBERGATEWAY_RESULT`, read by `gateway_result.ts`); the reasons below are its
+ * vocabulary. This module turns a reason into a sentence the web can show. The
+ * runner's OWN refusals (policy,
  * unsafe input, a prior partial run) carry reasons from the same vocabulary, so
  * the web never has to speak two languages.
  */
 
-/** Reasons a spawn can be refused. Mirrors vibe-master's vocabulary plus the
- *  four the runner produces itself. The API keeps its own allowlist: an unknown
+/** Reasons a spawn can be refused. The launcher's vocabulary (emitted by
+ *  `viber-gateway/lib/result_marker.ts`) plus the four the runner produces itself. The API keeps its own allowlist: an unknown
  *  reason is dropped there, never stored raw — it comes from a client machine. */
 export const SPAWN_REASONS = [
-  // Emitted by vibe-master
+  // Emitted by the launcher (viber-gateway)
   "already_running",
   "partial_team",
   "template_invalid",
@@ -39,18 +38,6 @@ export const SPAWN_REASONS = [
 
 export type SpawnReason = (typeof SPAWN_REASONS)[number];
 
-const MARKER = "VIBEMASTER_RESULT";
-
-/** Detail is diagnostic context, never shown raw to a user (the server bounds it
- *  again and the web renders from the REASON). Bounded here too so a runaway
- *  child cannot push a megabyte into a report. */
-const DETAIL_MAX = 300;
-
-export interface ParsedSpawnResult {
-  reason: SpawnReason;
-  detail?: string;
-}
-
 /**
  * Keep only the names that belong to THIS command's roster.
  *
@@ -98,72 +85,6 @@ export function rosterNames(
   return names;
 }
 
-/**
- * Extract the outcome marker from RAW child stderr.
- *
- * Read this before the recap is built, never after: the recap is redacted and
- * then cut to 4 000 characters, and the marker is written LAST — exactly the end
- * that the cut removes. A four-member roster overflows that budget easily, so
- * parsing the recap would work in tests and fail on a real spawn.
- *
- * Scans for the LAST line that starts with the marker AND parses AND carries a
- * known reason — not simply the last line. On `launch_failed` the marker is
- * written after child processes have inherited this same stderr, so trailing
- * child output can follow it; and a line quoting the marker inside other text is
- * ignored because the prefix must start the line.
- *
- * Returns null when there is no marker (an older vibe-master, or output lost to
- * a maxBuffer overflow) — the caller then behaves exactly as before.
- */
-export type MarkerTrust =
-  /** Believe only a marker echoing this nonce (the runner path — the default). */
-  | { nonce: string }
-  /** No emitter check at all. Named so a caller cannot fall into it by omission
-   *  (Opus review): an optional nonce silently skipped would reopen "last valid
-   *  marker wins" with no test turning red. Only for reading output nobody
-   *  else could have written into — a human running the CLI, or a unit test. */
-  | { trustUnauthenticated: true };
-
-export function parseSpawnResult(
-  rawStderr: string,
-  trust: MarkerTrust,
-): ParsedSpawnResult | null {
-  const expectedNonce = "nonce" in trust ? trust.nonce : undefined;
-  if (expectedNonce !== undefined && expectedNonce.length === 0) {
-    throw new Error("parseSpawnResult: empty nonce — pass {trustUnauthenticated:true} to skip the check deliberately");
-  }
-  const known = new Set<string>(SPAWN_REASONS);
-  for (const line of rawStderr.split(/\r?\n/).reverse()) {
-    if (!line.startsWith(`${MARKER} `)) continue;
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(line.slice(MARKER.length + 1));
-    } catch {
-      continue; // truncated or interleaved — keep looking further back
-    }
-    if (typeof parsed !== "object" || parsed === null) continue;
-    const { reason, detail, nonce } = parsed as {
-      reason?: unknown;
-      detail?: unknown;
-      nonce?: unknown;
-    };
-    // Emitter proof. Spawned agents inherit this stderr, and an agent working on
-    // THIS repo prints this very contract in its own output — "the last valid
-    // marker wins" would let such a line overrule the real outcome and turn a
-    // launch_failed into a neutral already_running. Only the process we handed
-    // the nonce to can echo it.
-    if (expectedNonce && nonce !== expectedNonce) continue;
-    if (typeof reason !== "string" || !known.has(reason)) continue;
-    return {
-      reason: reason as SpawnReason,
-      ...(typeof detail === "string" && detail.length > 0
-        ? { detail: detail.slice(0, DETAIL_MAX) }
-        : {}),
-    };
-  }
-  return null;
-}
-
 /**
  * The sentence the web shows. Built from the REASON. Where agent names carry the
  * actionable part ("which member is missing"), they go through

package/lib/team_template_tool.ts

@@ -56,8 +56,8 @@ export const TEAM_TEMPLATES_TOOL_DEF = {
         description:
           "The roster, for create/update: { roles: [{ role, runtime, permission, rolePrompt, model?, effort?, count? }] } — same shape `get` returns. " +
           "On update a spec REPLACES the whole spec: send every role. " +
-          "model: leave it OUT (the runtime picks its own default) UNLESS the owner explicitly asks for a model; on claude it is a family: opus, sonnet, haiku or fable. " +
-          "effort (claude only): low, medium, high, xhigh or max — same rule, leave it OUT unless asked. " +
+          "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), effort low, medium, high, xhigh or max. " +
+          "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 field rules: the capabilities tool.",
       },
       project_id: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.31",
+  "version": "0.8.33",
   "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
   "type": "module",
   "bin": {

package/viber-codex-bridge.ts

@@ -123,6 +123,15 @@ import { startBridgeToolHost, type BridgeToolHost } from "./lib/bridge_tool_host
 import type { AgentToolsContext } from "./lib/agent_tools.ts";
 import type { OpenDmResult } from "./lib/peers.ts";
 import { resolveLockDir } from "./lib/lock_dir.ts";
+import {
+  type CodexPair,
+  type ModelListPage,
+  readCodexPair,
+  threadStartPairParams,
+  turnStartPairParams,
+  pairMismatch,
+  verifyCodexPair,
+} from "./lib/codex_model_pair.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) —
@@ -673,7 +682,8 @@ class OutboundTurnTracker {
   }
 }
 
-class CodexAppServer {
+/** Exported for its #665 witnesses only (a fake child stands in for `codex app-server`). */
+export class CodexAppServer {
   private child: ChildProcessWithoutNullStreams;
   private nextId = 1;
   private stdoutBuffer = "";
@@ -700,6 +710,10 @@ class CodexAppServer {
      * env (read through `bearer_token_env_var`) so it never lands in argv/config.
      */
     mcp?: { url: string; bearerEnvVar: string; bearerValue: string },
+    /** #665: the model/effort the template set, or undefined (a role stored before #665). */
+    private readonly pair?: CodexPair,
+    /** Test seam (#665): what launches `codex app-server`. Production passes nothing. */
+    spawnChild: typeof spawn = spawn,
   ) {
     const codexBin = process.env.VIBER_CODEX_BIN?.trim() || "codex";
     const args = ["app-server"];
@@ -735,7 +749,7 @@ class CodexAppServer {
       args.push("-c", `mcp_servers.viber.bearer_token_env_var="${mcp.bearerEnvVar}"`);
       childEnv[mcp.bearerEnvVar] = mcp.bearerValue;
     }
-    this.child = spawn(codexBin, args, {
+    this.child = spawnChild(codexBin, args, {
       cwd: process.cwd(),
       env: childEnv,
       stdio: ["pipe", "pipe", "pipe"],
@@ -800,6 +814,7 @@ class CodexAppServer {
     const existing = state.threads[key]?.thread_id;
     const t0 = nowMs(); // #409: measure thread resume/start (the first-DM cost)
     let resumeAttempted = false;
+    let resumeMismatch: string | undefined;
 
     if (existing && !options.newThread) {
       try {
@@ -813,17 +828,26 @@ class CodexAppServer {
           sandbox: AGENT_SANDBOX,
           developerInstructions: AGENT_INSTRUCTIONS,
           excludeTurns: true,
+          // #665: the pair at resume time too — a resumed thread was created on the model of
+          // its FIRST launch; this moves it onto the template's, like turn/start does.
+          ...threadStartPairParams(this.pair),
         });
         // #409 (Codex): validate/extract the id BEFORE logging success — a malformed
         // response must NOT be logged as resume then again as resume-failed→start.
         const resumedId = extractThreadId(resumed);
-        logTiming("ensureThread", nowMs() - t0, "outcome=resume");
-        return resumedId;
+        // #665: codex answers the thread's EFFECTIVE model — checked, never assumed. A mismatch
+        // leaves this try (it must not fall back to a fresh thread and hide the problem).
+        resumeMismatch = pairMismatch(this.pair, resumed, "thread/resume");
+        if (resumeMismatch === undefined) {
+          logTiming("ensureThread", nowMs() - t0, "outcome=resume");
+          return resumedId;
+        }
       } catch (err) {
         process.stderr.write(
           `[viber-codex-bridge] codex: resume failed (${safeErrorMessage(err)}), starting a fresh thread\n`,
         );
       }
+      if (resumeMismatch !== undefined) this.stopOnPairMismatch(resumeMismatch);
     }
 
     process.stderr.write("[viber-codex-bridge] codex: starting fresh bridge-owned thread\n");
@@ -836,8 +860,18 @@ class CodexAppServer {
       ephemeral: false,
       threadSource: "user",
       sessionStartSource: options.newThread ? "clear" : "startup",
+      ...threadStartPairParams(this.pair),
+    }).catch((err: unknown) => {
+      // #665: a refusal caused by the pair must name it, not surface as a bare RPC error.
+      if (this.pair === undefined) throw err;
+      throw new Error(
+        `codex refused thread/start with model ${this.pair.model} / effort ${this.pair.effort}: ${safeErrorMessage(err)}`,
+      );
     });
     const threadId = extractThreadId(started);
+    // #665: same check on a fresh thread — what codex SAYS it runs, not what we asked.
+    const startMismatch = pairMismatch(this.pair, started, "thread/start");
+    if (startMismatch !== undefined) this.stopOnPairMismatch(startMismatch);
     state.threads[key] = {
       thread_id: threadId,
       conversation_id: options.conversationId,
@@ -867,11 +901,36 @@ class CodexAppServer {
       sandboxPolicy: buildTurnSandboxPolicy(AGENT_TIER),
       developerInstructions: AGENT_INSTRUCTIONS,
       responsesapiClientMetadata: { source: "viber-codex-bridge" },
+      // #665: on EVERY turn — it also moves a resumed thread onto the template's model.
+      ...turnStartPairParams(this.pair),
     });
     const turnId = this.extractTurnId(response);
     return await this.waitForTurn(threadId, turnId);
   }
 
+  /**
+   * #665: check the pair against THIS codex's catalogue (`model/list`) — no thread, no turn, so
+   * it runs before any `turn/start`. No pair: nothing is called (the pre-#665 behaviour).
+   */
+  /** #665: codex is not running the template's pair — stop the bridge in clear, never run on. */
+  private stopOnPairMismatch(reason: string): never {
+    process.stderr.write(`${LOG_PREFIX} #665: ${reason}\n`);
+    this.onUnexpectedExit?.(reason);
+    throw new Error(reason);
+  }
+
+  async verifyPair(timeoutMs: number): Promise<void> {
+    if (this.pair === undefined) return;
+    await verifyCodexPair(
+      this.pair,
+      async (cursor) => (await this.request("model/list", { cursor, includeHidden: false })) as ModelListPage,
+      timeoutMs,
+    );
+    process.stderr.write(
+      `${LOG_PREFIX} #665: codex model ${this.pair.model} / effort ${this.pair.effort} — found in this codex's catalogue\n`,
+    );
+  }
+
   close(): void {
     this.closing = true;
     this.child.kill();
@@ -1382,6 +1441,8 @@ function setupCodexRuntime(deps: {
   requestShutdown: (err: BridgeShutdownError) => void;
   /** #627: why the bridge is paused (null = may write). */
   pauseReason: () => string | null;
+  /** #665: the template's model/effort, or undefined. */
+  pair: CodexPair | undefined;
 }): { codex: CodexAppServer; toolHost: BridgeToolHost } {
   const { tracker } = deps;
   const bridgeToolsCtx: AgentToolsContext = {
@@ -1417,10 +1478,39 @@ function setupCodexRuntime(deps: {
       deps.requestShutdown(new BridgeShutdownError(reason, 3));
     },
     { url: toolHost.url, bearerEnvVar: "VIBER_MCP_TOKEN", bearerValue: toolHost.bearerToken },
+    deps.pair,
   );
   return { codex, toolHost };
 }
 
+/** #665: one deadline for the whole `model/list` walk at startup (it may refresh over network). */
+const CODEX_PAIR_CHECK_TIMEOUT_MS = 30_000;
+
+/**
+ * #665: initialize codex and check its pair. On ANY failure — initialize, catalogue refusal,
+ * deadline — `release` runs (child, tool host, lock) BEFORE the error leaves as a
+ * BridgeShutdownError (a refused pair) or as itself (initialize): on the `--conversation` path nothing
+ * else would release them.
+ */
+export async function startCheckedCodex(
+  codex: Pick<CodexAppServer, "initialize" | "verifyPair">,
+  timeoutMs: number,
+  release: () => void,
+): Promise<void> {
+  try {
+    await codex.initialize();
+  } catch (err) {
+    release();
+    throw err; // unchanged type: an initialize failure stays a crash, as before #665 (Opus review)
+  }
+  try {
+    await codex.verifyPair(timeoutMs);
+  } catch (err) {
+    release();
+    throw new BridgeShutdownError(safeErrorMessage(err), 2); // a refused pair is a deliberate end
+  }
+}
+
 function logCodexSafety(): void {
   process.stderr.write(
     `${LOG_PREFIX} codex safety: tier=${AGENT_TIER}, sandbox=${AGENT_SANDBOX}, approvalPolicy=${AGENT_APPROVAL_POLICY}, network=${networkForTier(AGENT_TIER)}, ` +
@@ -1436,6 +1526,8 @@ function logCodexSafety(): void {
 
 export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
   const options = parseArgs(argv);
+  // #665: both or neither — a partial pair stops the bridge HERE, before any identity or child.
+  const pair = readCodexPair(process.env);
   const { auth, fingerprint } = loadBridgeAuthAndFingerprint();
   // #317 (iii): per-turn outbound tracker (anti-double-post + send_message target).
   const tracker = new OutboundTurnTracker();
@@ -1512,10 +1604,20 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
           startConversation: helpers.startConversation,
           requestShutdown: helpers.requestShutdown,
           pauseReason: helpers.pauseReason,
+          pair,
         });
         codex = rt.codex;
         toolHost = rt.toolHost;
         await codex.initialize();
+        // #665: before the control stream opens, so before any join, thread or turn. A refusal is
+        // a deliberate end (presence `ended`), never a crash the runner would read as alive.
+        try {
+          await codex.verifyPair(CODEX_PAIR_CHECK_TIMEOUT_MS);
+        } catch (err) {
+          const stop = new BridgeShutdownError(safeErrorMessage(err), 2);
+          helpers.requestShutdown(stop);
+          throw stop;
+        }
         logCodexSafety();
       },
       onShutdown: () => {
@@ -1570,10 +1672,19 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<void
         if (!shutdown.signal.aborted) shutdown.abort(err);
       },
       pauseReason: () => gateRef.gate?.reason() ?? REASON_STARTING,
+      pair,
     });
     codex = rt.codex;
     toolHost = rt.toolHost;
-    await codex.initialize();
+    // #665: before the presence record and the stream, so before any turn. This runs BEFORE the
+    // try/finally below, so a failure must release what is already held (Codex-2 review of d6d127a5).
+    const started = codex;
+    const host = toolHost;
+    await startCheckedCodex(started, CODEX_PAIR_CHECK_TIMEOUT_MS, () => {
+      started.close();
+      host.stop();
+      res.bridgeLock.release();
+    });
     logCodexSafety();
     process.stderr.write(`${LOG_PREFIX} ready: joined ${res.minted.conversation_id} as instance ${res.instanceKey.slice(0, 8)}\n`);
     // #315: no control stream here, so beat the instance liveness directly.