@bivy/bivy 0.20.1-staging.4 → 0.20.1-staging.6

package/bin/bivy.mjs

@@ -40,6 +40,7 @@ import { nativeResumeRef, resolveSessionsLimit, truncateSavedSessions } from "./
 import { renderManagedBlock, upsertManagedBlock, removeManagedBlock, rcFileForShell } from "./shim-path.mjs";
 import { removeInstallAndState } from "./uninstall-paths.mjs";
 import { findAvailablePort, reconcilePort } from "./port-picker.mjs";
+import { parseTailscaleStatus, serveConflict, serveFailureHint, serveOffArgs, serveOnArgs, serveState } from "./tailscale.mjs";
 import { resolveAttachSessionId } from "./attach-session-id.mjs";
 import { detectInstallKind as classifyInstallKind, npmGlobalPrefix } from "./install-kind.mjs";
 import { hasConfiguredService as configuredServiceExists } from "./service-state.mjs";
@@ -2521,18 +2522,18 @@ async function cmdContext(args = []) {
   console.log(`\nEverything else: ${c.cyan("bivy help")} (or ${c.cyan("bivy help --json")}).`);
 }
 
-// `bivy suggest "<task>" [--title "…"] [--session <id>]` — propose a task the
-// user can start in one tap, beside this session or in it. For an agent
+// `bivy suggest "<task>" [--title "…"] [--run here|subagents|new] [--session <id>]`
+// — propose a task the user can start in one tap, in this session or beside it. For an agent
 // offering next steps: write the task as a complete instruction.
 async function cmdSuggest(args = []) {
-  const usage = 'Usage: bivy suggest "<task>" [--title "short label"] [--session <id>] [--json]';
+  const usage = 'Usage: bivy suggest "<task>" [--title "short label"] [--run here|subagents|new] [--session <id>] [--json]';
   if (args.includes("-h") || args.includes("--help")) {
-    console.log(`${usage}\n\nPost a task the user can start in one tap, in this session or in a parallel one that works in its own copy of the project. Write it as a complete instruction, with paths relative to the project root. --json prints {"ok","id"}.`);
+    console.log(`${usage}\n\nPost a task the user can start in one tap: in this session, through your sub-agents, or in a parallel session that works in its own copy of the project. Write it as a complete instruction, with paths relative to the project root.\n\n--run says where you recommend running it, which becomes the card's main button: here (builds on this conversation), subagents (independent tasks you can split across your own sub-agents; only if you have them), or new (bigger independent work the user will want to follow in its own session). Without it, one card recommends here and several recommend new.\n\n--json prints {"ok","id"}.`);
     return;
   }
   const json = wantsJson(args);
   const fail = (error) => cliError(error, { json, paint: c.red });
-  const flagsWithValue = new Set(["--session", "--title"]);
+  const flagsWithValue = new Set(["--session", "--title", "--run"]);
   const flag = (name) => {
     const i = args.indexOf(name);
     return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
@@ -2540,10 +2541,12 @@ async function cmdSuggest(args = []) {
   const text = args.filter((a, i) => !a.startsWith("-") && !(i > 0 && flagsWithValue.has(args[i - 1]))).join(" ").trim();
   const sessionId = resolveAttachSessionId({ sessionFlag: flag("--session"), env: process.env });
   if (!text) return fail({ code: "usage", message: usage, exit: EXIT.usage });
+  const run = flag("--run");
+  if (run !== undefined && !["here", "subagents", "new"].includes(run)) return fail({ code: "usage", message: `--run is here, subagents or new (got "${run}").`, exit: EXIT.usage });
   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 });
   const config = loadConfig();
   if (!(await ensureNodeRunning(config))) return fail({ code: "node_unreachable", message: `Could not reach the Bivy node at ${url(config)}.`, next: "bivy status", exit: EXIT.unavailable });
-  const res = await sessionPost(config, sessionId, "suggest", { text, title: flag("--title") }).catch((error) => error);
+  const res = await sessionPost(config, sessionId, "suggest", { text, title: flag("--title"), run }).catch((error) => error);
   if (res instanceof Error) return fail({ code: "node_unreachable", message: `Could not reach the Bivy node: ${res.message}`, next: "bivy status", exit: EXIT.unavailable });
   const body = await res.json().catch(() => ({}));
   if (!res.ok) return fail(sessionHttpError("Suggest", res.status, body));
@@ -5671,6 +5674,122 @@ async function cmdLinkPhone(args = []) {
   }
 }
 
