@calliopelabs/cli 3.3.0 → 3.4.0

package/dist/attach.js

@@ -4,7 +4,8 @@
  * `calliope attach` connects to a running agent host over the Agent Host
  * Protocol (JSON-RPC over WebSocket) and follows a session another surface
  * started (the IDE, desktop, AGTerm, Chat Studio), answering its tool-call
- * confirmations from the terminal.
+ * confirmations from the terminal, including any already waiting when it joins
+ * and those inside a subagent, which the session's `inputNeeded` lists (#394).
  *
  *   calliope attach --url <ws-url>                 list the host's sessions
  *   calliope attach --url <ws-url> <session-uri>   follow one, approve its tool calls
@@ -20,8 +21,10 @@
  * CALLIOPE_AHP=off is the kill switch.
  */
 import * as readline from 'readline';
+import WebSocket from 'ws';
 /** Protocol versions offered in `initialize`; keep in step with calliope-vscode scripts/ahp-supported-versions.json. */
-export const SUPPORTED_VERSIONS = ['1.0.0', '0.6.0'];
+export const SUPPORTED_VERSIONS = ['1.0.0', '0.9.0', '0.6.0'];
+export const ATTACH_TIMEOUT_MS = 60_000;
 export const FALLBACK_EXIT = 3;
 const ROOT = 'ahp-root://';
 const UNSUPPORTED_PROTOCOL_VERSION = -32005;
@@ -34,13 +37,17 @@ export function defaultChatUri(session) {
     return `ahp-chat://default/${Buffer.from(session).toString('base64url')}`;
 }
 /**
- * Node's WebSocket hides the status of a refused upgrade, so ask plainly first:
- * an authorized agent-host route answers a plain GET with 426 Upgrade Required.
+ * Classify authentication refusals before upgrading the transport. An authorized
+ * agent-host route answers a plain GET with 426 Upgrade Required.
  */
