@kdonev/termscape 0.1.5 → 0.1.7

package/dist/hub.js

@@ -6,26 +6,33 @@ import { openDb } from './db/index.js';
 import { Store } from './db/store.js';
 import { briefMode, ProfileRegistry } from './agents/profiles.js';
 import { AgentDetector } from './agents/detect.js';
-import { TemplateRegistry, validate as validateTemplate } from './agents/templates.js';
+import { TemplateRegistry, overlayCanvasTemplates, 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 { canSee } from './agents/visibility.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';
 import { checkFolder, folderName } from './folders.js';
-export const HUB_VERSION = '0.1.5';
+export const HUB_VERSION = '0.1.7';
 /**
  * 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
  * status several times a turn.
  */
 const ANNOUNCE_COALESCE_MS = 300;
+/**
+ * How long a new agent's output has to stop before its opening instruction is
+ * typed in, and the longest that is waited for at all. See typeWhenReady.
+ */
+const OPENING_QUIET_MS = 1500;
+const OPENING_READY_CAP_MS = 20_000;
 /** Colours cycled through when a workspace is created, for canvas grouping. */
 const WORKSPACE_COLORS = [
     '#7c9cf5',
@@ -119,6 +126,11 @@ export class Hub extends EventEmitter {
         // Peer windows share the canvas, so a new local window must not land on
         // one. The manager cannot see the registry; this is the view it needs.
         this.sessions.remoteWindows = () => this.peers.sessions().map((s) => s.window);
+        // A brief lists who its agent can see, and that is decided across every
+        // machine by lineage - which only the hub has the view for.
+        this.sessions.visiblePeers = (s) => this.everyAgent()
+            .filter((o) => o.address !== s.address && canSee(s, o))
+            .map((o) => o.address);
         this.peers.on('host', (h) => this.emit('host', h));
         this.peers.on('peerAgents', (hostId, found) => this.emit('hostAgents', hostId, found));
         this.peers.on('peerSession', (s) => this.emit('session', s));
@@ -135,15 +147,40 @@ export class Hub extends EventEmitter {
         // 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));
+            /*
+             * The canvas is authoritative about who may see whom: the asking hub
+             * checked already, but from a directory that may be a moment stale,
+             * and a host that did not check at all must not be a way round it.
+             */
             switch (ask.t) {
                 case 'deliver':
-                    return void done(this.deliverFrom(ask.from, ask.to, ask.body));
+                    return void done((async () => {
+                        this.requireVisible(this.lineageOf(ask.from), ask.to);
+                        return this.deliverFrom(ask.from, ask.to, ask.body);
+                    })());
                 case 'readScreen':
-                    return void done(this.readScreenAt(ask.address, ask.lines));
+                    return void done((async () => {
+                        this.requireVisible(this.lineageOf(ask.from), ask.address);
+                        return this.readScreenAt(ask.from, ask.address, ask.lines);
+                    })());
                 case 'listHosts':
                     return void done(Promise.resolve(this.hostsView(fromHostId)));
+                case 'listTemplates':
+                    return void done(Promise.resolve(this.templateViews()));
+                case 'pickTemplate':
+                    return void done(Promise.resolve(this.pickTemplateFor(ask)));
                 case 'spawn':
                     return void done(this.spawnFrom(ask, fromHostId));
+                case 'proposeTemplate': {
+                    // `from` is only trusted as far as the host that sent it: an
+                    // agent on one machine must not be able to propose as, and have
+                    // the answer typed into, an agent on another.
+                    if (this.peers.hostIdFor(ask.from) !== fromHostId) {
+                        return void done(Promise.reject(new Error(`no agent at address "${ask.from}"`)));
+                    }
+                    const { t: _t, from, ...input } = ask;
+                    return void done(this.proposeTemplateFrom(from, input));
+                }
             }
         });
         // Every attached machine's view of the canvas is whatever we last told it,
@@ -191,6 +228,39 @@ export class Hub extends EventEmitter {
             return 'remote';
         return this.uplink?.agents().some((a) => a.address === address) ? 'uplink' : null;
     }
+    /**
+     * Every agent this hub knows of, on any machine, with its lineage: its own,
+     * those on machines it holds, and those the canvas told it about. The three
+     * are exclusive for the reason `locate` gives.
+     */
+    everyAgent() {
+        return [
+            ...this.sessions.list(),
+            ...this.peers.sessions(),
+            ...(this.uplink?.agents() ?? []),
+        ].map((a) => ({ address: a.address, parentAddress: a.parentAddress ?? null }));
+    }
+    /** One address's lineage, from the same view, or null for one nobody here knows. */
+    lineageOf(address) {
+        const local = this.sessions.getByAddress(address);
+        if (local)
+            return { address, parentAddress: local.parentAddress ?? null };
+        const found = this.peers.find(address)?.session ??
+            this.uplink?.agents().find((a) => a.address === address);
+        return found ? { address, parentAddress: found.parentAddress ?? null } : null;
+    }
+    /**
+     * Refuse to act on an address the viewer may not see, in exactly the words
+     * used for one that does not exist: a hidden agent must not be discoverable
+     * by probing for the difference. An address nobody knows is let through, so
+     * the delivery path can record the failed attempt as it always has.
+     */
+    requireVisible(viewer, address) {
+        const target = this.lineageOf(address);
+        if (target && (!viewer || !canSee(viewer, target))) {
+            throw new Error(`no agent at address "${address}"`);
+        }
+    }
     /**
      * Attach this hub to the canvas reachable over `uplink`.
      *
@@ -436,7 +506,21 @@ export class Hub extends EventEmitter {
      */
     async proposeTemplate(sessionId, input) {
         const me = this.requireSession(sessionId);
-        const mine = [...this.proposals.values()].filter((p) => p.fromAddr === me.address);
+        // Templates are central (issue 22): the canvas is where they live and
+        // where the human who answers is, so an attached hub hands the proposal
+        // up. No local fallback when that fails - a proposal kept here would wait
+        // for a dialog nobody is ever shown, which is the bug this fixes.
+        if (this.uplink?.attached) {
+            return this.uplink.ask({ t: 'proposeTemplate', from: me.address, ...input });
+        }
+        return this.proposeTemplateFrom(me.address, input);
+    }
+    /**
+     * A proposal from an agent already established, here or on an attached
+     * machine - the canvas's half of proposeTemplate.
+     */
+    async proposeTemplateFrom(fromAddr, input) {
+        const mine = [...this.proposals.values()].filter((p) => p.fromAddr === fromAddr);
         if (mine.length >= MAX_PENDING_PROPOSALS) {
             /*
              * Name them. The way this limit is actually reached is a human closing
@@ -457,7 +541,7 @@ export class Hub extends EventEmitter {
         const candidate = this.candidateTemplate(input);
         const proposal = {
             id: randomUUID(),
-            fromAddr: me.address,
+            fromAddr,
             proposedAt: Date.now(),
             template: {
                 id: candidate.id,
@@ -523,6 +607,21 @@ export class Hub extends EventEmitter {
      * as an instruction.
      */
     tellAgent(address, text) {
+        if (!this.sessions.getByAddress(address)) {
+            // An agent on an attached machine proposed it, and only that machine
+            // owns its terminal. Best effort, like the local case below.
+            if (this.peers.hostIdFor(address))
+                void this.peers.notify(address, text).catch(() => { });
+            return;
+        }
+        this.notifyAgent(address, text);
+    }
+    /**
+     * tellAgent's local half, and what an attached hub runs when the canvas
+     * sends it a notice for one of its agents. The one place the `[termscape]`
+     * prefix is applied, so a notice reads the same from any machine.
+     */
+    notifyAgent(address, text) {
         const target = this.sessions.getByAddress(address);
         if (!target)
             return;
@@ -680,14 +779,25 @@ export class Hub extends EventEmitter {
         };
     }
     async startSession(opts) {
+        const parentAddress = opts.spawnedBy
+            ? (this.sessions.get(opts.spawnedBy)?.address ?? null)
+            : null;
+        return this.startPicked({ ...opts, parentAddress }, this.resolveTemplate(opts));
+    }
+    /**
+     * Start a session from a template already resolved, locally or on a host.
+     *
+     * Split from startSession for spawn_agent on an attached hub, whose
+     * template may have been resolved by the canvas: resolving its id again
+     * here would look it up in a registry that has never heard of it.
+     */
+    async startPicked(opts, picked) {
         const ws = this.store.getWorkspace(opts.workspaceId);
         if (!ws)
             throw new Error(`unknown workspace ${opts.workspaceId}`);
-        const picked = this.resolveTemplate(opts);
         // A workspace that belongs to a host runs its agents there. The peer owns
         // the PTY; what comes back is a session we show on our own canvas.
         if (ws.hostId) {
-            const spawner = opts.spawnedBy ? this.sessions.get(opts.spawnedBy) : null;
             // Resolved values cross, never the template id: a template is config
             // and the two machines do not share config, so a name that means "opus,
             // high effort" here may mean nothing over there. The id travels only so
@@ -700,11 +810,12 @@ export class Hub extends EventEmitter {
                 model: picked.model,
                 effort: picked.effort,
                 prompt: picked.prompt,
+                restorePrompt: picked.restorePrompt,
                 // Values, like the model and the effort beside it: the template lives
                 // here and the far side has never heard of it.
                 env: picked.env,
                 name: opts.name,
-                spawnedByAddress: spawner?.address ?? null,
+                spawnedByAddress: opts.parentAddress ?? null,
             });
         }
         return this.startResolved({ ...opts, ...picked });
@@ -735,6 +846,7 @@ export class Hub extends EventEmitter {
             name: opts.name ?? opts.template ?? undefined,
             cwd: opts.cwd,
             spawnedBy: opts.spawnedBy ?? null,
+            parentAddress: opts.parentAddress ?? null,
         });
         /*
          * Typed in once the CLI is up rather than written into argv, where it
@@ -752,6 +864,7 @@ export class Hub extends EventEmitter {
             .join('\n\n');
         if (opening)
             void this.deliverOpeningInstruction(session.id, opening);
+        this.store.setOpeningPrompt(session.id, opts.restorePrompt === undefined ? (opts.prompt ?? null) : opts.restorePrompt);
         return session;
     }
     /**
@@ -792,6 +905,29 @@ export class Hub extends EventEmitter {
             void this.deliverOpeningInstruction(session.id, brief);
         return session;
     }
+    /**
+     * Start a running session over: a fresh conversation, an empty window, and
+     * its opening typed in again - the window's `clear` button.
+     *
+     * A restart rather than typing `/clear` at the CLI. Only Claude Code could
+     * say it had cleared, and only through a hook; a restart is the same for
+     * every agent, and the hub knows exactly when the new one is up.
+     *
+     * What comes back is the opening the session recorded when it started (see
+     * startResolved): a template's instruction, or the human's from the dialog -
+     * never a spawning peer's task, which would start that work over. A brief
+     * that rides in on a flag needs nothing here; a typed one goes first, as it
+     * did at start.
+     */
+    async clearSession(sessionId) {
+        const session = await this.sessions.restartFresh(sessionId);
+        const opening = [this.typedBrief(session), this.store.getOpeningPrompt(sessionId)]
+            .filter((part) => !!part)
+            .join('\n\n');
+        if (opening)
+            void this.deliverOpeningInstruction(session.id, opening);
+        return session;
+    }
     async resumeWorkspace(workspaceId) {
         const out = [];
         for (const s of this.sessions.list()) {
@@ -900,7 +1036,9 @@ export class Hub extends EventEmitter {
             workspace: ws?.name ?? null,
             cwd: s.cwd,
             profile: s.profile,
-            spawnedBy: s.spawnedBy ? this.sessions.get(s.spawnedBy)?.address ?? null : null,
+            // By address rather than through the local id, which a parent on
+            // another machine never had.
+            spawnedBy: s.parentAddress ?? null,
         };
     }
     /**
@@ -919,7 +1057,17 @@ export class Hub extends EventEmitter {
      */
     async listTemplates(sessionId, id) {
         this.requireSession(sessionId);
-        const shown = this.templates.info().map((t) => ({
+        const shown = this.uplink?.attached ? await this.templateViewsWithCanvas() : this.templateViews();
+        if (id === undefined)
+            return { templates: shown };
+        const one = shown.find((t) => t.id === id);
+        if (!one)
+            throw new Error(`no template "${id}"`);
+        return one;
+    }
+    /** This hub's own templates, in the shape list_templates answers with. */
+    templateViews() {
+        return this.templates.info().map((t) => ({
             id: t.id,
             description: t.description,
             agent: t.agent,
@@ -934,12 +1082,48 @@ export class Hub extends EventEmitter {
             error: t.error,
             source: t.source,
         }));
-        if (id === undefined)
-            return { templates: shown };
-        const one = shown.find((t) => t.id === id);
-        if (!one)
-            throw new Error(`no template "${id}"`);
-        return one;
+    }
+    /**
+     * An attached hub's list: the templates the canvas made, and the bare agents
+     * this machine has (see overlayCanvasTemplates).
+     *
+     * Templates are central (issue 22), so this hub's own stored or declared
+     * ones are left out: nobody on the canvas can see or edit them, and
+     * spawn_agent refuses them here for the same reason. A link that cannot
+     * answer leaves this machine's bare agents, which are still true.
+     */
+    async templateViewsWithCanvas() {
+        const local = this.templateViews();
+        try {
+            const canvas = await this.uplink.ask({ t: 'listTemplates' });
+            return overlayCanvasTemplates(canvas, local);
+        }
+        catch {
+            return overlayCanvasTemplates([], local);
+        }
+    }
+    /**
+     * The canvas answering an attached hub's spawn_agent: what `profile` means
+     * here, with the caller's own template standing in when it named none.
+     *
+     * `picked: null` for anything the canvas did not make - a bare agent id, or
+     * a template derived from one - which the asking hub then resolves against
+     * its own config, since that is what it will actually launch. A template
+     * that exists but cannot be used is an answer rather than a failed relay, so
+     * the asking hub can tell it apart from a link that did not answer.
+     */
+    pickTemplateFor(ask) {
+        const inherited = ask.parentTemplate ? this.templates.get(ask.parentTemplate) : null;
+        const id = ask.profile ?? (inherited && !inherited.error ? ask.parentTemplate : ask.parentProfile);
+        const t = this.templates.get(id);
+        if (!t || t.source === 'derived')
+            return { picked: null };
+        try {
+            return { picked: this.resolveTemplate({ profile: id }) };
+        }
+        catch (err) {
+            return { error: err.message };
+        }
     }
     /**
      * Every machine on the canvas, for `spawn_agent`'s `host` to name and
@@ -1174,6 +1358,11 @@ export class Hub extends EventEmitter {
             return this.store.getHost(ws.hostId)?.label ?? 'remote';
         return this.thisMachineLabel();
     }
+    /**
+     * Every agent the caller can see, on every machine: lineage decides who
+     * that is (see agents/visibility.ts), not the machine or the workspace.
+     * `workspace` only narrows what is already visible.
+     */
     async listAgents(sessionId, workspace) {
         const me = this.requireSession(sessionId);
         const wsById = new Map(this.store.listWorkspaces().map((w) => [w.id, w]));
@@ -1186,6 +1375,7 @@ export class Hub extends EventEmitter {
             status: s.status,
             statusText: s.statusText,
             host: myLabel,
+            parentAddress: s.parentAddress ?? null,
             isYou: s.id === me.id,
         }));
         const hostLabels = new Map(this.store.listHosts().map((h) => [h.id, h.label]));
@@ -1202,6 +1392,7 @@ export class Hub extends EventEmitter {
                 status: s.status,
                 statusText: s.statusText,
                 host: (hostId ? hostLabels.get(hostId) : undefined) ?? 'remote',
+                parentAddress: s.parentAddress ?? null,
                 isYou: false,
             };
         });
@@ -1209,12 +1400,13 @@ export class Hub extends EventEmitter {
         // is the only complete one, so this is where an agent on an attached
         // machine learns that anything exists beyond this machine.
         const fromCanvas = (this.uplink?.agents() ?? []).map((a) => ({ ...a, isYou: false }));
-        return [...local, ...remote, ...fromCanvas].filter((a) => !workspace || a.workspace === workspace);
+        return [...local, ...remote, ...fromCanvas].filter((a) => (a.isYou || canSee(me, a)) && (!workspace || a.workspace === workspace));
     }
     async sendMessage(sessionId, to, text) {
         const me = this.requireSession(sessionId);
         if (me.address === to)
             throw new Error('cannot send a message to yourself');
+        this.requireVisible(me, to);
         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.
@@ -1256,6 +1448,7 @@ export class Hub extends EventEmitter {
             statusText: s.statusText,
             // What the machine that owns the canvas is called, from anywhere else.
             host: 'canvas',
+            parentAddress: s.parentAddress ?? null,
         }));
         const elsewhere = this.peers
             .sessions()
@@ -1268,6 +1461,7 @@ export class Hub extends EventEmitter {
             status: s.status,
             statusText: s.statusText,
             host: hostLabels.get(this.peers.hostIdFor(s.address) ?? '') ?? 'remote',
+            parentAddress: s.parentAddress ?? null,
         }));
         return [...here, ...elsewhere];
     }
@@ -1320,16 +1514,58 @@ export class Hub extends EventEmitter {
             throw err;
         }
     }
