viber-channel 0.8.17 → 0.8.19

package/lib/auth.ts

@@ -1,5 +1,5 @@
 import { chmodSync, readFileSync, writeFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { basename, isAbsolute, join } from "node:path";
 
 export interface AuthJson {
   schema_version: number;
@@ -63,15 +63,81 @@ export function isDevBackend(
  * silently authenticated against the dev backend with STAGING creds (`-32000`)
  * because only `VIBER_BASE_URL` was set and the auth file defaulted to staging.
  */
-export function authFilePath(cwd: string = process.cwd()): string {
+export function authFilePath(
+  cwd: string = process.cwd(),
+  baseUrl: string = process.env.VIBER_BASE_URL ?? "",
+): string {
+  const qa = isQaBackend(baseUrl);
   const override = process.env.VIBER_AUTH_FILE;
   if (override !== undefined && override.trim() !== "") {
+    assertAuthFileMatchesBackend(basename(override), qa);
     return isAbsolute(override) ? override : join(cwd, override);
   }
-  const file = isDevBackend() ? "dev.auth.json" : "auth.json";
+  const file = isDevBackend(baseUrl) ? "dev.auth.json" : qa ? QA_AUTH_FILE : "auth.json";
   return join(cwd, ".viber", file);
 }
 
+/**
+ * #613: the auth file `connect` must write for a claim URL. The CLAIM decides
+ * for qa: `connect https://viber-qa.dgypx.dev/connect/<id>` run with no
+ * VIBER_BASE_URL would otherwise derive the file from the (empty) env and write
+ * qa credentials into `auth.json`, overwriting STAGING's. A set env that
+ * contradicts the claim (qa vs not qa) is refused. Non-qa claims keep the
+ * pre-#613 behavior (file derived from the env) unchanged.
+ */
+export function connectAuthPath(
+  claimBaseUrl: string,
+  cwd: string = process.cwd(),
+  envBaseUrl: string = process.env.VIBER_BASE_URL ?? "",
+): string {
+  const claimQa = isQaBackend(claimBaseUrl);
+  if (envBaseUrl.trim() !== "" && claimQa !== isQaBackend(envBaseUrl)) {
+    throw new Error(
+      `claim URL ${claimBaseUrl} and VIBER_BASE_URL=${envBaseUrl} disagree on the qa backend; refusing to write credentials`,
+    );
+  }
+  return authFilePath(cwd, claimQa ? claimBaseUrl : envBaseUrl);
+}
+
+/** #613: the qa web host. Matched EXACTLY (hostname), never by substring. */
+export const QA_WEB_HOST = "viber-qa.dgypx.dev";
+export const QA_AUTH_FILE = "qa.auth.json";
+
+/**
+ * #613: true only when `VIBER_BASE_URL` is the qa web host. Same raw-env
+ * classification rule as {@link isDevBackend} (never the API transport host),
+ * but an exact hostname match: a substring test would let any host containing
+ * "qa" read qa credentials, or a qa host fall through to STAGING's auth.json.
+ */
+export function isQaBackend(
+  baseUrl: string = process.env.VIBER_BASE_URL ?? "",
+): boolean {
+  try {
+    return new URL(baseUrl).hostname === QA_WEB_HOST;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * #613: a `VIBER_AUTH_FILE` override still wins, but a CONTRADICTORY one is
+ * refused instead of resolved in silence: qa credentials against another
+ * backend, or another env's well-known file against the qa backend. Custom
+ * file names stay allowed on both sides.
+ */
+function assertAuthFileMatchesBackend(file: string, qa: boolean): void {
+  if (!qa && file === QA_AUTH_FILE) {
+    throw new Error(
+      `VIBER_AUTH_FILE points at ${QA_AUTH_FILE} but VIBER_BASE_URL is not https://${QA_WEB_HOST}`,
+    );
+  }
+  if (qa && (file === "auth.json" || file === "dev.auth.json")) {
+    throw new Error(
+      `VIBER_BASE_URL is the qa backend but VIBER_AUTH_FILE points at ${file} (another env's credentials)`,
+    );
+  }
+}
+
 export function loadAuth(cwd: string = process.cwd()): AuthJson {
   const path = authFilePath(cwd);
   let raw: string;

package/lib/bridge_core.ts

@@ -306,11 +306,13 @@ export async function postBridgeReply(opts: {
 	ownPostedIds: Set<string>;
 	signal?: AbortSignal;
 	logPrefix: string;
+	/** Fetch seam (#606) — see postMessage. Defaults to the global fetch. */
+	fetchImpl?: typeof fetch;
 }): Promise<void> {
 	const { baseUrl, runtime, text, ownPostedIds, signal, logPrefix } = opts;
 	let result;
 	try {
-		result = await postMessage(baseUrl, runtime.id, runtime.token, text, undefined, signal);
+		result = await postMessage(baseUrl, runtime.id, runtime.token, text, undefined, signal, opts.fetchImpl ?? fetch);
 	} catch (err) {
 		if (err instanceof ConversationTokenExpiredError) {
 			throw new BridgeShutdownError("conversation token expired", 3);
@@ -345,6 +347,93 @@ export function decideTurnPostAction(opts: {
 	return "auto-post";
 }
 
+/** Max length of the runtime cause quoted verbatim in a channel failure notice. */
+const FAILURE_CAUSE_MAX = 400;
+
+/** Transport degradation observed during a turn (#606 step-02, codex only). */
+export type TurnDegradation = { events: number; lastStatus?: number };
+
+/**
+ * #606 — the text a bridge posts on the CHANNEL when a turn fails.
+ *
+ * The whole point of the issue is that a failed turn was written to stderr only,
+ * so the model filled the silence with an INVENTED cause. This text therefore
+ * quotes what the runtime said, VERBATIM and truncated, and adds nothing of its
+ * own: no classification, no advice, no guess. Pure (no clock, no network) so it
+ * is testable without a harness.
+ */
+export function failureNoticeText(err: unknown, degradation?: TurnDegradation): string {
+	const raw = safeErrorMessage(err).replace(/\s+/g, " ").trim();
+	const cause = raw.length > FAILURE_CAUSE_MAX ? `${raw.slice(0, FAILURE_CAUSE_MAX)}...` : raw || "(aucun detail)";
+	let text = `Tour echoue, aucune reponse produite. Cause rapportee par le runtime: ${cause}`;
+	if (degradation && degradation.events > 0) {
+		const status = degradation.lastStatus ? `, dernier statut HTTP ${degradation.lastStatus}` : "";
+		text += ` (transport degrade: ${degradation.events} evenement(s) avant l'echec${status})`;
+	}
+	return text;
+}
+
+/**
+ * #606 — the dedup signature of a failure cause.
+ *
+ * A blown quota fails EVERY subsequent turn: without dedup the fix that makes a
+ * failure speak would flood the channel. Two failures of the same cause must
+ * therefore yield the SAME key, so the volatile identifiers a runtime stamps on
+ * each attempt (turnId, threadId, cf-ray, timestamps, long hex ids) are stripped.
+ *
+ * The degradation COUNT is deliberately reduced to its presence, never its value:
+ * keying on the number would make every different N a "new cause" and re-open the
+ * flood the dedup exists to close.
+ */
+export function failureCauseKey(err: unknown, degradation?: TurnDegradation): string {
+	const normalized = safeErrorMessage(err)
+		.replace(/"(?:turnId|threadId|conversationId|requestId)"\s*:\s*"[^"]*"/g, "")
+		// STOPS at a JSON delimiter (review codex P2a). `\S+` here crossed the
+		// closing quote and ate everything up to the next SPACE — measured: two
+		// errors differing only by httpStatusCode 503 vs 429 collapsed onto
+		// `Codex turn failed: {"message":"Request failed,` because the status sat
+		// AFTER the cf-ray. A normalisation that eats the discriminator gags the
+		// second outage: the exact defect this key exists to avoid.
+		.replace(/cf-ray:\s*[^\s",}\]]+/gi, "")
+		.replace(/\d{4}-\d{2}-\d{2}T[\d:.]+Z?/g, "")
+		// The RESET INSTANT of a quota, in the two shapes our own log carries for
+		// the same outage (review codex, .raw l.95 vs l.111): with the date and
+		// without. Stripping only the clock left them on different keys, so the
+		// same cause announced twice.
+		.replace(
+			/\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{1,2}(?:st|nd|rd|th)?,?\s*\d{4}\b/gi,
+			"",
+		)
+		.replace(/\b\d{1,2}:\d{2}(:\d{2})?\s*(AM|PM)?\b/gi, "")
+		.replace(/\b[0-9a-f]{12,}\b/gi, "")
+		.replace(/\s+/g, " ")
+		.trim();
+	const degraded = degradation && degradation.events > 0 ? "|degraded" : "";
+	// WHOLE, neither truncated nor hashed (review codex, both passes). Slicing to a
+	// display bound made the key lose identity past that bound — two errors sharing
+	// a long prefix became one cause and the second was silenced. A digest fixed
+	// that but kept a residual collision, which costs a SUPPRESSED notice: the
+	// defect this key exists to prevent, made rare instead of impossible.
+	// There is no size constraint to trade against: the key is one closure variable
+	// holding one cause at a time. Keeping the normalised string entire removes the
+	// class rather than shrinking it — a display concern must not decide identity,
+	// which is the whole lesson of P2b.
+	return `${normalized}${degraded}`;
+}
+
+/**
+ * #606 step-02 — read the transport degradation a runtime attached to the error
+ * it threw. The failing turn never returns a TurnResult, so the count cannot ride
+ * on one; the codex bridge stamps it on the Error itself. Any runtime that stamps
+ * nothing (gemma: a single fetch, no intermediate transport events to observe)
+ * simply yields undefined, and the notice omits the clause.
+ */
+export function readTurnDegradation(err: unknown): TurnDegradation | undefined {
+	const d = (err as { degradation?: unknown })?.degradation as TurnDegradation | undefined;
+	if (!d || typeof d.events !== "number" || d.events <= 0) return undefined;
+	return { events: d.events, lastStatus: typeof d.lastStatus === "number" ? d.lastStatus : undefined };
+}
+
 /**
  * #429 cross-run dedup, mirror of dm_stream's `forwardMessage` guard (L146-147).
  * True when this id was already DELIVERED in a prior run and must be skipped on a
@@ -570,6 +659,34 @@ export async function sseLoop(opts: {
 	const sseUrl = buildSseUrl(minted.ws_url, minted.conversation_id);
 	const ownPostedIds = new Set<string>();
 
+	// #606 anti-flood state: the cause key of the LAST failure actually announced
+	// on the channel. A blown quota fails every subsequent turn, so announcing each
+	// one would replace a silence bug with a spam bug. Closure state, owned by this
+	// loop — no module singleton (.claude/rules/architecture.md §7).
+	// Cross-RUN note. This comment CLAIMED the key survives a re-join; it does not,
+	// and N.11 measures the opposite (review codex, prose-has-no-test: the code was
+	// right, the sentence was false). What actually happens: the watermark
+	// deliberately does NOT advance on a failed reply (at-least-once retry, see
+	// below), so a re-join replays the message and fails again — and since each
+	// sseLoop call owns a FRESH closure, that re-join announces once more. Same for
+	// a process restart. Deliberate: a bridge that comes back and hits the same wall
+	// is information. Within one join, the key is what stops the flood.
+	let lastAnnouncedCause: string | undefined;
+
+	/**
+	 * #606 — a DELIVERED turn means the previous cause is over: rearm the notice.
+	 *
+	 * Lives HERE, on the turn outcome, and not at a caller. Review F2 measured why:
+	 * written at the text caller only, the VOICE path never rearmed, so
+	 * text-fails → voice-recovers → text-fails-again left the third failure GAGGED
+	 * — the issue's own defect, reproduced by the issue's fix. Placing it on the
+	 * outcome removes the class instead of patching the two paths that exist today.
+	 * An ABORTED turn never gets here: teardown says nothing about runtime health.
+	 */
+	function rearmFailureNotice(): void {
+		lastAnnouncedCause = undefined;
+	}
+
 	// Run one turn for `content` via the injected runtime, then auto-post its
 	// reply UNLESS an outbound tool already posted this turn (anti-double-post).
 	// Returns true when the reply was dropped because the stream was aborted
@@ -598,12 +715,15 @@ export async function sseLoop(opts: {
 				return true;
 			case "suppress-outbound":
 				process.stderr.write(`${logPrefix} outbound tool posted this turn on ${runtime.id}; suppressing final auto-post\n`);
+				rearmFailureNotice();
 				return false;
 			case "skip-empty":
 				process.stderr.write(`${logPrefix} turn on ${runtime.id} produced no text and used no outbound tool; nothing to deliver\n`);
+				rearmFailureNotice();
 				return false;
 			case "auto-post":
-				await postBridgeReply({ baseUrl: baseUrl(), runtime, text: reply, ownPostedIds, signal, logPrefix });
+				await postBridgeReply({ baseUrl: baseUrl(), runtime, text: reply, ownPostedIds, signal, logPrefix, fetchImpl });
+				rearmFailureNotice();
 				return false;
 		}
 	}
@@ -652,6 +772,49 @@ export async function sseLoop(opts: {
 			.finally(() => ackInFlightIds.delete(idStr));
 	}
 
+
+	/**
+	 * #606 — say a failed turn on the CHANNEL, best-effort.
+	 *
+	 * Deliberately unable to make things worse:
+	 *  - the transport may be the very thing that broke (the measured case was a
+	 *    503 storm), so a failing notice is swallowed to stderr, NEVER retried and
+	 *    never rethrown — one failure must not become two;
+	 *  - it posts through postBridgeReply, so the notice id lands in ownPostedIds
+	 *    like any other reply and cannot feed itself back through handleInboundMessage;
+	 *  - the cause key is recorded only AFTER a post that actually succeeded, so a
+	 *    lost notice does not silence the next one.
+	 */
+	async function announceTurnFailure(err: unknown): Promise<void> {
+		const degradation = readTurnDegradation(err);
+		const key = failureCauseKey(err, degradation);
+		if (key === lastAnnouncedCause) {
+			process.stderr.write(`${logPrefix} failure notice suppressed (same cause as the previous one)\n`);
+			return;
+		}
+		try {
+			await postBridgeReply({
+				baseUrl: baseUrl(),
+				runtime,
+				text: failureNoticeText(err, degradation),
+				ownPostedIds,
+				signal,
+				logPrefix,
+				fetchImpl,
+			});
+			lastAnnouncedCause = key;
+		} catch (notifyErr) {
+			// Includes BridgeShutdownError from an expired token: swallowed here on
+			// purpose. CONSEQUENCE, named because it is not obvious (review F3): a
+			// token expiry first met BY THE NOTICE is discovered later, on the next
+			// turn, instead of shutting the bridge down now. Accepted — this path
+			// runs while ALREADY handling a failure; escalating a
+			// shutdown from the notice would turn "the agent could not answer" into
+			// "the agent died", which is a worse report than the one we came to give.
+			process.stderr.write(`${logPrefix} failure notice could not be posted: ${safeErrorMessage(notifyErr)}\n`);
+		}
+	}
+
 	async function handleInboundMessage(msg: ConversationMessage): Promise<boolean> {
 		const idStr = msg.id !== undefined && msg.id !== null ? String(msg.id) : undefined;
 		// TRUTHY check (not `!== undefined`): idStr === "" must yield NaN, not
@@ -688,6 +851,7 @@ export async function sseLoop(opts: {
 		} catch (err) {
 			if (err instanceof BridgeShutdownError) throw err;
 			process.stderr.write(`${logPrefix} failed to handle message: ${safeErrorMessage(err)}\n`);
+			await announceTurnFailure(err);
 		}
 		return options.once === true;
 	}
@@ -810,6 +974,12 @@ export async function sseLoop(opts: {
 							} catch (err) {
 								if (err instanceof BridgeShutdownError) throw err;
 								process.stderr.write(`${logPrefix} failed to handle transcription: ${safeErrorMessage(err)}\n`);
+								// #606: a VOICE turn that fails was the second silent swallow in this
+								// same chain — found while building the tests, not by the grep on
+								// "failed to handle message", which only ever proved the uniqueness of
+								// the TEXT path. A user speaking to a dead runtime deserves the same
+								// notice as one typing to it.
+								await announceTurnFailure(err);
 							}
 							if (options.once) return;
 						}

package/lib/connect.ts

@@ -19,7 +19,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, isAbsolute, join, relative } from "node:path";
-import { authFilePath } from "./auth.js";
+import { connectAuthPath, isQaBackend } from "./auth.js";
 import { clientFingerprint } from "./fingerprint.js";
 import { cfAccessHeaders } from "./cfAccess.js";
 
@@ -50,6 +50,21 @@ interface TerminalResponse {
 
 type PollResponse = ConsumedResponse | PendingResponse | TerminalResponse;
 
+const DEFAULT_NEXT_STEPS =
+  `Next steps:\n` +
+  `  1. Register the channel MCP server (one-time per machine):\n` +
+  `       claude mcp add viber-channel --scope user -- bunx viber-channel@latest\n` +
+  `  2. Restart Claude Code in this directory.\n\n`;
+
+// #613: qa never runs the published channel — the default advice would be wrong
+// at the exact moment of the qa gesture.
+export const QA_NEXT_STEPS =
+  `Next steps (qa):\n` +
+  `  1. Run the channel FROM SOURCE in the Gateway worktree: register viber-qa-channel\n` +
+  `     in its local .mcp.json (bun ./viber-channel/viber-channel.ts,\n` +
+  `     VIBER_BASE_URL=https://viber-qa.dgypx.dev). NEVER bunx viber-channel@latest.\n` +
+  `  2. See plans/613-env-qa (mount procedure).\n\n`;
+
 const POLL_INTERVAL_MS = 2000;
 const MAX_POLL_DURATION_MS = 10 * 60 * 1000;
 
@@ -77,6 +92,7 @@ function writeAuthJson(
   cwd: string,
   data: ConsumedResponse,
   fingerprint: string,
+  authPath: string,
 ): void {
   const viberDir = join(cwd, ".viber");
   mkdirSync(viberDir, { recursive: true });
@@ -85,7 +101,7 @@ function writeAuthJson(
   // credentials to the same file the channel will read (e.g. dev.auth.json),
   // instead of silently writing auth.json while the channel reads elsewhere.
   // readme.md + .gitignore stay in <cwd>/.viber regardless.
-  const authPath = authFilePath(cwd);
+  // #613: `authPath` comes from connectAuthPath (the claim decides for qa).
   mkdirSync(dirname(authPath), { recursive: true });
 
   const auth: Record<string, unknown> = {
@@ -159,6 +175,8 @@ export async function runConnect(
   cwd: string = process.cwd(),
 ): Promise<void> {
   const { baseUrl, claimId } = parseClaimUrl(claimUrl);
+  // #613: resolved BEFORE any network call, so a contradiction fails early.
+  const authPath = connectAuthPath(baseUrl, cwd);
 
   const fingerprint = clientFingerprint(cwd);
   process.stderr.write(
@@ -191,14 +209,11 @@ export async function runConnect(
     }
     const data = (await pollResp.json()) as PollResponse;
     if (data.status === "consumed") {
-      writeAuthJson(cwd, data, fingerprint);
+      writeAuthJson(cwd, data, fingerprint, authPath);
       process.stdout.write(
         `\n✓ Connected as ${data.user_email} to project '${data.project_name}'.\n` +
-          `  Wrote ${authFilePath(cwd)}\n\n` +
-          `Next steps:\n` +
-          `  1. Register the channel MCP server (one-time per machine):\n` +
-          `       claude mcp add viber-channel --scope user -- bunx viber-channel@latest\n` +
-          `  2. Restart Claude Code in this directory.\n\n`,
+          `  Wrote ${authPath}\n\n` +
+          (isQaBackend(baseUrl) ? QA_NEXT_STEPS : DEFAULT_NEXT_STEPS),
       );
       return;
     }

package/lib/gateway_result.ts

@@ -0,0 +1,266 @@
+/**
+ * gateway_result.ts — the runner's half of `viber-gateway team`'s result contract.
+ *
+ * ## ⚠ 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
+ * "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.
+ *
+ * ## ⚠⚠ AND IT CARRIES A VERDICT, NOT ONLY A REASON — that asymmetry with `parseSpawnResult` is the fix
+ *
+ * Measured at `e9495114`:
+ *
+ * ```
+ * ../../viber-gateway/lib/team_spawn_command.ts:358
+ *     "An INCOMPLET team whose members all reached a verdict is a RESULT, not a crash: 0"
+ * lib/runner_exec.ts   resolve({ ok: !err, ... })   ->  `err` is set on a NON-ZERO exit only
+ * ```
+ *
+ * ▶▶ 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
+ * 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
+ * produced*, which is true. **The defect was reading that as *the team is there*.**
+ *
+ * ## ▶ THE FALLBACK IS A FAILURE, NEVER A SUCCESS
+ *
+ * `parseSpawnResult` returns `null` for "no marker" and the caller *degrades 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.
+ */
+
+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. */
+const GATEWAY_MARKER = "VIBERGATEWAY_RESULT";
+
+/** Bounded at both ends of the pipe, like `vibe-master`'s detail. */
+const DETAIL_MAX = 300;
+
+const VERDICTS = ["COMPLETE", "INCOMPLET", "REFUSED"] as const;
+export type GatewayVerdict = (typeof VERDICTS)[number];
+
+export interface ParsedGatewayResult {
+  /** ⚠ `COMPLETE` is the ONLY value a caller may read as success. */
+  verdict: GatewayVerdict;
+  /**
+   * ⚠⚠ *Must someone go LOOK?* — the distinction the gateway's EXIT CODE carries and the verdict does
+   * not, and the one step-05 says the machine line owes: *"a caller cannot tell 'usage error' from 'a
+   * tree may be standing', and that is the only distinction that decides whether someone must go
+   * LOOK."*
+   *
+   * ▶ An `INCOMPLET` team may or may not have left a tree standing, so a consumer that wants to know
+   * whether to hunt cannot get it from the verdict. ⚠ **Defaults to `true` when the field is missing**
+   * — see {@link parseGatewayResult}: on this question the safe default is *go look*, because the
+   * expensive direction is believing nothing is standing when something is.
+   */
+  noVerdictTreeMayStand: boolean;
+  /** Absent when the gateway could not name the outcome truthfully in this vocabulary. ⚠ Then the
+   *  caller has a proven FAILURE with no cause to render — which is honest, and is not a success. */
+  reason?: SpawnReason;
+  detail?: string;
+}
+
+/**
+ * Extract the gateway's marker from RAW stderr.
+ *
+ * Read BEFORE the recap is redacted and cut, for the reason `spawn_reason.ts` already states: the
+ * marker is written LAST, so it is the first thing a 4 000-character cut removes.
+ *
+ * ⚠ Scans BACKWARDS for the last line that starts with the marker AND parses AND echoes the nonce AND
+ * carries a known verdict — not simply the last line. ▶ An unknown value makes the scan keep going,
+ * which means a stale marker further back could be returned in its place; that is why the emitter
+ * check is mandatory here rather than optional, and why {@link gatewaySpawnOk} treats a `null` as a
+ * failure instead of a shrug.
+ *
+ * ⚠⚠ THE NONCE IS REQUIRED, WITH NO OPT-OUT ON THIS PATH — and what it buys is written, not implied.
+ * ▶ It DE-CORRELATES an accidental look-alike: an agent working on this repo prints this very contract
+ * on a deliberately-inherited stderr. ⚠ **It is not proof of emitter**: a same-user process can read a
+ * parent's command line on Windows and forge it. `runner_exec.ts` says the same of `vibe-master`'s
+ * nonce, so this path holds the SAME guarantee as the one it replaces and names it — no property that
+ * was ever held is withdrawn.
+ *
+ * ⚠ **And the bound on what the roster intersection protects — my first version claimed too much**
+ * (`gwl10-review-codex-2`): it said *what protects the RENDERED text is the roster intersection*.
+ * ▶ `keepRosterNames` intersects the **`detail`** only. It protects **no** part of the `verdict`, the
+ * `reason`, or which sentence gets selected — those are trusted from the marker. ⚠ *A guard credited
+ * with more than it covers is read as the answer to a defect it does not touch.*
+ */
+export function parseGatewayResult(
+  rawStderr: string,
+  nonce: string,
+): ParsedGatewayResult | null {
+  if (nonce.length === 0) {
+    throw new Error("parseGatewayResult: the nonce is REQUIRED — there is no unauthenticated mode on this path");
+  }
+  const knownReasons = new Set<string>(SPAWN_REASONS);
+  const knownVerdicts = new Set<string>(VERDICTS);
+  for (const line of rawStderr.split(/\r?\n/).reverse()) {
+    if (!line.startsWith(`${GATEWAY_MARKER} `)) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line.slice(GATEWAY_MARKER.length + 1));
+    } catch {
+      continue; // truncated or interleaved — keep looking further back
+    }
+    if (typeof parsed !== "object" || parsed === null) continue;
+    const {
+      verdict,
+      reason,
+      detail,
+      noVerdictTreeMayStand,
+      nonce: echoed,
+    } = parsed as {
+      verdict?: unknown;
+      reason?: unknown;
+      detail?: unknown;
+      noVerdictTreeMayStand?: unknown;
+      nonce?: unknown;
+    };
+    if (echoed !== nonce) continue;
+    if (typeof verdict !== "string" || !knownVerdicts.has(verdict)) continue;
+    return {
+      verdict: verdict as GatewayVerdict,
+      // ⚠⚠ FAILS TOWARD "GO LOOK". An older gateway, or a payload whose field was lost, must not read
+      // as "nothing is standing" — that is the cheap direction, and the expensive one is a tree nobody
+      // hunts. ▶ Rules entry 10: a fallback is only legitimate when it cannot be confused with a
+      // measurement, and here the safe value and the reassuring value are OPPOSITE.
+      noVerdictTreeMayStand: typeof noVerdictTreeMayStand === "boolean" ? noVerdictTreeMayStand : true,
+      // ⚠ A reason this runner does not know is DROPPED while the verdict is kept: the verdict is what
+      // decides success, so an unknown reason must cost the SENTENCE and never the failure. ▶ The
+      // opposite order — discarding the line — would turn an unrecognised reason into a false green.
+      ...(typeof reason === "string" && knownReasons.has(reason)
+        ? { reason: reason as SpawnReason }
+        : {}),
+      ...(typeof detail === "string" && detail.length > 0
+        ? { detail: detail.slice(0, DETAIL_MAX) }
+        : {}),
+    };
+  }
+  return null;
+}
+
+/**
+ * Did the gateway spawn the whole team?
+ *
+ * ⚠⚠ **`null` — no readable marker — is a FAILURE.** ▶ The exit code cannot answer this question (a
+ * `0` covers an INCOMPLET team), so "we could not read the verdict" and "it worked" must not collapse
+ * into the same answer. A caller that wants the old exit-code behaviour has to say so in a diff.
+ */
+export function gatewaySpawnOk(parsed: ParsedGatewayResult | null): boolean {
+  return parsed?.verdict === "COMPLETE";
+}
+
+/**
+ * Was the DESIRED STATE already in place, so that launching nothing is the right outcome?
+ *
+ * ⚠⚠ JP's arbitration of 2026-08-27, on a defect the live shot surfaced: a replayed spawn that is
+ * CORRECTLY de-duplicated used to reach the browser as a RED failure. ▶ *Nothing is broken — the
+ * team is running, and the system protected the user from a duplicate.* ⚠ So it reports `succeeded`
+ * with a message that says nothing was launched.
+ *
+ * ## ⚠⚠ WHY THIS IS NOT THE FALSE GREEN THIS MODULE EXISTS TO CLOSE
+ *
+ * ⚠ The whole point of {@link gatewaySpawnOk} is that ONLY `COMPLETE` is success, because a
+ * half-launched team must never read as one. ▶ **This predicate is safe for a measured reason, not
+ * a judged one**: `already_running` is emitted by
+ * `../../viber-gateway/lib/result_marker.ts` ONLY when this call launched NOTHING **and**
+ * `alreadyPresent` covers the WHOLE roster **and** the roster is non-empty. ⚠⚠ **So the condition
+ * under which this returns true is exactly the condition that guard validates** — the desired roster
+ * is present, in full.
+ *
+ * ▶ Measured live (TIR D, 2026-08-27): second emission of the same command, `member: existing`,
+ * ONE record, ONE manifest, same `jobName`, same host anchor.
+ *
+ * ⚠ **It is a SEPARATE predicate rather than a widening of `gatewaySpawnOk`**: that function's
+ * meaning — *the whole team was launched by this call* — stays exact, and the new case shows up in a
+ * diff instead of hiding inside a boolean that already had a name.
+ */
+export function gatewayNothingToDo(parsed: ParsedGatewayResult | null): boolean {
+  // ⚠⚠ THIS FUNCTION WAS DEAD, and the decision it names was taken on a BARE STRING beside it
+  // (`runner_exec.ts`: `reason === "already_running"`). Found independently, under seal, by
+  // `gwl10-review-opus` (execution) and `gwl10-review-codex-2` (contract), #590.
+  //
+  // ▶ The guarantee lived on a function nobody called; the decision lived in an expression that
+  // asserted less. **Rules entry 23: two statements about the same fact, and neither reads the other.**
+  //
+  // ⚠⚠ AND THE VERDICT IS CHECKED HERE, which the bare string never did. The docblock above
+  // justifies this predicate by the EMITTER's guard — nothing launched, `alreadyPresent` covers the
+  // whole roster — but that is a property of the EMITTER while this decision is taken by the READER,
+  // and the header of this very file writes that the nonce **de-correlates and is NOT proof of
+  // emitter**. ▶ So the reader verifies what it was relying on the emitter to hold:
+  //
+  //   gateway_result.ts   VERDICTS accepted here = COMPLETE | INCOMPLET | REFUSED
+  //   result_marker.ts    the team report emits   COMPLETE | INCOMPLET
+  //
+  // ⚠⚠⚠ AND THE FIRST VERSION OF THIS GUARD REQUIRED `COMPLETE`, WHICH WAS A REGRESSION — caught by
+  // `gwl10-review-codex-2` under seal, reproduced by execution before being accepted.
+  //
+  // ⚠ It rested on *“`INCOMPLET` + `already_running` is internally inconsistent”*. **That premise is
+  // FALSE**, and the emitter says so:
+  //
+  //   spawn.ts:533        verdict = launched.length === members.length ? COMPLETE : INCOMPLET
+  //   result_marker.ts    `already_running` requires launched.length === 0 AND members.length > 0
+  //   => a NOMINAL REPLAY is ALWAYS `INCOMPLET`, and `COMPLETE + already_running` is UNREACHABLE
+  //
+  // ▶ Measured through the emitter itself:
+  //   gatewayResultFor({verdict:"INCOMPLET", launched:[], alreadyPresent:["a","b"], members:["a","b"]})
+  //     -> {"verdict":"INCOMPLET","reason":"already_running","detail":"a, b"}
+  //
+  // ⚠⚠ So requiring `COMPLETE` made this predicate **NEVER TRUE** — a guard that cannot bite — and
+  // it restored the FALSE RED that JP's arbitration existed to remove. ▶ `COMPLETE` here means *"every
+  // member was launched BY THIS CALL"*, which a replay by definition is not.
+  //
+  // ⚠ And the witness that "proved" it fabricated a `COMPLETE + already_running` marker by hand — a
+  // pair the emitter never produces. **A fixture built from the clause cannot refute the clause**
+  // (rules entry 16).
+  //
+  // ▶▶ What the reader can legitimately check is what the TEAM REPORT can emit: `COMPLETE` or
+  // `INCOMPLET`, never `REFUSED`. That keeps the protection — a verdict outside the emitter's range
+  // is refused — without denying the arbitrated case.
+  //
+  // ⚠ `already_running` is the ONLY reason in the vocabulary that renders as reassuring
+  // (`spawn_reason.ts`) — *the exact false green this issue exists to remove*.
+  // ⚠⚠ WRITTEN IN THE POSITIVE, and the first version was `verdict !== "REFUSED"` — an EXCLUSION,
+  // which decides by OMISSION (`gwl10-review-opus`, #590). ▶ `VERDICTS` carries three values today;
+  // a fourth added tomorrow would fall on the PROMOTE side with nothing saying so.
+  //
+  // ▶▶ The set is identical today, and a new verdict now lands on the SAFE side. ⚠ This is the
+  // third exclusion-list defect of this batch, all three the same shape, so the form is the fix.
+  //
+  // ⚠⚠ AND THE REASON THIS GUARD EXISTS IS NOT "the emitter cannot produce that pair"
+  // (`gwl10-review-opus`, and his argument is better than the one first written here):
+  //
+  //   ▶▶ **The reader cannot authenticate the emitter — this file says so a few lines up — so the
+  //      EMITTER'S RANGE does not protect the reader. A reader's guard must hold against ANY marker.**
+  //
+  // ⚠ That is the same family as the nonce: it DE-CORRELATES an accidental look-alike, it does not
+  // prove who wrote the line. ▶ So this predicate is not checking "is this pair plausible from our
+  // own emitter" — it is refusing to promote the single reassuring word in the vocabulary on anything
+  // but the two verdicts a team report is allowed to carry, whoever wrote them.
+  return (
+    parsed?.reason === "already_running" &&
+    (parsed.verdict === "COMPLETE" || parsed.verdict === "INCOMPLET")
+  );
+}
+
+/**
+ * Must someone go hunt a process on that machine?
+ *
+ * ⚠ Separate from {@link gatewaySpawnOk} because the two answer DIFFERENT questions and a single
+ * boolean conflated them: a `COMPLETE` team can still leave a member whose tree status could not be
+ * established, and a `REFUSED` command may have created nothing at all. ▶ **Success and "go look" are
+ * not each other's negation**, which is exactly why the gateway splits `2` from `3`.
+ *
+ * ⚠ `null` — no readable marker — answers **TRUE**: we could not establish anything, so we cannot
+ * establish that nothing is standing.
+ */
+export function gatewayNoVerdictTreeMayStand(parsed: ParsedGatewayResult | null): boolean {
+  return parsed === null ? true : parsed.noVerdictTreeMayStand;
+}

package/lib/messages.ts

@@ -160,6 +160,13 @@ export async function postMessage(
    * `signal.aborted` guard before the call cannot.
    */
   signal?: AbortSignal,
+  /**
+   * Optional fetch seam (#606). Defaults to the global `fetch`. Exists so the
+   * failure-notice path of `sseLoop` is OBSERVABLE in tests: without it the only
+   * way to read what the bridge posts is to monkey-patch the global, and a test
+   * that cannot see the notice cannot prove the fix that exists to emit it.
+   */
+  fetchImpl: typeof fetch = fetch,
 ): Promise<MessagePostResult> {
   if (!text || text.trim().length === 0) {
     return {
@@ -173,7 +180,7 @@ export async function postMessage(
   const url = `${baseUrl}/api/conversations/${conversationId}/messages`;
   let resp: Response;
   try {
-    resp = await fetch(url, {
+    resp = await fetchImpl(url, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${conversationToken}`,

package/lib/runner_exec.ts

@@ -18,6 +18,7 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 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";
 
 /** A validated role from the server snapshot (allowlisted shape). */
@@ -155,7 +156,29 @@ export type TeamSpawnRunner = (
    *  explicit trust parameter closes. A mock may ignore the argument; it cannot
    *  forget that it exists. */
   nonce: string,
-) => Promise<{ ok: boolean; recap: string; reason?: SpawnReason; detail?: string }>;
+) => Promise<{
+  ok: boolean;
+  recap: string;
+  reason?: SpawnReason;
+  detail?: string;
+  /**
+   * ⚠⚠ #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 emits this word only when NO roster member is missing.
+   *
+   * ⚠ **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
+   * REQUIRED because an optional nonce would fail OPEN — a launcher could omit it and silently
+   * trust any marker. **Here omission denies, there omission would have trusted.** ⚠ Do not
+   * "harmonise" the two: the asymmetry is the safety.
+   */
+  nothingToDo?: boolean;
+}>;
 
 /**
  * Build a CURATED child environment (Codex review, blocking): `execFile` would
@@ -227,6 +250,230 @@ export const execFileTeamSpawn: TeamSpawnRunner = (args, 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 (`vibe-master/lib/teams.ts`, `classifyCollision`): this word is 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 } : {}),
+        });
+      },
+    );
+  });
+};
+
+/**
+ * The base command that launches `viber-gateway`. ⚠ Same convention as
+ * {@link vibeMasterBaseCmd} rather than a second one — a space-separated token
+ * list, still an argv ARRAY, no shell — because a dev runner must be able to
+ * point at the SOURCE gateway exactly as it can point at the source
+ * `vibe-master` (`VIBER_GATEWAY_CMD="bun /path/gateway.ts"`).
+ */
+export function viberGatewayBaseCmd(source: NodeJS.ProcessEnv = process.env): string[] {
+  const raw = source.VIBER_GATEWAY_CMD?.trim();
+  const parts = raw ? raw.split(/\s+/) : ["viber-gateway"];
+  return parts.length > 0 ? parts : ["viber-gateway"];
+}
+
+/**
+ * Where the gateway's registry lives for THIS workspace.
+ *
+ * Beside the runner's other durable per-workspace state rather than at the bare cwd: see the
+ * measurement in {@link buildGatewayTeamArgs}. It must SURVIVE (contract line 17) and it must not be
+ * under `tmpdir()`, which `resolveRegistryDir` refuses outright.
+ */
+export function gatewayRegistryDir(cwd: string = process.cwd()): string {
+  return join(cwd, ".viber", "gateway-registry");
+}
+
+/**
+ * Create the registry directory before the verb needs it, and return it.
+ *
+ * ⚠⚠ MEASURED IN THE LIVE FIRING WINDOW, through the real verb, right after `--dir` was wired:
+ *
+ * ```
+ * durable refusal: NOT PUBLISHED - ENOENT: no such file or directory, open
+ *   '...\.viber\gateway-registry\manifest-....lock....staging'
+ * ```
+ *
+ * ▶ **`--dir` pointed at a directory nobody creates**, so `publishCommandRefusal` could not write and
+ * the refusal was NOT durable - and contract line 1 requires a refusal to be VISIBLE ON DISK.
+ *
+ * ⚠ And the neighbouring guard held, which is why the two halves are separate: the refusal was still
+ * PRINTED and its reason still travelled to the server. *A refusal nobody could record is still a
+ * refusal the caller must see.*
+ *
+ * ⚠ The party that CHOOSES the directory is the party that creates it. ▶ The gateway deliberately
+ * does NOT create an arbitrary `--dir`: a path a human mistyped should fail loudly rather than be
+ * silently brought into existence somewhere unintended.
+ */
+export function ensureGatewayRegistryDir(cwd: string = process.cwd()): string {
+  const dir = gatewayRegistryDir(cwd);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * The argv for `viber-gateway team`. ⚠ EXPORTED and PURE so the route can be
+ * witnessed without launching anything: piloting the verb would start processes,
+ * so what a unit test can prove is the ARGV, and the verb itself is measured in
+ * the firing window.
+ *
+ * ## ⚠⚠ THREE THINGS THE OLD ARGV DID NOT CARRY, and each is a measured mismatch
+ *
+ * ```
+ * viber-gateway/gateway.ts   --command-id, --prefix, --team, --spec-file, --cwd are ALL REQUIRED
+ *                            ("none of them has a defensible default")
+ * the old argv               ["team","spawn","--spec-file",p,"--prefix",x,"--result-nonce",n]
+ *                            + --team ONLY when cmd.team_name is set
+ * ```
+ *
+ * 1. ⚠ **`--team` is REQUIRED there and OPTIONAL here.** ▶ It falls back to the
+ *    PREFIX, which is already this command's team identity in practice:
+ *    `rosterNames` builds every member name as `{prefix}-{role}`.
+ *
+ *    ⚠⚠ **AND MY FIRST TWO REASONS FOR THIS FALLBACK WERE BOTH FALSE** — measured by
+ *    `gwl10-review-codex-2` on the contract angle, and the fallback survives them:
+ *
+ *    ```
+ *    team_derivation.ts:308-310   rosterIdFor(cmdId) = digest({domain, cmd: cmdId})
+ *    team_spawn_command.ts:277    const rosterId = rosterIdFor(cmd.id)
+ *    ```
+ *
+ *    ▶ The manifest is keyed by the **command id**, and it CONTAINS `team` +
+ *    `agentIds`; it is not *"keyed `(team, agentId)`"* as I wrote. ⚠ So two commands
+ *    sharing a prefix get two DISTINCT `cmd.id`s and therefore **two manifests** —
+ *    my *"they share a manifest, which is CORRECT"* was false in both halves, and
+ *    contract lines 13/14 are about the SAME command replayed, not two commands.
+ *
+ *    ▶ **What actually requires a non-empty value** is `MixedTeam`, which refuses a
+ *    batch whose team is `""` (`spawn.ts:318`), plus the gateway's own refusal of an
+ *    absent `--team` (*"no defensible default"*). ⚠ *A conclusion that survives two
+ *    false reasons still needs the true one written next to it.*
+ * 2. ⚠ **`--cwd`**: the runner's workspace is `process.cwd()` everywhere in this
+ *    file (`.viber/runner-specs`, `-logs`, `-inflight`), so that is the workspace
+ *    the agents must get. Passing none would have let the gateway decide, which is
+ *    a value only this side can know.
+ * 3. ⚠⚠ **`--vibe-master-cmd`, and omitting it would be a SILENT DEV REGRESSION.**
+ *    `VIBE_MASTER_CMD` exists so a dev runner points at the source instead of a
+ *    stale global binary (the #460 dev-QA foot-gun). ▶ After this junction the
+ *    runner no longer launches `vibe-master` — **the gateway does** — so the
+ *    variable must travel as a FLAG or dev silently reverts to the installed
+ *    binary. ⚠ Nothing would have gone red: the spawn would work, against the
+ *    wrong binary. This is also the flag whose being *really taken by the verb* is
+ *    one of the two live proofs the next firing window owes.
+ */
+export function buildGatewayTeamArgs(cmd: {
+  commandId: string;
+  prefix: string;
+  teamName?: string;
+  specPath: string;
+  cwd: string;
+  registryDir: string;
+  permission: string;
+  env?: string;
+  nonce: string;
+  vibeMasterCmd?: string;
+}): string[] {
+  const args = [
+    "team",
+    // ⚠ `--dir` IS REQUIRED HERE, and omitting it was a defect found in the firing-window preflight,
+    // before anything was launched. Measured at `8862ef3d`:
+    //
+    // ```
+    // buildGatewayTeamArgs        ->  no --dir
+    // gateway.ts main()               resolveRegistryDir(argValue("--dir") ?? "")
+    // resolveRegistryDir("")      ->  <the REPO ROOT>
+    // ```
+    //
+    // ⚠ So every spawn would write `<launchId>.json`, `.manifest`, `.refusal` and `specs/` **into a
+    // checkout shared with another team** - untracked files at the repo root, which is the one thing
+    // this repo's shared-checkout rule forbids outright.
+    //
+    // ⚠ And the second hazard is worse than noise: `registry.ts:569` lists `*.json` in its own
+    // directory, so any JSON at that root reads back as a CORRUPT RECORD. Measured: this repo has
+    // ZERO `*.json` at its root today, so the hazard is not reached - **but that is an accident of
+    // layout, not a property**, and it is the third time this workshop has paid for treating a
+    // registry directory as a work area (*a suffix is not a namespace*).
+    //
+    // So it goes next to this file's other durable per-workspace state - `runner-specs`,
+    // `runner-logs`, `runner-inflight` - which also satisfies contract line 17: it SURVIVES, and it is
+    // not under `tmpdir()`, which `resolveRegistryDir` refuses outright.
+    "--dir",
+    cmd.registryDir,
+    "--command-id",
+    cmd.commandId,
+    "--prefix",
+    cmd.prefix,
+    // ⚠ See (1) above: the prefix IS the team identity when none was named.
+    "--team",
+    cmd.teamName ?? cmd.prefix,
+    "--spec-file",
+    cmd.specPath,
+    "--cwd",
+    cmd.cwd,
+    "--permission",
+    cmd.permission,
+    "--result-nonce",
+    cmd.nonce,
+  ];
+  if (cmd.env) args.push("--env", cmd.env);
+  // ▶ Only when set: an empty `--vibe-master-cmd` would make the gateway resolve an
+  // empty command, which is worse than not passing the flag at all.
+  if (cmd.vibeMasterCmd && cmd.vibeMasterCmd.trim().length > 0) {
+    args.push("--vibe-master-cmd", cmd.vibeMasterCmd.trim());
+  }
+  return args;
+}
+
+/**
+ * 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}.
+ *
+ * ```
+ * viber-gateway/lib/team_spawn_command.ts:358
+ *     "An INCOMPLET team whose members all reached a verdict is a RESULT, not a crash: 0"
+ * ```
+ *
+ * ▶▶ So `ok = !err` would report `succeeded` on a HALF-LAUNCHED team, and the
+ * browser would say *team spawn 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*.
+ *
+ * ⚠ **No readable marker is a FAILURE**, not a degradation: unlike the
+ * `vibe-master` path, the exit code here cannot establish success, so
+ * "we could not read the verdict" must not collapse into "it worked"
+ * (`gatewaySpawnOk`).
+ */
+export const execFileGatewayTeamSpawn: TeamSpawnRunner = (args, nonce) => {
+  const base = viberGatewayBaseCmd();
+  const bin = base[0] as string;
+  return new Promise((resolve) => {
+    execFile(
+      bin,
+      [...base.slice(1), ...args],
+      { timeout: 5 * 60 * 1000, killSignal: "SIGKILL", maxBuffer: 1024 * 1024, env: buildChildEnv() },
+      (_err, stdout, stderr) => {
+        // ⚠ RAW stderr, before redaction and before the 4 000-char cut, for the
+        // reason the marker is written LAST — the cut removes that end first.
+        const parsed = parseGatewayResult(stderr ?? "", nonce);
+        const recap = redactSecrets(`${stdout}\n${stderr}`.trim()).slice(0, 4000);
+        resolve({
+          // ▶ `_err` is deliberately UNUSED. Naming it with an underscore rather
+          // than dropping the parameter keeps the callback's shape identical to
+          // the vibe-master launcher's, so a reader comparing the two sees that
+          // the difference is a CHOICE and not an omission.
+          ok: gatewaySpawnOk(parsed),
+          // ▶ #590: the gateway's own guard, CALLED — it used to be dead code while the reader
+          // re-tested the bare string. It checks roster coverage AND the verdict.
+          nothingToDo: gatewayNothingToDo(parsed),
           recap,
           ...(parsed?.reason ? { reason: parsed.reason } : {}),
           ...(parsed?.detail ? { detail: parsed.detail } : {}),
@@ -394,7 +641,12 @@ export async function executeClaim(
   cmd: ClaimedCommand,
   deps: ExecDeps = {},
 ): Promise<"succeeded" | "failed" | "aborted"> {
-  const runTeamSpawn = deps.runTeamSpawn ?? execFileTeamSpawn;
+  // ⚠⚠ 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.
+  const runTeamSpawn = deps.runTeamSpawn ?? execFileGatewayTeamSpawn;
   const fetchImpl = deps.apiFetch ?? fetch;
   const inflight = deps.inflight ?? fsInflightStore();
 
@@ -476,12 +728,74 @@ export async function executeClaim(
     // as the user; what protects the RENDERED text is the roster intersection
     // below, not this nonce.
     const nonce = randomBytes(16).toString("hex");
-    const args = ["team", "spawn", "--spec-file", specPath, "--prefix", cmd.prefix, "--result-nonce", nonce];
-    if (cmd.team_name) args.push("--team", cmd.team_name);
-    if (cmd.env) args.push("--env", cmd.env);
+    //
+    // ⚠⚠ THE JUNCTION (#590 step-05). This used to be
+    // `["team","spawn","--spec-file",…]` for `vibe-master`; it is now
+    // `viber-gateway team`, which derives the batch, publishes the manifest BEFORE
+    // any claim, and invokes `vibe-master` itself. ▶ The route is the same shape —
+    // one team command, never N — because the spec file is *the snapshot the server
+    // validated* and splitting it here would recreate the local name resolution
+    // `--spec-file`'s strict mode exists to forbid.
+    //
+    // ▶ What the junction BUYS, and it is not a refactor: a `launchId` STABLE per
+    // `(command, agent)` (`attemptLaunchId`), so a replayed command claims the same
+    // attempt instead of minting a second one; and a denominator that survives the
+    // process, so a member refused before any claim stays counted.
+    const args = buildGatewayTeamArgs({
+      commandId: cmd.id,
+      prefix: cmd.prefix,
+      ...(cmd.team_name ? { teamName: cmd.team_name } : {}),
+      specPath,
+      cwd: process.cwd(),
+      // Beside `runner-specs`/`runner-logs`/`runner-inflight`, never the bare cwd - see
+      // `buildGatewayTeamArgs`, where the measurement that forced this is recorded.
+      registryDir: ensureGatewayRegistryDir(),
+      // ⚠ The roster's own permission, taken from the SERVER-VALIDATED snapshot and
+      // not invented here. ▶ A roster whose members disagree is REFUSED by the
+      // gateway (`assertUniformPermission`) rather than launched at one of the two
+      // — which is a behaviour CHANGE and the right one: `vibe-master` reads its
+      // permission from the ARGV and never from the spec, so a mixed roster used to
+      // launch a `read-only` member `read-write` with nothing going red.
+      permission: cmd.template_spec.roles[0]?.permission ?? "read-only",
+      ...(cmd.env ? { env: cmd.env } : {}),
+      nonce,
+      // ⚠ See (3) on `buildGatewayTeamArgs`: the runner no longer launches
+      // `vibe-master`, so this must TRAVEL or dev silently uses the installed
+      // binary. Read from the env here, where the variable is already the
+      // convention, rather than re-invented as a second knob.
+      ...(process.env.VIBE_MASTER_CMD ? { vibeMasterCmd: process.env.VIBE_MASTER_CMD } : {}),
+    });
 
     inflight.mark(cmd.id); // durable "started here" BEFORE launch (C4)
-    const { ok, recap, reason, detail } = await runTeamSpawn(args, nonce);
+    const { ok, recap, reason, detail, nothingToDo: launcherSaysNothingToDo } =
+      await runTeamSpawn(args, nonce);
+    // ⚠⚠ JP's arbitration of 2026-08-27: a replayed spawn that is CORRECTLY de-duplicated is a
+    // NORMAL outcome, not a failure. ▶ Measured live (TIR D): second emission of the same command
+    // -> `member: existing`, ONE record, ONE manifest, same jobName, same host anchor. **Nothing is
+    // broken, and the system protected the user from a duplicate** - yet the browser showed RED.
+    //
+    // ⚠⚠ AND IT IS NOT THE FALSE GREEN THIS BATCH CLOSED, for a MEASURED reason: on the gateway path
+    // `already_running` is emitted ONLY when this call launched NOTHING **and** `alreadyPresent` covers
+    // the WHOLE roster **and** the roster is non-empty (`result_marker.ts`, `gatewayNothingToDo`).
+    // ▶ So the desired roster is present, in full.
+    //
+    // ⚠ The BOUND, because the same word reaches here from two launchers: on the `vibe-master` path
+    // the guarantee is vibe-master's own, not those three conditions. ▶ Both mean *the team with
+    // this prefix is already running*, which is why the status is the same; but only the gateway path
+    // has the roster-coverage guard, and a reader must not credit it to the other.
+    //
+    // ⚠⚠ AND THIS LINE USED TO READ `reason === "already_running"` — the bare string, crossed with
+    // NOTHING. #590, found independently under seal by both reviewers. ▶ The comment directly above
+    // says the guarantee DIFFERS by launcher, and the code three lines below credited it to both.
+    //
+    // ▶ Now each launcher STATES its own claim and the reader consumes the claim, not the word.
+    // ⚠ **FAIL CLOSED**: an absent field is *no claim*, so it denies the promotion. A launcher that
+    // says nothing gets the old failure path, never the reassuring one.
+    //
+    // ⚠⚠ `reason` is deliberately NOT consulted here any more. Re-adding it as a fallback
+    // (`?? reason === "already_running"`) would restore exactly the defect this closes — the
+    // reassuring word promoted on no proof — and it would do so while LOOKING like belt-and-braces.
+    const nothingToDo = launcherSaysNothingToDo ?? false;
 
     // #496: the failure now travels as a REASON plus a sentence built from it —
     // whoever clicked Spawn in a browser can act on what they read. The full
@@ -495,7 +809,7 @@ export async function executeClaim(
     // said "reconcile: handled 1 command(s)". A failure now states itself where
     // it is read FIRST. This stream is local, so the ABSOLUTE path belongs here;
     // what travels to the server is the relative ref below.
-    if (!ok) {
+    if (!ok && !nothingToDo) {
       const writeDaemonLine =
         deps.writeDaemonLine ?? ((line: string) => process.stderr.write(`${line}\n`));
       writeDaemonLine(
@@ -510,6 +824,17 @@ export async function executeClaim(
       cmd.id,
       ok
         ? { fencing_token: cmd.fencing_token, status: "succeeded", result: { message: "team spawn completed", log: logPath } }
+        : nothingToDo
+        ? {
+            fencing_token: cmd.fencing_token,
+            status: "succeeded",
+            // ▶ A DIFFERENT message from the launch case, deliberately: the outcome is normal but it
+            // is NOT "the team was launched", and a reader must be able to tell the two apart.
+            result: {
+              message: "team already running — nothing was launched",
+              log: logPath,
+            },
+          }
         : {
             fencing_token: cmd.fencing_token,
             status: "failed",
@@ -532,7 +857,7 @@ export async function executeClaim(
     // the marker so a re-claim doesn't relaunch a command that already ran here.
     if (finalStatus >= 200 && finalStatus < 300) {
       inflight.clear(cmd.id);
-      return ok ? "succeeded" : "failed";
+      return ok || nothingToDo ? "succeeded" : "failed";
     }
     return "aborted"; // report not accepted (409/other) — marker kept for reconcile
   } finally {

package/lib/urls.ts

@@ -34,6 +34,8 @@ export function isTrustedViberOrigin(origin: string): boolean {
   if (host === "viber.dgypx.dev" || host === "viber-dev.dgypx.dev") return true;
   // #480: the agent API hosts. Hard-coded on purpose — see the warning below.
   if (host === "viber-api-staging.dgypx.dev") return true;
+  // #613: the qa env (web + agent API host), isolated from staging.
+  if (host === "viber-qa.dgypx.dev" || host === "viber-api-qa.dgypx.dev") return true;
   // Explicitly-configured bases (self-host / dev override) — matched by origin.
   // Both are LOCAL env vars, i.e. already trusted input.
   for (const configured of [process.env.VIBER_BASE_URL, process.env.VIBER_API_BASE_URL]) {

package/package.json

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

@@ -42,9 +42,57 @@ import {
   safeErrorMessage,
   senderLabel,
   shouldHandleMessage,
+  type TurnDegradation,
   type TurnPostAction,
 } from "./lib/bridge_core.ts";
 
+/**
+ * #606 step-02 — pull the HTTP status out of a codex `codexErrorInfo`, if it has one.
+ *
+ * MEASURED shape: `{"responseStreamDisconnected":{"httpStatusCode":503}}`. Other
+ * variants are plain strings (`"usageLimitExceeded"`) with no status at all, so
+ * this returns undefined rather than guessing — the notice then simply omits the
+ * clause. Pure and exported so the shape can be tested without a codex process.
+ */
+/**
+ * #606 step-02 — is this codex notification a transport DEGRADATION, and which
+ * turn does it belong to? Pure, so the measured JSON-RPC shape is tested without
+ * a codex process (the class of defect in .claude/rules: a wiring only exercised
+ * through a hand-stamped fixture is not exercised at all).
+ */
+export function readDegradationNotification(
+  params: unknown,
+): { threadId: string; turnId: string; status?: number } | undefined {
+  const p = params as
+    | { willRetry?: unknown; turnId?: unknown; threadId?: unknown; error?: { codexErrorInfo?: unknown } }
+    | undefined;
+  if (!p || p.willRetry !== true) return undefined;
+  if (typeof p.threadId !== "string" || typeof p.turnId !== "string") return undefined;
+  return { threadId: p.threadId, turnId: p.turnId, status: extractHttpStatus(p.error?.codexErrorInfo) };
+}
+
+/**
+ * #606 step-02 — stamp the degradation a turn suffered onto the Error it fails
+ * with. A failing turn returns no TurnResult, so the Error is the only carrier;
+ * bridge_core reads it back with readTurnDegradation. Zero events → no stamp, so
+ * a clean failure never claims a degraded transport.
+ */
+export function stampDegradation(err: Error, events: number, lastStatus?: number): Error {
+  if (events > 0) (err as Error & { degradation?: TurnDegradation }).degradation = { events, lastStatus };
+  return err;
+}
+
+export function extractHttpStatus(info: unknown): number | undefined {
+  if (!info || typeof info !== "object") return undefined;
+  for (const value of Object.values(info as Record<string, unknown>)) {
+    if (value && typeof value === "object") {
+      const status = (value as { httpStatusCode?: unknown }).httpStatusCode;
+      if (typeof status === "number") return status;
+    }
+  }
+  return undefined;
+}
+
 /** Per-bridge log tag — passed to the shared core so its lines stay under this prefix. */
 const LOG_PREFIX = "[viber-codex-bridge]";
 // Re-export the bridge-core symbols that existing importers/tests reference by
@@ -117,6 +165,15 @@ interface TurnWaiter {
   threadId: string;
   turnId: string;
   deltas: string[];
+  /**
+   * #606 step-02 — transport degradation observed DURING this turn: codex emits a
+   * JSON-RPC `error` notification with `willRetry: true` for each WebSocket
+   * reconnect / HTTPS fallback, carrying `turnId` and an httpStatusCode. Counted
+   * here so a turn that later fails can SAY it was already limping, instead of
+   * leaving the model to invent why it was slow.
+   */
+  degradationEvents: number;
+  degradationLastStatus?: number;
   resolve: (value: string) => void;
   reject: (err: Error) => void;
   timeout: ReturnType<typeof setTimeout>;
@@ -690,7 +747,13 @@ class CodexAppServer {
       this.pending.clear();
       for (const waiter of this.turnWaiters.values()) {
         clearTimeout(waiter.timeout);
-        waiter.reject(err);
+        // #606, review codex: same reason as the timeout path — a child that dies
+        // after a reconnect storm should say the storm, not only the death. A FRESH
+        // Error per waiter: stamping the shared one would give every waiter the
+        // last one's counters.
+        waiter.reject(
+          stampDegradation(new Error(reason), waiter.degradationEvents, waiter.degradationLastStatus),
+        );
       }
       this.turnWaiters.clear();
       // The child is gone — the bridge must NOT keep beating/serving SSE as a
@@ -881,7 +944,10 @@ class CodexAppServer {
         status === "failed" ||
         (typeof status === "object" && status !== null && "type" in status && status.type === "failed")
       ) {
-        waiter.reject(new Error(`Codex turn failed: ${JSON.stringify(params.turn?.error ?? status)}`));
+        const failure = new Error(`Codex turn failed: ${JSON.stringify(params.turn?.error ?? status)}`);
+        // #606: a failing turn returns no TurnResult, so the degradation count
+        // rides on the Error itself — bridge_core reads it with readTurnDegradation.
+        waiter.reject(stampDegradation(failure, waiter.degradationEvents, waiter.degradationLastStatus));
       } else {
         waiter.resolve(waiter.deltas.join("").trim());
       }
@@ -890,9 +956,41 @@ class CodexAppServer {
 
     if (msg.method === "error" || msg.method === "warning" || msg.method === "configWarning") {
       process.stderr.write(`[viber-codex-bridge] codex ${msg.method}: ${JSON.stringify(msg.params)}\n`);
+      this.recordDegradation(msg);
     }
   }
 
+  /**
+   * #606 step-02 — count a transport hiccup against the turn that suffered it.
+   *
+   * MEASURED shape (.vctl/logs/dynamic-vibe-agent-606-review-codex.raw, l.34):
+   *   {"error":{"message":"Reconnecting... 2/5",
+   *     "codexErrorInfo":{"responseStreamDisconnected":{"httpStatusCode":503}}},
+   *    "willRetry":true,"threadId":"...","turnId":"..."}
+   *
+   * `willRetry: true` is the discriminator: codex is saying it is RECOVERING, so
+   * this is degradation, not the failure itself (the failure arrives separately as
+   * turn/completed with status failed). The count only ever reaches the channel
+   * through a turn that goes on to FAIL — a turn that recovers stays on stderr,
+   * because the channel is not a transport log.
+   *
+   * NOT COVERED, deliberately, and said here rather than left to look forgotten:
+   *  - an abnormally LONG turn with no error notification (the issue's 43.8 s) —
+   *    catching it needs a threshold, and a literal threshold is the very defect
+   *    class of .claude/rules/instruments-qui-concluent-a-lenvers.md §4;
+   *  - gemma has nothing equivalent: lib/ollama_chat.ts is a single fetch with no
+   *    intermediate transport events, so there is nothing to observe and nothing
+   *    is promised. bridge_core's failure notice still covers its FAILURES.
+   */
+  private recordDegradation(msg: JsonRpcMessage): void {
+    const event = readDegradationNotification(msg.params);
+    if (!event) return;
+    const waiter = this.turnWaiters.get(`${event.threadId}:${event.turnId}`);
+    if (!waiter) return;
+    waiter.degradationEvents += 1;
+    if (event.status !== undefined) waiter.degradationLastStatus = event.status;
+  }
+
   private handleServerRequest(msg: JsonRpcMessage): void {
     const result = decideServerRequestResponse(msg.method!, msg.params);
     // Log accepts of our tool-call elicitation and every decline, so the surgical
@@ -921,10 +1019,21 @@ class CodexAppServer {
     const key = `${threadId}:${turnId}`;
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
+        const waiter = this.turnWaiters.get(key);
         this.turnWaiters.delete(key);
-        reject(new Error("Codex turn timed out after 10 minutes"));
+        // #606, review codex: a timeout used to reject WITHOUT the degradation
+        // stamp, so a turn that reconnected five times and then hung reported a
+        // bare timeout — the most interesting failure losing the only fact that
+        // explained it.
+        reject(
+          stampDegradation(
+            new Error("Codex turn timed out after 10 minutes"),
+            waiter?.degradationEvents ?? 0,
+            waiter?.degradationLastStatus,
+          ),
+        );
       }, 10 * 60 * 1000);
-      this.turnWaiters.set(key, { threadId, turnId, deltas: [], resolve, reject, timeout });
+      this.turnWaiters.set(key, { threadId, turnId, deltas: [], resolve, reject, timeout, degradationEvents: 0 });
     });
   }
 }