@kdonev/termscape 0.1.3 → 0.1.4

package/dist/hub.js

@@ -1,7 +1,6 @@
 import { randomBytes, randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
-import { existsSync, readFileSync } from 'node:fs';
-import { basename, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
 import { encodeInjection, INJECT_SUBMIT, MAX_PENDING_PROPOSALS, parseAddress, slugify, } from './protocol/index.js';
 import { openDb } from './db/index.js';
 import { Store } from './db/store.js';
@@ -9,14 +8,18 @@ import { briefMode, ProfileRegistry } from './agents/profiles.js';
 import { AgentDetector } from './agents/detect.js';
 import { TemplateRegistry, validate as validateTemplate } from './agents/templates.js';
 import { TokenRegistry } from './agents/tokens.js';
+import { Shares } from './agents/shares.js';
 import { MessageRouter } from './agents/router.js';
+import { PollWatch } from './agents/polling.js';
 import { SessionManager } from './session/manager.js';
 import { briefFileFor } from './agents/wiring.js';
 import { PeerRegistry } from './remote/registry.js';
+import { SPAWN_RELAY_TIMEOUT_MS } from './remote/peer-serve.js';
 import { deploy } from './remote/deployer.js';
 import { hubTarballPath } from './remote/tarball.js';
 import { paths } from './paths.js';
-export const HUB_VERSION = '0.1.3';
+import { checkFolder, folderName } from './folders.js';
+export const HUB_VERSION = '0.1.4';
 /**
  * How long changes are pooled before every attached machine is told the
  * canvas has moved on. A status change is a session change, and agents change
@@ -34,6 +37,16 @@ const WORKSPACE_COLORS = [
 ];
 /** How many agents one workspace may hold, bounding runaway recursive spawns. */
 export const DEFAULT_SPAWN_CAP = 12;
+/**
+ * Floor on a note's size, applied on every write.
+ *
+ * The resize handle in the browser already clamps to this, but the write
+ * still goes through here: a message is a message, not a client's promise to
+ * have behaved, and a note collapsed to nothing is a note nobody can ever
+ * grab again to resize back.
+ */
+const MIN_NOTE_W = 120;
+const MIN_NOTE_H = 80;
 /**
  * The hub: owns the database, the sessions, and the routing between agents.
  * The web server and the MCP endpoint are thin layers over this.
@@ -53,6 +66,8 @@ export class Hub extends EventEmitter {
     /** What of those profiles this machine actually has installed. */
     agents;
     tokens;
+    /** Per-session share links (issue 14). Persisted, unlike `tokens`. */
+    shares;
     sessions;
     router;
     peers;
@@ -78,6 +93,8 @@ export class Hub extends EventEmitter {
      * agent honestly about whether anyone is there to decide.
      */
     viewers = 0;
+    /** Catches an agent watching a screen instead of waiting for a reply. */
+    pollWatch = new PollWatch();
     constructor(opts = {}) {
         super();
         this.db = openDb(opts.dbPath ?? paths.db());
@@ -90,6 +107,7 @@ export class Hub extends EventEmitter {
         // canvas the same way it forwards session changes.
         this.agents.on('changed', (found) => this.emit('agents', found));
         this.tokens = new TokenRegistry();
+        this.shares = new Shares(this.store);
         this.spawnCap = opts.spawnCap ?? DEFAULT_SPAWN_CAP;
         // Origin is corrected once the server binds and knows its port.
         this.sessions = new SessionManager(this.store, this.profiles, this.tokens, 'http://127.0.0.1:0');
@@ -111,14 +129,22 @@ export class Hub extends EventEmitter {
             // and for remote sessions the address *is* the id it was given.
             this.emit('data', address, data);
         });
-        // A host asking us to act on an address it cannot resolve itself. We are
-        // the only hub that knows where every address on this canvas lives, and
-        // the answer travels back the way the question came.
-        this.peers.on('relay', (ask, reply) => {
+        // A host asking us to act on something it cannot resolve itself. We are
+        // the only hub that knows what every machine on this canvas is and where
+        // every address on it lives, and the answer travels back the way the
+        // question came.
+        this.peers.on('relay', (ask, reply, fromHostId) => {
             const done = (p) => p.then((result) => reply(true, result, null), (err) => reply(false, null, err.message));
-            if (ask.t === 'deliver')
-                return void done(this.deliverFrom(ask.from, ask.to, ask.body));
-            return void done(this.readScreenAt(ask.address, ask.lines));
+            switch (ask.t) {
+                case 'deliver':
+                    return void done(this.deliverFrom(ask.from, ask.to, ask.body));
+                case 'readScreen':
+                    return void done(this.readScreenAt(ask.address, ask.lines));
+                case 'listHosts':
+                    return void done(Promise.resolve(this.hostsView(fromHostId)));
+                case 'spawn':
+                    return void done(this.spawnFrom(ask, fromHostId));
+            }
         });
         // Every attached machine's view of the canvas is whatever we last told it,
         // so anything that changes who is running has to be followed by telling
@@ -179,17 +205,19 @@ export class Hub extends EventEmitter {
     }
     /* ---------------------------------------------------------- workspaces */
     createWorkspace(name, rootPath, hostId = null) {
-        const abs = resolve(rootPath);
-        if (!hostId && !existsSync(abs)) {
-            throw new Error(`folder does not exist: ${abs}`);
-        }
+        // A remote root belongs to the machine it names, not to this process —
+        // resolving and checking it here, in this platform's own flavour, is
+        // exactly the bug folders.ts exists to fix. It is stored verbatim
+        // (trimmed) and left for that machine to make sense of, the same way
+        // peer-serve does when it is asked to start a session there.
+        const path = hostId ? rootPath.trim() : checkFolder(rootPath).path;
         const existing = this.store.listWorkspaces();
-        const wsName = uniqueWorkspaceName(slugify(name || basename(abs)), existing.map((w) => w.name));
+        const wsName = uniqueWorkspaceName(slugify(name || folderName(path)), existing.map((w) => w.name));
         const ws = {
             id: randomUUID(),
             name: wsName,
             kind: hostId ? 'remote' : 'local',
-            rootPath: abs,
+            rootPath: path,
             hostId,
             color: WORKSPACE_COLORS[existing.length % WORKSPACE_COLORS.length],
             createdAt: Date.now(),
@@ -220,14 +248,12 @@ export class Hub extends EventEmitter {
             throw new Error(`unknown workspace ${id}`);
         const next = {};
         if (patch.rootPath !== undefined) {
-            const abs = resolve(patch.rootPath);
-            // Only a local folder can be checked from here; a remote one is the
-            // other machine's to know about, exactly as it is on create.
-            if (!ws.hostId && !existsSync(abs)) {
-                throw new Error(`folder does not exist: ${abs}`);
-            }
-            if (abs !== ws.rootPath)
-                next.rootPath = abs;
+            // Only a local folder can be resolved and checked from here; a remote
+            // one is the other machine's to know about, exactly as it is on
+            // create.
+            const path = ws.hostId ? patch.rootPath.trim() : checkFolder(patch.rootPath).path;
+            if (path !== ws.rootPath)
+                next.rootPath = path;
         }
         if (patch.name !== undefined) {
             const wanted = slugify(patch.name);
@@ -252,6 +278,20 @@ export class Hub extends EventEmitter {
         this.emit('workspace', updated);
         return updated;
     }
+    /**
+     * Resolve and check a folder on whichever machine would own the workspace,
+     * before that workspace exists. The Add/Edit-workspace dialog's pre-flight:
+     * without it, a bad remote root was never checked at all (createWorkspace
+     * cannot check what it cannot resolve), and a bad local one was only
+     * checked after the dialog had already closed. One method either way, so
+     * the dialog does not need to know which kind of workspace it is asking
+     * about.
+     */
+    async checkHostFolder(hostId, path) {
+        if (!hostId)
+            return checkFolder(path);
+        return this.peers.checkFolder(hostId, path);
+    }
     async removeWorkspace(id) {
         const ws = this.store.getWorkspace(id);
         for (const s of this.sessions.list().filter((s) => s.workspaceId === id)) {
@@ -774,6 +814,77 @@ export class Hub extends EventEmitter {
     setViewport(v) {
         this.store.saveViewport(v);
     }
+    /* ----------------------------------------------------------------- notes */
+    /**
+     * Write a note straight to the db, no debounce.
+     *
+     * Windows debounce their layout writes (see `session/manager.ts`), and lose
+     * whichever drag was in flight if the hub is killed inside that window -
+     * `layout.test.ts` covers it, and `notes.test.ts` proves this does not
+     * repeat it. `setViewport` above already writes straight through for the
+     * same reason.
+     *
+     * Non-finite numbers are dropped rather than clamped to some default: a NaN
+     * or Infinity in x/y/w/h/z means the sender computed garbage, and the
+     * previous good rect is a safer answer than inventing one.
+     */
+    saveNote(note) {
+        const finite = [note.x, note.y, note.w, note.h, note.z].every(Number.isFinite);
+        if (!finite)
+            return null;
+        const clamped = {
+            ...note,
+            w: Math.max(MIN_NOTE_W, note.w),
+            h: Math.max(MIN_NOTE_H, note.h),
+        };
+        this.store.saveNote(clamped);
+        return clamped;
+    }
+    removeNote(id) {
+        this.store.removeNote(id);
+    }
+    /* --------------------------------------------------------------- shares */
+    /**
+     * Grant a link that opens `sessionId` alone in another browser.
+     *
+     * Checked against `allSessions()` rather than trusted from the caller,
+     * because there is deliberately no foreign key holding the share table to
+     * this: a remote window's session lives on a peer, not in this database
+     * (see migration 9), so the only way to refuse an id that names nothing is
+     * to ask the same place the canvas itself would.
+     */
+    shareSession(sessionId) {
+        if (!this.allSessions().some((s) => s.id === sessionId)) {
+            throw new Error(`unknown session ${sessionId}`);
+        }
+        const token = this.shares.share(sessionId);
+        this.emit('shares', this.shares.list());
+        return token;
+    }
+    /**
+     * Revoke a share link. `/ws` listens for `shareRevoked` and closes every
+     * socket already scoped to this session - without that, "revoked" would be
+     * untrue for a reviewer tab that is already open, which is the one case
+     * revocation exists for.
+     */
+    unshareSession(sessionId) {
+        this.shares.unshare(sessionId);
+        this.emit('shares', this.shares.list());
+        this.emit('shareRevoked', sessionId);
+    }
+    /**
+     * Resolve a share token to the session it grants, re-checking against
+     * `allSessions()` the same way `shareSession` does at mint time. Not
+     * expected to ever disagree - `removeSession` and `removeRemoteWindow` both
+     * delete the row when a session goes - but a socket presenting a token is
+     * exactly the moment to distrust a row rather than the moment to assume it.
+     */
+    resolveShareToken(token) {
+        const sessionId = this.shares.resolve(token);
+        if (!sessionId)
+            return null;
+        return this.allSessions().some((s) => s.id === sessionId) ? sessionId : null;
+    }
     /* ------------------------------------------------- AgentApi (MCP tools) */
     requireSession(sessionId) {
         const s = this.sessions.get(sessionId);
@@ -830,9 +941,243 @@ export class Hub extends EventEmitter {
             throw new Error(`no template "${id}"`);
         return one;
     }
+    /**
+     * Every machine on the canvas, for `spawn_agent`'s `host` to name and
+     * `list_hosts` to report. Relayed rather than answered locally on an
+     * attached hub: it holds rows for nothing but itself, so only the canvas
+     * can say what else exists, whether it is reachable, or what it has
+     * installed.
+     */
+    async listHosts(sessionId) {
+        this.requireSession(sessionId);
+        if (this.uplink?.attached)
+            return this.uplink.ask({ t: 'listHosts' });
+        return this.hostsView(null);
+    }
+    /**
+     * Every machine on the canvas as the canvas itself sees it: the canvas
+     * machine (which has no host row of its own — synthesised here with the
+     * same empty id the web tree already gives it), then every host row, each
+     * with the workspaces it has and the agent CLIs it last reported.
+     *
+     * `callerHostId` marks `you`: null for the canvas hub's own agents, a host
+     * id for a relayed caller elsewhere on the canvas. Only ever called here,
+     * on the canvas — an attached hub has nothing to build this from.
+     */
+    hostsView(callerHostId) {
+        const remoteSessions = this.peers.sessions();
+        const remoteAgentCount = (workspaceName) => remoteSessions.filter((s) => s.address.startsWith(`${workspaceName}/`)).length;
+        const localAgentCount = (workspaceId) => this.sessions.list().filter((s) => s.workspaceId === workspaceId).length;
+        const agentInfo = (a) => ({
+            id: a.id,
+            available: a.available,
+            version: a.version,
+            detail: a.detail,
+        });
+        const canvasWorkspaces = this.store
+            .listWorkspaces()
+            .filter((w) => w.hostId === null)
+            .map((w) => ({ name: w.name, rootPath: w.rootPath, agents: localAgentCount(w.id) }));
+        const canvasEntry = {
+            id: '',
+            label: 'canvas',
+            kind: 'canvas',
+            state: 'connected',
+            you: callerHostId === null,
+            platform: null,
+            error: null,
+            workspaces: canvasWorkspaces,
+            agents: this.agents.snapshot().map(agentInfo),
+        };
+        const remoteAgentsByHost = this.peers.agentsByHost();
+        const hostRows = this.store.listHosts().map((h) => {
+            const rowed = this.store
+                .listWorkspaces()
+                .filter((w) => w.hostId === h.id)
+                .map((w) => ({ name: w.name, rootPath: w.rootPath, agents: remoteAgentCount(w.name) }));
+            const rowedNames = new Set(rowed.map((w) => w.name));
+            // A workspace on that machine seen only through a running agent's
+            // address, with no row here: the canvas never created one for it — an
+            // older client, say, or a row removed locally while the peer kept
+            // running it. Listed, so an agent can see it exists, but `rootPath`
+            // stays null: spawn_agent has nothing to spawn into.
+            const rowlessNames = new Set(remoteSessions
+                .filter((s) => this.peers.hostIdFor(s.address) === h.id)
+                .map((s) => parseAddress(s.address)?.workspace)
+                .filter((name) => !!name && !rowedNames.has(name)));
+            const rowless = [...rowlessNames].map((name) => ({
+                name,
+                rootPath: null,
+                agents: remoteAgentCount(name),
+            }));
+            return {
+                id: h.id,
+                label: h.label,
+                kind: h.kind,
+                state: h.state,
+                you: callerHostId === h.id,
+                platform: h.platform,
+                error: h.error,
+                workspaces: [...rowed, ...rowless],
+                agents: (remoteAgentsByHost[h.id] ?? []).map(agentInfo),
+            };
+        });
+        return [canvasEntry, ...hostRows];
+    }
+    /**
+     * Whether a spawn_agent `host` names the machine this hub itself runs on:
+     * 'local', 'self', or the label the canvas last told an attached hub it is
+     * called. An attached hub holds no id worth matching for itself — only the
+     * canvas holds a row for it — so these are the only ways it can recognise
+     * itself.
+     */
+    namesThisMachine(host) {
+        const h = host.trim().toLowerCase();
+        if (h === 'local' || h === 'self')
+            return true;
+        const mine = this.uplink?.hostLabel();
+        return !!mine && h === mine.toLowerCase();
+    }
+    /**
+     * Turn a spawn_agent `host` (plus an optional `workspace`) into the
+     * `Workspace` to start into. Shared by a local call naming a `host` and a
+     * relayed one: the two must fail identically, since either can be what a
+     * spawn_agent call elsewhere on the canvas turns into by the time it
+     * reaches here. Only ever called on the canvas — it is the one hub these
+     * rules can be evaluated on.
+     */
+    resolveSpawnTarget(opts) {
+        const hosts = this.hostsView(opts.callerHostId);
+        const wanted = opts.host.trim();
+        const asSelf = wanted.toLowerCase() === 'local' || wanted.toLowerCase() === 'self';
+        // Pick the machine. 'local'/'self' first, then an exact id, and only
+        // then a label matched case-insensitively — in that order, so a label
+        // can never shadow an id and 'local' is never read as someone's actual
+        // label.
+        let matches;
+        if (asSelf) {
+            matches = hosts.filter((h) => h.you);
+        }
+        else {
+            const byId = hosts.filter((h) => h.id === wanted);
+            matches =
+                byId.length > 0 ? byId : hosts.filter((h) => h.label.toLowerCase() === wanted.toLowerCase());
+        }
+        if (matches.length === 0) {
+            throw new Error(`unknown host "${opts.host}"; hosts are: ${hosts.map((h) => h.label).join(', ')} ` +
+                '(call list_hosts)');
+        }
+        if (matches.length > 1) {
+            throw new Error(`host "${opts.host}" names more than one machine; pass the id instead: ` +
+                matches.map((h) => h.id).join(', '));
+        }
+        const target = matches[0];
+        // Reachability. The canvas entry is always reachable; a host row is only
+        // as reachable as its live connection right now.
+        if (target.kind !== 'canvas' && this.peers.peer(target.id)?.connected !== true) {
+            throw new Error(`host "${target.label}" is not connected; nothing can be started there right now`);
+        }
+        // Pick the workspace. Only rows the canvas actually holds can be spawned
+        // into — a rowless one, seen only through a running agent's address,
+        // is something list_hosts can show but not something this can start.
+        const rowed = target.workspaces.filter((w) => w.rootPath !== null);
+        let chosenName;
+        if (opts.workspace) {
+            const here = target.workspaces.find((w) => w.name === opts.workspace);
+            if (here && here.rootPath !== null) {
+                chosenName = here.name;
+            }
+            else if (here) {
+                throw new Error(`workspace "${opts.workspace}" exists on "${target.label}" but the canvas holds no ` +
+                    'folder for it; ask the human to add it from the canvas');
+            }
+            else {
+                const elsewhere = hosts.find((h) => h.id !== target.id && h.workspaces.some((w) => w.name === opts.workspace));
+                if (elsewhere) {
+                    throw new Error(`workspace "${opts.workspace}" is on host "${elsewhere.label}", not "${target.label}"`);
+                }
+                throw new Error(`no workspace "${opts.workspace}" on host "${target.label}"` +
+                    (rowed.length ? `; workspaces there are: ${rowed.map((w) => w.name).join(', ')}` : ''));
+            }
+        }
+        else {
+            const sameName = opts.callerWorkspaceName
+                ? rowed.find((w) => w.name === opts.callerWorkspaceName)
+                : undefined;
+            if (sameName) {
+                chosenName = sameName.name;
+            }
+            else if (rowed.length === 1) {
+                chosenName = rowed[0].name;
+            }
+            else if (rowed.length === 0) {
+                throw new Error(`host "${target.label}" has no workspace on the canvas; ask the human to add one there first`);
+            }
+            else {
+                throw new Error(`host "${target.label}" has several workspaces (${rowed.map((w) => w.name).join(', ')}); ` +
+                    'pass workspace: one of them');
+            }
+        }
+        /*
+         * The CLI check, last — the one thing that can be refused before an
+         * irreversible spawn. An empty list is not "confirmed zero CLIs":
+         * `AgentDetector.snapshot()` is documented "never async, and never
+         * empty: a profile that has not been probed yet is reported with
+         * `available: null`" (detect.ts:69-71), and `shell` is unconditional in
+         * `BUILTIN_PROFILES` (profiles.ts:470), so a machine that has synced its
+         * CLIs at all reports at least one entry, probed or not. An empty array
+         * here can therefore only be the `?? []` fallback firing because no
+         * `agents` frame has arrived from that host yet — not a machine that has
+         * reported having none.
+         */
+        if (target.agents.length > 0) {
+            const known = target.agents.find((a) => a.id === opts.agent);
+            if (!known || known.available === false) {
+                const has = target.agents.filter((a) => a.available !== false).map((a) => a.id);
+                throw new Error(`host "${target.label}" cannot run "${opts.agent}"` +
+                    (known?.detail ? `: ${known.detail}` : '') +
+                    (has.length ? `; it has: ${has.join(', ')}` : ''));
+            }
+        }
+        const hostId = target.kind === 'canvas' ? null : target.id;
+        const ws = this.store
+            .listWorkspaces()
+            .find((w) => (w.hostId ?? null) === hostId && w.name === chosenName);
+        if (!ws) {
+            // Cannot happen outside a race: `chosenName` came from `hostsView`,
+            // which read these same store rows a moment ago.
+            throw new Error(`workspace "${chosenName}" on "${target.label}" vanished mid-request`);
+        }
+        return ws;
+    }
+    /**
+     * What this hub's own machine is called: 'canvas' when it owns the canvas,
+     * or the label the canvas gave an attached one — the same name list_hosts
+     * and list_agents both use, so every tool agrees on what a machine is
+     * called. Before the canvas's first `directory` arrives, an attached hub
+     * has not been told yet; 'local' is the fallback list_agents always
+     * answered with.
+     */
+    thisMachineLabel() {
+        return this.uplink?.attached ? (this.uplink.hostLabel() ?? 'local') : 'canvas';
+    }
+    /**
+     * What a workspace's machine is called, for a spawn reply's `host` field.
+     * `ws.hostId` set means a *remote* machine as this hub's own store knows
+     * it — true whether this hub is the canvas resolving a peer, or a peer
+     * itself (which holds no host rows of its own, so this branch never
+     * triggers for it). Null means local to whichever hub is asking, which is
+     * only 'canvas' when that hub is the canvas.
+     */
+    hostLabelForWorkspace(ws) {
+        if (ws.hostId)
+            return this.store.getHost(ws.hostId)?.label ?? 'remote';
+        return this.thisMachineLabel();
+    }
     async listAgents(sessionId, workspace) {
         const me = this.requireSession(sessionId);
         const wsById = new Map(this.store.listWorkspaces().map((w) => [w.id, w]));
+        const myLabel = this.thisMachineLabel();
         const local = this.sessions.list().map((s) => ({
             address: s.address,
             workspace: wsById.get(s.workspaceId)?.name ?? null,
@@ -840,7 +1185,7 @@ export class Hub extends EventEmitter {
             state: s.state,
             status: s.status,
             statusText: s.statusText,
-            host: 'local',
+            host: myLabel,
             isYou: s.id === me.id,
         }));
         const hostLabels = new Map(this.store.listHosts().map((h) => [h.id, h.label]));
@@ -870,7 +1215,11 @@ export class Hub extends EventEmitter {
         const me = this.requireSession(sessionId);
         if (me.address === to)
             throw new Error('cannot send a message to yourself');
-        return this.deliverFrom(me.address, to, text);
+        const result = await this.deliverFrom(me.address, to, text);
+        // Only a successful send counts as a question asked - deliverFrom throws
+        // on failure, so a message that never arrived does not excuse polling.
+        this.pollWatch.noteMessage(me.address, to);
+        return result;
     }
     /**
      * Tell every attached machine who is on the canvas.
@@ -973,11 +1322,6 @@ export class Hub extends EventEmitter {
     }
     async spawnAgent(sessionId, opts) {
         const me = this.requireSession(sessionId);
-        const ws = opts.workspace
-            ? this.store.getWorkspaceByName(opts.workspace)
-            : this.store.getWorkspace(me.workspaceId);
-        if (!ws)
-            throw new Error(`unknown workspace "${opts.workspace}"`);
         // The child starts the way its parent did: from the same template, so the
         // model and effort the template chose are not silently dropped in favour
         // of the bare agent's defaults. A template that has been deleted or has
@@ -987,16 +1331,63 @@ export class Hub extends EventEmitter {
         const inherited = me.template ? this.templates.get(me.template) : null;
         const inherit = opts.profile ?? (inherited && !inherited.error ? me.template : me.profile);
         /*
-         * One injection, delivered once, by the hub that owns the child's PTY: the
-         * template's opening instruction first, then what the spawning agent asked
-         * for, attributed. Delivering them separately would race two injections on
-         * the same ready-signal, landing back to back in undefined order, so the
-         * opening merges here and rides to the child through startSession — which
-         * also means the remote path needs no delivery of its own.
+         * Resolved, and the opening instruction built, ahead of the workspace: a
+         * `host` needs the resolved agent id before it can even ask whether that
+         * machine can run it, and a relay carries only resolved values, never a
+         * template name — the two hubs do not share config. One injection,
+         * delivered once, by whichever hub ends up owning the child's PTY: the
+         * template's opening instruction first, then what the spawning agent
+         * asked for, attributed. Delivering them separately would race two
+         * injections on the same ready-signal, landing back to back in undefined
+         * order, so the opening merges here and rides to the child however it
+         * gets there.
          */
-        const templatePrompt = inherit ? (this.templates.get(inherit)?.prompt ?? null) : null;
+        const picked = this.resolveTemplate({ profile: inherit });
         const instruction = opts.prompt ? `[from ${me.address}] ${opts.prompt}` : null;
-        const opening = [templatePrompt, instruction].filter(Boolean).join('\n\n') || undefined;
+        const opening = [picked.prompt, instruction].filter(Boolean).join('\n\n') || undefined;
+        // A `host` naming something beyond this hub's own machine has to go up
+        // the link: an attached hub holds rows for nothing but itself, and only
+        // the canvas can say whether the machine exists, is reachable, or can
+        // run this agent.
+        if (opts.host !== undefined && this.uplink?.attached && !this.namesThisMachine(opts.host)) {
+            return this.uplink.ask({
+                t: 'spawn',
+                from: me.address,
+                host: opts.host,
+                workspace: opts.workspace,
+                name: opts.name,
+                agent: picked.agent,
+                template: picked.template,
+                model: picked.model,
+                effort: picked.effort,
+                env: picked.env,
+                opening,
+                promptGiven: !!opts.prompt,
+            }, { timeoutMs: SPAWN_RELAY_TIMEOUT_MS });
+        }
+        let ws;
+        if (opts.host !== undefined && !this.uplink?.attached) {
+            // The canvas, resolving a `host` for real — itself included, since it
+            // is the one hub these rules can even be evaluated on.
+            ws = this.resolveSpawnTarget({
+                host: opts.host,
+                workspace: opts.workspace,
+                callerWorkspaceName: this.store.getWorkspace(me.workspaceId)?.name ?? null,
+                callerHostId: null,
+                agent: picked.agent,
+            });
+        }
+        else {
+            // No `host`, unchanged — or an attached hub naming its own machine,
+            // which needs none of resolveSpawnTarget's cross-machine knowledge,
+            // because this hub does not have any.
+            const found = opts.workspace
+                ? this.store.getWorkspaceByName(opts.workspace)
+                : this.store.getWorkspace(me.workspaceId);
+            if (!found)
+                throw new Error(`unknown workspace "${opts.workspace}"`);
+            ws = found;
+        }
         const child = await this.startSession({
             workspaceId: ws.id,
             profile: inherit,
@@ -1008,9 +1399,65 @@ export class Hub extends EventEmitter {
             address: child.address,
             workspace: ws.name,
             profile: child.profile,
+            host: this.hostLabelForWorkspace(ws),
             promptQueued: !!opts.prompt,
         };
     }
+    /**
+     * Execute a spawn_agent relayed from another hub, exactly as a local call
+     * naming the same `host` would: resolve the target with
+     * `resolveSpawnTarget`, then land it directly rather than through
+     * `startSession` — the values already came out of `resolveTemplate` on the
+     * asking hub, and re-resolving `ask.agent` as a template id here could hit
+     * a stored template of the same name that means something else entirely on
+     * this hub. Never re-resolves a template and never re-prefixes the
+     * opening, for the same reason `startSession`'s own peer request does not:
+     * a template is config, and the two hubs do not share it.
+     */
+    async spawnFrom(ask, fromHostId) {
+        const ws = this.resolveSpawnTarget({
+            host: ask.host,
+            workspace: ask.workspace,
+            callerWorkspaceName: ask.from.split('/')[0] ?? null,
+            callerHostId: fromHostId,
+            agent: ask.agent,
+        });
+        const child = ws.hostId
+            ? await this.peers.startSession(ws.hostId, {
+                workspaceName: ws.name,
+                rootPath: ws.rootPath,
+                profile: ask.agent,
+                template: ask.template ?? null,
+                model: ask.model,
+                effort: ask.effort,
+                prompt: ask.opening,
+                env: ask.env,
+                name: ask.name,
+                // See the known gap noted on spawn_agent's `host`: the spawner
+                // lives on a hub this canvas has no local id for, and the
+                // canvas-local branch below cannot take one either — the session
+                // table's foreign key would reject it.
+                spawnedByAddress: null,
+            })
+            : await this.startResolved({
+                workspaceId: ws.id,
+                agent: ask.agent,
+                template: ask.template ?? null,
+                model: ask.model,
+                effort: ask.effort,
+                prompt: ask.opening,
+                env: ask.env,
+                name: ask.name,
+                spawnedBy: null,
+            });
+        return {
+            address: child.address,
+            workspace: ws.name,
+            profile: child.profile,
+            host: this.hostLabelForWorkspace(ws),
+            promptQueued: ask.promptGiven,
+        };
+    }
     /**
      * A template's opening instruction, typed in plainly.
      *
@@ -1063,8 +1510,15 @@ export class Hub extends EventEmitter {
         }
     }
     async readScreen(sessionId, address, lines) {
-        this.requireSession(sessionId);
-        return this.readScreenAt(address, lines);
+        const me = this.requireSession(sessionId);
+        const result = await this.readScreenAt(address, lines);
+        // Decorating after the await, rather than counting the call up front,
+        // means a remote or uplink target gets the note too. Counted here, not in
+        // readScreenAt: that path also serves peers asking on this hub's behalf
+        // for a caller it never authenticated, and the count belongs to the
+        // caller's own hub.
+        const note = this.pollWatch.noteRead(me.address, address);
+        return note ? { ...result, note } : result;
     }
     /**
      * read_screen for a caller this hub has already established — either an