@aiwg/cockpit 2026.6.12 → 2026.6.13

package/bridge/src/server.mjs

@@ -371,7 +371,14 @@ async function destroyInstance(upstreamUrl, instanceId) {
     }
   } catch (err) {
     const message = String(err?.message ?? err);
-    if (inst && / -> 404(?:;|$)/.test(message)) {
+    // A docker/container row with a resolvable name is still physically
+    // removable even when admin-v2 has no instance record (404): fall through
+    // to the `docker rm -f` cleanup below so the stopped container is actually
+    // removed. Returning already_gone here would claim success while the
+    // container persists and re-appears on the next inventory poll — the
+    // "stale stopped Docker row can't be destroyed" failure.
+    const dockerCleanable = ['docker', 'container'].includes(runtime) && dockerName;
+    if (inst && !dockerCleanable && / -> 404(?:;|$)/.test(message)) {
       return {
         target: `${upstreamUrl}/api/v2/admin/instances/${encodeURIComponent(instanceId)}/destroy`,
         status: 200,
@@ -397,7 +404,18 @@ async function destroyInstance(upstreamUrl, instanceId) {
     };
   }
 
-  await spawnCollect('docker', ['rm', '-f', dockerName]);
+  let alreadyGone = false;
+  try {
+    await spawnCollect('docker', ['rm', '-f', dockerName]);
+  } catch (err) {
+    // `docker rm -f` errors only because the container is already gone (e.g.
+    // removed out-of-band). That is success for a destroy request, not a failure.
+    if (/No such container|is not running|not found/i.test(String(err?.message ?? err))) {
+      alreadyGone = true;
+    } else {
+      throw err;
+    }
+  }
   return {
     target: `docker rm -f ${dockerName}`,
     status: 200,
@@ -407,6 +425,8 @@ async function destroyInstance(upstreamUrl, instanceId) {
       runtime,
       state: 'destroyed',
       result: { state: 'destroyed' },
+      already_gone: alreadyGone,
+      message: alreadyGone ? `Container ${dockerName} was already removed; inventory refreshed.` : undefined,
       fallback: 'docker-cli-after-admin-v2-instance-not-found',
     },
   };
@@ -953,22 +973,34 @@ async function getSessions(executorUrl, instanceId) {
         return u.toString();
       } catch { /* fall through to legacy shape */ }
     }
-    return `${wsBase}/agents/${encodeURIComponent(sessionAgentId)}/sessions/${encodeURIComponent(sessionId)}/attach`;
-  };
-  return {
-    instance_id: instanceId,
-    sessions: sessions.map((s) => {
-      const sessionId = s.id ?? s.session_id ?? s.sessionId;
-      return {
-        ...s,
-        id: sessionId,
-        instance_id: s.instance_id ?? s.instanceId ?? instanceId,
-        agent_id: s.agent_id ?? s.agentId ?? sessionAgentId,
-        role_policy: s.role_policy ?? s.rolePolicy ?? (s.default_role === 'observer' ? 'observe-default' : s.default_role) ?? 'observe-default',
-        attach_url: normalizeAttachUrl(s, sessionId),
-      };
-    }),
+    // Fallback URL construction (session entry carried no attach_url/pty_ws_url).
+    // The executor's pty-ws route keys the agent segment by the INSTANCE id, not
+    // the registered agent name — resolveSessionAgentId returns the name for some
+    // agents (e.g. VMs after a Bridge restart), which the route won't accept and
+    // the data-plane socket never connects (#1671). Use the instance id here; the
+    // agent name is only needed for the session-list FETCH, not the attach path.
+    return `${wsBase}/agents/${encodeURIComponent(instanceId)}/sessions/${encodeURIComponent(sessionId)}/attach`;
   };
+  // Dedup by session id: the executor can register/return the same session more
+  // than once (e.g. a session registered twice in its registry), which surfaced
+  // as duplicate rows that are impossible to tell apart in the Sessions picker.
+  // Keep the first occurrence of each id (and drop id-less entries).
+  const seen = new Set();
+  const deduped = [];
+  for (const s of sessions) {
+    const sessionId = s.id ?? s.session_id ?? s.sessionId;
+    if (!sessionId || seen.has(sessionId)) continue;
+    seen.add(sessionId);
+    deduped.push({
+      ...s,
+      id: sessionId,
+      instance_id: s.instance_id ?? s.instanceId ?? instanceId,
+      agent_id: s.agent_id ?? s.agentId ?? sessionAgentId,
+      role_policy: s.role_policy ?? s.rolePolicy ?? (s.default_role === 'observer' ? 'observe-default' : s.default_role) ?? 'observe-default',
+      attach_url: normalizeAttachUrl(s, sessionId),
+    });
+  }
+  return { instance_id: instanceId, sessions: deduped };
 }
 
 async function endSession(executorUrl, instanceId, sessionId) {
@@ -1212,7 +1244,9 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
             attachUrl = u.toString();
           } catch { /* fall through to legacy shape */ }
         }
-        return json(res, status, { ...body, id: sessionId, attach_url: attachUrl ?? `${wsBase}/agents/${encodeURIComponent(sessionAgentId)}/sessions/${encodeURIComponent(sessionId)}/attach` });
+        // Same as the list path (#1671): the attach segment must be the instance
+        // id the executor's pty-ws route accepts, not the resolved agent name.
+        return json(res, status, { ...body, id: sessionId, attach_url: attachUrl ?? `${wsBase}/agents/${encodeURIComponent(id)}/sessions/${encodeURIComponent(sessionId)}/attach` });
       }
 
       // --- management surface (UC-012): lifecycle + task cancel ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cockpit",
-  "version": "2026.6.12",
+  "version": "2026.6.13",
   "description": "AIWG Cockpit — UX-first control plane over AIWG + multi-stack agentic sessions. Opt-in, separately published; NOT shipped in the base aiwg npm package (guarded by test/smoke/cockpit-base-footprint.test.js).",
   "type": "module",
   "license": "MIT",

package/web/src/App.test.tsx

@@ -219,6 +219,27 @@ describe('App shell (rendered DOM)', () => {
     expect(screen.queryByText(/action failed/i)).toBeNull();
   });
 
