directionallylocal 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# Directionally Local installer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```sh
+curl -fsSL https://directionallylocal.run | sh
+```
+
+It asks three things:
+
+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.
+
+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
+```
+
+Then, on your laptop:
+
+```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
+```
+
+Typing `dl` on its own explains what it is and what's going on, on the server and on the laptop.
+
+The "fits ~N agents" figure is a conservative estimate from memory and CPUs (1 GB per sandbox). Measured numbers will replace it.
+
+## Commands
+
+Run these as root on the server. `dl` is short for `directionallylocal`; both work.
+
+| 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 doctor` | Check every part, with a fix for each failure. |
+| `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.
+
+## What it sets up
+
+- **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.
+- **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`.
+
+Supported: Ubuntu 24.04 and 22.04 and Debian 12, on x86_64 or arm64, with at least 4 GB of RAM and 15 GB free under `/var`.
+
+## The install script's address
+
+`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`.
+
+## Development
+
+```sh
+npm install
+npm test          # node:test through tsx; a simulated server exercises up, doctor, and uninstall
+npm run typecheck
+npm run build
+```

package/bin/directionallylocal.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/dist/cli.js

@@ -0,0 +1,272 @@
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { doctor, formatChecks } from "./doctor.js";
+import { briefStatus, connectLaptop, laptopsCommand, logsCommand, serverHome, serverRunsCommand } from "./home.js";
+import { cancel, connect, describeError, laptopHome, pull, run, runs, servers, watch } from "./laptop/commands.js";
+import { TtyPrompter } from "./prompt.js";
+import { readState } from "./state.js";
+import { DryRunSystem, RealSystem } from "./system.js";
+import { uninstall } from "./uninstall.js";
+import { PlainUi, TerminalUi, palette } from "./ui.js";
+import { up } from "./up.js";
+const HELP = `Directionally Local: background coding agents on your own server.
+Send a task from your laptop; it runs in its own sandbox and comes back as a pull request.
+(dl is short for directionallylocal; both work.)
+
+On your laptop:
+  dl connect URL          connect to your server (approve the code it shows)
+  dl run "TASK"           run a task on the server, from inside a GitHub repository
+                          (your uncommitted changes go along; Ctrl-C stops watching, not the task)
+  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 servers              connected servers (dl servers remove NAME)
+  run options: --server NAME, -m MODEL, --repo OWNER/NAME, --detach
+
+On the server:
+  dl                      what this is, whether it's healthy, laptops, and runs
+  dl up [--dry-run]       install, or repair, everything (safe to re-run)
+  dl connect-laptop       how to connect a laptop, and a link to approve it in a browser
+  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 logs [hotcell|autopilot] [-f]   the services' logs
+  dl doctor               check every part, with a fix for each problem
+  dl uninstall [--purge]  remove everything (--purge also removes config and data)
+
+up options:
+  --autopilot-version <x.y.z>   default: latest on npm
+  --hotcell-version <x.y.z>     default: latest on npm
+
+Unattended installs answer the questions with environment variables:
+  DL_TAILSCALE_AUTH_KEY   Tailscale auth key (tskey-…), unless this machine is already on a tailnet
+  DL_OPENROUTER_API_KEY   model key, stored in Hotcell only
+  DL_GITHUB_TOKEN         GitHub token for cloning, pushing, and opening PRs
+
+Advanced:
+  DL_ACCESS=loopback          don't expose the server; reach it over an SSH tunnel
+  DL_SKIP_CREDENTIAL_CHECK=1  don't check the keys with OpenRouter and GitHub (offline installs)
+`;
+export async function main(argv, io = {
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+}, options = {}) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                "dry-run": { type: "boolean" },
+                purge: { type: "boolean" },
+                "autopilot-version": { type: "string" },
+                "hotcell-version": { type: "string" },
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+                brief: { type: "boolean" },
+                follow: { type: "boolean", short: "f" },
+                name: { type: "string" },
+                "no-open": { type: "boolean" },
+                server: { type: "string" },
+                model: { type: "string", short: "m" },
+                repo: { type: "string" },
+                detach: { type: "boolean" },
+                json: { type: "boolean" },
+            },
+        });
+    }
+    catch (error) {
+        io.err(`${error.message}\n\n${HELP}`);
+        return 2;
+    }
+    const [command] = parsed.positionals;
+    const { values } = parsed;
+    if (values.version) {
+        io.out(`${packageVersion()}\n`);
+        return 0;
+    }
+    if (values.help || command === "help") {
+        io.out(HELP);
+        return 0;
+    }
+    const log = (line) => io.out(`${line}\n`);
+    // The live checklist needs a terminal; a dry run prints its plan line by line instead.
+    const terminal = options.terminal ?? (process.stdout.isTTY === true);
+    const live = terminal && command === "up" && !values["dry-run"];
+    const ui = live ? new TerminalUi(io.out) : new PlainUi(io.out);
+    const colorOn = terminal && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+    const colors = palette(colorOn);
+    const laptopIO = { out: io.out, err: io.err, color: colorOn };
+    const system = values["dry-run"] ? new DryRunSystem(log) : new RealSystem(log, live ? { outputLog: UP_LOG } : {});
+    try {
+        switch (command) {
+            case "up":
+                if (system.dryRun)
+                    log("Dry run: nothing on this machine will change.\n");
+                await up(system, {
+                    prompter: new TtyPrompter(),
+                    ui,
+                    ...(values["autopilot-version"] ? { autopilotVersion: values["autopilot-version"] } : {}),
+                    ...(values["hotcell-version"] ? { hotcellVersion: values["hotcell-version"] } : {}),
+                });
+                return 0;
+            case "doctor": {
+                const checks = await doctor(system);
+                log(formatChecks(checks, terminal && !process.env.NO_COLOR));
+                return checks.every((check) => check.ok) ? 0 : 1;
+            }
+            case undefined:
+            case "status": {
+                const state = await readState(system);
+                if (!state) {
+                    if (values.brief)
+                        return 0;
+                    // A laptop connected to servers gets its own home; otherwise, what this is and how to start.
+                    if (!command && await laptopHome(laptopIO))
+                        return 0;
+                    io.out(NOT_A_SERVER(colors));
+                    return command ? 1 : 0;
+                }
+                if (values.brief) {
+                    await briefStatus(system, state, io.out, colors);
+                    return 0;
+                }
+                if (!isRoot()) {
+                    await briefStatus(system, state, io.out, colors);
+                    io.out(`  ${colors.dim("For laptops and runs:")} sudo dl\n\n`);
+                    return 0;
+                }
+                await serverHome(system, state, io.out, colors);
+                return 0;
+            }
+            case "connect": {
+                const url = parsed.positionals[1];
+                if (!url) {
+                    io.err(`  Usage: dl connect https://your-server   ${colors.dim("(the address dl up printed on the server)")}\n`);
+                    return 2;
+                }
+                await interruptible((signal) => connect({ url, signal, open: !values["no-open"], ...(values.name ? { name: values.name } : {}) }, laptopIO));
+                return 0;
+            }
+            case "run": {
+                const task = parsed.positionals.slice(1).join(" ").trim();
+                if (!task) {
+                    io.err(`  Usage: dl run "fix the flaky checkout test"   ${colors.dim("(from inside a GitHub repository)")}\n`);
+                    return 2;
+                }
+                return await interruptible((signal) => run({
+                    task,
+                    cwd: process.cwd(),
+                    signal,
+                    detach: Boolean(values.detach),
+                    ...(values.server ? { server: values.server } : {}),
+                    ...(values.model ? { model: values.model } : {}),
+                    ...(values.repo ? { repository: values.repo } : {}),
+                }, laptopIO));
+            }
+            case "watch":
+            case "cancel":
+            case "pull": {
+                const id = parsed.positionals[1];
+                if (!id) {
+                    io.err(`  Usage: dl ${command} ID   ${colors.dim("(from dl runs)")}\n`);
+                    return 2;
+                }
+                const server = values.server ? { server: values.server } : {};
+                if (command === "watch")
+                    return await interruptible((signal) => watch({ id, signal, ...server }, laptopIO));
+                if (command === "cancel")
+                    await cancel({ id, ...server }, laptopIO);
+                else
+                    await pull({ id, cwd: process.cwd(), ...server }, laptopIO);
+                return 0;
+            }
+            case "servers":
+                return await servers(parsed.positionals.slice(1), laptopIO);
+            case "runs":
+                // On a server, its runs; on a laptop, the tasks it sent.
+                if (!(await readState(system))) {
+                    await runs({ json: Boolean(values.json), ...(values.server ? { server: values.server } : {}) }, laptopIO);
+                    return 0;
+                }
+            // falls through
+            case "connect-laptop":
+            case "laptops":
+            case "logs": {
+                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 ${parsed.positionals.join(" ")}\n`);
+                    return 1;
+                }
+                const rest = parsed.positionals.slice(1);
+                if (command === "connect-laptop")
+                    return await connectLaptop(system, state, rest[0], io.out, colors);
+                if (command === "laptops")
+                    return await laptopsCommand(system, rest, io.out, colors);
+                if (command === "runs")
+                    return await serverRunsCommand(system, io.out, colors);
+                return await logsCommand(system, [...rest, ...(values.follow ? ["-f"] : [])]);
+            }
+            case "uninstall":
+                await uninstall(system, { purge: Boolean(values.purge) });
+                return 0;
+            default:
+                io.err(`Unknown command "${command}".\n\n${HELP}`);
+                return 2;
+        }
+    }
+    catch (error) {
+        ui.finish();
+        const c = palette(live && !process.env.NO_COLOR);
+        io.err(`\n  ${c.red("✗")} ${describeError(error).replace(/\n/g, "\n    ")}\n`);
+        if (live)
+            io.err(await logTail(UP_LOG, c));
+        return 1;
+    }
+}
+const NOT_A_SERVER = (c) => `
+  ${c.bold("Directionally Local")}  ${c.dim("isn't set up on this machine.")}
+
+  Background coding agents on your own server: send a task from your laptop,
+  get a pull request back.
+
+  ${c.dim("Set up a server (as root, on Ubuntu or Debian):")}
+     curl -fsSL https://directionallylocal.run | sh
+
+  ${c.dim("Already have one? Connect this laptop to it:")}
+     dl connect https://your-server
+
+`;
+/** Ctrl-C aborts the command (a running task keeps going on the server). */
+async function interruptible(work) {
+    const controller = new AbortController();
+    const onInterrupt = () => controller.abort();
+    process.once("SIGINT", onInterrupt);
+    try {
+        return await work(controller.signal);
+    }
+    finally {
+        process.off("SIGINT", onInterrupt);
+    }
+}
+function isRoot() {
+    return process.getuid?.() === 0;
+}
+/** From package.json, which sits one level above both src/ and dist/. */
+function packageVersion() {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+}
+/** Where `dl up` keeps other tools' output; shown only when something fails. */
+export const UP_LOG = "/var/log/directionallylocal/up.log";
+async function logTail(path, c) {
+    const text = await readFile(path, "utf8").catch(() => "");
+    const lines = text.trimEnd().split("\n").filter((line) => line.trim() && !line.startsWith("#")).slice(-15);
+    if (lines.length === 0)
+        return "";
+    return `\n  ${c.dim(`Last lines of ${path}:`)}\n${lines.map((line) => `    ${c.dim(line.slice(0, 200))}`).join("\n")}\n\n  Fix it and run ${c.bold("dl up")} again; it picks up where it stopped.\n`;
+}

package/dist/detect.js

@@ -0,0 +1,94 @@
+import { nodeAdvisory } from "./node-advisory.js";
+/** v0 supports the Ubuntu/Debian releases the issue targets; others get a clear refusal. */
+const SUPPORTED_OS = {
+    ubuntu: ["22.04", "24.04"],
+    debian: ["12"],
+};
+export const MIN_MEMORY_MB = 3_500;
+export const MIN_DISK_GB = 15;
+export async function detectHost(system) {
+    const [osRelease, meminfo, nproc, df, arch, kvm, systemd, uid, docker, bridge, node, tailscale, dockerd] = await Promise.all([
+        system.readFile("/etc/os-release"),
+        system.readFile("/proc/meminfo"),
+        system.probe("nproc", []),
+        system.probe("df", ["-Pk", "/var"]),
+        system.probe("uname", ["-m"]),
+        system.exists("/dev/kvm"),
+        system.exists("/run/systemd/system"),
+        system.probe("id", ["-u"]),
+        system.probe("docker", ["version", "--format", "{{.Server.Version}}"]),
+        system.probe("ip", ["-4", "-o", "addr", "show", "docker0"]),
+        system.probe("node", ["-p", "process.versions.node"]),
+        system.probe("tailscale", ["version"]),
+        system.exists("/usr/bin/dockerd"),
+    ]);
+    return {
+        os: parseOsRelease(osRelease ?? ""),
+        arch: arch.stdout.trim(),
+        memoryMb: parseMemTotalMb(meminfo ?? ""),
+        cpus: Number(nproc.stdout.trim()) || 0,
+        diskFreeGb: parseDfFreeGb(df.stdout),
+        kvm,
+        systemd,
+        root: uid.stdout.trim() === "0",
+        docker: docker.code === 0 && docker.stdout.trim() !== "",
+        dockerInstalled: dockerd,
+        dockerBridgeIp: parseInterfaceIp(bridge.stdout),
+        nodeVersion: node.code === 0 && node.stdout.trim() ? node.stdout.trim() : undefined,
+        tailscale: tailscale.code === 0,
+    };
+}
+/** Problems that stop `up` before it changes anything. */
+export function preflightProblems(facts) {
+    const problems = [];
+    if (!facts.root)
+        problems.push("Run as root (sudo dl up).");
+    if (!facts.systemd)
+        problems.push("systemd is required to run the services.");
+    const versions = SUPPORTED_OS[facts.os.id];
+    if (!versions?.includes(facts.os.versionId)) {
+        problems.push(`${facts.os.prettyName || "This OS"} isn't supported yet; use Ubuntu 24.04 or 22.04, or Debian 12.`);
+    }
+    if (facts.arch !== "x86_64" && facts.arch !== "aarch64")
+        problems.push(`CPU architecture ${facts.arch} isn't supported.`);
+    if (facts.memoryMb < MIN_MEMORY_MB)
+        problems.push(`At least 4 GB of RAM is needed (found ${(facts.memoryMb / 1024).toFixed(1)} GB).`);
+    // The services run on this Node; never install onto one with a known RCE.
+    const node = nodeAdvisory(facts.nodeVersion ?? "");
+    if (!node.ok)
+        problems.push(`${node.message} Re-run install.sh, which upgrades Node.`);
+    if (facts.diskFreeGb < MIN_DISK_GB)
+        problems.push(`At least ${MIN_DISK_GB} GB free under /var is needed (found ${facts.diskFreeGb} GB).`);
+    return problems;
+}
+/**
+ * How many agents fit at once: memory left after the host's own share, divided by each
+ * sandbox's cap. A conservative estimate until the density benchmark (hotcell#17) lands.
+ */
+export function agentCapacity(facts, cellMemoryMb) {
+    const reservedMb = Math.max(1_536, Math.round(facts.memoryMb * 0.15));
+    const byMemory = Math.floor((facts.memoryMb - reservedMb) / cellMemoryMb);
+    const byCpu = Math.max(1, facts.cpus * 2);
+    return Math.max(1, Math.min(byMemory, byCpu));
+}
+export function parseOsRelease(text) {
+    const values = new Map();
+    for (const line of text.split("\n")) {
+        const match = line.match(/^([A-Z_]+)=(.*)$/);
+        if (match)
+            values.set(match[1], match[2].replace(/^"(.*)"$/, "$1"));
+    }
+    return { id: values.get("ID") ?? "", versionId: values.get("VERSION_ID") ?? "", prettyName: values.get("PRETTY_NAME") ?? "" };
+}
+export function parseMemTotalMb(text) {
+    const kb = Number(text.match(/^MemTotal:\s+(\d+)\s+kB/m)?.[1] ?? 0);
+    return Math.round(kb / 1024);
+}
+export function parseDfFreeGb(text) {
+    const fields = text.trim().split("\n")[1]?.trim().split(/\s+/);
+    const availableKb = Number(fields?.[3] ?? 0);
+    return Math.floor(availableKb / 1024 / 1024);
+}
+export function parseInterfaceIp(text) {
+    return text.match(/\binet (\d+\.\d+\.\d+\.\d+)\//)?.[1];
+}

package/dist/doctor.js

@@ -0,0 +1,72 @@
+import { detectHost, MIN_DISK_GB } from "./detect.js";
+import { nodeAdvisory } from "./node-advisory.js";
+import { AUTOPILOT_PORT, AUTO_UPGRADES, HOTCELL_PORT, NODE_AUTO_UPDATES, PATHS, SERVICES, parseEnvFile } from "./layout.js";
+import { readState } from "./state.js";
+import { palette } from "./ui.js";
+/** `directionallylocal doctor`: every moving part, with a fix for each failure. */
+export async function doctor(system) {
+    const checks = [];
+    const add = (check) => checks.push(check);
+    const state = await readState(system);
+    add(state
+        ? { name: "installed", ok: true, detail: `${state.release}, ${state.access.mode} at ${state.access.url}` }
+        : { name: "installed", ok: false, detail: "not installed", fix: "sudo dl up" });
+    const facts = await detectHost(system);
+    const node = nodeAdvisory(facts.nodeVersion ?? "");
+    add({
+        name: "node",
+        ok: node.ok && node.message === undefined,
+        detail: node.message ?? `${facts.nodeVersion} (patched)`,
+        fix: "re-run install.sh to upgrade Node.js (apt-get install --only-upgrade nodejs for a patch)",
+    });
+    const periodic = /APT::Periodic::Unattended-Upgrade\s+"1"/.test((await system.readFile(AUTO_UPGRADES)) ?? "");
+    const nodeUpdates = await system.exists(NODE_AUTO_UPDATES);
+    add({
+        name: "security updates",
+        ok: periodic && nodeUpdates,
+        detail: periodic && nodeUpdates ? "daily, including Node.js" : !periodic ? "unattended-upgrades is off" : "Node.js isn't included",
+        fix: "sudo dl up",
+    });
+    add({ name: "disk", ok: facts.diskFreeGb >= MIN_DISK_GB, detail: `${facts.diskFreeGb} GB free under /var`, fix: "free space: docker system prune, or grow the disk" });
+    add(facts.docker
+        ? { name: "docker", ok: true, detail: "running" }
+        : { name: "docker", ok: false, detail: "not running", fix: "dl up" });
+    // People read these, so they're named for what they do, not their systemd units.
+    for (const [service, name, logs] of [
+        [SERVICES.metadataBlock, "sandbox firewall", "dl up"],
+        [SERVICES.hotcell, "sandboxes", "dl logs hotcell · then dl up"],
+        [SERVICES.autopilot, "agent server", "dl logs autopilot · then dl up"],
+    ]) {
+        const active = (await system.probe("systemctl", ["is-active", service])).stdout.trim();
+        add({ name, ok: active === "active", detail: active === "active" ? "running" : active || "unknown", fix: logs });
+    }
+    const hotcell = await system.probe("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", `http://127.0.0.1:${HOTCELL_PORT}/`]);
+    add({ name: "sandboxes API", ok: /^\d{3}$/.test(hotcell.stdout.trim()) && hotcell.stdout.trim() !== "000", detail: `HTTP ${hotcell.stdout.trim() || "none"}`, fix: "dl up" });
+    const keys = await system.probe("runuser", ["-u", "hotcell", "--", "env", `HOTCELL_HOME=${PATHS.hotcellHome}`, "HOTCELL_KEYSTORE=file", "/usr/bin/node", `${PATHS.current}/node_modules/hotcell/dist/index.js`, "keys", "ls"]);
+    const hasModelKey = keys.code === 0 && /^\s*openrouter\b/m.test(keys.stdout);
+    add({ name: "model key", ok: hasModelKey, detail: hasModelKey ? "OpenRouter key in Hotcell" : "no OpenRouter key in Hotcell", fix: "sudo dl up (asks for it)" });
+    const github = Boolean(parseEnvFile(await system.readFile(PATHS.githubEnv)).GITHUB_TOKEN);
+    add({ name: "github", ok: github, detail: github ? "token configured" : "no token; runs can't push or open PRs", fix: "sudo dl up (asks for it)" });
+    const autopilot = (await system.probe("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", `http://127.0.0.1:${AUTOPILOT_PORT}/api/v1/health`])).stdout.trim();
+    add({ name: "agent server API", ok: autopilot === "401", detail: autopilot === "401" ? "up (refuses requests without a token)" : `HTTP ${autopilot || "none"}`, fix: "dl logs autopilot · then dl up" });
+    if (state?.access.mode === "tailscale") {
+        const serve = await system.probe("tailscale", ["serve", "status"]);
+        const serving = serve.code === 0 && serve.stdout.includes(`127.0.0.1:${AUTOPILOT_PORT}`);
+        add({ name: "private access", ok: serving, detail: serving ? `on ${state.access.url}` : "not published on your tailnet", fix: "dl up" });
+        const remote = await system.probe("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", "10", `${state.access.url}/api/v1/health`]);
+        add({ name: "reachable", ok: remote.stdout.trim() === "401", detail: `${state.access.url}: HTTP ${remote.stdout.trim() || "none"}`, fix: "turn on HTTPS certificates at https://login.tailscale.com/admin/dns" });
+    }
+    return checks;
+}
+export function formatChecks(checks, color = false) {
+    const c = palette(color);
+    const width = Math.max(...checks.map((check) => check.name.length)) + 2;
+    const rows = checks.map((check) => {
+        const glyph = check.ok ? c.green("✓") : c.red("✗");
+        const fix = !check.ok && check.fix ? `\n     ${c.dim(`fix: ${check.fix}`)}` : "";
+        return `  ${glyph} ${check.name.padEnd(width)}${check.ok ? c.dim(check.detail) : c.red(check.detail)}${fix}`;
+    });
+    const failed = checks.filter((check) => !check.ok).length;
+    const verdict = failed === 0 ? `${c.green("✓")} ${c.bold("All good")}` : `${c.red("✗")} ${c.bold(`${failed} to fix`)}`;
+    return `${rows.join("\n")}\n\n  ${verdict}`;
+}

