directionallylocal 0.6.0 → 0.8.0

package/README.md

@@ -1,59 +1,128 @@
 # Directionally Local installer
 
-Rent a server, paste one line, and send coding tasks to it from your laptop. Each task runs in its own [Hotcell](https://github.com/directionally-local/hotcell) sandbox, driven by [Autopilot](https://github.com/directionally-local/autopilot), and comes back as a pull request, even with your laptop closed.
+Coding agents that run on your own computer or on your own server. Send a task; it runs in its own [Hotcell](https://github.com/directionally-local/hotcell) sandbox, driven by [Autopilot](https://github.com/directionally-local/autopilot), and comes back as a pull request, even with your laptop closed.
+
+## Start on your laptop
 
 ```sh
-curl -fsSL https://directionallylocal.run | sh
+npm install -g directionallylocal
+dl
 ```
 
-It asks three things:
+`dl` asks where your agents should run:
+
+- **On this computer** — start now, nothing to rent, pauses when this computer sleeps.
+- **On my own server** — keeps going when your laptop is closed; needs SSH access.
+
+For a server, `dl` lists the hosts in `~/.ssh/config` (or takes `user@host[:port]`), checks it over SSH, installs itself there, and pairs this laptop. Nothing is exposed on the server: `dl` reaches it through an SSH tunnel.
+
+### The keys it asks for
+
+Two keys, kept on the server only. `dl` looks for them on your laptop first and offers each one it finds:
 
-1. **Tailscale auth key.** The server joins your tailnet and serves Autopilot on its private `https://<name>.<tailnet>.ts.net` address, with no public ports. Turn on MagicDNS and HTTPS certificates for the tailnet first. Own-domain and instant-address options are coming.
-2. **OpenRouter API key.** This is stored in Hotcell's keystore on the server. Sandboxes get spend-capped gateway tokens instead, and your laptop never sees the key.
-3. **GitHub token,** so runs can clone, push, and open PRs. A fine-grained token with Contents and Pull requests read/write on the repositories you'll use is enough. It stays on the server; sandboxes push through Autopilot's repository-scoped proxy.
+- **GitHub** — your GitHub CLI login (`gh auth token`), offered as *"Use your GitHub CLI login (you)? It stays on your server."* Otherwise it asks for a fine-grained token with Contents and Pull requests read/write.
+- **OpenRouter** — the key in `OPENROUTER_API_KEY`, or the one Autopilot already has, offered the same way. Otherwise it asks for one.
 
-It ends with:
+The OpenRouter key goes into Hotcell's keystore on the server; sandboxes get spend-capped gateway tokens instead, and your laptop never sees it. The GitHub token stays on the server too; sandboxes push through Autopilot's repository-scoped proxy.
+
+### The model
+
+Setup asks once which model tasks and sessions use. The default is `deepseek/deepseek-v4.1-flash-1017`; if Autopilot already has a default model, that one is preselected instead. Change it any time with `dl model`, or per run with `-m`.
+
+### It ends with
 
 ```
-✓ Ready. Fits ~6 agents at once (estimate).
-  Open once to approve laptops in your browser: https://box.tail1234.ts.net/api/v1/auth/claim?token=…
-  On your laptop (signed in to the same tailnet): autopilot remote add https://box.tail1234.ts.net
+✓ Ready · fits ~6 agents at once (estimate)
+  1 Start a session: cd into a GitHub repository, then type
+      dl
+  2 Or hand off a one-off task
+      dl run "fix the flaky checkout test"
+
+  dl status shows where agents run and what they're doing.
 ```
 
-Then, on your laptop:
+Then, from inside a GitHub repository:
 
 ```sh
-npm install -g directionallylocal
-dl connect https://box.tail1234.ts.net     # approve the code in the browser you opened the link in
-dl run "fix the flaky checkout test"       # from inside a GitHub repository; local changes go along
-dl runs                                    # tasks and their pull requests
-dl pull <id>                               # check one out here
+dl                                  # talk to the repository's agent; it keeps running when you leave
+dl run "fix the flaky checkout test"  # one-off task; your uncommitted changes go along
+dl runs                             # tasks and their pull requests
+dl pull <id>                        # check one out here
 ```
 
-Typing `dl` on its own explains what it is and what's going on, on the server and on the laptop.
+`dl status` says when a server is behind npm, once a day: `! box is behind: Autopilot 2.7.0 → 2.7.2   dl update box`.
 
-The "fits ~N agents" figure is a conservative estimate from memory and CPUs (1 GB per sandbox). Measured numbers will replace it.
+The "fits ~N agents" figure is a conservative estimate: memory left after the host's own share (at least 1.5 GB or 15%), divided by 1 GB per sandbox, capped at two per CPU. Measured numbers will replace it.
 
 ## Commands
 
-Run these as root on the server. `dl` is short for `directionallylocal`; both work.
+`dl` is short for `directionallylocal`; both work.
+
+### On your laptop
+
+| Command | What it does |
+| --- | --- |
+| `dl` | Set up the first time; afterwards, an overview. Inside a GitHub repository, that repository's agent session. |
+| `dl setup` | Set up or repair where your agents run. Safe to re-run. `--identity FILE` names the SSH key to use. |
+| `dl new` | In a GitHub repository: start a fresh conversation for it. |
+| `dl status` | Where your agents run and what they're doing. Works anywhere. |
+| `dl connect URL` | Connect to a server someone else set up; approve the code it shows. |
+| `dl run "TASK"` | Run a task, from inside a GitHub repository. Ctrl-C stops watching, not the task. |
+| `dl runs` | Your tasks and their pull requests. `--json` for scripts. |
+| `dl watch ID` / `dl cancel ID` | Follow a task, or stop one. |
+| `dl pull ID` | Check out a task's branch here. |
+| `dl preview ID` | Deploy a task's Workers branch on the server with Serverless Objects and open it here, over the SSH tunnel. |
+| `dl servers` | Where agents run. `dl servers rename OLD NEW`, `dl servers remove NAME`. |
+| `dl use [NAME]` | Where tasks go without `--server`. With no name, shows it. |
+| `dl keys [openrouter\|github]` | Which keys are set, or replace one. `--server NAME` picks the server. |
+| `dl model [ID]` | The model for tasks and sessions. With no ID, picks from a list. |
+| `dl update [NAME]` | Update a server's Autopilot, Hotcell and sandbox image over SSH. `--wait` waits for running tasks instead of asking; with no terminal it waits anyway. |
+| `dl local status` | Agents running on this computer: running?, where, how many fit. |
+| `dl local uninstall [--purge]` | Stop and remove them. `--purge` also deletes keys and data. |
+
+Run options: `--server NAME`, `-m/--model MODEL`, `--repo OWNER/NAME`, `--detach`.
+
+### On the server
+
+Run these as root. `dl` on its own shows what this is, whether it's healthy, the connected laptops, and the runs.
 
 | Command | What it does |
 | --- | --- |
 | `dl up` | Install or repair everything. Safe to re-run: it keeps your keys and generated secrets and skips work that's already done. |
 | `dl up --dry-run` | Print what `up` would change, without changing anything. |
+| `dl connect-laptop` | How to connect a laptop, and a link to approve it in a browser. `dl connect-laptop CODE` approves the code a laptop shows. |
+| `dl laptops` | Connected laptops. `dl laptops remove NAME` disconnects one. |
+| `dl runs` | Tasks running or done, with their pull requests. |
+| `dl logs [hotcell\|autopilot] [-f]` | The services' logs. |
+| `dl preview ID [--remove]` | Deploy a task's branch as a preview, or stop it. Needs `DL_PREVIEWS_BUCKET`. |
+| `dl previews` | Live previews: task, port, branch. |
 | `dl doctor` | Check every part, with a fix for each failure. |
+| `dl keys [set openrouter\|github]` | Which keys are set, or replace one (hidden input). |
 | `dl status` | Show the installed versions and where to reach the server. |
 | `dl uninstall` | Remove the services and software but keep configuration and data. Add `--purge` to delete those too, plus the service accounts and the sandbox image. |
 
-For unattended installs, set the answers as environment variables: `DL_TAILSCALE_AUTH_KEY`, `DL_OPENROUTER_API_KEY` and `DL_GITHUB_TOKEN`. `DL_ACCESS=loopback` skips Tailscale; you then reach the server over an SSH tunnel.
+### Unattended installs
+
+Set the answers as environment variables: `DL_TAILSCALE_AUTH_KEY`, `DL_OPENROUTER_API_KEY` and `DL_GITHUB_TOKEN`. `DL_ACCESS` picks how the server is reached: `tailscale` (the default), `loopback` (this machine only), or `ssh` (what the laptop's setup uses). `DL_SKIP_CREDENTIAL_CHECK=1` skips the online key checks for offline installs.
 
-## What it sets up
+The laptop's setup drives the server over SSH with `dl up --access ssh --answers-stdin --events json`, which takes the keys as one JSON object on stdin and reports progress as JSON lines. `dl up --needs` reports which keys it would still ask for, without changing anything.
+
+## The one-line server install
+
+The curl path is still there for a server you set up by hand, as root on Ubuntu or Debian:
+
+```sh
+curl -fsSL https://directionallylocal.run | sh
+```
+
+It installs Node.js if needed, installs `directionallylocal`, and runs `dl up`. The laptop's setup uses the same script to bootstrap a server over SSH.
+
+## What it sets up on a server
 
 - **Node.js 24 LTS,** if Node is missing or lacks the fix for CVE-2026-111497 (22.23.4+, 24.22.1+ and 26.12.1+ are accepted). Node security releases from NodeSource are added to Ubuntu's automatic updates, which otherwise skip them. Delete `/etc/apt/apt.conf.d/52directionallylocal-nodejs` to opt out.
 - **Docker,** if it's missing, plus a rule that keeps sandboxes away from the cloud metadata endpoint. Docker isn't updated automatically, because its repo ships major upgrades and restarting the Docker daemon can stop running sandboxes.
 - **Hotcell and Autopilot from npm,** under `/opt/directionallylocal/releases/<versions>`, with `current` pointing at the active release.
-- **Two systemd services, each under its own unprivileged account:** `hotcell.service` (sandboxes and the credential gateway, on loopback) and `autopilot.service` (the API that laptops pair with, on `127.0.0.1:4096`). Only Tailscale Serve exposes it.
+- **Three systemd units:** `hotcell.service` (sandboxes and the credential gateway, on loopback) and `autopilot.service` (the API that laptops pair with, on `127.0.0.1:4096`), each under its own unprivileged account, plus `directionallylocal-metadata-block.service`, the firewall rule for sandboxes. Only Tailscale Serve exposes the API, and only when you use Tailscale access.
 - **A sandbox image** with Node, git, Python, and the Autopilot runtime baked in.
 - **Configuration** in `/etc/hotcell`, `/etc/autopilot` and `/etc/directionallylocal`, readable only by root and the matching service account. Data lives in `/var/lib/hotcell` and `/var/lib/autopilot`.
 
@@ -63,6 +132,8 @@ Supported: Ubuntu 24.04 and 22.04 and Debian 12, on x86_64 or arm64, with at lea
 
 `site/` is the Cloudflare Worker for `https://directionallylocal.run`. It serves `install.sh` to `curl` at the bare domain (and `/install.sh`), sends browsers to directionallylocal.com, and serves nothing else. Subdomains of `directionallylocal.run` are users' instant addresses, and the domain is on the Public Suffix List, so the Worker never sets cookies. Deploy it with `npx wrangler deploy -c site/wrangler.toml`.
 
+`site/wrangler.jsonc` is the portable config that celld and Serverless Objects read; `site/wrangler.toml` keeps the Cloudflare-only `routes` and `workers_dev`. The install script is checked in as `site/install-script.ts` so the Worker has no non-JavaScript imports; regenerate it with `npm run sync:site-script` after editing `install.sh`. `sobjects build --strict site` checks that the Worker stays portable. The design for the name service and approvals page is in [`docs/plans/portable-services.md`](docs/plans/portable-services.md).
+
 ## Development
 
 ```sh
@@ -70,6 +141,7 @@ npm install
 npm test          # node:test through tsx; a simulated server exercises up, doctor, and uninstall
 npm run typecheck
 npm run build
+npm run sync:site-script   # after editing install.sh
 ```
 
 ## License

package/dist/cli.js

@@ -9,7 +9,10 @@ import { loadRemotes } from "./laptop/config.js";
 import { keys } from "./laptop/keys.js";
 import { model } from "./laptop/settings.js";
 import { projectSession } from "./laptop/session.js";
+import { preview as laptopPreview } from "./laptop/preview.js";
 import { setup } from "./laptop/setup.js";
+import { realSshExec } from "./laptop/ssh.js";
+import { update } from "./laptop/update.js";
 import { localCommand } from "./local/cli.js";
 import { setUpOnThisComputer } from "./local/setup.js";
 import { TtyPrompter } from "./prompt.js";
@@ -17,6 +20,7 @@ import { readState } from "./state.js";
 import { DryRunSystem, RealSystem } from "./system.js";
 import { uninstall } from "./uninstall.js";
 import { JsonUi, PlainUi, TerminalUi, palette } from "./ui.js";
+import { previewCommand, previewsCommand } from "./preview.js";
 import { needs, parseAccessMode, parseProvidedAnswers, up } from "./up.js";
 const HELP = `Directionally Local: coding agents that run on this computer or on your own server.
 Send a task; it runs in its own sandbox and comes back as a pull request.
@@ -34,10 +38,13 @@ On your laptop:
   dl runs                 your tasks and their pull requests
   dl watch ID             follow a task      dl cancel ID   stop one
   dl pull ID              check out a task's branch here
+  dl preview ID           deploy a task's Workers branch on the server and open it here
   dl servers              where agents run (dl servers remove NAME · dl servers rename OLD NEW)
   dl use [NAME]           where tasks go without --server (no NAME: show it)
   dl keys [openrouter|github]   which keys are set, or replace one (--server NAME)
   dl model [ID]           the model for tasks and sessions (no ID: pick from a list)
+  dl update [NAME]        update a server's Autopilot, Hotcell and sandbox image
+                          (--wait: wait for running tasks instead of asking)
   run options: --server NAME, -m/--model MODEL, --repo OWNER/NAME, --detach
   dl local status         agents running on this computer: running?, where, how many fit
   dl local uninstall [--purge]   stop and remove them (--purge also deletes keys and data)
@@ -49,6 +56,8 @@ On the server:
   dl connect-laptop CODE  approve the code a laptop shows
   dl laptops              connected laptops (dl laptops remove NAME to disconnect one)
   dl runs                 tasks running or done, with their pull requests
+  dl preview ID [--remove]   deploy a task's branch with Serverless Objects, or stop it
+  dl previews             live previews: task, port, branch
   dl logs [hotcell|autopilot] [-f]   the services' logs
   dl doctor               check every part, with a fix for each problem
   dl keys [set openrouter|github]   which keys are set, or replace one (hidden input)
@@ -106,6 +115,7 @@ export async function main(argv, io = {
                 needs: { type: "boolean" },
                 identity: { type: "string" },
                 stdin: { type: "boolean" },
+                wait: { type: "boolean" },
             },
         });
     }
@@ -220,7 +230,7 @@ export async function main(argv, io = {
                     }
                     // A laptop connected to servers gets its own home (`dl status` shows it from anywhere);
                     // otherwise, what this is and how to start.
-                    if ((!command || command === "status") && await laptopHome(laptopIO))
+                    if ((!command || command === "status") && await laptopHome(laptopIO, undefined, undefined, { ssh: realSshExec }))
                         return 0;
                     // A laptop with nothing set up yet: the wizard (it needs someone to answer it).
                     if (!command && terminal && !isRoot() && (await loadRemotes()).length === 0)
@@ -242,6 +252,15 @@ export async function main(argv, io = {
             }
             case "setup":
                 return await setup({ io: laptopIO, terminal, localSetup: (input) => setUpOnThisComputer(input), ...(values.identity ? { identityFile: values.identity } : {}) });
+            case "update":
+                return await update(parsed.positionals.slice(1), {
+                    ssh: realSshExec,
+                    prompter: new TtyPrompter(),
+                    newUi: () => terminal ? new TerminalUi(io.out, undefined, colorOn) : new PlainUi(io.out),
+                    io: laptopIO,
+                    interactive: terminal,
+                    wait: Boolean(values.wait),
+                });
             case "connect": {
                 const url = parsed.positionals[1];
                 if (!url) {
@@ -291,6 +310,34 @@ export async function main(argv, io = {
                 io.err(`  dl new starts a fresh conversation from inside a GitHub repository (with something set up: dl setup).\n`);
                 return 1;
             }
+            case "preview": {
+                const id = parsed.positionals[1];
+                if (!id) {
+                    io.err(`  Usage: dl preview ID   ${colors.dim("(from dl runs)")}\n`);
+                    return 2;
+                }
+                // On a server, deploy it; on a laptop, ask the server to and tunnel to the result.
+                if (await readState(system)) {
+                    if (!isRoot()) {
+                        io.err(`  Run it as root: sudo dl preview ${id}\n`);
+                        return 1;
+                    }
+                    return await previewCommand(system, parsed.positionals.slice(1), { json: Boolean(values.json) }, io.out, colors);
+                }
+                return await laptopPreview({ id, ...(values.server ? { server: values.server } : {}) }, {}, laptopIO);
+            }
+            case "previews": {
+                const state = await readState(system);
+                if (!state) {
+                    io.out(NOT_A_SERVER(colors));
+                    return 1;
+                }
+                if (!isRoot()) {
+                    io.err("  Run it as root: sudo dl previews\n");
+                    return 1;
+                }
+                return await previewsCommand(system, io.out, colors);
+            }
             case "servers":
                 return await servers(parsed.positionals.slice(1), laptopIO);
             case "use":

package/dist/home.js

@@ -3,6 +3,7 @@ import { AUTOPILOT_PORT, CELL_MEMORY_MB, SERVICES } from "./layout.js";
 import { approvePairing, createLaptopCredential, listLaptops, listServerRuns, ownerLink, pendingPairings, revokeLaptop } from "./server-api.js";
 import { describeAccess, readState } from "./state.js";
 import { palette } from "./ui.js";
+import { readPreviews } from "./preview.js";
 import { nextSteps } from "./up.js";
 const ABOUT = "Background coding agents on your own server: send a task from your laptop, get a pull request back.";
 /** Quick health for the home screen and the login line: services up and the API answering. */
@@ -21,8 +22,8 @@ async function health(system) {
 }
 /** `dl` on a server: what this is, whether it's healthy, who's connected, what's running, what to do. */
 export async function serverHome(system, state, write, c) {
-    const [status, laptops, runs, pending, facts] = await Promise.all([
-        health(system), listLaptops(system), listServerRuns(system), pendingPairings(system), detectHost(system),
+    const [status, laptops, runs, pending, facts, previews] = await Promise.all([
+        health(system), listLaptops(system), listServerRuns(system), pendingPairings(system), detectHost(system), readPreviews(system),
     ]);
     const verdict = status.ok ? c.green("● healthy") : c.red(`● ${status.problems.join(", ")}`);
     const week = Date.now() - 7 * 24 * 60 * 60 * 1000;
@@ -33,6 +34,9 @@ export async function serverHome(system, state, write, c) {
     write(row("Laptops", laptops === undefined ? c.dim("unknown (run dl up to update)") : laptops.length === 0 ? "none connected yet" : `${laptops.length} connected · ${laptops.map((laptop) => laptop.name).join(", ")}`, "dl laptops"));
     write(row("Runs", runs === undefined ? c.dim("unknown (run dl up to update)") : `${running} running · ${doneThisWeek} this week`, "dl runs"));
     write(row("Capacity", `~${agentCapacity(facts, CELL_MEMORY_MB)} agents at once (estimate)`));
+    if (previews.previews.length > 0) {
+        write(row("Previews", `${previews.previews.length} live · ${previews.previews.map((preview) => preview.id).join(", ")}`, "dl previews"));
+    }
     if (pending.length > 0) {
         write(`\n  ${c.yellow("!")} Waiting for approval: ${pending.map((entry) => `${c.bold(entry.code)} (${entry.name})`).join(", ")}   ${c.dim("dl connect-laptop <code>")}\n`);
     }

package/dist/laptop/client.js

@@ -77,6 +77,25 @@ export class RemoteClient {
     cancel(conversationId) {
         return this.request("POST", `/conversations/${encodeURIComponent(conversationId)}/cancel`);
     }
+    /**
+     * The newest event of a finished conversation: one request, then the stream is dropped.
+     * `dl runs` uses it to say why a task failed without replaying the whole run.
+     */
+    async lastEvent(conversationId, lastEventId) {
+        const controller = new AbortController();
+        try {
+            for await (const event of this.events(conversationId, Math.max(0, lastEventId - 1), controller.signal)) {
+                return event;
+            }
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            controller.abort();
+        }
+        return undefined;
+    }
     /**
      * Events after `cursor`, reconnecting with the last seen ID when the stream drops,
      * until the caller stops iterating or the signal aborts.

package/dist/laptop/commands.js

@@ -12,6 +12,7 @@ import { DEFAULT_MODEL, laptopModel } from "./settings.js";
 import { sshCommandLine } from "./ssh.js";
 import { openBrowser } from "./open-browser.js";
 import { withConnections } from "./tunnel.js";
+import { outdatedServers } from "./update.js";
 export { DEFAULT_MODEL, readAutopilotModel } from "./settings.js";
 /**
  * `dl` on a laptop: send tasks to where agents run (this computer, or your own server),
@@ -129,12 +130,16 @@ async function listRuns(remotes, connections, json, io) {
         io.out(`\n  No tasks yet. From inside a GitHub repository:  ${c.bold('dl run "fix the flaky checkout test"')}\n\n`);
         return;
     }
+    const reasons = await failureReasons(rows, remotes, connections);
     io.out("\n");
     for (const entry of rows) {
         const running = entry.activeRunId !== null;
         const glyph = running ? c.cyan("◐") : entry.status === "completed" || entry.status === "merged" ? c.green("✓") : ["failed", "interrupted"].includes(entry.status) ? c.red("✗") : c.dim("○");
         const multi = remotes.length > 1 ? `${entry.server}  ` : "";
         io.out(`  ${glyph} ${entry.conversationId.slice(0, 8)}  ${multi}${(running ? "running" : entry.status).padEnd(11)} ${(entry.repository ?? "").padEnd(26)} ${c.dim(entry.pullRequestURL ?? entry.branch ?? "")}\n`);
+        const reason = reasons.get(entry.conversationId);
+        if (reason)
+            io.out(`      ${c.dim(oneLine(reason, 100))}\n`);
     }
     io.out(`\n  ${c.dim("Follow one:")} dl watch <id>   ${c.dim("Check one out:")} dl pull <id>\n\n`);
 }
@@ -262,7 +267,7 @@ export async function renameServer(args, io = processIO, path) {
     return 0;
 }
 /** `dl` on a laptop: what this is, which servers it's connected to, what to type next. */
-export async function laptopHome(io = processIO, open, model = laptopModel) {
+export async function laptopHome(io = processIO, open, model = laptopModel, versions) {
     const c = palette(io.color === true);
     const remotes = await loadRemotes();
     if (remotes.length === 0)
@@ -276,12 +281,19 @@ export async function laptopHome(io = processIO, open, model = laptopModel) {
             total += list?.length ?? 0;
         }
     });
-    const [current, chosen] = await Promise.all([defaultName(), model()]);
+    const [current, chosen, outdated] = await Promise.all([
+        defaultName(),
+        model(),
+        versions ? outdatedServers(remotes, versions).catch(() => []) : Promise.resolve([]),
+    ]);
     io.out(`\n  ${c.bold("Directionally Local")}  ${c.dim("on this laptop")}\n\n`);
     io.out("  Coding agents that run on this computer or your own server: send a task, get a pull request back.\n\n");
     io.out(`  ${c.dim("Runs on".padEnd(11))}${remotes.map((remote) => `${mark(remote, current, c)} ${remote.name} ${c.dim(where(remote))}`).join(", ")}   ${c.dim(remotes.length > 1 ? "dl servers · dl use NAME" : "dl servers")}\n`);
     io.out(`  ${c.dim("Tasks".padEnd(11))}${running} running · ${total} in all   ${c.dim("dl runs")}\n`);
-    io.out(`  ${c.dim("Model".padEnd(11))}${chosen ?? DEFAULT_MODEL}   ${c.dim("dl model")}\n\n`);
+    io.out(`  ${c.dim("Model".padEnd(11))}${chosen ?? DEFAULT_MODEL}   ${c.dim("dl model")}\n`);
+    for (const entry of outdated)
+        io.out(`  ${c.yellow("!")} ${entry.name} is behind: ${entry.notice}   ${c.dim(`dl update ${entry.name}`)}\n`);
+    io.out("\n");
     io.out(`  ${c.dim("Start a session: cd into a GitHub repository, then type")}  ${c.bold("dl")}\n`);
     io.out(`  ${c.dim("Or hand off a one-off task:")}  ${c.bold('dl run "fix the flaky checkout test"')}\n\n`);
     return true;
@@ -293,12 +305,15 @@ async function follow(client, remote, conversationId, cursor, signal, io, replay
     signal?.addEventListener("abort", stop, { once: true });
     const renderer = new EventRenderer(io, c);
     let outcome;
+    let finalEvent;
     try {
         if (replayUntil === undefined || replayUntil > cursor) {
             for await (const event of client.events(conversationId, cursor, controller.signal)) {
                 renderer.render(event);
-                if (RUN_END_EVENTS.has(event.type))
+                if (RUN_END_EVENTS.has(event.type)) {
                     outcome = event.type;
+                    finalEvent = event;
+                }
                 if (replayUntil === undefined ? RUN_END_EVENTS.has(event.type) : event.id >= replayUntil)
                     break;
             }
@@ -325,9 +340,18 @@ async function follow(client, remote, conversationId, cursor, signal, io, replay
         return 0;
     }
     io.err(`\n  ${c.red("✗")} ${id} ${outcome}\n`);
+    const reason = failureReason(finalEvent);
+    if (reason)
+        for (const line of wrap(reason, 100, 3))
+            io.err(`    ${c.dim(line)}\n`);
     if (renderer.unpriced || isModelNotPriced(JSON.stringify(final))) {
         io.err(`  This model isn't in your server's price list yet. Run ${c.bold("dl setup")} to refresh it, or pick another model with -m.\n`);
     }
+    else {
+        const hint = reason ? failureHint(reason) : undefined;
+        if (hint)
+            io.err(`  ${c.dim(hint)}\n`);
+    }
     io.err("\n");
     return 1;
 }
@@ -439,6 +463,78 @@ function oneLine(text, max) {
     const flat = text.replace(/\s+/g, " ").trim();
     return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
 }
+/** The reason a run ended, from its final event. Servers have used `reason`, `error` and `message`. */
+export function failureReason(event) {
+    if (!event)
+        return undefined;
+    for (const key of ["reason", "error", "message", "detail"]) {
+        const value = event.data[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+/** A next step for the reasons we recognise, or undefined. */
+export function failureHint(reason) {
+    const text = reason.toLowerCase();
+    if (/context window|token limit|too many tokens|maximum context/.test(text))
+        return "pick a model with a bigger window: dl model";
+    if (/not priced|no such model|model not found|not offered|unknown model/.test(text))
+        return "pick another model: dl model";
+    if (/rate limit|429|quota/.test(text))
+        return "wait a moment, or check the OpenRouter key: dl keys openrouter";
+    if (/git_push_failed|push failed|permission denied|bad credentials|401/.test(text))
+        return "check the GitHub token: dl keys github";
+    if (/out of memory|oom|killed/.test(text))
+        return "the sandbox ran out of memory; try a smaller task";
+    return undefined;
+}
+/** `text` broken into at most `maxLines` lines of `width`, with an ellipsis when it was cut. */
+export function wrap(text, width, maxLines) {
+    const words = text.replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (line && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line ? `${line} ${word}` : word;
+        }
+    }
+    if (line)
+        lines.push(line);
+    if (lines.length <= maxLines)
+        return lines;
+    const kept = lines.slice(0, maxLines);
+    kept[maxLines - 1] = `${kept[maxLines - 1].slice(0, width - 1)}…`;
+    return kept;
+}
+/** How many failed tasks `dl runs` asks about; each one is a request. */
+const REASON_LOOKUPS = 10;
+/** One line per failed task, from its final event. */
+async function failureReasons(rows, remotes, connections) {
+    const reasons = new Map();
+    let lookups = 0;
+    for (const entry of rows) {
+        if (lookups >= REASON_LOOKUPS)
+            break;
+        if (entry.activeRunId !== null || !["failed", "interrupted"].includes(entry.status))
+            continue;
+        const remote = remotes.find((candidate) => candidate.name === entry.server);
+        if (!remote)
+            continue;
+        lookups++;
+        const event = await connections.client(remote)
+            .then((client) => client.lastEvent(entry.conversationId, entry.lastEventId))
+            .catch(() => undefined);
+        const reason = failureReason(event);
+        if (reason)
+            reasons.set(entry.conversationId, reason);
+    }
+    return reasons;
+}
 export function describeError(error) {
     if (error instanceof RemoteApiError)
         return `${error.message} (${error.code})`;

package/dist/laptop/preview.js

@@ -0,0 +1,60 @@
+import { palette } from "../ui.js";
+import { resolveRemote } from "./config.js";
+import { openBrowser } from "./open-browser.js";
+import { checkServer, realSshExec, shellQuote } from "./ssh.js";
+import { createForwarder } from "./tunnel.js";
+/** Non-root users run the server commands with sudo; checkServer made sure it needs no password. */
+function sudo(facts) {
+    return facts.root ? "" : "sudo -n ";
+}
+export async function preview(input, deps, io) {
+    const c = palette(io.color === true);
+    const remote = await resolveRemote(input.server);
+    if (!remote.ssh) {
+        io.err(`\n  ${c.red("✗")} ${remote.name} wasn't set up over SSH, so this laptop can't reach a preview on it.\n  On the server: ${c.bold(`dl preview ${input.id}`)}\n\n`);
+        return 1;
+    }
+    const ssh = deps.ssh ?? realSshExec;
+    const facts = await checkServer(remote.ssh, ssh, remote.name);
+    io.err(`  ${c.cyan("·")} Deploying ${input.id} on ${remote.name}…\n`);
+    const result = await ssh(remote.ssh, `${sudo(facts)}dl preview ${shellQuote(input.id)} --json`);
+    const answer = lastJson(result.stdout);
+    if (result.code !== 0 || typeof answer?.port !== "number") {
+        const detail = lastLine(result.stderr) || lastLine(result.stdout) || `dl preview exited with ${result.code}`;
+        io.err(`\n  ${c.red("✗")} ${detail}\n\n`);
+        return 1;
+    }
+    const forward = deps.forward ?? createForwarder();
+    const endpoint = await forward(remote.ssh, answer.port, remote.name);
+    const id = typeof answer.id === "string" ? answer.id : input.id;
+    io.out(`\n  ${c.green("✓")} ${id} is live at ${c.bold(endpoint.url)}\n`);
+    io.out(`  ${c.dim("Ctrl-C closes the tunnel; the preview keeps running (dl preview " + id + " --remove stops it).")}\n\n`);
+    if ((deps.openBrowser ?? openBrowser)(endpoint.url))
+        io.out(`  ${c.dim("(opened it for you)")}\n\n`);
+    try {
+        await (deps.hold ?? holdUntilInterrupted)();
+    }
+    finally {
+        await endpoint.close();
+    }
+    return 0;
+}
+function holdUntilInterrupted() {
+    return new Promise((resolve) => {
+        process.once("SIGINT", () => resolve());
+    });
+}
+function lastJson(text) {
+    for (const line of text.trim().split("\n").reverse()) {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            // keep looking: a banner or warning may come before the JSON
+        }
+    }
+    return undefined;
+}
+function lastLine(text) {
+    return text.trim().split("\n").at(-1)?.trim() ?? "";
+}

package/dist/laptop/tunnel.js

@@ -7,17 +7,13 @@ const realSpawn = (args) => spawn("ssh", args, { stdio: ["ignore", "ignore", "pi
 export function tunnelArgs(access, localPort, remotePort) {
     return ["-N", "-o", "ExitOnForwardFailure=yes", ...sshOptions(access), "-L", `127.0.0.1:${localPort}:127.0.0.1:${remotePort}`, access.target];
 }
-export function createOpener(options = {}) {
+export function createForwarder(options = {}) {
     const spawnTunnel = options.spawn ?? realSpawn;
     const freePort = options.freePort ?? pickFreePort;
     const accepts = options.accepts ?? acceptsConnections;
     const timeoutMs = options.timeoutMs ?? 20_000;
     const pollMs = options.pollMs ?? 100;
-    return async (remote) => {
-        if (!remote.ssh)
-            return { url: remote.url, close: async () => { } };
-        const access = remote.ssh;
-        const remotePort = Number(new URL(remote.url).port || 80);
+    return async (access, remotePort, display = access.target) => {
         const port = await freePort();
         const child = spawnTunnel(tunnelArgs(access, port, remotePort));
         let stderr = "";
@@ -44,18 +40,26 @@ export function createOpener(options = {}) {
             if (exited) {
                 await close();
                 const detail = stderr.trim().split("\n").at(-1)?.trim();
-                throw new Error(`Couldn't open an SSH tunnel to ${remote.name} (${access.target})${detail ? `: ${detail}` : ""}\n  Check that this works: ${sshCommandLine(access)}`);
+                throw new Error(`Couldn't open an SSH tunnel to ${display} (${access.target})${detail ? `: ${detail}` : ""}\n  Check that this works: ${sshCommandLine(access)}`);
             }
             if (await accepts(port))
                 return { url: `http://127.0.0.1:${port}`, close };
             if (Date.now() >= deadline) {
                 await close();
-                throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s opening an SSH tunnel to ${remote.name} (${access.target}).\n  Check that this works: ${sshCommandLine(access)}`);
+                throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s opening an SSH tunnel to ${display} (${access.target}).\n  Check that this works: ${sshCommandLine(access)}`);
             }
             await new Promise((resolve) => setTimeout(resolve, pollMs));
         }
     };
 }
