@bivy/bivy 0.19.4-staging.5 → 0.19.4-staging.7

package/README.md

@@ -4,22 +4,27 @@
 [![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-2b6cb0)](LICENSE)
 [![node](https://img.shields.io/badge/node-%E2%89%A520-2b6cb0)](https://nodejs.org)
 
-**Build, try, and review apps from your phone. Your coding agent and dev
-environment stay on your own machines.**
-
-Bivy is an open-source remote development environment built around coding
-agents. Ask for a change, try the running app, and point to or draw on what
-needs fixing. Send that feedback to the agent and try again—all in the same
-session, without going back to your computer.
-
-Live previews bring your app to your phone or browser without deploying it to
-Render, building a Docker image, or setting up a separate preview server.
-Share a preview link so someone else can try it and leave notes, too.
-
-Keep Claude Code, Codex, Pi, OpenCode, or another supported agent. Keep your
-repos, tools, databases, and development environment. Bivy connects them to
-chat, a terminal, app previews, and code review wherever you are. Start work
-yourself, or let an issue, CI failure, message, schedule, or webhook start it.
+**Local coding agents that show their work. Anywhere.**
+
+Bivy is the open-source workspace for coding agents. It runs Claude Code, Codex,
+Pi, OpenCode and other agents on your own machine. Reach them from a browser or
+your phone, with the live session, its terminal, its approvals, and the app
+they're building right in the chat. Try it, mark what's wrong, and send it back.
+
+Bivy is not another coding agent and not a cloud development machine. The agent
+stays local and does the coding with your model provider. Your repos, tools,
+databases, and services stay where they are. Bivy gives you remote access to all
+of it, plus live previews, automations, and review.
+
+- **Live previews.** The running app beside the chat. Mark it, send it back,
+  share it with someone who has no Bivy account.
+- **Automations.** GitHub issues, failed CI, Linear, Slack, schedules, and
+  webhooks start the work. It comes back as a preview link or a pull request.
+- **Any agent.** Hit a usage limit? Fork the session to another agent, or let
+  Bivy retry when the limit resets.
+- **Your machine, anywhere.** Start at your desk, pick the session up on your
+  phone. The machine dials out, so there are no ports to open, and session
+  traffic is end-to-end encrypted.
 
 **[Start free on Bivy Cloud](https://app.bivy.sh)** ·
 **[Quickstart](docs/quickstart.md)** ·
@@ -47,30 +52,34 @@ agents. Connect a Mac, Linux computer, or existing server and bring your own
 agent subscription, model API key, or local model. You can also self-host the
 entire remote-access stack.
 
-> **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the
+> **Bivy is 0.x software.** Claude Code, Codex, Pi, OpenCode, and Grok are the
 > release-tested paths. Credential sync, resume, handoffs, approvals, and
 > sandboxing depend on the runtime. See the
 > [runtime support matrix](docs/runtime-support-matrix.md).
 
-## Build → preview → mark up → iterate
+## Don't just read the diff. Try the app.
 
-Remote chat lets you ask an agent for a change. Bivy also lets you **use what
-it built and show it what to fix**, without a separate deployment step.
+Bivy lets you **use what the agent built and show it what to fix**, without a
+separate deployment step.
 
 1. **Ask for a change.** The agent works in your repo with your existing tools
    and local services.
-2. **Try the app.** Open a live preview from the session. Use the running app,
-   not just a screenshot of what the agent says it finished. Bivy can discover
-   dev servers running in the session workspace; tap **Preview** to open one.
-3. **Mark up what needs work.** Point at an element or circle and draw on the
-   preview. Add a note, then send the draft to the agent with the element and
-   page context. Marked-up screenshots and before/after comparison are available
-   when agent screenshots are enabled.
-4. **Iterate and review.** Try the next version, inspect the diff, review checks,
-   and decide when the work is ready—not just when the agent stops.
-5. **Bring someone else into the review.** Copy a public preview link so they
-   can use the app without a Bivy account and leave notes on specific elements.
-   Bring their notes into the session when you're ready to act on them.
+2. **Try the app.** Bivy finds the dev server the agent starts and opens it
+   beside the chat: web apps, terminals, and desktop apps. Use the running app,
+   not a screenshot of what the agent says it finished.
+3. **Mark what needs work.** Press and hold anything in the preview to mark it,
+   or drag to circle it, then say what you want. **Mark another** keeps
+   separate notes separate. The marks go to the agent with the element and page
+   context. No screenshots to paste.
+4. **Follow each note.** Every mark stays in the chat as a pin that resolves
+   itself: **Changed** when a later run changes what you marked, **Element
+   gone** when it leaves the page, **Done** when you say so.
+5. **Review the next version.** A new version waits on the preview pill instead
+   of reloading under you. Take it when you're ready, compare before and after,
+   inspect the diff and checks, and decide when the work is done.
+6. **Get a second opinion.** Share a preview link for 1 hour, 1 day, or 7 days.
+   Teammates and clients try the running app and leave notes without a Bivy
+   account. Make it view-only, or **Stop sharing** to end every link at once.
 
 On Bivy Cloud, preview delivery is built in: no per-app domains, certificates,
 public ports, or tunnels to configure. Self-hosters configure preview delivery
@@ -79,27 +88,13 @@ build or dev-server setup, and **the machine serving it must stay awake and
 online**. These are development previews, not production hosting.
 
 **Share deliberately:** anyone with a preview link can use that app, including
-its live backend. Links expire after 24 hours and can be revoked sooner.
+its live backend, until the link expires or you stop sharing.
 Reviewer notes aren't sent to the agent automatically; you send them or explicitly
 allow agent access. Preview traffic uses HTTPS through the preview relay, not
 session end-to-end encryption; the relay operator can see it.
 
 [App previews, visual feedback, and sharing →](docs/apps.md)
 
-## Your agents and machines, one workspace
-
-| Capability | What it means for you |
-|---|---|
-| **One workspace, multiple agents** | Use different agents and models for different tasks without maintaining a separate workflow for each. |
-| **Your machines and environment** | Work beside your existing repos, dev servers, databases, private networks, toolchains, and GPUs. |
-| **Automations and triggers** | Let issues, failed CI, messages, schedules, and webhooks start work instead of copying requests into a chat. |
-| **Encrypted key and OAuth sync** | Reuse Bivy-managed provider credentials across enrolled machines and compatible runtimes, with less repeated setup. |
-| **Live sessions from anywhere** | Build and review from your phone, browser, or terminal; answer questions and approve supported actions in the same session. |
-| **Live app previews** | Try the running app without deploying it to a separate hosting service. |
-| **Visual feedback and sharing** | Point, draw, and send specific feedback to the agent; share a preview link for outside review. |
-| **Reviewable results** | Inspect the app, changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |
-| **Hosted convenience or self-hosting** | Use Bivy Cloud for managed remote access, or run the same open-source core yourself. |
-
 ## One workflow, from trigger to review
 
 ```text
@@ -131,34 +126,70 @@ creates runs when an event matches.
 Manual and automated work use the same kind of live session. You can join a run
 when it needs help rather than wait for a black-box job to finish.
 
-### Work in the environment you already have
+### Let events start the work
 
-A clean cloud sandbox isn't always enough. Your agent may need the database
-running on localhost, an uncommitted change, an internal API behind your VPN,
-or a model running on your GPU. Bivy runs the agent where those things already
-exist, subject to that machine's permissions and the runtime's protection.
+Automations turn recurring or incoming work into sessions you can join,
+supervise, and review. An agent picks the task up on your machine and posts
+back a preview link or a pull request, so you try the result where the task
+lives and reply in the same session. Choose the repository, machine, agent,
+model, approval mode, sandbox setting, and maximum attempts.
 
-Connect several machines to the same account: a laptop for interactive work,
-a Linux server for background jobs, or a GPU box for local inference. Choose
-the machine for each session or pin it in an automation. Repository runs can
-use isolated Git worktrees without rebuilding the whole development environment.
+| Trigger | Example workflow |
+|---|---|
+| **GitHub issues and mentions** | Label an issue `bivy` or `bivy/<machine>`, or mention your Bivy GitHub App, to work toward a pull request. |
+| **Failed CI** | Match a failed workflow, ask the agent to reproduce it, make a fix, and run the affected checks. |
+| **Linear** | Label an issue to start work without copying its description into an agent. |
+| **Slack** | Send a request from the conversation where the work came up. |
+| **Schedules** | Run a weekly dependency review, recurring maintenance, or a one-time task. |
+| **Signed webhooks** | Connect alerts, internal tools, or your own event sources. |
 
-**The execution machine must stay awake and online.** To close your laptop and
-leave work running, run the agent on a different, always-on machine.
+Configure automations in the app or version them with your repository in
+`.bivy/automations.yaml`:
 
-[Environment and multi-machine recipes →](docs/capability-recipes.md)
+```bash
+bivy automation init
+# Edit the generated definition for your repository and workflow.
+bivy automation validate
+bivy automation test --event .bivy/events/failed-ci.yaml  # supply a local event fixture
+bivy automation apply
+```
 
-### Use multiple agents, not multiple disconnected workflows
+Or delegate a one-off job without creating an automation:
 
-Run Claude Code for one task, Codex for another, and Pi or OpenCode where they
-fit. Bivy supplies the shared session, remote-access, automation, and review
-surfaces; your chosen agent still does the coding and uses your model provider.
+```bash
+bivy runs start "Review outdated dependencies and propose a small, tested update."
+bivy runs wait <id>
+```
+
+Runs keep routing and lifecycle evidence, check results, and output references
+in a reviewable Receipt. For unattended issue work, Bivy runs declared repository
+checks after the agent's turn; failed required checks fail the run even if the
+agent reports success. A completed process alone is not proof that the task
+succeeded.
 
+[Automation recipes →](docs/capability-recipes.md#let-events-start-runs) ·
+[Automations as code →](docs/automations-as-code.md) ·
+[Run outcomes and reliability limits →](docs/automation-runs.md)
+
+### Use every agent you pay for. Switch mid-task.
+
+Run Claude Code for one task, Codex for another, and Pi or OpenCode where they
+fit, side by side in one session list. Bivy supplies the shared session,
+remote-access, automation, and review surfaces; your chosen agent still does
+the coding and uses your model provider.
+
+- **Hit a usage limit? Keep going.** When a turn fails on a limit, fork the
+  session, with its code and conversation, to another agent and model, or let
+  Bivy retry when the limit resets (the provider has to report a reset time).
+- **Get a second opinion.** `bivy delegate` hands a task to another agent, on
+  the same machine or a different one, and brings back its answer, branch, and
+  PR. `--to codex,claude@linux` sends one task to several agents to compare.
 - Choose an agent and, where supported, a model for each session or run.
 - Import existing Claude Code and Codex sessions.
 - Fork or move work to another agent or machine when a different setup fits
   better. Continuation fidelity varies: some paths preserve native history,
-  while others replay portable turns or seed the destination with context.
+  while others replay portable turns or hand over a summary with the earlier
+  transcript as a local file.
 - Use agent-native logins, Bivy-managed credentials, or local inference.
   Bivy's custom OpenAI-compatible endpoint registry currently feeds Pi;
   other agents may need their own provider configuration.
@@ -199,48 +230,22 @@ hosted-provisioning custody grants are separate from ordinary encrypted sync.
 [Credentials guide →](docs/credentials-guide.md) ·
 [Key storage →](docs/key-management.md)
 
-### Let events start the work
-
-Automations turn recurring or incoming work into sessions you can join,
-supervise, and review. Choose the repository, machine, agent, model, approval
-mode, sandbox setting, and maximum attempts.
-
-| Trigger | Example workflow |
-|---|---|
-| **GitHub issues and mentions** | Label an issue `bivy` or `bivy/<machine>`, or mention your Bivy GitHub App, to work toward a pull request. |
-| **Failed CI** | Match a failed workflow, ask the agent to reproduce it, make a fix, and run the affected checks. |
-| **Linear** | Label an issue to start work without copying its description into an agent. |
-| **Slack** | Send a request from the conversation where the work came up. |
-| **Schedules** | Run a weekly dependency review, recurring maintenance, or a one-time task. |
-| **Signed webhooks** | Connect alerts, internal tools, or your own event sources. |
-
-Configure automations in the app or version them with your repository in
-`.bivy/automations.yaml`:
-
-```bash
-bivy automation init
-# Edit the generated definition for your repository and workflow.
-bivy automation validate
-bivy automation test --event .bivy/events/failed-ci.yaml  # supply a local event fixture
-bivy automation apply
-```
+### Work in the environment you already have
 
-Or delegate a one-off job without creating an automation:
+A clean cloud sandbox isn't always enough. Your agent may need the database
+running on localhost, an uncommitted change, an internal API behind your VPN,
+or a model running on your GPU. Bivy runs the agent where those things already
+exist, subject to that machine's permissions and the runtime's protection.
 
-```bash
-bivy runs start "Review outdated dependencies and propose a small, tested update."
-bivy runs wait <id>
-```
+Connect several machines to the same account: a laptop for interactive work,
+a Linux server for background jobs, or a GPU box for local inference. Choose
+the machine for each session or pin it in an automation. Repository runs can
+use isolated Git worktrees without rebuilding the whole development environment.
 
-Runs keep routing and lifecycle evidence, check results, and output references
-in a reviewable Receipt. For unattended issue work, Bivy runs declared repository
-checks after the agent's turn; failed required checks fail the run even if the
-agent reports success. A completed process alone is not proof that the task
-succeeded.
+**The execution machine must stay awake and online.** To close your laptop and
+leave work running, run the agent on a different, always-on machine.
 
-[Automation recipes →](docs/capability-recipes.md#let-events-start-runs) ·
-[Automations as code →](docs/automations-as-code.md) ·
-[Run outcomes and reliability limits →](docs/automation-runs.md)
+[Environment and multi-machine recipes →](docs/capability-recipes.md)
 
 ### Start at your desk. Continue anywhere.
 
@@ -269,6 +274,29 @@ in your browser; adding it to your home screen is optional.
 [Remote access →](docs/remote-access.md) ·
 [Voice, files, and terminal recipes →](docs/capability-recipes.md)
 
+### Agents can reach you, too
+
+Every session gets the `bivy` CLI, so any agent with a shell can talk back
+through the app, not only agents with their own built-in tools:
+
+```bash
+bivy notify "Tests are green, PR is up"     # chat card + phone push when you're away
+bivy ask "Ship to staging?" --option Yes --option No  # waits for your answer
+bivy attach report.png --caption "Before/after"       # show a file in the chat
+bivy suggest "Add a dark theme to settings"           # a next task you start in one tap
+bivy context --json                                   # session, workspace, machine, apps
+```
+
+`bivy help --json` lists every command, and with `BIVY_OUTPUT=json` failures
+come back as structured errors with distinct exit codes, so an agent can tell
+what went wrong and what to run next. `bivy guide` prints short playbooks for
+agents, and the same commands are served as MCP tools for agents that prefer
+them. Add your own standing instructions for
+every session in **Settings → Agent instructions**.
+
+[Commands for agents inside a session →](docs/cli-reference.md#inside-an-agent-session) ·
+[Agent instructions →](docs/agent-instructions.md)
+
 ## Get started
 
 ### Install
@@ -404,9 +432,9 @@ for the task, especially before enabling unattended work.
 
 ## Agents and everyday commands
 
-**Claude Code, Codex, Pi, and OpenCode are release-tested.** Additional adapters
-include Gemini CLI, Qwen Code, Goose, Aider, Cline, Crush, Cursor, GitHub Copilot,
-Grok, Amp, Auggie, Droid, Continue, Kilo Code, and Rovo Dev. Installation,
+**Claude Code, Codex, Pi, OpenCode, and Grok are release-tested.** Additional
+adapters include Gemini CLI, Qwen Code, Goose, Aider, Cline, Crush, Cursor, GitHub
+Copilot, Amp, Auggie, Droid, Continue, Kilo Code, and Rovo Dev. Installation,
 resume, model selection, and tool protection vary—see the
 [support matrix](docs/runtime-support-matrix.md) and [agent guides](docs/agents/README.md).
 

package/bin/bivy.mjs

@@ -511,7 +511,19 @@ function nativeAgentAuthDetected(choice) {
 }
 
 function url(config) {
-  return `http://localhost:${config.port}`;
+  // BIVY_NODE_URL: set by `bivy mcp-serve` for the CLI it runs, so tools reach
+  // the node that started the agent whatever data dir this process resolves.
+  const override = process.env.BIVY_NODE_URL?.trim().replace(/\/+$/, "");
+  return override || `http://localhost:${config.port}`;
+}
+
+// The credential for a request about `sessionId`: the agent's own session token
+// ($BIVY_SESSION_TOKEN) when it is that session, else a device token when this
+// user can mint one, else none (loopback on a single-user host needs none).
+async function sessionAuth(config, sessionId) {
+  const own = resolveAttachSessionId({ env: process.env });
+  if (process.env.BIVY_SESSION_TOKEN && sessionId && sessionId === own) return process.env.BIVY_SESSION_TOKEN;
+  try { return await localDeviceToken(config); } catch { return undefined; }
 }
 
 // The host the node will bind (mirrors src/server.ts). We probe on this same
@@ -2424,8 +2436,7 @@ async function cmdAttach(args = []) {
 // (loopback bypasses auth), but include one when available so multi-user
 // hosts work too.
 async function sessionPost(config, sessionId, action, body) {
-  let token;
-  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const token = await sessionAuth(config, sessionId);
   return fetch(`${url(config)}/api/session/${encodeURIComponent(sessionId)}/${action}`, {
     method: "POST",
     headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
@@ -2437,7 +2448,7 @@ async function sessionPost(config, sessionId, action, body) {
 function sessionHttpError(what, status, body) {
   const message = `${what} failed (${status}): ${body?.error || "unknown error"}`;
   if (status === 404) return { code: "session_not_found", message, hint: "The session must be open on this node.", next: "bivy context", exit: EXIT.notFound };
-  if (status === 401 || status === 403) return { code: "denied", message, exit: EXIT.denied };
+  if (status === 401 || status === 403) return { code: "denied", message, hint: "A session's token only reaches that session; run it from the session's own shell, or from a terminal signed in to this node.", exit: EXIT.denied };
   if (status === 400) return { code: "invalid", message, exit: EXIT.usage };
   return { code: "failed", message, exit: EXIT.failed };
 }
@@ -2472,8 +2483,7 @@ async function cmdContext(args = []) {
   let node = { session: null };
   if (sessionId) {
     const config = loadConfig();
-    let token;
-    try { token = await localDeviceToken(config); } catch { token = undefined; }
+    const token = await sessionAuth(config, sessionId);
     try {
       const res = await fetch(`${url(config)}/api/session/${encodeURIComponent(sessionId)}/context`, { headers: token ? { authorization: `Bearer ${token}` } : {} });
       const body = await res.json().catch(() => ({}));
@@ -2631,8 +2641,7 @@ answer later and 'bivy ask status <id>' checks without waiting.
   if (!Number.isFinite(timeout) || timeout < 1) return fail({ code: "usage", message: "--timeout takes seconds or a duration like 90s, 10m or 2h.", 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 });
-  let token;
-  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const token = await sessionAuth(config, sessionId);
   const base = `${url(config)}/api/session/${encodeURIComponent(sessionId)}/ask`;
   const call = async (suffix, body) => {
     const res = await fetch(`${base}${suffix}`, {
@@ -2686,11 +2695,10 @@ answer later and 'bivy ask status <id>' checks without waiting.
 
 // One JSON request to the local node for the commands below: starts the node if
 // needed and returns { status, body }, or fails in the shared error shape.
-async function nodeRequest(method, pathname, body, { json = false } = {}) {
+async function nodeRequest(method, pathname, body, { json = false, sessionId } = {}) {
   const config = loadConfig();
   if (!(await ensureNodeRunning(config))) return cliError({ code: "node_unreachable", message: `Could not reach the Bivy node at ${url(config)}.`, next: "bivy status", exit: EXIT.unavailable }, { json, paint: c.red });
-  let token;
-  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const token = await sessionAuth(config, sessionId);
   const res = await fetch(`${url(config)}${pathname}`, {
     method,
     headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
@@ -2719,7 +2727,7 @@ async function cmdFork(args = []) {
   const modelArg = parsed.one("--model");
   const slash = modelArg?.indexOf("/") ?? -1;
   const model = modelArg ? (slash > 0 ? { provider: modelArg.slice(0, slash), id: modelArg.slice(slash + 1) } : { provider: "", id: modelArg }) : undefined;
-  const { status, body } = await nodeRequest("POST", "/api/session/fork", { sessionId, ...(model ? { model } : {}) }, { json });
+  const { status, body } = await nodeRequest("POST", "/api/session/fork", { sessionId, ...(model ? { model } : {}) }, { json, sessionId });
   if (status === 404) return fail({ code: "node_outdated", message: "This node is older than 'bivy fork'.", next: "bivy update", exit: EXIT.unavailable });
   if (status >= 400 || body.error) return fail({ code: /not found/i.test(body.error ?? "") ? "session_not_found" : "failed", message: `Fork failed: ${body.error || `HTTP ${status}`}`, exit: /not found/i.test(body.error ?? "") ? EXIT.notFound : EXIT.failed });
   if (json) { console.log(JSON.stringify({ sessionId: body.sessionId, fidelity: body.fidelity, ...(body.missing?.length ? { missing: body.missing } : {}) })); return; }
@@ -2818,6 +2826,62 @@ async function cmdInstructions(args = []) {
   fail({ code: "usage", message: usage, exit: EXIT.usage });
 }
 
+// `bivy automation apply` inside an agent session: the node shows the user what
+// would change as an approval card and applies it only once they approve, with
+// this machine's account credential. `proposal <id> [--wait]` follows one.
+async function cmdAutomationProposal(args = []) {
+  const usage = "Usage (in an agent session): bivy automation apply [path] [--prune] [--timeout 90] [--json]\n       bivy automation proposal <id> [--wait] [--timeout 90] [--json]";
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(`${usage}\n\nInside an agent session, apply goes through this machine's approval mode: usually the user gets an approval card listing what would change and decides; with "never ask" it applies at once. The chat records what was applied. Waits up to --timeout seconds (default 90) for the answer; if it hasn't come, prints the proposal id to check later with 'bivy automation proposal <id> --wait'. The card stays open for 30 minutes. Validate and plan first ('bivy automation validate', 'plan').`);
+    return;
+  }
+  const json = wantsJson(args);
+  const fail = (error) => cliError(error, { json, paint: c.red });
+  const parsed = parseSessionArgs(args, ["--timeout", "--session"]);
+  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.", next: "bivy sessions --json", exit: EXIT.usage });
+  const timeout = parsed.one("--timeout") === undefined ? 90 : durationSeconds(parsed.one("--timeout"));
+  if (!Number.isFinite(timeout) || timeout < 0) return fail({ code: "usage", message: "--timeout takes seconds or a duration like 90s or 10m.", exit: EXIT.usage });
+  const base = `/api/session/${encodeURIComponent(sessionId)}/automations/apply`;
+  const [action, target] = parsed.positional;
+  let proposal;
+  if (action === "proposal") {
+    if (!target) return fail({ code: "usage", message: usage, exit: EXIT.usage });
+    const { status, body } = await nodeRequest("GET", `${base}/${encodeURIComponent(target)}`, undefined, { json, sessionId });
+    if (status >= 400) return fail({ code: status === 404 ? "not_found" : "failed", message: body.error || `HTTP ${status}`, exit: status === 404 ? EXIT.notFound : EXIT.failed });
+    proposal = body;
+    if (!parsed.has("--wait")) { if (json) console.log(JSON.stringify(proposal)); else console.log(`Proposal ${proposal.id}: ${proposal.status}`); return; }
+  } else {
+    const file = path.resolve(process.cwd(), target ?? ".bivy/automations.yaml");
+    const { status, body } = await nodeRequest("POST", base, { file, prune: parsed.has("--prune") }, { json, sessionId });
+    if (status === 404 && !body.error?.includes("Session")) return fail({ code: "node_outdated", message: "This node is older than proposing automations from a session.", next: "bivy update", exit: EXIT.unavailable });
+    if (status >= 400) return fail(sessionHttpError("Proposing the automations", status, body));
+    proposal = body;
+    if (!json) {
+      console.error(`Changes to apply (${proposal.file}):`);
+      for (const change of proposal.changes) console.error(`  ${change.action === "create" ? "+" : change.action === "remove" ? "-" : "~"} ${change.id}`);
+    }
+  }
+  const deadline = Date.now() + timeout * 1000;
+  let polls = 0;
+  while (proposal.status === "pending" && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, polls === 0 ? 500 : 2000));
+    if (polls++ === 1 && !json) console.error("Waiting for the user to approve them…");
+    const { status, body } = await nodeRequest("GET", `${base}/${encodeURIComponent(proposal.id)}`, undefined, { json, sessionId });
+    if (status < 400) proposal = body;
+  }
+  if (json) console.log(JSON.stringify(proposal));
+  if (proposal.status === "applied") { if (!json) console.log(proposal.output || "Applied."); return; }
+  if (proposal.status === "pending") {
+    if (!json) console.log(`The user hasn't answered yet. Check later with: bivy automation proposal ${proposal.id} --wait`);
+    process.exit(EXIT.timeout);
+  }
+  const message = { rejected: "The user declined these automation changes.", expired: "Nobody answered within 30 minutes; nothing was applied.", failed: `Approved, but applying failed: ${proposal.error || "unknown error"}` }[proposal.status] ?? proposal.status;
+  if (!json) console.error(message);
+  process.exit(proposal.status === "expired" ? EXIT.timeout : EXIT.failed);
+}
+
 // Cross-agent / cross-machine delegation (docs/agent-delegation.md): hand a
 // self-contained task from this session to another agent, optionally on another
 // account machine, and get its answer back. Agent-agnostic — any agent with a
@@ -2854,8 +2918,7 @@ async function cmdDelegate(args = []) {
   if (!sessionId) { console.error(c.red("No session id. Run inside an agent session ($BIVY_SESSION_ID) or pass --session <id>.")); process.exit(1); return; }
   const config = loadConfig();
   if (!(await ensureNodeRunning(config))) { console.error(c.red(`Could not reach the Bivy node at ${url(config)}.`)); process.exit(1); return; }
-  let token;
-  try { token = await localDeviceToken(config); } catch { token = undefined; }
+  const token = await sessionAuth(config, sessionId);
   const base = `${url(config)}/api/session/${encodeURIComponent(sessionId)}/delegated-runs`;
   const call = async (path, body) => {
     const res = await fetch(`${base}${path}`, {
@@ -3136,9 +3199,9 @@ async function appMenu(rest, { json = false } = {}) {
 async function appRequest(action, body, { print = true } = {}) {
   const config = loadConfig();
   if (!(await ensureNodeRunning(config))) throw new Error("Could not reach the Bivy node.");
-  const token = await localDeviceToken(config);
+  const token = await sessionAuth(config, body.sessionId);
   const response = await fetch(`${url(config)}/api/apps/${action}`, {
-    method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify(body),
+    method: "POST", headers: { ...(token ? { authorization: `Bearer ${token}` } : {}), "content-type": "application/json" }, body: JSON.stringify(body),
   });
   const result = await response.json();
   if (!response.ok || result.error) throw new Error(result.error || `App command failed (${response.status}).`);
@@ -5821,6 +5884,22 @@ function readSelfVersion() {
   }
 }
 
+// A command an agent tried that doesn't exist is the best hint for what it
+// expected Bivy to have. Inside a session, keep the word (never its arguments)
+// in <data-dir>/agent-cli-misses.jsonl for `pnpm run eval:agent-ux` and
+// whoever names the next command. Bounded: one rotation at 256 KiB.
+function recordAgentMiss(word) {
+  const session = resolveAttachSessionId({ env: process.env });
+  if (!session || typeof word !== "string" || word.length > 64) return;
+  try {
+    const file = path.join(appDir, "agent-cli-misses.jsonl");
+    if (fs.existsSync(file) && fs.statSync(file).size > 256 * 1024) fs.renameSync(file, `${file}.1`);
+    fs.appendFileSync(file, `${JSON.stringify({ ts: Date.now(), session, word })}\n`, { mode: 0o600 });
+  } catch {
+    // Best-effort: a miss log must never change what the command does.
+  }
+}
+
 function printHelp() {
   const details = { run: `Agents: ${[...AGENT_INTEGRATIONS.keys()].join(" | ")}, or -- <command>` };
   console.log(`\n${renderHelp({ paint: c.cyan, bold: c.bold, details })}\n`);
@@ -5898,13 +5977,27 @@ function cmdGuide(args = []) {
   console.log(guide.markdown.trimEnd());
 }
 
+// Inside an agent session the daemon names its own CLI ($BIVY_NODE_CLI). When
+// `bivy` was found on PATH (every installer links it by that name) and is
+// another file, run the node's, so the agent gets the commands its node
+// documents. Running a file on purpose (`node …/bin/bivy.mjs`) is left alone.
+function nodeCliToRun() {
+  const nodeCli = process.env.BIVY_NODE_CLI;
+  if (path.basename(process.argv[1] ?? "") !== "bivy") return undefined;
+  if (!nodeCli || !path.isAbsolute(nodeCli) || !fs.existsSync(nodeCli)) return undefined;
+  try { return fs.realpathSync(nodeCli) === fs.realpathSync(selfScript) ? undefined : nodeCli; } catch { return undefined; }
+}
+
 async function main() {
+  const nodeCli = nodeCliToRun();
+  if (nodeCli) process.exit(spawnSync(process.execPath, [nodeCli, ...process.argv.slice(2)], { stdio: "inherit", env: process.env }).status ?? 1);
   await hydrateCanonicalConfig();
   const argv = process.argv.slice(2);
   const [command, ...args] = argv;
   if (command === undefined) { printHelp(); return; }
   const entry = resolveCommand(command);
   if (!entry) {
+    recordAgentMiss(command);
     const close = suggestCommands(command);
     cliError({
       code: "unknown_command",
@@ -6044,6 +6137,11 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
       break;
     }
     case "automation": {
+      // An agent's apply is a proposal the user approves (see cmdAutomationProposal).
+      if ((args[0] === "apply" && !args.includes("--dry-run") && !process.env.BIVY_AUTOMATION_DIRECT && resolveAttachSessionId({ env: process.env })) || args[0] === "proposal") {
+        await cmdAutomationProposal(args);
+        break;
+      }
       if (!(await ensureDeps())) process.exit(1);
       process.exit(await run(nodeBin, [...nodeScriptArgs(automationEntry), ...args], { cwd: process.cwd(), env: process.env }));
       break;

package/bin/cli-commands.mjs

@@ -78,7 +78,11 @@ export const COMMANDS = [
 
   // Runs and automations
   { name: "runs", group: "runs", scope: "account", json: true, usage: 'runs <start|list|status|wait>', summary: "Unattended Runs with checks, evidence and a Receipt", subcommands: ["start", "list", "status", "wait"] },
-  { name: "automation", aliases: ["automations"], group: "runs", scope: "account", json: true, usage: "automation <list|trigger|init|validate|plan|test|apply>", summary: "Automations as code: validate, plan, apply, trigger", subcommands: ["list", "trigger", "init", "validate", "plan", "test", "test-filter", "apply"] },
+  { name: "automation", aliases: ["automations"], group: "runs", scope: "account", json: true, usage: "automation <list|trigger|init|validate|plan|test|apply>", summary: "Automations as code: validate, plan, apply, trigger", subcommands: ["list", "trigger", "init", "validate", "plan", "test", "test-filter", "apply", "proposal"],
+    tools: [
+      { name: "automation_plan", description: "Check an automations file (.bivy/automations.yaml) and show what each automation would do: trigger, routing, effective safety. Run it before automation_apply.", input: { path: { type: "string", description: "The automations file (default .bivy/automations.yaml)." } }, argv: ["automation", "plan", { arg: "path" }] },
+      { name: "automation_apply", description: "Propose applying an automations file to the user's account. They get an approval card listing each change; nothing is applied unless they approve. Returns the proposal: status applied, rejected, expired, failed, or pending (check later with bivy automation proposal <id> --wait).", input: { path: { type: "string", description: "The automations file (default .bivy/automations.yaml)." }, prune: { type: "boolean", description: "Also remove automations this file no longer has." } }, argv: ["automation", "apply", { arg: "path" }, { when: "prune", flag: "--prune" }] },
+    ] },
 
   // This node
   { name: "setup", aliases: ["init"], group: "node", scope: "node", usage: "setup", summary: "First-run wizard: agent, model login, remote sign-in, background service" },

package/bin/guides/automate.md

@@ -9,11 +9,35 @@ infrastructure code:
     bivy automation validate                       # check it
     bivy automation plan --json                    # triggers, routing, effective safety
     bivy automation test --event event.json        # which automation an event would start
-    bivy automation apply                          # reconcile the account with the file
+    bivy automation apply                          # ask the user, then apply
     bivy automation list --json
     bivy automation trigger <id-or-key>            # run one now
 
+A scheduled one (triggers: schedule, github, linear, webhook, manual; the
+format is in docs/automations-as-code.md):
+
+    version: 1
+    automations:
+      - id: nightly-tests
+        name: Nightly tests
+        trigger: schedule
+        schedule: { cron: "0 2 * * *", timezone: UTC }   # or { at: "2026-10-01T09:00:00Z" }
+        repo: owner/name                                  # required for schedules
+        instructions: |
+          Run the test suite. If it fails, open an issue with the failing tests.
+        safety:
+          approval: risky
+          sandbox: workspace-write
+
+From a session, `apply` goes through the machine's approval mode. Usually the
+user gets a card listing every change and decides. With "never ask" it applies
+at once, and the chat records what changed either way. The command waits up to
+90 seconds for an answer and prints apply's output once it's applied (exit 0). Exit 1 means they declined
+(don't retry the same thing), and exit 5 means they haven't answered yet: carry
+on, and check later with `bivy automation proposal <id> --wait`.
+`apply --dry-run` shows the changes without asking anyone.
+
 To pause one, set `enabled: false` on it and apply. Always `validate` and
-`plan` before `apply`, and show the user the plan when it
-changes something they didn't ask for. `apply --prune` also removes automations
-the file no longer has. `bivy automation --help` has every flag.
+`plan` first, and say in the chat what the automation will do and when.
+`apply --prune` also removes automations the file no longer has.
+`bivy automation --help` has every flag.

package/dist/agent-instructions.js

@@ -49,6 +49,8 @@ export const BIVY_AGENT_NOTE = [
         '`bivy delegate "<self-contained task>" --agent <id> [--machine <name>] --wait` runs it there and prints ' +
         "its answer and any branch/PR; `--to codex,grok@<machine>` asks several to compare, `bivy delegate machines` " +
         "lists machines and their agents. Use your own sub-agents for everything else.",
+    "- Work that should run on its own later (on a schedule, or when CI fails or an issue arrives) is a Bivy automation: " +
+        "`bivy guide automate`. Applying one may ask the user first.",
     "- `bivy context` shows your session, workspace and published apps; `bivy guide` has short playbooks; " +
         "`bivy help` lists every command (`--json` for all).",
 ].join("\n");

package/dist/approval.js

@@ -30,7 +30,7 @@ export class ApprovalManager {
     }
     async request(input) {
         const request = {
-            id: randomUUID(),
+            id: input.id ?? randomUUID(),
             sessionId: input.sessionId,
             toolName: input.toolName,
             input: input.toolInput,