+  it('keeps Destroy enabled for a stopped Docker row so it can be cleaned up', async () => {
+    const stale = { ...instance('stale-dkr-1', 'docker', 'full-suite'), state: 'stopped' };
+    const inventory = { instances: [stale], count: 1, fetched_at: new Date().toISOString() };
+    globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/api/health')) return jsonResponse({ executor_url: 'http://127.0.0.1:8122' });
+      if (url.includes('/api/inventory')) return jsonResponse(inventory);
+      if (url.includes('/api/running')) return jsonResponse({ count: 0, running: [] });
+      if (url.includes('/api/approvals')) return jsonResponse({ approvals: [] });
+      if (url.includes('/api/cost')) return jsonResponse({ total: { input_tokens: 0, output_tokens: 0, usd: 0 }, per_instance: [] });
+      return jsonResponse({});
+    }) as typeof fetch;
+
+    render(<App />);
+    fireEvent.click(screen.getByRole('tab', { name: 'Inventory' }));
+    const destroy = await screen.findByRole('button', { name: /destroy instance stale-dkr-1/i });
+    // Previously hard-disabled for stopped Docker rows, which trapped stale
+    // containers in inventory with no in-UI way to remove them.
+    expect((destroy as HTMLButtonElement).disabled).toBe(false);
+  });
+
   it('each tab has a matching labelled tabpanel (controls/labelledby pairing)', () => {
     render(<App />);
     for (const tab of screen.getAllByRole('tab')) {

package/web/src/App.tsx

@@ -202,10 +202,21 @@ interface OperationStatus {
   error?: { message?: string; detail?: string; code?: string } | string;
 }
 
+// How long the picker waits for a newly-launched instance's agent to register
+// before handing the user back to Inventory. Heavy loadouts (e.g. full-suite —
+// all 9 providers × 6 frameworks) legitimately take well over a minute to
+// install and enroll their agent inside a fresh container/VM, so a short wait
+// produced false "no session-ready agent" failures for instances that were in
+// fact up and still installing. Overridable via window.AIWG_COCKPIT_SESSION_WAIT_S.
+const SESSION_READY_TIMEOUT_S = (() => {
+  const raw = Number((window as unknown as { AIWG_COCKPIT_SESSION_WAIT_S?: unknown }).AIWG_COCKPIT_SESSION_WAIT_S);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 150;
+})();
+
 async function waitForSessionReady(instanceId?: string, operationId?: string) {
   let last = '';
   let operationDetail = '';
-  for (let i = 0; i < 45; i += 1) {
+  for (let i = 0; i < SESSION_READY_TIMEOUT_S; i += 1) {
     if (operationId) {
       const op = await api<OperationStatus>(`/api/operations/${encodeURIComponent(operationId)}`);
       const state = String(op.state ?? '').toLowerCase();
@@ -234,7 +245,12 @@ async function waitForSessionReady(instanceId?: string, operationId?: string) {
     }
     await sleep(1_000);
   }
-  throw new Error(`Instance launched, but no session-ready agent appeared within 45s (${last}).`);
+  const where = instanceId ? `Instance ${instanceId}` : 'The instance';
+  throw new Error(
+    `${where} launched and is still installing its loadout — its agent had not registered after ${SESSION_READY_TIMEOUT_S}s `
+    + `(${last}). This is not a failure: heavy loadouts (e.g. full-suite) can take longer. `
+    + `It will appear under Inventory once its agent enrolls; open a session from there when it shows as running.`,
+  );
 }
 
 function operationFailure(op: OperationStatus) {

package/web/src/components/Inventory.tsx

@@ -116,8 +116,7 @@ export function Inventory({ onStartSession, onLaunchInstance }: { onStartSession
                   : <button aria-label={`Start instance ${fmtId(i.id)}`} onClick={() => control(`/api/instances/${encodeURIComponent(i.id)}/start`, 'POST')}>Start Instance</button>}{' '}
                 <button
                   aria-label={`Destroy instance ${fmtId(i.id)}`}
-                  disabled={i.state !== 'running' && i.runtime === 'docker'}
-                  title={i.state !== 'running' && i.runtime === 'docker' ? 'Sandbox reports this stopped Docker row but admin-v2 no longer has a destroyable instance record.' : undefined}
+                  title={i.state !== 'running' && i.runtime === 'docker' ? 'Stopped Docker row — Destroy removes the container directly (admin-v2 has no instance record).' : undefined}
                   onClick={() => { if (confirm(`Destroy ${fmtId(i.id)}? This cannot be undone.`)) control(`/api/instances/${encodeURIComponent(i.id)}`, 'DELETE'); }}
                 >
                   Destroy

package/web/src/components/LaunchInstanceModal.test.tsx

@@ -77,6 +77,21 @@ describe('LaunchInstanceModal', () => {
     });
   });
 
+  it('regenerates a fresh instance name on each open so back-to-back launches do not collide', async () => {
+    globalThis.fetch = mockFetch();
+    const { rerender } = render(<LaunchInstanceModal open onClose={() => {}} onLaunched={() => {}} />);
+    fireEvent.change(await screen.findByLabelText('Runtime'), { target: { value: 'docker' } });
+    const name1 = (await screen.findByLabelText('Name') as HTMLInputElement).value;
+    expect(name1).toMatch(/^cockpit-/);
+    // Close then reopen — the second launch (e.g. a VM after a Docker) must get a
+    // different name, or both register the same name-keyed agent and shadow each other.
+    rerender(<LaunchInstanceModal open={false} onClose={() => {}} onLaunched={() => {}} />);
+    rerender(<LaunchInstanceModal open onClose={() => {}} onLaunched={() => {}} />);
+    const name2 = (await screen.findByLabelText('Name') as HTMLInputElement).value;
+    expect(name2).toMatch(/^cockpit-/);
+    expect(name2).not.toBe(name1);
+  });
+
   it('passes a VM SSH public key path when launching QEMU', async () => {
     globalThis.fetch = mockFetch();
     const onLaunched = vi.fn();

package/web/src/components/LaunchInstanceModal.tsx

@@ -22,6 +22,15 @@ const FALLBACK_LOADOUTS: Loadout[] = [
   { id: 'full-suite', label: 'full-suite', description: 'Multi-provider tool suite', runtimes: ['qemu', 'vm'] },
 ];
 
+// A fresh, collision-resistant instance name per launch. The executor keys
+// agents by instance name, so two instances sharing a name (e.g. a Docker
+// container and a VM both named `cockpit-<ts>`) register the same agent id and
+// shadow each other — the second launch silently knocks the first offline.
+// Date.now() alone collides within a page session (the name was generated once
+// at mount and reused); add random entropy and regenerate on every open/launch.
+const genInstanceName = () =>
+  `cockpit-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`.slice(0, 32);
+
 export function LaunchInstanceModal({
   open,
   onClose,
@@ -32,7 +41,7 @@ export function LaunchInstanceModal({
   onLaunched: (instanceId?: string, openSession?: boolean, operationId?: string) => Promise<void> | void;
 }) {
   const [runtime, setRuntime] = useState<Runtime>('host');
-  const [name, setName] = useState(() => `cockpit-${Date.now().toString(36)}`.slice(0, 32));
+  const [name, setName] = useState(genInstanceName);
   const [loadout, setLoadout] = useState('host-tools');
   const [loadouts, setLoadouts] = useState<Loadout[]>([]);
   const [instances, setInstances] = useState<Instance[]>([]);
@@ -49,6 +58,9 @@ export function LaunchInstanceModal({
 
   useEffect(() => {
     if (!open) return;
+    // Fresh name every time the picker opens, so back-to-back launches (e.g.
+    // Docker then VM) never collide on the executor's name-keyed agent registry.
+    setName(genInstanceName());
     let cancelled = false;
     Promise.all([
       api<{ loadouts: Loadout[] }>('/api/loadouts').catch(() => ({ loadouts: [] as Loadout[] })),
@@ -116,6 +128,7 @@ export function LaunchInstanceModal({
         : `Launch accepted: ${instanceId ?? operationId ?? 'operation pending'}`);
       await onLaunched(instanceId, openSession, operationId);
       if (openSession) onClose();
+      else setName(genInstanceName()); // modal stays open — next launch gets a fresh, non-colliding name
     } catch (e) {
       setErr((e as Error).message);
     } finally {

package/web/src/components/Sessions.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { render, screen, waitFor, fireEvent, cleanup } from '@testing-library/react';
+import { render, screen, waitFor, fireEvent, cleanup, within } from '@testing-library/react';
 import { Sessions } from './Sessions';
 import type { SessionApi } from '../useSession';
 
@@ -110,10 +110,83 @@ describe('Sessions', () => {
 
     render(<Sessions session={session} composer="" setComposer={() => {}} onRequestStart={() => {}} refreshMs={10} />);
 
-    expect(await screen.findByRole('option', { name: /docker-one/i })).toBeTruthy();
-    expect(await screen.findByRole('option', { name: /docker-two/i })).toBeTruthy();
-    expect(screen.queryByRole('option', { name: /docker-one/i })).toBeNull();
-    expect(await screen.findByRole('option', { name: /sess-new/i })).toBeTruthy();
+    // The nav lists instances as buttons (not <select> options) now (#1670).
+    expect(await screen.findByText('docker-one')).toBeTruthy();
+    // Inventory refresh swaps inst-1 → inst-2; the dead instance drops out and
+    // selection follows to the live one, whose session is listed underneath.
+    expect(await screen.findByText('docker-two')).toBeTruthy();
+    await waitFor(() => expect(screen.queryByText('docker-one')).toBeNull());
+    // Scope to the nav (the active-session indicator also carries the id by title).
+    const nav = screen.getByLabelText('Instances and sessions');
+    expect(await within(nav).findByTitle('sess-new')).toBeTruthy();
+  });
+
+  it('auto-attaches in observe when a different session is selected (#1670)', async () => {
+    const session = stubSession(); // currently attached to .../sessions/sess-1/attach as controller
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/api/inventory')) return jsonResponse({ instances: [INSTANCE] });
+      if (url.includes('/api/sessions?instance=')) return jsonResponse({
+        sessions: [{ id: 'sess-2', session_name: 'terminal-other', instance_id: 'inst-1', attach_url: 'ws://x/agents/inst-1/sessions/sess-2/attach', mode: 'managed', backend: 'tmux' }],
+      });
+      return new Response('{}', { status: 404 });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+    render(<Sessions session={session} composer="" setComposer={() => {}} onRequestStart={() => {}} />);
+
+    const nav = screen.getByLabelText('Instances and sessions');
+    const sessBtn = await within(nav).findByTitle('sess-2');
+    fireEvent.click(sessBtn);
+    // Selecting a not-yet-attached session attaches it read-only; the operator clicks Drive to take over.
+    expect(session.attach).toHaveBeenCalledWith('ws://x/agents/inst-1/sessions/sess-2/attach', false, 'observer');
+  });
+
+  it('does not re-attach (downgrade) when re-selecting the session already attached', async () => {
+    const session = stubSession(); // state.url === .../sessions/sess-1/attach, role controller
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/api/inventory')) return jsonResponse({ instances: [INSTANCE] });
+      if (url.includes('/api/sessions?instance=')) return jsonResponse({
+        sessions: [{ id: 'sess-1', session_name: 'terminal-main', instance_id: 'inst-1', attach_url: 'ws://x/agents/inst-1/sessions/sess-1/attach', mode: 'managed', backend: 'tmux' }],
+      });
+      return new Response('{}', { status: 404 });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+    render(<Sessions session={session} composer="" setComposer={() => {}} onRequestStart={() => {}} />);
+
+    const nav = screen.getByLabelText('Instances and sessions');
+    fireEvent.click(await within(nav).findByTitle('sess-1'));
+    // Clicking the session we already drive must not downgrade us back to observer.
+    expect(session.attach).not.toHaveBeenCalled();
+  });
+
+  it('distinguishes sessions by name + backend + viewer count in the nav (#1670)', async () => {
+    const session = stubSession();
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/api/inventory')) return jsonResponse({ instances: [INSTANCE] });
+      if (url.includes('/api/sessions?instance=')) return jsonResponse({
+        sessions: [
+          { id: 'sess-a', session_name: 'terminal-alpha', instance_id: 'inst-1', attach_url: 'ws://x/agents/inst-1/sessions/sess-a/attach', mode: 'managed', backend: 'tmux', controllers: 1, observers: 1 },
+          { id: 'sess-b', session_name: 'terminal-beta', instance_id: 'inst-1', attach_url: 'ws://x/agents/inst-1/sessions/sess-b/attach', mode: 'direct', backend: 'native', members: 0 },
+        ],
+      });
+      return new Response('{}', { status: 404 });
+    });
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    render(<Sessions session={session} composer="" setComposer={() => {}} onRequestStart={() => {}} />);
+
+    // Two distinct sessions, each shown by name with its own backend/viewer meta.
+    // Scope to the nav — the controls bar's active-session indicator echoes the label.
+    await screen.findByText('terminal-beta');
+    const nav = screen.getByLabelText('Instances and sessions');
+    expect(within(nav).getByText('terminal-alpha')).toBeTruthy();
+    expect(within(nav).getByText('terminal-beta')).toBeTruthy();
+    expect(within(nav).getByText('managed/tmux · 2 viewers')).toBeTruthy();
+    expect(within(nav).getByText('direct/native · 0 viewers')).toBeTruthy();
+    // sess-a has a controller connected → it carries the ctrl badge; sess-b does not.
+    expect(within(nav).getByTitle('A controller is connected')).toBeTruthy();
   });
 });
 

package/web/src/components/Sessions.tsx

@@ -60,7 +60,15 @@ export function Sessions({ session, composer, setComposer, onRequestStart, refre
       })
       .catch((e) => { setSessions([]); setAttachUrl(''); setSessionErr((e as Error).message); });
   }, []);
-  useEffect(() => { loadSessions(instId); }, [instId, loadSessions]);
+  // Reload the selected instance's sessions on selection change AND on an interval,
+  // so a session created elsewhere (the Start modal, the Running board, another
+  // operator) shows up in the nav without re-selecting the instance.
+  useEffect(() => {
+    if (!instId) return;
+    loadSessions(instId);
+    const timer = window.setInterval(() => loadSessions(instId), refreshMs);
+    return () => window.clearInterval(timer);
+  }, [instId, loadSessions, refreshMs]);
 
   const send = () => { if (session.sendInput(composer)) setComposer(''); };
   const attached = session.state.attached;
@@ -85,15 +93,16 @@ export function Sessions({ session, composer, setComposer, onRequestStart, refre
   // Starting now routes through the shared picker (#1640/#1641) so this tab and the
   // dashboard verb share one params/clobber/error path. The selects below remain for
   // attaching to / observing / driving sessions that already exist.
-  const endSelectedSession = async () => {
-    if (!current || !selectedSession) return;
-    const label = selectedSession.session_name ?? selectedSession.id;
+  const endSelectedSession = async (target?: SessionInfo) => {
+    const s = target ?? selectedSession;
+    if (!current || !s) return;
+    const label = s.session_name ?? s.id;
     if (!confirm(`End session ${label}? This closes the PTY and detaches connected views.`)) return;
-    setEndingSession(selectedSession.id);
+    setEndingSession(s.id);
     setSessionErr('');
     try {
-      await api(`/api/instances/${encodeURIComponent(current.id)}/sessions/${encodeURIComponent(selectedSession.id)}`, { method: 'DELETE' });
-      if (session.state.url === selectedSession.attach_url) session.detach();
+      await api(`/api/instances/${encodeURIComponent(current.id)}/sessions/${encodeURIComponent(s.id)}`, { method: 'DELETE' });
+      if (session.state.url === s.attach_url) session.detach();
       await loadSessions(current.id);
     } catch (e) {
       setSessionErr((e as Error).message);
@@ -105,80 +114,142 @@ export function Sessions({ session, composer, setComposer, onRequestStart, refre
   return (
     <>
       <p className="hint">
-        <strong>Workspace.</strong> Attach to a single session on one instance to observe or drive it. Start a
-        new session above, or pick a live task from the <strong>Running</strong> fleet board and open it here.
+        <strong>Workspace.</strong> Pick an instance on the left, then a session under it to observe or drive.
+        Start a new session per instance, or open a live task from the <strong>Running</strong> fleet board.
       </p>
-      <div className="controls">
-        <label htmlFor="sel-instance">Instance</label>
-        <select id="sel-instance" value={instId} onChange={(e) => setInstId(e.target.value)}>
-          {instances.map((i) => <option key={i.id} value={i.id}>{i.launch_context?.name ?? fmtId(i.id)} · {i.loadout}</option>)}
-          {!instances.length && <option value="">— no session-capable running instances —</option>}
-        </select>
-        <label htmlFor="sel-backend">Mode</label>
-        <select id="sel-backend" value={backendKey} onChange={(e) => setBackendKey(e.target.value)}>
-          {backends.length
-            ? backends.map((b) => <option key={`${b.mode}:${b.backend}`} value={`${b.mode}:${b.backend}`} disabled={!b.available}>{b.mode} · {b.backend}{b.available ? '' : ` — ${b.reason ?? 'unsupported'}`}</option>)
-            : <option value="">— not advertised —</option>}
-        </select>
-        <button onClick={() => onRequestStart(instId)}>Start…</button>
-        <label htmlFor="sel-session">Session</label>
-        <select id="sel-session" value={attachUrl} onChange={(e) => setAttachUrl(e.target.value)}>
-          {sessions.length
-            ? sessions.map((s) => <option key={s.id} value={s.attach_url}>{s.id} · {s.mode ?? s.session_class ?? 'managed'}/{s.backend ?? s.session_backend ?? 'tmux'} · {current?.launch_context?.name ?? fmtId(instId)}</option>)
-            : <option value="">— no sessions —</option>}
-        </select>
-        <button disabled={!attachUrl || (attached && session.state.role === 'observer')} onClick={() => session.attach(attachUrl, false, 'observer')}>Observe</button>
-        <button disabled={!attachUrl || selectedBackend?.drive === false || (attached && session.state.role === 'controller')} onClick={() => session.attach(attachUrl, false, 'controller')}>
-          {attached && session.state.role === 'observer' ? 'Take Control' : 'Drive'}
-        </button>
-        <button disabled={!attached || selectedBackend?.keyframe === false} onClick={session.requestKeyframe}>Keyframe</button>
-        <button disabled={!attached} onClick={() => session.replay(attachUrl, requestedReplayRole)}>Reattach + replay</button>
-        <button
-          disabled={!selectedSession || endingSession === selectedSession?.id}
-          onClick={endSelectedSession}
-          title="Terminate the selected PTY session on the agent"
-        >
-          {endingSession === selectedSession?.id ? 'Ending…' : 'End Session'}
-        </button>
-        <button disabled={!attached} onClick={session.detach}>Detach</button>
-        {session.state.role && <span className={`badge ${session.state.role}`}>{session.state.role}</span>}
-      </div>
-      {sessionErr && <p className="err">Session action failed: {sessionErr}</p>}
-      {current && (
-        <p className="hint">
-          {current.runtime_posture.label} · {current.transport.label} ({current.transport.mode}) · attach starts as observe unless control is explicitly granted.
-          {attached && session.state.role === 'observer' ? ' Click Take Control to re-attach with write access.' : ''}
-          {selectedBackend && !selectedBackend.available ? ` ${selectedBackend.reason ?? 'Selected backend is unavailable.'}` : ''}
-        </p>
-      )}
-      <div className="terminal" ref={session.openTerminal} role="log" aria-label="Session output" />
-      {showPicker && (
-        <div className="picker">
-          <p className="hint" style={{ marginTop: 0 }}>Pick a capability to insert into the command — then Send to inject it. (Lookup is UI; the agent runs it.)</p>
-          <CapabilitySearch compact autoFocus onPick={insertCap} />
-        </div>
-      )}
-      <div className="inputrow">
-        <button aria-label="Insert a capability" title="Insert a capability (search)" onClick={() => setShowPicker((v) => !v)}>＋</button>
-        <input
-          ref={inputRef}
-          value={composer}
-          onChange={(e) => setComposer(e.target.value)}
-          onKeyDown={(e) => { if (e.key === 'Enter') send(); }}
-          placeholder={session.isController ? 'Type to drive the session…' : 'Observing — input is read-only'}
-          disabled={!session.isController}
-          aria-label="Session input"
-        />
-        <button disabled={!session.isController} onClick={send}>Send</button>
+      <div className="session-workspace">
+        {/* Persistent instances → sessions navigation (agentic-sandbox-style control screen, #1670). */}
+        <aside className="session-nav" aria-label="Instances and sessions">
+          <div className="session-nav-head">
+            <h2>Instances</h2>
+            <span className="hint">{instances.length}</span>
+          </div>
+          {!instances.length && <p className="empty">No session-capable running instances.</p>}
+          <ul className="nav-list">
+            {instances.map((i) => {
+              const isSel = i.id === instId;
+              const name = i.launch_context?.name ?? fmtId(i.id);
+              return (
+                <li key={i.id} className={`nav-instance${isSel ? ' selected' : ''}`}>
+                  <button className="nav-instance-row" aria-expanded={isSel} onClick={() => setInstId(i.id)} title={i.id}>
+                    <span className={`badge isolation-${i.runtime_posture.isolation}`}>{i.runtime}</span>
+                    <span className="nav-instance-name">{name}</span>
+                    <span className={`state ${i.state}`}><span className="dot" aria-hidden="true" />{i.state}</span>
+                  </button>
+                  {isSel && (
+                    <div className="nav-sessions">
+                      {sessions.length === 0 && <p className="empty nav-empty">No sessions yet.</p>}
+                      <ul>
+                        {sessions.map((s) => {
+                          const selS = s.attach_url === attachUrl;
+                          const live = session.state.url === s.attach_url && attached;
+                          return (
+                            <li key={s.id}>
+                              <button
+                                className={`nav-session${selS ? ' selected' : ''}${live ? ' live' : ''}`}
+                                // Selecting a session auto-attaches in observe (read-only) so the
+                                // operator immediately sees it; they click Drive to take control.
+                                // Re-selecting the session already attached here is a no-op (don't
+                                // downgrade an active controller back to observer).
+                                onClick={() => {
+                                  setAttachUrl(s.attach_url);
+                                  if (s.attach_url !== session.state.url) session.attach(s.attach_url, false, 'observer');
+                                }}
+                                title={s.id}
+                              >
+                                <span className="nav-session-name">{sessionLabel(s)}</span>
+                                <span className="nav-session-meta">{sessionMeta(s)}</span>
+                                {sessionHoldsController(s) && <span className="badge controller" title="A controller is connected">ctrl</span>}
+                                {live && <span className="badge live-dot" title="Attached here">●</span>}
+                              </button>
+                              <button
+                                className="nav-session-end"
+                                aria-label={`End session ${sessionLabel(s)}`}
+                                title="End this PTY session"
+                                disabled={endingSession === s.id}
+                                onClick={() => endSelectedSession(s)}
+                              >
+                                {endingSession === s.id ? '…' : '×'}
+                              </button>
+                            </li>
+                          );
+                        })}
+                      </ul>
+                      <button className="cta-sm nav-new-session" disabled={backends.length > 0 && !selectedBackend?.available} onClick={() => onRequestStart(i.id)}>＋ New session</button>
+                    </div>
+                  )}
+                </li>
+              );
+            })}
+          </ul>
+        </aside>
+
+        <section className="session-main">
+          <div className="controls">
+            {backends.length > 1 && (
+              <>
+                <label htmlFor="sel-backend">Mode</label>
+                <select id="sel-backend" value={backendKey} onChange={(e) => setBackendKey(e.target.value)}>
+                  {backends.map((b) => <option key={`${b.mode}:${b.backend}`} value={`${b.mode}:${b.backend}`} disabled={!b.available}>{b.mode} · {b.backend}{b.available ? '' : ` — ${b.reason ?? 'unsupported'}`}</option>)}
+                </select>
+              </>
+            )}
+            <span className="controls-active" title={selectedSession?.id}>{selectedSession ? sessionLabel(selectedSession) : '— no session selected —'}</span>
+            <button disabled={!attachUrl || (attached && session.state.role === 'observer')} onClick={() => session.attach(attachUrl, false, 'observer')}>Observe</button>
+            <button disabled={!attachUrl || selectedBackend?.drive === false || (attached && session.state.role === 'controller')} onClick={() => session.attach(attachUrl, false, 'controller')}>
+              {attached && session.state.role === 'observer' ? 'Take Control' : 'Drive'}
+            </button>
+            <button disabled={!attached || selectedBackend?.keyframe === false} onClick={session.requestKeyframe}>Keyframe</button>
+            <button disabled={!attached} onClick={() => session.replay(attachUrl, requestedReplayRole)}>Reattach + replay</button>
+            <button disabled={!attached} onClick={session.detach}>Detach</button>
+            {session.state.role && <span className={`badge ${session.state.role}`}>{session.state.role}</span>}
+          </div>
+          {sessionErr && <p className="err">Session action failed: {sessionErr}</p>}
+          {current && (
+            <p className="hint">
+              {current.runtime_posture.label} · {current.transport.label} ({current.transport.mode}) · attach starts as observe unless control is explicitly granted.
+              {attached && session.state.role === 'observer' ? ' Click Take Control to re-attach with write access.' : ''}
+              {selectedBackend && !selectedBackend.available ? ` ${selectedBackend.reason ?? 'Selected backend is unavailable.'}` : ''}
+            </p>
+          )}
+          <div className="terminal" ref={session.openTerminal} role="log" aria-label="Session output" />
+          {showPicker && (
+            <div className="picker">
+              <p className="hint" style={{ marginTop: 0 }}>Pick a capability to insert into the command — then Send to inject it. (Lookup is UI; the agent runs it.)</p>
+              <CapabilitySearch compact autoFocus onPick={insertCap} />
+            </div>
+          )}
+          <div className="inputrow">
+            <button aria-label="Insert a capability" title="Insert a capability (search)" onClick={() => setShowPicker((v) => !v)}>＋</button>
+            <input
+              ref={inputRef}
+              value={composer}
+              onChange={(e) => setComposer(e.target.value)}
+              onKeyDown={(e) => { if (e.key === 'Enter') send(); }}
+              placeholder={session.isController ? 'Type to drive the session…' : 'Observing — input is read-only'}
+              disabled={!session.isController}
+              aria-label="Session input"
+            />
+            <button disabled={!session.isController} onClick={send}>Send</button>
+          </div>
+        </section>
       </div>
-      <p className="hint">
-        Pick or start a session, then Attach. Cockpit requests observe-first access; drive/control is explicit and denial reasons stay visible through the session stream.
-        Actions inject their command right here.
-      </p>
     </>
   );
 }
 
+function sessionLabel(s: SessionInfo): string {
+  return s.session_name ?? s.sessionName ?? fmtId(s.id);
+}
+function sessionMeta(s: SessionInfo): string {
+  const backend = `${s.mode ?? s.session_class ?? 'managed'}/${s.backend ?? s.session_backend ?? 'tmux'}`;
+  const viewers = s.members ?? ((s.controllers ?? 0) + (s.observers ?? 0));
+  return `${backend} · ${viewers} viewer${viewers === 1 ? '' : 's'}`;
+}
+function sessionHoldsController(s: SessionInfo): boolean {
+  return s.has_controller === true || (s.controllers ?? 0) > 0;
+}
+
 function dedupeInstances(instances: Instance[]) {
   const seen = new Set<string>();
   return instances.filter((instance) => {

package/web/src/styles.css

@@ -252,3 +252,38 @@ code { font:13px ui-monospace, monospace; color:var(--muted); }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { scroll-behavior:auto !important; transition:none !important; animation:none !important; }
 }
+
+/* Session workspace — persistent instances→sessions nav (agentic-sandbox-style control screen, #1670) */
+.session-workspace { display:grid; grid-template-columns:minmax(240px, 300px) minmax(0, 1fr); gap:16px; align-items:start; }
+@media (max-width: 820px) { .session-workspace { grid-template-columns:1fr; } }
+.session-nav { border:1px solid var(--line); border-radius:10px; background:var(--panel); padding:10px; max-height:calc(100vh - 250px); overflow-y:auto; }
+.session-nav-head { display:flex; align-items:center; justify-content:space-between; margin:2px 4px 8px; }
+.session-nav-head h2 { margin:0; font-size:15px; }
+.session-nav-head .hint { margin:0; }
+.nav-list { list-style:none; margin:0; padding:0; display:flex; flex-direction:column; gap:4px; }
+.nav-instance { border-radius:8px; border:1px solid transparent; }
+.nav-instance.selected { background:rgba(94,234,212,.06); border-color:var(--line); }
+.nav-instance-row { width:100%; display:flex; align-items:center; gap:8px; background:none; border:0; padding:8px; cursor:pointer; text-align:left; border-radius:8px; }
+.nav-instance-row:hover { border-color:transparent; background:rgba(148,163,184,.08); }
+.nav-instance-name { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; font-weight:600; font-size:13px; }
+.nav-instance .state { font-size:11px; color:var(--muted); }
+.nav-instance .badge { font-size:10px; padding:1px 7px; text-transform:lowercase; }
+.nav-sessions { padding:0 6px 8px 10px; display:flex; flex-direction:column; gap:4px; }
+.nav-sessions ul { list-style:none; margin:0; padding:0; display:flex; flex-direction:column; gap:3px; }
+.nav-sessions li { display:flex; align-items:stretch; gap:4px; }
+.nav-session { flex:1; min-width:0; display:flex; flex-wrap:wrap; align-items:center; gap:4px 6px; background:none; border:1px solid transparent; border-left:2px solid var(--line); border-radius:6px; padding:6px 8px; cursor:pointer; text-align:left; }
+.nav-session:hover { background:rgba(148,163,184,.08); }
+.nav-session.selected { border-color:var(--accent); border-left-color:var(--accent); background:rgba(94,234,212,.08); }
+.nav-session.live { border-left-color:var(--ok); }
+.nav-session-name { flex-basis:100%; font-size:12px; font-weight:600; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.nav-session-meta { font-size:11px; color:var(--muted); }
+.nav-session .badge { padding:0 6px; font-size:10px; }
+.nav-session .live-dot { border-color:var(--ok); color:var(--ok); }
+.nav-session-end { align-self:center; padding:4px 9px; color:var(--muted); border-color:transparent; background:none; line-height:1; }
+.nav-session-end:hover:not(:disabled) { border-color:var(--err); color:var(--err); }
+.nav-new-session { margin-top:6px; align-self:flex-start; }
+.cta-sm { font-size:12px; padding:5px 10px; border-color:var(--accent); color:var(--accent); }
+.nav-empty { margin:4px 0; font-size:12px; }
+.session-main { min-width:0; }
+.controls-active { color:var(--muted); font-size:13px; padding:5px 10px; border:1px dashed var(--line); border-radius:7px; max-width:240px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.badge.live-dot { color:var(--ok); border-color:var(--ok); }

package/web/src/useSession.test.tsx

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useSession } from './useSession';
+
+// Minimal WebSocket double: records every constructed socket and lets the test
+// drive open/close/message. Mirrors the readiness-race timing (#1669).
+class MockWS {
+  static instances: MockWS[] = [];
+  url: string;
+  sent: string[] = [];
+  private listeners: Record<string, ((e: unknown) => void)[]> = {};
+  constructor(url: string) { this.url = url; MockWS.instances.push(this); }
+  addEventListener(type: string, fn: (e: unknown) => void) { (this.listeners[type] ||= []).push(fn); }
+  send(data: string) { this.sent.push(data); }
+  close() { /* no-op; the test drives 'close' explicitly */ }
+  emit(type: string, e: unknown = {}) { (this.listeners[type] || []).forEach((fn) => fn(e)); }
+}
+
+beforeEach(() => {
+  MockWS.instances = [];
+  (globalThis as unknown as { WebSocket: unknown }).WebSocket = MockWS as unknown;
+  vi.useFakeTimers();
+});
+afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); });
+
+describe('useSession — retry through the PTY-readiness window (#1669)', () => {
+  it('reconnects on an early empty close instead of giving up', () => {
+    const { result } = renderHook(() => useSession());
+    act(() => { result.current.attach('ws://x/attach', false, 'controller'); });
+    expect(MockWS.instances).toHaveLength(1);
+
+    // First socket opens, then closes with zero frames (agent PTY not ready yet).
+    act(() => { MockWS.instances[0].emit('open'); MockWS.instances[0].emit('close'); });
+    // No reconnect yet (waits the backoff)...
+    expect(MockWS.instances).toHaveLength(1);
+    // ...then a fresh socket is opened to retry.
+    act(() => { vi.advanceTimersByTime(1300); });
+    expect(MockWS.instances).toHaveLength(2);
+  });
+
+  it('counts a failing socket once even though it fires both error and close', () => {
+    const { result } = renderHook(() => useSession());
+    act(() => { result.current.attach('ws://x/attach', false, 'controller'); });
+    // A real failing WebSocket dispatches BOTH 'error' and 'close'; that must
+    // burn only one retry slot, not two (otherwise the budget halves silently).
+    act(() => { MockWS.instances[0].emit('open'); MockWS.instances[0].emit('error'); MockWS.instances[0].emit('close'); });
+    act(() => { vi.advanceTimersByTime(1300); });
+    expect(MockWS.instances).toHaveLength(2);
+  });
+
+  it('stops retrying once the first frame arrives (real stream established)', () => {
+    const { result } = renderHook(() => useSession());
+    act(() => { result.current.attach('ws://x/attach', false, 'controller'); });
+
+    // Reach the second attempt, then this socket actually streams a frame.
+    act(() => { MockWS.instances[0].emit('open'); MockWS.instances[0].emit('close'); });
+    act(() => { vi.advanceTimersByTime(1300); });
+    const live = MockWS.instances[1];
+    act(() => {
+      live.emit('open');
+      live.emit('message', { data: JSON.stringify({ op: 'binding_hello' }) });
+      live.emit('message', { data: JSON.stringify({ op: 'output', seq: 1, payload: { data: btoa('hi') } }) });
+    });
+    // A later close after streaming must NOT spawn another socket.
+    act(() => { live.emit('close'); vi.advanceTimersByTime(5000); });
+    expect(MockWS.instances).toHaveLength(2);
+  });
+
+  it('gives up after the retry budget and does not reconnect forever', () => {
+    const { result } = renderHook(() => useSession());
+    act(() => { result.current.attach('ws://x/attach', false, 'controller'); });
+    // Every attempt closes empty; after the budget it stops creating sockets.
+    for (let i = 0; i < 10; i += 1) {
+      act(() => { MockWS.instances[MockWS.instances.length - 1].emit('open'); MockWS.instances[MockWS.instances.length - 1].emit('close'); });
+      act(() => { vi.advanceTimersByTime(1300); });
+    }
+    // 1 initial + 6 retries = 7 sockets, then it stops.
+    expect(MockWS.instances.length).toBeLessThanOrEqual(7);
+  });
+});

package/web/src/useSession.ts

@@ -22,6 +22,12 @@ export interface ResponseNeededState { needed: boolean; prompt: string; since: s
 const RESIZE_FLOOR_COLS = 20;
 const RESIZE_FLOOR_ROWS = 5;
 
+// Retry-through-readiness window (#1669). A freshly-launched instance can accept
+// the attach but stream 0 frames and close within ~2s while its PTY/tmux comes
+// up; ~7s of reconnects rides past that without a hard error.
+const MAX_READY_RETRIES = 6;
+const READY_RETRY_MS = 1200;
+
 const textEnc = new TextEncoder();
 const textDec = new TextDecoder();
 
@@ -76,6 +82,14 @@ export function useSession() {
   const roRef = useRef<ResizeObserver | null>(null);
   const roleRef = useRef<Role>(null); // current role, read by term.onData without re-subscribing
   const outputTailRef = useRef('');
+  // Retry-through-readiness state (#1669): a freshly-launched VM/container can
+  // accept the pty-ws attach, send 0 frames, and close within ~2s because the
+  // agent's PTY/tmux isn't streamable yet. Rather than show a hard
+  // [connection error], reconnect a few times until the first frame arrives.
+  const gotFrameRef = useRef(false);   // any output/keyframe seen on the current attach
+  const retryRef = useRef(0);          // reconnect attempts since the last user-initiated attach
+  const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const closedByUserRef = useRef(false); // detach()/new attach — suppress reconnect
   const [state, setState] = useState<SessionState>({ attached: false, role: null, url: null });
   const [responseNeeded, setResponseNeeded] = useState<ResponseNeededState>({ needed: false, prompt: '', since: null, source: 'pty' });
 
@@ -111,6 +125,9 @@ export function useSession() {
         convertEol: false, // the PTY/tmux emits its own CR/LF
         scrollback: 2000,
         cursorBlink: false,
+        // Read-only until control is granted: observe must not capture keystrokes
+        // at all (not just drop them on send). Flipped to false on controller.
+        disableStdin: true,
         fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
         fontSize: 13,
         theme: { background: '#0a0c10', foreground: '#cdd3de' },
@@ -153,53 +170,101 @@ export function useSession() {
   useEffect(() => () => {
     try { roRef.current?.disconnect(); } catch { /* */ }
     try { termRef.current?.dispose(); } catch { /* */ }
+    closedByUserRef.current = true;
+    if (retryTimerRef.current) { clearTimeout(retryTimerRef.current); retryTimerRef.current = null; }
     wsRef.current?.close();
   }, []);
 
   const attach = useCallback((url: string, replay = false, requestedRole: Exclude<Role, null> = 'observer') => {
+    if (retryTimerRef.current) { clearTimeout(retryTimerRef.current); retryTimerRef.current = null; }
+    closedByUserRef.current = false;
+    retryRef.current = 0;
+    gotFrameRef.current = false;
     wsRef.current?.close();
     if (!replay) lastSeq.current = 0;
     roleRef.current = null;
+    if (termRef.current) termRef.current.options.disableStdin = true; // read-only until role_assigned grants control
     clearResponseNeeded();
     outputTailRef.current = '';
     setState({ attached: false, role: null, url });
     if (!replay) { try { termRef.current?.reset(); } catch { /* */ } }
-    const ws = new WebSocket(replay ? `${url}?replay_from=${lastSeq.current}` : url);
-    wsRef.current = ws;
-    ws.addEventListener('open', () => setState((s) => ({ ...s, attached: true, url })));
-    ws.addEventListener('close', () => { roleRef.current = null; setState((s) => ({ ...s, attached: false, role: null })); });
-    ws.addEventListener('error', () => write(textEnc.encode('\r\n[connection error]\r\n')));
-    ws.addEventListener('message', (ev) => {
-      let m: WsMsg;
-      try { m = JSON.parse(ev.data as string); } catch { return; }
-      switch (m.op) {
-        case 'binding_hello': {
-          sendOp('pty.join_session', { role: requestedRole });
-          // Tell the PTY our current dimensions up front so the first tmux redraw fits.
-          const t = termRef.current;
-          if (t && t.cols >= RESIZE_FLOOR_COLS && t.rows >= RESIZE_FLOOR_ROWS) sendOp('pty.session_resize', { cols: t.cols, rows: t.rows });
-          break;
+
+    // Open (or re-open, on a readiness retry) the data-plane socket.
+    const connect = () => {
+      const ws = new WebSocket(replay ? `${url}?replay_from=${lastSeq.current}` : url);
+      wsRef.current = ws;
+      let gone = false; // a failing socket fires BOTH 'error' and 'close' — handle once
+      ws.addEventListener('open', () => setState((s) => ({ ...s, attached: true, url })));
+      const onGone = (kind: 'close' | 'error') => {
+        if (gone) return;
+        gone = true;
+        roleRef.current = null;
+        setState((s) => ({ ...s, attached: false, role: null }));
+        // Clean detach, or we were already streaming → leave it (a real end/drop).
+        if (closedByUserRef.current || gotFrameRef.current) return;
+        // Early empty close/error before the first frame → the agent's PTY isn't
+        // streamable yet. Reconnect through the readiness window rather than error.
+        if (retryRef.current < MAX_READY_RETRIES) {
+          retryRef.current += 1;
+          if (retryRef.current === 1) write(textEnc.encode('\r\n[waiting for session…]\r\n'));
+          retryTimerRef.current = setTimeout(connect, READY_RETRY_MS);
+          return;
         }
-        case 'role_assigned':
-          roleRef.current = m.payload?.role ?? null;
-          setState((s) => ({ ...s, role: m.payload?.role ?? null }));
-          requestAnimationFrame(() => fit());
-          break;
-        case 'output':
-          if (m.seq) lastSeq.current = Math.max(lastSeq.current, m.seq);
-          write(b64ToBytes(m.payload?.data ?? ''));
-          break;
-        case 'keyframe':
-          for (const f of m.payload?.frames ?? []) { if (f.seq) lastSeq.current = Math.max(lastSeq.current, f.seq); write(b64ToBytes(f.payload.data)); }
-          break;
-        case 'error':
-          write(textEnc.encode(`\r\n[${m.payload?.code ?? 'error'}]\r\n`));
-          break;
-      }
-    });
+        void kind;
+        write(textEnc.encode('\r\n[connection error — session did not become ready]\r\n'));
+      };
+      ws.addEventListener('close', () => onGone('close'));
+      ws.addEventListener('error', () => onGone('error'));
+      ws.addEventListener('message', (ev) => {
+        let m: WsMsg;
+        try { m = JSON.parse(ev.data as string); } catch { return; }
+        switch (m.op) {
+          case 'binding_hello': {
+            sendOp('pty.join_session', { role: requestedRole });
+            // Tell the PTY our current dimensions up front so the first tmux redraw fits.
+            const t = termRef.current;
+            if (t && t.cols >= RESIZE_FLOOR_COLS && t.rows >= RESIZE_FLOOR_ROWS) sendOp('pty.session_resize', { cols: t.cols, rows: t.rows });
+            break;
+          }
+          case 'role_assigned': {
+            const role = m.payload?.role ?? null;
+            roleRef.current = role;
+            setState((s) => ({ ...s, role }));
+            // Only a controller may type into the terminal; observers are read-only.
+            if (termRef.current) termRef.current.options.disableStdin = role !== 'controller';
+            // Re-attaching to an established session whose shell is idle gets no
+            // live output and the join replay carries no keyframe — request one so
+            // the current screen paints immediately instead of staying blank.
+            if (!gotFrameRef.current) sendOp('pty.request_keyframe');
+            requestAnimationFrame(() => fit());
+            break;
+          }
+          case 'output':
+            gotFrameRef.current = true; retryRef.current = 0; // first frame → readiness reached
+            if (m.seq) lastSeq.current = Math.max(lastSeq.current, m.seq);
+            write(b64ToBytes(m.payload?.data ?? ''));
+            break;
+          case 'keyframe':
+            gotFrameRef.current = true; retryRef.current = 0;
+            for (const f of m.payload?.frames ?? []) { if (f.seq) lastSeq.current = Math.max(lastSeq.current, f.seq); write(b64ToBytes(f.payload.data)); }
+            break;
+          case 'error':
+            write(textEnc.encode(`\r\n[${m.payload?.code ?? 'error'}]\r\n`));
+            break;
+        }
+      });
+    };
+    connect();
   }, []);
 
-  const detach = useCallback(() => { wsRef.current?.close(); wsRef.current = null; }, []);
+  const detach = useCallback(() => {
+    closedByUserRef.current = true;
+    roleRef.current = null;
+    if (termRef.current) termRef.current.options.disableStdin = true; // detached → read-only
+    if (retryTimerRef.current) { clearTimeout(retryTimerRef.current); retryTimerRef.current = null; }
+    wsRef.current?.close();
+    wsRef.current = null;
+  }, []);
   const replay = useCallback((url: string, requestedRole?: Exclude<Role, null>) => {
     const role = requestedRole ?? roleRef.current ?? 'observer';
     detach();