@bivy/bivy 0.21.2-staging.1 → 0.21.2-staging.11

package/bin/archive-install.mjs

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Install and update from the self-contained GitHub release archives
+ * (scripts/release-archives.mjs). Layout under the install root
+ * (default ~/.local/share/bivy):
+ *
+ *   versions/<version>-<target>/   one extracted archive each
+ *   current -> versions/…          the active one, swapped atomically
+ *
+ * The launcher (current/bin/bivy) passes its unresolved `current` path as
+ * BIVY_ARCHIVE_ROOT, so a service unit or shim written through it keeps
+ * working after `current` moves to a new version.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+export const RELEASES_URL = "https://github.com/bivysh/bivy/releases";
+export const ARCHIVE_INFO = "bivy-archive.json";
+/** Versions kept on disk: the active one and the one before it, for rollback. */
+const KEEP = 2;
+
+/** "linux-x64" etc.: the archive target for this machine, or undefined. */
+export function archiveTarget(platform = process.platform, arch = process.arch) {
+  return ["linux", "darwin"].includes(platform) && ["x64", "arm64"].includes(arch) ? `${platform}-${arch}` : undefined;
+}
+
+/** Where a channel's manifest and archives live. `latest` is the newest stable release. */
+export function channelUrls(channel, base = process.env.BIVY_RELEASES_URL || RELEASES_URL) {
+  const dir = channel === "latest" ? `${base}/latest/download` : `${base}/download/${encodeURIComponent(channel)}`;
+  return {
+    manifest: `${dir}/manifest.json`,
+    // Stable archives are fetched from their own tag, so a release published
+    // mid-update can't swap the file under a manifest read a moment earlier.
+    archive: (manifest, file) => (channel === "latest" ? `${base}/download/v${manifest.version}/${file}` : `${dir}/${file}`),
+  };
+}
+
+/**
+ * The archive install this CLI runs from, or null. `archiveRoot` is the
+ * launcher's BIVY_ARCHIVE_ROOT; it only counts when it really is the install
+ * holding `appRoot`, so a value inherited into some other checkout is ignored.
+ */
+export function archiveInstall(archiveRoot, appRoot) {
+  if (!archiveRoot) return null;
+  try {
+    if (fs.realpathSync(path.join(archiveRoot, "app")) !== fs.realpathSync(appRoot)) return null;
+    const info = JSON.parse(fs.readFileSync(path.join(archiveRoot, ARCHIVE_INFO), "utf8"));
+    // Run as current/bin/bivy or as versions/<v>/bin/bivy, the install root is
+    // the same, and `current` is the path worth writing down.
+    const parent = path.dirname(archiveRoot);
+    const installRoot = path.basename(archiveRoot) === "current" ? parent : path.basename(parent) === "versions" ? path.dirname(parent) : undefined;
+    // An archive unpacked anywhere else runs, but has no install to update.
+    const current = path.join(installRoot ?? "", "current");
+    if (!installRoot || !fs.existsSync(current)) return null;
+    // Run through `current`, write `current`; a specific version (say, a new one
+    // being checked before the swap) stays itself.
+    const root = fs.realpathSync(archiveRoot) === fs.realpathSync(current) ? current : archiveRoot;
+    return { root, installRoot, version: info.version, target: info.target };
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchManifest(url, fetchImpl = fetch) {
+  const res = await fetchImpl(url, { signal: AbortSignal.timeout(15_000) });
+  if (!res.ok) throw new Error(`Could not read the release manifest (${res.status} from ${url})`);
+  const manifest = await res.json();
+  if (typeof manifest?.version !== "string" || !manifest.archives) throw new Error(`${url} is not a Bivy release manifest`);
+  return manifest;
+}
+
+/**
+ * Fetch a large file with curl. Node's fetch can abort the process on an
+ * assertion when a server closes the connection while the body is paused
+ * for backpressure; curl is on every machine install.sh runs on.
+ */
+export function curlDownload(url, dest) {
+  const res = spawnSync("curl", ["-fsSL", "--retry", "2", "-o", dest, url], { encoding: "utf8" });
+  if (res.status !== 0) throw new Error(`Could not download ${url}: ${(res.stderr || "").trim() || `curl exit ${res.status}`}`);
+}
+
+/**
+ * Download, verify and extract one archive into versions/. Returns its
+ * directory. Nothing outside versions/ changes, so a failure here leaves the
+ * running install untouched.
+ */
+export async function stageArchive({ installRoot, manifest, target, archiveUrl, download = curlDownload }) {
+  const entry = manifest.archives[target];
+  if (!entry) throw new Error(`Bivy ${manifest.version} has no archive for ${target}`);
+  const versions = path.join(installRoot, "versions");
+  fs.mkdirSync(versions, { recursive: true });
+  const work = fs.mkdtempSync(path.join(versions, ".stage-"));
+  try {
+    const tarball = path.join(work, entry.file);
+    await download(archiveUrl(manifest, entry.file), tarball);
+    const sha256 = crypto.createHash("sha256").update(fs.readFileSync(tarball)).digest("hex");
+    if (sha256 !== entry.sha256) throw new Error(`${entry.file} failed verification: sha256 ${sha256}, the manifest says ${entry.sha256}`);
+
+    const tar = spawnSync("tar", ["-xzf", tarball, "-C", work], { encoding: "utf8" });
+    if (tar.status !== 0) throw new Error(`Could not extract ${entry.file}: ${tar.stderr}`);
+    const extracted = path.join(work, entry.file.replace(/\.tar\.gz$/, ""));
+    const info = JSON.parse(fs.readFileSync(path.join(extracted, ARCHIVE_INFO), "utf8"));
+    if (info.version !== manifest.version || info.target !== target) throw new Error(`${entry.file} holds ${info.version} ${info.target}, not ${manifest.version} ${target}`);
+
+    const dest = path.join(versions, `${manifest.version}-${target}`);
+    // Re-staging a version (a reinstall) must not replace the directory `current`
+    // points at while it runs; move it aside first and drop it afterwards.
+    const aside = fs.existsSync(dest) ? `${dest}.old-${process.pid}` : undefined;
+    if (aside) fs.renameSync(dest, aside);
+    fs.renameSync(extracted, dest);
+    if (aside) fs.rmSync(aside, { recursive: true, force: true });
+    return dest;
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** The version directory `current` points at, or undefined. */
+export function activeVersion(installRoot) {
+  try {
+    return path.resolve(installRoot, fs.readlinkSync(path.join(installRoot, "current")));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Point `current` at a version directory atomically. Returns what it pointed at before. */
+export function activate(installRoot, versionDir) {
+  const previous = activeVersion(installRoot);
+  const link = path.join(installRoot, "current");
+  const next = `${link}.next-${process.pid}`;
+  fs.rmSync(next, { force: true });
+  fs.symlinkSync(path.relative(installRoot, versionDir), next);
+  fs.renameSync(next, link);
+  return previous;
+}
+
+/** Remove version directories other than the newest KEEP, never the active one. */
+export function prune(installRoot, keep = []) {
+  const versions = path.join(installRoot, "versions");
+  const active = activeVersion(installRoot);
+  const kept = new Set([...new Set([active, ...keep].filter(Boolean).map((p) => path.resolve(p)))].slice(0, KEEP));
+  for (const name of fs.readdirSync(versions)) {
+    const dir = path.join(versions, name);
+    if (!kept.has(dir)) fs.rmSync(dir, { recursive: true, force: true });
+  }
+}

package/bin/bivy.mjs

@@ -45,11 +45,16 @@ import { parseTailscaleStatus, serveConflict, serveFailureHint, serveOffArgs, se
 import { resolveAttachSessionId } from "./attach-session-id.mjs";
 import { detectInstallKind as classifyInstallKind, managedInstall, npmGlobalPrefix } from "./install-kind.mjs";
 import { hasConfiguredService as configuredServiceExists } from "./service-state.mjs";
+import { activate, activeVersion, archiveInstall, archiveTarget, channelUrls, fetchManifest, prune, stageArchive } from "./archive-install.mjs";
 import { COMMANDS, EXIT, cliError, completionWords, describeCli, describeCommand, describeTools, renderHelp, resolveCommand, subcommandTable, suggestCommands, toolArgv, wantsJson } from "./cli-commands.mjs";
 
-const selfScript = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(selfScript);
-const repoRoot = path.resolve(__dirname, "..");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// A GitHub release archive install runs through its launcher, which names the
+// install's `current` path. Paths written to disk (service unit, shims) use it,
+// so they stay valid when an update points `current` at a new version.
+const archive = archiveInstall(process.env.BIVY_ARCHIVE_ROOT, path.resolve(__dirname, ".."));
+const repoRoot = archive ? path.join(archive.root, "app") : path.resolve(__dirname, "..");
+const selfScript = path.join(repoRoot, "bin", "bivy.mjs");
 // Mutable node state (config, relay E2E keys, sessions, logs) must live in a
 // stable, user-owned directory that survives reinstalls. Pick it by install type:
 //   - BIVY_DATA_DIR set                         -> honor it (explicit override)
@@ -77,10 +82,11 @@ process.env.BIVY_DATA_DIR = appDir;
 //   - "git"        dev checkout (has .git)
 //   - "npx"        ephemeral `npx bivy` run (repoRoot under an npm _npx cache)
 //   - "npm-global" `npm i -g @bivy/bivy` (repoRoot is below node_modules/@bivy)
+//   - "archive"    a GitHub release archive under ~/.local/share/bivy (install.sh)
 //   - "packaged"   install.sh tarball tree (user-owned, self-preserving)
 //   - "managed"    a system package (the AUR's `bivy`), updated by its manager
 function detectInstallKind() {
-  return classifyInstallKind(repoRoot);
+  return archive ? "archive" : classifyInstallKind(repoRoot);
 }
 const cliConfigPath = path.join(appDir, "cli.json");
 const canonicalConfigPath = path.join(appDir, "config.yaml");
@@ -185,7 +191,7 @@ const mcpProxyEntry = path.join(repoRoot, packaged ? "dist/harness/mcp-proxy-cli
 const mcpServeEntry = path.join(repoRoot, packaged ? "dist/harness/mcp-serve-cli.js" : "src/harness/mcp-serve-cli.ts");
 const qrEntry = path.join(repoRoot, "public", "qr.js");
 const tsxCli = packaged ? "" : path.join(repoRoot, "node_modules", "tsx", "dist", "cli.mjs");
-const nodeBin = process.execPath;
+const nodeBin = archive ? path.join(archive.root, "runtime", "bin", "node") : process.execPath;
 const nodeScriptArgs = (entry) => (tsxCli ? [tsxCli, entry] : [entry]);
 
 // Resolve the baked-in hosted endpoints (app/relay/client URLs). Imported lazily
@@ -230,7 +236,7 @@ function commandPath(extraPath = "") {
     process.env.PATH || "",
     // npm global executables normally live beside the Node binary (including
     // nvm/fnm installs). Services need this even without shell initialization.
-    path.dirname(process.execPath),
+    path.dirname(nodeBin),
   ].filter(Boolean);
   return [...new Set(parts.flatMap((part) => String(part).split(path.delimiter)).filter(Boolean))].join(path.delimiter);
 }
@@ -2679,6 +2685,7 @@ finish: Bivy already pushes when a turn ends while the user is away. --json prin
 // Blocks until the user answers (printing the answer), or with --async returns
 // an id to read later with `bivy ask status|wait <id>`.
 const ASK_USAGE = `Usage: bivy ask "<question>" [--option <label>]… [--multi] [--header <label>] [--timeout 10m] [--async] [--json]
+       bivy ask "<question>" --secret <NAME> [--url <https://…>] [--timeout 10m] [--json]
        bivy ask status <id> [--json]
        bivy ask wait <id> [--timeout 10m] [--json]`;
 
@@ -2691,6 +2698,11 @@ Ask the user a question in the chat and wait for the answer. Their devices get a
 several with --multi) or write their own; without options they type an answer.
 --header is the short label on the card.
 
+--secret NAME asks for an API key, token or password instead: the card takes a
+hidden value, the node stores it in its vault as NAME, and this prints only
+secret://NAME, never the value. --url is where the user finds it. Use it with
+'bivy secrets exec --env NAME -- <command>'.
+
 Prints the answer and exits 0. Exits 1 if the user dismissed the question and 5
 if --timeout (default 10m, up to 24h) passes first; the card closes then.
 --async returns the question's id at once; 'bivy ask wait <id>' blocks for the
@@ -2700,7 +2712,7 @@ answer later and 'bivy ask status <id>' checks without waiting.
   }
   const json = wantsJson(args);
   const fail = (error) => cliError(error, { json, paint: c.red });
-  const parsed = parseSessionArgs(args, ["--session", "--option", "--header", "--timeout"]);
+  const parsed = parseSessionArgs(args, ["--session", "--option", "--header", "--timeout", "--secret", "--url"]);
   if (parsed.error) return fail({ code: "usage", message: parsed.error, exit: EXIT.usage });
   const sessionId = resolveAttachSessionId({ sessionFlag: parsed.one("--session"), env: process.env });
   if (!sessionId) return fail({ code: "no_session", message: "No session id.", hint: "Run inside an agent session ($BIVY_SESSION_ID) or pass --session <id>.", next: "bivy sessions --json", exit: EXIT.usage });
@@ -2723,6 +2735,7 @@ answer later and 'bivy ask status <id>' checks without waiting.
   };
   const answerText = (result) => Object.values(result.answers ?? {}).join("\n");
   const finish = (result) => {
+    if (result.status === "answered" && !answerText(result)) return fail({ code: "failed", message: "The secret was not stored on this node.", next: "bivy secrets doctor", exit: EXIT.failed });
     const out = { id: result.id, status: result.status, ...(result.status === "answered" ? { answer: answerText(result) } : {}) };
     if (result.status === "answered") { console.log(json ? JSON.stringify(out) : out.answer); return; }
     if (result.status === "pending") { console.log(json ? JSON.stringify(out) : `Still waiting for an answer. Check again with: bivy ask wait ${result.id}`); process.exit(EXIT.timeout); }
@@ -2749,8 +2762,10 @@ answer later and 'bivy ask status <id>' checks without waiting.
   if (!question) return fail({ code: "usage", message: ASK_USAGE, exit: EXIT.usage });
   const options = parsed.values["--option"] ?? [];
   if (options.length === 1) return fail({ code: "usage", message: "Offer at least two --option values, or none for a free-text answer.", exit: EXIT.usage });
+  const secretName = parsed.one("--secret");
+  if (parsed.one("--url") !== undefined && secretName === undefined) return fail({ code: "usage", message: "--url goes with --secret.", exit: EXIT.usage });
   const started = await call("", {
-    questions: [{ question, header: parsed.one("--header"), options, multiSelect: parsed.has("--multi") }],
+    questions: [{ question, header: parsed.one("--header"), options, multiSelect: parsed.has("--multi"), ...(secretName !== undefined ? { secret: { name: secretName, url: parsed.one("--url") } } : {}) }],
     timeoutSeconds: timeout,
   });
   if (parsed.has("--async")) {
@@ -4065,6 +4080,7 @@ function plistContent(config) {
     PORT: String(config.port),
     BIVY_WORKSPACE: config.workspace,
     BIVY_DATA_DIR: appDir,
+    ...(archive ? { BIVY_ARCHIVE_ROOT: archive.root } : {}),
     ...config.env,
     PATH: commandPath(config.env?.PATH),
   })
@@ -4109,6 +4125,7 @@ function systemdContent(config) {
     PORT: String(config.port),
     BIVY_WORKSPACE: config.workspace,
     BIVY_DATA_DIR: appDir,
+    ...(archive ? { BIVY_ARCHIVE_ROOT: archive.root } : {}),
     ...config.env,
     PATH: commandPath(config.env?.PATH),
   })
@@ -4301,7 +4318,9 @@ async function restartServiceReconciled(config) {
   // A typed config edit may change workspace, port, or environment without
   // touching the old unit. Reinstall on content drift so `bivy restart` really
   // applies the canonical file instead of reviving stale baked-in values.
-  if (portChanged || configChanged) return await installService(config);
+  // installService only *starts* the unit (`enable --now`, `launchctl load`),
+  // which leaves an already-running node on its old code; restart it as well.
+  if (portChanged || configChanged) return (await installService(config)) && restartService();
   return restartService();
 }
 
@@ -5515,6 +5534,49 @@ async function cmdUpdate(args = []) {
   await runUpdate(args);
 }
 
+/**
+ * Update a GitHub release archive install: stage the channel's archive beside
+ * the running one, point `current` at it, restart, and point `current` back if
+ * the node doesn't come up. The version before stays on disk for that.
+ */
+async function updateArchiveInstall(channel, { skipWait, force }) {
+  const urls = channelUrls(channel);
+  const target = archiveTarget();
+  console.log(c.dim(`Checking ${urls.manifest} (channel: ${channel})…`));
+  const manifest = await fetchManifest(urls.manifest);
+  if (manifest.version === archive.version && !force) {
+    console.log(c.green(`Bivy ${archive.version} is the newest on ${channel}.`));
+    return;
+  }
+  console.log(c.dim(`Downloading Bivy ${manifest.version} for ${target}…`));
+  const staged = await stageArchive({ installRoot: archive.installRoot, manifest, target, archiveUrl: urls.archive });
+  const probe = runQuiet(path.join(staged, "bin", "bivy"), ["--version"]);
+  if (probe.code !== 0 || probe.stdout.trim() !== manifest.version) {
+    throw new Error(`The downloaded Bivy ${manifest.version} does not run here (${(probe.stderr || probe.stdout).trim() || `exit ${probe.code}`}); kept ${archive.version}.`);
+  }
+  const config = loadConfig();
+  await waitForIdleSessions(config, { skip: skipWait });
+  const previous = activate(archive.installRoot, staged);
+  if (!hasConfiguredService(config)) {
+    prune(archive.installRoot, [staged, previous]);
+    console.log(c.green(`Updated to ${manifest.version}. Run 'bivy start' to use it.`));
+    return;
+  }
+  if ((await restartServiceReconciled(config)) && (await verifyNodeCameUp(config))) {
+    prune(archive.installRoot, [staged, previous]);
+    console.log(c.green(`Updated ${archive.version} → ${manifest.version} and restarted the background service.`));
+    return;
+  }
+  if (previous && previous !== activeVersion(archive.installRoot)) {
+    activate(archive.installRoot, previous);
+    await restartServiceReconciled(config);
+    console.log(c.red(`⚠ Bivy ${manifest.version} did not come up, so ${archive.version} is back in place.`));
+  } else {
+    reportNodeDidNotStart();
+  }
+  process.exitCode = 1;
+}
+
 async function runUpdate(args = []) {
   const skipWait = args.includes("--force") || args.includes("--no-wait");
   const kind = detectInstallKind();
@@ -5564,6 +5626,12 @@ async function runUpdate(args = []) {
     return;
   }
 
+  if (kind === "archive") {
+    await updateArchiveInstall(channel, { skipWait, force: args.includes("--force") });
+    console.log(c.dim(`=== bivy update finished ${new Date().toISOString()} ===`));
+    return;
+  }
+
   if (kind === "packaged") {
     console.log(c.dim(`Updating packaged Bivy install (channel: ${channel})…`));
     // The actual restart happens inside install.sh, which shells out to
@@ -6747,8 +6815,10 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
       // secrets-cli.ts only recognizes "--help"/"help" as the FIRST argument, so
       // a subcommand-position --help (e.g. 'bivy secrets list --help') would
       // otherwise be ignored and the live action would run anyway (#113).
-      const forwardArgs = (args.includes("-h") || args.includes("--help")) ? ["--help"] : args;
-      process.exit(await run(nodeBin, [...nodeScriptArgs(secretsEntry), ...forwardArgs], { cwd: repoRoot, env: process.env }));
+      // Words after `--` belong to `secrets exec`'s command, not to us.
+      const own = args.includes("--") ? args.slice(0, args.indexOf("--")) : args;
+      const forwardArgs = (own.includes("-h") || own.includes("--help")) ? ["--help"] : args;
+      process.exit(await run(nodeBin, [...nodeScriptArgs(secretsEntry), ...forwardArgs], { cwd: own[0] === "exec" ? process.cwd() : repoRoot, env: process.env }));
       break;
     }
     case "voice": {

package/bin/cli-commands.mjs

@@ -46,8 +46,9 @@ export const COMMANDS = [
   { name: "attach", group: "session", scope: "session", json: true, usage: 'attach <file> [--caption "…"] [--artifact]', summary: "Show a local file or image to the user in the chat" },
   { name: "notify", group: "session", scope: "session", json: true, usage: "notify [--urgent]", summary: "Push to the user's phone so they come back (nothing posted in the chat)",
     tools: [{ name: "notify_user", description: "Push to the user's phone so they come back to this session, e.g. when you are blocked on them while still working. The push names the session only and nothing is posted in the chat, so say what you need in your reply. Not needed when you finish: Bivy already pushes when a turn ends while they are away. Sent only when nobody has the app open, at most one a minute per session.", input: { urgent: { type: "boolean", description: "Push even while the user has the app open." } }, argv: ["notify", { when: "urgent", flag: "--urgent" }] }] },
-  { name: "ask", group: "session", scope: "session", json: true, usage: 'ask "<question>" [--option A --option B] [--async]', summary: "Ask the user a question and wait for the answer", subcommands: ["status", "wait"],
-    tools: [{ name: "ask_user", description: "Ask the user a question in the chat and wait for their answer (their phone gets a push). Offer 2-8 options, or none for a free-text answer; they can always write their own. Returns {status, answer}: status is answered, dismissed (decide yourself) or expired.", input: { question: { type: "string", description: "The question.", required: true }, options: { type: "array", items: { type: "string" }, description: "Choices to pick from (2-8)." }, multiple: { type: "boolean", description: "Allow several choices." }, header: { type: "string", description: "A short label for the card." }, timeout_seconds: { type: "number", description: "How long to wait (default 600)." } }, argv: ["ask", { arg: "question" }, { flag: "--option", from: "options" }, { when: "multiple", flag: "--multi" }, { flag: "--header", from: "header" }, { flag: "--timeout", from: "timeout_seconds" }] }] },
+  { name: "ask", group: "session", scope: "session", json: true, usage: 'ask "<question>" [--option A --option B] [--secret NAME] [--async]', summary: "Ask the user a question (or for a secret) and wait for the answer", subcommands: ["status", "wait"],
+    tools: [{ name: "ask_user", description: "Ask the user a question in the chat and wait for their answer (their phone gets a push). Offer 2-8 options, or none for a free-text answer; they can always write their own. Returns {status, answer}: status is answered, dismissed (decide yourself) or expired.", input: { question: { type: "string", description: "The question.", required: true }, options: { type: "array", items: { type: "string" }, description: "Choices to pick from (2-8)." }, multiple: { type: "boolean", description: "Allow several choices." }, header: { type: "string", description: "A short label for the card." }, timeout_seconds: { type: "number", description: "How long to wait (default 600)." } }, argv: ["ask", { arg: "question" }, { flag: "--option", from: "options" }, { when: "multiple", flag: "--multi" }, { flag: "--header", from: "header" }, { flag: "--timeout", from: "timeout_seconds" }] },
+      { name: "request_secret", description: "Ask the user for an API key, token or password. Their card takes a hidden value that is stored in this machine's vault as `name`; you get back only secret://<name>, never the value. Use it with `bivy secrets exec --env <name> -- <command>`. Never ask for a secret with ask_user. Returns {status, answer}.", input: { name: { type: "string", description: "Vault name, env-var style, e.g. STRIPE_API_KEY.", required: true }, question: { type: "string", description: "What to paste and why, e.g. \"Paste your Stripe secret key so I can create the products.\"", required: true }, url: { type: "string", description: "https:// page where the user finds or creates it." }, timeout_seconds: { type: "number", description: "How long to wait (default 600)." } }, argv: ["ask", { arg: "question" }, { flag: "--secret", from: "name" }, { flag: "--url", from: "url" }, { flag: "--timeout", from: "timeout_seconds" }] }] },
   { name: "title", group: "session", scope: "session", json: true, usage: 'title "<title>"', summary: "Rename this session",
     tools: [{ name: "set_session_title", description: "Rename this session in the user's session list. Use a short title (under 60 characters) that says what the work is, when the first message made a poor title or the work changed direction.", input: { title: { type: "string", description: "The new title.", required: true } }, argv: ["title", { arg: "title" }] }] },
   { name: "app", group: "session", scope: "session", json: true, usage: "app <publish|shot|present|share|run|…>", summary: "Live previews: publish a web/terminal/desktop app, screenshot it, present it", subcommands: ["publish", "list", "remove", "shot", "present", "share", "notes", "run", "click", "type", "key", "scroll", "drag", "move", "menu"],
@@ -114,7 +115,7 @@ export const COMMANDS = [
   { name: "logout", aliases: ["signout"], group: "accounts", scope: "account", usage: "logout", summary: "Sign this machine out" },
   { name: "provider", aliases: ["model"], group: "accounts", scope: "node", usage: "provider login [provider]", summary: "Sign into a model provider", subcommands: ["login"] },
   { name: "auth", aliases: ["credentials", "creds"], group: "accounts", scope: "node", usage: "auth <list|add|remove|import|sync|…>", summary: "Model credentials: import local logins, add, sync", subcommands: ["list", "add", "remove", "sync", "preset", "ingest", "config", "import"] },
-  { name: "secrets", aliases: ["secret"], group: "accounts", scope: "node", usage: "secrets <list|set|ref|delete|doctor|resolve>", summary: "Store tokens in the node vault", subcommands: ["list", "set", "ref", "delete", "doctor", "resolve"] },
+  { name: "secrets", aliases: ["secret"], group: "accounts", scope: "node", usage: "secrets <list|set|ref|delete|doctor|resolve|exec>", summary: "Store tokens in the node vault, and run a command with them", subcommands: ["list", "set", "ref", "delete", "doctor", "resolve", "exec"] },
   { name: "github:connect", aliases: ["connect-repo"], group: "accounts", scope: "node", usage: "github:connect [owner/repo]", summary: "Connect GitHub" },
   { name: "github:app-create", group: "accounts", scope: "node", usage: "github:app-create [--org <org>]", summary: "One-click: create and connect a GitHub App" },
   { name: "github:app-connect", group: "accounts", scope: "node", usage: "github:app-connect --app-id <id> --key <path.pem>", summary: "Connect an existing GitHub App" },
@@ -129,7 +130,7 @@ export const COMMANDS = [
 
   // Help and discovery
   { name: "guide", group: "help", scope: "node", json: true, usage: "guide [topic] [--json]", summary: "Short playbooks for agents: show the user, talk to them, long work, more hands, automate",
-    tools: [{ name: "bivy_guide", description: "Short playbooks for working in Bivy. Without a topic, lists them.", input: { topic: { type: "string", description: "show-the-user, talk-to-the-user, long-work, more-hands or automate." } }, argv: ["guide", { arg: "topic" }] }] },
+    tools: [{ name: "bivy_guide", description: "Short playbooks for working in Bivy. Without a topic, lists them.", input: { topic: { type: "string", description: "show-the-user, talk-to-the-user, long-work, more-hands, automate or add-an-agent." } }, argv: ["guide", { arg: "topic" }] }] },
   { name: "help", aliases: ["-h", "--help"], group: "help", scope: "node", json: true, usage: "help [command] [--json]", summary: "Show this help, one command's row, or every command as JSON" },
   { name: "version", aliases: ["--version", "-v"], group: "help", scope: "node", usage: "version", summary: "Print the installed Bivy version" },
 

package/bin/guides/add-an-agent.md

@@ -0,0 +1,39 @@
+# Add an agent: any ACP agent or CLI
+
+Summary: Make another coding agent available in Bivy, writing a small adapter when its CLI needs one.
+
+An agent with an ACP mode needs only its command:
+
+    bivy agent add gemini-acp --command gemini --args '["--experimental-acp"]'
+
+Any other CLI that takes a prompt on stdin (or as its last argument with
+`--prompt-mode argv`):
+
+    bivy agent add review-bot --transport process --command review-bot --args '["run"]'
+
+It is in the picker at once. Check it with one real turn, which prints the answer:
+
+    bivy exec -a gemini-acp "Say hello"
+
+When the CLI's output needs translating, write an adapter: a program Bivy runs
+once per turn with the prompt on stdin. It prints one JSON event per line:
+
+    {"type":"session.started","sessionId":"abc"}     # passed back as {id} to resume
+    {"type":"message.reasoning","text":"…"}
+    {"type":"tool.call","toolCallId":"t1","name":"bash","input":{"command":"ls"}}
+    {"type":"tool.result","toolCallId":"t1","result":"…"}
+    {"type":"message.delta","text":"The answer…"}
+    {"type":"usage","tokens":{"input_tokens":10,"output_tokens":20}}
+    {"type":"session.done"}                          # or {"type":"session.error","error":"…"}
+
+Start from examples/agents/jsonl-adapter/adapter.mjs in the Bivy repo, then:
+
+    bivy agent add my-agent --transport process --parser bivy-protocol \
+      --command "$PWD/adapter.mjs" --resume-args '["--resume","{id}"]'
+    bivy exec -a my-agent "List the files here"
+
+These events report what the agent did; they cannot ask before a tool runs. For
+approvals, the adapter must speak ACP (`--transport acp`).
+
+The entry lives under `agents:` in the node's config.yaml (`bivy agent list`,
+`bivy agent remove <id>`). The full format is in docs/add-an-agent.md.

package/bin/guides/talk-to-the-user.md

@@ -30,6 +30,19 @@ dismissed it (use your judgment), exit 5 that `--timeout` (default 10m) passed.
 For long waits use `--async`, keep working, and later `bivy ask wait <id>`.
 Ask only when you can't reasonably decide yourself.
 
+## You need a key or password: ask for a secret
+
+    bivy ask "Paste your Stripe secret key so I can create the products" \
+      --secret STRIPE_API_KEY --url https://dashboard.stripe.com/apikeys
+    bivy secrets exec --env STRIPE_API_KEY -- stripe products list
+
+The card takes a hidden value and stores it in this machine's vault; you get
+back `secret://STRIPE_API_KEY`, never the value. Use it through
+`bivy secrets exec`, which puts it in the command's environment. It stays
+stored for later sessions, so try `bivy secrets exec` first and ask only when
+it says the secret is missing. Never ask for a secret with a plain `bivy ask`
+or in chat, and never print it: the answer would land in the transcript.
+
 ## Name the session: title
 
     bivy title "Fix login redirect loop"

package/bin/prune-sessions.mjs

@@ -68,23 +68,55 @@ export function linkSessionWorktrees({ sessions, staleSessions, staleWorktrees,
   return { sessions: sorted, worktrees: [...removeWorktrees] };
 }
 
-// Removal set for sessions. Live ("working") sessions are never touched. The
-// newest `keep` NON-EMPTY sessions (across every agent) survive; empty/untitled
-// sessions are always beyond the keep window. An item is removed only when it is
-// BOTH beyond the keep window AND older than `ageMs` — the same safe intersection
-// as the file-based selectStale, so keep-only and age-only both behave sensibly.
-// `keep`/`ageMs` of null disable that half of the test.
+// Delegated child sessions (sub-agents, `delegatedFrom`) belong to the session
+// that started them, as the sidebar nests them. Groups sessions into families
+// keyed by the top-most listed ancestor; a child whose parent isn't listed is
+// its own root.
+function sessionFamilies(sessions) {
+  const byId = new Map(sessions.map((s) => [s.id, s]));
+  const rootOf = (s) => {
+    const seen = new Set([s.id]);
+    let cur = s;
+    for (;;) {
+      const parent = byId.get(cur.delegatedFrom?.sessionId);
+      if (!parent || seen.has(parent.id)) return cur.id;
+      seen.add(parent.id);
+      cur = parent;
+    }
+  };
+  const families = new Map();
+  for (const s of sessions) {
+    const root = rootOf(s);
+    families.set(root, [...(families.get(root) ?? []), s]);
+  }
+  return [...families.values()];
+}
+
+// Removal set for sessions. A parent and its sub-agent sessions are judged as one
+// unit: the family's activity is its newest member's, it is live if any member is
+// working, and it is empty only if every member is. So sub-agents never take
+// keep slots from real sessions, and a recent child keeps its parent (and vice
+// versa). Live families are never touched. The newest `keep` NON-EMPTY families
+// survive; empty ones are always beyond the keep window. A family is removed only
+// when it is BOTH beyond the keep window AND older than `ageMs` — the same safe
+// intersection as the file-based selectStale. `keep`/`ageMs` of null disable that
+// half of the test.
 export function selectStaleSessions(sessions, keep, ageMs, now) {
-  const eligible = sessions.filter((s) => s.status !== "working");
-  const nonEmptyDesc = eligible
-    .filter((s) => !isEmptySession(s))
-    .sort((a, b) => sessionActivityMs(b) - sessionActivityMs(a));
-  const rank = new Map(nonEmptyDesc.map((s, i) => [s.id, i]));
+  const eligible = sessionFamilies(sessions)
+    .filter((members) => !members.some((s) => s.status === "working"))
+    .map((members) => ({
+      members,
+      activity: Math.max(...members.map(sessionActivityMs)),
+      empty: members.every(isEmptySession),
+    }));
+  const nonEmptyDesc = eligible.filter((f) => !f.empty).sort((a, b) => b.activity - a.activity);
+  const rank = new Map(nonEmptyDesc.map((f, i) => [f, i]));
   return eligible
-    .filter((s) => {
-      const beyondKeep = keep === null ? true : (isEmptySession(s) ? true : (rank.get(s.id) ?? Infinity) >= keep);
-      const olderThan = ageMs === null ? true : now - sessionActivityMs(s) >= ageMs;
+    .filter((f) => {
+      const beyondKeep = keep === null ? true : (f.empty ? true : rank.get(f) >= keep);
+      const olderThan = ageMs === null ? true : now - f.activity >= ageMs;
       return beyondKeep && olderThan;
     })
+    .flatMap((f) => f.members)
     .sort((a, b) => sessionActivityMs(b) - sessionActivityMs(a));
 }