local-operator-ui 0.29.12 → 0.30.1

package/out/main/index.js

@@ -4240,23 +4240,31 @@ function resolveGlobalInstallPlan(input) {
        * Managed - what the app is about to do TO THEM. This arm used to tell the
        * user to go to a terminal on the one path where the app runs the command
        * itself, which no surface rendered (reviews D7, U7), and the offer named
-       * no cost at all before the click (review U3). The restart is the one
-       * destructive thing this path does, so it is stated here rather than in
-       * the in-flight panel the user reaches only after pressing.
+       * no cost at all before the click (review U3). It named the restart as its
+       * cost for the same reason - it was the one destructive thing this path
+       * did. It no longer is: on the generation layout the install lands beside
+       * the running build and the server keeps serving the build it loaded until
+       * its own next idle, so the cost is the install and the wait, and no
+       * sentence here may describe a turn being dropped.
        *
        * Source build - the same disclosure with the one difference that matters:
-       * what is rebuilt is THEIR checkout, and the version they end up on is the
-       * checkout's rather than the release the app offered.
+       * this route DOES rewrite a tree a live runtime is reading, so its sentence
+       * keeps saying so. What it adds is the half it was silent about: the app
+       * now waits for the fleet to drain before it starts
+       * (`drainFleetForUpdate`), which is the operator's own rule - nothing may
+       * kill runtimes en masse - applied to the one route that can.
        *
        * Legacy - WHY the app will not press the button, which is what the user
        * is choosing between (reviews U8, N1). It lived only in the mono Details
-       * line, trailing a resolved path and a classification.
+       * line, trailing a resolved path and a classification. Its warning is
+       * about the OLD INSTALLER the reader would run themselves, not about
+       * anything this app does, which is why it still says a turn can be lost.
        *
        * NEITHER ENDS IN A COLON: the well below is visually distinct in both
        * panels, and in the by-hand panel the next line was the version sentence,
        * so the promise landed on the wrong line (review D5).
        */
-      remedy: managed ? "The app updates this install and then restarts the server it started, so a turn that is in flight is dropped while the server comes back. This can take a minute or two." : sourceRebuildRoute ? "Rebuilds this checkout with `lop-update`. The rebuild happens in place, so sessions on this machine can be interrupted while it runs, and it can take up to half an hour. This install keeps reporting the checkout's version, not the release the app offered." : "This install predates the non-disruptive installer, so update it once from your terminal. This install's updater rewrites the shared environment in place, which can interrupt sessions mid-turn; the app manages updates after that.",
+      remedy: managed ? "The app installs the new build beside the one in use and leaves the server you are using on the build it loaded, so nothing in flight is cut off. The server moves onto the new build when it is next idle." : sourceRebuildRoute ? "Rebuilds this checkout with `lop-update`. The app waits for the turns running on this machine to finish first, and the rebuild then reinstalls this install in place - so a turn started while it runs can still be interrupted - and it can take up to half an hour. This install keeps reporting the checkout's version, not the release the app offered." : "This install predates the non-disruptive installer, so update it once from your terminal; that updater rewrites the shared environment in place, which can interrupt sessions mid-turn. The app manages updates after that.",
       detail: `${detail}${managed ? provenance : sourceRebuildRoute ? " source build of this machine's checkout; an in-place rebuild." : provenance}`,
       sourceBuild,
       managedRoute: managed ? "entry-point" : sourceRebuildRoute ? "source-build" : null,
@@ -4402,14 +4410,35 @@ function driftInstallReading(input) {
     return { version: input.planVersion, source: "unknown" };
   return { version: input.planVersion, source: "serving-install" };
 }
-function servingWorkStateFromSessions(body) {
+const DEGRADED_LIVENESS_SOURCE = "liveness";
+function rosterLivenessDegraded(body) {
+  const degraded = body?.result?.degraded;
+  return Array.isArray(degraded) && degraded.includes(DEGRADED_LIVENESS_SOURCE);
+}
+const KNOWN_LIVE_STATES = /* @__PURE__ */ new Set(["", "wedged", "busy", "attached", "idle"]);
+function fleetRosterFromSessions(body) {
   const sessions = body?.result?.sessions;
-  if (!Array.isArray(sessions)) return "unknown";
-  const rows = sessions.filter(
+  if (!Array.isArray(sessions)) return null;
+  if (rosterLivenessDegraded(body)) return null;
+  return sessions.filter(
     (row) => typeof row === "object" && row !== null
-  );
-  if (rows.some((row) => row.live_state === "busy")) return "busy";
-  if (rows.length > 0 && rows.every((row) => !("live_state" in row)))
+  ).map((row) => ({
+    sessionId: typeof row.id === "string" ? row.id : "",
+    name: typeof row.name === "string" ? row.name : "",
+    kind: typeof row.kind === "string" ? row.kind : "",
+    liveState: typeof row.live_state === "string" ? row.live_state : null
+  }));
+}
+function busyRosterRows(rows) {
+  return rows.filter((row) => row.liveState === "busy");
+}
+function servingWorkStateFromSessions(body) {
+  const rows = fleetRosterFromSessions(body);
+  if (rows === null) return "unknown";
+  if (busyRosterRows(rows).length > 0) return "busy";
+  if (rows.some(
+    (row) => row.liveState === null || !KNOWN_LIVE_STATES.has(row.liveState)
+  ))
     return "unknown";
   return "idle";
 }
@@ -6199,7 +6228,7 @@ async function prepareRuntime(options) {
   await promises.rename(staging, runtime);
   return { runtime, id: id2 };
 }
-function describe$1(error) {
+function describe$2(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function selectionIsWellFormed(root, selection) {
@@ -6251,7 +6280,7 @@ function inspectManagedSelection(options) {
       realDirectory(path2);
     } catch (error) {
       return missing(
-        `The selected ${what} is not there any more (${path2}): ${describe$1(error)}`
+        `The selected ${what} is not there any more (${path2}): ${describe$2(error)}`
       );
     }
   }
@@ -6265,7 +6294,7 @@ function inspectManagedSelection(options) {
       );
   } catch (error) {
     return missing(
-      `The selected environment is not complete (${selection.venv}): ${describe$1(error)}`
+      `The selected environment is not complete (${selection.venv}): ${describe$2(error)}`
     );
   }
   if (!fs.existsSync(path$1.join(selection.venv, "bin", "local-operator")))
@@ -6279,7 +6308,7 @@ function inspectManagedSelection(options) {
     )?.[1]?.trim();
   } catch (error) {
     return missing(
-      `The selected environment has no readable pyvenv.cfg (${selection.venv}): ${describe$1(error)}`
+      `The selected environment has no readable pyvenv.cfg (${selection.venv}): ${describe$2(error)}`
     );
   }
   if (home !== path$1.join(selection.runtime, "bin"))
@@ -6291,7 +6320,7 @@ function inspectManagedSelection(options) {
     identity = runtimeIdentity(selection.runtime, options.arch);
   } catch (error) {
     return missing(
-      `The selected Python runtime could not be read (${selection.runtime}): ${describe$1(error)}`
+      `The selected Python runtime could not be read (${selection.runtime}): ${describe$2(error)}`
     );
   }
   if (identity !== selection.runtimeId) {
@@ -6679,7 +6708,7 @@ class ProbeTimeout extends Error {
     this.name = "ProbeTimeout";
   }
 }
-const describe = (error) => error instanceof Error ? error.message : String(error);
+const describe$1 = (error) => error instanceof Error ? error.message : String(error);
 function runBounded(command, args, env, bounds) {
   return new Promise((resolve, reject) => {
     const child = node_child_process.spawn(command, args, {
@@ -6857,7 +6886,7 @@ async function ownedServeLaunch(interpreters, port, env, platform = process.plat
           bounds
         );
       } catch (error) {
-        rejected.push(`${interpreter}: ${describe(error)}`);
+        rejected.push(`${interpreter}: ${describe$1(error)}`);
       }
     }
     return null;
@@ -7324,6 +7353,18 @@ class BackendServiceManager {
   // Flag to track when the app is being closed
   isAutoUpdating = false;
   // Flag to track when an autoupdate is in progress
+  /**
+   * WHY the fleet roster last came back unreadable, when the server answered.
+   *
+   * A dead socket and a 401 look the same to `servingWorkState` - both are not
+   * evidence about work, so both are `unknown` and both hold a restart - but they
+   * are different next steps for a READER, and the update path's refusal says
+   * which happened (QA round 1, observation b). The transport is the only party
+   * that knows, so it records the answer here and the refusal reads it back;
+   * guessing it from the verdict is how the two would come to disagree. Reset on
+   * every read, so it always describes the most recent one.
+   */
+  fleetReadFailure = "unreachable";
   shutdownTimeoutMs = { ...SHUTDOWN_TIMEOUT_DEFAULTS };
   // Configurable timeouts for different shutdown scenarios
   /**
@@ -9150,6 +9191,10 @@ class BackendServiceManager {
    * A transport that does not answer, and a non-200, are both `unknown` - which
    * the decision treats as a reason to WAIT. A read that could not be taken is
    * not evidence that the machine is quiet.
+   *
+   * A LISTING whose own liveness read failed is `unknown` for the same reason and
+   * by the same route: `fleetRosterFromSessions` declines a degraded roster and
+   * answers null, which this reduces to `unknown` (review round 1, B1 = QA Q-1).
    */
   async servingWorkState() {
     try {
@@ -9159,12 +9204,63 @@ class BackendServiceManager {
         // first page is still work in flight, so the read asks for the lot.
         limit: 500
       });
+      this.noteFleetReadAnswer(response.status);
       if (response.status !== 200) return "unknown";
       return servingWorkStateFromSessions(response.body);
     } catch {
+      this.fleetReadFailure = "unreachable";
       return "unknown";
     }
   }
+  /**
+   * Record what a `sessions.list` answer says about the app's own access.
+   *
+   * 401/403 is the one non-200 that is about the CREDENTIAL rather than about the
+   * fleet: the server is up and answering, and it is refusing this app's token.
+   * Everything else - another status, or no answer at all - is `unreachable`,
+   * which is the arm whose remedy (try again once the server answers) is true.
+   */
+  noteFleetReadAnswer(status2) {
+    this.fleetReadFailure = status2 === 401 || status2 === 403 ? "refused-credentials" : "unreachable";
+  }
+  /**
+   * Why the last fleet read could not be taken: `servingWorkState`'s own reason.
+   *
+   * Read by the update path only when a refusal is being composed, and only on
+   * the `unknown` arm - see `FleetDrainOutcome.credentialsRefused`.
+   */
+  fleetReadFailureReason() {
+    return this.fleetReadFailure;
+  }
+  /**
+   * The session roster itself: the same read as `servingWorkState`, with the
+   * rows kept rather than reduced to one verdict.
+   *
+   * The update path's fleet gate needs the rows for two jobs a verdict cannot
+   * do: naming the sessions it waited for in a refusal, and taking the before
+   * and after snapshots that tell it which runtimes a restart displaced
+   * (`backend/fleet-drain.ts`). Both callers read ONE route, and the row shape
+   * and the busy spelling come from the same module, so there is no second
+   * reading of what "busy" means.
+   *
+   * Null rather than an empty array when the route did not answer: an empty
+   * roster is a machine with no sessions, which is a different fact from a read
+   * that could not be taken.
+   */
+  async servingSessionFleet() {
+    try {
+      const response = await this.requestDesktop({
+        op: "sessions.list",
+        limit: 500
+      });
+      this.noteFleetReadAnswer(response.status);
+      if (response.status !== 200) return null;
+      return fleetRosterFromSessions(response.body);
+    } catch {
+      this.fleetReadFailure = "unreachable";
+      return null;
+    }
+  }
   /**
    * The address this app is talking to RIGHT NOW.
    *
@@ -10219,7 +10315,17 @@ const METHODS$1 = [
   "owner_finish",
   "owner_retain",
   "owner_release",
-  ...CONSOLE_METHODS
+  ...CONSOLE_METHODS,
+  // File transfer, appended in the Python source's order so the two lists stay
+  // comparable by eye (design §6.1, §6.5). Both halves are NOT symmetric on the
+  // extension, and the reason is a measurement rather than a preference — see
+  // `EXTENSION_CANNOT_SERVE` in `browser_bridge/protocol.py`: no extension build
+  // can serve `download`, because Chrome refuses an extension every CDP primitive
+  // that could put a file where the harness chose (measured 2026-09-18, Chrome
+  // 153), while `upload` rides `DOM.setFileInputFiles` on the session it already
+  // holds. THIS host serves both.
+  "download",
+  "upload"
 ];
 const METHOD_SET = new Set(METHODS$1);
 function isMethod(value) {
@@ -10243,6 +10349,15 @@ const ERROR_CODES = [
   "proto_mismatch",
   "owner_refused",
   "extension_unresponsive",
+  // Present for MIRROR PARITY with `protocol.py`'s `ErrorCode`, and emitted by the
+  // DAEMON, never by this host (§6.2). It has to be in this list for the reason
+  // `rpc.ts` narrows an unknown code to `internal`: an already-released session
+  // validates `ErrorDetail.code` against the Python enum, so a frame carrying a
+  // code it does not know is DROPPED — which is worse than a wrong answer, because
+  // the caller waits out its whole budget. The daemon is on the safe side of that
+  // direction (daemon -> session), a browser host is not, which is exactly why a
+  // policy refusal travels as an `ok: true` result here.
+  "capability_unsupported",
   "internal",
   // The console namespace's own additions (design 10.6). Spread rather than copied
   // for the same reason METHODS is: this list is what `rpc.ts` narrows a raised
@@ -10250,6 +10365,7 @@ const ERROR_CODES = [
   // a command that hangs rather than one that fails.
   ...CONSOLE_ERROR_CODES
 ];
+const HOST_CAPABILITIES = ["download", "upload"];
 const RUN_DIRNAME = path$1.join("run", "ui-browser");
 const STATE_FILENAME = "host.json";
 const STATE_DIR_MODE = 448;
@@ -10319,6 +10435,10 @@ class BrowserStateWriter {
         host: "ui",
         app_version: this.appVersion,
         profile_dir: facts.profileDir,
+        // Advertised from the ONE list the `/health` route also reads (§6.3), so the
+        // record a session reads and the probe Python acquits a stale record with
+        // cannot name different capabilities.
+        capabilities: [...HOST_CAPABILITIES],
         tabs: facts.tabs,
         agent_tabs: facts.agentTabs,
         console: facts.console ?? false,
@@ -10651,7 +10771,7 @@ const FIXED = /* @__PURE__ */ new Map([
   ["f11", "\x1B[23~"],
   ["f12", "\x1B[24~"]
 ]);
-const CONTROL = /* @__PURE__ */ new Map([
+const CONTROL$1 = /* @__PURE__ */ new Map([
   ["ctrl+space", 0],
   ["ctrl+[", 27],
   ["ctrl+\\", 28],
@@ -10660,7 +10780,7 @@ const CONTROL = /* @__PURE__ */ new Map([
   ["ctrl+_", 31]
 ]);
 for (const letter of "abcdefghijklmnopqrstuvwxyz") {
-  CONTROL.set(`ctrl+${letter}`, letter.charCodeAt(0) - 96);
+  CONTROL$1.set(`ctrl+${letter}`, letter.charCodeAt(0) - 96);
 }
 const CURSOR = /* @__PURE__ */ new Map([
   ["up", { normal: "\x1B[A", application: "\x1BOA" }],
@@ -10675,7 +10795,7 @@ const encodeText = (text) => ENCODER$1.encode(text);
 function encodeNamedKey(name, modes) {
   const fixed = FIXED.get(name);
   if (fixed !== void 0) return encodeText(fixed);
-  const control = CONTROL.get(name);
+  const control = CONTROL$1.get(name);
   if (control !== void 0) return Uint8Array.from([control]);
   const cursor = CURSOR.get(name);
   if (cursor !== void 0) {
@@ -12646,6 +12766,7 @@ const PTY_PACKAGE = "node-pty";
 const SPAWN_HELPER_NAME = "spawn-helper";
 const SPAWN_HELPER_MODE = 493;
 const OWNER_EXECUTE = 64;
+const NATIVE_MODULE_NAME = "pty.node";
 const ASAR_APP = /([/\\])app\.asar([/\\])/;
 const ASAR_NODE_MODULES = /([/\\])node_modules\.asar([/\\])/;
 function unpackedPath(path2) {
@@ -12654,8 +12775,18 @@ function unpackedPath(path2) {
 function prebuildDir(root, target2) {
   return path$1.join(root, "prebuilds", `${target2.platform}-${target2.arch}`);
 }
-function spawnHelperPath(root, target2) {
-  return path$1.join(prebuildDir(root, target2), SPAWN_HELPER_NAME);
+function forksSpawnHelper(platform) {
+  return platform === "darwin";
+}
+function nativeDirs(root, target2) {
+  return [
+    path$1.join(root, "build", "Release"),
+    path$1.join(root, "build", "Debug"),
+    prebuildDir(root, target2)
+  ];
+}
+function spawnHelperPaths(root, target2) {
+  return nativeDirs(root, target2).map((dir) => path$1.join(dir, SPAWN_HELPER_NAME));
 }
 function resolvePtyRoot() {
   const requireFrom = node_module.createRequire(
@@ -12666,26 +12797,50 @@ function resolvePtyRoot() {
   );
 }
 function ensureSpawnHelperExecutable(root, target2) {
-  const path2 = spawnHelperPath(root, target2);
+  const required = forksSpawnHelper(target2.platform);
   try {
-    if (!fs.existsSync(path2)) {
-      return { path: null, mode: null, healed: false, reason: "no helper" };
-    }
-    const mode = fs.statSync(path2).mode & 511;
-    if ((mode & OWNER_EXECUTE) !== 0) {
-      return { path: path2, mode, healed: false };
+    const helpers = spawnHelperPaths(root, target2).filter((path2) => fs.existsSync(path2)).map((path2) => {
+      const mode = fs.statSync(path2).mode & 511;
+      if ((mode & OWNER_EXECUTE) !== 0) return { path: path2, mode, healed: false };
+      fs.chmodSync(path2, SPAWN_HELPER_MODE);
+      return { path: path2, mode, healed: true };
+    });
+    if (helpers.length === 0) {
+      return {
+        path: null,
+        mode: null,
+        healed: false,
+        required,
+        helpers,
+        reason: required ? "no helper" : `no helper, and ${target2.platform}-${target2.arch} forks none`
+      };
     }
-    fs.chmodSync(path2, SPAWN_HELPER_MODE);
-    return { path: path2, mode, healed: true };
+    const loaded = nativeDirs(root, target2).find(
+      (dir) => fs.existsSync(path$1.join(dir, NATIVE_MODULE_NAME))
+    );
+    const primary = helpers.find((helper) => path$1.dirname(helper.path) === loaded) ?? helpers[0];
+    return {
+      path: primary.path,
+      mode: primary.mode,
+      healed: helpers.some((helper) => helper.healed),
+      required,
+      helpers
+    };
   } catch (error) {
     return {
-      path: path2,
+      path: null,
       mode: null,
       healed: false,
+      required,
+      helpers: [],
       reason: error instanceof Error ? error.message : String(error)
     };
   }
 }
+function helperStatus(report) {
+  if (report.path !== null) return "ready";
+  return report.required ? "without a helper" : "no helper needed on this platform";
+}
 let cached = null;
 function loadNodePty() {
   if (cached) return cached;
@@ -12841,7 +12996,7 @@ async function startConsoleHost(options) {
     log
   });
   log(
-    `[console] host ready on the existing endpoint: ${registry.count()} surface(s) (node-pty ${load.helper.mode === null ? "without a helper" : "ready"})`
+    `[console] host ready on the existing endpoint: ${registry.count()} surface(s) (node-pty ${helperStatus(load.helper)})`
   );
   return {
     ok: true,
@@ -13309,31 +13464,6 @@ function readJson(path2) {
 function errorData(error) {
   return error instanceof BridgeCommandError ? error.data : {};
 }
-const CDP_DEADLINE_MS = 15e3;
-const CDP_ATTACH_DEADLINE_MS = 5e3;
-const CHROME_API_DEADLINE_MS = 5e3;
-const SCRIPTING_DEADLINE_MS = 15e3;
-function deadline(op, ms, what) {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(
-        new BridgeCommandError("internal", `${what} did not respond within ${ms}ms`, {
-          stalled: what
-        })
-      );
-    }, ms);
-    op.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (error) => {
-        clearTimeout(timer);
-        reject(error);
-      }
-    );
-  });
-}
 function nextSequence(queue) {
   return (queue ?? []).reduce(
     (highest, entry) => Math.max(highest, entry.sequence),
@@ -13351,7 +13481,7 @@ const SCROLL_DIRECTIONS = /* @__PURE__ */ new Set([
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-const WEB_CONTENTS_DEADLINE_MS = CHROME_API_DEADLINE_MS;
+const WEB_CONTENTS_DEADLINE_MS = 15e3;
 const ONCE_GRANT_TTL_MS = 10 * 6e4;
 function receiptKey(origin, requester) {
   return `${origin}
@@ -14342,6 +14472,30 @@ function routeDebuggerEvent(webContentsId, method, rawParams) {
     });
   }
 }
+const CDP_DEADLINE_MS = 15e3;
+const CDP_ATTACH_DEADLINE_MS = 5e3;
+const SCRIPTING_DEADLINE_MS = 15e3;
+function deadline(op, ms, what) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new BridgeCommandError("internal", `${what} did not respond within ${ms}ms`, {
+          stalled: what
+        })
+      );
+    }, ms);
+    op.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
 const PROTOCOL_VERSION = "1.3";
 const ALREADY_ATTACHED = /another debugger|already attached/i;
 class CdpPool {
@@ -14623,6 +14777,743 @@ class ConsentNotifier {
     }
   }
 }
+const DENY_EXTS = ["apk", "app", "bash", "bat", "cmd", "com", "command", "cpl", "crx", "dex", "dll", "dmg", "drv", "exe", "hta", "jar", "lnk", "msi", "msp", "mst", "ocx", "pkg", "ps1", "psm1", "reg", "scpt", "scr", "sh", "sys", "url", "vbe", "vbs", "wasm", "wsf", "zsh"];
+const CREDENTIAL_NAME_PATTERNS = ["id_rsa*", "id_ed25519*", "id_ecdsa*", "id_dsa*", "*.pem", "*.key", "*.p12", "*.pfx", "*.jks", "*.keystore", ".netrc", "_netrc", ".git-credentials", ".npmrc", ".pypirc", ".pgpass", ".my.cnf", ".dockercfg", ".env", ".env.*", "credentials", "credentials.json", "service-account*.json", "*.keychain", "*.keychain-db"];
+const CAPS = {
+  "downloadMaxBytes": 268435456,
+  "downloadMaxFilesPerCall": 20,
+  "downloadTimeoutS": 120,
+  "downloadTimeoutMaxS": 600,
+  "uploadMaxFiles": 10
+};
+const MAX_NAME_BYTES = 200;
+const FALLBACK_STEM = "download";
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
+const BIDI_ZERO_WIDTH = /[\u200b-\u200f\u202a-\u202e\u2066-\u2069]/g;
+const WINDOWS_RESERVED_STEMS = /* @__PURE__ */ new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  "com1",
+  "com2",
+  "com3",
+  "com4",
+  "com5",
+  "com6",
+  "com7",
+  "com8",
+  "com9",
+  "lpt1",
+  "lpt2",
+  "lpt3",
+  "lpt4",
+  "lpt5",
+  "lpt6",
+  "lpt7",
+  "lpt8",
+  "lpt9"
+]);
+function bytesOf(text) {
+  return new TextEncoder().encode(text).length;
+}
+function fallbackDigest(text) {
+  let hash = 2166136261;
+  for (const byte of new TextEncoder().encode(text)) {
+    hash = Math.imul(hash ^ byte, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+function truncateBytes(name, limit) {
+  let head = name;
+  let ext = "";
+  const dot = name.lastIndexOf(".");
+  if (dot > 0 && name.length - dot - 1 <= 12) {
+    head = name.slice(0, dot);
+    ext = name.slice(dot + 1);
+  }
+  const budget = limit - (ext ? bytesOf(ext) + 1 : 0);
+  if (budget <= 0) return "";
+  while (bytesOf(head) > budget && head.length > 0) {
+    head = head.slice(0, -1);
+    if (/[\ud800-\udbff]$/.test(head)) head = head.slice(0, -1);
+  }
+  return ext ? `${head}.${ext}` : head;
+}
+function fallbackName(raw, sniffedExt = "") {
+  const stem = `${FALLBACK_STEM}-${fallbackDigest(raw)}`;
+  return sniffedExt ? `${stem}.${sniffedExt}` : stem;
+}
+function safeName(raw, sniffedExt = "") {
+  const parts = raw.replace(/\\/g, "/").split("/");
+  let name = (parts[parts.length - 1] ?? "").replace(CONTROL, "").replace(BIDI_ZERO_WIDTH, "");
+  name = name.normalize("NFC").trim().replace(/[. ]+$/, "");
+  if (name === "" || name === "." || name === "..") return fallbackName(raw, sniffedExt);
+  const dot = name.lastIndexOf(".");
+  const stem = dot > 0 ? name.slice(0, dot) : name;
+  let ext = dot > 0 ? name.slice(dot + 1) : "";
+  if (WINDOWS_RESERVED_STEMS.has(stem.toLowerCase())) return fallbackName(raw, sniffedExt);
+  if (sniffedExt && ext.toLowerCase() !== sniffedExt.toLowerCase()) {
+    ext = sniffedExt;
+  }
+  return truncateBytes(ext ? `${stem}.${ext}` : stem, MAX_NAME_BYTES);
+}
+function extensionOf(raw) {
+  const name = safeName(raw).toLowerCase();
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return "";
+  const ext = name.slice(dot + 1);
+  return ext.length > 12 || ext.includes("/") ? "" : ext;
+}
+function executableName(raw) {
+  const ext = extensionOf(raw);
+  return ext !== "" && DENY_EXTS.includes(ext);
+}
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`);
+}
+CREDENTIAL_NAME_PATTERNS.map((pattern) => ({
+  pattern,
+  regex: globToRegExp(pattern)
+}));
+const QUIET_MS = 1500;
+const NOTES_KEPT = 4;
+const PROGRESS_RENDER_MS = 250;
+const CAP_SAMPLE_MS = 100;
+class DownloadArmer {
+  constructor(options) {
+    this.options = options;
+  }
+  captures = /* @__PURE__ */ new Map();
+  notes = [];
+  /** The newest file SAVED into the download directory, and how many have been saved
+   * in this app run, for the durable control's own label (review round 2, U12).
+   *
+   * WHY IT IS NOT DERIVED FROM `notes`: the notes are a bounded NOTIFICATION window
+   * (`NOTES_KEPT` = 4), so a save four decisions ago is gone from them — and the
+   * first draft of this field read the notes, which meant the summary VANISHED
+   * exactly when the user most needed it (a refusal, a refusal, a refusal, and the
+   * trace of the file that did arrive is gone). It is one string and a count, kept
+   * for the life of the process, which is what makes "this session" a true word in
+   * the control's label rather than a bound dressed up as a total. */
+  savedSummary = null;
+  /** The paths this host has PROMISED Chromium, keyed by the DIRECTORY they are
+   * in (review round 2, R2-4).
+   *
+   * WHY IT IS NOT ON THE CAPTURE ANY MORE. A reservation held per capture answers
+   * only the question that capture asked: two same-named downloads on two armed
+   * CALLS into one directory are still decided by the `existsSync` probe alone,
+   * because Chromium creates the file after `setSavePath` returns — so the second
+   * call cannot see the first's path. The directory is what a name can collide in,
+   * so the directory is the key. And a reservation is RELEASED when the write it
+   * was for settles — it either exists on disk (the probe sees it) or was
+   * discarded (the name is free) — rather than consuming its suffix for the rest
+   * of the call, which is how the next download of that name landed as
+   * `name (1).ext` with nothing on disk (review round 2, R2-4). */
+  reserved = /* @__PURE__ */ new Map();
+  /** The owner kind of one tab, or null when this armer cannot say (review round
+   * 2, U10: the kind travels with the decision because the tab may be closed by
+   * the time the row renders it). */
+  ownerKindOf(tabId) {
+    return this.options.ownerKindFor?.(tabId) ?? null;
+  }
+  /** Arm one tab. `dir` is the harness-composed directory (§10.2); it is created
+   * 0700 if missing, because the harness composes it and a race with a session's
+   * own cleanup must not cost the user the file.
+   *
+   * TWO RULES ABOUT THAT DIRECTORY (review round 1, M3), and both exist because
+   * this is the last place between a wire parameter and a `chmod`. ABSOLUTE: a
+   * relative `dir` resolves against the APP's working directory rather than the
+   * session's, which is the shape `upload` already refuses for its own paths. And
+   * the MODE IS ASSERTED ONLY ON A DIRECTORY THIS CALL CREATED: re-moding an
+   * existing path the harness composed — or a symlink to one — would be a chmod on
+   * something this host does not own.
+   */
+  arm(tabId, dir, timeoutMs) {
+    if (!path$1.isAbsolute(dir)) {
+      throw new BridgeCommandError(
+        "internal",
+        "download needs an absolute directory to write into",
+        { param: "dir" }
+      );
+    }
+    this.forget(tabId);
+    const created = !fs.existsSync(dir);
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 448 });
+      if (created) fs.chmodSync(dir, 448);
+    } catch (error) {
+      throw new BridgeCommandError(
+        "internal",
+        `download needs a directory it can write into: ${describe(error)}`,
+        { param: "dir" }
+      );
+    }
+    const now = this.options.now ?? Date.now;
+    const capture = {
+      tabId,
+      dir,
+      timeoutMs,
+      startedAt: now(),
+      files: [],
+      refusals: [],
+      pending: 0,
+      started: false,
+      live: [],
+      handedOut: /* @__PURE__ */ new Set(),
+      active: null,
+      lastProgressAt: 0,
+      quietTimer: null,
+      deadlineTimer: null,
+      capTimer: null,
+      finish: null,
+      settled: false
+    };
+    this.captures.set(tabId, capture);
+    const deadline2 = setTimeout(() => this.settle(capture), timeoutMs);
+    deadline2.unref?.();
+    capture.deadlineTimer = deadline2;
+    const capSample = setInterval(
+      () => this.sampleCaps(capture),
+      CAP_SAMPLE_MS
+    );
+    capSample.unref?.();
+    capture.capTimer = capSample;
+    this.options.log(
+      `[browser] armed downloads on tab ${tabId} into ${dir} for ${Math.round(timeoutMs / 1e3)}s`
+    );
+    this.options.onActivity?.();
+    return {
+      done: () => new Promise((resolve) => {
+        const answer = () => {
+          capture.settled = true;
+          resolve(this.resultOf(capture));
+        };
+        if (capture.settled) answer();
+        else capture.finish = answer;
+      })
+    };
+  }
+  /** Drop one tab's arm and stop tracking it. Called from the action's `finally`
+   * and from the single tab-removal path, so a closed tab cannot leave a live
+   * capture behind. */
+  forget(tabId) {
+    const capture = this.captures.get(tabId);
+    if (!capture) return;
+    this.captures.delete(tabId);
+    this.clearTimers(capture);
+    this.cancelLive(
+      capture,
+      "was still being written when the download call ended",
+      { rule: "interrupted", bytes: 0, limit: 0 }
+    );
+    for (const path2 of capture.handedOut) this.release(capture, path2);
+    if (!capture.settled) {
+      capture.settled = true;
+      capture.finish?.();
+    }
+  }
+  /**
+   * Decide one download attempt. THE ONLY ENTRY POINT `profile.ts` calls.
+   *
+   * The order is deliberate and is the design's: the NAME first (cheapest, and
+   * the only check that can refuse a `.url`/`.reg`/`.command`, whose bytes are
+   * plain text), then the CAP before the write, then the save path.
+   */
+  decide(item, webContentsId) {
+    const tabId = this.options.tabForWebContents(webContentsId);
+    const capture = tabId === null ? void 0 : this.captures.get(tabId);
+    if (!capture || capture.settled) {
+      return { cancel: true, reason: "no download call is armed on this tab" };
+    }
+    const raw = item.getFilename();
+    const clean = safeName(raw);
+    if (executableName(raw)) {
+      return this.refuse(
+        capture,
+        clean,
+        `refused: \`${clean}\` is an executable/script type; nothing was saved`,
+        { rule: "executable", bytes: item.getTotalBytes(), limit: 0 }
+      );
+    }
+    if (capture.files.length + capture.pending >= CAPS.downloadMaxFilesPerCall) {
+      return this.refuse(
+        capture,
+        clean,
+        // The row shows this verbatim, so it is written for a person who just
+        // clicked something rather than in tool-call jargon (review round 1, D1):
+        // "call" and "landed" described the MODEL's call, and a user reading the
+        // strip made neither.
+        `refused: this download call has already saved its limit of ${CAPS.downloadMaxFilesPerCall} files; nothing was saved`,
+        {
+          rule: "count",
+          bytes: 0,
+          limit: CAPS.downloadMaxFilesPerCall
+        }
+      );
+    }
+    const total = item.getTotalBytes();
+    if (total > CAPS.downloadMaxBytes) {
+      return this.refuse(
+        capture,
+        clean,
+        `refused: \`${clean}\` is over the ${humanBytes(CAPS.downloadMaxBytes)} per-file download limit; nothing was saved (it is ${total} bytes)`,
+        { rule: "limit", bytes: total, limit: CAPS.downloadMaxBytes }
+      );
+    }
+    const savePath = this.uniquePath(capture, clean, raw);
+    try {
+      item.setSavePath(savePath);
+    } catch (error) {
+      return this.refuse(
+        capture,
+        clean,
+        `refused: \`${clean}\` could not be saved — the download folder could not be written to (${describe(error)}); nothing was saved`,
+        { rule: "write", bytes: item.getTotalBytes(), limit: 0 }
+      );
+    }
+    this.track(item, capture, savePath);
+    this.reserve(capture, savePath);
+    return { cancel: false, reason: "" };
+  }
+  /** Promise one path, in this capture's own list and in the directory's index. */
+  reserve(capture, savePath) {
+    capture.handedOut.add(savePath);
+    const held = this.reserved.get(capture.dir);
+    if (held) held.add(savePath);
+    else this.reserved.set(capture.dir, /* @__PURE__ */ new Set([savePath]));
+  }
+  /** Give a reserved name back, because the write it was for has settled (review
+   * round 2, R2-4): the file is on disk, so the probe sees it, or it was
+   * discarded, so the name is free again.
+   *
+   * The capture's OWN list is what decides whether this host ever promised the
+   * path, so a `done` event arriving after the arm was forgotten — the capture
+   * object is still reachable through the listener closure even though the map
+   * entry is gone — cannot release something a different capture reserved. */
+  release(capture, savePath) {
+    if (!capture.handedOut.delete(savePath)) return;
+    const held = this.reserved.get(capture.dir);
+    if (!held) return;
+    held.delete(savePath);
+    if (held.size === 0) this.reserved.delete(capture.dir);
+  }
+  /** What the chrome row renders for ONE tab (§16.4).
+   *
+   * WHY PER TAB (review round 1, D2): `captures` and `notes` are host-wide, and
+   * the row rendered both into EVERY browser tab's chrome — so the strip of the
+   * tab the user is watching could narrate a decision taken in another one, and
+   * did exactly that in the published frames (`04` showed a refusal above a form
+   * holding three attached files). The active tab is the row's subject.
+   *
+   * `null` is "no tab is active", which renders nothing: the strip belongs to a
+   * tab, and there is no tab to speak for.
+   *
+   * WHY THE NOTES ARE HOST-WIDE AND THE TAB IS NAMED INSTEAD OF FILTERED OUT, which
+   * is a correction to this change's own first attempt at D2. Filtering the notes to
+   * the active tab looks like the reviewer's "scope it to the tab whose decision it
+   * was", and it HIDES the case the feature exists for: an agent tab is created
+   * INACTIVE by design (`tabs.ts`: "An agent `open` NEVER changes which tab the user
+   * is looking at", §11.4's focus-safety rule), so an agent's own download would
+   * leave no trace anywhere on screen — the exact complaint U3 files against the
+   * upload path, reintroduced on the download path. What the reviewer's finding
+   * actually needs is that the strip must not APPEAR to be about the page on screen:
+   * so the note keeps its `tabId`, the projection carries `activeTabId`, and the row
+   * says "on the agent's tab" when the two differ.
+   */
+  activityFor(tabId) {
+    const newest = [...this.captures.values()].at(-1);
+    return {
+      active: newest?.active ?? null,
+      // The DIRECTORY is reported from a live capture even before anything has
+      // started, so the reveal is available for the whole of a call rather than
+      // only after the first file lands. The NAME is not: "Downloading <a
+      // directory>" would be a row that appears before the page has decided to
+      // download anything.
+      dir: this.downloadDir(),
+      notes: [...this.notes].reverse(),
+      activeTabId: tabId,
+      recent: this.savedSummary
+    };
+  }
+  /** The directory the reveal opens (§16.4): the live arm's, else the newest one a
+   * decision used.
+   *
+   * HOST-WIDE ON PURPOSE, which is why it is not `activityFor`'s own field: the
+   * button is about the FOLDER the host writes into, not about a tab. Upload notes
+   * carry no directory, so they cannot answer for one. */
+  downloadDir() {
+    const dirs = this.notes.filter((note) => note.dir !== "").map((n) => n.dir);
+    return [...this.captures.values()].at(-1)?.dir ?? dirs.at(-1) ?? null;
+  }
+  /** One upload's own line (review round 1, U3).
+   *
+   * WHY AN UPLOAD HAS A NOTE AT ALL, when §16.4 deliberately has no upload
+   * affordance: the surface asymmetry was defensible while nothing was going
+   * wrong, but an upload is the more dangerous verb — and the QA matrix showed
+   * three files leaving the machine with the strip silent, or (worse) still
+   * narrating an unrelated download refusal while they left. One line naming what
+   * went where is not the per-file list §16.4 rules out; it is the same rule the
+   * download half follows, applied to the half that had none.
+   *
+   * The SITE comes from the page the action actually reported (never from a URL a
+   * caller composed), and the names are the sanitised ones the host attached. */
+  noteUpload(tabId, files, site) {
+    if (files.length === 0) return;
+    this.notes.push({
+      name: files[0]?.name ?? "",
+      count: files.length,
+      dir: "",
+      outcome: "sent",
+      reason: "",
+      at: (this.options.now ?? Date.now)(),
+      direction: "upload",
+      tabId,
+      site,
+      refusal: null,
+      ownerKind: this.ownerKindOf(tabId)
+    });
+    while (this.notes.length > NOTES_KEPT) this.notes.shift();
+    this.options.onActivity?.();
+  }
+  // ---- the item lifecycle --------------------------------------------------
+  track(item, capture, savePath) {
+    capture.started = true;
+    capture.pending += 1;
+    const entry = { item, savePath, weCancelled: false };
+    capture.live.push(entry);
+    this.showProgress(capture, entry);
+    if (capture.quietTimer) {
+      clearTimeout(capture.quietTimer);
+      capture.quietTimer = null;
+    }
+    this.options.onActivity?.();
+    item.on("updated", () => {
+      if (entry.weCancelled) return;
+      if (capture.settled) {
+        this.refuseLive(
+          capture,
+          entry,
+          `\`${path$1.basename(savePath)}\` was still being written after this call's answer`,
+          {
+            rule: "interrupted",
+            bytes: item.getReceivedBytes(),
+            limit: 0
+          }
+        );
+        return;
+      }
+      if (item.getReceivedBytes() > CAPS.downloadMaxBytes) {
+        this.overrun(capture, entry);
+        return;
+      }
+      this.showProgress(capture, entry);
+    });
+    item.once("done", (_event, state) => {
+      capture.pending -= 1;
+      capture.live = capture.live.filter((live) => live !== entry);
+      const name = path$1.basename(savePath);
+      this.release(capture, savePath);
+      if (entry.weCancelled) {
+        if (state !== "completed") discardPartial(savePath, this.options.log);
+      } else if (state === "completed") {
+        restrictMode(savePath, this.options.log);
+        capture.files.push(fileFact(item, savePath));
+        this.note(capture, name, "saved", 1, "", null);
+      } else {
+        const reason = capture.settled ? `refused: \`${name}\` did not finish (${state}) after this call's answer; the partial file was discarded` : `refused: \`${name}\` did not finish (${state}); the partial file was discarded`;
+        discardPartial(savePath, this.options.log);
+        if (!capture.settled) capture.refusals.push(reason);
+        this.note(capture, name, "refused", 1, reason, {
+          rule: "interrupted",
+          bytes: item.getReceivedBytes(),
+          limit: 0
+        });
+      }
+      this.showProgress(capture);
+      this.options.onActivity?.();
+      if (!capture.settled && capture.pending === 0) this.armQuiet(capture);
+    });
+  }
+  /** What the row says is in flight, refreshed on the render throttle.
+   *
+   * The LAST tracked item is the one the row names, which is the item a page that
+   * starts several files is currently growing; the byte counts come from the item
+   * itself, never from a sum this module keeps (a sum would be a second account of
+   * the same write). The throttle is what keeps a 40 MB download from sending a
+   * message per chunk to the renderer. */
+  showProgress(capture, entry) {
+    const last = entry ?? capture.live.at(-1);
+    capture.active = last ? {
+      name: path$1.basename(last.savePath),
+      received: last.item.getReceivedBytes(),
+      total: last.item.getTotalBytes(),
+      tabId: capture.tabId
+    } : null;
+    const now = (this.options.now ?? Date.now)();
+    if (now - capture.lastProgressAt < PROGRESS_RENDER_MS) return;
+    capture.lastProgressAt = now;
+    this.options.onActivity?.();
+  }
+  /** THE RUNTIME CAP'S REFUSAL, IN ONE PLACE (review round 2, Q4). Two triggers fire
+   * it now — Chromium's `updated` and this host's own sampler — and two spellings
+   * of one rule is exactly how the row's copy and the tool result stop agreeing.
+   *
+   * The RULE is `overrun` rather than `limit` (review round 2, R2-5): this case
+   * cancelled a write that was already on disk, and the row must not tell the user
+   * "Nothing was saved." about a partial it discarded. The SENTENCE is unchanged,
+   * because it is the tool result's and QA and the review both read it as right. */
+  overrun(capture, entry) {
+    this.refuseLive(
+      capture,
+      entry,
+      `\`${path$1.basename(entry.savePath)}\` went over the ${humanBytes(CAPS.downloadMaxBytes)} per-file download limit while it was being written`,
+      {
+        rule: "overrun",
+        bytes: entry.item.getReceivedBytes(),
+        limit: CAPS.downloadMaxBytes
+      }
+    );
+  }
+  /** Sample every still-writing transfer's own byte count for the runtime cap.
+   *
+   * WHY THIS EXISTS BESIDE THE `updated` CHECK (review round 2, Q4): `updated` is
+   * Chromium's event, and QA measured it silent for the whole of a 700 MiB write,
+   * so on its own it bounds the disk by the cap plus however long the origin stays
+   * quiet. This reads `getReceivedBytes()` — the item's own counter, the same one
+   * the refusal reports — so the ceiling is the host's to enforce rather than the
+   * page's throughput to decide. It reports nothing of its own: the refusal, the
+   * note and the cancel all go through `overrun`, so a sample can never produce a
+   * second account of a write the event already cancelled. */
+  sampleCaps(capture) {
+    if (capture.settled) return;
+    for (const entry of [...capture.live]) {
+      if (entry.weCancelled) continue;
+      if (entry.item.getReceivedBytes() <= CAPS.downloadMaxBytes) continue;
+      this.overrun(capture, entry);
+    }
+  }
+  /** Report a download this host is cancelling, and cancel it.
+   *
+   * ONE PATH FOR ALL THREE KINDS OF CANCEL (the runtime cap, the deadline, the
+   * call going away), because they differ only in the clause that explains them
+   * and a second copy would be a second chance to forget the note, the refusal or
+   * the cancel itself.
+   *
+   * `weCancelled` is set HERE rather than by the callers, and it is what makes the
+   * sentence survivable: the `done` event our own `cancel()` produces arrives after
+   * the answer in the deadline case, and the handler must then discard the residue
+   * without writing a second note. */
+  refuseLive(capture, entry, clause, refusal) {
+    entry.weCancelled = true;
+    const reason = `refused: ${clause}; it was cancelled and the partial file was discarded`;
+    capture.refusals.push(reason);
+    this.note(capture, path$1.basename(entry.savePath), "refused", 1, reason, refusal);
+    this.options.log(`[browser] ${reason}`);
+    if (entry.item.getState() !== "progressing") return;
+    try {
+      entry.item.cancel();
+    } catch (error) {
+      this.options.log(
+        `[browser] could not cancel ${path$1.basename(entry.savePath)}: ${describe(error)}`
+      );
+    }
+    if (entry.item.getState() !== "completed") {
+      discardPartial(entry.savePath, this.options.log);
+      this.release(capture, entry.savePath);
+    }
+    this.options.onActivity?.();
+  }
+  /** Cancel every download this capture still has writing. */
+  cancelLive(capture, clause, refusal) {
+    const live = [...capture.live];
+    capture.live = [];
+    for (const entry of live) {
+      if (entry.weCancelled) continue;
+      this.refuseLive(
+        capture,
+        entry,
+        `\`${path$1.basename(entry.savePath)}\` ${clause}`,
+        { ...refusal, bytes: entry.item.getReceivedBytes() }
+      );
+    }
+  }
+  armQuiet(capture) {
+    if (capture.quietTimer) clearTimeout(capture.quietTimer);
+    const timer = setTimeout(
+      () => this.settle(capture),
+      this.options.quietMs ?? QUIET_MS
+    );
+    timer.unref?.();
+    capture.quietTimer = timer;
+  }
+  /**
+   * Answer the call.
+   *
+   * THE TWO ARMS ARE THE DEADLINE AND THE QUIET WINDOW, and the quiet window never
+   * fires with a write in flight (it is only armed at `pending === 0`), so it always
+   * has the finished files Python is about to inspect. A DEADLINE can arrive
+   * mid-write, and it answers anyway — a call that never returns is worse than one
+   * that admits what it could not finish — after cancelling what was still writing,
+   * because that is the one file the harness could not describe honestly.
+   */
+  settle(capture) {
+    if (capture.settled) return;
+    if (capture.pending > 0) {
+      this.cancelLive(
+        capture,
+        `was still being written when the ${Math.round(capture.timeoutMs / 1e3)}s budget expired`,
+        {
+          rule: "deadline",
+          bytes: 0,
+          limit: Math.round(capture.timeoutMs / 1e3)
+        }
+      );
+    }
+    capture.settled = true;
+    capture.active = null;
+    this.clearTimers(capture);
+    capture.finish?.();
+    this.options.onActivity?.();
+  }
+  resultOf(capture) {
+    const reasons = [...capture.refusals];
+    if (capture.files.length === 0 && reasons.length === 0) {
+      const waited = Math.max(
+        1,
+        Math.round(
+          ((this.options.now ?? Date.now)() - capture.startedAt) / 1e3
+        )
+      );
+      reasons.push(
+        `no download started within ${waited}s; if the page needs a click first, pass a selector, or \`click\` it and retry`
+      );
+    }
+    return {
+      // `armed: false` is a POLICY answer, not a fault (§6.1). The app host always
+      // arms when the harness asks it to and reports true; the harness's own
+      // pre-arm refusals (its per-call checks before dispatching) are the caller of
+      // the other arm.
+      armed: true,
+      files: capture.files,
+      reason: reasons.join("; ")
+    };
+  }
+  refuse(capture, clean, reason, refusal) {
+    capture.refusals.push(reason);
+    this.note(capture, clean, "refused", 1, reason, refusal);
+    this.options.log(`[browser] ${reason}`);
+    return { cancel: true, reason };
+  }
+  note(capture, name, outcome, count, reason, refusal) {
+    this.notes.push({
+      name,
+      count,
+      dir: capture.dir,
+      outcome,
+      reason,
+      at: (this.options.now ?? Date.now)(),
+      direction: "download",
+      tabId: capture.tabId,
+      site: "",
+      refusal,
+      ownerKind: this.ownerKindOf(capture.tabId)
+    });
+    if (outcome === "saved") {
+      this.savedSummary = {
+        name,
+        count: (this.savedSummary?.count ?? 0) + 1
+      };
+    }
+    while (this.notes.length > NOTES_KEPT) this.notes.shift();
+  }
+  clearTimers(capture) {
+    if (capture.quietTimer) clearTimeout(capture.quietTimer);
+    if (capture.deadlineTimer) clearTimeout(capture.deadlineTimer);
+    if (capture.capTimer) clearInterval(capture.capTimer);
+    capture.quietTimer = null;
+    capture.deadlineTimer = null;
+    capture.capTimer = null;
+  }
+  /**
+   * A path in `dir` that neither exists nor has already been PROMISED in this
+   * capture. The page's name is never obeyed beyond its sanitised basename, and
+   * §11.4's rule is "no silent overwrite": the app host uniquifies with
+   * `name (1).ext` rather than letting a second download of the same name replace
+   * the first.
+   *
+   * THE RESERVATION IS THE FIX, and the earlier comment here was simply wrong
+   * (review round 1, Q1/M4). It claimed two downloads of one name on one tab
+   * "cannot race (an arm accepts them one at a time)" — being DECIDED one at a
+   * time is not being CREATED one at a time: Chromium creates the file after
+   * `setSavePath` returns, so two accepted downloads of one name are both in
+   * flight with the disk still empty, both probe the same path, and the second
+   * silently overwrites the first while the result reports two files at one path.
+   * The probe therefore runs against the filesystem AND against the paths this
+   * capture has already handed out.
+   *
+   * It is still not an atomic create, and that is honest rather than sloppy: the
+   * value is handed to Chromium, which opens the file itself, so a
+   * create-and-release probe would only add a window where the file exists empty.
+   * The reservation closes the window the probe could not see.
+   */
+  uniquePath(capture, clean, raw) {
+    const reserved = this.reserved.get(capture.dir);
+    const taken = (path2) => fs.existsSync(path2) || (reserved?.has(path2) ?? false);
+    const first = path$1.join(capture.dir, clean);
+    if (!taken(first)) return first;
+    const dot = clean.lastIndexOf(".");
+    const stem = dot > 0 ? clean.slice(0, dot) : clean;
+    const ext = dot > 0 ? clean.slice(dot + 1) : "";
+    for (let index = 1; index <= 999; index += 1) {
+      const candidate = path$1.join(
+        capture.dir,
+        ext ? `${stem} (${index}).${ext}` : `${stem} (${index})`
+      );
+      if (!taken(candidate)) return candidate;
+    }
+    return path$1.join(capture.dir, safeName(raw, extensionOf(raw) || "bin"));
+  }
+}
+function fileFact(item, savePath) {
+  return {
+    name: path$1.basename(savePath),
+    path: savePath,
+    bytes: item.getReceivedBytes(),
+    mime: item.getMimeType() || "",
+    sniffed: "",
+    sha256: ""
+  };
+}
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function humanBytes(bytes) {
+  const MiB = 1024 * 1024;
+  return `${Math.floor(bytes / MiB)} MiB`;
+}
+function discardPartial(path2, log) {
+  try {
+    if (fs.existsSync(path2)) {
+      fs.unlinkSync(path2);
+      log(`[browser] discarded the partial download at ${path$1.basename(path2)}`);
+    }
+  } catch (error) {
+    log(
+      `[browser] could not discard the partial download at ${path$1.basename(path2)}: ${describe(error)}`
+    );
+  }
+}
+function restrictMode(path2, log) {
+  try {
+    fs.chmodSync(path2, 384);
+  } catch (error) {
+    log(
+      `[browser] could not restrict ${path$1.basename(path2)} to 0600: ${describe(error)}`
+    );
+  }
+}
 function requesterOf(params, requestId2) {
   const supplied = typeof params.requester === "string" ? params.requester.trim() : "";
   return supplied.startsWith("session:") ? supplied : requestId2;
@@ -15275,10 +16166,10 @@ async function type(ctx, params) {
     returnByValue: true
   });
   await ctx.cdp.send(contents, "Input.insertText", { text });
-  const readBack = await conversationReadBack(ctx, node.objectId, contents);
-  if (readBack.includes(text)) {
+  const readBack2 = await conversationReadBack(ctx, node.objectId, contents);
+  if (readBack2.includes(text)) {
     ctx.registry.touch(record);
-    return { value: readBack, via: "insert_text", ...pageOf(record.view) };
+    return { value: readBack2, via: "insert_text", ...pageOf(record.view) };
   }
   const set = await ctx.cdp.send(
     contents,
@@ -15292,9 +16183,9 @@ async function type(ctx, params) {
   );
   ctx.registry.touch(record);
   return {
-    value: String(set?.result?.value ?? readBack),
+    value: String(set?.result?.value ?? readBack2),
     via: "value_setter",
-    insert_text_readback: readBack,
+    insert_text_readback: readBack2,
     ...pageOf(record.view)
   };
 }
@@ -15310,6 +16201,41 @@ async function conversationReadBack(ctx, objectId, contents) {
   );
   return String(out?.result?.value ?? "");
 }
+async function download(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const dir = stringParam(params, "dir");
+  if (!dir) {
+    throw new BridgeCommandError(
+      "internal",
+      "download needs the harness-composed directory to write into",
+      { param: "dir" }
+    );
+  }
+  const timeoutS = clampTimeout(numberParam(params, "timeout_s"));
+  const selector = stringParam(params, "selector");
+  try {
+    const arm = ctx.downloads.arm(record.tabId, dir, timeoutS * 1e3);
+    if (selector) await click(ctx, params);
+    const result = await arm.done();
+    ctx.registry.touch(record);
+    return {
+      files: result.files,
+      armed: result.armed,
+      reason: result.reason,
+      // The page's own identity, as every other action reports it: a caller that
+      // named a selector wants to know what it was looking at when the file
+      // started, and a click can have moved the page.
+      ...pageOf(record.view)
+    };
+  } finally {
+    ctx.downloads.forget(record.tabId);
+  }
+}
+function clampTimeout(requested) {
+  const wanted = requested === void 0 ? CAPS.downloadTimeoutS : requested;
+  if (!Number.isFinite(wanted) || wanted <= 0) return CAPS.downloadTimeoutS;
+  return Math.min(wanted, CAPS.downloadTimeoutMaxS);
+}
 const MAX_AGENT_TABS = 8;
 const BACKGROUND_VIEWPORT = {
   x: 0,
@@ -15432,6 +16358,24 @@ class TabRegistry {
       (record) => !record.view.webContents.isDestroyed() && record.view.webContents.id === webContentsId
     );
   }
+  /** The tab a webContents belongs to, or null.
+   *
+   * WHY THIS EXISTS: `will-download` is a SESSION-level handler (Electron's own
+   * split, see `profile.ts`), and the only thing it hands the handler that names a
+   * tab is the WebContents that started the download. Without this lookup the
+   * host could not tell an armed tab from an unarmed one, and every download would
+   * have to be refused — which is what it did before the file-transfer feature.
+   *
+   * A linear scan is deliberate: the set is bounded by the agent-tab cap plus the
+   * user's own tabs, it runs once per download, and a second index keyed by
+   * webContents id is one more thing that can go stale when a view dies. */
+  byWebContents(webContentsId) {
+    if (!Number.isSafeInteger(webContentsId)) return null;
+    for (const record of this.tabs.values()) {
+      if (record.view.webContents.id === webContentsId) return record;
+    }
+    return null;
+  }
   get activeTab() {
     return this.activeTabId === null ? null : this.tabs.get(this.activeTabId) ?? null;
   }
@@ -15964,6 +16908,202 @@ function retitle() {
     reason: "the browser tab is labelled with the page title"
   };
 }
+const READ_FILES_FUNCTION = `function () {
+  if (!("files" in this)) return null;
+  const descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "files");
+  let files;
+  try { files = descriptor && descriptor.get ? descriptor.get.call(this) : this.files; }
+  catch (err) { return null; }
+  if (!files) return null;
+  const list = Array.from(files);
+  return { count: list.length, names: list.map((f) => f.name), sizes: list.map((f) => f.size) };
+}`;
+const NOT_A_FILE_INPUT = 'that selector is not a file input; snapshot the page and use the element that <input type="file"> names';
+const CONTEXT_GONE = [
+  "Cannot find context with specified id",
+  "Cannot find execution context",
+  "Execution context was destroyed",
+  "Inspected target navigated or closed"
+];
+const NODE_GONE = [
+  "Node with given id does not belong to the document",
+  "No node with given id found",
+  "Could not find node with given id"
+];
+function isContextGone(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return CONTEXT_GONE.some((marker) => message.includes(marker));
+}
+function isNodeGone(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return NODE_GONE.some((marker) => message.includes(marker));
+}
+function describeError(error) {
+  const message = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
+  return message.slice(0, 120) || "no detail";
+}
+async function upload(ctx, params) {
+  const record = ctx.registry.requireSurface(params.tab);
+  const selector = stringParam(params, "selector");
+  if (!selector) {
+    throw new BridgeCommandError(
+      "element_not_found",
+      "upload needs a selector naming the file input"
+    );
+  }
+  const paths = uploadPaths(params);
+  const contents = record.view.webContents;
+  const node = await resolveNode(ctx, record, selector);
+  const accept = await acceptsOf(ctx, record, node.nodeId);
+  await ctx.cdp.send(contents, "DOM.setFileInputFiles", {
+    files: paths,
+    nodeId: node.nodeId
+  }).catch((error) => {
+    if (!/not a file input/i.test(String(error))) throw error;
+    throw new BridgeCommandError("element_not_found", NOT_A_FILE_INPUT, {
+      selector,
+      accept
+    });
+  });
+  let held = null;
+  let readback = "";
+  try {
+    held = await readBack(ctx, record, node.objectId);
+  } catch (error) {
+    readback = isContextGone(error) ? "unavailable — the page replaced its document from the change event before the input could be read back" : isNodeGone(error) ? "unavailable — the input was replaced or removed before it could be read back" : `unavailable — the read-back failed (${describeError(error)})`;
+  }
+  if (!readback) {
+    if (!held) {
+      throw new BridgeCommandError("element_not_found", NOT_A_FILE_INPUT, {
+        selector,
+        accept
+      });
+    }
+    assertHolds(paths, held, selector, accept);
+  }
+  ctx.registry.touch(record);
+  const facts = paths.map(factOf);
+  const page = pageOf(record.view);
+  ctx.downloads.noteUpload(record.tabId, facts, siteOf(page.url));
+  return {
+    // The selectors that accepted files. One entry today, because the wire takes
+    // one `selector`; the field is a list because the result vocabulary is shared
+    // with the extension host, whose `DOM.setFileInputFiles` call can address the
+    // same shape.
+    inputs: [selector],
+    accepted: facts,
+    // The host's own word about its read: "" when it completed, a sentence when it
+    // could not. The harness reports the attach as UNVERIFIED when this is set
+    // (`tools/builtin.py`: `verified = count >= 0 and not readback_reported`) rather
+    // than turning a completed egress into an error.
+    readback,
+    // The page's own identity, as every other action reports it: the harness's audit
+    // row for this call records the origin the files went TO, and a host that answered
+    // without it would leave that row naming nowhere.
+    ...page
+  };
+}
+function uploadPaths(params) {
+  const raw = params.paths;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new BridgeCommandError(
+      "internal",
+      "upload needs a non-empty list of paths",
+      { param: "paths" }
+    );
+  }
+  const paths = [];
+  for (const entry of raw) {
+    if (typeof entry !== "string" || !entry.trim()) {
+      throw new BridgeCommandError(
+        "internal",
+        "every upload path must be a non-empty string",
+        { param: "paths" }
+      );
+    }
+    const path2 = entry.trim();
+    if (!path$1.isAbsolute(path2)) {
+      throw new BridgeCommandError(
+        "internal",
+        `upload needs absolute paths; ${safeName(path2)} is not one`,
+        { param: "paths" }
+      );
+    }
+    paths.push(path2);
+  }
+  if (paths.length > CAPS.uploadMaxFiles) {
+    throw new BridgeCommandError(
+      "internal",
+      `upload takes at most ${CAPS.uploadMaxFiles} files per call`,
+      { param: "paths", limit: CAPS.uploadMaxFiles }
+    );
+  }
+  return paths;
+}
+async function acceptsOf(ctx, record, nodeId) {
+  const attributes = await ctx.cdp.send(
+    record.view.webContents,
+    "DOM.getAttributes",
+    { nodeId }
+  );
+  const list = attributes?.attributes ?? [];
+  for (let index = 0; index + 1 < list.length; index += 2) {
+    if (list[index] === "accept") return list[index + 1] ?? "";
+  }
+  return "";
+}
+async function readBack(ctx, record, objectId) {
+  const answer = await ctx.cdp.send(record.view.webContents, "Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: READ_FILES_FUNCTION,
+    returnByValue: true
+  });
+  return answer?.result?.value ?? null;
+}
+function assertHolds(paths, held, selector, accept) {
+  const expected = paths.map((path2) => path$1.basename(path2));
+  const mismatch = held.count !== expected.length || expected.some((name, index) => held.names[index] !== name) || paths.some((path2, index) => sizeOf(path2) !== held.sizes[index]);
+  if (!mismatch) return;
+  throw new BridgeCommandError(
+    "internal",
+    `the file input did not take the files: it holds ${summarise(held)}, and ${expected.length} were attached (${expected.join(", ")})`,
+    {
+      selector,
+      attached: expected,
+      held: held.names,
+      accept,
+      reason: "read_back_mismatch"
+    }
+  );
+}
+function summarise(held) {
+  if (held.count === 0) return "nothing";
+  return `${held.count} file(s) [${held.names.join(", ")}]`;
+}
+function sizeOf(path2) {
+  try {
+    return fs.statSync(path2).size;
+  } catch {
+    return -1;
+  }
+}
+function siteOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return "";
+  }
+}
+function factOf(path2) {
+  return {
+    name: path$1.basename(path2),
+    path: path2,
+    bytes: sizeOf(path2),
+    mime: "",
+    sniffed: "",
+    sha256: ""
+  };
+}
 const DOCUMENT_SCOPED = /* @__PURE__ */ new Set([
   "read",
   "snapshot",
@@ -15971,7 +17111,23 @@ const DOCUMENT_SCOPED = /* @__PURE__ */ new Set([
   "click",
   "type",
   "scroll",
-  "logs"
+  "logs",
+  // `download` names a control on the CURRENT document (the link or button that
+  // starts the file) and `upload` names a file input on it, so both are authorized
+  // against that document on entry and again on the result. BOTH are in the
+  // NAVIGATING_ACTIONS set below — each reaches its own control by driving the page,
+  // and an auto-submitting form turns an attach into a navigation — and NEITHER is
+  // in NAVIGATION_ACTIONS (the per-hop gate stays off for both); the set comments
+  // say why, and the pair is what replaced the single post-hoc check the round-1
+  // review refused (M2).
+  "download",
+  "upload"
+]);
+const NAVIGATING_ACTIONS = /* @__PURE__ */ new Set([
+  "click",
+  "type",
+  "download",
+  "upload"
 ]);
 const NAVIGATION_ACTIONS = /* @__PURE__ */ new Set(["click", "type"]);
 const TAB_SCOPED = /* @__PURE__ */ new Set([
@@ -15984,7 +17140,14 @@ const TAB_SCOPED = /* @__PURE__ */ new Set([
   "scroll",
   "logs",
   "close",
-  "retitle"
+  "retitle",
+  // The two file verbs take the tab's lane for the same reason every other
+  // tab-addressed action does, and for one more: `download` ARMS the tab for the
+  // duration of the call, and two concurrent arms on one tab would be two captures
+  // writing into two harness directories with no way to tell which file came from
+  // which call.
+  "download",
+  "upload"
 ]);
 const RESTORE_CONCURRENCY = 4;
 const RESTORE_TAB_TIMEOUT_MS = 1e4;
@@ -16021,6 +17184,7 @@ class BrowserHost {
   cdp;
   approvals;
   ownership;
+  downloads;
   log;
   onChanged;
   facts;
@@ -16044,6 +17208,7 @@ class BrowserHost {
     this.cdp = options.cdp;
     this.approvals = options.approvals;
     this.ownership = options.ownership;
+    this.downloads = options.downloads;
     this.log = options.log;
     this.onChanged = options.onChanged;
     this.facts = options.facts;
@@ -16069,10 +17234,11 @@ class BrowserHost {
     const record = this.registry.requireSurface(token);
     const requester = requesterOf(params, requestId2);
     let authorizedOn = record.documentEpoch;
+    const entryUrl = record.view.webContents.getURL();
     const assertDocument = () => {
       const url = new URL(record.view.webContents.getURL() || "about:blank");
       if (record.documentEpoch !== authorizedOn) {
-        if (!NAVIGATION_ACTIONS.has(method)) {
+        if (!NAVIGATING_ACTIONS.has(method)) {
           this.registry.bumpEpoch(record.tabId);
           throw new BridgeCommandError(
             "origin_not_allowed",
@@ -16084,6 +17250,9 @@ class BrowserHost {
       }
       if (!permittedScheme(url) || !this.approvals.documentAllowed(token, url, requester, authorizedOn)) {
         this.registry.bumpEpoch(record.tabId);
+        if (NAVIGATING_ACTIONS.has(method) && url.href !== entryUrl) {
+          this.restoreApprovedDocument(record, entryUrl);
+        }
         this.approvals.refuseDocument(url);
       }
       return url;
@@ -16109,6 +17278,22 @@ class BrowserHost {
       operation
     );
   }
+  /** Put a tab back on the document a call entered on, after that call's work
+   * landed it somewhere it may not hold.
+   *
+   * The restore is a plain load of an already-authorized URL, and it is deliberately
+   * NOT awaited: the caller is on its way to a thrown refusal, and the answer the
+   * model reads is about the refusal rather than about the repaint. A view that died
+   * under the call needs no restore and must not turn into a second error. */
+  restoreApprovedDocument(record, url) {
+    if (!url || record.view.webContents.isDestroyed()) return;
+    const restore = record.view.webContents.loadURL(url);
+    void Promise.resolve(restore).catch((error) => {
+      this.log(
+        `[browser] could not restore tab ${record.tabId} to ${url} after refusing a navigation: ${String(error)}`
+      );
+    });
+  }
   async perform(method, params, requestId2) {
     switch (method) {
       case "open":
@@ -16137,6 +17322,10 @@ class BrowserHost {
         return click(this, params);
       case "type":
         return type(this, params);
+      case "download":
+        return download(this, params);
+      case "upload":
+        return upload(this, params);
       case "request_access":
         return this.approvals.requestAccess(
           params.url,
@@ -16314,6 +17503,14 @@ class BrowserHost {
         loading: this.tabLoading(entry.tabId)
       })),
       activeTabId: activeRecord?.tabId ?? null,
+      // The download surface's facts (§16.4): what is in flight, where it went and
+      // what was refused, so the chrome row renders from the host's own state rather
+      // than from a second copy the renderer would have to keep in step. Shipped in
+      // the same projection as the strip for the reason the approvals list is: one
+      // subscription is one thing that can go stale. FOR ONE TAB (the active one),
+      // which is the round-1 D2 fix: a host-wide projection rendered a decision taken
+      // in another tab into this one's chrome.
+      transfers: this.downloads.activityFor(active?.tabId ?? null),
       url: active ? active.view.webContents.getURL() : "",
       title: active ? this.titleForChrome(active.view.webContents.getTitle()) : "",
       loading: active ? active.view.webContents.isLoading() : false,
@@ -16733,7 +17930,8 @@ const BROWSER_IPC_CHANNELS = [
   "browser-forget-site",
   "browser-clear-data",
   "browser-webauthn-respond",
-  "browser-webauthn-pending"
+  "browser-webauthn-pending",
+  "browser-reveal-downloads"
 ];
 function registerBrowserIpc(options) {
   function authorize(event) {
@@ -16862,6 +18060,15 @@ function registerBrowserIpc(options) {
     options.log(`[browser] cleared browsing data: ${what}`);
     return { cleared: what };
   });
+  electron.ipcMain.handle("browser-reveal-downloads", async (event) => {
+    authorize(event);
+    const message = await options.revealDownloads();
+    if (message)
+      options.log(
+        `[browser] could not reveal the download directory: ${message}`
+      );
+    return { opened: message === "", message };
+  });
 }
 function unregisterBrowserIpc() {
   for (const channel of BROWSER_IPC_CHANNELS) electron.ipcMain.removeHandler(channel);
@@ -17250,15 +18457,26 @@ function installBrowserSessionHandlers(browserSession, hooks = {}) {
       return false;
     }
   );
-  browserSession.on("will-download", (event, item) => {
-    event.preventDefault();
-    hooks.onDownloadAttempted?.({
-      webContentsId: -1,
-      url: item.getURL()
-    });
-    hooks.log?.(
-      `[browser] cancelled a download from ${item.getURL()}: background downloads are not supported`
-    );
+  browserSession.on("will-download", (event, item, webContents) => {
+    const webContentsId = webContents?.id ?? -1;
+    const decision = hooks.onDownload?.(item, webContentsId) ?? {
+      cancel: true,
+      reason: "background downloads are not supported"
+    };
+    if (decision.cancel) event.preventDefault();
+    const outcome = {
+      webContentsId,
+      url: item.getURL(),
+      filename: item.getFilename(),
+      savePath: decision.cancel ? null : item.getSavePath(),
+      reason: decision.reason
+    };
+    if (decision.cancel) {
+      hooks.log?.(
+        `[browser] cancelled a download from ${outcome.url}: ${decision.reason}`
+      );
+    }
+    hooks.onDownloadDecided?.(outcome);
   });
 }
 async function clearBrowsingData(browserSession, what) {
@@ -17440,7 +18658,12 @@ async function handle(req, res, options) {
         // rest, and a newer one learns whether the console is up without a
         // second probe (design 10.1). `false` when nobody reported a
         // capability, which is the honest answer for a host that has none.
-        console: options.capabilities?.().console ?? false
+        console: options.capabilities?.().console ?? false,
+        // Additive, and the SECOND reader of the same fact (§6.3): a session that
+        // finds a record it cannot trust asks here, and an old reader ignores the
+        // key. It names what this build SERVES, which is what makes a typed
+        // `capability_unsupported` possible without opening a socket.
+        capabilities: [...HOST_CAPABILITIES]
       };
       send(res, 200, body);
       return;
@@ -18562,14 +19785,34 @@ function browserHostEnabled(env = process.env) {
 async function startBrowserHost(options) {
   const { log } = options;
   const browserSession = resolveBrowserSession();
+  let registryForDownloads = null;
+  const downloads = new DownloadArmer({
+    tabForWebContents: (webContentsId) => registryForDownloads?.byWebContents(webContentsId)?.tabId ?? null,
+    // WHO OWNED THE TAB, recorded on the decision (review round 2, U10). Read from
+    // the registry at the moment the note is written, because the row may render it
+    // after the tab is closed — and "· on another tab" about a tab that no longer
+    // exists is a marker pointing at nothing. `null` when the lookup cannot answer
+    // (a tab already gone), which the row renders the old way rather than guessing.
+    ownerKindFor: (tabId) => registryForDownloads?.get(tabId)?.owner ?? null,
+    log,
+    onActivity: () => {
+      if (options.window.isDestroyed()) return;
+      options.window.webContents.send("browser-state-changed");
+    }
+  });
   installBrowserSessionHandlers(browserSession, {
     onPermissionRequested: (details) => {
       log(
         `[browser] denied a ${details.permission} permission request from ${details.origin || "(unknown origin)"}`
       );
     },
-    onDownloadAttempted: (details) => {
-      log(`[browser] refused a download from ${details.url}`);
+    onDownload: (item, webContentsId) => downloads.decide(item, webContentsId),
+    onDownloadDecided: (outcome) => {
+      if (outcome.savePath) {
+        log(
+          `[browser] saved a download from ${outcome.url} to ${outcome.savePath}`
+        );
+      }
     },
     log
   });
@@ -18668,9 +19911,11 @@ async function startBrowserHost(options) {
     releaseTab,
     notifyChanged
   );
+  registryForDownloads = registry;
   function releaseTab(tabId, webContentsId) {
     const view = views.get(tabId);
     views.delete(tabId);
+    downloads.forget(tabId);
     void cdp.detach(webContentsId).finally(() => {
       releaseView(options.window, view);
     });
@@ -18720,6 +19965,7 @@ async function startBrowserHost(options) {
     cdp,
     approvals,
     ownership,
+    downloads,
     log,
     onChanged: notifyChanged,
     facts: () => facts,
@@ -18782,6 +20028,17 @@ async function startBrowserHost(options) {
     host: () => host,
     webauthn: () => webauthn,
     clearData: (what) => sessionCookies.clearBrowsingData(what),
+    // THE REVEAL TAKES NO PATH FROM THE RENDERER (§16.4): it opens the directory the
+    // host is actually writing into, so the one place a page-derived string could
+    // have become a path stays out of the IPC surface as well. `shell.openPath`
+    // answers "" on success and a message on failure, which is returned rather than
+    // thrown: a reveal that fails is a Finder problem, not a fault in the agent's
+    // download.
+    revealDownloads: async () => {
+      const dir = downloads.downloadDir();
+      if (!dir) return "no download directory yet";
+      return electron.shell.openPath(dir);
+    },
     log
   });
   log(
@@ -20610,6 +21867,232 @@ function clauseTextOf(message, start, end) {
 function stripErrorPrefixes(message) {
   return message.replace(LEADING_ERROR_PREFIXES, "").replace(EMBEDDED_ERROR_PREFIX, ": ");
 }
+const FLEET_DRAIN_BUDGET_MS = 6e5;
+const FLEET_DRAIN_POLL_MS = 5e3;
+const FLEET_RETIRE_GRACE_MS = 6e4;
+const FLEET_RETIRE_SETTLE_MS = 3e4;
+async function waitForFleetIdle(input) {
+  const budgetMs = input.budgetMs ?? FLEET_DRAIN_BUDGET_MS;
+  const pollMs = input.pollMs ?? FLEET_DRAIN_POLL_MS;
+  const startedAt = input.now();
+  let workState = await input.readWorkState();
+  let waitedMs = 0;
+  while (workState !== "idle") {
+    waitedMs = input.now() - startedAt;
+    if (waitedMs >= budgetMs) {
+      const unknown = workState === "unknown";
+      const refusedCredentials = unknown && input.readUnreadableReason?.() === "refused-credentials";
+      return {
+        kind: "refused",
+        because: unknown ? "unknown" : "busy",
+        waitedMs,
+        busy: busyRosterRows(await input.readRoster() ?? []),
+        credentialsRefused: refusedCredentials
+      };
+    }
+    input.onWait?.(waitedMs, workState);
+    await input.sleep(Math.min(pollMs, budgetMs - waitedMs));
+    workState = await input.readWorkState();
+  }
+  return {
+    kind: "drained",
+    waitedMs: input.now() - startedAt,
+    fleet: (await input.readRoster())?.length ?? 0
+  };
+}
+function fleetDrainRefusalSentence(outcome, installLanded = false) {
+  const minutes = Math.max(1, Math.round(outcome.waitedMs / 6e4));
+  const waited = `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  const closing = installLanded ? "The install itself has landed, and the server keeps running the build it loaded until it can restart onto it; the app will offer this update again." : "Nothing was installed and the server keeps running the build it loaded; the app will offer this update again.";
+  if (outcome.because === "unknown") {
+    const lead2 = outcome.credentialsRefused ? "The server refused this app's credentials, so the app could not read which sessions are running on this machine." : "The app could not read which sessions are running on this machine, so it did not update the server.";
+    return `${lead2}
+
+Reading an unreadable fleet as idle could cut off a turn that is in flight, so the app waited ${waited} and then stopped. ${closing}`;
+  }
+  const names = outcome.busy.slice(0, 3).map((row) => row.name || row.sessionId).join(", ");
+  const more = outcome.busy.length > 3 ? ` and ${outcome.busy.length - 3} more` : "";
+  const lead = outcome.busy.length === 0 ? "The app could not name the sessions that were still working." : `${outcome.busy.length} session${outcome.busy.length === 1 ? " is" : "s are"} still running a turn on this machine: ${names}${more}.`;
+  return `${lead}
+
+The app waited ${waited} for them to finish and then stopped rather than cut a turn short. ${closing}`;
+}
+const isLiveRow = (row) => row.liveState !== "" && row.liveState !== null && row.sessionId !== "";
+const sessionHasRuntime = (rows, sessionId2) => {
+  if (rows === null) return null;
+  return rows.some((row) => row.sessionId === sessionId2 && isLiveRow(row));
+};
+const liveRosterIds = (rows) => {
+  if (rows === null) return null;
+  return new Set(rows.filter(isLiveRow).map((row) => row.sessionId));
+};
+function displacedSessions(before, after) {
+  const liveNow = liveRosterIds(after);
+  if (liveNow === null) return [];
+  return before.filter((row) => isLiveRow(row) && !liveNow.has(row.sessionId));
+}
+function unionFleetSnapshots(first, second) {
+  if (first === null) return second === null ? null : [...second];
+  if (second === null) return [...first];
+  const seen = new Set(first.map((row) => row.sessionId));
+  return [...first, ...second.filter((row) => !seen.has(row.sessionId))];
+}
+async function reengageDisplacedSessions(input) {
+  const graceMs = input.graceMs ?? FLEET_RETIRE_GRACE_MS;
+  const settleMs = input.settleMs ?? FLEET_RETIRE_SETTLE_MS;
+  const pollMs = input.retirePollMs ?? FLEET_DRAIN_POLL_MS;
+  const startedAt = input.now();
+  const snapshot2 = input.before.filter(isLiveRow);
+  if (snapshot2.length === 0)
+    return { displaced: [], engaged: [], failed: [], stillResident: [] };
+  const snapshotIds = snapshot2.map((row) => row.sessionId);
+  const stillLiveIn = (rows) => {
+    const live = liveRosterIds(rows);
+    if (live === null) return null;
+    return new Set(snapshotIds.filter((id2) => live.has(id2)));
+  };
+  let after = await input.readRoster();
+  let stillLive = stillLiveIn(after) ?? new Set(snapshotIds);
+  let lastChangeAt = input.now();
+  let waveMoved = stillLive.size < snapshotIds.length;
+  for (; ; ) {
+    const elapsed = input.now() - startedAt;
+    if (elapsed >= graceMs) break;
+    if (stillLive.size === 0) break;
+    if (waveMoved && input.now() - lastChangeAt >= settleMs) break;
+    await input.sleep(Math.min(pollMs, Math.max(1, graceMs - elapsed)));
+    after = await input.readRoster();
+    const next = stillLiveIn(after);
+    if (next === null) continue;
+    if (next.size !== stillLive.size || [...next].some((id2) => !stillLive.has(id2))) {
+      stillLive = next;
+      lastChangeAt = input.now();
+      waveMoved = true;
+    }
+  }
+  const finalRead = await input.readRoster();
+  if (finalRead !== null) after = finalRead;
+  const displaced = displacedSessions(input.before, after);
+  const stillResident = snapshot2.filter((row) => stillLive.has(row.sessionId));
+  const engaged = [];
+  const failed = [];
+  for (const row of displaced) {
+    try {
+      if (await input.engage(row)) engaged.push(row.sessionId);
+      else
+        failed.push({
+          sessionId: row.sessionId,
+          reason: "the server did not take the engage"
+        });
+    } catch (error) {
+      failed.push({
+        sessionId: row.sessionId,
+        reason: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  input.log?.(
+    `Re-engaged ${engaged.length} of ${displaced.length} displaced session(s)${failed.length > 0 ? `; ${failed.length} did not answer (${failed.map((row) => row.sessionId).join(", ")})` : ""}${stillResident.length > 0 ? `; ${stillResident.length} pre-swap runtime(s) still resident when the wait ended (${stillResident.map((row) => row.sessionId).join(", ")}), which nothing re-engages afterwards and which go cold on their own schedule` : ""}`
+  );
+  return { displaced, engaged, failed, stillResident };
+}
+const SESSION_ENGAGE_OPEN_MS = 5e3;
+const SESSION_ENGAGE_BEAT_MS = 5e3;
+const SESSION_ENGAGE_HOLD_MS = 2e4;
+const subscriptionIdIn = (frame) => {
+  try {
+    const parsed = JSON.parse(frame);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const payload = parsed.payload;
+    if (typeof payload !== "object" || payload === null) return null;
+    const id2 = payload.subscription_id;
+    return typeof id2 === "string" && id2 !== "" ? id2 : null;
+  } catch {
+    return null;
+  }
+};
+async function engageSessionThroughStream(input) {
+  const openMs = input.openMs ?? SESSION_ENGAGE_OPEN_MS;
+  const beatMs = input.beatMs ?? SESSION_ENGAGE_BEAT_MS;
+  const holdMs = input.holdMs ?? SESSION_ENGAGE_HOLD_MS;
+  const startedAt = input.now();
+  let subscriptionId = null;
+  let streamError = null;
+  const handle2 = input.subscribe(input.sessionId, (event) => {
+    if (event.kind === "data") {
+      subscriptionId ??= subscriptionIdIn(event.data);
+      return;
+    }
+    if (event.kind === "error") streamError ??= event.detail;
+    else streamError ??= "the session's events stream ended";
+  });
+  try {
+    while (subscriptionId === null && input.now() - startedAt < openMs) {
+      if (streamError !== null) break;
+      await input.sleep(
+        Math.min(beatMs, Math.max(1, openMs - (input.now() - startedAt)))
+      );
+    }
+    if (subscriptionId === null) {
+      return {
+        engaged: false,
+        reason: streamError ?? "the session's events stream never announced a subscription",
+        beats: 0
+      };
+    }
+    const lease = await input.watch(subscriptionId);
+    if (lease.status !== 200) {
+      return {
+        engaged: false,
+        reason: `the lease answered ${lease.status}`,
+        beats: 0
+      };
+    }
+    const warm = await input.warm(input.sessionId);
+    if (warm.status !== 200) {
+      input.log?.(
+        `The warm for ${input.sessionId} answered ${warm.status}; the lease is still held while the runtime comes up`
+      );
+    }
+    let beats = 0;
+    let cameUp = false;
+    let leaseHeld = true;
+    const leaseAt = input.now();
+    while (input.now() - startedAt < openMs + holdMs) {
+      const live = await input.hasRuntime();
+      if (live === true) {
+        cameUp = true;
+        break;
+      }
+      await input.sleep(
+        Math.min(
+          beatMs,
+          Math.max(1, openMs + holdMs - (input.now() - startedAt))
+        )
+      );
+      if (streamError !== null) {
+        if (leaseHeld) {
+          leaseHeld = false;
+          input.log?.(
+            `The lease for ${input.sessionId} was withdrawn when its stream ended (${streamError}); the roster read still decides whether a runtime came up`
+          );
+        }
+        continue;
+      }
+      await input.watch(subscriptionId);
+      beats += 1;
+    }
+    if (cameUp) return { engaged: true, beats };
+    const heldSeconds = Math.round((input.now() - leaseAt) / 1e3);
+    return {
+      engaged: false,
+      reason: streamError === null ? `no runtime for ${input.sessionId} ${heldSeconds}s after the lease` : `the session's events stream ended ${heldSeconds}s into the hold (${streamError}), so the lease was withdrawn before the runtime could be asked for`,
+      beats
+    };
+  } finally {
+    input.unsubscribe(handle2.streamId);
+  }
+}
 const GROUP_SIGNAL_GRACE_MS = 5e3;
 const GROUP_EXIT_WAIT_MS = 2e4;
 function isInstallGroupAlive(pid) {
@@ -20936,8 +22419,8 @@ function readPlistValue(plistPath, key) {
 }
 function readStagedBundle(appPath) {
   const plistPath = path$1.join(appPath, "Contents", "Info.plist");
-  const executableName = readPlistValue(plistPath, "CFBundleExecutable");
-  const executablePath = executableName == null ? null : path$1.join(appPath, "Contents", "MacOS", executableName);
+  const executableName2 = readPlistValue(plistPath, "CFBundleExecutable");
+  const executablePath = executableName2 == null ? null : path$1.join(appPath, "Contents", "MacOS", executableName2);
   const architectures2 = executablePath != null && fs.existsSync(executablePath) ? (readCommandOutput("/usr/bin/lipo", ["-archs", executablePath]) ?? "").split(ARCHITECTURE_SEPARATOR_REGEX).filter((entry) => entry.length > 0) : null;
   return {
     appPath,
@@ -21439,6 +22922,53 @@ class UpdateService {
    * the handler).
    */
   installPreflightInFlight = false;
+  /**
+   * How long an update press may hold back for the fleet, and how often it
+   * re-reads it.
+   *
+   * FIELDS rather than the module's constants read in place, because both halves
+   * are waited on inside one press and the harness has to be able to drive a wait
+   * in milliseconds instead of ten minutes (`scripts/update-robustness.test.mjs`,
+   * the same lever `waitForBackendVersion` and the install budgets already are).
+   * The values they start at are the host tool's own, in
+   * `backend/fleet-drain.ts`, where the reasoning for the ten minutes lives.
+   */
+  fleetDrainBudgetMs = FLEET_DRAIN_BUDGET_MS;
+  fleetDrainPollMs = FLEET_DRAIN_POLL_MS;
+  /**
+   * How long a displaced runtime gets to retire on its own before the app puts
+   * its successor back, and how long the pre-swap live set must hold still first.
+   *
+   * Fields for the reason the pair above are: a service-level case has to drive
+   * the wait in milliseconds instead of the harness's real convergence window
+   * (30 s of settle inside a 60 s grace), and the numbers themselves - with the
+   * harness constants they come from - are argued in `backend/fleet-drain.ts`.
+   */
+  fleetRetireGraceMs = FLEET_RETIRE_GRACE_MS;
+  fleetRetireSettleMs = FLEET_RETIRE_SETTLE_MS;
+  /**
+   * The engage's own three bounds: how long the session's events stream may take
+   * to announce its subscription, how often the held lease is renewed, and how
+   * long the stream is held while the runtime comes up.
+   *
+   * Fields for the reason the four above are - a service-level case drives them in
+   * milliseconds rather than paying twenty seconds per session - and the numbers
+   * themselves, with the harness constants they come from, are argued in
+   * `backend/session-engage.ts`.
+   */
+  sessionEngageOpenMs = SESSION_ENGAGE_OPEN_MS;
+  sessionEngageBeatMs = SESSION_ENGAGE_BEAT_MS;
+  sessionEngageHoldMs = SESSION_ENGAGE_HOLD_MS;
+  /**
+   * How long the press IN FLIGHT has already spent waiting for the fleet.
+   *
+   * The budget above is the press's, not each drain's (review round 1, m2): a
+   * rebuild press drains twice - once before the install and once before the
+   * restart - so a per-drain budget let one press hold the button for twenty
+   * minutes while the panel promised ten. Reset at the top of every press, in
+   * `updateBackend`, because the guarantee is about one press.
+   */
+  fleetDrainSpentMs = 0;
   /**
    * Initialize the update service
    * @param mainWindow - The main application window
@@ -23994,8 +25524,14 @@ ${heal.removed.join("\n")}`,
        * reader is talking to) was missing on the only arm whose press now
        * publishes a generation and restarts a daemon. It is the managed global
        * arm's own wording, aimed at this arm's mechanism.
+       *
+       * AND IT NO LONGER PROMISES A DROPPED TURN. It did, because it described
+       * what the press used to do; the press now waits for the running turns to
+       * finish before it moves the server (`drainFleetForUpdate`), so the honest
+       * consequence is the wait and the sequence, with the cost stated as the
+       * time it takes rather than as work it destroys.
        */
-      remedy: "The app publishes a new server environment and then restarts the server it started, so a turn that is in flight is dropped while the server comes back. This can take a minute or two.",
+      remedy: "The app publishes the new build beside the one the server is using, waits for the turns already running on this machine to finish, and then moves the server onto it, so nothing in flight is cut off. This can take a minute or two.",
       detail: `The app started this server itself (${startupMode}).`,
       sourceBuild: false,
       /*
@@ -24298,6 +25834,28 @@ ${heal.removed.join("\n")}`,
            * other two events already carry. It travels here too.
            */
           restartable: this.backendIsAppOwned(),
+          /*
+           * WHETHER THIS PRESS MOVES THE SERVER AT ALL, which is not the same
+           * question as `restartable` above and is not answerable from it.
+           * `restartable` says the daemon reading this app is one the app STARTED;
+           * this says the press would RESTART it. On the harness's generation
+           * layout the install lands in a tree no running process is reading, so
+           * the app installs and announces and the server adopts the new build at
+           * its own next idle - the cost sentence and the install phase's clause
+           * both promised a bounce, and a promise the press does not keep is the
+           * class of copy defect this panel has been reviewed for three times.
+           *
+           * THREE FACTS, and every one of them is already on this panel: the press
+           * runs the app's own publish-and-restart only where the install it would
+           * move is the app's OWN (`appOwnsInstall`, the reading below it); the
+           * global `lop update` route does not bounce anything when its install is
+           * a harness generation (`managedRoute`), and does when the route is the
+           * in-place checkout rebuild; and a daemon this app did not start is never
+           * the app's to move at all. The single case that restarts on a generation
+           * install is a press with nothing left to install - the skew panel's own
+           * control - which is a different offer entirely.
+           */
+          restartsServer: this.backendIsAppOwned() && (this.appOwnsInstall(startupMode, serving) || plan.managedRoute !== "entry-point"),
           /*
            * AND WHOSE INSTALL A PRESS WOULD MOVE (design D5), which is the other
            * ownership reading: `restartable` is true here on a global install too,
@@ -24644,6 +26202,259 @@ ${heal.removed.join("\n")}`,
   backendIsAppOwned() {
     return this.backendService?.servingInstall().owned.owned ?? false;
   }
+  /**
+   * Wait for the fleet this app can see to go idle, or refuse the update.
+   *
+   * THE ONE GATE EVERY RESTART AND EVERY IN-PLACE INSTALL GOES THROUGH. A
+   * restart of the server serving this app is `stop(true)` - SIGTERM, ten
+   * seconds, SIGKILL - and the daemon's own `retire.py` declines that exit for
+   * exactly this reason: its shutdown cancels work it owns. The operator's rule
+   * is that nothing kills runtimes en masse, so the app waits for the fleet to
+   * drain before it touches anything, and REFUSES with a remedy at the end of
+   * its budget rather than cutting off a turn on a timer.
+   *
+   * WHY THE MANAGER'S OWN READERS. `servingWorkState` is the app's existing
+   * busy signal (see `servingWorkStateFromSessions`) and `servingSessionFleet`
+   * is the same route with the rows kept; this method adds the WAIT and the
+   * refusal, not a second notion of what is running.
+   *
+   * A REFUSAL, NOT A FAILURE: it answers the press with the sentence that says
+   * what the app was waiting for, on the same channel the other refusals use
+   * (`backend-update-error`), and the install it guarded does not happen.
+   *
+   * @returns true when the fleet drained (or nothing is running in it), false
+   *   when the update was refused and the caller must not proceed
+   */
+  async drainFleetForUpdate(input) {
+    const { backend, what } = input;
+    const spentMs = this.fleetDrainSpentMs;
+    const remainingMs = Math.max(0, this.fleetDrainBudgetMs - spentMs);
+    const outcome = await waitForFleetIdle({
+      readWorkState: () => backend.servingWorkState(),
+      readRoster: () => backend.servingSessionFleet(),
+      // The transport's own reading of WHY an unreadable roster was
+      // unreadable, read only if a refusal is composed from one.
+      readUnreadableReason: () => backend.fleetReadFailureReason(),
+      sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+      now: () => Date.now(),
+      budgetMs: remainingMs,
+      pollMs: this.fleetDrainPollMs,
+      /*
+       * The panel is told the update is WAITING, and it is told before the
+       * first poll rather than after the tenth: a press that means to install
+       * and instead sits still for minutes is the silence this panel's copy
+       * exists to remove. The ELAPSED reading travels with it (design D3): a
+       * ten-minute wait with nothing moving on the frame is indistinguishable
+       * from a hung app, and `waitedMs` is the one number the app already has.
+       */
+      onWait: (elapsedMs) => {
+        this.sendToRenderer("backend-update-progress", {
+          phase: "draining",
+          waitedMs: spentMs + elapsedMs
+        });
+        logger.info(
+          `Update waiting for the fleet to drain before it may ${what} (${Math.round(elapsedMs / 1e3)}s so far)`,
+          LogFileType.UPDATE_SERVICE
+        );
+      }
+    });
+    this.fleetDrainSpentMs = spentMs + outcome.waitedMs;
+    if (outcome.kind === "drained") {
+      logger.info(
+        `The fleet is idle (${outcome.fleet} session(s) on the roster, ${outcome.waitedMs}ms waited); the update may ${what}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return true;
+    }
+    const message = fleetDrainRefusalSentence(
+      outcome,
+      input.installLanded === true
+    );
+    const command = input.command ?? null;
+    const pressWaitedMs = spentMs + outcome.waitedMs;
+    logger.warn(
+      `Refusing to ${what}: the fleet did not drain in ${pressWaitedMs}ms (${outcome.because}, ${outcome.busy.length} mid-turn, this leg spent ${outcome.waitedMs}ms). ${message}${command ? ` By hand: ${command}` : ""}`,
+      LogFileType.UPDATE_SERVICE
+    );
+    this.sendToRenderer("backend-update-error", {
+      message,
+      phase: "update",
+      logPath: serverUpdateLogPath(),
+      /*
+       * WHAT WAS WAITED FOR, and the choice made instead of forcing: this is
+       * what lets the panel paint a HELD-BACK update rather than a failed one
+       * (review round 1, D1) and put the sessions it waited for, and the
+       * command that skips the wait, where a reader can act on them.
+       */
+      refusal: {
+        because: outcome.because,
+        waitedMs: pressWaitedMs,
+        command,
+        credentialsRefused: outcome.credentialsRefused === true,
+        /*
+         * WHICH REFUSAL THIS IS (design round 2, D6). The heading is the reader's
+         * takeaway from a panel they have been looking at for ten minutes, and the
+         * three refusal sites are not the same event: the install leg's refusal left
+         * nothing on disk, while the two restart-leg refusals happen AFTER the build
+         * landed. "The update didn't start" is false on the second pair - the
+         * producer's own doc for `installLanded` says so - so the fact travels with
+         * the report and the panel keys its heading on it.
+         */
+        installLanded: input.installLanded === true
+      }
+    });
+    return false;
+  }
+  /**
+   * Put back the runtimes a restart displaced, and say what came back.
+   *
+   * Step 5 of the host tool's own order (`~/tools/lop-fleet-update`): the app
+   * snapshots the fleet, drains it, moves the server, and then re-engages what
+   * the move displaced - the unwatched `daemon`-kind sessions in particular,
+   * which nothing else revives. `reengageDisplacedSessions` owns the retire wait
+   * and the ordering rules.
+   *
+   * BEST EFFORT AND NEVER A BLOCKER: this runs after the server is healthy and
+   * the update has already been reported, so a displace list that will not come
+   * back is a logged fact rather than a failed update. That is deliberate - a
+   * `warm` the daemon refuses must not turn a landed update into an error panel.
+   */
+  async reengageFleetAfterRestart(backend, before) {
+    try {
+      const result = await reengageDisplacedSessions({
+        before,
+        readRoster: () => backend.servingSessionFleet(),
+        engage: (row) => this.engageSessionRuntime(backend, row),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        graceMs: this.fleetRetireGraceMs,
+        settleMs: this.fleetRetireSettleMs,
+        retirePollMs: this.fleetDrainPollMs,
+        log: (line) => logger.info(line, LogFileType.UPDATE_SERVICE)
+      });
+      if (result.displaced.length === 0) {
+        if (result.stillResident.length > 0) {
+          logger.info(
+            `Nothing was displaced after the restart; ${result.stillResident.length} pre-swap runtime(s) were still resident when the wait ended (${result.stillResident.map((row) => row.sessionId).join(", ")}) and will go cold on their own schedule`,
+            LogFileType.UPDATE_SERVICE
+          );
+        }
+        return;
+      }
+      if (result.failed.length > 0) {
+        logger.warn(
+          `${result.failed.length} displaced session(s) did not come back after the restart: ${result.failed.map((row) => `${row.sessionId} (${row.reason})`).join(", ")}`,
+          LogFileType.UPDATE_SERVICE
+        );
+      }
+    } catch (error) {
+      logger.warn(
+        `Could not re-engage the sessions a restart displaced: ${error instanceof Error ? error.message : String(error)}`,
+        LogFileType.UPDATE_SERVICE
+      );
+    }
+  }
+  /**
+   * Start one session's runtime again, without submitting anything to it.
+   *
+   * THE APP'S OWN PATH FOR OPENING A SESSION (review round 2, R2-M1, which is the
+   * finding that this call was a no-op against the shipped daemon). What this used
+   * to do - post `sessions.watch` with a freshly generated subscription id and then
+   * post `sessions.warm` - breaks BOTH preconditions the two routes carry:
+   *
+   * - **The lease must name a subscription the bridge KNOWS.** The id is minted
+   *   server-side by an events subscription (`DesktopSessionBridge.subscribe`) and
+   *   `watch` looks it up in that table, raising `KeyError` for one it has never
+   *   seen - which the route ladder answers as a **404**, one request before the
+   *   warm. A random id therefore never leased anything, and the engage reported
+   *   "did not answer" about a call it could have known would fail.
+   * - **A warm only survives while something else holds the bridge.** The bridge is
+   *   reference-counted by IN-FLIGHT REQUESTS; a warm issued while nothing holds it
+   *   is cancelled the moment its own request returns (`routes/desktop_sessions.py`'s
+   *   `warm` docstring, pinned by
+   *   `tests/unit/server/test_desktop_sessions.py::test_a_warm_survives_its_own_request_while_a_subscriber_holds_the_bridge`).
+   *   The renderer's panel path works because a mounted `SessionPanel` holds an
+   *   EVENTS STREAM for its whole life; a one-shot warm from main held nothing, so
+   *   the 200 said the call was admitted, not that a runtime exists.
+   *
+   * So the engage is what CLICKING THE SESSION does, through the app's own relay:
+   * hold the session's events stream, take the subscription id its `open` frame
+   * carries, lease that id as a VISIBLE watch (a live visible lease is what CREATES
+   * residency for a cold session - `DesktopSessionBridge.refresh_watch`), warm it,
+   * and keep holding until the roster says the runtime is there.
+   * `session-engage.ts` owns that rule and the evidence each leg rests on.
+   *
+   * AND THE BOOLEAN IS A CLAIM ABOUT THE MACHINE, not about a status code: every
+   * route on this path answers 200 to a call it will not act on, so what decides the
+   * outcome is the same roster read the fleet gate uses (`sessionHasRuntime`). The
+   * caller's "re-engaged N of M" log line is worth exactly that much.
+   *
+   * `visible: true` IS ONLY SAFE WHERE A PRESENCE RECORD EXISTS. The runtime prefers
+   * this app's machine-wide presence record and falls back to exactly this
+   * per-connection flag (`session/runtime/server.py::_desktop_visible`), so on a
+   * machine with no record the app is telling a session's runtime that somebody is
+   * looking at a session nobody has open - which can suppress a banner for it
+   * (`_visible_attach_surfaces`). It is kept because the lease-driven warm requires
+   * a VISIBLE lease (`_lease_warm_loop`), and it is the flag the renderer's own beat
+   * sends for a session it really is showing.
+   *
+   * NOT `sessions.message`, deliberately: a message would admit a turn in every
+   * conversation this machine holds, which is work and spend the user did not ask
+   * for, and the drain that ran before the restart is what makes a notice about
+   * interrupted work unnecessary - by construction nothing was mid-turn when the
+   * server moved.
+   */
+  async engageSessionRuntime(backend, row) {
+    const relay = backend.getStreamRelay();
+    return await engageSessionThroughStream({
+      sessionId: row.sessionId,
+      subscribe: (sessionId2, emit) => relay.subscribe({ sessionId: sessionId2 }, (event) => {
+        if (event.kind === "data") {
+          emit({ kind: "data", data: event.data });
+          return;
+        }
+        if (event.kind === "error") {
+          emit({ kind: "error", detail: event.detail });
+          return;
+        }
+        emit({ kind: "end" });
+      }),
+      unsubscribe: (streamId) => relay.unsubscribe(streamId),
+      watch: (subscriptionId) => backend.requestDesktop({
+        op: "sessions.watch",
+        sessionId: row.sessionId,
+        subscriptionId,
+        visible: true,
+        canNotify: false
+      }),
+      warm: (sessionId2) => backend.requestDesktop({ op: "sessions.warm", sessionId: sessionId2 }),
+      hasRuntime: async () => sessionHasRuntime(await backend.servingSessionFleet(), row.sessionId),
+      sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+      now: () => Date.now(),
+      openMs: this.sessionEngageOpenMs,
+      beatMs: this.sessionEngageBeatMs,
+      holdMs: this.sessionEngageHoldMs,
+      log: (line) => logger.info(line, LogFileType.UPDATE_SERVICE)
+    }).then((outcome) => {
+      if (!outcome.engaged) {
+        logger.warn(
+          `The re-engage of ${row.sessionId} did not start a runtime: ${outcome.reason ?? "no reason given"}`,
+          LogFileType.UPDATE_SERVICE
+        );
+      }
+      return outcome.engaged;
+    });
+  }
+  /**
+   * The fleet as it is now, for the before/after pair a restart is judged on.
+   *
+   * Null is a roster that could not be read, and every caller treats it as "no
+   * snapshot": a re-engage with no `before` has nothing to put back, and
+   * inventing one would re-engage sessions that were never displaced.
+   */
+  async readFleetSnapshot(backend) {
+    return backend.servingSessionFleet();
+  }
   /**
    * The build the daemon serving this app BOOTED with, or null when its record
    * carries no reading.
@@ -25047,6 +26858,14 @@ ${heal.removed.join("\n")}`,
     const budgetMs = rebuildRoute ? SOURCE_REBUILD_TIMEOUT_MS : GLOBAL_UPDATE_TIMEOUT_MS;
     const before = this.readInstallVersionAt(installPath) ?? plan.installedInstallVersion;
     const markerBefore = rebuildRoute ? this.readRebuildMarkerState(installPath) : null;
+    const fleetBeforeInstall = rebuildRoute ? await this.readFleetSnapshot(backend) : null;
+    if (rebuildRoute && !await this.drainFleetForUpdate({
+      backend,
+      command: freshPlan.updateCommand ?? null,
+      what: "install"
+    })) {
+      return false;
+    }
     this.sendToRenderer("backend-update-progress", {
       phase: "installing",
       sourceRebuild: rebuildRoute
@@ -25139,7 +26958,9 @@ ${heal.removed.join("\n")}`,
       `Global install updated: ${before ?? "unknown"} -> ${after ?? "unknown"}`,
       LogFileType.UPDATE_SERVICE
     );
-    if (backend.isUsingExternalBackend()) {
+    const generationInstall = freshPlan.managedRoute === "entry-point";
+    const installAlreadyCurrent = !rebuildRoute && before !== null && after !== null && before === after;
+    if (backend.isUsingExternalBackend() || generationInstall && !installAlreadyCurrent) {
       const health = await this.getInstalledBackendVersion();
       const running2 = this.eventRunningVersion(health);
       logger.info(
@@ -25160,14 +26981,30 @@ ${heal.removed.join("\n")}`,
       });
       return true;
     }
+    if (!await this.drainFleetForUpdate({
+      backend,
+      command: freshPlan.updateCommand ?? null,
+      what: "restart",
+      /*
+       * A press with nothing left to install has no install to report as
+       * landed, and saying one was would be the one false thing in the
+       * refusal.
+       */
+      installLanded: !installAlreadyCurrent
+    })) {
+      logger.info(
+        installAlreadyCurrent ? "Nothing was left to install; the restart was refused because the fleet did not drain. The daemon keeps serving the build it loaded." : "The install landed; the restart was refused because the fleet did not drain. The daemon keeps serving the build it loaded.",
+        LogFileType.UPDATE_SERVICE
+      );
+      return false;
+    }
     logger.info(
       "Restarting backend service onto the updated install...",
       LogFileType.UPDATE_SERVICE
     );
     this.sendToRenderer("backend-update-progress", { phase: "restarting" });
-    backend.setAutoUpdating(true);
+    const fleetBeforeRestart = await this.readFleetSnapshot(backend);
     const restartSuccess = await backend.restart();
-    backend.setAutoUpdating(false);
     if (!restartSuccess) {
       logger.error(
         "Backend service restart failed after the global install update",
@@ -25220,6 +27057,13 @@ ${heal.removed.join("\n")}`,
       `Backend reports version ${reported} after the global install update`,
       LogFileType.UPDATE_SERVICE
     );
+    const reengageSnapshot = unionFleetSnapshots(
+      fleetBeforeInstall,
+      fleetBeforeRestart
+    );
+    if (reengageSnapshot !== null) {
+      await this.reengageFleetAfterRestart(backend, reengageSnapshot);
+    }
     this.sendToRenderer("backend-update-completed", {
       installVersion: after,
       runningVersion: reported,
@@ -25302,6 +27146,12 @@ ${heal.removed.join("\n")}`,
   }
   async updateBackend(targetVersion) {
     logger.info("Updating backend...", LogFileType.UPDATE_SERVICE);
+    const backend = this.backendService;
+    const heldElsewhere = backend?.checkIsAutoUpdating?.() === true;
+    if (!heldElsewhere) {
+      this.fleetDrainSpentMs = 0;
+      backend?.setAutoUpdating(true);
+    }
     try {
       if (!this.backendService) {
         logger.error(
@@ -25421,6 +27271,8 @@ ${heal.removed.join("\n")}`,
         });
       }
       return false;
+    } finally {
+      if (!heldElsewhere) backend?.setAutoUpdating(false);
     }
   }
   /**
@@ -25563,6 +27415,15 @@ ${reason}` : ""}`,
       });
       return true;
     }
+    const fleetAfterPublish = await this.readFleetSnapshot(backend);
+    if (!await this.drainFleetForUpdate({
+      backend,
+      command: null,
+      what: "restart",
+      installLanded: outcome.replaced
+    })) {
+      return false;
+    }
     logger.info(
       "Restarting backend service onto the published environment...",
       LogFileType.UPDATE_SERVICE
@@ -25570,9 +27431,8 @@ ${reason}` : ""}`,
     if (willPublish) {
       this.sendToRenderer("backend-update-progress", { phase: "restarting" });
     }
-    backend.setAutoUpdating(true);
+    const fleetBeforeRestart = await this.readFleetSnapshot(backend);
     const restarted = await backend.restart();
-    backend.setAutoUpdating(false);
     const healthy = restarted ? await this.checkBackendHealth() : false;
     if (!restarted || !healthy) {
       logger.error(
@@ -25648,6 +27508,13 @@ ${reason}` : ""}`,
       `The server serving this app reports ${running} after the app-managed environment update`,
       LogFileType.UPDATE_SERVICE
     );
+    const reengageSnapshot = unionFleetSnapshots(
+      fleetAfterPublish,
+      fleetBeforeRestart
+    );
+    if (reengageSnapshot !== null) {
+      await this.reengageFleetAfterRestart(backend, reengageSnapshot);
+    }
     this.sendToRenderer("backend-update-completed", {
       installVersion,
       runningVersion: running,