+const tailscaleConfigPath = path.join(appDir, "tailscale.json");
+const LOCAL_TOKEN_NAMES = ["Bivy CLI", "Local Remote UI"];
+
+function runTailscale(args) {
+  const res = spawnSync("tailscale", args, { encoding: "utf8" });
+  if (res.error?.code === "ENOENT") return null;
+  return { ok: res.status === 0, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+async function printPairLink(config) {
+  const data = await localApi(config, "/api/auth/pair-codes", { method: "POST", body: "{}" });
+  if (!data?.url) throw new Error("The node did not return a pairing link.");
+  const qr = terminalQr(data.url);
+  if (qr) console.log(qr);
+  console.log(`\nOpen on your phone (single use, 10 minutes):\n${c.cyan(data.url)}\n`);
+}
+
+// `bivy tailscale` — reach this machine from anywhere on your tailnet with no
+// control plane or relay: `tailscale serve` puts HTTPS on the machine's ts.net
+// name and forwards it to the node's direct listener, which serves the web app.
+async function cmdTailscale(args = []) {
+  const [verb = "on"] = args;
+  if (args.includes("-h") || args.includes("--help") || !["on", "pair", "status", "devices", "revoke", "off"].includes(verb)) {
+    console.log(`Usage: bivy tailscale [on|pair|status|devices|revoke <id>|off]
+
+  on           Serve this machine's Bivy on https://<machine>.<tailnet>.ts.net (tailnet only) and show a pairing link
+  pair         Show a new one-time pairing link for another device
+  status       Show the Tailscale address and whether it is served
+  devices      List the devices holding a token for this node
+  revoke <id>  Revoke a device's token and disconnect it
+  off          Stop serving Bivy over Tailscale`);
+    return;
+  }
+  const config = loadConfig();
+  if (!(await isReachable(config))) {
+    console.log(c.yellow(`The node is not reachable at ${url(config)}. Start it first: ${c.cyan(config.service ? "bivy restart" : "bivy start")}`));
+    process.exitCode = EXIT.unavailable;
+    return;
+  }
+  const saved = (() => { try { return JSON.parse(fs.readFileSync(tailscaleConfigPath, "utf8")); } catch { return null; } })();
+
+  if (verb === "pair") {
+    if (!saved) { console.log(`Tailscale access is off. Turn it on with ${c.cyan("bivy tailscale")}.`); process.exitCode = EXIT.failed; return; }
+    await printPairLink(config);
+    return;
+  }
+  if (verb === "devices") {
+    // The CLI and loopback web client mint their own tokens on this machine; list them as a count.
+    const all = (await localApi(config, "/api/auth/devices")) ?? [];
+    const devices = all.filter((device) => !LOCAL_TOKEN_NAMES.includes(device.name));
+    for (const device of devices) console.log(`${c.cyan(device.id)}  ${device.name}${device.createdAt ? c.dim(`  paired ${device.createdAt}`) : ""}`);
+    if (!devices.length) console.log("No paired devices.");
+    if (all.length > devices.length) console.log(c.dim(`(+${all.length - devices.length} tokens used on this machine by the CLI)`));
+    return;
+  }
+  if (verb === "revoke") {
+    const id = args[1];
+    if (!id) { console.log("Usage: bivy tailscale revoke <id>  (ids from 'bivy tailscale devices')"); process.exitCode = EXIT.usage; return; }
+    const res = await fetch(`${url(config)}/api/auth/devices/${encodeURIComponent(id)}`, { method: "DELETE", headers: { authorization: `Bearer ${await localDeviceToken(config)}` } });
+    if (!res.ok) { console.log(c.yellow(`No device ${id}.`)); process.exitCode = EXIT.notFound; return; }
+    console.log(`${c.green("✓")} Revoked ${id}.`);
+    return;
+  }
+  if (verb === "status") {
+    console.log(saved ? `${c.green("✓")} Served on ${c.cyan(`https://${saved.hostname}`)} (tailnet only) → 127.0.0.1:${saved.port}` : `Tailscale access is off. Turn it on with ${c.cyan("bivy tailscale")}.`);
+    return;
+  }
+  if (verb === "off") {
+    if (saved) {
+      const state = serveState(runTailscale(["serve", "status", "--json"])?.stdout, saved.hostname);
+      if (state.target === `http://127.0.0.1:${saved.port}`) runTailscale(serveOffArgs());
+    }
+    fs.rmSync(tailscaleConfigPath, { force: true });
+    await localApi(config, "/api/direct/reload", { method: "POST", body: "{}" });
+    console.log(`${c.green("✓")} Bivy is no longer served over Tailscale. Paired devices keep their tokens; see them with 'bivy tailscale devices' and revoke with 'bivy tailscale revoke <id>'.`);
+    return;
+  }
+
+  const status = runTailscale(["status", "--json"]);
+  if (!status) {
+    console.log(`${c.yellow("Tailscale isn't installed.")} Install it from ${c.cyan("https://tailscale.com/download")} (Arch: ${c.cyan("sudo pacman -S tailscale && sudo systemctl enable --now tailscaled")}), sign in with ${c.cyan("sudo tailscale up")}, then run ${c.cyan("bivy tailscale")} again.`);
+    process.exitCode = EXIT.unavailable;
+    return;
+  }
+  const { running, hostname } = parseTailscaleStatus(status.stdout);
+  if (!running || !hostname) {
+    console.log(`${c.yellow("Tailscale isn't connected.")} Sign in with ${c.cyan("sudo tailscale up")}, then run ${c.cyan("bivy tailscale")} again.`);
+    process.exitCode = EXIT.unavailable;
+    return;
+  }
+  const port = saved?.port ?? await findAvailablePort(config.port + 2, "127.0.0.1");
+  const conflict = serveConflict(serveState(runTailscale(["serve", "status", "--json"])?.stdout, hostname), port);
+  if (conflict) {
+    console.log(c.yellow(conflict));
+    process.exitCode = EXIT.conflict;
+    return;
+  }
+  fs.writeFileSync(tailscaleConfigPath, `${JSON.stringify({ port, hostname }, null, 2)}\n`, { mode: 0o600 });
+  const reload = await localApi(config, "/api/direct/reload", { method: "POST", body: "{}" });
+  const served = runTailscale(serveOnArgs(port));
+  if (!served?.ok) {
+    fs.rmSync(tailscaleConfigPath, { force: true });
+    await localApi(config, "/api/direct/reload", { method: "POST", body: "{}" }).catch(() => {});
+    console.error(c.red(`tailscale serve failed: ${(served?.stderr || served?.stdout || "").trim()}`));
+    const hint = serveFailureHint(served?.stderr);
+    if (hint) console.log(hint);
+    process.exitCode = EXIT.failed;
+    return;
+  }
+  console.log(c.bold(c.green(`\n  Bivy is on https://${hostname}\n`)));
+  console.log(c.dim("  Only devices on your tailnet can reach it. Pair each one once with a link from 'bivy tailscale pair'."));
+  if (!reload?.webApp) console.log(c.yellow("  This install has no built web app, so the address serves the API only. Run 'pnpm run build:web' in a source checkout."));
+  console.log("");
+  await printPairLink(config);
+}
+
 function printUninstallHelp() {
   console.log(`
 ${c.bold("bivy uninstall")} — remove Bivy and all its data from this machine
@@ -6268,6 +6387,9 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
     case "link":
       await cmdLinkPhone(args);
       break;
+    case "tailscale":
+      await cmdTailscale(args);
+      break;
     case "relay:setup":
       await cmdRelaySetup(args);
       break;

package/bin/cli-commands.mjs

@@ -48,8 +48,8 @@ export const COMMANDS = [
     tools: [{ name: "notify_user", description: "Send the user a message: a card in the chat, and a push to their phone when nobody has the app open (the push names the session, not the text). Use it when long work finishes, you are blocked, or something needs their attention. At most one push a minute per session.", input: { message: { type: "string", description: "What to tell the user.", required: true }, urgent: { type: "boolean", description: "Push even while the user has the app open." } }, argv: ["notify", { arg: "message" }, { 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: "suggest", group: "session", scope: "session", json: true, usage: 'suggest "<task>" [--title "label"]', summary: "Propose a task the user can start in one tap",
-    tools: [{ name: "suggest_task", description: "Propose a next step the user can start in one tap, in this session or in a parallel one with its own copy of the project. Write the task as a complete instruction with paths relative to the project root. Post one per idea instead of listing them.", input: { task: { type: "string", description: "The complete instruction.", required: true }, title: { type: "string", description: "A short label for the card." } }, argv: ["suggest", { arg: "task" }, { flag: "--title", from: "title" }] }] },
+  { name: "suggest", group: "session", scope: "session", json: true, usage: 'suggest "<task>" [--title "label"] [--run here|subagents|new]', summary: "Propose a task the user can start in one tap",
+    tools: [{ name: "suggest_task", description: "Propose a next step the user can start in one tap: in this session, through your sub-agents, or in a parallel session with its own copy of the project. Write the task as a complete instruction with paths relative to the project root. Post one per idea instead of listing them.", input: { task: { type: "string", description: "The complete instruction.", required: true }, title: { type: "string", description: "A short label for the card." }, run: { type: "string", enum: ["here", "subagents", "new"], description: "Where you recommend running it: here (builds on this conversation), subagents (independent tasks you can split across your own sub-agents; only if you have them), or new (bigger independent work in its own session). Defaults: here for one card, new for several." } }, argv: ["suggest", { arg: "task" }, { flag: "--title", from: "title" }, { flag: "--run", from: "run" }] }] },
   { 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"],
     tools: [
       { name: "app_publish", description: "Give the user a live preview of something with a UI, from an app manifest file (web server port, static build, terminal, or desktop app). Run `bivy app --help` for the manifest format.", input: { manifest_path: { type: "string", description: "Path to the manifest JSON.", required: true } }, argv: ["app", "publish", { arg: "manifest_path" }] },
@@ -103,6 +103,7 @@ export const COMMANDS = [
   { name: "token", group: "node", scope: "node", usage: "token", summary: "Print a device token for this node" },
   { name: "open", group: "node", scope: "node", usage: "open", summary: "Open the remote web app" },
   { name: "link", group: "node", scope: "node", usage: "link", summary: "Show a web app link as a QR code in the terminal" },
+  { name: "tailscale", group: "node", scope: "node", usage: "tailscale [on|pair|status|devices|revoke|off]", summary: "Reach this machine over Tailscale, with no server in between", subcommands: ["on", "pair", "status", "devices", "revoke", "off"] },
   { name: "relay:setup", group: "node", scope: "node", usage: "relay:setup", summary: "Enable secure remote web app access" },
   { name: "uninstall", group: "node", scope: "node", usage: "uninstall [--keep-sessions] [--dry-run]", summary: "Remove Bivy and all its data" },
 

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

@@ -28,9 +28,18 @@ Ask only when you can't reasonably decide yourself.
 
     bivy suggest "Add a GET /version endpoint that returns the package version." --title "Add /version"
 
-Each suggestion is a card the user can start in one tap, here or in a parallel
-session with its own copy of the project. Write it as a complete instruction with
-paths relative to the project root. Post one per idea instead of a bulleted list.
+Each suggestion is a card the user can start in one tap: here, through your
+sub-agents, or in a parallel session with its own copy of the project. Write it as
+a complete instruction with paths relative to the project root. Post one per idea
+instead of a bulleted list.
+
+`--run` picks the card's main button; the others stay one tap away:
+
+| `--run` | When |
+|---|---|
+| `here` | It builds on this conversation, or it's small. Default for a single card. |
+| `subagents` | Independent tasks you can split across your own sub-agents and report back on. Only if you have sub-agents. |
+| `new` | Bigger independent work the user will want to follow, review or merge on its own. Default for several cards. |
 
 ## Is anyone there?
 

package/bin/tailscale.mjs

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Pure helpers for `bivy tailscale`: read `tailscale status --json` and
+// `tailscale serve status --json`, and build the `tailscale serve` arguments.
+// No process spawning here, so each decision is testable on its own.
+
+/** The one HTTPS port Bivy claims on the machine's tailnet name. */
+export const SERVE_HTTPS_PORT = 443;
+
+/** `{ running, hostname }` from `tailscale status --json` output. */
+export function parseTailscaleStatus(text) {
+  let status;
+  try { status = JSON.parse(text); } catch { return { running: false, hostname: null }; }
+  const hostname = String(status?.Self?.DNSName ?? "").replace(/\.$/, "") || null;
+  return { running: status?.BackendState === "Running", hostname };
+}
+
+/** Where `tailscale serve` should send the machine's HTTPS traffic. */
+export function serveTarget(port) {
+  return `http://127.0.0.1:${port}`;
+}
+
+export function serveOnArgs(port) {
+  return ["serve", "--bg", `--https=${SERVE_HTTPS_PORT}`, serveTarget(port)];
+}
+
+export function serveOffArgs() {
+  return ["serve", `--https=${SERVE_HTTPS_PORT}`, "off"];
+}
+
+/**
+ * What already sits on `<hostname>:443`, from `tailscale serve status --json`:
+ * `funnel` when it is public (Tailscale Funnel), and the proxy target of `/`
+ * when something is served there. Bivy refuses to share a Funnel'd name, and
+ * refuses to replace a target that isn't its own.
+ */
+export function serveState(text, hostname) {
+  let status;
+  try { status = JSON.parse(text || "{}"); } catch { status = {}; }
+  const key = `${hostname}:${SERVE_HTTPS_PORT}`;
+  const handlers = status?.Web?.[key]?.Handlers ?? {};
+  return {
+    funnel: status?.AllowFunnel?.[key] === true,
+    target: typeof handlers["/"]?.Proxy === "string" ? handlers["/"].Proxy : null,
+    otherPaths: Object.keys(handlers).filter((p) => p !== "/"),
+  };
+}
+
+/** Why `bivy tailscale` can't take `<hostname>:443`, or null when it can. */
+export function serveConflict(state, port) {
+  if (state.funnel) return "Tailscale Funnel is on for this machine's HTTPS name, which would put Bivy on the public internet. Turn it off first: tailscale funnel reset";
+  if (state.target && state.target !== serveTarget(port)) return `tailscale serve already sends https:// on this machine to ${state.target}. Remove it first: tailscale serve --https=${SERVE_HTTPS_PORT} off`;
+  if (state.otherPaths.length) return `tailscale serve already has paths on this machine's HTTPS name (${state.otherPaths.join(", ")}). Remove them first: tailscale serve --https=${SERVE_HTTPS_PORT} off`;
+  return null;
+}
+
+/** A one-line hint for a failed `tailscale serve`, from its stderr. */
+export function serveFailureHint(stderr) {
+  const text = String(stderr ?? "");
+  if (/access denied|permission denied|must be root|operator/i.test(text)) return "Let your user manage Tailscale once: sudo tailscale set --operator=$USER";
+  if (/https.*not enabled|enable https|certificates/i.test(text)) return "Turn on HTTPS certificates for your tailnet (admin console → DNS → HTTPS Certificates), then run this again.";
+  return null;
+}

package/dist/agent-instructions.js

@@ -39,9 +39,12 @@ export const BIVY_AGENT_NOTE = [
         "can check your work; `bivy app present` tells the user a visible change is ready to look at. " +
         "`bivy app --help` has the details.",
     "- Proposing tasks the user could hand you (next steps, ideas, options): post each with " +
-        '`bivy suggest "<complete instruction>" [--title "short label"]` instead of only listing them. The user can ' +
-        "start each in one tap, in this session or in a parallel one that works in its own copy of the project, so " +
-        "write it to stand on its own, with paths relative to the project root.",
+        '`bivy suggest "<complete instruction>" [--title "short label"] [--run here|subagents|new]` instead of only ' +
+        "listing them. The user can start each in one tap, in this session, through your sub-agents, or in a parallel " +
+        "one that works in its own copy of the project, so write it to stand on its own, with paths relative to the " +
+        "project root. `--run` is the one you recommend: here when it builds on this conversation, subagents for " +
+        "independent tasks you can split and supervise (only if you have sub-agents), new for bigger work worth its " +
+        "own session.",
     "- When you finish long work, get blocked, or need the user to look at something: " +
         '`bivy notify "<message>"` (a chat card, plus a push to their phone when they are away). To ask and wait for ' +
         'an answer: `bivy ask "<question>" [--option A --option B]` prints their answer (or use your own ask-the-user tool).',

package/dist/apps/styles.css

@@ -3128,8 +3128,9 @@ p.setup-note .btn.link { min-height: 44px; margin-block: calc((1lh - 44px) / 2);
 .suggestion-title { margin: 0; font-size: var(--text-base); font-weight: var(--weight-semibold); overflow-wrap: anywhere; }
 .suggestion-text { margin: 0; color: var(--muted); font-size: var(--text-sm); white-space: pre-wrap; overflow-wrap: anywhere; display: -webkit-box; -webkit-line-clamp: 4; -webkit-box-orient: vertical; overflow: hidden; }
 .suggestion-actions { display: flex; flex-wrap: wrap; gap: var(--space-2); margin-top: var(--space-2); }
-.suggestion-all { display: flex; flex-direction: column; gap: var(--space-1); margin-top: var(--space-2); padding-top: var(--space-2); border-top: 1px solid var(--line); }
-.suggestion-all .suggestion-actions { margin-top: 0; }
+.suggestion-bar, .suggestion-all { display: flex; flex-direction: column; gap: var(--space-1); margin-top: var(--space-2); }
+.suggestion-all { padding-top: var(--space-2); border-top: 1px solid var(--line); }
+.suggestion-bar .suggestion-actions, .suggestion-all .suggestion-actions { margin-top: 0; }
 .suggestion-hint { margin: 0; color: var(--muted); font-size: var(--text-xs); }
 /* In a set, the title is the checkbox's label, so the whole line is the tap target. */
 .suggestion-pick { display: flex; align-items: flex-start; gap: var(--space-2); cursor: pointer; }

package/dist/auth.js

@@ -112,6 +112,18 @@ export function isLoopbackAddress(address) {
     const addr = address.replace(/^::ffff:/, "");
     return addr === "127.0.0.1" || addr === "::1" || addr === "localhost";
 }
+// Sockets accepted by a listener that fronts remote callers through a local
+// proxy (`tailscale serve` forwards tailnet traffic from 127.0.0.1). Their peer
+// address is loopback, but the caller is not, so they never get loopback trust.
+const remoteSockets = new WeakSet();
+/** Treat every connection `server` accepts as remote, whatever its peer address. */
+export function markRemoteListener(server) {
+    server.on("connection", (socket) => remoteSockets.add(socket));
+}
+/** True when a request physically arrived over loopback from a local caller. */
+export function isLoopbackRequest(req) {
+    return !!req.socket && !remoteSockets.has(req.socket) && isLoopbackAddress(req.socket.remoteAddress);
+}
 export function extractToken(headerValue) {
     if (!headerValue)
         return null;
@@ -141,7 +153,7 @@ export function tokenFromRequest(req) {
  * `/api/auth/bootstrap`) can rely on it even when the general bypass in
  * `isAuthorized` is off. */
 export function resolveAuth(identity, req) {
-    const loopback = isLoopbackAddress(req.socket?.remoteAddress);
+    const loopback = isLoopbackRequest(req);
     const deviceId = identity.verifyToken(tokenFromRequest(req));
     return { deviceId, loopback };
 }
@@ -160,7 +172,8 @@ export function isAuthorized(ctx) {
  * web client (?local=1), a LAN device browsing the node directly, or CLI/native
  * clients (no Origin).
  * Remote phones reach the node through the relay, which the node dials
- * *outbound* — those never arrive here as inbound upgrades. So we allow only
+ * *outbound* — those never arrive here as inbound upgrades — or over Tailscale
+ * on the `*.ts.net` name, which counts as local here. So we allow only
  * local/private hostnames and reject a public Host (rebinding) or public Origin
  * (cross-site). Escape hatches: BIVY_ALLOWED_HOSTS (comma-separated extra
  * hostnames, e.g. a reverse-proxy domain) and BIVY_ALLOW_ANY_ORIGIN=1.
@@ -272,7 +285,7 @@ export function authMiddleware(identity, sessionTokens) {
                 return;
             }
             sessionTokens.used?.(sessionId, call);
-            req.auth = { deviceId: null, loopback: isLoopbackAddress(req.socket?.remoteAddress), sessionId };
+            req.auth = { deviceId: null, loopback: isLoopbackRequest(req), sessionId };
             next();
             return;
         }

package/dist/pair-codes.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// One-time pairing codes for devices that reach the node directly (over
+// Tailscale). The owner mints a code on the machine (`bivy tailscale pair`),
+// the phone opens `https://<machine>.ts.net/#pair=<code>` and trades the code
+// for a device token. Codes are single-use, short-lived and held only in
+// memory, so a restart invalidates every outstanding one.
+import { createHash, randomBytes } from "node:crypto";
+export const PAIR_CODE_TTL_MS = 10 * 60 * 1000;
+const digest = (code) => createHash("sha256").update(code).digest("hex");
+export class PairCodes {
+    now;
+    // Keyed by the code's hash, so a lookup never compares secrets directly.
+    pending = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    issue(ttlMs = PAIR_CODE_TTL_MS) {
+        this.sweep();
+        const code = randomBytes(24).toString("base64url");
+        const expiresAt = this.now() + ttlMs;
+        this.pending.set(digest(code), expiresAt);
+        return { code, expiresAt };
+    }
+    /** True once per valid, unexpired code; the code is spent either way. */
+    redeem(code) {
+        if (!code)
+            return false;
+        const key = digest(code);
+        const expiresAt = this.pending.get(key);
+        this.pending.delete(key);
+        return expiresAt !== undefined && expiresAt > this.now();
+    }
+    sweep() {
+        const now = this.now();
+        for (const [key, expiresAt] of this.pending)
+            if (expiresAt <= now)
+                this.pending.delete(key);
+    }
+}

package/dist/remote/direct.js

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Direct access over Tailscale: no control plane, no relay. `bivy tailscale`
+// writes `<data-dir>/tailscale.json` and points `tailscale serve` (HTTPS on the
+// machine's ts.net name, tailnet only) at a loopback port; the node opens that
+// port as its direct listener. Every connection on it is treated as remote, so
+// callers need a device token, which a phone gets by redeeming a pairing code.
+import fs from "node:fs";
+import path from "node:path";
+export const DIRECT_CONFIG_FILE = "tailscale.json";
+export function loadDirectListenerConfig(appDir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(appDir, DIRECT_CONFIG_FILE), "utf8"));
+        const port = Number(raw.port);
+        if (!Number.isInteger(port) || port <= 0 || port > 65535)
+            return null;
+        return { port, hostname: typeof raw.hostname === "string" && raw.hostname ? raw.hostname : undefined };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/remote/index.js

@@ -12,3 +12,4 @@
 // promote to a standalone `@bivy/remote` npm package.
 export { RelayConnector, loadRelayConfig } from "./relay-client.js";
 export { soloCredentials, buildDialUrl } from "./solo.js";
+export { loadDirectListenerConfig, DIRECT_CONFIG_FILE } from "./direct.js";

package/dist/server.js

@@ -74,7 +74,7 @@ import { exportProviderAuth, exportAccountApiKeys, exportAccountOAuthCredentials
 import { listProviders } from "./runtime/provider-catalog.js";
 import { exportLocalModels, importLocalModels } from "./runtime/local-model-store.js";
 import { sessionLikeFields } from "./session/start-like.js";
-import { MAX_SUGGESTION_TEXT, MAX_SUGGESTION_TITLE, isTaskSuggestion } from "./session/suggestions.js";
+import { MAX_SUGGESTION_TEXT, MAX_SUGGESTION_TITLE, SUGGESTION_RUNS, isTaskSuggestion } from "./session/suggestions.js";
 import { BIVY_AGENT_NOTE, mergeSyncedAgentInstructions, readAgentInstructions, sessionInstructions, writeAgentInstructions, MAX_AGENT_INSTRUCTIONS_BYTES } from "./agent-instructions.js";
 import { execEphemeralRequest } from "./ephemeral-exec.js";
 import { ApprovalManager } from "./approval.js";
@@ -84,8 +84,11 @@ import { canOpenBrowser, openBrowser } from "./browser-open.js";
 import { openOAuthLoginOnNode } from "./runtime/oauth/oauth-node-open.js";
 import { collectNodeStats } from "./node-stats.js";
 import { SessionEventCoalescer } from "./session-event-coalescer.js";
-import { authMiddleware, resolveAuth, isAuthorized, requestOriginAllowed } from "./auth.js";
-import { RelayConnector, loadRelayConfig, soloCredentials } from "./remote/index.js";
+import { authMiddleware, resolveAuth, isAuthorized, requestOriginAllowed, markRemoteListener } from "./auth.js";
+import { PairCodes } from "./pair-codes.js";
+import http from "node:http";
+import { webAppDirs, webAppRouter } from "./web-app.js";
+import { RelayConnector, loadRelayConfig, loadDirectListenerConfig, soloCredentials } from "./remote/index.js";
 import { readEphemeralTeardownConfig, shouldSelfTeardown, snapshotsDurableForTeardown, performSelfTeardown } from "./ephemeral-teardown.js";
 import { buildSessionSnapshot, applySessionSnapshot } from "./session/snapshot.js";
 import { clearTurnActivity } from "./session/turn-activity.js";
@@ -1070,9 +1073,16 @@ const accessDevices = createAccessDeviceController({
     create: (name) => identity.createDevice(name),
     revoke: (id) => identity.revokeDevice(id),
     onCreated: (device) => broadcast({ type: "device.created", device }),
-    onRevoked: (id) => broadcast({ type: "device.revoked", id }),
+    onRevoked: (id) => {
+        broadcast({ type: "device.revoked", id });
+        // A revoked token loses its open sockets now, not at its next reconnect.
+        for (const socket of clients)
+            if (socketDeviceIds.get(socket) === id)
+                socket.close(1008, "Unauthorized");
+    },
 });
 const clients = new Set();
+const socketDeviceIds = new WeakMap();
 const commandProcesses = new Map();
 const oauthLogins = new Map();
 // A browser-initiated subscription login parks the node on `manualCodePromise`
@@ -9337,7 +9347,8 @@ app.use((_req, res, next) => {
 // (OAuth callback, GitHub App manifest). It does NOT host the web UI — the
 // React/Vite PWA (@bivy/web) is served exclusively by the hosted or self-hosted
 // control plane. `/` returns a small informational stub for anyone who points a
-// browser straight at the node.
+// browser straight at the node. The one exception is the direct listener for
+// `bivy tailscale` (below), which has no control plane and serves the app itself.
 app.get("/", (_req, res) => {
     res.setHeader("Cache-Control", "no-store, max-age=0");
     res
@@ -9447,6 +9458,20 @@ app.post("/api/auth/bootstrap", sensitiveRateLimiter, (req, res) => {
     const { device, token } = accessDevices.create(name);
     res.json({ ok: true, device, token });
 });
+// Pairing a device that reaches the node directly (Tailscale): trade a one-time
+// code minted on this machine for a device token. Registered before the auth
+// middleware because the caller has no token yet; the code is the credential.
+const pairCodes = new PairCodes();
+app.post("/api/auth/pair", sensitiveRateLimiter, (req, res) => {
+    if (!requestOriginAllowed(req))
+        return res.status(403).json({ error: "Forbidden origin" });
+    if (!pairCodes.redeem(String(req.body?.code ?? ""))) {
+        return res.status(401).json({ error: "This pairing link is used or expired. Run 'bivy tailscale pair' on your machine for a new one." });
+    }
+    const name = String(req.body?.name ?? "").trim().slice(0, 80) || "Paired device";
+    const { device, token } = accessDevices.create(name);
+    res.json({ ok: true, device, token });
+});
 // All other /api routes require auth (loopback may bypass, per config and host
 // — see loopbackAllowed()/isMultiUserHost() in src/auth.ts).
 app.use("/api", authMiddleware(identity, {
@@ -9457,6 +9482,23 @@ app.use("/api", authMiddleware(identity, {
     used: (sessionId, call) => { if (call.method !== "GET")
         auditLog.record({ kind: "agent.call", session: sessionId, tool: `${call.method} ${call.path}` }); },
 }));
+// Mint a pairing code for a direct (Tailscale) device. Only callers already
+// trusted by this node get one: the owner's CLI, or an already-paired device.
+app.post("/api/auth/pair-codes", (_req, res) => {
+    const direct = loadDirectListenerConfig(appDir);
+    const { code, expiresAt } = pairCodes.issue();
+    const url = direct?.hostname ? `https://${direct.hostname}/#pair=${code}` : undefined;
+    res.json({ ok: true, code, expiresAt, url });
+});
+// Start, move or stop the direct listener after `bivy tailscale` changes it.
+app.post("/api/direct/reload", async (_req, res, next) => {
+    try {
+        res.json({ ok: true, ...(await reloadDirectListener()) });
+    }
+    catch (error) {
+        next(error);
+    }
+});
 // Reload relay.json without forcing the user to restart the whole node. This is
 // used by `bivy relay:setup` after it enrolls the node.
 app.post("/api/relay/reload", (_req, res) => {
@@ -11666,16 +11708,18 @@ app.get("/api/session/:id/automations/apply/:proposalId", (req, res) => {
     res.json(proposal);
 });
 // `bivy suggest "<task>"`: the agent proposes a task the user can start in one
-// tap, here or in a parallel session (see packages/web SuggestionCard).
+// tap, here, through this agent's sub-agents, or in a parallel session; `run`
+// is the one the agent recommends (see packages/web SuggestionCard).
 app.post("/api/session/:id/suggest", (req, res) => {
     const record = openSessions.get(String(req.params.id));
     if (!record)
         return res.status(404).json({ error: "Session not found" });
     const text = typeof req.body?.text === "string" ? req.body.text.trim() : "";
     const title = typeof req.body?.title === "string" && req.body.title.trim() ? req.body.title.trim() : undefined;
-    const suggestion = { id: `suggestion-${randomBytes(8).toString("hex")}`, text, ...(title ? { title } : {}) };
+    const run = req.body?.run || undefined;
+    const suggestion = { id: `suggestion-${randomBytes(8).toString("hex")}`, text, ...(title ? { title } : {}), ...(run ? { run } : {}) };
     if (!isTaskSuggestion(suggestion))
-        return res.status(400).json({ error: `A suggestion needs text (up to ${MAX_SUGGESTION_TEXT} characters) and an optional title (up to ${MAX_SUGGESTION_TITLE}).` });
+        return res.status(400).json({ error: `A suggestion needs text (up to ${MAX_SUGGESTION_TEXT} characters), an optional title (up to ${MAX_SUGGESTION_TITLE}) and an optional run (${SUGGESTION_RUNS.join(", ")}).` });
     eventLog.appendSuggestion(record.id, { afterMessageCount: record.session.getMessages().length, suggestion });
     broadcast(stampSessionEvent({ type: "session.event", sessionId: record.id, event: { type: "suggestion", id: suggestion.id, suggestion } }));
     res.json({ ok: true, id: suggestion.id });
@@ -12005,6 +12049,7 @@ const server = app.listen(port, host, async () => {
     console.log(`Agent data dir: ${piDir}`);
     console.log(`Workspace: ${defaultWorkspace}`);
     startRelayIfConfigured();
+    void reloadDirectListener().catch((error) => console.error("[direct] Could not start the direct listener:", error instanceof Error ? error.message : error));
     void syncAgentBridges().catch((error) => console.warn("[bridges] Could not install agent bridges; they will install on first use:", error instanceof Error ? error.message : error));
     if (appGateway) {
         appGateway.server.on("error", (error) => { console.error("[apps] Preview gateway could not start:", error); shutdown("preview gateway failure"); });
@@ -12071,6 +12116,46 @@ server.on("error", (error) => {
     process.exit(1);
 });
 const wss = new WebSocketServer({ server, path: "/ws" });
+// Direct listener (`bivy tailscale`): the same API and WebSocket, plus the web
+// app, on a loopback port `tailscale serve` exposes to the tailnet over HTTPS.
+// markRemoteListener keeps its proxied, loopback-looking connections from ever
+// getting loopback trust; every caller needs a device token.
+const directWebApp = webAppRouter(webAppDirs(repoRoot));
+let directListener = null;
+async function reloadDirectListener() {
+    const config = loadDirectListenerConfig(appDir);
+    if (directListener && directListener.port !== config?.port) {
+        const previous = directListener;
+        directListener = null;
+        for (const client of previous.wss.clients)
+            client.terminate();
+        previous.wss.close();
+        previous.server.closeAllConnections();
+        await new Promise((resolve) => previous.server.close(() => resolve()));
+    }
+    if (config && !directListener) {
+        const directApp = express();
+        directApp.disable("x-powered-by");
+        if (directWebApp)
+            directApp.use(directWebApp);
+        directApp.use(app);
+        const listener = http.createServer(directApp);
+        markRemoteListener(listener);
+        const directWss = new WebSocketServer({ server: listener, path: "/ws" });
+        directWss.on("connection", (socket, req) => wss.emit("connection", socket, req));
+        await new Promise((resolve, reject) => {
+            listener.once("error", reject);
+            listener.listen(config.port, "127.0.0.1", () => {
+                listener.off("error", reject);
+                resolve();
+            });
+        });
+        listener.on("error", (error) => console.error("[direct] Listener error:", error));
+        directListener = { port: config.port, server: listener, wss: directWss };
+        console.log(`[direct] Listening on 127.0.0.1:${config.port}${config.hostname ? ` for https://${config.hostname}` : ""}${directWebApp ? "" : " (web app not built; API only)"}`);
+    }
+    return { enabled: Boolean(directListener), port: directListener?.port, webApp: Boolean(directWebApp) };
+}
 wss.on("connection", (socket, req) => {
     // Reject cross-origin / DNS-rebinding upgrades before auth: loopback bypasses
     // auth by default, so a page the user merely visited could otherwise open a
@@ -12079,11 +12164,14 @@ wss.on("connection", (socket, req) => {
         socket.close(1008, "Forbidden origin");
         return;
     }
-    if (!isAuthorized(resolveAuth(identity, req))) {
+    const socketAuth = resolveAuth(identity, req);
+    if (!isAuthorized(socketAuth)) {
         socket.close(1008, "Unauthorized");
         return;
     }
     clients.add(socket);
+    if (socketAuth.deviceId)
+        socketDeviceIds.set(socket, socketAuth.deviceId);
     // Terminals opened on this socket; closed when the socket disconnects so a
     // dropped browser tab doesn't leak shells. Output is unicast to this socket.
     const ownedTerminals = new Set();