viber-channel 0.8.11 → 0.8.13

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 { messageForReason, parseSpawnResult, rosterNames, type SpawnReason } from "./spawn_reason.js";
 
 /** A validated role from the server snapshot (allowlisted shape). */
 export interface SnapshotRole {
@@ -148,7 +149,13 @@ export function validateAgainstPolicy(cmd: ClaimedCommand, policy: RunnerPolicy)
 
 export type TeamSpawnRunner = (
   args: string[],
-) => Promise<{ ok: boolean; recap: string }>;
+  /** #496: the nonce the child must echo on its outcome marker for it to be
+   *  believed. REQUIRED (Codex review): an optional nonce lets a future launcher
+   *  omit it and silently fall back to trusting any marker — the very hole the
+   *  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 }>;
 
 /**
  * Build a CURATED child environment (Codex review, blocking): `execFile` would
@@ -202,7 +209,7 @@ export function vibeMasterBaseCmd(source: NodeJS.ProcessEnv = process.env): stri
 /** 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) => {
+export const execFileTeamSpawn: TeamSpawnRunner = (args, nonce) => {
   const base = vibeMasterBaseCmd();
   const bin = base[0] as string;
   return new Promise((resolve) => {
@@ -211,8 +218,19 @@ export const execFileTeamSpawn: TeamSpawnRunner = (args) => {
       [...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, recap });
+        resolve({
+          ok: !err,
+          recap,
+          ...(parsed?.reason ? { reason: parsed.reason } : {}),
+          ...(parsed?.detail ? { detail: parsed.detail } : {}),
+        });
       },
     );
   });
@@ -273,6 +291,49 @@ export interface ExecDeps {
   writeSpec?: SpecFileWriter;
   /** Injectable local-log writer (tests). Returns the log path. */
   writeLog?: (commandId: string, recap: string) => string;
+  /** Injectable daemon-stderr writer (tests). Defaults to process.stderr. */
+  writeDaemonLine?: (line: string) => void;
+}
+
+/** Where the log lives, as shown to whoever reads the WEB (#506): RELATIVE, so
+ *  it names the file without carrying the machine's absolute path — home
+ *  directory and user name included — to the server. The absolute path stays on
+ *  the daemon's own stderr, which never leaves the machine. */
+export function runnerLogRef(commandId: string): string {
+  return `.viber/runner-logs/${commandId}.log`;
+}
+
+/** What `writeRunnerLog` returns when it could NOT write (unwritable dir, full
+ *  disk). Named, because the remote message must not point at a file that was
+ *  never created. */
+export const LOG_UNAVAILABLE = "(local log unavailable)";
+
+/** The log reference to put in the REMOTE message, or undefined when no log
+ *  exists (#506 review, both reviewers): pointing someone at
+ *  `.viber/runner-logs/<id>.log` when the write failed would be this issue in
+ *  miniature — a component asserting more than it knows, on the very sentence
+ *  this step fixes. Callers fall back to the no-path wording. */
+export function remoteLogRef(commandId: string, logPath: string): string | undefined {
+  return logPath === LOG_UNAVAILABLE ? undefined : runnerLogRef(commandId);
+}
+
+/** The one line of a recap worth putting on the daemon's stderr: its first
+ *  `error:` line, bounded. Already redacted upstream by `redactSecrets`. Falls
+ *  back to the first non-empty line when the CLI printed no `error:` line, so a
+ *  failure is never reported as silence.
+ *
+ *  The result must be ONE line: it is written with a trailing newline onto a
+ *  shared stream, so any control character surviving inside it could forge a
+ *  second log line. Hence splitting on a LONE `\r` too (Codex review — a bare CR
+ *  is what a progress-bar writer emits), and stripping the remaining C0/C1
+ *  controls rather than trusting the split alone. */
+export function firstErrorLine(recap: string, max = 300): string {
+  const lines = recap
+    .split(/\r\n|\r|\n/)
+    .map((l) => l.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim())
+    .filter(Boolean);
+  const line = lines.find((l) => l.startsWith("error:")) ?? lines[0] ?? "(no output)";
+  return line.slice(0, max);
 }
 
 /** Write the full launch recap to a 0600 LOCAL log (never sent to the server —
@@ -285,11 +346,23 @@ export function writeRunnerLog(commandId: string, recap: string, cwd: string = p
     mkdirSync(dir, { recursive: true });
     writeFileSync(path, recap, { mode: 0o600 });
   } catch {
-    return "(local log unavailable)";
+    return LOG_UNAVAILABLE;
   }
   return path;
 }
 
+/** A `failed` report body carrying a structured reason (#496). The sentence is
+ *  derived from the REASON, so what the web shows is server/runner-authored copy,
+ *  never a raw client string; `error` keeps the operator-facing precision the
+ *  local log used to hold alone. */
+function refusalBody(
+  cmd: ClaimedCommand,
+  reason: SpawnReason,
+  error: string,
+): Record<string, unknown> {
+  return { fencing_token: cmd.fencing_token, status: "failed", reason, error };
+}
+
 async function report(
   auth: RunnerAuthLite,
   cmdId: string,
@@ -331,14 +404,24 @@ export async function executeClaim(
   try {
     policy = deps.policy ?? loadRunnerPolicy();
   } catch (err) {
-    const reason = err instanceof RunnerPolicyInvalidError ? err.message : "invalid local policy";
-    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: `local policy invalid: ${reason}` }, fetchImpl);
+    const cause = err instanceof RunnerPolicyInvalidError ? err.message : "invalid local policy";
+    await report(
+      auth,
+      cmd.id,
+      refusalBody(cmd, "policy_invalid", `local policy invalid: ${cause}`),
+      fetchImpl,
+    );
     return "failed";
   }
 
   const refusal = validateAgainstPolicy(cmd, policy);
   if (refusal) {
-    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: `local policy: ${refusal}` }, fetchImpl);
+    await report(
+      auth,
+      cmd.id,
+      refusalBody(cmd, "policy_refused", `local policy: ${refusal}`),
+      fetchImpl,
+    );
     return "failed";
   }
 
