@runuai/host 0.9.12 → 0.9.14

package/lib/agent-cli.ts

@@ -168,6 +168,22 @@ function parseFlags(args) {
   return { flags, rest };
 }
 
+// A punchlist item's text is prose, and prose written in THIS repo contains
+// --id and --text. parseFlags is global and greedy, so routing todo text
+// through it silently rewrote the request: "todo edit aaaaaa the --id flag"
+// resolved to { ref: "flag", text: "aaaaaa the" } and edited a different item,
+// and a valueless --text became the literal string "true" — an item
+// overwritten with garbage, or worse, the wrong item overwritten at all. Todo
+// text is therefore read from the raw argv tail and never flag-parsed. The
+// --id <ref> form survives only in leading position, where it cannot be
+// mistaken for prose.
+function todoRef(args) {
+  return args[0] === "--id"
+    ? { ref: args[1], tail: args.slice(2) }
+    : { ref: args[0] && !args[0].startsWith("--") ? args[0] : "", tail: args.slice(1) };
+}
+function todoText(args) { return args.join(" ").trim(); }
+
 async function api(method, path, body) {
   const res = await fetch(API_URL + path, {
     method,
@@ -292,14 +308,30 @@ async function main() {
       break;
     }
     case "todo add": {
-      const text = pos.join(" ") || flags.text || "";
+      const text = todoText(rest);
       if (!text) { console.error("uai: todo add needs text"); process.exit(1); }
       const t = (await api("POST", "/api/agent/todos", { op: "add", text })).todo;
       out("added #" + t.shortId + ": " + t.text);
       break;
     }
+    case "todo edit": {
+      const { ref, tail } = todoRef(rest);
+      const text = todoText(tail);
+      if (!ref) { console.error("uai: todo edit needs an item id (see 'uai todo list')"); process.exit(1); }
+      if (!text) { console.error("uai: todo edit needs replacement text"); process.exit(1); }
+      const t = (await api("POST", "/api/agent/todos", { op: "edit", ref, text })).todo;
+      out("edited #" + t.shortId + ": " + t.text);
+      break;
+    }
+    case "todo remove": {
+      const { ref } = todoRef(rest);
+      if (!ref) { console.error("uai: todo remove needs an item id (see 'uai todo list')"); process.exit(1); }
+      await api("POST", "/api/agent/todos", { op: "remove", ref });
+      out("removed #" + String(ref).replace(/^#/, ""));
+      break;
+    }
     case "todo claim": case "todo done": case "todo reopen": case "todo unclaim": {
-      const ref = pos[0] || flags.id;
+      const { ref } = todoRef(rest);
       if (!ref) { console.error("uai: todo " + action + " needs an item id (see 'uai todo list')"); process.exit(1); }
       const t = (await api("POST", "/api/agent/todos", { op: action, ref })).todo;
       out(action + " #" + t.shortId + ": " + t.text);
@@ -359,6 +391,8 @@ async function main() {
         "  uai memory delete <id>",
         "  uai todo list",
         "  uai todo add <text>",
+        "  uai todo edit <#id> <text>",
+        "  uai todo remove <#id>",
         "  uai todo claim|done|reopen|unclaim <#id>",
         "  uai preview add <name> <containerPort>",
         "  uai project create --name <n> --repo <git-url> [--prompt <p>]",

package/lib/orchestrator.ts

@@ -3083,7 +3083,9 @@ export function buildSystemPreamble(
         "You are one agent in a uai task chat channel, shared with the human",
         "and the other agents. To hand work to or ask another agent, mention",
         "it by id at the start of a line — e.g. `@codex please review the",
-        "diff`. uai routes that message into that agent's input.",
+        "diff`. uai buffers the handoff and routes your complete turn into that",
+        "agent's input only after your current turn ends. The mention does NOT",
+        "wake the peer while you continue using tools in the same turn.",
         ];
   const collaborationBrief = isSecretary
     ? [
@@ -3107,8 +3109,9 @@ export function buildSystemPreamble(
         "Collaborate with your peers — divide up the work, review each other's",
         "changes, share concrete ideas, and debate approach decisions by",
         "@-mentioning them. That is how the team gets things done, and you",
-        "should do it freely whenever it moves the work forward. But mentioning",
-        "a peer WAKES it and costs a turn, so make each one count: a message to",
+        "should do it freely whenever it moves the work forward. But a peer",
+        "@mention WAKES it after your turn ends and costs a turn, so make each",
+        "one count: a message to",
         "a peer should ADVANCE the work — a real proposal, a question you need",
         "answered, a hand-off, or a review with specific findings. Do NOT",
         "@-mention a peer just to greet, thank, agree, acknowledge, or say",
@@ -3267,7 +3270,7 @@ export function buildSystemPreamble(
               ? ", `memory search <query>`"
               : "") +
             (agent.permissions?.includes("todo.write")
-              ? ", `todo list|add|claim|done`"
+              ? ", `todo list|add|edit|remove|claim|done`"
               : "") +
             (agent.permissions?.includes("previews.write")
               ? ", `preview add <name> <port>`"
@@ -3327,7 +3330,9 @@ export function buildSystemPreamble(
                 "**`todo claim <#id>` BEFORE you start** an item so two agents",
                 "don't do the same work — and `todo done <#id>` when it's",
                 "complete. Check `todo list` before picking up work. The human",
-                "watches the same list in the task UI.",
+                "watches the same list in the task UI. Use `todo edit <#id>",
+                "<text>` to correct an item and `todo remove <#id>` to delete",
+                "one; both refuse an item another agent is actively claiming.",
               ]
             : []),
           ...(agent.permissions?.includes("tasks.history")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/scripts/agent/task-up.sh

@@ -167,6 +167,22 @@ fi
 reject_unsafe_host_directory "$task_workspace" "the task workspace"
 mkdir -p "$task_workspace"
 
+# Git resolves symlinked ancestors when it writes a linked worktree's absolute
+# `.git` pointer. Keep the configured (lexical) task paths as Uai's stable host
+# paths, but also remember their physical aliases for validation and bind-mount
+# destinations. The task root itself was rejected above if it was a symlink;
+# `pwd -P` therefore resolves only trusted ancestors such as a migrated
+# UAI_WORKSPACE_ROOT (`~/.uai-host-app/workspace -> ~/.uai`).
+step "WORKTREE_FAILED" "resolve task workspace paths"
+if ! task_dir_physical=$(cd "$task_dir" && pwd -P) \
+  || [ -z "$task_dir_physical" ]; then
+  emit_err "WORKTREE_FAILED" \
+    "Uai could not resolve the task workspace's physical host path" \
+    "resolve task workspace paths"
+fi
+task_workspace_physical="$task_dir_physical/workspace"
+task_uai_dir_physical="$task_dir_physical/.uai"
+
 # -----------------------------------------------------------------------------
 # 3. Bare mirrors + worktrees, one per selected project.
 # -----------------------------------------------------------------------------
@@ -486,6 +502,7 @@ while IFS= read -r project_obj; do
   # that old bind mount. The new cache path has never entered a container.
   mirror_dir="$projects_root/$project_id/host-cache.git"
   task_repo_dir="$task_uai_dir/repos/$project_id.git"
+  task_repo_dir_physical="$task_uai_dir_physical/repos/$project_id.git"
   worktree_target="$task_workspace/$project_slug"
   reject_unsafe_host_directory "$worktree_target" \
     "the project worktree for $project_slug"
@@ -513,14 +530,18 @@ while IFS= read -r project_obj; do
       gitdir_lines=$(awk 'END { print NR }' "$worktree_target/.git")
       gitdir_value=$(sed -n 's/^gitdir: //p' "$worktree_target/.git")
       case "$gitdir_value" in
-        "$task_repo_dir"/worktrees/*) ;;
+        "$task_repo_dir"/worktrees/*)
+          gitdir_leaf=${gitdir_value#"$task_repo_dir"/worktrees/}
+          ;;
+        "$task_repo_dir_physical"/worktrees/*)
+          gitdir_leaf=${gitdir_value#"$task_repo_dir_physical"/worktrees/}
+          ;;
         *)
           emit_err "WORKTREE_FAILED" \
             "This task uses Uai's legacy shared Git layout. Its container has been removed so it can no longer write the shared mirror. Preserve any uncommitted changes from $worktree_target, then recreate the task to migrate safely." \
             "legacy task repository requires recreation ($project_id)"
           ;;
       esac
-      gitdir_leaf=${gitdir_value#"$task_repo_dir"/worktrees/}
       case "$gitdir_leaf" in
         ''|.|..|*/*)
           emit_err "WORKTREE_FAILED" \
@@ -1018,11 +1039,24 @@ fi
   # repository is mounted; the host cache never enters a container. Legacy
   # worktrees fail closed before Compose rendering and must be recreated.
   printf '      - "%s:%s"\n' "$task_workspace" "$task_workspace"
+  if [ "$task_workspace_physical" != "$task_workspace" ]; then
+    # Git canonicalizes a symlinked workspace root in both directions: the
+    # worktree's `.git` points at the physical repository, and the repository's
+    # worktree metadata points back at the physical workspace. Mount the same
+    # already-approved workspace at that alias without exposing its `.uai`
+    # sibling or any broader host directory.
+    printf '      - "%s:%s"\n' \
+      "$task_workspace" "$task_workspace_physical"
+  fi
   while IFS= read -r vol_obj; do
     [ -n "$vol_obj" ] || continue
     vol_pid=$(jq -r '.id' <<<"$vol_obj")
     printf '      - "%s/repos/%s.git:%s/repos/%s.git"\n' \
       "$task_uai_dir" "$vol_pid" "$task_uai_dir" "$vol_pid"
+    if [ "$task_uai_dir_physical" != "$task_uai_dir" ]; then
+      printf '      - "%s/repos/%s.git:%s/repos/%s.git"\n' \
+        "$task_uai_dir" "$vol_pid" "$task_uai_dir_physical" "$vol_pid"
+    fi
   done < <(jq -c '.[]' <<<"$projects_json")
   printf '      - "%s:/opt/asdf-data"\n' "$ASDF_VOLUME"
   # ADR-053: host-wide Playwright browser cache. Always mounted (harmless
@@ -1290,7 +1324,9 @@ while IFS= read -r safe_project; do
   for safe_worktree in \
     "/workspace/$safe_project_slug" \
     "$task_workspace/$safe_project_slug" \
-    "$task_uai_dir/repos/$safe_project_id.git"; do
+    "$task_uai_dir/repos/$safe_project_id.git" \
+    "$task_workspace_physical/$safe_project_slug" \
+    "$task_uai_dir_physical/repos/$safe_project_id.git"; do
     if ! printf '%s\n' "$container_safe_dirs" \
       | grep -Fqx -- "$safe_worktree"; then
       if ! docker exec -u node "${managed_exec_env[@]}" "$app_container" \
@@ -1305,6 +1341,26 @@ while IFS= read -r safe_project; do
   done
 done < <(jq -c '.[]' <<<"$projects_json")
 
+# A running container is not sufficient proof that its linked worktrees are
+# usable. In particular, Git may have canonicalized a symlinked host workspace
+# root while Compose mounted only its lexical spelling. Verify the actual path
+# agents use before credentials, dependency installation, or status=running.
+step "CONTAINER_INIT_FAILED" "verify task Git worktrees"
+while IFS= read -r verify_project; do
+  [ -n "$verify_project" ] || continue
+  verify_project_slug=$(jq -r '.slug' <<<"$verify_project")
+  verify_is_worktree=""
+  if ! verify_is_worktree=$(docker exec -u node "${managed_exec_env[@]}" \
+    "$app_container" "${managed_clean_env[@]}" /usr/bin/git \
+    -C "/workspace/$verify_project_slug" rev-parse \
+    --is-inside-work-tree 2>/dev/null) \
+    || [ "$verify_is_worktree" != "true" ]; then
+    emit_err "CONTAINER_INIT_FAILED" \
+      "Uai could not open $verify_project_slug as a Git worktree inside the task container. Retry the task after checking the host workspace path." \
+      "verify task Git worktree ($verify_project_slug)"
+  fi
+done < <(jq -c '.[]' <<<"$projects_json")
+
 # A failed/retried start can preserve a container that still holds a previous
 # account. Erase that Uai-managed state first for both connected and
 # disconnected starts; otherwise a no-credential resume could briefly reuse a

package/src/event-outbox.ts

@@ -0,0 +1,104 @@
+/**
+ * ADR-103: the host-side event outbox.
+ *
+ * Every HostEvent gets a monotonic seq and its serialized wire frame is held
+ * here until the cloud acks it. The bridge connection drains the outbox in
+ * order — live traffic and reconnect replay are the same code path, so a
+ * WSS blip (a cloud deploy) can no longer drop events on the floor.
+ *
+ * Bounded, in-memory. A host PROCESS restart still loses unsent events —
+ * that path is ADR-061's (the restarted host reattaches to the container
+ * and resumes streaming); this outbox closes the disconnect gap only.
+ */
+
+import type { HostEvent } from "./protocol";
+
+export interface OutboxEntry {
+  seq: number;
+  /** The full serialized `{kind:"event", seq, event}` frame, ready to send. */
+  raw: string;
+}
+
+/** Overflow bounds. Generous: a disconnect longer than this many events is a
+ *  real outage, not a deploy blip, and dropping OLDEST keeps the tail — the
+ *  most recent turn — intact for replay. */
+const MAX_ENTRIES = 10_000;
+const MAX_BYTES = 32 * 1024 * 1024;
+
+export class EventOutbox {
+  private entries: OutboxEntry[] = [];
+  private totalBytes = 0;
+  private nextSeq = 1;
+  /** Highest seq ever transmitted on any connection. */
+  private sentUpTo = 0;
+  /** Entries dropped by overflow since the last drain — for one loud log. */
+  private droppedSinceDrain = 0;
+
+  /** Serialize + append. Returns the entry's seq. */
+  enqueue(event: HostEvent): number {
+    const seq = this.nextSeq++;
+    const raw = JSON.stringify({ kind: "event", seq, event });
+    this.entries.push({ seq, raw });
+    this.totalBytes += raw.length;
+    while (
+      this.entries.length > MAX_ENTRIES ||
+      (this.totalBytes > MAX_BYTES && this.entries.length > 1)
+    ) {
+      const dropped = this.entries.shift();
+      if (!dropped) break;
+      this.totalBytes -= dropped.raw.length;
+      // Only a NEVER-SENT entry is a real loss; an unacked-but-sent one most
+      // likely landed and just lost its ack.
+      if (dropped.seq > this.sentUpTo) this.droppedSinceDrain += 1;
+    }
+    return seq;
+  }
+
+  /** Cumulative ack: forget everything up to and including `seq`. */
+  ack(seq: number): void {
+    let i = 0;
+    for (const entry of this.entries) {
+      if (entry.seq > seq) break;
+      this.totalBytes -= entry.raw.length;
+      i += 1;
+    }
+    if (i > 0) this.entries.splice(0, i);
+    if (seq > this.sentUpTo) this.sentUpTo = seq;
+  }
+
+  /**
+   * Rewind the transmit cursor for a reconnect (ADR-103 resume handshake).
+   * `afterSeq` is the cloud's watermark: everything newer re-sends on the
+   * next drain. `null` = the cloud has no state for this boot — replay
+   * nothing; only never-transmitted entries go out.
+   */
+  resume(afterSeq: number | null): void {
+    if (afterSeq !== null && afterSeq < this.sentUpTo) this.sentUpTo = afterSeq;
+  }
+
+  /**
+   * Entries due for transmission, in order. The caller sends them and the
+   * cursor advances — drain is idempotent per entry until `resume` rewinds.
+   */
+  drain(): OutboxEntry[] {
+    const due = this.entries.filter((e) => e.seq > this.sentUpTo);
+    const last = due[due.length - 1];
+    if (last) this.sentUpTo = last.seq;
+    return due;
+  }
+
+  /** Never-sent entries lost to overflow since the last call; resets. */
+  takeDroppedCount(): number {
+    const n = this.droppedSinceDrain;
+    this.droppedSinceDrain = 0;
+    return n;
+  }
+
+  get size(): number {
+    return this.entries.length;
+  }
+
+  get bytes(): number {
+    return this.totalBytes;
+  }
+}

package/src/index.ts

@@ -171,26 +171,123 @@ export const hostCommands: HostCommands = {
             .split(/\r?\n/)
             .some((state) => state.trim() === "running")
         ) {
-          // waitForChannelClose crossed the teardown fence above. A completed
-          // close-only teardown may have left this running task tombstoned, so
-          // the idempotent-success transition must reopen delivery just like a
-          // fresh successful taskUp does.
-          orchestrator.allowChannel(input.task.id);
-          return {
-            ok: true,
-            value: {
-              composeProject: existingTask.composeProject,
-              worktreePath: existingTask.worktreePath,
-              codeServerPort: existingTask.codeServerPort ?? undefined,
-              previewPorts: parsePreviewPortRuntimes(
-                existingTask.previewPorts,
-              ),
-            },
-          };
+          // Docker being up is not enough to prove a lost-response retry is
+          // healthy. The worktree's `.git` file contains an absolute pointer
+          // into the task-private repository; after a host workspace-root
+          // migration the old container can keep running while every agent
+          // sees `fatal: not a git repository`. Probe from INSIDE the live
+          // container, which is the filesystem view the agents actually use.
+          // Scratchpads have no projects, so this remains an O(1) fast path.
+          const appContainer = `${existingTask.composeProject}-app-1`;
+          let projectsHealthy = true;
+          for (const project of input.projects) {
+            const gitHealth = await dockerCli(
+              [
+                "exec",
+                "-u",
+                "node",
+                // docker exec inherits the Compose/project environment. Clear
+                // loader and Git controls before the first executable, then
+                // give Git a minimal environment of its own. Keep this aligned
+                // with task-up.sh's managed container operations.
+                "-e",
+                "HOME=/home/node",
+                "-e",
+                "PATH=/usr/bin:/bin",
+                "-e",
+                "LD_PRELOAD=",
+                "-e",
+                "LD_LIBRARY_PATH=",
+                "-e",
+                "DYLD_INSERT_LIBRARIES=",
+                "-e",
+                "DYLD_LIBRARY_PATH=",
+                "-e",
+                "BASH_ENV=",
+                "-e",
+                "ENV=",
+                "-e",
+                "GIT_CONFIG=",
+                "-e",
+                "GIT_CONFIG_GLOBAL=",
+                "-e",
+                "GIT_CONFIG_SYSTEM=",
+                "-e",
+                "GIT_CONFIG_NOSYSTEM=",
+                "-e",
+                "GIT_CONFIG_COUNT=0",
+                "-e",
+                "GIT_EXEC_PATH=",
+                "-e",
+                "GIT_SSH=",
+                "-e",
+                "GIT_SSH_COMMAND=",
+                "-e",
+                "GIT_ASKPASS=",
+                "-e",
+                "SSH_ASKPASS=",
+                "-w",
+                `/workspace/${project.slug}`,
+                appContainer,
+                "/usr/bin/env",
+                "-i",
+                "HOME=/home/node",
+                "PATH=/usr/bin:/bin",
+                "/usr/bin/git",
+                "rev-parse",
+                "--is-inside-work-tree",
+              ],
+              { timeoutMs: 10_000 },
+            );
+            // A timeout/spawn error is not proof that the repository is
+            // broken. Preserve the running task and let the caller retry once
+            // Docker can answer, just as the runtime-state probe above does.
+            if (gitHealth.status === null) {
+              return {
+                ok: false,
+                code: HostErrorCode.HostUnavailable,
+                message:
+                  `could not verify Git state for task ${input.task.id} ` +
+                  `project ${project.id}: ` +
+                  (gitHealth.stderr.trim().slice(0, 200) ||
+                    "docker did not answer"),
+                retryable: true,
+              };
+            }
+            if (
+              gitHealth.status !== 0 ||
+              gitHealth.stdout.trim() !== "true"
+            ) {
+              projectsHealthy = false;
+              console.warn(
+                `[host-agent] task ${input.task.id}: project ${project.id} Git health check failed; rebuilding the running task (${gitHealth.stderr.trim().slice(0, 200) || `git exited ${String(gitHealth.status)}`})`,
+              );
+              break;
+            }
+          }
+          if (projectsHealthy) {
+            // waitForChannelClose crossed the teardown fence above. A completed
+            // close-only teardown may have left this running task tombstoned,
+            // so the idempotent-success transition must reopen delivery just
+            // like a fresh successful taskUp does.
+            orchestrator.allowChannel(input.task.id);
+            return {
+              ok: true,
+              value: {
+                composeProject: existingTask.composeProject,
+                worktreePath: existingTask.worktreePath,
+                codeServerPort: existingTask.codeServerPort ?? undefined,
+                previewPorts: parsePreviewPortRuntimes(
+                  existingTask.previewPorts,
+                ),
+              },
+            };
+          }
         }
-        // Docker positively proved the mirrored app is absent/stopped. Drain
-        // and invalidate any stale in-memory channel before taskUp recreates
-        // the same stable compose/container names.
+        // Docker positively proved the mirrored app is absent/stopped, or the
+        // live container proved one of its project repositories is broken.
+        // Drain and invalidate any stale in-memory channel before taskUp
+        // recreates the same stable compose/container names and repairs Git.
         await orchestrator.closeChannel(input.task.id);
       }
       recordTaskStarting(input.task.id);

package/src/main.ts

@@ -82,8 +82,10 @@ import { canAdvertiseTypedSecretaryDispatch } from "../lib/agents/mode";
 import "../lib/agents/factory";
 import { ensureStandardImage, standardRuntimes } from "../lib/standard-image";
 import { hostCommands, hostEvents } from "./index";
+import { EventOutbox } from "./event-outbox";
 import {
   HostErrorCode,
+  EVENT_REPLAY_PROTOCOL_FEATURE,
   GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
   GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
   GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE,
@@ -149,6 +151,33 @@ let shutdownRequested = false;
 let pendingBinaryTunnelId: string | null = null;
 const tunnels = new TunnelRegistry();
 
+// ADR-103: event outbox. BOOT_ID scopes seqs to this process lifetime; the
+// cloud's replay watermark only applies within a matching boot. Events are
+// enqueued by a PROCESS-level subscription (below, before connect()) so a
+// dropped WSS no longer drops events — they drain on reconnect, after the
+// cloud names its watermark via event.resume.
+const BOOT_ID = newId();
+const eventOutbox = new EventOutbox();
+// Transmission is held per-connection until the cloud's event.resume sets the
+// replay cursor (or the fallback timer concedes the cloud predates ADR-103).
+let eventFlushEnabled = false;
+let resumeFallbackTimer: NodeJS.Timeout | null = null;
+const RESUME_FALLBACK_MS = 3_000;
+
+function flushEvents(): void {
+  const socket = ws;
+  if (!eventFlushEnabled || !socket || socket.readyState !== WebSocket.OPEN) {
+    return;
+  }
+  const dropped = eventOutbox.takeDroppedCount();
+  if (dropped > 0) {
+    console.warn(
+      `[host-agent] event outbox overflowed: ${dropped} unsent event(s) lost`,
+    );
+  }
+  for (const entry of eventOutbox.drain()) socket.send(entry.raw);
+}
+
 interface PausableSource {
   pause(): unknown;
   resume(): unknown;
@@ -187,6 +216,13 @@ void ensureStandardImage();
 // self-heals such containers: it re-copies and chowns every running task.
 void recoveryComplete().then(() => reinjectCodexRunningTasks());
 watchCodexAuth();
+// ADR-103: subscribe ONCE, for the process — not per connection. Every event
+// lands in the outbox regardless of socket state; flushEvents is a no-op
+// while disconnected and the backlog drains after the resume handshake.
+hostEvents.subscribe((event) => {
+  eventOutbox.enqueue(event);
+  flushEvents();
+});
 connect();
 // Local browser UI (ADR-028) — same single process, alongside the WSS client.
 // Best-effort: a UI bind failure must not take the host service down.
@@ -234,6 +270,7 @@ function buildCapabilities(): HostCapabilities {
     version: packageVersion(),
     protocolFeatures: [
       TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
+      EVENT_REPLAY_PROTOCOL_FEATURE,
       GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
       GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
       GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE,
@@ -275,19 +312,22 @@ function connect(): void {
 
   let lastTraffic = Date.now();
   let ready = false;
-  let unsubscribe: (() => void) | null = null;
   let pingTimer: NodeJS.Timeout | null = null;
   let deadTimer: NodeJS.Timeout | null = null;
 
   const cleanup = (): void => {
     if (pingTimer) clearInterval(pingTimer);
     if (deadTimer) clearInterval(deadTimer);
-    if (unsubscribe) unsubscribe();
+    eventFlushEnabled = false;
+    if (resumeFallbackTimer) {
+      clearTimeout(resumeFallbackTimer);
+      resumeFallbackTimer = null;
+    }
     if (ws === socket) ws = null;
   };
 
   socket.on("open", () => {
-    send(socket, { kind: "auth", token, hostId });
+    send(socket, { kind: "auth", token, hostId, bootId: BOOT_ID });
     // Advertise capabilities immediately after auth (ADR-021). The bridge
     // rejects with close-code 4001 if auth fails, so sending here is harmless
     // on a bad token and saves a round-trip on a good one. Re-sent on every
@@ -303,10 +343,14 @@ function connect(): void {
     setHostObsTag(hostId);
     addHostBreadcrumb("bridge", "connected");
 
-    unsubscribe = hostEvents.subscribe((event) => {
-      if (socket.readyState !== WebSocket.OPEN) return;
-      send(socket, { kind: "event", event });
-    });
+    // ADR-103: hold event transmission until the cloud names its replay
+    // watermark (event.resume). A pre-103 cloud never will — after the
+    // fallback, drain never-transmitted entries only (no replay, no dupes).
+    resumeFallbackTimer = setTimeout(() => {
+      resumeFallbackTimer = null;
+      eventFlushEnabled = true;
+      flushEvents();
+    }, RESUME_FALLBACK_MS);
 
     pingTimer = setInterval(() => {
       if (socket.readyState === WebSocket.OPEN) {
@@ -339,6 +383,20 @@ function connect(): void {
     switch (frame.kind) {
       case "pong":
         break;
+      case "event.resume":
+        // ADR-103: the cloud named its watermark — rewind the transmit
+        // cursor to it (null = no state, replay nothing) and start draining.
+        if (resumeFallbackTimer) {
+          clearTimeout(resumeFallbackTimer);
+          resumeFallbackTimer = null;
+        }
+        eventOutbox.resume(frame.afterSeq);
+        eventFlushEnabled = true;
+        flushEvents();
+        break;
+      case "event.ack":
+        eventOutbox.ack(frame.seq);
+        break;
       case "command":
         void handleCommand(socket, frame);
         break;
@@ -1227,6 +1285,15 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
   if (frame.kind === "pong" && typeof frame.ts === "number") {
     return { kind: "pong", ts: frame.ts };
   }
+  if (
+    frame.kind === "event.resume" &&
+    (frame.afterSeq === null || typeof frame.afterSeq === "number")
+  ) {
+    return { kind: "event.resume", afterSeq: frame.afterSeq };
+  }
+  if (frame.kind === "event.ack" && typeof frame.seq === "number") {
+    return { kind: "event.ack", seq: frame.seq };
+  }
   if (
     frame.kind === "command" &&
     typeof frame.commandId === "string" &&

package/src/protocol.ts

@@ -41,6 +41,11 @@ export const GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE =
   "github-repository-access-v1";
 export const GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE =
   "github-credential-generation-v1";
+// ADR-103: the host runs an event outbox — seq'd event frames, resume
+// handshake on reconnect, cumulative acks. A cloud seeing this feature knows
+// a disconnect no longer loses events (they replay), so it keeps its
+// in-flight turn buffers across the gap.
+export const EVENT_REPLAY_PROTOCOL_FEATURE = "event-replay-v1";
 export const COMMUNICATOR_EXECUTION_PROFILE = "communicator";
 export const MAX_AGENT_ID_CHARS = 128;
 export const MAX_SECRETARY_DISPATCH_RECIPIENTS = 16;
@@ -603,7 +608,15 @@ export type CloudToHost =
   // discovery, DCR, PKCE, token exchange, encrypted storage. Secrets in a
   // probe (headerValue, clientSecret) are write-only; nothing secret ever
   // rides an ack. `opId` correlates request↔ack.
-  | { kind: "mcp.op"; opId: string; op: McpOp };
+  | { kind: "mcp.op"; opId: string; op: McpOp }
+  // ADR-103: sent once right after auth to a host that supplied a bootId.
+  // `afterSeq` is the cloud's replay watermark for this boot: the host
+  // replays every outbox entry with seq > afterSeq. `null` means the cloud
+  // has no watermark for this boot (fresh boot, or lost KV) — the host sends
+  // only entries it never transmitted, replaying nothing.
+  | { kind: "event.resume"; afterSeq: number | null }
+  // ADR-103: cumulative — the host trims outbox entries with seq <= seq.
+  | { kind: "event.ack"; seq: number };
 
 /** One MCP-connection operation (ADR-057), executed by the host. */
 export type McpOp =
@@ -632,14 +645,19 @@ export type McpOp =
   | { kind: "disconnect"; connectionId: string };
 
 export type HostToCloud =
-  | { kind: "auth"; token: string; hostId: string }
+  // ADR-103: `bootId` scopes event seqs to one host process lifetime — the
+  // cloud's replay watermark only applies within a matching boot. Optional
+  // for pre-103 hosts (which also never send seq'd events).
+  | { kind: "auth"; token: string; hostId: string; bootId?: string }
   | { kind: "host.capabilities"; capabilities: HostCapabilities }
   | {
       kind: "result";
       commandId: string;
       result: HostCommandResult<unknown>;
     }
-  | { kind: "event"; event: HostEvent }
+  // ADR-103: `seq` is the outbox sequence number (monotonic within a bootId).
+  // Absent from pre-103 hosts; the cloud dedups replay overlap by it.
+  | { kind: "event"; event: HostEvent; seq?: number }
   // Host-pushed task lifecycle (ADR-028 local-UI Stop): the host operator paused
   // a task's containers, so the cloud mirrors the status (currently "stopped").
   | { kind: "task.status"; taskId: string; status: string }