-export async function preflight(wsUrl, headers, fetchImpl = fetch) {
+export async function preflight(wsUrl, headers, fetchImpl = fetch, options = {}) {
     const http = wsUrl.replace(/^ws/, 'http');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? ATTACH_TIMEOUT_MS);
+    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
     try {
-        const res = await fetchImpl(http, { headers, redirect: 'manual' });
+        const res = await fetchImpl(http, { headers, redirect: 'manual', signal });
+        void res.body?.cancel().catch(() => { });
         if (res.status === 426 || res.ok) {
             return undefined;
         }
@@ -48,8 +55,12 @@ export async function preflight(wsUrl, headers, fetchImpl = fetch) {
         const toLogin = res.status >= 300 && res.status < 400 && /\/(hub\/)?login|oauth/.test(res.headers.get('location') ?? '');
         return fail(res.status === 401 || res.status === 403 || toLogin ? 'auth' : 'unreachable', `the host route answered HTTP ${res.status}`);
     }
-    catch (err) {
-        return fail('unreachable', `cannot reach ${http}: ${err.message}`);
+    catch {
+        return fail('unreachable', signal.aborted ? 'host preflight timed out' : 'host preflight failed');
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
     }
 }
 /** Find (or start) the user's agent host on a JupyterHub; returns its WebSocket URL. */
@@ -57,10 +68,30 @@ export async function resolveHubHost(opts) {
     const { hubUrl, user, token, serverName = 'agenthost', fetchImpl = fetch, timeoutMs = 60_000 } = opts;
     const api = new URL('hub/api/', hubUrl.endsWith('/') ? hubUrl : `${hubUrl}/`);
     const headers = { Authorization: `token ${token}` };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const request = (url, init = {}) => fetchImpl(url, {
+        ...init, signal: controller.signal, redirect: 'error', credentials: 'omit',
+    });
     const deadline = Date.now() + timeoutMs;
     try {
+        const tap = await request(new URL('/agent-host/status', hubUrl), { headers });
+        if (tap.status === 401)
+            return fail('auth', 'hub tap refused the credential');
+        if (tap.status !== 404) {
+            const body = await tap.json();
+            if (tap.ok && body?.enabled === true && body.endpoint === '/agent-host/') {
+                const ws = new URL('/agent-host/', hubUrl);
+                ws.protocol = ws.protocol === 'https:' ? 'wss:' : 'ws:';
+                return { ok: true, url: ws.toString() };
+            }
+            const reason = body?.reason === 'disabled' || body?.reason === 'unentitled' || body?.reason === 'auth'
+                ? body.reason : tap.status === 403 ? 'auth' : 'unreachable';
+            return fail(reason, `hub tap answered ${tap.status}`);
+        }
         for (let spawned = false;;) {
-            const res = await fetchImpl(new URL(`users/${encodeURIComponent(user)}`, api), { headers });
+            controller.signal.throwIfAborted();
+            const res = await request(new URL(`users/${encodeURIComponent(user)}`, api), { headers });
             if (!res.ok) {
                 return fail(res.status === 401 || res.status === 403 ? 'auth' : 'unreachable', `hub user lookup answered ${res.status}`);
             }
@@ -68,30 +99,35 @@ export async function resolveHubHost(opts) {
             const server = body.servers?.[serverName];
             if (server?.ready && server.url) {
                 const ws = new URL(`${server.url}agent-host/`, hubUrl);
+                if (ws.origin !== new URL(hubUrl).origin)
+                    return fail('unreachable', 'hub answered a foreign server URL');
                 ws.protocol = ws.protocol === 'https:' ? 'wss:' : 'ws:';
                 return { ok: true, url: ws.toString() };
             }
-            if (!spawned) {
-                const spawn = await fetchImpl(new URL(`users/${encodeURIComponent(user)}/servers/${encodeURIComponent(serverName)}`, api), { method: 'POST', headers });
-                if (spawn.status === 401) {
+            if (!spawned && !server?.pending) {
+                const spawn = await request(new URL(`users/${encodeURIComponent(user)}/servers/${encodeURIComponent(serverName)}`, api), {
+                    method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ profile: serverName }),
+                });
+                if (spawn.status === 401)
                     return fail('auth', 'hub refused the token');
-                }
                 if (spawn.status === 403 || (spawn.status === 400 && !server)) {
                     return fail('unentitled', `hub refused to start ${serverName}: ${spawn.status}`);
                 }
-                if (!spawn.ok && spawn.status !== 400) {
+                if (!spawn.ok && spawn.status !== 400)
                     return fail('unreachable', `hub could not start ${serverName}: ${spawn.status}`);
-                }
                 spawned = true;
             }
-            if (Date.now() >= deadline) {
+            if (Date.now() >= deadline)
                 return fail('unreachable', `${serverName} not ready within ${Math.round(timeoutMs / 1000)}s`);
-            }
-            await new Promise(resolve => setTimeout(resolve, 1000));
+            await new Promise(resolve => setTimeout(resolve, Math.min(1000, Math.max(0, deadline - Date.now()))));
         }
     }
     catch (err) {
-        return fail('unreachable', `hub unreachable: ${err.message}`);
+        return fail('unreachable', controller.signal.aborted ? 'hub discovery timed out' : `hub unreachable: ${err.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
     }
 }
 /** The minimal JSON-RPC client attach needs, over any WebSocket-shaped object. */
@@ -99,37 +135,87 @@ export class AhpConnection {
     ws;
     nextId = 1;
     pending = new Map();
+    failure;
+    onClosed;
     actions = [];
-    closed;
+    set closed(callback) {
+        this.onClosed = callback;
+        if (this.failure)
+            callback?.(this.failure);
+    }
     constructor(ws) {
         this.ws = ws;
         ws.addEventListener('message', ev => {
-            const msg = JSON.parse(String(ev.data));
+            if (this.failure)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(String(ev.data));
+                if (!msg || typeof msg !== 'object' || Array.isArray(msg))
+                    throw new Error('invalid frame');
+            }
+            catch {
+                this.stop('invalid host message');
+                return;
+            }
             if (msg.id !== undefined && this.pending.has(msg.id)) {
-                this.pending.get(msg.id).resolve(msg);
+                const pending = this.pending.get(msg.id);
                 this.pending.delete(msg.id);
+                pending.cleanup();
+                pending.resolve(msg);
                 return;
             }
             if (msg.method === 'action' && msg.params?.action) {
                 for (const fn of this.actions) {
-                    fn(msg.params.action, msg.params.channel);
+                    fn(msg.params.action, msg.params.channel, msg.params.serverSeq);
                 }
             }
         });
-        ws.addEventListener('close', ev => this.closed?.(`connection closed (${ev.code ?? 'unknown'})`));
+        ws.addEventListener('close', ev => this.stop(`connection closed (${ev.code ?? 'unknown'})`));
+        ws.addEventListener('error', () => this.stop('host transport failed'));
     }
-    call(method, params) {
+    stop(detail) {
+        if (this.failure)
+            return;
+        this.failure = detail;
+        for (const pending of this.pending.values()) {
+            pending.cleanup();
+            pending.resolve({ error: { code: -32000, message: detail } });
+        }
+        this.pending.clear();
+        this.onClosed?.(detail);
+        try {
+            this.ws.terminate ? this.ws.terminate() : this.ws.close();
+        }
+        catch { /* Already closed. */ }
+    }
+    call(method, params, options = {}) {
+        if (this.failure)
+            return Promise.resolve({ error: { code: -32000, message: this.failure } });
+        if (options.signal?.aborted) {
+            this.stop('host setup timed out');
+            return Promise.resolve({ error: { code: -32000, message: this.failure } });
+        }
         const id = this.nextId++;
         return new Promise(resolve => {
-            this.pending.set(id, { resolve });
-            this.ws.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+            const aborted = () => this.stop('host setup timed out');
+            const timer = setTimeout(() => this.stop('host request timed out'), options.timeoutMs ?? ATTACH_TIMEOUT_MS);
+            const cleanup = () => { clearTimeout(timer); options.signal?.removeEventListener('abort', aborted); };
+            this.pending.set(id, { resolve, cleanup });
+            options.signal?.addEventListener('abort', aborted, { once: true });
+            try {
+                this.ws.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+            }
+            catch {
+                this.stop('host request failed');
+            }
         });
     }
     dispatch(channel, clientSeq, action) {
         this.ws.send(JSON.stringify({ jsonrpc: '2.0', method: 'dispatchAction', params: { channel, clientSeq, action } }));
     }
     close() {
-        this.ws.close();
+        this.stop('connection closed');
     }
 }
 /** Classify the `initialize` answer; undefined when the host is usable. */
@@ -144,19 +230,88 @@ export function checkInitialize(msg, supported = SUPPORTED_VERSIONS) {
     }
     return undefined;
 }
+const text = (value, fallback) => typeof value === 'string' ? value : value?.markdown ?? fallback;
 /**
  * Render a session's chat actions and answer tool confirmations. Resolves when
  * the connection closes, or after the next turn with `once`.
+ *
+ * `subscribed` is the chat channel's `subscribe` snapshot for a client joining
+ * a session already under way: the confirmations it shows waiting are asked
+ * first. `sessionSubscribed` is the session channel's: its `inputNeeded` lists
+ * the confirmations waiting in the session's other chats (a subagent's), which
+ * are answered on their own chat. Each channel's actions that arrive before its
+ * snapshot are held, then applied after it, skipping any the snapshot already
+ * includes.
  */
-export function follow(conn, session, io) {
+export function follow(conn, session, io, subscribed, sessionSubscribed) {
     const chat = defaultChatUri(session);
     let seq = 0;
     let finish;
+    let ended = false;
     const done = new Promise(resolve => { finish = resolve; });
-    conn.actions.push(async (action, channel) => {
-        if (channel !== chat) {
+    // Confirmations this client knows are open, by tool call, each able to
+    // withdraw its prompt. One prompt at a time: a snapshot can hold several, and
+    // two readline prompts on one stdin garble each other. `request` is the
+    // session's `inputNeeded` id of a confirmation asked for another chat.
+    const open = new Map();
+    let prompts = Promise.resolve();
+    const settled = (toolCallId) => {
+        open.get(toolCallId)?.asked.abort();
+        open.delete(toolCallId);
+    };
+    const settleAll = () => {
+        for (const toolCallId of [...open.keys()]) {
+            settled(toolCallId);
+        }
+    };
+    // The default chat's turn is over, and so are the prompts asked on it. One
+    // for another chat closes when the session removes its request: the host ends
+    // subagent turns with a cancelled parent's, and a background subagent's turn
+    // can outlive the parent's.
+    const settleTurn = () => {
+        for (const [toolCallId, { request }] of [...open]) {
+            if (request === undefined) {
+                settled(toolCallId);
+            }
+        }
+    };
+    // Following is over: no prompt outlives it, or its readline keeps the process alive.
+    const end = (reason) => {
+        if (ended)
+            return;
+        ended = true;
+        settleAll();
+        finish(reason);
+    };
+    const confirm = (target, turnId, toolCallId, confirmationTitle, toolInput, request) => {
+        if (ended || open.has(toolCallId)) {
             return;
         }
+        const asked = new AbortController();
+        open.set(toolCallId, { asked, request });
+        const title = text(confirmationTitle, 'Run tool');
+        const input = typeof toolInput === 'string' ? toolInput : JSON.stringify(toolInput ?? '');
+        const approve = io.approve;
+        if (!approve) {
+            io.write(`\n[waiting for approval elsewhere] ${title}: ${input}\n`);
+            return;
+        }
+        prompts = prompts.then(async () => {
+            if (asked.signal.aborted) {
+                return;
+            }
+            const approved = await approve(title, input, asked.signal);
+            if (asked.signal.aborted) {
+                io.write('\n[approval no longer needed; nothing sent]\n');
+                return;
+            }
+            open.delete(toolCallId);
+            conn.dispatch(target, ++seq, approved
+                ? { type: 'chat/toolCallConfirmed', turnId, toolCallId, approved: true, confirmed: 'user-action' }
+                : { type: 'chat/toolCallConfirmed', turnId, toolCallId, approved: false, reason: 'denied' });
+        }).catch(err => io.write(`\n[approval prompt failed] ${err.message}\n`));
+    };
+    const apply = (action) => {
         switch (action.type) {
             case 'chat/turnStarted':
                 io.write(`\n› ${action.message?.text ?? ''}\n`);
@@ -165,37 +320,110 @@ export function follow(conn, session, io) {
                 io.write(action.content ?? '');
                 break;
             case 'chat/toolCallReady':
-                if (action.confirmationTitle !== undefined) {
-                    const title = typeof action.confirmationTitle === 'string' ? action.confirmationTitle : action.confirmationTitle?.markdown ?? 'Run tool';
-                    const input = typeof action.toolInput === 'string' ? action.toolInput : JSON.stringify(action.toolInput ?? '');
-                    if (!io.approve) {
-                        io.write(`\n[waiting for approval elsewhere] ${title}: ${input}\n`);
-                        break;
-                    }
-                    const approved = await io.approve(title, input);
-                    conn.dispatch(chat, ++seq, approved
-                        ? { type: 'chat/toolCallConfirmed', turnId: action.turnId, toolCallId: action.toolCallId, approved: true, confirmed: 'user-action' }
-                        : { type: 'chat/toolCallConfirmed', turnId: action.turnId, toolCallId: action.toolCallId, approved: false, reason: 'denied' });
+                if (!action.confirmed) {
+                    confirm(chat, action.turnId, action.toolCallId, action.confirmationTitle ?? action.invocationMessage, action.toolInput);
                 }
                 break;
+            case 'chat/toolCallConfirmed':
+                settled(action.toolCallId);
+                break;
             case 'chat/toolCallComplete':
+                settled(action.toolCallId);
                 io.write(`\n[tool ${action.result?.success === false ? 'failed' : 'done'}]\n`);
                 break;
+            case 'chat/turnCancelled':
+                settleTurn();
+                io.write('\n[turn cancelled]\n');
+                if (io.once)
+                    end('cancelled');
+                break;
             case 'chat/turnComplete':
+                settleTurn();
                 io.write('\n[turn complete]\n');
                 if (io.once) {
-                    finish('turnComplete');
+                    end('turnComplete');
                 }
                 break;
             case 'chat/error':
-                io.write(`\n[turn error] ${JSON.stringify(action.error ?? action).slice(0, 200)}\n`);
+                settleTurn();
+                io.write(`\n[turn error] ${JSON.stringify(action.part?.error ?? action.error ?? action).slice(0, 200)}\n`);
                 if (io.once) {
-                    finish('error');
+                    end('error');
                 }
                 break;
         }
-    });
-    conn.closed = detail => finish(detail);
+    };
+    // The session's `inputNeeded` lists the input waiting in every chat. A
+    // confirmation on the default chat is there too, and is asked through that
+    // chat above: a host without calliope-vscode#823 drops its entry while the
+    // call still waits (the provider's late ready moves it to running), so that
+    // removal is no answer. The session is how attach hears about the other
+    // chats, a subagent's.
+    const ask = (request) => {
+        const call = request?.toolCall;
+        if (request?.kind === 'toolConfirmation' && call?.status === 'pending-confirmation'
+            && typeof request.chat === 'string' && request.chat !== chat && typeof request.turnId === 'string') {
+            confirm(request.chat, request.turnId, call.toolCallId, call.confirmationTitle ?? call.invocationMessage, call.toolInput, request.id);
+        }
+    };
+    const applySession = (action) => {
+        switch (action.type) {
+            case 'session/inputNeededSet':
+                ask(action.request);
+                break;
+            case 'session/inputNeededRemoved':
+                for (const [toolCallId, { request }] of [...open]) {
+                    if (request === action.id) {
+                        settled(toolCallId);
+                    }
+                }
+                break;
+        }
+    };
+    // Apply a channel's actions from its snapshot on: those that arrive first are
+    // held, then applied after it, skipping any it already includes.
+    const track = (channel, onAction, seed, snapshot) => {
+        let held = snapshot ? [] : undefined;
+        conn.actions.push((action, from, serverSeq) => {
+            if (ended || from !== channel) {
+                return;
+            }
+            if (held) {
+                held.push({ action, serverSeq });
+                return;
+            }
+            onAction(action);
+        });
+        const join = (joined) => {
+            if (ended)
+                return;
+            seed(joined);
+            const early = held ?? [];
+            held = undefined;
+            const fromSeq = joined?.fromSeq;
+            for (const { action, serverSeq } of early) {
+                if (fromSeq === undefined || serverSeq === undefined || serverSeq > fromSeq) {
+                    onAction(action);
+                }
+            }
+        };
+        snapshot?.then(join, () => join(undefined));
+    };
+    track(chat, apply, snapshot => {
+        const turn = snapshot?.state?.activeTurn;
+        for (const part of turn?.responseParts ?? []) {
+            const call = part.kind === 'toolCall' ? part.toolCall : undefined;
+            if (turn && call?.status === 'pending-confirmation') {
+                confirm(chat, turn.id, call.toolCallId, call.confirmationTitle ?? call.invocationMessage, call.toolInput);
+            }
+        }
+    }, subscribed);
+    track(session, applySession, snapshot => {
+        for (const request of snapshot?.state?.inputNeeded ?? []) {
+            ask(request);
+        }
+    }, sessionSubscribed);
+    conn.closed = end;
     return { done };
 }
 function parseArgs(args) {
@@ -219,14 +447,18 @@ function parseArgs(args) {
     }
     return out;
 }
-function askYesNo(title, input) {
+function askYesNo(title, input, signal) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise(resolve => rl.question(`\n${title}\n  ${input}\nApprove? [y/N] `, answer => {
-        rl.close();
-        resolve(/^y(es)?$/i.test(answer.trim()));
-    }));
+    return new Promise(resolve => {
+        const end = (approved) => {
+            rl.close();
+            resolve(approved);
+        };
+        signal.addEventListener('abort', () => end(false), { once: true });
+        rl.question(`\n${title}\n  ${input}\nApprove? [y/N] `, answer => end(/^y(es)?$/i.test(answer.trim())));
+    });
 }
-export async function runAttach(args, env = process.env) {
+export async function runAttach(args, env = process.env, options = {}) {
     const opts = parseArgs(args);
     const err = (s) => process.stderr.write(`${s}\n`);
     const fallback = (f) => {
@@ -234,73 +466,106 @@ export async function runAttach(args, env = process.env) {
         err('Falling back: run `calliope` to work locally.');
         return FALLBACK_EXIT;
     };
-    if (isDisabled(env)) {
+    if (isDisabled(env))
         return fallback(fail('disabled', 'CALLIOPE_AHP is off'));
+    const timeoutMs = options.timeoutMs ?? ATTACH_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000) {
+        return fallback(fail('unreachable', 'invalid attach setup timeout'));
     }
-    const token = env[opts.tokenEnv];
-    const headers = token ? { Authorization: `token ${token}` } : {};
-    let url = opts.url;
-    if (!url && opts.hub && opts.user) {
-        if (!token) {
-            return fallback(fail('auth', `set ${opts.tokenEnv} to a hub API token`));
+    const controller = new AbortController();
+    const deadline = Date.now() + timeoutMs;
+    const remaining = () => Math.max(1, deadline - Date.now());
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let ws;
+    let conn;
+    try {
+        const token = env[opts.tokenEnv];
+        const headers = token ? { Authorization: `token ${token}` } : {};
+        let url = opts.url;
+        if (!url && opts.hub && opts.user) {
+            if (!token)
+                return fallback(fail('auth', `set ${opts.tokenEnv} to a hub API token`));
+            const resolved = await resolveHubHost({ hubUrl: opts.hub, user: opts.user, token, timeoutMs: remaining() });
+            if (!resolved.ok)
+                return fallback(resolved);
+            url = resolved.url;
         }
-        const resolved = await resolveHubHost({ hubUrl: opts.hub, user: opts.user, token });
-        if (!resolved.ok) {
-            return fallback(resolved);
+        if (!url) {
+            err('usage: calliope attach (--url <ws-url> | --hub <url> --user <name>) [session-uri] [--read-only]');
+            return 1;
         }
-        url = resolved.url;
-    }
-    if (!url) {
-        err('usage: calliope attach (--url <ws-url> | --hub <url> --user <name>) [session-uri] [--read-only]');
-        return 1;
-    }
-    const refused = await preflight(url, headers);
-    if (refused) {
-        return fallback(refused);
-    }
-    const ws = new WebSocket(url, { headers });
-    const opened = await new Promise(resolve => {
-        ws.addEventListener('open', () => resolve(true));
-        ws.addEventListener('error', () => resolve(false));
-    });
-    if (!opened) {
-        return fallback(fail('unreachable', 'the WebSocket upgrade failed'));
+        const refused = await preflight(url, headers, fetch, { signal: controller.signal, timeoutMs: remaining() });
+        if (refused)
+            return fallback(refused);
+        controller.signal.throwIfAborted();
+        ws = options.createSocket ? options.createSocket(url, headers) : new WebSocket(url, { headers });
+        const socket = ws;
+        const opened = await new Promise(resolve => {
+            const finish = (ok) => { controller.signal.removeEventListener('abort', aborted); resolve(ok); };
+            const aborted = () => { try {
+                socket.terminate ? socket.terminate() : socket.close();
+            }
+            catch { /* Already closed. */ } finish(false); };
+            socket.addEventListener('open', () => finish(true));
+            socket.addEventListener('error', () => finish(false));
+            socket.addEventListener('close', () => finish(false));
+            controller.signal.addEventListener('abort', aborted, { once: true });
+            if (controller.signal.aborted)
+                aborted();
+        });
+        if (!opened)
+            return fallback(fail('unreachable', controller.signal.aborted ? 'host setup timed out' : 'the WebSocket upgrade failed'));
+        conn = new AhpConnection(socket);
+        const call = (method, params) => conn.call(method, params, { signal: controller.signal, timeoutMs: remaining() });
+        const init = await call('initialize', {
+            channel: ROOT, protocolVersions: SUPPORTED_VERSIONS, clientId: `calliope-cli-${process.pid}`,
+            clientInfo: { name: 'calliope-cli', version: '1' }, initialSubscriptions: [ROOT],
+        });
+        const bad = checkInitialize(init);
+        if (bad)
+            return fallback(bad);
+        if (!opts.session) {
+            const list = await call('listSessions', { channel: ROOT });
+            if (list.error)
+                return fallback(fail('unreachable', 'the host could not list sessions'));
+            const items = (list.result?.items ?? []);
+            process.stdout.write(items.length ? '' : 'No sessions on this host.\n');
+            for (const session of items)
+                process.stdout.write(`${session.resource}  ${session.title ?? ''}  ${session.modifiedAt ?? ''}\n`);
+            return 0;
+        }
+        // Register follow before either subscription answers: frames may follow a
+        // snapshot in the same network read. Keep the setup deadline through both.
+        const chat = defaultChatUri(opts.session);
+        const sessionAnswer = call('subscribe', { channel: opts.session });
+        const chatAnswer = sessionAnswer.then(answer => answer.error ? answer : call('subscribe', { channel: chat }));
+        const { done } = follow(conn, opts.session, {
+            write: s => process.stdout.write(s), approve: opts.readOnly ? undefined : askYesNo, once: opts.once,
+        }, chatAnswer.then(answer => answer.result?.snapshot), sessionAnswer.then(answer => answer.result?.snapshot));
+        const answers = await Promise.all([sessionAnswer, chatAnswer]);
+        if (answers.some(answer => answer.error))
+            return fallback(fail('unreachable', 'the host could not subscribe to the session'));
+        clearTimeout(timer);
+        process.stderr.write(`attached to ${opts.session} (AHP ${init.result.protocolVersion}); Ctrl+C to detach\n`);
+        const ended = await done;
+        if (ended.startsWith('connection') || ended.startsWith('host') || ended.startsWith('invalid')) {
+            return fallback(fail('unreachable', 'the host connection was lost; the run remains on its host'));
+        }
+        return ended === 'turnComplete' ? 0 : 1;
     }
-    const conn = new AhpConnection(ws);
-    const init = await conn.call('initialize', {
-        channel: ROOT, protocolVersions: SUPPORTED_VERSIONS, clientId: `calliope-cli-${process.pid}`,
-        clientInfo: { name: 'calliope-cli', version: '1' }, initialSubscriptions: [ROOT],
-    });
-    const bad = checkInitialize(init);
-    if (bad) {
-        conn.close();
-        return fallback(bad);
+    catch {
+        return fallback(fail('unreachable', controller.signal.aborted ? 'host setup timed out' : 'host attachment failed'));
     }
-    if (!opts.session) {
-        const list = await conn.call('listSessions', { channel: ROOT });
-        if (list.error) {
-            err(`calliope attach: the host could not list sessions: ${list.error.message.split('\n')[0]}`);
-            conn.close();
-            return 1;
-        }
-        const items = (list.result?.items ?? []);
-        process.stdout.write(items.length ? '' : 'No sessions on this host.\n');
-        for (const s of items) {
-            process.stdout.write(`${s.resource}  ${s.title ?? ''}  ${s.modifiedAt ?? ''}\n`);
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+        conn?.close();
+        if (!conn && ws) {
+            try {
+                ws.terminate ? ws.terminate() : ws.close();
+            }
+            catch { /* Already closed. */ }
         }
-        conn.close();
-        return 0;
     }
-    await conn.call('subscribe', { channel: opts.session });
-    await conn.call('subscribe', { channel: defaultChatUri(opts.session) });
-    process.stderr.write(`attached to ${opts.session} (AHP ${init.result.protocolVersion}); Ctrl+C to detach\n`);
-    const { done } = follow(conn, opts.session, {
-        write: s => process.stdout.write(s),
-        approve: opts.readOnly ? undefined : askYesNo,
-        once: opts.once,
-    });
-    const ended = await done;
-    conn.close();
-    return ended === 'turnComplete' ? 0 : 1;
 }
 //# sourceMappingURL=attach.js.map