@kdonev/termscape 0.1.9 → 0.2.1

package/README.md

@@ -1,55 +1,89 @@
 # Termscape
 
-Run a crew of AI coding agents on one infinite canvas, and let them talk to
+Run a crew of AI coding agents side by side on one canvas, and let them talk to
 each other.
 
-Each terminal window on the canvas runs an agent CLI wired to an MCP server the
-hub exposes. Agents can look each other up, send each other messages, spawn
-helpers into their workspace, and check on each other's terminals. A message
-from one agent is delivered by typing it into the other's terminal, immediately.
+![Agents on a Termscape canvas messaging each other](https://raw.githubusercontent.com/kdonev/termscape/main/docs/intro.gif)
 
-Local-first: the hub runs on your machine and the UI opens in a window of its
-own — the same web page a browser would show. It binds
-every interface, so the canvas opens on your phone or a second screen as well —
-with its token — and another machine can attach itself from the join page.
-`--listen loopback` keeps the whole thing to this machine. Other machines run
-the same hub as a daemon and appear on the same canvas.
+## What it's for
 
-## Getting started
+Running several coding agents at once usually means a pile of terminal tabs
+that know nothing about each other, with you copying text between them.
+Termscape puts them all in one place and lets them work together:
+
+- **See every agent at once.** Each agent is a live terminal on a zoomable
+  canvas, grouped by project.
+- **Let agents talk to each other.** An agent can message another, ask it for
+  a review, or start a helper to take part of the work.
+- **Pick up where you left off.** Close Termscape and start it again: the
+  canvas comes back, and your agents can continue their conversations.
+- **Use more than one machine.** Agents on another computer appear on the same
+  canvas and are messaged the same way.
+- **Check in from anywhere.** Open the canvas on your phone or a second screen,
+  or share a single terminal with a colleague.
+
+Works with Claude Code, Codex, Gemini CLI, Kilo Code and opencode.
+
+## Quick start
+
+You need Node 24 or newer and at least one agent CLI, such as
+[Claude Code](https://claude.com/claude-code). Then run:
 
 ```bash
 npx @kdonev/termscape
 ```
 
-That starts the hub and opens the canvas in a window of its own. The window is
-the app: closing it stops the hub, saving state first, just as Ctrl+C in the
-terminal would. `--browser` opens the canvas in a browser tab instead, which
-the hub outlives, and `--no-open` opens nothing; the URL is printed either
-way. Nothing is installed system-wide: state lives in `~/.termscape`, and
-deleting that directory is the uninstall.
-
-The window is the operating system's own webview — WebView2 on Windows,
-WebKit on macOS, WebKitGTK on Linux — so there is no browser bundled with it.
-Linux needs WebKitGTK 4.1 and libxdo (`sudo apt install libwebkit2gtk-4.1-0
-libxdo3` on Debian and Ubuntu). Where no webview can be loaded, the hub says
-why and opens the browser instead.
-
-The hub is reachable from your network, so the same URL — token and all — opens
-the canvas on a phone or a second screen, and the **+ machine** dialog already
-has a join link in it for the second machine; see
-[Adding another machine](#adding-another-machine). To keep the hub to this
-machine entirely — no join page, nothing off 127.0.0.1:
+The canvas opens in a window of its own; close the window to stop Termscape.
+Nothing is installed system-wide. To remove it, delete `~/.termscape`.
+
+On Linux, install WebKitGTK first (`sudo apt install libwebkit2gtk-4.1-0
+libxdo3` on Debian and Ubuntu), or the canvas opens in your browser instead.
+
+## Quick tour
+
+1. **Add a workspace.** Click **machines** in the top bar, then
+   **+ workspace**, and pick a project folder.
+2. **Start an agent.** Click **+ agent** on the workspace and choose one, such
+   as `claude`. Its terminal appears on the canvas, and you use it as you
+   would in any terminal.
+3. **Start a second one** in the same workspace.
+4. **Let them work together.** Just ask, in plain words: *"ask the other agent
+   to review your last change"*. The message shows up in the other agent's
+   terminal with the sender's name, and the answer comes back the same way.
+   Agents can also start helpers of their own.
+5. **Find your way around.** Scroll to pan, **Ctrl/⌘ + scroll** to zoom,
+   **Ctrl/⌘ + 1** to see everything, **Ctrl/⌘ + 2** to zoom in on one
+   terminal. Clicking an agent in the panel takes you to it.
+6. **See what was said.** **messages** in the top bar lists every message the
+   agents have sent each other.
+7. **Come back later.** Stop Termscape and start it again. The canvas returns
+   as you left it, and **resume** on a window continues that agent's
+   conversation. (Agents that can't continue one show **restart** instead.)
+
+That's the core of it. The sections below cover the details.
+
+## Starting options
+
+The window is the app: closing it stops Termscape, saving state first, just as
+Ctrl+C in the terminal would. `--browser` opens the canvas in a browser tab
+instead, which Termscape outlives, and `--no-open` opens nothing; the URL is
+printed either way. State lives in `~/.termscape`.
+
+The window is the operating system's own webview (WebView2 on Windows, WebKit
+on macOS, WebKitGTK on Linux), so no browser is bundled. Where no webview can
+be loaded, Termscape says why and opens the browser instead.
+
+The canvas is reachable from your network with its token, so the same URL
+opens it on a phone or a second screen, and the **+ machine** dialog has a join
+link for adding another computer (see
+[Adding another machine](#adding-another-machine)). To keep everything on this
+machine only:
 
 ```bash
 npx @kdonev/termscape --listen loopback
 ```
 
-Slide out the **machines** panel: every machine, the workspaces on it, and
-the agents in each. Point a workspace at a folder there, and start an agent
-in it. Adding, editing and removing all open a dialog over the canvas, so the
-node you acted on stays where it was and a refusal — a folder that is not
-there, a rename the addresses will not allow — arrives in the dialog next to
-the field, with what you typed still in it.
+## Using the canvas
 
 - **Scroll** to pan, **Ctrl/⌘ + scroll** to zoom, **Ctrl/⌘ + 1** to fit,
   **Ctrl/⌘ + 2** to zoom to one terminal
@@ -57,12 +91,16 @@ the field, with what you typed still in it.
   navigates instead of zooming: in over a terminal maximizes it, out steps
   back to the workspace around it and then to everything. Zooming at any
   ordinary pace is left alone
-- Every window shows its real terminal at every zoom; the text minifies
-  rather than being replaced by a card, so a zoomed-out canvas still shows
-  the shape of what each agent is doing
-- Clicking an agent in the panel brings the canvas to it
+- Every window shows its real terminal at every zoom; the text shrinks rather
+  than being replaced by a card, so a zoomed-out canvas still shows the shape
+  of what each agent is doing
+- The **machines** panel lists every machine, the workspaces on it, and the
+  agents in each. Clicking an agent brings the canvas to it
 - Clicking the canvas closes the panel, as does **Escape** — which closes the
   panel first and clears the selection only once it is shut
+- Adding, editing and removing open a dialog over the canvas; if something is
+  refused, such as a folder that does not exist, the reason appears next to
+  the field with what you typed still in it
 - **share** on a window's title bar hands a reviewer a link to that one
   terminal, live, with nothing else on the canvas visible to them — see
   [Security](#security) for what the link actually grants
@@ -73,7 +111,8 @@ the field, with what you typed still in it.
   needs 22)
 - An agent CLI on your `PATH` — [Claude Code](https://claude.com/claude-code)
   is the profile that ships configured
-- macOS, Windows, or Linux
+- macOS, Windows, or Linux; on Linux, WebKitGTK 4.1 and libxdo for the app
+  window
 
 Everything native is prebuilt on all three platforms, so no compiler is
 needed.
@@ -91,10 +130,11 @@ Hub (Node)
 Remote hub (same binary, --headless)
 ```
 
+Each terminal window runs an agent CLI wired to an MCP server the hub exposes.
 Agents never talk to each other directly. They call `send_message` on their own
-hub; the hub does the delivery, locally or by forwarding to a peer. That is why
-an agent addresses a peer on another machine exactly as it addresses one in the
-next window.
+hub; the hub does the delivery, locally or by forwarding to a peer, by typing
+the message into the other agent's terminal. That is why an agent addresses a
+peer on another machine exactly as it addresses one in the next window.
 
 ## Adding another machine
 
@@ -411,6 +451,31 @@ Two consequences worth knowing:
 - Resume relaunches in the **same working directory**, because that is how
   Claude Code finds a conversation. Move the folder and resume starts fresh.
 
+## Updating
+
+The hub asks npm for a newer release shortly after it starts and every six
+hours after that. When there is one, an **update** button appears next to the
+version in the top bar. Nothing restarts until you press it. Then the hub
+downloads the release, restarts on the same address in the same terminal,
+and the canvas reconnects on its own. The agents that were running stop with
+the old hub and are resumed by the new one, continuing their conversations.
+(Stopping the hub yourself is different: those agents come back stopped, as
+described under [State and restart](#state-and-restart).)
+
+This works for `npx @kdonev/termscape` and for a global `npm install -g`. A
+checkout of this repository updates the way checkouts do, so for one of those
+the button only links to the release. `--no-update-check` (or
+`TERMSCAPE_NO_UPDATE_CHECK=1`) turns the check off.
+
+Other machines take the canvas's own build, not npm's. When one runs a
+different version from the canvas, its row in the machines panel gets an
+**update** button, so you pick when each machine restarts. A deployed machine
+is redeployed over SSH. A joined one runs the join installer again by itself
+(its output is in `~/.termscape/update.log` there) and rejoins as the same
+machine. Either way, the agents that were running there are resumed. A joined machine one protocol version behind the canvas stays on the
+canvas as *outdated* until you update it. Machines joined with 0.1.9 or
+earlier can't update themselves yet, so re-run the join command on those once.
+
 ## Remote machines
 
 Add a machine in the panel. The hub is copied over SSH, installed, and started as a
@@ -449,7 +514,8 @@ could be talked into sending an attacker's text to a peer.
 - `--dangerously-skip-permissions` is never a default.
 - A share link is a real grant of a keyboard on an agent that can run
   commands, not a read-only view — the dialog says so before you copy one.
-  It opens exactly one terminal and nothing else: no canvas, no other agent's
+  That includes pasting images: each one is written, capped at 5 MB, to a file
+  under that session's own directory in `~/.termscape/run`. It opens exactly one terminal and nothing else: no canvas, no other agent's
   name, no panel. It is scoped to that one session everywhere the canvas
   token is checked, stored in `state.db` so it survives a hub restart, and
   reachable only on the interfaces the hub bound — a hub started with

package/dist/cli-args.d.ts

@@ -1,3 +1,4 @@
+import type { parseArgs } from 'node:util';
 /**
  * The hub's command line, in a module of its own.
  *
@@ -53,6 +54,10 @@ export declare const CLI_OPTIONS: {
         readonly type: "boolean";
         readonly default: false;
     };
+    readonly 'no-update-check': {
+        readonly type: "boolean";
+        readonly default: false;
+    };
     readonly version: {
         readonly type: "boolean";
         readonly default: false;
@@ -62,4 +67,9 @@ export declare const CLI_OPTIONS: {
         readonly default: false;
     };
 };
+/** What `parseArgs` makes of CLI_OPTIONS. */
+export type CliValues = ReturnType<typeof parseArgs<{
+    options: typeof CLI_OPTIONS;
+    strict: true;
+}>>['values'];
 //# sourceMappingURL=cli-args.d.ts.map

package/dist/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAeoD,CAAC"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiBoD,CAAC;AAE7E,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,UAAU,CAChC,OAAO,SAAS,CAAC;IAAE,OAAO,EAAE,OAAO,WAAW,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC,CAChE,CAAC,QAAQ,CAAC,CAAC"}

package/dist/cli-args.js

@@ -31,6 +31,8 @@ export const CLI_OPTIONS = {
     'no-open': { type: 'boolean', default: false },
     // The canvas opens in a window of its own unless this asks for a tab.
     browser: { type: 'boolean', default: false },
+    // Checking npm for a newer release is on unless this says otherwise.
+    'no-update-check': { type: 'boolean', default: false },
     version: { type: 'boolean', default: false },
     help: { type: 'boolean', default: false },
 };

package/dist/cli-args.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxB,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IAC7C,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACzB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxB,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IAChC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACzB,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IACzC,oEAAoE;IACpE,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IAC9C,sEAAsE;IACtE,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IAC5C,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IAC5C,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;CACiC,CAAC"}
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxB,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IAC7C,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACzB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxB,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IAChC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACzB,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IACzC,oEAAoE;IACpE,SAAS,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IAC9C,sEAAsE;IACtE,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IAC5C,qEAAqE;IACrE,iBAAiB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IACtD,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;IAC5C,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;CACiC,CAAC"}

package/dist/cli.js

@@ -1,269 +1,26 @@
 #!/usr/bin/env node
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
-import { Hub, HUB_VERSION } from './hub.js';
-import { serve, MEMORABLE_PORTS } from './server.js';
-import { mintClientToken } from './agents/tokens.js';
-import { paths } from './paths.js';
-import { listenPlan } from './remote/lan.js';
-import { joinCanvas } from './remote/join.js';
-import { openInBrowser } from './browser.js';
-import { openAppWindow } from './window/open-window.js';
-import { ProfileRegistry } from './agents/profiles.js';
-import { which } from './agents/resolve.js';
-import { debugTopics } from './debug.js';
+import { fileURLToPath } from 'node:url';
 import { CLI_OPTIONS } from './cli-args.js';
-/** How long shutdown waits for open connections to close. See `shutdown`. */
-const SERVER_CLOSE_DEADLINE_MS = 2000;
-/**
- * Warn when no agent CLI is installed.
- *
- * Without this the first thing a new user does - start an agent - fails inside
- * a terminal window on the canvas, where the error is easy to miss and reads
- * like the hub is broken. Checking every profile that wires up MCP, rather
- * than "claude" specifically, keeps a custom ~/.termscape/agents.toml counted.
+import { shouldSupervise, supervise } from './supervisor.js';
+/*
+ * Deliberately almost empty. Deciding whether this process is the hub or the
+ * supervisor that runs it has to happen before anything loads a native
+ * module: the supervisor outlives every hub it starts, and on Windows a
+ * global update cannot replace a .node file any live process has loaded. So
+ * the hub is imported only on the branch that runs it.
  */
-function preflightAgents() {
-    const agents = ProfileRegistry.load()
-        .list()
-        .filter((profile) => profile.mcp);
-    if (agents.length === 0)
-        return;
-    if (agents.some((profile) => which(profile.command)))
-        return;
-    const names = agents.map((profile) => profile.command).join(', ');
-    console.error(`[warn] no agent CLI found on PATH (looked for: ${names})`);
-    console.error('       install one - https://claude.com/claude-code - or set');
-    console.error('       an absolute "command" in ~/.termscape/agents.toml.');
-    console.error('       Terminals with the "shell" profile still work.');
-    console.error('');
-}
-async function main() {
+async function run() {
     const { values } = parseArgs({ options: CLI_OPTIONS, strict: true });
-    if (values.version) {
-        console.log(HUB_VERSION);
+    const cliPath = fileURLToPath(import.meta.url);
+    if (shouldSupervise(values, cliPath)) {
+        await supervise(cliPath);
         return;
     }
-    if (values.help) {
-        console.log(`termscape ${HUB_VERSION}
-
-  --port <n>        port to bind; 0 lets the OS pick. Default: the first
-                    free memorable port (7777, 4242, ...)
-  --listen <addr>   bind address. Default: every interface, so the canvas is
-                    reachable from your network with its token and another
-                    machine can attach from the join page - the one page
-                    served *without* the token. "loopback" keeps the hub to
-                    this machine, and turns that page off with it
-  --headless        serve no web UI; used when running as a remote hub
-  --token <t>       client token to use instead of generating one
-  --open            open the canvas even when not on a terminal
-  --no-open         do not open the canvas; just print the url
-  --browser         open the canvas in the browser instead of its own
-                    window. Closing that window stops the hub; closing a
-                    browser tab does not
-
-Joining another machine's canvas:
-
-  --join <url>      dial that hub and put this machine on its canvas
-  --join-token <t>  single-use token from its join page; not needed once
-                    this machine has enrolled once
-  --label <name>    how to name this machine there (default: hostname)
-`);
-        return;
-    }
-    preflightAgents();
-    mkdirSync(paths.home(), { recursive: true });
-    const clientToken = values.token ?? mintClientToken();
-    writeFileSync(paths.tokenFile(), clientToken, { mode: 0o600 });
-    // The join installer reads this to stop a previous hub before replacing its
-    // files; on Windows a loaded .node cannot be deleted while it runs.
-    writeFileSync(paths.pidFile(), String(process.pid));
-    const plan = listenPlan(values.listen, { headless: values.headless });
-    const hub = new Hub();
-    const { app, origin, lanOrigin, lanAltOrigin, enrollOrigin, enrollAltOrigin, port, peerServer, } = await serve({
-        hub,
-        host: plan.host,
-        enroll: plan.enroll,
-        // The join page has to be typed by hand on another machine, so prefer a
-        // port worth remembering unless one was asked for explicitly.
-        port: values.port === undefined ? MEMORABLE_PORTS : Number(values.port),
-        clientToken,
-        headless: values.headless,
-    });
-    const url = `${origin}/?token=${clientToken}`;
-    // A remote hub is parsed by the deployer, so keep this line machine-readable.
-    console.log(`termscape hub ${HUB_VERSION} listening on ${origin}`);
-    console.log(`TERMSCAPE_PORT=${port}`);
-    // Said out loud because it is easy to leave on, and because a remote
-    // session only traces if the hub on the *other* machine was started with
-    // it too - a half-traced path is what makes an input look lost.
-    const traced = debugTopics();
-    if (traced.length > 0) {
-        console.log(`  tracing: ${traced.join(', ')} (TERMSCAPE_DEBUG)`);
-    }
-    /*
-     * Binding wide and answering the join page is the default now, which makes
-     * it news rather than a confirmation - so it is said first, before the URLs,
-     * and it says what it costs before it says what it buys. The old banner put
-     * this last, where it read as an acknowledgement of something the operator
-     * had just typed.
-     *
-     * The way out is printed on the enrolling path too, not only the other one.
-     * It is the branch where somebody might want it.
-     */
-    if (!values.headless && lanOrigin) {
-        const where = lanOrigin.replace(/^http:\/\//, '');
-        console.log(`\n  on your network at ${where}`);
-        if (enrollOrigin) {
-            console.log(`          anyone who can reach it can load the join page and`);
-            console.log(`          attach a machine to this canvas. Everything else`);
-            console.log(`          needs the token below.`);
-            console.log(`          --listen loopback keeps the hub to this machine.`);
-        }
-        else {
-            console.log(`          the canvas needs the token below, so this is worth`);
-            console.log(`          opening on a phone or a second screen.`);
-            console.log(`          --listen loopback keeps the hub to this machine.`);
-        }
-    }
-    if (!values.headless)
-        console.log(`\n  open:   ${url}`);
-    // The canvas is worth opening from a phone or a second screen, and that
-    // needs the token too - so offer the whole URL, not just the host.
-    if (!values.headless && lanOrigin) {
-        console.log(`       or ${lanOrigin}/?token=${clientToken}`);
-        // If the name does not resolve on the other machine, the IP always will.
-        if (lanAltOrigin)
-            console.log(`       or ${lanAltOrigin}/?token=${clientToken}`);
-    }
-    if (enrollOrigin) {
-        console.log(`\n  enroll: ${enrollOrigin}/join`);
-        if (enrollAltOrigin)
-            console.log(`       or ${enrollAltOrigin}/join`);
-    }
-    else if (!values.headless) {
-        // Only two ways to get here now that the default enrolls: the operator
-        // asked for loopback, or this machine has no address anyone could reach it
-        // on. Saying which is the difference between a setting they chose and a
-        // network they need to go and look at.
-        const why = values.listen === undefined
-            ? 'this machine has no address another machine could reach it on'
-            : 'this hub is bound to loopback';
-        console.log(`\n  no join page: ${why}`);
-    }
-    if (!values.headless)
-        console.log('');
-    // The canvas hub asks us to stop when the user drops this host, so the
-    // machine does not keep a hub running that belongs to nobody.
-    // A join that was refused cannot be retried into working, and this hub was
-    // started only to join. Stopping frees its install for a re-run.
-    hub.on('joinFailed', (message) => {
-        console.error(`[join] cannot join: ${message}`);
-        void shutdown('join failed');
-    });
-    hub.on('peerShutdown', () => {
-        console.log('\n[peer] the canvas dropped this host; stopping');
-        void shutdown('peer');
-    });
-    let link = null;
-    if (values.join) {
-        link = joinCanvas({
-            hub,
-            peerServer,
-            hubUrl: values.join,
-            joinToken: values['join-token'],
-            label: values.label,
-        });
-    }
-    let shuttingDown = false;
-    const shutdown = async (signal) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        console.log(`\n[${signal}] saving state...`);
-        // Snapshots are forced here: this is the write that makes a clean restart
-        // come back with the right screens.
-        try {
-            link?.stop();
-            hub.shutdown();
-        }
-        catch (err) {
-            // Stopping is the one thing this must not fail at. A throw here used to
-            // skip the exit below and leave the hub up with nothing to stop it.
-            console.error('[shutdown]', err instanceof Error ? err.message : err);
-        }
-        try {
-            rmSync(paths.pidFile(), { force: true });
-        }
-        catch {
-            // Best effort; a stale pid file is handled by whoever reads it.
-        }
-        /*
-         * Closing the server is given a deadline rather than waited out. It waits
-         * for every websocket to finish its close handshake, and a client that
-         * never answers - a tab on a laptop that went to sleep, a machine on the
-         * other end of a dead link, anything that opened a socket and went quiet -
-         * held it open indefinitely. The canvas window had gone, the terminal was
-         * still held, and only Ctrl+C gave it back. State is already saved by now;
-         * all that is left to lose is a goodbye nobody is listening for.
-         */
-        await Promise.race([
-            app.close().catch(() => {
-                // Server already down.
-            }),
-            new Promise((resolve) => setTimeout(resolve, SERVER_CLOSE_DEADLINE_MS).unref()),
-        ]);
-        // node-pty on ConPTY keeps handles that can hold the loop open past close.
-        process.exit(0);
-    };
-    for (const sig of ['SIGINT', 'SIGTERM']) {
-        process.on(sig, () => void shutdown(sig));
-    }
-    process.on('uncaughtException', (err) => {
-        console.error('[fatal]', err);
-        void shutdown('uncaughtException');
-    });
-    // Node escalates an unhandled rejection to uncaughtException, which above
-    // stops the hub. A peer refusing a request is a normal thing that must not
-    // cost the user every agent running on this machine, so it is logged and
-    // survived instead. Call sites still catch their own; this is the net.
-    process.on('unhandledRejection', (reason) => {
-        console.error('[unhandled]', reason instanceof Error ? reason.message : reason);
-    });
-    /*
-     * Opening the canvas is the default, not a flag.
-     *
-     * The URL carries a token, so it is long and cannot be retyped - leaving
-     * the user to copy it out of scrollback is most of the friction in a
-     * one-command install. A headless hub has no UI to open, and a hub started
-     * by a script or a supervisor has nobody watching, which is what the TTY
-     * check stands in for. --open overrides that check; --no-open beats both.
-     *
-     * What opens is a window of the canvas's own, which is the app: closing it
-     * stops the hub, as Ctrl+C would. --browser asks for a tab instead, and a
-     * machine with no webview to show gets one anyway rather than nothing.
-     * Opened after `shutdown` exists, since closing the window calls it.
-     */
-    const wantsCanvas = !values.headless &&
-        !values['no-open'] &&
-        (values.open || process.stdout.isTTY === true);
-    if (wantsCanvas && values.browser) {
-        openInBrowser(url);
-    }
-    else if (wantsCanvas) {
-        openAppWindow(url, {
-            onClosed: () => void shutdown('window closed'),
-            onUnavailable: () => {
-                console.error('[app] no native window here; opening the browser instead');
-                openInBrowser(url);
-            },
-            onCrashed: (why) => {
-                console.error(`[app] the window exited (${why}); the hub is still running at ${url}`);
-            },
-        });
-    }
+    const { main } = await import('./main.js');
+    await main(values, cliPath);
 }
-main().catch((err) => {
+run().catch((err) => {
     console.error(err);
     process.exit(1);
 });

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE7D;;;;;;GAMG;AACH,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QACrC,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IAC3C,MAAM,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAClB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/hub.d.ts

@@ -12,12 +12,13 @@ import { SessionManager } from './session/manager.js';
 import type { AgentApi } from './mcp/server.js';
 import { PeerRegistry } from './remote/registry.js';
 import { type Uplink } from './remote/peer-serve.js';
+import type { Updater } from './update/updater.js';
 /** One template as list_templates shows it: described, with its env named but not given. */
 type TemplateView = Omit<AgentTemplateInfo, 'env' | 'error'> & {
     envNames: string[];
     error: string | null;
 };
-export declare const HUB_VERSION = "0.1.9";
+export declare const HUB_VERSION = "0.2.1";
 /** How many agents one workspace may hold, bounding runaway recursive spawns. */
 export declare const DEFAULT_SPAWN_CAP = 12;
 export interface HubOptions {
@@ -48,6 +49,12 @@ export declare class Hub extends EventEmitter implements AgentApi {
     readonly sessions: SessionManager;
     readonly router: MessageRouter;
     readonly peers: PeerRegistry;
+    /**
+     * Newer releases and installing them. Set by the command line once it knows
+     * how this hub was installed; null in tests and on a joined machine, which
+     * takes its canvas's build instead.
+     */
+    updater: Updater | null;
     /**
      * The link back to the canvas this hub was attached to, if it was. Null on a
      * hub that owns a canvas — which is what makes the difference between the
@@ -304,6 +311,15 @@ export declare class Hub extends EventEmitter implements AgentApi {
      * fails on a permission error rather than replacing the files.
      */
     removeHost(hostId: string): Promise<void>;
+    /**
+     * Bring a host to this hub's version.
+     *
+     * An ssh host is redeployed: its hub is stopped first, because a deploy
+     * reuses a hub it finds running, and then `connectHost` finds the version
+     * wrong and installs this one. An enrolled host is told to fetch this hub's
+     * build and restart itself; it comes back on its own, at the new version.
+     */
+    upgradeHost(hostId: string): Promise<void>;
     /**
      * Deploy the hub to a host if needed, tunnel to it, and join it to the
      * directory. The peer token is minted per connection and never written to
@@ -406,6 +422,17 @@ export declare class Hub extends EventEmitter implements AgentApi {
      * did at start.
      */
     clearSession(sessionId: string): Promise<Session>;
+    /**
+     * Write down which agents on this machine are running, ahead of a restart
+     * for an update, so the hub that comes up next can resume them.
+     */
+    rememberRunning(): void;
+    /**
+     * Resume what the hub before this one was running when it went down for an
+     * update. One agent that will not come back is reported and skipped, not a
+     * reason to leave the others stopped.
+     */
+    resumeRemembered(): Promise<string[]>;
     resumeWorkspace(workspaceId: string): Promise<Session[]>;
     moveWindow(sessionId: string, rect: WindowRect): void;
     setViewport(v: Viewport): void;