npm - agent-dag - Versions diffs - 1.28.0 → 1.29.0 - Mend

agent-dag 1.28.0 → 1.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/bin/agent-dag.js +7 -2
package/dist/web/assets/{index-WLMEm0bm.css → index-BLOOP_Fy.css} +1 -1
package/dist/web/assets/{index-D3CYh4Dp.js → index-DR2DFwYn.js} +15 -15
package/dist/web/index.html +2 -2
package/package.json +1 -1
package/src/server/claude-accounts.mjs +22 -9
package/src/server/cswap-auto.mjs +6 -5
package/src/server/cswap-install.mjs +177 -22
package/src/server/uv-bootstrap.mjs +186 -0

package/dist/web/index.html CHANGED Viewed

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agents-deck</title>
     <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='84' font-size='84'%3E%E2%97%89%3C/text%3E%3C/svg%3E" />
-    <script type="module" crossorigin src="/assets/index-D3CYh4Dp.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-WLMEm0bm.css">
+    <script type="module" crossorigin src="/assets/index-DR2DFwYn.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BLOOP_Fy.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "agent-dag",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Live deck of Claude Code and Codex agents — watch parallel subagents fork, call tools, and return on one calm canvas. Also available as npx ccdeck and npx agent-dag.",
   "type": "module",
   "bin": {

package/src/server/claude-accounts.mjs CHANGED Viewed

@@ -14,6 +14,7 @@
 // and cannot lose a login. Switching shells out to `cswap` rather than
 // reimplementing the lock protocol its correctness depends on.
 import { readFile } from "node:fs/promises";
+import { cswapBin, cswapVersion, installHint } from "./cswap-install.mjs";
 import { run, runDetached } from "./exec.mjs";
 import { join } from "node:path";
 import { homedir, platform } from "node:os";
@@ -68,7 +69,9 @@ function nudgeCollector(rows, now) {
   if (!due) return;
   _lastNudge = now;
-  runDetached("cswap", ["list"]);   // not installed — the panel already says so
+  // Fire-and-forget: this function is deliberately synchronous so callers never
+  // wait on it, and resolving the binary is the only async part.
+  cswapBin().then(bin => runDetached(bin, ["list"])).catch(() => {});
 }
 async function readJson(path) {
@@ -103,8 +106,11 @@ function lane(id, label, win) {
 /**
  * Every managed account with whatever usage claude-swap last saw for it.
  *
- * Returns { ok: false, reason: "no_store" } when claude-swap isn't installed —
- * the panel then explains itself rather than showing an empty list.
+ * When there is nothing to show, says which of the two reasons it is:
+ * "no_cswap" (the tool is not installed, and here is the command for this
+ * machine) or "no_accounts" (it is installed but nothing has been added yet).
+ * They need different things from the user, and reporting both as one empty
+ * panel leaves whichever one they are in with nowhere to go.
  */
 export async function fetchClaudeAccounts({ force = false } = {}) {
   const now = Date.now();
@@ -114,7 +120,12 @@ export async function fetchClaudeAccounts({ force = false } = {}) {
   const root = backupRoot();
   const seq  = await readJson(join(root, "sequence.json"));
-  if (!seq?.accounts) return finish({ ok: false, reason: "no_store", fetchedAt: now });
+  if (!seq?.accounts) {
+    const version = await cswapVersion();
+    return finish(version
+      ? { ok: false, reason: "no_accounts", version, fetchedAt: now }
+      : { ok: false, reason: "no_cswap", hint: await installHint(), fetchedAt: now });
+  }
   const usage = await readJson(join(root, "cache", "usage.json"));
   // A schema bump means the rows may not mean what this code thinks they do.
@@ -201,9 +212,11 @@ export function switchClaudeAccount(accountNum) {
   // Argument vector, never a shell — and resolved through exec.mjs so the
   // Windows `.exe`/`.cmd` shim is found too.
-  return run("cswap", ["switch", String(num)], { timeout: 30_000 }).then(r => {
-    if (r.ok) return { ok: true, output: r.stdout.trim() };
-    const reason = r.code === "ENOENT" ? "no_cswap" : r.killed ? "timeout" : "switch_failed";
-    return { ok: false, reason, output: (r.stderr || r.stdout).trim().slice(0, 500) };
-  });
+  return cswapBin()
+    .then(bin => run(bin, ["switch", String(num)], { timeout: 30_000 }))
+    .then(r => {
+      if (r.ok) return { ok: true, output: r.stdout.trim() };
+      const reason = r.code === "ENOENT" ? "no_cswap" : r.killed ? "timeout" : "switch_failed";
+      return { ok: false, reason, output: (r.stderr || r.stdout).trim().slice(0, 500) };
+    });
 }

package/src/server/cswap-auto.mjs CHANGED Viewed

@@ -11,6 +11,7 @@
 // on, the setting survives restarts, and the UI can always ask what a tick
 // WOULD do (--dry-run) before committing to letting it happen.
 import { run } from "./exec.mjs";
+import { cswapBin } from "./cswap-install.mjs";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -37,7 +38,7 @@ const SETTINGS = {
 /** Parse `cswap config` — "key   value   (default)" per line. */
 export async function readCswapConfig() {
-  const r = await run("cswap", ["config"]);
+  const r = await run(await cswapBin(), ["config"]);
   if (!r.ok) return null;
   const out = {};
   for (const line of r.stdout.split("\n")) {
@@ -71,7 +72,7 @@ export async function setCswapConfig(key, value) {
     if (str && !/^[A-Za-z0-9 ,._-]{1,120}$/.test(str)) return { ok: false, reason: "bad_value" };
   }
-  const r = await run("cswap", ["config", "set", key, str]);
+  const r = await run(await cswapBin(), ["config", "set", key, str]);
   return r.ok ? { ok: true } : { ok: false, reason: "set_failed", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
 }
@@ -104,7 +105,7 @@ function summarise(stdout) {
  * never switches and never writes claude-swap's state.
  */
 export async function previewAutoSwitch() {
-  const r = await run("cswap", ["auto", "--once", "--dry-run", "--json"], { timeout: TICK_TIMEOUT_MS });
+  const r = await run(await cswapBin(), ["auto", "--once", "--dry-run", "--json"], { timeout: TICK_TIMEOUT_MS });
   if (!r.ok && !r.stdout) {
     return { ok: false, reason: r.code === "ENOENT" ? "no_cswap" : "tick_failed",
              detail: (r.stderr || "").trim().slice(0, 300) };
@@ -114,7 +115,7 @@ export async function previewAutoSwitch() {
 /** Evaluate a tick for real. May switch the active account. */
 async function runAutoTick() {
-  const r = await run("cswap", ["auto", "--once", "--json"], { timeout: TICK_TIMEOUT_MS });
+  const r = await run(await cswapBin(), ["auto", "--once", "--json"], { timeout: TICK_TIMEOUT_MS });
   if (!r.ok && !r.stdout) {
     return { ok: false, reason: "tick_failed", detail: (r.stderr || "").trim().slice(0, 300) };
   }
@@ -233,6 +234,6 @@ export async function autoStatus() {
 export async function setAccountEnabled(accountNum, enabled) {
   const num = Number(accountNum);
   if (!Number.isInteger(num) || num < 1 || num > 999) return { ok: false, reason: "bad_account" };
-  const r = await run("cswap", [enabled ? "enable" : "disable", String(num)]);
+  const r = await run(await cswapBin(), [enabled ? "enable" : "disable", String(num)]);
   return r.ok ? { ok: true } : { ok: false, reason: "command_failed", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
 }

package/src/server/cswap-install.mjs CHANGED Viewed

@@ -8,7 +8,8 @@
 // entirely. It is always best-effort — the deck's core function does not
 // depend on it, so a failure is reported and then ignored.
 import { run, runDetached } from "./exec.mjs";
-import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { bootstrapUv, existingBootstrappedUv } from "./uv-bootstrap.mjs";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -19,9 +20,45 @@ const INSTALL_TIMEOUT_MS = 180_000; // uv resolves + builds a Python env
 const UPDATE_CHECK_MS = 24 * 3600_000;
 const MARKER = join(homedir(), ".agents-deck", ".cswap-update-check");
-/** Installed version string, or null when cswap isn't on PATH. */
+/**
+ * How to invoke cswap: the bare name when PATH resolves it, otherwise an
+ * absolute path to where its installers actually put it.
+ *
+ * ~/.local/bin is where both `uv tool install` and `pipx install` place
+ * executables, on every platform, and it is famously not on PATH — that is the
+ * whole reason `pipx ensurepath` exists. Installing claude-swap successfully
+ * and then reporting it as missing because the shell cannot see it is a bad
+ * enough outcome on its own; it is worse now that the deck may have done the
+ * installing. So PATH is a convenience here, not the source of truth.
+ *
+ * Re-resolved when a lookup fails so an install during this process is picked
+ * up without a restart.
+ */
+let _bin = null;
+export async function cswapBin() {
+  if (_bin) return _bin;
+  if ((await run("cswap", ["--version"], { timeout: 8_000 })).ok) return (_bin = "cswap");
+  const exe = process.platform === "win32" ? "cswap.exe" : "cswap";
+  const candidates = [
+    join(homedir(), ".local", "bin", exe),
+    // pipx before 1.5 on Windows, and any pip --user install.
+    process.platform === "win32"
+      ? join(homedir(), "AppData", "Roaming", "Python", "Scripts", exe)
+      : join(homedir(), ".pyenv", "shims", exe),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c) && (await run(c, ["--version"], { timeout: 8_000 })).ok) return (_bin = c);
+  }
+  return "cswap";   // not found; leave the bare name so errors read sensibly
+}
+/** Forget the cached resolution — call after installing. */
+export function resetCswapBin() { _bin = null; }
+/** Installed version string, or null when cswap cannot be found. */
 export async function cswapVersion() {
-  const r = await run("cswap", ["--version"]);
+  const r = await run(await cswapBin(), ["--version"]);
   if (!r.ok) return null;
   // "claude-swap 0.25.0" → "0.25.0"
   const m = (r.stdout || r.stderr).trim().match(/(\d+\.\d+\.\d+\S*)/);
@@ -37,18 +74,129 @@ export async function cswapVersion() {
  * Python environment where it can collide with their own dependencies, which
  * is not a thing to do to someone without asking.
  */
+/**
+ * Python interpreters that are safe to execute on this machine.
+ *
+ * Both desktop platforms ship a fake python that does something other than run
+ * python when none is installed, and this code runs unprompted at startup for
+ * an optional panel — so neither may be executed on spec.
+ *
+ * macOS: /usr/bin/python3 is a shim that opens the "install developer tools?"
+ * dialog. `xcode-select -p` says whether the real thing is behind it, and is
+ * itself only a path lookup.
+ *
+ * Windows: `python` and `python3` are App Execution Aliases under
+ * WindowsApps — zero-length reparse points that open the Microsoft Store. They
+ * are on PATH whether or not Python exists, so presence proves nothing and
+ * running one opens the Store. `where` reports the paths without executing
+ * anything, so the aliases can be filtered out and the real interpreter (if
+ * any) called by absolute path. `py`, the Python launcher, only exists when
+ * Python was actually installed and is safe as-is.
+ *
+ * Returns absolute paths or bare command names, best first; empty when there
+ * is nothing safe to run.
+ */
+let _pythons = null;
+async function safePythons() {
+  if (_pythons != null) return _pythons;
+  if (process.platform === "darwin") {
+    _pythons = (await run("xcode-select", ["-p"], { timeout: 5_000 })).ok
+      ? ["python3", "python"]
+      : [];
+    return _pythons;
+  }
+  if (process.platform !== "win32") {
+    _pythons = ["python3", "python"];
+    return _pythons;
+  }
+  const found = [];
+  // The launcher first: it is never an alias.
+  if ((await run("py", ["-0"], { timeout: 8_000 })).ok) found.push("py");
+  for (const name of ["python", "python3"]) {
+    const r = await run("where", [name], { timeout: 8_000 });
+    if (!r.ok) continue;
+    for (const line of r.stdout.split(/\r?\n/)) {
+      const p = line.trim();
+      if (!p || /\\WindowsApps\\/i.test(p)) continue;   // Store alias, not an interpreter
+      found.push(p);
+      break;
+    }
+  }
+  _pythons = found;
+  return _pythons;
+}
+/**
+ * Ways to install a Python application, best first.
+ *
+ * `python -m pipx` matters more than it looks: pipx is very often present as a
+ * module without a `pipx` on PATH — every Debian/Ubuntu `apt install pipx`, and
+ * any `pip install --user pipx` where ~/.local/bin was never added to PATH. The
+ * two-entry version of this list reported "needs uv or pipx" to people who had
+ * pipx installed, which is the kind of wrong answer that stops someone looking.
+ */
+async function installers() {
+  const out = [
+    { cmd: "uv",   probe: ["--version"], args: ["tool", "install", "claude-swap"], via: "uv" },
+    { cmd: "pipx", probe: ["--version"], args: ["install", "claude-swap"],         via: "pipx" },
+  ];
+  // A uv fetched on an earlier run counts as installed tooling from here on.
+  const own = existingBootstrappedUv();
+  if (own) out.push({ cmd: own, probe: ["--version"], args: ["tool", "install", "claude-swap"], via: "uv (bundled)" });
+  for (const py of await safePythons()) {
+    out.push({
+      cmd: py,
+      probe: ["-m", "pipx", "--version"],
+      args: ["-m", "pipx", "install", "claude-swap"],
+      via: `${py} -m pipx`,
+    });
+  }
+  return out;
+}
 async function installCswap() {
-  for (const [cmd, args] of [
-    ["uv",   ["tool", "install", "claude-swap"]],
-    ["pipx", ["install", "claude-swap"]],
-  ]) {
-    const probe = await run(cmd, ["--version"], { timeout: 5_000 });
-    if (!probe.ok) continue;
+  for (const { cmd, probe, args, via } of await installers()) {
+    if (!(await run(cmd, probe, { timeout: 8_000 })).ok) continue;
     const r = await run(cmd, args, { timeout: INSTALL_TIMEOUT_MS });
-    if (r.ok) return { ok: true, via: cmd };
-    return { ok: false, reason: "install_failed", via: cmd, detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+    if (r.ok) return { ok: true, via };
+    return { ok: false, reason: "install_failed", via, detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+  }
+  // Nothing on the machine can install a Python application. Rather than hand
+  // the user a command and stop, fetch uv itself — verified, and into the
+  // deck's own directory, see uv-bootstrap.mjs — and use that.
+  const boot = await bootstrapUv();
+  if (!boot.ok) return { ok: false, reason: "no_installer", bootstrap: boot.reason, hint: await installHint() };
+  const r = await run(boot.bin, ["tool", "install", "claude-swap"], { timeout: INSTALL_TIMEOUT_MS });
+  if (r.ok) return { ok: true, via: `uv ${boot.version} (fetched)` };
+  return { ok: false, reason: "install_failed", via: "uv (fetched)", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+}
+/**
+ * What to actually type, for this machine.
+ *
+ * "needs uv or pipx" is a dead end for the person who has neither and no
+ * opinion about Python packaging — which is most people running a Node CLI.
+ * uv is a single self-contained binary and is what claude-swap documents, so
+ * that is what gets recommended; if the machine already has Python, pipx via
+ * pip is offered instead because it uses something already installed.
+ */
+export async function installHint() {
+  const uv = process.platform === "win32"
+    ? 'powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  (then: uv tool install claude-swap)'
+    : "curl -LsSf https://astral.sh/uv/install.sh | sh  (then: uv tool install claude-swap)";
+  for (const py of await safePythons()) {
+    if ((await run(py, ["-c", "import sys"], { timeout: 5_000 })).ok) {
+      // Quoted: a resolved Windows path routinely contains spaces.
+      const q = /\s/.test(py) ? `"${py}"` : py;
+      return `${q} -m pip install --user pipx && ${q} -m pipx install claude-swap`;
+    }
   }
-  return { ok: false, reason: "no_installer" };
+  return uv;
 }
 function updateCheckDue() {
@@ -94,15 +242,20 @@ function isOlder(a, b) {
  * take tens of seconds, which is not a thing to put in front of the server
  * starting. The running copy keeps working; the new one is there next launch.
  */
-function upgradeInBackground(via) {
-  const args = via === "uv" ? ["tool", "upgrade", "claude-swap"] : ["upgrade", "claude-swap"];
-  runDetached(via, args);
+function upgradeInBackground(found) {
+  const { cmd, via } = found;
+  const args = via === "uv"
+    ? ["tool", "upgrade", "claude-swap"]
+    : via === "pipx"
+      ? ["upgrade", "claude-swap"]
+      : ["-m", "pipx", "upgrade", "claude-swap"];   // python -m pipx
+  runDetached(cmd, args);
 }
 /** Whichever Python tool installer is available, or null. */
 async function findInstaller() {
-  for (const cmd of ["uv", "pipx"]) {
-    if ((await run(cmd, ["--version"], { timeout: 5_000 })).ok) return cmd;
+  for (const { cmd, probe, via } of await installers()) {
+    if ((await run(cmd, probe, { timeout: 8_000 })).ok) return { cmd, via };
   }
   return null;
 }
@@ -127,10 +280,10 @@ export async function ensureCswap() {
     touchMarker();
     const latest = await latestOnPypi();
     if (latest && existing !== "installed" && isOlder(existing, latest)) {
-      const via = await findInstaller();
-      if (via) {
-        upgradeInBackground(via);
-        return { state: "upgrading", version: existing, latest, via };
+      const found = await findInstaller();
+      if (found) {
+        upgradeInBackground(found);
+        return { state: "upgrading", version: existing, latest, via: found.via };
       }
     }
     return { state: "present", version: existing };
@@ -138,9 +291,11 @@ export async function ensureCswap() {
   const result = await installCswap();
   if (!result.ok) return { state: "unavailable", ...result };
+  resetCswapBin();   // it exists now; the earlier "not on PATH" answer is stale
   // Freshly installed tools land in ~/.local/bin, which may not be on the PATH
-  // of the shell that launched us — so confirm rather than assume.
+  // of the shell that launched us — cswapBin looks there directly, so this
+  // confirms the install rather than confirming the user's PATH.
   const version = await cswapVersion();
   return version
     ? { state: "installed", via: result.via, version }

package/src/server/uv-bootstrap.mjs ADDED Viewed

@@ -0,0 +1,186 @@
+// Last-resort acquisition of `uv`, so claude-swap can be installed on a machine
+// with no Python tooling at all.
+//
+// The alternative everyone reaches for is `curl -LsSf https://astral.sh/uv/
+// install.sh | sh`, which executes whatever that URL happens to serve, with the
+// user's privileges, and drops files into their global tool path. This does the
+// narrower thing instead: fetch one named release artifact from Astral's own
+// GitHub releases, check it against the SHA-256 that release publishes beside
+// it, and unpack it inside ~/.agents-deck. Nothing is executed until it has
+// been verified, nothing lands outside a directory the deck already owns, and
+// deleting that directory undoes all of it.
+//
+// It is still a network fetch of an executable, so it only happens when there
+// is no other way: uv, pipx, and python -m pipx have all already been ruled out
+// by the caller. AGENTS_DECK_NO_INSTALL=1 disables it along with everything else.
+import { createHash } from "node:crypto";
+import { mkdir, writeFile, rm, chmod, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { run } from "./exec.mjs";
+const TOOL_DIR = join(homedir(), ".agents-deck", "tools");
+const UV_DIR   = join(TOOL_DIR, "uv");
+const RELEASE_API = "https://api.github.com/repos/astral-sh/uv/releases/latest";
+const DOWNLOAD_BASE = "https://github.com/astral-sh/uv/releases/download";
+// Used when the releases API cannot be reached — rate limiting is per-IP and
+// unauthenticated, so this is a normal outcome rather than an error. Any
+// reasonably recent uv can install claude-swap; it self-updates later.
+const FALLBACK_VERSION = "0.12.3";
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+/**
+ * Release artifact for this machine, or null if uv does not publish one.
+ *
+ * Rosetta is deliberately not special-cased: an x64 Node on Apple Silicon
+ * reports x64 and gets the x64 build, which runs.
+ */
+export function assetName(platform = process.platform, arch = process.arch) {
+  const a = { x64: "x86_64", arm64: "aarch64", ia32: "i686" }[arch];
+  if (!a) return null;
+  // Apple publishes no i686 build, and never will.
+  if (platform === "darwin") return a === "i686" ? null : `uv-${a}-apple-darwin.tar.gz`;
+  if (platform === "win32")  return `uv-${a}-pc-windows-msvc.zip`;
+  if (platform === "linux")  return `uv-${a}-unknown-linux-gnu.tar.gz`;
+  return null;
+}
+/** Path to a uv this function installed earlier, or null. */
+export function existingBootstrappedUv() {
+  const bin = join(UV_DIR, process.platform === "win32" ? "uv.exe" : "uv");
+  return existsSync(bin) ? bin : null;
+}
+async function latestVersion() {
+  try {
+    const res = await fetch(RELEASE_API, {
+      headers: { accept: "application/vnd.github+json", "user-agent": "agents-deck" },
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (!res.ok) return FALLBACK_VERSION;
+    const tag = (await res.json())?.tag_name;
+    return typeof tag === "string" && /^\d/.test(tag) ? tag : FALLBACK_VERSION;
+  } catch {
+    return FALLBACK_VERSION;
+  }
+}
+async function download(url, { asText = false } = {}) {
+  const res = await fetch(url, {
+    redirect: "follow",
+    headers: { "user-agent": "agents-deck" },
+    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+  });
+  if (!res.ok) return null;
+  return asText ? (await res.text()) : Buffer.from(await res.arrayBuffer());
+}
+/**
+ * Unpack the artifact.
+ *
+ * `tar` is present on macOS, on Linux, and on Windows 10 1803 and later (as
+ * bsdtar), but Windows ships .zip and older Windows has no tar at all — so zip
+ * goes through PowerShell's Expand-Archive, which is always there.
+ */
+async function extract(archivePath, destDir) {
+  if (archivePath.endsWith(".zip")) {
+    const r = await run("powershell.exe", [
+      "-NoProfile", "-NonInteractive", "-Command",
+      `Expand-Archive -LiteralPath '${archivePath}' -DestinationPath '${destDir}' -Force`,
+    ], { timeout: 120_000 });
+    return r.ok;
+  }
+  const r = await run("tar", ["-xzf", archivePath, "-C", destDir], { timeout: 120_000 });
+  return r.ok;
+}
+/**
+ * Find the uv executable somewhere under `dir`.
+ *
+ * The archives put it in a versioned subdirectory whose name has changed
+ * between releases, so it is located rather than assumed.
+ */
+async function findUv(dir, depth = 0) {
+  const wanted = process.platform === "win32" ? "uv.exe" : "uv";
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); } catch { return null; }
+  for (const e of entries) {
+    if (e.isFile() && e.name === wanted) return join(dir, e.name);
+  }
+  if (depth >= 2) return null;
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const hit = await findUv(join(dir, e.name), depth + 1);
+    if (hit) return hit;
+  }
+  return null;
+}
+/**
+ * Download and verify uv into ~/.agents-deck/tools/uv.
+ *
+ * Returns { ok: true, bin, version } or { ok: false, reason }. Never throws:
+ * every caller treats a missing uv as an expected state.
+ */
+export async function bootstrapUv() {
+  const already = existingBootstrappedUv();
+  if (already) return { ok: true, bin: already, version: "existing" };
+  // Downloading an executable is a bigger step than installing a package with a
+  // tool the user already chose, so it gets its own off switch as well as the
+  // blanket one — someone may want the managed installs and not this.
+  if (process.env.AGENTS_DECK_NO_DOWNLOAD === "1") return { ok: false, reason: "download_disabled" };
+  const asset = assetName();
+  if (!asset) return { ok: false, reason: "unsupported_platform" };
+  const version = await latestVersion();
+  const base = `${DOWNLOAD_BASE}/${version}/${asset}`;
+  const staging = join(tmpdir(), `agents-deck-uv-${process.pid}`);
+  try {
+    const [archive, sumText] = await Promise.all([
+      download(base),
+      download(`${base}.sha256`, { asText: true }),
+    ]);
+    if (!archive) return { ok: false, reason: "download_failed" };
+    // No published checksum means no way to know what was downloaded, and an
+    // unverified binary is not something to run on someone's machine.
+    const expected = sumText?.trim().split(/\s+/)[0]?.toLowerCase();
+    if (!expected || !/^[0-9a-f]{64}$/.test(expected)) {
+      return { ok: false, reason: "no_checksum" };
+    }
+    const actual = createHash("sha256").update(archive).digest("hex");
+    if (actual !== expected) return { ok: false, reason: "checksum_mismatch" };
+    await mkdir(staging, { recursive: true });
+    const archivePath = join(staging, asset);
+    await writeFile(archivePath, archive);
+    if (!(await extract(archivePath, staging))) return { ok: false, reason: "extract_failed" };
+    const found = await findUv(staging);
+    if (!found) return { ok: false, reason: "not_in_archive" };
+    await mkdir(UV_DIR, { recursive: true });
+    const dest = join(UV_DIR, process.platform === "win32" ? "uv.exe" : "uv");
+    // Copy rather than rename: the staging dir is in the system temp directory,
+    // which is often a different filesystem, and rename across one fails.
+    const { copyFile } = await import("node:fs/promises");
+    await copyFile(found, dest);
+    if (process.platform !== "win32") await chmod(dest, 0o755);
+    const check = await run(dest, ["--version"], { timeout: 15_000 });
+    if (!check.ok) return { ok: false, reason: "does_not_run" };
+    return { ok: true, bin: dest, version };
+  } catch (err) {
+    return { ok: false, reason: "error", detail: String(err?.message ?? err).slice(0, 200) };
+  } finally {
+    await rm(staging, { recursive: true, force: true }).catch(() => {});
+  }
+}