+export function createOpener(options = {}) {
+    const forward = createForwarder(options);
+    return async (remote) => {
+        if (!remote.ssh)
+            return { url: remote.url, close: async () => { } };
+        return forward(remote.ssh, Number(new URL(remote.url).port || 80), remote.name);
+    };
+}
 export const openRemote = createOpener();
 /**
  * For an interactive session: ssh in its own process group, so Ctrl-C typed into the agent's

package/dist/laptop/update.js

@@ -0,0 +1,206 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { palette } from "../ui.js";
+import { resolveRemote } from "./config.js";
+import { EventReplayer } from "./remote-install.js";
+import { checkServer } from "./ssh.js";
+import { withConnections } from "./tunnel.js";
+const execFileAsync = promisify(execFile);
+const DAY_MS = 24 * 60 * 60 * 1000;
+const STATE_FILE = "/etc/directionallylocal/state.json";
+/** Non-root users run the server commands with sudo; checkServer made sure it needs no password. */
+function sudo(facts) {
+    return facts.root ? "" : "sudo -n ";
+}
+/** The versions a server has installed, from the state file `dl up` writes (world-readable). */
+export async function serverVersions(access, ssh) {
+    const result = await ssh(access, `cat ${STATE_FILE}`);
+    if (result.code !== 0)
+        return undefined;
+    try {
+        const state = JSON.parse(result.stdout);
+        return typeof state.autopilotVersion === "string" && typeof state.hotcellVersion === "string"
+            ? { autopilot: state.autopilotVersion, hotcell: state.hotcellVersion }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `1.2.10` is newer than `1.2.9`; a pre-release suffix is ignored, since npm's `latest` has none. */
+export function compareVersions(a, b) {
+    const parse = (version) => version.replace(/^v/, "").split(/[.+-]/).slice(0, 3).map((part) => Number(part) || 0);
+    const left = parse(a);
+    const right = parse(b);
+    for (let index = 0; index < 3; index++) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** "Autopilot 2.7.0 → 2.7.2 · Hotcell 1.4.0 → 1.4.1", or undefined when the server is current. */
+export function behindNotice(server, latest) {
+    const parts = [];
+    if (compareVersions(server.autopilot, latest.autopilot) < 0)
+        parts.push(`Autopilot ${server.autopilot} → ${latest.autopilot}`);
+    if (compareVersions(server.hotcell, latest.hotcell) < 0)
+        parts.push(`Hotcell ${server.hotcell} → ${latest.hotcell}`);
+    return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+export function versionsCachePath(env = process.env) {
+    const cacheHome = env.XDG_CACHE_HOME?.trim() || join(homedir(), ".cache");
+    return join(cacheHome, "directionallylocal", "versions.json");
+}
+async function npmVersion(pkg) {
+    try {
+        const { stdout } = await execFileAsync("npm", ["view", pkg, "version"], { timeout: 15_000 });
+        const version = stdout.trim();
+        return /^\d+\.\d+\.\d+/.test(version) ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * npm's newest Autopilot and Hotcell, looked up at most once a day. Offline keeps the last
+ * answer rather than pretending the server is current.
+ */
+export async function latestVersions(options = {}) {
+    const path = options.cacheFile ?? versionsCachePath();
+    const now = (options.now ?? Date.now)();
+    const maxAge = options.maxAgeMs ?? DAY_MS;
+    const cached = await readCache(path);
+    if (cached && now - cached.checkedAt < maxAge)
+        return cached;
+    const npm = options.npm ?? npmVersion;
+    const [autopilot, hotcell] = await Promise.all([npm("autopilot-ai"), npm("hotcell")]);
+    if (!autopilot || !hotcell)
+        return cached;
+    const fresh = { autopilot, hotcell, checkedAt: now };
+    await writeCache(path, fresh);
+    return fresh;
+}
+async function readCache(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return typeof parsed.autopilot === "string" && typeof parsed.hotcell === "string" && typeof parsed.checkedAt === "number"
+            ? { autopilot: parsed.autopilot, hotcell: parsed.hotcell, checkedAt: parsed.checkedAt }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeCache(path, versions) {
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        const temp = `${path}.${process.pid}.tmp`;
+        await writeFile(temp, `${JSON.stringify(versions, null, 2)}\n`, { mode: 0o644 });
+        await rename(temp, path);
+    }
+    catch {
+        // A cache that can't be written only costs another lookup next time.
+    }
+}
+/** How many tasks are running on a server, or undefined when it can't be asked. */
+export async function runningTasks(remote, open) {
+    try {
+        return await withConnections(open, async (connections) => {
+            const list = await (await connections.client(remote)).listConversations(200);
+            return list.filter((entry) => entry.activeRunId !== null).length;
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Servers that are behind npm, for `dl status`. One SSH round trip each, and a cached lookup. */
+export async function outdatedServers(remotes, deps) {
+    const latest = await (deps.latest ?? (() => latestVersions()))();
+    if (!latest)
+        return [];
+    const outdated = [];
+    for (const remote of remotes) {
+        if (!remote.ssh)
+            continue;
+        const server = await serverVersions(remote.ssh, deps.ssh);
+        if (!server)
+            continue;
+        const notice = behindNotice(server, latest);
+        if (notice)
+            outdated.push({ name: remote.name, notice });
+    }
+    return outdated;
+}
+/** `dl update [NAME] [--wait]`: update a server over SSH, without interrupting its tasks. */
+export async function update(args, deps) {
+    const c = palette(deps.io.color === true);
+    const name = args.find((arg) => !arg.startsWith("-"));
+    const remote = await resolveRemote(name);
+    if (!remote.ssh) {
+        deps.io.err(`\n  ${c.red("✗")} ${remote.name} wasn't set up over SSH, so this laptop can't update it.\n  On the server: ${c.bold("sudo dl up")}\n\n`);
+        return 1;
+    }
+    const facts = await checkServer(remote.ssh, deps.ssh, remote.name);
+    const before = await serverVersions(remote.ssh, deps.ssh);
+    const running = deps.running ?? ((target) => runningTasks(target, deps.open));
+    const count = await running(remote);
+    if (count === undefined) {
+        deps.io.err(`  ${c.yellow("!")} Couldn't ask ${remote.name} what's running; updating anyway.\n`);
+    }
+    else if (count > 0) {
+        if (!(await settleRunning(remote, count, deps, running, c)))
+            return 1;
+    }
+    deps.io.out(`\n  ${c.bold("Updating")} ${remote.name}${before ? c.dim(`  (Autopilot ${before.autopilot} · Hotcell ${before.hotcell})`) : ""}\n\n`);
+    const replay = new EventReplayer(deps.newUi);
+    // No --access: the server keeps the way it's reached. `{}` means "no new answers", so a
+    // missing key fails at once instead of waiting for a prompt nobody can see.
+    const result = await deps.ssh(remote.ssh, `${sudo(facts)}dl up --answers-stdin --events json`, {
+        input: "{}\n",
+        onStdoutLine: (line) => replay.line(line),
+    });
+    replay.finish();
+    if (result.code !== 0 || replay.error) {
+        deps.io.err(`\n  ${c.red("✗")} Updating ${remote.name} failed: ${replay.error ?? `dl up exited with ${result.code}`}\n`);
+        for (const line of replay.tail())
+            deps.io.err(`    ${c.dim(line)}\n`);
+        deps.io.err("\n");
+        return 1;
+    }
+    const after = await serverVersions(remote.ssh, deps.ssh);
+    const changed = before && after && (before.autopilot !== after.autopilot || before.hotcell !== after.hotcell);
+    const versions = after ? `  ${c.dim(`Autopilot ${after.autopilot} · Hotcell ${after.hotcell}`)}` : "";
+    deps.io.out(`\n  ${c.green("✓")} ${remote.name} is up to date${changed ? "" : c.dim("  (already was)")}${versions}\n\n`);
+    return 0;
+}
+/**
+ * Decides what to do about running tasks: wait when asked or when nobody can answer, and
+ * otherwise ask. Returns whether to go ahead.
+ */
+async function settleRunning(remote, count, deps, running, c) {
+    const tasks = `${count} task${count === 1 ? "" : "s"}`;
+    if (deps.wait || !deps.interactive) {
+        deps.io.out(`  ${c.cyan("·")} ${tasks} running on ${remote.name}; waiting for ${count === 1 ? "it" : "them"} to finish (Ctrl-C stops waiting).\n`);
+        await waitForIdle(remote, deps, running);
+        return true;
+    }
+    const answer = (await deps.prompter.text(`  ${tasks} running on ${remote.name}. Update now and interrupt ${count === 1 ? "it" : "them"}? [y/N] `)).trim().toLowerCase();
+    if (answer === "y" || answer === "yes")
+        return true;
+    deps.io.out(`  ${c.dim("Not updating. Wait for them, then run")} dl update ${remote.name}${c.dim(", or add --wait.")}\n\n`);
+    return false;
+}
+async function waitForIdle(remote, deps, running) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    for (;;) {
+        const count = await running(remote);
+        if (count === undefined || count === 0)
+            return;
+        await sleep(15_000);
+    }
+}

package/dist/layout.js

@@ -17,6 +17,9 @@ export const PATHS = {
     autopilotHome: "/var/lib/autopilot",
     workspace: "/var/lib/autopilot/workspaces/default",
     units: "/etc/systemd/system",
+    /** One checkout and one Serverless Objects node per preview (docs/plans/preview-deploys.md). */
+    previews: "/var/lib/directionallylocal/previews",
+    previewsState: "/var/lib/directionallylocal/previews.json",
 };
 /** Lets Ubuntu's unattended-upgrades install Node.js fixes from NodeSource, like its own packages. */
 export const NODE_AUTO_UPDATES = "/etc/apt/apt.conf.d/52directionallylocal-nodejs";

package/dist/preview.js

@@ -0,0 +1,219 @@
+import { join } from "node:path";
+import { parseEnvFile, PATHS, USERS } from "./layout.js";
+import { listServerRuns } from "./server-api.js";
+import { palette } from "./ui.js";
+/**
+ * `dl preview`: deploy an agent's Workers branch on this server with Serverless Objects and
+ * reach it over the laptop's SSH tunnel. Design: docs/plans/preview-deploys.md.
+ *
+ * Serverless Objects is pre-alpha, so a preview failing is expected rather than exceptional:
+ * it never fails the task or its pull request, and it is reported in `dl previews`.
+ */
+export const MAX_PREVIEWS = 3;
+export const PREVIEW_PORT_FIRST = 8090;
+export const PREVIEW_PORT_LAST = 8099;
+/** Root only: a monorepo with several Wrangler projects is out of scope for Phase 1. */
+const WRANGLER_CONFIGS = /^wrangler\.(json|jsonc|toml)$/;
+export function previewId(conversationId) {
+    return conversationId.slice(0, 8);
+}
+/** A branch is previewable when its root has a Wrangler config (design §3). */
+export function isWranglerProject(files) {
+    return files.some((name) => WRANGLER_CONFIGS.test(name));
+}
+/** The first free port in the range, or undefined when every slot is taken. */
+export function freePort(previews) {
+    const used = new Set(previews.map((preview) => preview.port));
+    for (let port = PREVIEW_PORT_FIRST; port <= PREVIEW_PORT_LAST; port++)
+        if (!used.has(port))
+            return port;
+    return undefined;
+}
+/** The preview's own node config (design §2.3): its own port and its own bucket prefix. */
+export function sobjectsToml(input) {
+    return `[celld]\nbucket = ${JSON.stringify(input.bucket)}\nlisten = "127.0.0.1:${input.port}"\n`;
+}
+export function bucketFor(prefix, id) {
+    return `${prefix.replace(/\/+$/, "")}/${id}`;
+}
+/**
+ * The token reaches git through the environment, never argv: `ps` would show it there.
+ * The helper string itself holds no secret.
+ */
+const CREDENTIAL_HELPER = 'credential.helper=!f() { echo username=x-access-token; echo "password=$GITHUB_TOKEN"; }; f';
+export function cloneArgs(repository, branch, directory) {
+    return ["-c", CREDENTIAL_HELPER, "clone", "--depth", "1", "--branch", branch, `https://github.com/${repository}.git`, directory];
+}
+export function fetchArgs(branch) {
+    return ["-c", CREDENTIAL_HELPER, "fetch", "--depth", "1", "origin", branch];
+}
+export async function readPreviews(system) {
+    const raw = await system.readFile(PATHS.previewsState);
+    if (!raw)
+        return { version: 1, previews: [] };
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed.version === 1 && Array.isArray(parsed.previews) ? { version: 1, previews: parsed.previews } : { version: 1, previews: [] };
+    }
+    catch {
+        return { version: 1, previews: [] };
+    }
+}
+export async function writePreviews(system, state) {
+    await system.writeFile(PATHS.previewsState, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o644 });
+}
+/** The server's GitHub token, for a read-only clone as the autopilot user (design §2.5). */
+export async function githubToken(system) {
+    const token = parseEnvFile(await system.readFile(PATHS.githubEnv)).GITHUB_TOKEN;
+    return token || undefined;
+}
+/** Deploys (or redeploys) one run's branch, keeping its port and URL stable. */
+export async function deployPreview(run, deps) {
+    const { system } = deps;
+    const { repository, branch } = run;
+    if (!repository || !branch)
+        throw new Error("That task has no branch to preview yet; it pushes one when it finishes a step.");
+    const id = previewId(run.conversationId);
+    const directory = join(PATHS.previews, id);
+    const state = await readPreviews(system);
+    const existing = state.previews.find((preview) => preview.id === id);
+    const port = existing?.port ?? freePort(state.previews);
+    if (port === undefined)
+        throw new Error(`All ${MAX_PREVIEWS} preview slots are in use. Remove one: dl preview <id> --remove`);
+    await syncCheckout(system, { repository, branch, directory }, deps.token);
+    if (!(await isWranglerCheckout(system, directory))) {
+        throw new Error(`${repository} at ${branch} has no wrangler.json, wrangler.jsonc or wrangler.toml at its root, so there's nothing to preview.`);
+    }
+    await system.writeFile(join(directory, "sobjects.toml"), sobjectsToml({ bucket: bucketFor(deps.bucket, id), port }), {
+        mode: 0o644,
+        owner: `${USERS.autopilot}:${USERS.autopilot}`,
+    });
+    const env = { SOBJECTS_STATE_DIR: join(directory, "state") };
+    await system.run("sobjects", ["deploy", directory], { env, describe: `sobjects deploy ${id}` });
+    await system.run("sobjects", ["up", "--detach"], { env, cwd: directory, describe: `sobjects up ${id}` });
+    const wait = deps.waitForPort ?? ((target) => waitForPort(system, target));
+    if (!(await wait(port)))
+        throw new Error(`The preview started but nothing answered on 127.0.0.1:${port}. Check its log: dl logs`);
+    const preview = {
+        id,
+        conversationId: run.conversationId,
+        repository,
+        branch,
+        port,
+        directory,
+        createdAt: (deps.now?.() ?? new Date()).toISOString(),
+    };
+    await writePreviews(system, { version: 1, previews: [...state.previews.filter((entry) => entry.id !== id), preview] });
+    return preview;
+}
+/** Stops a preview's node and deletes its checkout and state. */
+export async function removePreview(id, system) {
+    const state = await readPreviews(system);
+    const preview = state.previews.find((entry) => entry.id === id);
+    if (!preview)
+        return false;
+    await system.run("sobjects", ["down"], {
+        cwd: preview.directory,
+        env: { SOBJECTS_STATE_DIR: join(preview.directory, "state") },
+        allowFailure: true,
+        describe: `sobjects down ${id}`,
+    });
+    await system.remove(preview.directory);
+    await writePreviews(system, { version: 1, previews: state.previews.filter((entry) => entry.id !== id) });
+    return true;
+}
+async function syncCheckout(system, input, token) {
+    const owner = `${USERS.autopilot}:${USERS.autopilot}`;
+    const env = { GITHUB_TOKEN: token };
+    if (!(await system.exists(input.directory))) {
+        await system.mkdir(PATHS.previews, { owner });
+        await system.run("runuser", ["-u", USERS.autopilot, "--", "git", ...cloneArgs(input.repository, input.branch, input.directory)], {
+            env,
+            describe: `clone ${input.repository}`,
+        });
+        return;
+    }
+    await system.run("runuser", ["-u", USERS.autopilot, "--", "git", "-C", input.directory, ...fetchArgs(input.branch)], {
+        env,
+        describe: `fetch ${input.branch}`,
+    });
+    await system.run("runuser", ["-u", USERS.autopilot, "--", "git", "-C", input.directory, "reset", "--hard", "FETCH_HEAD"], {
+        describe: `reset ${input.branch}`,
+    });
+}
+async function isWranglerCheckout(system, directory) {
+    const listing = await system.probe("ls", ["-1", directory]);
+    return listing.code === 0 && isWranglerProject(listing.stdout.split("\n").map((line) => line.trim()).filter(Boolean));
+}
+async function waitForPort(system, port, attempts = 30) {
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        const answer = await system.probe("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", "2", `http://127.0.0.1:${port}/`]);
+        const code = answer.stdout.trim();
+        if (answer.code === 0 && code !== "" && code !== "000")
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 1_000));
+    }
+    return false;
+}
+/** `dl preview <id> [--remove] [--json]`: deploy a run's branch, or stop its preview. */
+export async function previewCommand(system, args, options, write, c) {
+    const id = args.find((arg) => !arg.startsWith("-"));
+    if (!id) {
+        write(`  Usage: dl preview <id>   ${c.dim("(from dl runs)")}   ${c.dim("--remove stops it")}\n`);
+        return 2;
+    }
+    if (args.includes("--remove")) {
+        const removed = await removePreview(id, system);
+        if (options.json)
+            write(`${JSON.stringify({ id, removed })}\n`);
+        else
+            write(`\n  ${removed ? c.green("✓") : c.red("✗")} ${removed ? `Removed the preview for ${id}` : `No preview for ${id}`}\n\n`);
+        return removed ? 0 : 1;
+    }
+    const runs = await listServerRuns(system, 200);
+    if (runs === undefined) {
+        write(`\n  ${c.red("✗")} Couldn't list runs; run ${c.bold("dl up")} to update this server.\n\n`);
+        return 1;
+    }
+    const matches = runs.filter((run) => run.conversationId.startsWith(id));
+    if (matches.length === 0) {
+        write(`\n  ${c.red("✗")} No task ${id}. ${c.dim("dl runs")} lists them.\n\n`);
+        return 1;
+    }
+    if (matches.length > 1) {
+        write(`\n  ${c.red("✗")} ${id} matches several tasks; use more characters.\n\n`);
+        return 1;
+    }
+    const token = await githubToken(system);
+    if (!token) {
+        write(`\n  ${c.red("✗")} This server has no GitHub token, so it can't clone the branch. Set one: ${c.bold("dl keys set github")}\n\n`);
+        return 1;
+    }
+    const bucket = options.bucket ?? process.env.DL_PREVIEWS_BUCKET;
+    if (!bucket) {
+        write(`\n  ${c.red("✗")} Previews need a bucket for their state. Set ${c.bold("DL_PREVIEWS_BUCKET")} in ${c.dim(PATHS.autopilotEnv)} (e.g. s3://my-previews).\n\n`);
+        return 1;
+    }
+    const preview = await deployPreview(matches[0], { system, bucket, token });
+    if (options.json) {
+        write(`${JSON.stringify({ id: preview.id, port: preview.port, url: `http://127.0.0.1:${preview.port}` })}\n`);
+        return 0;
+    }
+    write(`\n  ${c.green("✓")} ${preview.id} is live at ${c.bold(`http://127.0.0.1:${preview.port}`)}\n`);
+    write(`  ${c.dim("From your laptop:")} dl preview ${preview.id}   ${c.dim("Stop it:")} dl preview ${preview.id} --remove\n\n`);
+    return 0;
+}
+/** `dl previews`: the live previews, newest first. */
+export async function previewsCommand(system, write, c) {
+    const { previews } = await readPreviews(system);
+    if (previews.length === 0) {
+        write(`\n  No previews. From a task's branch:  ${c.bold("dl preview <id>")}\n\n`);
+        return 0;
+    }
+    write("\n");
+    for (const preview of [...previews].sort((a, b) => b.createdAt.localeCompare(a.createdAt))) {
+        write(`  ${c.green("●")} ${preview.id}  ${c.dim(`:${preview.port}`)}  ${(preview.repository ?? "").padEnd(28)} ${c.dim(preview.branch)}\n`);
+    }
+    write(`\n  ${c.dim("Open one from your laptop:")} dl preview <id>   ${c.dim("Stop one:")} dl preview <id> --remove\n\n`);
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "directionallylocal",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Directionally Local: background coding agents on your own server. One-line server install, and the dl command for your server and laptop.",
   "license": "Apache-2.0",
   "homepage": "https://directionallylocal.com",
@@ -27,8 +27,10 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit && tsc -p site/tsconfig.json",
-    "test": "tsx --test \"src/**/*.test.ts\" \"site/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit && tsc -p site/tsconfig.json && tsc -p services/tsconfig.json",
+    "test": "tsx --test \"src/**/*.test.ts\" \"site/**/*.test.ts\" \"services/**/*.test.ts\"",
+    "sync:site-script": "node site/generate-install-script.mjs",
+    "check:portable": "node scripts/check-portable-apis.mjs services/name services/shared",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "devDependencies": {