+    /**
+     * What a spawn_agent `profile` resolves to for this caller.
+     *
+     * 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
+     * since failed to load falls back to the agent itself — a spawn must not
+     * die because config changed under a running parent; a profile the
+     * spawning agent named explicitly always wins.
+     *
+     * On an attached hub the canvas is asked first, because that is where
+     * templates are made (see templateViewsWithCanvas). Only a template the
+     * canvas actually holds comes back from there. Anything else, and any link
+     * that does not answer, is resolved against this hub's own config - but
+     * only as a bare agent or its derived template: templates are central, and
+     * one stored or declared only on this machine is not one.
+     */
+    async pickSpawnTemplate(me, profile) {
+        if (this.uplink?.attached) {
+            let answer = null;
+            try {
+                answer = await this.uplink.ask({
+                    t: 'pickTemplate',
+                    profile,
+                    parentTemplate: me.template,
+                    parentProfile: me.profile,
+                });
+            }
+            catch {
+                // The link, not the template: resolve here as if there were none.
+            }
+            if (answer && 'error' in answer)
+                throw new Error(answer.error);
+            if (answer?.picked)
+                return answer.picked;
+            const own = (id) => {
+                const t = this.templates.get(id);
+                return !t || t.source === 'derived';
+            };
+            if (profile !== undefined && !own(profile))
+                throw new Error(`no template "${profile}"`);
+            // The caller's own template came from the canvas, which has just said
+            // it no longer holds it; its agent is what is left.
+            const inherit = profile ?? (me.template && own(me.template) ? me.template : me.profile);
+            return this.resolveTemplate({ profile: inherit });
+        }
+        const inherited = me.template ? this.templates.get(me.template) : null;
+        const inherit = profile ?? (inherited && !inherited.error ? me.template : me.profile);
+        return this.resolveTemplate({ profile: inherit });
+    }
     async spawnAgent(sessionId, opts) {
         const me = this.requireSession(sessionId);
-        // 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
-        // since failed to load falls back to the agent itself — a spawn must not
-        // die because config changed under a running parent; a profile the
-        // spawning agent named explicitly always wins.
-        const inherited = me.template ? this.templates.get(me.template) : null;
-        const inherit = opts.profile ?? (inherited && !inherited.error ? me.template : me.profile);
         /*
          * Resolved, and the opening instruction built, ahead of the workspace: a
          * `host` needs the resolved agent id before it can even ask whether that
@@ -1342,7 +1578,7 @@ export class Hub extends EventEmitter {
          * order, so the opening merges here and rides to the child however it
          * gets there.
          */
-        const picked = this.resolveTemplate({ profile: inherit });
+        const picked = await this.pickSpawnTemplate(me, opts.profile);
         const instruction = opts.prompt ? `[from ${me.address}] ${opts.prompt}` : null;
         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
@@ -1362,6 +1598,7 @@ export class Hub extends EventEmitter {
                 effort: picked.effort,
                 env: picked.env,
                 opening,
+                restore: picked.prompt ?? null,
                 promptGiven: !!opts.prompt,
             }, { timeoutMs: SPAWN_RELAY_TIMEOUT_MS });
         }
