viber-channel 0.8.31 → 0.8.32

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.",

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_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/package.json

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