@@ -350,7 +433,7 @@ export async function executeClaim(
     const s = await report(
       auth,
       cmd.id,
-      { fencing_token: cmd.fencing_token, status: "failed", error: "prior partial run detected on this runner — not relaunched" },
+      refusalBody(cmd, "partial_run", "prior partial run detected on this runner — not relaunched"),
       fetchImpl,
     );
     if (s >= 200 && s < 300) inflight.clear(cmd.id);
@@ -360,7 +443,12 @@ export async function executeClaim(
   // template_name is the positional <name> in argv: positive allowlist (no
   // leading '-', no control char) — argv-flag-injection defense.
   if (!/^[A-Za-z0-9_.][A-Za-z0-9 _.-]{0,63}$/.test(cmd.template_name)) {
-    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: "unsafe template_name" }, fetchImpl);
+    await report(
+      auth,
+      cmd.id,
+      refusalBody(cmd, "unsafe_template_name", "unsafe template_name"),
+      fetchImpl,
+    );
     return "failed";
   }
 
@@ -378,21 +466,65 @@ export async function executeClaim(
   const { path: specPath, cleanup } = (deps.writeSpec ?? fsWriteSpec())(spec);
   try {
     // Allowlisted argv (C3): fixed flags + validated values, no free string.
-    const args = ["team", "spawn", "--spec-file", specPath, "--prefix", cmd.prefix];
+    // #496: a fresh nonce per launch, echoed back on the outcome marker.
+    // Threat model, stated precisely (Codex review): this DE-CORRELATES an
+    // accidental look-alike — an agent that prints this contract in its own
+    // output on the shared, deliberately-inherited stderr — which is the case
+    // that actually happens here. It is NOT authentication: a same-user process
+    // can read the parent's command line on Windows and forge the value. Nothing
+    // on this path can defend against a hostile local process, which already runs
+    // 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);
 
     inflight.mark(cmd.id); // durable "started here" BEFORE launch (C4)
-    const { ok, recap } = await runTeamSpawn(args);
-
-    // Generic remote report; full recap to a 0600 LOCAL log only (no secret leak).
+    const { ok, recap, reason, detail } = await runTeamSpawn(args, nonce);
+
+    // #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
+    // recap still goes ONLY to the 0600 local log (no secret leak); what changed
+    // is that the local log is no longer the sole place the cause exists. With no
+    // marker (older vibe-master, output lost to maxBuffer) we degrade to exactly
+    // the previous message rather than inventing a cause.
     const logPath = deps.writeLog ? deps.writeLog(cmd.id, recap) : writeRunnerLog(cmd.id, recap);
+    // #506, the issue's second defect: the remote message sent people to "the
+    // machine's log", and the log they actually open — the daemon's — only ever
+    // 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) {
+      const writeDaemonLine =
+        deps.writeDaemonLine ?? ((line: string) => process.stderr.write(`${line}\n`));
+      writeDaemonLine(
+        `[runner] spawn FAILED command=${cmd.id} reason=${reason ?? "unknown"} log=${logPath} ${firstErrorLine(recap)}`,
+      );
+    }
+    // Resolved ONCE: three call sites in a ternary could drift apart under a
+    // later edit, and they must agree on whether a log exists (Opus review).
+    const logRef = remoteLogRef(cmd.id, logPath);
     const finalStatus = await report(
       auth,
       cmd.id,
       ok
         ? { fencing_token: cmd.fencing_token, status: "succeeded", result: { message: "team spawn completed", log: logPath } }
-        : { fencing_token: cmd.fencing_token, status: "failed", error: "team spawn failed — see local runner log" },
+        : {
+            fencing_token: cmd.fencing_token,
+            status: "failed",
+            error: reason
+              ? messageForReason(
+                  reason,
+                  detail,
+                  rosterNames(cmd.prefix, cmd.template_spec.roles),
+                  logRef,
+                )
+              : logRef
+                ? `team spawn failed — see ${logRef} on that machine`
+                : "team spawn failed, and the local log could not be written on that machine",
+            ...(reason ? { reason } : {}),
+          },
       fetchImpl,
     );
     // Clear the inflight marker ONLY when the TERMINAL report is accepted (2xx)

package/lib/spawn_reason.ts

@@ -0,0 +1,230 @@
+/**
+ * spawn_reason.ts — the runner's half of the spawn-outcome contract (#496).
+ *
+ * A spawn refused on this machine used to reach the web as one sentence,
+ * "team spawn failed — see local runner log". Whoever clicked Spawn from a
+ * browser has no terminal and no access to that log: they saw a red failure and
+ * had nowhere to go. The cause existed — it was on the runner's stderr — and was
+ * thrown away here.
+ *
+ * `vibe-master` now emits a machine line (`VIBEMASTER_RESULT {"reason":…}`,
+ * see vibe-master/lib/spawn_result.ts). This module extracts it and 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
+ *  reason is dropped there, never stored raw — it comes from a client machine. */
+export const SPAWN_REASONS = [
+  // Emitted by vibe-master
+  "already_running",
+  "partial_team",
+  "template_invalid",
+  "roster_invalid",
+  "codex_unavailable",
+  "launch_failed",
+  // Emitted by the runner itself
+  "policy_invalid",
+  "policy_refused",
+  "unsafe_template_name",
+  "partial_run",
+] as const;
+
+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.
+ *
+ * A charset check is not enough (Codex review): `session-expired, sign-in, now`
+ * satisfies any agent-id pattern and would be rendered as though it listed
+ * members. The only trustworthy authority on what a name may be is the roster the
+ * SERVER validated and sent — so `detail` is not sanitized, it is INTERSECTED
+ * with that roster. A name the server never asked to spawn cannot reach the
+ * screen, whatever the runner sent, and prose cannot survive at all.
+ */
+const MAX_NAMES = 10;
+
+export function keepRosterNames(
+  detail: string | undefined,
+  roster: readonly string[],
+): string | undefined {
+  if (!detail) return undefined;
+  const allowed = new Set(roster);
+  const names = detail
+    .split(",")
+    .map((t) => t.trim())
+    .filter((t) => allowed.has(t))
+    .slice(0, MAX_NAMES);
+  return names.length > 0 ? names.join(", ") : undefined;
+}
+
+/**
+ * The agent names a command may talk about: `{prefix}-{role}`, plus
+ * `{prefix}-{role}-{n}` for replicated roles. Mirrors vibe-master's naming in
+ * `resolveTeamSpawn` — the two must move together.
+ */
+export function rosterNames(
+  prefix: string,
+  roles: readonly { role: string; count?: number }[],
+): string[] {
+  const names: string[] = [];
+  for (const r of roles) {
+    const count = r.count && r.count > 1 ? r.count : 1;
+    if (count === 1) {
+      names.push(`${prefix}-${r.role}`);
+      continue;
+    }
+    for (let i = 1; i <= count; i++) names.push(`${prefix}-${r.role}-${i}`);
+  }
+  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
+ * {@link keepRosterNames} first, so what is interpolated is provably a subset of
+ * the roster the server itself validated — never a sentence a machine chose.
+ * The roster is REQUIRED (Opus review): defaulting it to `[]` would let a caller
+ * drop every name in silence — the same "bypass by omission" the explicit marker
+ * trust closes, failing safe but failing quietly. A caller with no roster passes
+ * `[]` deliberately, and that shows in the diff.
+ *
+ * `policy_refused` interpolates NOTHING: its detail is free-form policy text, not
+ * a name list, so it cannot be shape-checked. The precision stays in the
+ * operator-facing `error`, off the screen.
+ */
+export function messageForReason(
+  reason: SpawnReason,
+  detail?: string,
+  roster: readonly string[],
+  logRef?: string,
+): string {
+  const safe = keepRosterNames(detail, roster);
+  const names = safe ? ` (${safe})` : "";
+  switch (reason) {
+    case "already_running":
+      // ATTRIBUTED, not asserted (Opus review). Of the nine reasons this is the
+      // ONLY one that renders as reassuring — every other paints red. So it is
+      // the one a buggy or compromised runner could use to claim "nothing was
+      // launched" while agents are actually running: the exact false green this
+      // issue exists to remove, re-entering through the pipe we just built. The
+      // server cannot verify the claim, so the copy SOURCES it instead. A user
+      // whose screen disagrees with their machine then knows what to doubt.
+      return `the runner reports that a team with this prefix was already running on this machine${names} — so nothing was launched`;
+    case "partial_team":
+      return `the runner reports that a team with this prefix is only PARTLY running — these members are missing${names}. Stop the survivors or pick a fresh prefix`;
+    case "template_invalid":
+      // On the web path this is NOT a user mistake: the runner never passes a
+      // template NAME, it writes the server-validated snapshot to a file and
+      // passes --spec-file. So this means the server's own snapshot could not be
+      // read back — a defect. Telling the user to go read a log they cannot open,
+      // for a problem they did not cause, would repeat this issue in miniature.
+      // #506, second defect of the issue: this sentence sent the reader to "the
+      // machine's log" WITHOUT naming it — and the log they did open, the
+      // daemon's, said nothing about the failure. `logRef` is the RELATIVE path
+      // (`.viber/runner-logs/<command_id>.log`): it locates the file without
+      // shipping an absolute Windows path — hence the machine's user name — to
+      // the server and onto someone's screen.
+      return `the roster sent for this spawn could not be read back on the runner machine — this is likely a defect, not something you did wrong; the full error is in ${logRef ?? "the machine's log"} on that machine`;
+    case "roster_invalid":
+      // #506: the OTHER half of what template_invalid used to swallow. The
+      // snapshot was read fine — it is the ROSTER that cannot be launched as
+      // written, and that IS the template author's to fix. Two catches, two
+      // reasons: this one says "you can fix this", template_invalid says "this
+      // is a defect on our side". Saying the second for the first sends someone
+      // to read a log for a mistake they could correct in two clicks.
+      return `this team template cannot be launched as written${names} — fix the template, then spawn again`;
+    case "codex_unavailable":
+      return "codex is not launchable on this machine, so no agent was started — install codex or set VIBER_CODEX_BIN";
+    case "launch_failed":
+      return `a member failed to start${names}; the rest of the roster was skipped — the team is incomplete`;
+    case "policy_invalid":
+      return "this machine's local runner policy is present but invalid, so the spawn was refused";
+    case "policy_refused":
+      return "this machine's local policy refuses this spawn";
+    case "unsafe_template_name":
+      return "the template name was rejected as unsafe by the runner";
+    case "partial_run":
+      return "a prior run of this command already started here and was not relaunched — check the machine before retrying";
+  }
+}

package/package.json

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