@@ -1388,13 +1625,7 @@ export class Hub extends EventEmitter {
                 throw new Error(`unknown workspace "${opts.workspace}"`);
             ws = found;
         }
-        const child = await this.startSession({
-            workspaceId: ws.id,
-            profile: inherit,
-            name: opts.name,
-            spawnedBy: me.id,
-            prompt: opening,
-        });
+        const child = await this.startPicked({ workspaceId: ws.id, name: opts.name, spawnedBy: me.id, parentAddress: me.address }, { ...picked, prompt: opening, restorePrompt: picked.prompt ?? null });
         return {
             address: child.address,
             workspace: ws.name,
@@ -1431,13 +1662,12 @@ export class Hub extends EventEmitter {
                 model: ask.model,
                 effort: ask.effort,
                 prompt: ask.opening,
+                restorePrompt: ask.restore ?? null,
                 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,
+                // By address, the one id every hub agrees on: the spawner lives on
+                // a hub this canvas has no local id for.
+                spawnedByAddress: ask.from,
             })
             : await this.startResolved({
                 workspaceId: ws.id,
@@ -1446,9 +1676,14 @@ export class Hub extends EventEmitter {
                 model: ask.model,
                 effort: ask.effort,
                 prompt: ask.opening,
+                restorePrompt: ask.restore ?? null,
                 env: ask.env,
                 name: ask.name,
+                // No local id to give - the session table's foreign key would
+                // reject one from another machine - but the address still says
+                // whose child this is, which is what visibility is decided from.
                 spawnedBy: null,
+                parentAddress: ask.from,
             });
         return {
             address: child.address,
@@ -1473,27 +1708,64 @@ export class Hub extends EventEmitter {
     /**
      * Wait for the CLI to be up, then type. Written straight away the text lands
      * before the program is reading it; the wait is for output to arrive and
-     * then pause, which is as close to "it has drawn its prompt" as this gets
+     * then stop, which is as close to "it has drawn its prompt" as this gets
      * without knowing the CLI.
+     *
+     * Quiet measured from the last output, not a fixed delay from the first.
+     * The first output is not the CLI at all on Windows - ConPTY draws its own
+     * the moment the process exists - so a delay counted from there was a guess
+     * at how long the CLI takes to load, and a slower machine lost it: the start
+     * of the instruction went into a program not yet reading, the rest landed
+     * in its composer, and the Enter went nowhere. A CLI that never stops
+     * drawing still gets its instruction, once the cap is up.
+     *
+     * Nor into a question. A CLI that opens by asking the human something -
+     * Claude Code in a folder it has not been trusted in - is quiet too, and
+     * the instruction typed at it was spent on the question: gone, or partly
+     * taken as answers to it. Such a screen is waited out until it changes.
      */
     async typeWhenReady(sessionId, text) {
         const pty = this.sessions.pty(sessionId);
         if (!pty)
             return;
+        const profile = this.profiles.get(this.sessions.get(sessionId)?.profile ?? '');
+        const hint = profile?.askingHint ? new RegExp(profile.askingHint, 'i') : null;
+        // A question on screen outlasts any cap: the human answers it when they
+        // get to the window, and the instruction is still wanted after that.
+        const asking = () => !!hint && hint.test(pty.tailLines(pty.rows));
         const ready = await new Promise((res) => {
             let settled = false;
+            let seen = false;
+            let quiet = null;
             const done = (v) => {
                 if (settled)
                     return;
                 settled = true;
-                clearTimeout(timer);
+                clearTimeout(cap);
+                if (quiet)
+                    clearTimeout(quiet);
                 pty.off('data', onData);
+                pty.off('exit', onExit);
                 res(v);
             };
-            const onData = () => setTimeout(() => done(true), 1200);
-            const timer = setTimeout(() => done(false), 20_000);
-            timer.unref?.();
+            const onData = () => {
+                seen = true;
+                if (quiet)
+                    clearTimeout(quiet);
+                quiet = setTimeout(() => {
+                    quiet = null;
+                    if (!asking())
+                        done(true);
+                }, OPENING_QUIET_MS);
+            };
+            const onExit = () => done(false);
+            const cap = setTimeout(() => {
+                if (!asking())
+                    done(seen);
+            }, OPENING_READY_CAP_MS);
+            cap.unref?.();
             pty.on('data', onData);
+            pty.on('exit', onExit);
         });
         if (!ready || !pty.running)
             return;
@@ -1511,7 +1783,8 @@ export class Hub extends EventEmitter {
     }
     async readScreen(sessionId, address, lines) {
         const me = this.requireSession(sessionId);
-        const result = await this.readScreenAt(address, lines);
+        this.requireVisible(me, address);
+        const result = await this.readScreenAt(me.address, 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
@@ -1525,13 +1798,15 @@ export class Hub extends EventEmitter {
      * agent of its own, or a peer that authenticated one and is asking on its
      * behalf. Resolves the address the same three ways a delivery does.
      */
-    async readScreenAt(address, lines) {
+    async readScreenAt(from, address, lines) {
         const where = this.locate(address);
         if (where === 'remote')
             return this.peers.readScreen(address, lines);
         if (where === 'uplink') {
             return this.uplink.ask({
                 t: 'readScreen',
+                // The canvas decides again whether the caller may look.
+                from,
                 address,
                 lines,
             });
@@ -1557,9 +1832,13 @@ export class Hub extends EventEmitter {
         const me = this.requireSession(sessionId);
         const target = this.sessions.getByAddress(address);
         if (!target) {
-            // Spawn lineage lives on the hub that owns the session, so the
-            // spawned-by rule below is enforced over there, by that hub.
-            if (this.locate(address) === 'remote') {
+            // A remote session reports who spawned it by address, so the rule
+            // below can be judged here before the host is asked to stop it.
+            const remote = this.peers.find(address)?.session;
+            if (remote) {
+                if (remote.parentAddress !== me.address) {
+                    throw new Error(`"${address}" was not spawned by you; only its spawner may stop it`);
+                }
                 await this.peers.stopSession(address);
                 return { stopped: address };
             }
@@ -1568,8 +1847,9 @@ export class Hub extends EventEmitter {
         if (target.id === me.id)
             throw new Error('use your own exit command to stop yourself');
         // An agent may only stop what it created. Otherwise a single confused
-        // agent could take down the whole canvas.
-        if (target.spawnedBy !== me.id) {
+        // agent could take down the whole canvas. Judged by address, so a child
+        // whose spawner is on another machine is judged the same as a local one.
+        if (target.parentAddress !== me.address) {
             throw new Error(`"${address}" was not spawned by you; only its spawner may stop it`);
         }
         this.sessions.stop(target.id);