@kdonev/termscape 0.1.6 → 0.1.8

package/dist/hub.js

@@ -13,19 +13,37 @@ 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.6';
+export const HUB_VERSION = '0.1.8';
 /**
  * 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;
+/**
+ * How long a delivery waits for a starting agent before going in regardless.
+ *
+ * There has to be a bound. A session's readiness gate deliberately outlasts
+ * its own cap while a question is on screen - the instruction is still wanted
+ * once the human answers - but a `send_message` that blocks its caller until
+ * somebody walks over to a window is worse than a message that arrives badly.
+ * So the wait is bounded here, and past it delivery is what it always was:
+ * immediate, recorded, and the CLI's business.
+ */
+const DELIVERY_WAIT_CAP_MS = 20_000;
 /** Colours cycled through when a workspace is created, for canvas grouping. */
 const WORKSPACE_COLORS = [
     '#7c9cf5',
@@ -77,6 +95,16 @@ export class Hub extends EventEmitter {
      * two roles a null check rather than a flag.
      */
     uplink = null;
+    /**
+     * Per session: resolves once its CLI is reading and its opening instruction,
+     * if it had one, has been typed and sent.
+     *
+     * Every delivery to a local session queues behind this. Without it a message
+     * sent to an agent that was still starting - which is exactly what an agent
+     * that has just called `spawn_agent` does next - was written into a program
+     * not yet reading, and sat in the composer unsent forever (issue 27).
+     */
+    opened = new Map();
     announceTimer = null;
     /** Live SSH tunnels, keyed by host id. Not persisted: they die with the hub. */
     tunnels = new Map();
@@ -113,12 +141,21 @@ export class Hub extends EventEmitter {
         this.sessions = new SessionManager(this.store, this.profiles, this.tokens, 'http://127.0.0.1:0');
         this.router = new MessageRouter(this.store, this.sessions, this.profiles, (m) => this.emit('message', m));
         this.sessions.on('session', (s) => this.emit('session', s));
-        this.sessions.on('removed', (id, address) => this.emit('removed', id, address));
+        this.sessions.on('removed', (id, address) => {
+            // Nothing left to open, and nothing left to hold a delivery for.
+            this.opened.delete(id);
+            this.emit('removed', id, address);
+        });
         this.sessions.on('data', (id, chunk) => this.emit('data', id, chunk));
         this.peers = new PeerRegistry(this.store, HUB_VERSION, (address) => this.sessions.getByAddress(address)?.id ?? null);
         // 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,11 +172,22 @@ 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':
@@ -148,6 +196,16 @@ export class Hub extends EventEmitter {
                     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,
@@ -195,6 +253,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`.
      *
@@ -440,7 +531,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
@@ -461,7 +566,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,
@@ -527,6 +632,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;
@@ -684,7 +804,10 @@ export class Hub extends EventEmitter {
         };
     }
     async startSession(opts) {
-        return this.startPicked(opts, this.resolveTemplate(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.
@@ -700,7 +823,6 @@ export class Hub extends EventEmitter {
         // 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
@@ -718,7 +840,7 @@ export class Hub extends EventEmitter {
                 // 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 });
@@ -749,6 +871,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
@@ -764,35 +887,10 @@ export class Hub extends EventEmitter {
         const opening = [this.typedBrief(session), opts.prompt]
             .filter((part) => !!part)
             .join('\n\n');
-        if (opening)
-            void this.deliverOpeningInstruction(session.id, opening);
+        this.noteOpening(session.id, opening || null);
         this.store.setOpeningPrompt(session.id, opts.restorePrompt === undefined ? (opts.prompt ?? null) : opts.restorePrompt);
         return session;
     }
-    /**
-     * The agent cleared its conversation, so type its opening in again.
-     *
-     * Claude Code's `/clear` starts a new conversation in the same process, and
-     * everything the opening instruction told it - the role a template gave it,
-     * what the human said it was for - goes with the old one. The brief does
-     * not need this when it rode in on a flag, since that is system prompt and
-     * survives; a typed brief is conversation like the instruction, so it goes
-     * first here exactly as it did at start.
-     *
-     * Reported by the agent's own SessionStart hook (see wiring.ts), so this
-     * fires for a clear and never for a start or a resume, which must not
-     * repeat the opening.
-     */
-    restoreOpeningAfterClear(sessionId) {
-        const session = this.sessions.get(sessionId);
-        if (!session)
-            return;
-        const opening = [this.typedBrief(session), this.store.getOpeningPrompt(sessionId)]
-            .filter((part) => !!part)
-            .join('\n\n');
-        if (opening)
-            void this.typeWhenReady(sessionId, opening, { alreadyUp: true });
-    }
     /**
      * The brief for an agent that cannot be handed one, or null.
      *
@@ -826,9 +924,31 @@ export class Hub extends EventEmitter {
      */
     async resumeSession(sessionId) {
         const session = await this.sessions.resume(sessionId);
-        const brief = this.typedBrief(session);
-        if (brief)
-            void this.deliverOpeningInstruction(session.id, brief);
+        // A fresh CLI, so a fresh gate: messages must wait for this one to be
+        // reading just as they did when it first started.
+        this.noteOpening(session.id, this.typedBrief(session));
+        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');
+        this.noteOpening(session.id, opening || null);
         return session;
     }
     async resumeWorkspace(workspaceId) {
@@ -939,7 +1059,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,
         };
     }
     /**
@@ -985,13 +1107,13 @@ export class Hub extends EventEmitter {
         }));
     }
     /**
-     * An attached hub's list: what the canvas has, over what this hub has.
+     * An attached hub's list: the templates the canvas made, and the bare agents
+     * this machine has (see overlayCanvasTemplates).
      *
-     * Templates are made on the canvas, so an agent over here that could only
-     * see this hub's own list never saw the ones a human had just added. The
-     * canvas's derived templates are left out - they describe the canvas
-     * machine's agents, and this machine's own are already in the local list.
-     * A link that cannot answer leaves the local list, which is still true.
+     * 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();
@@ -1000,7 +1122,7 @@ export class Hub extends EventEmitter {
             return overlayCanvasTemplates(canvas, local);
         }
         catch {
-            return local;
+            return overlayCanvasTemplates([], local);
         }
     }
     /**
@@ -1259,6 +1381,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]));
@@ -1271,6 +1398,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]));
@@ -1287,6 +1415,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,
             };
         });
@@ -1294,12 +1423,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.
@@ -1341,6 +1471,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()
@@ -1353,6 +1484,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];
     }
@@ -1369,6 +1501,13 @@ export class Hub extends EventEmitter {
         // records the failed attempt with its reason, which is what keeps the
         // promise that no message is ever dropped silently.
         if (where === 'local' || where === null) {
+            // Behind the target's opening, if it is still starting. This is the one
+            // place delivery is not immediate, and the exception earns itself: the
+            // alternative is writing into a CLI that is not reading, which is not a
+            // delivery at all.
+            const target = this.sessions.getByAddress(to);
+            if (target)
+                await this.awaitOpened(target.id);
             const r = this.router.send(fromAddr, to, text);
             if (!r.delivered)
                 throw new Error(r.error ?? 'delivery failed');
@@ -1417,8 +1556,10 @@ export class Hub extends EventEmitter {
      *
      * 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.
+     * 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) {
@@ -1438,6 +1579,16 @@ export class Hub extends EventEmitter {
                 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);
@@ -1504,7 +1655,7 @@ export class Hub extends EventEmitter {
                 throw new Error(`unknown workspace "${opts.workspace}"`);
             ws = found;
         }
-        const child = await this.startPicked({ workspaceId: ws.id, name: opts.name, spawnedBy: me.id }, { ...picked, prompt: opening, restorePrompt: picked.prompt ?? null });
+        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,
@@ -1544,11 +1695,9 @@ export class Hub extends EventEmitter {
                 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,
@@ -1560,7 +1709,11 @@ export class Hub extends EventEmitter {
                 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,
@@ -1582,56 +1735,145 @@ export class Hub extends EventEmitter {
     async deliverOpeningInstruction(sessionId, prompt) {
         await this.typeWhenReady(sessionId, prompt);
     }
+    /**
+     * Record how a session opens, and hold every later delivery behind it.
+     *
+     * Registered whether or not there is anything to type: an agent started with
+     * no instruction at all still has a CLI that is not reading yet, and that is
+     * the case issue 27 was reported for. Not awaited by the caller - the window
+     * appears now - but stored, so the first message to arrive waits for the
+     * same moment the instruction would have.
+     */
+    noteOpening(sessionId, opening) {
+        const done = opening
+            ? this.deliverOpeningInstruction(sessionId, opening)
+            : this.awaitReady(sessionId).then(() => { });
+        // Failures are the gate opening, not the gate jamming: a session that died
+        // on the way up must not hold its own message log hostage.
+        this.opened.set(sessionId, done.catch(() => { }));
+    }
+    /**
+     * Wait for a local session to be ready to be typed at, but not forever.
+     *
+     * Once resolved the promise stays resolved, so this costs a steady-state
+     * delivery a microtask and nothing else.
+     */
+    async awaitOpened(sessionId) {
+        const gate = this.opened.get(sessionId);
+        if (!gate)
+            return;
+        let timer;
+        try {
+            await Promise.race([
+                gate,
+                new Promise((res) => {
+                    timer = setTimeout(res, DELIVERY_WAIT_CAP_MS);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     /**
      * 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.
      *
-     * `alreadyUp` is for a CLI that has been running all along and is only
-     * redrawing, as after a `/clear`. It may already have finished drawing by
-     * the time this is called, and an idle one then prints nothing at all - so
-     * the pause is counted from now as well as from its next output, and
-     * running out of patience still types rather than giving up.
+     * 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, opts = {}) {
+    async typeWhenReady(sessionId, text) {
+        const ready = await this.awaitReady(sessionId);
         const pty = this.sessions.pty(sessionId);
-        if (!pty)
-            return;
-        const ready = await new Promise((res) => {
-            let settled = false;
-            const done = (v) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(timer);
-                pty.off('data', onData);
-                res(v);
-            };
-            const onData = () => setTimeout(() => done(true), 1200);
-            const timer = setTimeout(() => done(!!opts.alreadyUp), 20_000);
-            timer.unref?.();
-            pty.on('data', onData);
-            if (opts.alreadyUp)
-                onData();
-        });
-        if (!ready || !pty.running)
+        if (!ready || !pty?.running)
             return;
         const session = this.sessions.get(sessionId);
         if (!session)
             return;
         const mode = this.profiles.get(session.profile)?.inject ?? 'bracketed';
         try {
-            this.sessions.inject(sessionId, encodeInjection(text, mode), INJECT_SUBMIT);
+            // Awaited, so that a caller holding this session's readiness gate is not
+            // released until the Enter is in: a message injected between the paste
+            // and its Enter is folded into the same prompt.
+            await this.sessions.inject(sessionId, encodeInjection(text, mode), INJECT_SUBMIT);
         }
         catch {
             // The agent died between the readiness check and the write; the message
             // log already reflects that it never started.
         }
     }
+    /**
+     * Wait until the CLI in a session is up and reading, or give up.
+     *
+     * Split out of `typeWhenReady` because typing is not the only thing that has
+     * to wait for this. A message delivered to an agent whose CLI has not
+     * started reading is written into a program that is not listening: the paste
+     * lands in a composer that is not there yet and the Enter goes nowhere, and
+     * what the sender sees is a delivery that was recorded and never acted on.
+     * See `deliverFrom`.
+     */
+    async awaitReady(sessionId) {
+        const pty = this.sessions.pty(sessionId);
+        if (!pty)
+            return false;
+        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));
+        return new Promise((res) => {
+            let settled = false;
+            let seen = false;
+            let quiet = null;
+            const done = (v) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(cap);
+                if (quiet)
+                    clearTimeout(quiet);
+                pty.off('data', onData);
+                pty.off('exit', onExit);
+                res(v);
+            };
+            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);
+        });
+    }
     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
@@ -1645,13 +1887,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,
             });
@@ -1677,9 +1921,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 };
             }
@@ -1688,8 +1936,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);