viber-channel 0.8.19 → 0.8.21

package/lib/runner_registry.ts

@@ -0,0 +1,413 @@
+/**
+ * runner_registry.ts — what the runner remembers about the agents it launched
+ * (#627 step-02).
+ *
+ * JP's rule: after a crash or a reboot nothing relaunches on its own, but the web
+ * offers, per disconnected conversation, "relaunch with the last settings". Those
+ * settings must therefore SURVIVE the machine — vibe-master's sidecar lives in
+ * tmpdir and dies with the boot (agent_meta.ts, #370), and the runner itself kept
+ * nothing per agent.
+ *
+ * One JSON file per backend, next to the agents' presence records:
+ *
+ *   <presenceDir(web host)>/runner/registry.json
+ *   <presenceDir(web host)>/runner/runner.json     ← the runner's own local state
+ *
+ * An entry is keyed by `registryKey(project_id, name)`. The NAME (`{prefix}-{role}`,
+ * `rosterNames`) is the label the agent registers with, and the server keeps labels
+ * unique PER PROJECT — two projects can both run a `627-dev-lead`. So the runner joins
+ * an entry to the presence record carrying the same (project_id, label).
+ *
+ * The file holds each role's `rolePrompt` in clear. It is not a secret (the server
+ * validated it and ships it to the agent), but it is written owner-only (0600 — a
+ * POSIX mode; on Windows the file inherits the profile's ACL), like the runner's
+ * other files. Tokens never go in a role prompt, and never go here.
+ *
+ * Known limit: two runners on the same machine AND the same backend (the app plus a
+ * source `run-runner`) would race on this file and could lose an update. One runner
+ * per backend per machine is the supported shape.
+ *
+ * ⚠ An UNREADABLE registry is kept as it is and blocks every write and every
+ * relaunch. Overwriting it would erase the settings of every agent on the machine,
+ * which is the one loss JP asked us never to cause.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { presenceDir } from "./presence_record.js";
+
+export const REGISTRY_SCHEMA_VERSION = 1;
+
+/** Closed entries older than this are dropped, so the file cannot grow forever. */
+export const CLOSED_ENTRY_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * The gateway's launch id of one member of one command — a COPY of
+ * `attemptLaunchId` (`viber-gateway/lib/team_derivation.ts`): `launch-` + the first 32
+ * hex of sha256 over the canonical JSON `{"agentId":…,"cmd":…}` (keys sorted).
+ * viber-channel is published alone and cannot import the gateway; the parity test in
+ * `test/runner_registry.test.ts` pins the copy to the original.
+ */
+export function launchIdFor(commandId: string, name: string): string {
+  const canonical = `{"agentId":${JSON.stringify(name)},"cmd":${JSON.stringify(commandId)}}`;
+  return `launch-${createHash("sha256").update(canonical).digest("hex").slice(0, 32)}`;
+}
+
+/**
+ * Does this job name belong to this launch? The gateway mints `vibe-agent-<launchId>-<token>`
+ * (`job_name.ts`). A PREFIX test on that published shape, bounded by the trailing `-`,
+ * so `launch-ab` never matches `launch-abc…`. Pinned by the same parity test.
+ */
+export function jobNameIsLaunch(jobName: string, launchId: string): boolean {
+  return jobName.startsWith(`vibe-agent-${launchId}-`);
+}
+
+/** The registry key of a member: project + name (a name is unique per project only). */
+export function registryKey(projectId: number | null, name: string): string {
+  return `${projectId ?? "-"}:${name}`;
+}
+
+/** The launch settings of one role, as the server snapshot validated them. */
+export interface RegistryRole {
+  role: string;
+  runtime: string;
+  permission: string;
+  rolePrompt?: string;
+  model?: string;
+}
+
+export type RegistryEntryState = "active" | "closed";
+
+export interface RegistryEntry {
+  name: string;
+  command_id: string;
+  template_name: string;
+  prefix: string;
+  team_name: string | null;
+  env: string | null;
+  project_id: number | null;
+  workspace: string;
+  role: RegistryRole;
+  launched_at: number;
+  /** The gateway's launch id of this member (`launchIdFor`): the exact join key. */
+  launch_id: string;
+  /** When the entry became closed; null while active. */
+  closed_at: number | null;
+  /** The instance that carries this name now; null until its record is seen. */
+  instance_id: string | null;
+  conversation_id: string | null;
+  state: RegistryEntryState;
+  /** A relaunch (step-07) names the instance it replaces. */
+  replaces: string | null;
+  /**
+   * The replaced instance, until the server acknowledged it CLOSED: the roster
+   * reports it `closed` every beat meanwhile (#627 step-07). Absent in a registry
+   * written before this field: read as null.
+   */
+  pending_close?: string | null;
+  /**
+   * #627 (decision A, Codex): OLDER replaced instances whose conversations were not
+   * handed over yet when this entry was relaunched AGAIN (its replacement died mid-
+   * handover). Each still travels as a pair with the entry's current instance.
+   */
+  handover_from?: string[];
+  /**
+   * #627 (Codex): every instance this name REPLACED (newest last, bounded) — never
+   * resent, only read to find the successor when an old instance's button is used
+   * after its handover was acknowledged or refused for good.
+   */
+  predecessors?: string[];
+}
+
+export interface Registry {
+  schema_version: number;
+  entries: Record<string, RegistryEntry>;
+}
+
+export type RegistryRead =
+  | { kind: "ok"; registry: Registry }
+  | { kind: "absent" }
+  | { kind: "unreadable"; error: string };
+
+export function runnerStateDir(identityBaseUrl: string, lockDir?: string): string {
+  return join(presenceDir(identityBaseUrl, lockDir), "runner");
+}
+
+export function registryPath(identityBaseUrl: string, lockDir?: string): string {
+  return join(runnerStateDir(identityBaseUrl, lockDir), "registry.json");
+}
+
+export function runnerStatePath(identityBaseUrl: string, lockDir?: string): string {
+  return join(runnerStateDir(identityBaseUrl, lockDir), "runner.json");
+}
+
+function atomicWriteJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2), { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // already gone
+    }
+    throw err;
+  }
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isStrOrNull(v: unknown): boolean {
+  return v === null || typeof v === "string";
+}
+
+function isEntry(key: string, v: unknown): v is RegistryEntry {
+  if (!isObject(v) || !isObject(v.role)) return false;
+  if (typeof v.name !== "string") return false;
+  if (!(v.project_id === null || typeof v.project_id === "number")) return false;
+  if (registryKey(v.project_id as number | null, v.name) !== key) return false;
+  const r = v.role;
+  const okRole =
+    typeof r.role === "string" && typeof r.runtime === "string" && typeof r.permission === "string";
+  const okText =
+    typeof v.command_id === "string" &&
+    typeof v.template_name === "string" &&
+    typeof v.prefix === "string" &&
+    typeof v.workspace === "string" &&
+    typeof v.launch_id === "string";
+  const okNullable =
+    isStrOrNull(v.team_name) &&
+    isStrOrNull(v.env) &&
+    isStrOrNull(v.instance_id) &&
+    isStrOrNull(v.conversation_id) &&
+    isStrOrNull(v.replaces) &&
+    (v.pending_close === undefined || isStrOrNull(v.pending_close)) &&
+    (v.handover_from === undefined || (Array.isArray(v.handover_from) && v.handover_from.every((x) => typeof x === "string"))) &&
+    (v.predecessors === undefined || (Array.isArray(v.predecessors) && v.predecessors.every((x) => typeof x === "string"))) &&
+    (v.project_id === null || typeof v.project_id === "number");
+  const okState = v.state === "active" || v.state === "closed";
+  const okClosedAt = v.closed_at === null || typeof v.closed_at === "number";
+  return okRole && okText && okNullable && okState && okClosedAt && typeof v.launched_at === "number";
+}
+
+export function readRegistry(path: string): RegistryRead {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { kind: "absent" };
+    return { kind: "unreadable", error: String(err) };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { kind: "unreadable", error: `invalid JSON: ${String(err)}` };
+  }
+  if (!isObject(parsed) || parsed.schema_version !== REGISTRY_SCHEMA_VERSION || !isObject(parsed.entries)) {
+    return { kind: "unreadable", error: "invalid registry shape" };
+  }
+  for (const [name, entry] of Object.entries(parsed.entries)) {
+    if (!isEntry(name, entry)) return { kind: "unreadable", error: `invalid entry ${JSON.stringify(name)}` };
+  }
+  return { kind: "ok", registry: parsed as unknown as Registry };
+}
+
+/**
+ * Apply `change` to the registry on disk. Absent → start empty. Unreadable →
+ * REFUSE, leave the file untouched, and say so: the caller logs, never retries by
+ * overwriting.
+ */
+export function updateRegistry(
+  path: string,
+  /** Return `false` to skip the write (nothing changed). */
+  change: (registry: Registry) => boolean | void,
+): { ok: true } | { ok: false; error: string } {
+  const read = readRegistry(path);
+  if (read.kind === "unreadable") return { ok: false, error: `registry unreadable, left untouched: ${read.error}` };
+  const registry: Registry =
+    read.kind === "ok" ? read.registry : { schema_version: REGISTRY_SCHEMA_VERSION, entries: {} };
+  if (change(registry) === false) return { ok: true };
+  try {
+    atomicWriteJson(path, registry);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: `registry write failed: ${String(err)}` };
+  }
+}
+
+/** What a spawn command tells the registry, taken from the claimed command. */
+export interface SpawnForRegistry {
+  command_id: string;
+  template_name: string;
+  prefix: string;
+  team_name: string | null;
+  env: string | null;
+  project_id: number | null;
+  workspace: string;
+  roles: readonly (RegistryRole & { count?: number })[];
+}
+
+/**
+ * The member names of a roster, each with its role — the same naming as
+ * `rosterNames` (`{prefix}-{role}`, `-{i}` suffix when count > 1).
+ */
+export function rosterMembers(
+  prefix: string,
+  roles: readonly (RegistryRole & { count?: number })[],
+): { name: string; role: RegistryRole }[] {
+  const members: { name: string; role: RegistryRole }[] = [];
+  for (const r of roles) {
+    const { count, ...role } = r;
+    const n = count && count > 1 ? count : 1;
+    if (n === 1) {
+      members.push({ name: `${prefix}-${r.role}`, role });
+      continue;
+    }
+    for (let i = 1; i <= n; i++) members.push({ name: `${prefix}-${r.role}-${i}`, role });
+  }
+  return members;
+}
+
+/**
+ * Record a launched team. A member already present is REPLACED: a new launch under
+ * the same name supersedes the settings of the old one, and its instance is not
+ * known until the new agent's record appears.
+ */
+export function recordSpawn(registry: Registry, spawn: SpawnForRegistry, now: number): void {
+  pruneClosed(registry, now);
+  for (const { name, role } of rosterMembers(spawn.prefix, spawn.roles)) {
+    registry.entries[registryKey(spawn.project_id, name)] = {
+      name,
+      command_id: spawn.command_id,
+      template_name: spawn.template_name,
+      prefix: spawn.prefix,
+      team_name: spawn.team_name,
+      env: spawn.env,
+      project_id: spawn.project_id,
+      workspace: spawn.workspace,
+      role,
+      launched_at: now,
+      launch_id: launchIdFor(spawn.command_id, name),
+      closed_at: null,
+      instance_id: null,
+      conversation_id: null,
+      state: "active",
+      replaces: null,
+      pending_close: null,
+    };
+  }
+}
+
+/** Drop closed entries past `CLOSED_ENTRY_TTL_MS`. */
+export function pruneClosed(registry: Registry, now: number): void {
+  for (const [key, entry] of Object.entries(registry.entries)) {
+    if (entry.state === "closed" && entry.closed_at !== null && now - entry.closed_at > CLOSED_ENTRY_TTL_MS) {
+      delete registry.entries[key];
+    }
+  }
+}
+
+/** What the runner saw in one LIVE agent's presence record. */
+export interface SeenAgent {
+  label: string | null;
+  project_id: number | null;
+  instance_id: string;
+  conversation_id: string | null;
+  /** The record's `created_at`: when two live records carry the same name, the newest wins. */
+  created_at: number;
+  /** The record's `job_name`: when present, the EXACT join to an entry's launch. */
+  job_name: string | null;
+}
+
+/**
+ * Keep entries in step with the agents' records: the instance that carries a name
+ * and the conversation it is on. Returns whether anything changed, so the caller
+ * writes only when needed. A record without a label, or for a name the runner never
+ * launched, is ignored here — the runner reports it all the same (step-03).
+ */
+export function syncFromRecords(registry: Registry, seen: readonly SeenAgent[]): boolean {
+  // 1. EXACT: a record whose job name is an entry's launch belongs to that entry,
+  //    whatever its label says. 2. ONLY for a record with no job name (an agent the
+  //    gateway did not launch, or older than #627): (project, name), and when two live records
+  //    share it — a relaunch overlapping its old process — the NEWEST wins. Never
+  //    the directory order.
+  const winners = new Map<string, { agent: SeenAgent; exact: boolean }>();
+  for (const agent of seen) {
+    const exactK = exactKey(registry, agent);
+    // A record WITH a job name belongs to that launch or to none: an old launch's
+    // record must never fill the entry of a newer one by its name (Codex, 2nd round).
+    const byName = agent.job_name === null && agent.label !== null;
+    const key = exactK ?? (byName ? registryKey(agent.project_id, agent.label as string) : undefined);
+    if (key === undefined) continue;
+    const exact = exactK !== undefined;
+    const held = winners.get(key);
+    const wins =
+      held === undefined ||
+      (exact && !held.exact) ||
+      (exact === held.exact && agent.created_at > held.agent.created_at);
+    if (wins) winners.set(key, { agent, exact });
+  }
+  let changed = false;
+  for (const [key, { agent }] of winners) {
+    const entry = registry.entries[key];
+    if (entry === undefined || entry.state === "closed") continue;
+    if (entry.instance_id !== agent.instance_id || entry.conversation_id !== agent.conversation_id) {
+      entry.instance_id = agent.instance_id;
+      entry.conversation_id = agent.conversation_id;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+/** The runner's own local presence, read by its agents (step-06). */
+export interface RunnerState {
+  schema_version: number;
+  runner_id: string;
+  /** Epoch ms of the last heartbeat the server answered 2xx; null before the first. */
+  last_beat_ok_at: number | null;
+}
+
+export function writeRunnerState(path: string, state: Omit<RunnerState, "schema_version">): void {
+  atomicWriteJson(path, { schema_version: REGISTRY_SCHEMA_VERSION, ...state });
+}
+
+export function readRunnerState(path: string): RunnerState | null {
+  try {
+    const v: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!isObject(v) || v.schema_version !== REGISTRY_SCHEMA_VERSION) return null;
+    if (typeof v.runner_id !== "string") return null;
+    if (!(v.last_beat_ok_at === null || typeof v.last_beat_ok_at === "number")) return null;
+    return v as unknown as RunnerState;
+  } catch {
+    return null;
+  }
+}
+
+function exactKey(registry: Registry, agent: SeenAgent): string | undefined {
+  if (agent.job_name === null) return undefined;
+  for (const [key, entry] of Object.entries(registry.entries)) {
+    // An empty launch id (a relaunch without a gateway job name) never joins exactly.
+    if (entry.launch_id !== "" && jobNameIsLaunch(agent.job_name, entry.launch_id)) return key;
+  }
+  return undefined;
+}
+
+/** A closed instance, acknowledged by the server: its entry will not be relaunched. */
+export function markClosed(registry: Registry, instanceIds: readonly string[], now: number): boolean {
+  const ids = new Set(instanceIds);
+  let changed = false;
+  for (const entry of Object.values(registry.entries)) {
+    if (entry.state === "active" && entry.instance_id !== null && ids.has(entry.instance_id)) {
+      entry.state = "closed";
+      entry.closed_at = now;
+      changed = true;
+    }
+  }
+  return changed;
+}

package/lib/runner_relaunch.ts

@@ -0,0 +1,181 @@
+/**
+ * runner_relaunch.ts — the runner brings back ONE agent (#627 step-07).
+ *
+ * The web asked (JP, 2026-09-25): per disconnected conversation, "relaunch with the
+ * last settings". The server sends a `relaunch` command naming the instance; the
+ * runner — the only party that can see the machine — decides:
+ *
+ *   - no registry entry for that instance     → refused (only an agent this runner
+ *                                                knows is relaunchable, JP 2026-09-26);
+ *   - its process is still ALIVE               → nothing is launched: the runner's next
+ *                                                roster re-attaches it (a duplicate
+ *                                                agent on one conversation is the one
+ *                                                thing the lease exists to prevent);
+ *   - the runner CANNOT TELL                   → refused, never a guess;
+ *   - dead (record gone after an acknowledged
+ *     down, or dead by pid + start time)       → `vibe-master spawn` with the saved
+ *                                                settings, on the SAME conversation
+ *                                                (Gemma cannot reload one: a new one).
+ *
+ * After a successful launch the entry remembers the instance it replaces and marks
+ * it `pending_close`: the roster reports that old instance `closed` until the server
+ * acknowledges it, so no greyed ghost stays behind the new agent.
+ */
+import { enumerateStartTimes } from "./process_start.js";
+import { presenceRecordPath, readPresenceRecord } from "./presence_record.js";
+import { type RegistryEntry, readRegistry, registryPath, updateRegistry } from "./runner_registry.js";
+import { classifyRecord, type ProcessTable } from "./runner_roster.js";
+
+/** What the web may be told: a typed outcome, like every other spawn report. */
+export type RelaunchOutcome =
+  | { kind: "launched"; message: string }
+  | { kind: "reattached"; message: string }
+  | { kind: "refused"; error: string; policy?: boolean; /** vibe-master's own output, for the LOCAL log only. */ recap?: string };
+
+/** vibe-master's runtime ids for the ones a roster carries. */
+function vibeMasterRuntime(runtime: string): string {
+  return runtime === "claude-code" ? "claude" : runtime;
+}
+
+/** Runtimes that can reload an existing conversation (`vibe-master spawn --conversation`). */
+const RELOADS_CONVERSATION = new Set(["claude", "codex"]);
+
+/**
+ * The argv for one member, from its saved settings. PURE. `--conversation` only for a
+ * runtime that can reload one; Gemma starts a new conversation (JP, 2026-09-25).
+ */
+export function relaunchArgs(entry: RegistryEntry): string[] {
+  const runtime = vibeMasterRuntime(entry.role.runtime);
+  // `--mode terminal`, like the runner's team launch (runner_exec.ts). Measured live (#627
+  // step 11): without it a codex relaunch defaults to background mode, which goes through
+  // vctl — and the runner's cwd (the app home) is no vctl project, so every relaunch failed.
+  const args = ["spawn", "--runtime", runtime, "--permission", entry.role.permission, "--cwd", entry.workspace, "--name", entry.name, "--mode", "terminal"];
+  if (entry.team_name) args.push("--team", entry.team_name);
+  if (entry.env) args.push("--env", entry.env);
+  if (entry.role.model) args.push("--model", entry.role.model);
+  if (entry.conversation_id && RELOADS_CONVERSATION.has(runtime)) args.push("--conversation", entry.conversation_id);
+  // Last: free text, nothing appended after it (same rule as the gateway's argv).
+  if (entry.role.rolePrompt) args.push("--role", entry.role.rolePrompt);
+  return args;
+}
+
+export interface RelaunchDeps {
+  identity: string;
+  lockDir?: string;
+  enumerate?: () => Promise<ProcessTable | undefined>;
+  /** Runs `vibe-master <args>`; ok = exit 0. */
+  runSpawn: (args: string[]) => Promise<{ ok: boolean; recap: string }>;
+  now?: () => number;
+  /** Today's local policy on the saved settings; a string = refused. */
+  checkPolicy?: (entry: RegistryEntry) => string | null;
+  /** Test seam: runs between the registry read and its preparation (a race). */
+  beforePrepare?: () => void;
+}
+
+function findEntry(entries: Record<string, RegistryEntry>, instanceId: string): [string, RegistryEntry] | undefined {
+  return Object.entries(entries).find(([, e]) => e.instance_id === instanceId);
+}
+
+/** Replaced instances remembered per name, only to find their successor (Codex). */
+export const PREDECESSORS_KEPT = 20;
+
+/** #627 (decision A, Codex): the entry that REPLACED this instance, if any. */
+function findSuccessor(entries: Record<string, RegistryEntry>, instanceId: string): [string, RegistryEntry] | undefined {
+  return Object.entries(entries).find(
+    ([, e]) =>
+      e.state !== "closed" &&
+      (e.pending_close === instanceId || (e.handover_from ?? []).includes(instanceId) || (e.predecessors ?? []).includes(instanceId)),
+  );
+}
+
+export async function relaunchInstance(requestedId: string, deps: RelaunchDeps): Promise<RelaunchOutcome> {
+  const path = registryPath(deps.identity, deps.lockDir);
+  const read = readRegistry(path);
+  if (read.kind !== "ok") {
+    return { kind: "refused", error: read.kind === "absent" ? "this runner launched no agent yet" : `registry unreadable: ${read.error}` };
+  }
+  // #627 (decision A, Codex): relaunching an instance that was already REPLACED means
+  // relaunching its name — the entry now carries its successor, whose settings and
+  // handover it inherits. One launch per name: a successor still starting is refused.
+  let instanceId = requestedId;
+  let found = findEntry(read.registry.entries, instanceId);
+  if (found === undefined) {
+    const successor = findSuccessor(read.registry.entries, instanceId);
+    if (successor !== undefined) {
+      const current = successor[1].instance_id;
+      if (current === null) {
+        return { kind: "refused", error: "a relaunch of this agent is already starting — wait for it to come online" };
+      }
+      instanceId = current;
+      found = successor;
+    }
+  }
+  if (found === undefined) {
+    return { kind: "refused", error: "this runner has no saved settings for that agent — only an agent it launched can be relaunched" };
+  }
+  const [key, entry] = found;
+  if (entry.state === "closed") return { kind: "refused", error: "that agent was closed on purpose" };
+
+  // Alive? The record, when it still exists, is checked like the roster checks it.
+  const rec = readPresenceRecord(presenceRecordPath(deps.identity, instanceId, deps.lockDir));
+  if (rec.kind === "unreadable") return { kind: "refused", error: "cannot tell whether that agent is still running (its record is unreadable)" };
+  if (rec.kind === "ok") {
+    const table = await (deps.enumerate ?? (() => enumerateStartTimes()))();
+    if (table === undefined) return { kind: "refused", error: "cannot tell whether that agent is still running (process enumeration failed)" };
+    const verdict = classifyRecord(rec.record, table);
+    if (verdict.kind === "present") {
+      return { kind: "reattached", message: "that agent is still running — it is re-attached, nothing was launched" };
+    }
+    if (verdict.kind === "unknown") return { kind: "refused", error: `cannot tell whether that agent is still running (${verdict.why})` };
+    // A DECIDED end not acknowledged yet (revoked, lease lost to another holder,
+    // --once done) is a close: relaunching it is what decision 3 excludes (Opus I1).
+    if (verdict.kind === "closed") return { kind: "refused", error: "that agent ended on purpose — nothing to relaunch" };
+  }
+  // Record absent (an acknowledged down, then removed) or dead by pid + start time.
+
+  const refusal = deps.checkPolicy?.(entry) ?? null;
+  if (refusal !== null) return { kind: "refused", error: `local policy: ${refusal}`, policy: true };
+
+  // The registry is written BEFORE the launch (Codex): a launch whose bookkeeping
+  // could not be recorded would leave the old instance greyed for good and the new
+  // one unjoinable. A failed launch then restores the entry as it was.
+  const now = (deps.now ?? Date.now)();
+  const before = { ...entry };
+  deps.beforePrepare?.();
+  let preparedEntry = false;
+  const prepared = updateRegistry(path, (r) => {
+    const e = r.entries[key];
+    if (e === undefined) return false; // gone since the read: see `preparedEntry` below
+    preparedEntry = true;
+    e.replaces = instanceId;
+    // A predecessor still waiting for its handover is kept, not overwritten: its
+    // conversations go to whichever instance runs this name next (Codex).
+    if (e.pending_close && e.pending_close !== instanceId) {
+      e.handover_from = [...new Set([...(e.handover_from ?? []), e.pending_close])].filter((id) => id !== instanceId);
+    }
+    e.pending_close = instanceId;
+    e.predecessors = [...(e.predecessors ?? []).filter((id) => id !== instanceId), instanceId].slice(-PREDECESSORS_KEPT);
+    e.instance_id = null;
+    e.launched_at = now;
+    e.state = "active";
+    // This relaunch has no gateway job name: the old launch id must not let an old
+    // process's record join the NEW entry exactly (Opus I2). The new agent joins by
+    // (project, name), then its own instance id.
+    e.launch_id = "";
+    return true;
+  });
+  if (!prepared.ok) return { kind: "refused", error: `the runner registry could not be updated, nothing launched: ${prepared.error}` };
+  // "Nothing written" is not success: the entry vanished between the read and the
+  // write, so there is nowhere to record the new agent — never launch (Codex).
+  if (!preparedEntry) return { kind: "refused", error: "that agent's saved settings vanished before the relaunch, nothing launched" };
+
+  const result = await deps.runSpawn(relaunchArgs(entry));
+  if (!result.ok) {
+    updateRegistry(path, (r) => {
+      r.entries[key] = before;
+      return true;
+    });
+    return { kind: "refused", error: "vibe-master could not relaunch that agent — see the runner log", recap: result.recap };
+  }
+  return { kind: "launched", message: `relaunched ${entry.name} with its last settings` };
+}