package/dist/home.js

@@ -0,0 +1,126 @@
+import { agentCapacity, detectHost } from "./detect.js";
+import { AUTOPILOT_PORT, CELL_MEMORY_MB, SERVICES } from "./layout.js";
+import { approvePairing, listLaptops, listServerRuns, ownerLink, pendingPairings, revokeLaptop } from "./server-api.js";
+import { readState } from "./state.js";
+import { palette } from "./ui.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. */
+async function health(system) {
+    const problems = [];
+    for (const [unit, label] of [[SERVICES.hotcell, "sandboxes"], [SERVICES.autopilot, "agent server"]]) {
+        if ((await system.probe("systemctl", ["is-active", unit])).stdout.trim() !== "active")
+            problems.push(`${label} stopped`);
+    }
+    if (problems.length === 0) {
+        const code = (await system.probe("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", "3", `http://127.0.0.1:${AUTOPILOT_PORT}/api/v1/health`])).stdout.trim();
+        if (code !== "401")
+            problems.push("agent server not answering");
+    }
+    return { ok: problems.length === 0, problems };
+}
+/** `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 verdict = status.ok ? c.green("● healthy") : c.red(`● ${status.problems.join(", ")}`);
+    const week = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    const running = runs?.filter((run) => run.active).length ?? 0;
+    const doneThisWeek = runs?.filter((run) => !run.active && Date.parse(run.createdAt) >= week).length ?? 0;
+    const row = (label, value, hint = "") => `  ${c.dim(label.padEnd(11))}${value}${hint ? `   ${c.dim(hint)}` : ""}\n`;
+    write(`\n  ${c.bold("Directionally Local")}  ${verdict}  ${c.dim(state.access.url)}\n\n  ${ABOUT}\n\n`);
+    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 (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`);
+    }
+    write(`\n  ${c.dim("Connect a laptop")}   dl connect-laptop\n  ${c.dim("Something wrong?")}   dl doctor\n  ${c.dim("All commands")}       dl help\n\n`);
+}
+/** `dl status --brief`: one line, for the login message. Never slow, never fails loudly. */
+export async function briefStatus(system, state, write, c) {
+    const status = await health(system);
+    write(`\n  ${c.bold("Directionally Local")}  ${status.ok ? c.green("● healthy") : c.red(`● ${status.problems.join(", ")}`)}  ${c.dim(state.access.url)}\n  ${c.dim("Type")} dl ${c.dim("for what this is and what's running.")}\n\n`);
+}
+/**
+ * `dl connect-laptop [CODE]`: approve a laptop's code, or explain how to connect one and
+ * print a fresh browser link for approving them.
+ */
+export async function connectLaptop(system, state, code, write, c) {
+    if (code) {
+        const result = await approvePairing(system, code);
+        write(`\n  ${result.ok ? c.green("✓") : c.red("✗")} ${result.ok ? "Laptop approved. It finishes connecting on its own." : result.message}\n\n`);
+        return result.ok ? 0 : 1;
+    }
+    const pending = await pendingPairings(system);
+    if (pending.length > 0) {
+        write(`\n  ${c.bold("Waiting for approval")}\n${pending.map((entry) => `  ${c.bold(entry.code)}  ${entry.name}   ${c.dim(`dl connect-laptop ${entry.code}`)}`).join("\n")}\n`);
+    }
+    const link = await ownerLink(system, state.access.url);
+    write(`\n  ${c.bold("Connect a laptop")}\n`);
+    nextSteps({ url: state.access.url, ownerLink: link, access: state.access.mode }).slice(0, 2).forEach((item, index) => {
+        write(`\n  ${c.cyan(String(index + 1))}  ${item.label}\n${item.value.split("\n").map((line) => `     ${c.bold(line)}`).join("\n")}\n`);
+    });
+    write(`\n  ${c.dim("The laptop shows a code; approve it in that browser, or here with")} dl connect-laptop <code>\n\n`);
+    return 0;
+}
+export async function laptopsCommand(system, args, write, c) {
+    const laptops = await listLaptops(system);
+    if (laptops === undefined) {
+        write(`\n  ${c.red("✗")} Couldn't list laptops; run ${c.bold("dl up")} to update this server.\n\n`);
+        return 1;
+    }
+    if (args[0] === "remove") {
+        const target = args.slice(1).join(" ").trim().toLowerCase();
+        const matches = laptops.filter((laptop) => laptop.id === target || laptop.id.startsWith(target) || laptop.name.toLowerCase() === target);
+        if (!target || matches.length !== 1) {
+            write(`\n  ${c.red("✗")} ${matches.length > 1 ? "That matches several laptops; use its id from dl laptops." : `No laptop named "${target}".`}\n\n`);
+            return 1;
+        }
+        const ok = await revokeLaptop(system, matches[0].id);
+        write(`\n  ${ok ? c.green("✓") : c.red("✗")} ${ok ? `Disconnected ${matches[0].name}. It can't reach this server any more.` : "Couldn't disconnect it."}\n\n`);
+        return ok ? 0 : 1;
+    }
+    if (laptops.length === 0) {
+        write(`\n  No laptops connected yet.   ${c.dim("dl connect-laptop")}\n\n`);
+        return 0;
+    }
+    write("\n");
+    for (const laptop of laptops) {
+        const used = laptop.lastUsedAt ? `last used ${laptop.lastUsedAt.slice(0, 10)}` : "not used yet";
+        write(`  ${c.green("●")} ${laptop.name.padEnd(28)} ${c.dim(`${used} · ${laptop.id.slice(0, 8)}`)}\n`);
+    }
+    write(`\n  ${c.dim("Disconnect one:")} dl laptops remove <name>\n\n`);
+    return 0;
+}
+export async function serverRunsCommand(system, write, c) {
+    const runs = await listServerRuns(system, 50);
+    if (runs === undefined) {
+        write(`\n  ${c.red("✗")} Couldn't list runs; run ${c.bold("dl up")} to update this server.\n\n`);
+        return 1;
+    }
+    if (runs.length === 0) {
+        write(`\n  No runs yet. From a laptop:  ${c.bold('dl run "fix the flaky checkout test"')}\n\n`);
+        return 0;
+    }
+    write("\n");
+    for (const run of runs)
+        write(formatRun(run, c));
+    write("\n");
+    return 0;
+}
+export function formatRun(run, c) {
+    const glyph = run.active ? c.cyan("◐") : run.status === "completed" || run.status === "merged" ? c.green("✓") : run.status === "failed" || run.status === "interrupted" ? c.red("✗") : c.dim("○");
+    const where = run.pullRequestURL ?? run.branch ?? "";
+    return `  ${glyph} ${run.conversationId.slice(0, 8)}  ${(run.active ? "running" : run.status).padEnd(11)} ${(run.repository ?? "").padEnd(28)} ${c.dim(where)}${run.startedBy ? c.dim(`  · ${run.startedBy}`) : ""}\n`;
+}
+/** `dl logs [hotcell|autopilot] [-f]`: the services' logs, without knowing their unit names. */
+export async function logsCommand(system, args) {
+    const follow = args.includes("-f") || args.includes("--follow");
+    const which = args.find((arg) => !arg.startsWith("-"));
+    const units = which === "hotcell" ? [SERVICES.hotcell] : which === "autopilot" ? [SERVICES.autopilot] : [SERVICES.hotcell, SERVICES.autopilot];
+    const result = await system.run("journalctl", [...units.flatMap((unit) => ["-u", unit]), "-n", "80", "--no-pager", ...(follow ? ["-f"] : [])], { inherit: true, allowFailure: true });
+    return result.code;
+}
+export { readState };