@aiwg/cockpit 2026.7.11 → 2026.7.12

package/README.md

@@ -58,7 +58,8 @@ AIWG_COCKPIT_EXECUTOR_URL=http://127.0.0.1:8122 aiwg cockpit
 - **Home** — connected-state overview, first-run flow, and a session-first entry point.
 - **Inventory** — host, container, Docker, and VM runtime targets with lifecycle controls.
 - **Running** — active work across stacks, spend posture, and task stop controls.
-- **Sessions** — observe-first terminal attach, explicit drive/control, and replay posture.
+- **Missions** — read-only Mission Control projection: sessions, per-mission status, audit tail.
+- **Sessions** — observe-first terminal attach, explicit drive/control, replay posture, and stale-agent recovery.
 - **Approvals** — unified human-in-the-loop decision inbox.
 - **Explore** — live index status/query/rebuild plus read-only AIWG capability catalog.
 - **Library** — user-owned assets cloned/imported under `~/.aiwg/cockpit/library`.
@@ -138,7 +139,8 @@ operator / CLI:  aiwg cockpit
 | **Home** | Guided first-run: what-is-this, live status, the **Start a session** primary verb, first-run tour. |
 | **Inventory** | Instances + lifecycle (Start/Stop/Destroy). |
 | **Running** | Running work across stacks + cross-stack spend + per-task Stop. |
-| **Sessions** | Live pty terminal — observe/drive, keyframe, non-destructive replay; inline **＋ capability picker**. |
+| **Missions** | Read-only Mission Control projection — durable `aiwg mc` sessions merged with the live executor task session. |
+| **Sessions** | Live pty terminal — observe/drive, keyframe, non-destructive replay, stale-agent recovery; inline **＋ capability picker**. |
 | **Approvals** | Unified HITL inbox (`hitl-prompt/v1`); decisions = operator authorization. |
 | **Explore** | Live artifact-index status/query/rebuild plus read-only AIWG catalog search. |
 | **Library** | Your own assets — clone from the catalog / import / remove. AIWG files never overwritten. |
@@ -177,9 +179,10 @@ Set `AIWG_COCKPIT_KEYCHAIN_STRICT=1` when shells must refuse plaintext runtime
 tokens. In strict mode the Bridge exits if it cannot persist the per-launch token
 to the OS keychain, and shell-core refuses runtime files that only contain a
 plaintext token. Operator intent is also recorded in a local redacted audit log
-under `~/.aiwg/cockpit/audit/events.jsonl` for lifecycle, session, action-inject,
-and approval-response decisions; bearer material and provider credentials are
-redacted before write.
+under `~/.aiwg/cockpit/audit/events.jsonl` for lifecycle, session, and
+approval-response decisions (the web UI additionally records action injections
+as operator intents); bearer material and provider credentials are redacted
+before write.
 
 ## Run (dev/test, against a real agentic-sandbox executor)
 
@@ -196,6 +199,17 @@ binary before serving Cockpit. Override `AIWG_COCKPIT_EXECUTOR_URL` (default
 `http://127.0.0.1:8122`) or `PORT` (default `8140`). Set
 `AIWG_COCKPIT_EXECUTOR_COMMAND` to pin the autostart command, or
 `AIWG_COCKPIT_AUTOSTART_EXECUTOR=0` to require an already-running executor.
+
+**Bring up both halves at once (#1634).** `npm run cockpit:up` (→
+`apps/cockpit/scripts/cockpit-up.sh`) guarantees a real, current executor is
+listening *before* the Bridge starts: it launches the agentic-sandbox executor
+via its own `management/dev.sh` when one isn't already healthy on
+`AIWG_COCKPIT_EXECUTOR_URL` (default `http://127.0.0.1:8122`), then delegates to
+`cockpit-dev.sh` for the Bridge + UI. Set `AIWG_COCKPIT_ENSURE_EXECUTOR=0` to
+skip the executor-ensure step when a sandbox is already running, or
+`AIWG_COCKPIT_START_HOST_DAEMON=1` to also start the optional host-runtime
+daemon. `cockpit-dev.sh` stays the Cockpit-only launcher.
+
 Equivalent manual steps:
 
 ```bash
@@ -217,10 +231,10 @@ agentic-sandbox executor. The bundled mock is reserved for automated tests and
 PoCs; if a mock-like executor is detected, the Bridge refuses it unless
 `AIWG_COCKPIT_ALLOW_MOCK_EXECUTOR=1` is set by an automated harness.
 
-The Bridge keeps legacy admin-surface compatibility (`/admin/instances`,
-`/admin/running`) for automated coverage, but dev/test launches should target
-real agentic-sandbox v2 admin surfaces (`/api/v2/admin/instances`,
-`/api/v2/admin/running`). Field normalization covers snake_case and camelCase
+The Bridge probes legacy (`/admin/instances`) and v2 (`/api/v2/admin/instances`)
+admin surfaces as fallback candidates for inventory and lifecycle; running work
+and approvals are derived from per-instance A2A task lists rather than any
+admin `/running` route. Field normalization covers snake_case and camelCase
 payloads so live sandboxes can evolve without breaking the operator UI; unknown
 fields degrade to opaque posture rather than failing the screen.
 
@@ -230,6 +244,39 @@ QEMU/VM launches. Cockpit does not replace attached sessions when provisioning;
 it refreshes inventory and leaves concurrency and resource admission to
 agentic-sandbox.
 
+### Recover stale agents
+
+When a container, Docker, or VM runtime is still running but its agent
+registration has disappeared, Cockpit keeps the row visible instead of hiding
+it. Inventory and Sessions show `agent unreachable` and expose **Reconnect**
+for stale container/Docker **and vm/qemu/kvm** rows (#1778). Use this when an
+instance is alive but session attach, running projections, or actions cannot
+resolve an agent id.
+
+The Bridge handles recovery through:
+
+1. executor-owned reconnect endpoints when the sandbox exposes one, then
+2. local Docker fallback: `docker exec <container> agent-reconnect`, or
+3. VM fallback (#1778): the same reconnect SIGHUP delivered through the libvirt
+   qemu-guest-agent channel (`virsh qemu-agent-command <domain> guest-exec
+   pkill -HUP -x agent-client`). Sessions survive reconnect on agentic-sandbox
+   2026.7.8+ agents; older agents preserve only detached tmux sessions
+   (agentic-sandbox#634).
+
+The Docker fallback requires sandbox images that include the `agent-reconnect`
+helper (agentic-sandbox v2026.7.5+ images); the VM fallback requires virsh
+access to the domain from the Bridge host. If **Reconnect** reports that no
+reconnect path is available, rebuild or repull the sandbox image, then start the
+instance again. For host targets, prefer starting Cockpit with the host daemon:
+
+```bash
+AIWG_COCKPIT_START_HOST_DAEMON=1 npm run cockpit:up
+```
+
+After a successful reconnect, refresh Inventory, then attach from Sessions. A
+Reconnect action never creates a replacement instance and never destroys the
+running container; it only attempts to restore the missing agent registration.
+
 `aiwg cockpit` (the operator command) will wrap this; the Bridge serves the built
 React app token-injected, falling back to a legacy page when no build is present.
 
@@ -402,6 +449,25 @@ Known state as of the 2026-06-19 host live run:
   `v2026.6.34`: VM matrix PASS — provision → vsock enroll → boot-ready → provider
   workload → clean destroy. Evidence:
   `.aiwg/testing/cockpit-vm-vsock-2026-06-27.md/.json`.
+- Instance **transport posture + host-daemon** now surface from the sandbox side
+  (`dd97529 fix(admin-v2): expose instance transport posture`, plus `#611`
+  host-runtime session listing). Re-validated Cockpit-side against `v2026.7.4`
+  (2026-07-09): Inventory renders real posture per instance — Host + Container
+  `Secure transport · mtls` (Host daemon `available`), enrolled VM `Local
+  transport · vsock`, a mid-bootstrap VM showing transport `Unknown` with the
+  informative posture `bootstrap-pending` (vs the old dead `unknown`; every
+  enrolled instance now renders real posture). Session-list returns
+  cleanly (no 502 — the `#140`/`#611` endpoints are live). Runtime coverage
+  banner `host ✓ · docker ✓ · vm ✓`. Evidence:
+  `.aiwg/testing/cockpit-7.4-transport-verify-2026-07-09.md` +
+  `.aiwg/working/cockpit-7.4-inventory-2026-07-09.png`.
+- Stale Docker/container agent recovery is wired through the Bridge and UI
+  (2026-07-11): stale running instances remain visible as `agent unreachable`,
+  Inventory and Sessions expose **Reconnect**, and the Bridge tries executor
+  reconnect before Docker `agent-reconnect`. Host-daemon scoped live UAT passed
+  against the real executor with `AIWG_COCKPIT_LIVE_PROVISION=1`,
+  `AIWG_COCKPIT_LIVE_MATRIX_TARGETS=host`, and Codex provider workload evidence
+  at `test-results/cockpit-live-host-daemon-2026-07-11.md/.json`.
 - Remaining upstream follow-ups are Claude auth-state propagation
   (roctinam/agentic-sandbox#499) and agent-scoped PTY sessions not appearing in
   the formal/global session registry (roctinam/agentic-sandbox#500).
@@ -418,9 +484,11 @@ agentic-sandbox executor through `AIWG_COCKPIT_EXECUTOR_URL`. The host target
 (agentic-sandbox#460) and direct/managed multiplexer sessions
 (agentic-sandbox#461) have landed upstream; the Bridge seam is now the
 AIWG-side integration point for #1589. Runtime-tier provisioning and
-host-daemon UX are tracked in roctinam/aiwg#1615, direct/managed PTY negotiation
-in #1616, the live real-sandbox gate in #1617, and transport-trust visibility in
-#1618. Secure transport details map back to agentic-sandbox#409/#410/#412; local
+host-daemon surfacing (roctinam/aiwg#1615) and transport-trust visibility (#1618)
+**landed and are verified against `v2026.7.4`** — transport posture and
+host-daemon now render per instance (a host-daemon *detail-status* payload
+remains a residual under #1615). Direct/managed PTY negotiation (#1616) and the
+live real-sandbox gate (#1617) continue. Secure transport details map back to agentic-sandbox#409/#410/#412; local
 Browser/Tauri/VS Code-to-Bridge auth remains roctinam/aiwg#1595.
 
 ### Operator-wall review modes (#1622)

package/bridge/src/server.mjs

@@ -357,7 +357,23 @@ async function proxy(res, method, target) {
   return json(res, r.status, body);
 }
 
-async function fetchJsonFirst(candidates, { method = 'GET', headers, body: requestBodyOption, timeoutMs = 0 } = {}) {
+const SAFE_FALLBACK_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+function isAbortError(err) {
+  return err?.name === 'AbortError' || /aborted|abort/i.test(String(err?.message ?? err));
+}
+
+function isConnectionRefusedError(err) {
+  const text = [
+    err?.code,
+    err?.cause?.code,
+    err?.message,
+    err?.cause?.message,
+  ].filter(Boolean).join(' ');
+  return /ECONNREFUSED|connection refused/i.test(text);
+}
+
+export async function fetchJsonFirst(candidates, { method = 'GET', headers, body: requestBodyOption, timeoutMs = 0 } = {}) {
   const failures = [];
   for (const candidate of candidates) {
     const target = typeof candidate === 'string' ? candidate : candidate.target;
@@ -370,7 +386,13 @@ async function fetchJsonFirst(candidates, { method = 'GET', headers, body: reque
     try {
       r = await fetch(target, { method: requestMethod, headers: requestHeaders, body: requestBody, ...(controller ? { signal: controller.signal } : {}) });
     } catch (err) {
-      failures.push(`${target} -> ${String(err?.message ?? err)}`);
+      const failure = isAbortError(err) && timeoutMs > 0
+        ? `${target} -> timeout after ${timeoutMs}ms`
+        : `${target} -> ${String(err?.message ?? err)}`;
+      failures.push(failure);
+      const safeToTryNext = SAFE_FALLBACK_METHODS.has(String(requestMethod).toUpperCase())
+        || isConnectionRefusedError(err);
+      if (!safeToTryNext) throw new Error(failures.join('; '));
       continue;
     } finally {
       if (timeout) clearTimeout(timeout);
@@ -580,6 +602,138 @@ async function destroyInstance(upstreamUrl, instanceId) {
   };
 }
 
+// #1778: VM-runtime counterpart of `docker exec <ctr> agent-reconnect`. Sandbox
+// VM images bake qemu-guest-agent ("essential for virsh exec") and agent-rs
+// handles SIGHUP as reconnect-in-place on every runtime, so delivering
+// `pkill -HUP -x agent-client` through the libvirt guest-agent channel makes
+// the agent re-register without touching the VM. Session survival is
+// version-conditional: agentic-sandbox 2026.7.8+ agents preserve all sessions
+// across reconnect; older agents preserve only detached-tmux sessions
+// (agentic-sandbox#634).
+async function signalVmAgentReconnect(domain) {
+  const execRaw = await spawnCollect('virsh', ['qemu-agent-command', domain, JSON.stringify({
+    execute: 'guest-exec',
+    arguments: { path: '/bin/sh', arg: ['-c', 'pkill -HUP -x agent-client'], 'capture-output': true },
+  })]);
+  const pid = JSON.parse(String(execRaw))?.return?.pid;
+  if (!Number.isInteger(pid)) throw new Error(`guest-exec returned no pid: ${String(execRaw).trim()}`);
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const statusRaw = await spawnCollect('virsh', ['qemu-agent-command', domain, JSON.stringify({
+      execute: 'guest-exec-status',
+      arguments: { pid },
+    })]);
+    const status = JSON.parse(String(statusRaw))?.return;
+    if (status?.exited) return status.exitcode ?? 0;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  // The signal command was handed to the guest; slow exec-status reporting is
+  // not a delivery failure.
+  return 0;
+}
+
+const VM_RUNTIME_KINDS = ['vm', 'qemu', 'kvm'];
+
+async function reconnectInstance(upstreamUrl, instanceId) {
+  const inventory = await getInventory(upstreamUrl).catch(() => ({ instances: [] }));
+  const inst = inventory.instances.find((i) => String(i.id) === String(instanceId));
+  const runtime = String(inst?.runtime ?? inst?.runtime_posture?.kind ?? '').toLowerCase();
+  const dockerName = inst?.launch_context?.name;
+  const candidates = [
+    { target: `${upstreamUrl}/api/v2/admin/instances/${encodeURIComponent(instanceId)}/reconnect`, method: 'POST' },
+    { target: `${upstreamUrl}/admin/instances/${encodeURIComponent(instanceId)}/reconnect`, method: 'POST' },
+    { target: `${upstreamUrl}/api/v1/instances/${encodeURIComponent(instanceId)}/reconnect`, method: 'POST' },
+  ];
+  try {
+    const result = await fetchJsonFirst(candidates, { timeoutMs: 5_000 });
+    if (result.status < 400) return result;
+  } catch {
+    // agentic-sandbox v2026.7.6 still exposes the container reconnect as an
+    // in-image helper, not an HTTP endpoint. Fall through to the local-dev path.
+  }
+
+  if (['docker', 'container'].includes(runtime) && dockerName) {
+    try {
+      const output = await spawnCollect('docker', ['exec', dockerName, 'agent-reconnect']);
+      return {
+        target: `docker exec ${dockerName} agent-reconnect`,
+        status: 202,
+        body: {
+          id: instanceId,
+          runtime,
+          docker_name: dockerName,
+          state: 'reconnecting',
+          message: `Reconnect requested for ${dockerName}; inventory will refresh as the agent re-registers.`,
+          output: String(output).trim(),
+          fallback: 'docker-agent-reconnect',
+        },
+      };
+    } catch (err) {
+      return {
+        target: `docker exec ${dockerName} agent-reconnect`,
+        status: 502,
+        body: {
+          error: 'reconnect_failed',
+          message: `Could not run agent-reconnect in ${dockerName}. Repull/rebuild the agent image if it predates agentic-sandbox v2026.7.5.`,
+          detail: String(err?.message ?? err),
+        },
+      };
+    }
+  }
+
+  if (VM_RUNTIME_KINDS.includes(runtime)) {
+    // For VM instances the agent_id doubles as the libvirt domain name
+    // (agentic-sandbox provision-vm.sh registers agent_id = $vm_name).
+    const domain = dockerName ?? inst?.name ?? String(instanceId);
+    const target = `virsh qemu-agent-command ${domain} guest-exec pkill -HUP -x agent-client`;
+    try {
+      const exitcode = await signalVmAgentReconnect(domain);
+      if (exitcode === 0) {
+        return {
+          target,
+          status: 202,
+          body: {
+            id: instanceId,
+            runtime,
+            vm_domain: domain,
+            state: 'reconnecting',
+            message: `Reconnect requested for VM ${domain}; inventory will refresh as the agent re-registers. Sessions survive reconnect on agentic-sandbox 2026.7.8+ agents; older agents preserve only detached tmux sessions (agentic-sandbox#634).`,
+            fallback: 'virsh-guest-agent-sighup',
+          },
+        };
+      }
+      return {
+        target,
+        status: 502,
+        body: {
+          error: 'reconnect_failed',
+          message: `No running agent-client process found inside VM ${domain}. Restart the agent service in the guest (systemctl restart agent-client) or reprovision the VM.`,
+          exitcode,
+        },
+      };
+    } catch (err) {
+      return {
+        target,
+        status: 502,
+        body: {
+          error: 'reconnect_failed',
+          message: `Could not signal agent-client in VM ${domain} via qemu-guest-agent. The bridge host needs virsh access to the libvirt domain and the guest-agent channel must be up (agentic-sandbox#633).`,
+          detail: String(err?.message ?? err),
+        },
+      };
+    }
+  }
+
+  return {
+    target: `${upstreamUrl}/api/v2/admin/instances/${encodeURIComponent(instanceId)}/reconnect`,
+    status: 409,
+    body: {
+      error: 'reconnect_unavailable',
+      message: 'Reconnect is available for Docker/container instances (docker exec) and VM instances (qemu-guest-agent). For host-runtime agents, signal the agent directly: pkill -HUP -x agent-client.',
+      runtime: runtime || 'unknown',
+    },
+  };
+}
+
 function asArrayFromEnvelope(body, keys) {
   if (Array.isArray(body)) return body;
   if (!body || typeof body !== 'object') return [];
@@ -594,10 +748,22 @@ function asArrayFromEnvelope(body, keys) {
   return [];
 }
 
+const AGENT_ID_CACHE_TTL_MS = Number(process.env.AIWG_COCKPIT_AGENT_CACHE_TTL_MS ?? 5_000);
+const agentListCache = new Map();
+
+async function getAgentList(executorUrl) {
+  const cached = agentListCache.get(executorUrl);
+  const now = Date.now();
+  if (cached && cached.expiresAt > now) return cached.agents;
+  const { body } = await fetchJsonFirst([`${executorUrl}/api/v1/agents`]);
+  const agents = asArrayFromEnvelope(body, ['agents', 'items', 'data']);
+  agentListCache.set(executorUrl, { agents, expiresAt: now + AGENT_ID_CACHE_TTL_MS });
+  return agents;
+}
+
 async function resolveSessionAgentId(executorUrl, instanceId) {
   try {
-    const { body } = await fetchJsonFirst([`${executorUrl}/api/v1/agents`]);
-    const agents = asArrayFromEnvelope(body, ['agents', 'items', 'data']);
+    const agents = await getAgentList(executorUrl);
     const agent = agents.find((a) => String(a.instance_id ?? a.instanceId ?? '') === String(instanceId));
     return agent?.id ?? agent?.agent_id ?? agent?.agentId ?? instanceId;
   } catch {
@@ -769,17 +935,23 @@ function normalizeInstance(executorUrl, i) {
 function defaultSessionLaunch(instance) {
   const runtime = String(instance?.runtime_posture?.kind ?? instance?.runtime ?? '').toLowerCase();
   if (runtime === 'host') {
+    // Honor the executor-reported cwd — it is valid on the target host, including
+    // remote worker hosts whose filesystem does not mirror the Bridge machine.
+    // Fall back to the operator home only when the executor reports no cwd;
+    // hardcoding homedir() would resolve the Bridge's local home and break
+    // sessions on any host runtime that is not the Bridge machine itself.
     return {
       command: 'bash',
       args: ['-l'],
-      working_dir: instance?.launch_context?.cwd,
+      working_dir: instance?.launch_context?.cwd ?? homedir(),
     };
   }
   if (runtime === 'container' || runtime === 'docker' || runtime === 'vm' || runtime === 'qemu' || runtime === 'kvm') {
+    const home = runtime === 'container' || runtime === 'docker' ? '/root' : '/home/agent';
     return {
       command: '/bin/bash',
-      args: ['-lc', 'cd "${HOME:-/root}" && exec /bin/bash -l'],
-      working_dir: '/root',
+      args: ['-lc', `cd ${shellSingleQuote(home)} && exec /bin/bash -l`],
+      working_dir: home,
     };
   }
   return {
@@ -788,6 +960,25 @@ function defaultSessionLaunch(instance) {
   };
 }
 
+// Deterministic prefix + per-request nonce. The name is IDENTICAL across this
+// request's fallback candidates (so a timed-out-but-created session is
+// recoverable by name, and the executor's 409-by-name guard dedupes candidate
+// retries) but UNIQUE across requests — operators can hold multiple concurrent
+// sessions per (instance, mode, backend). A fully canonical name here silently
+// reused the first session on every subsequent "New session" click.
+function sessionNameFor(instanceId, { mode = 'managed', backend = 'tmux' } = {}) {
+  const slug = (value) => String(value || 'default')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 36) || 'default';
+  return `cockpit-${slug(instanceId)}-${slug(mode)}-${slug(backend)}-${randomBytes(3).toString('hex')}`;
+}
+
+function shellSingleQuote(value) {
+  return `'${String(value).replaceAll("'", "'\"'\"'")}'`;
+}
+
 function runtimeExtensionFromCard(card) {
   const extensions = card?.capabilities?.extensions;
   if (!Array.isArray(extensions)) return null;
@@ -817,8 +1008,7 @@ async function enrichInstanceFromAgentCard(executorUrl, instance) {
 
 async function getRegisteredAgents(executorUrl) {
   try {
-    const { body } = await fetchJsonFirst([`${executorUrl}/api/v1/agents`]);
-    return asArrayFromEnvelope(body, ['agents', 'items', 'data']);
+    return await getAgentList(executorUrl);
   } catch {
     return [];
   }
@@ -1220,8 +1410,8 @@ async function getSessionEventRows(executorUrl, instances) {
         agent_id: session.agent_id,
         state: session.state ?? session.status ?? session.session_state ?? 'available',
         role_policy: session.role_policy,
-        backend: session.backend ?? session.session_backend,
-        mode: session.mode ?? session.session_class,
+        session_backend: session.session_backend,
+        session_class: session.session_class,
       });
     }
   }));
@@ -1248,7 +1438,7 @@ async function getEventSnapshot(executorUrl) {
     events.push({ id: `approval:${approval.id}`, type: 'hitl.approval', source: 'a2a', subject: approval.task_id ?? approval.id, state: approval.status, severity: approval.risk, ts, ref: { instance_id: approval.instance_id, approval_id: approval.id } });
   }
   for (const session of sessions ?? []) {
-    events.push({ id: `session:${session.instance_id}:${session.id}`, type: 'session.lifecycle', source: 'pty-session', subject: session.id, state: session.state, ts, ref: { instance_id: session.instance_id, session_id: session.id, agent_id: session.agent_id, backend: session.backend, mode: session.mode, role_policy: session.role_policy } });
+    events.push({ id: `session:${session.instance_id}:${session.id}`, type: 'session.lifecycle', source: 'pty-session', subject: session.id, state: session.state, ts, ref: { instance_id: session.instance_id, session_id: session.id, agent_id: session.agent_id, session_backend: session.session_backend, session_class: session.session_class, role_policy: session.role_policy } });
   }
   for (const mission of missions.missions ?? []) {
     events.push({ id: `mission:${mission.id}`, type: 'mission.lifecycle', source: mission.source ?? 'aiwg-mc', subject: mission.id, state: mission.status, ts, ref: { session_id: mission.session_id, mission_id: mission.id, ralph_loop_id: mission.ralph_loop_id } });
@@ -1324,6 +1514,50 @@ async function getSessions(executorUrl, instanceId) {
   return normalizeSessionRows({ sessions, executorUrl, instanceId, sessionAgentId });
 }
 
+function normalizeScreenSnapshot(body, { instanceId, sessionId, source }) {
+  const text = String(body?.text ?? body?.snapshot ?? body?.screen ?? body?.content ?? '');
+  const rawLines = Array.isArray(body?.lines) ? body.lines : text.replace(/\r/g, '\n').split('\n');
+  return {
+    instance_id: instanceId,
+    session_id: sessionId,
+    text,
+    lines: rawLines.map((line) => String(line)).filter(Boolean).slice(-80),
+    seq: body?.seq ?? body?.sequence ?? body?.anchor_sequence ?? body?.anchorSequence ?? null,
+    fetched_at: new Date().toISOString(),
+    source,
+    snapshot_format: body?.snapshot_format ?? body?.snapshotFormat ?? body?.format ?? 'text/plain',
+  };
+}
+
+async function getSessionScreen(executorUrl, instanceId, sessionId) {
+  const sessionAgentId = await resolveSessionAgentId(executorUrl, instanceId);
+  const agentIds = unique([sessionAgentId, instanceId]);
+  const paths = agentIds.flatMap((agentId) => {
+    const encodedAgent = encodeURIComponent(agentId);
+    const encodedSession = encodeURIComponent(sessionId);
+    return [
+      `${executorUrl}/api/v1/agents/${encodedAgent}/sessions/${encodedSession}/screen`,
+      `${executorUrl}/api/v1/agents/${encodedAgent}/sessions/${encodedSession}/screen-state`,
+      `${executorUrl}/agents/${encodedAgent}/sessions/${encodedSession}/screen`,
+      `${executorUrl}/agents/${encodedAgent}/sessions/${encodedSession}/screen-state`,
+    ];
+  });
+  try {
+    const { body, target, status } = await fetchJsonFirst(paths);
+    return { status, body: normalizeScreenSnapshot(body, { instanceId, sessionId, source: target }) };
+  } catch (e) {
+    return {
+      status: 404,
+      body: {
+        error: 'session_screen_unavailable',
+        instance_id: instanceId,
+        session_id: sessionId,
+        detail: String(e?.message ?? e),
+      },
+    };
+  }
+}
+
 export function normalizeSessionRows({ sessions, executorUrl, instanceId, sessionAgentId = instanceId }) {
   const wsBase = executorUrl.replace(/^http/i, 'ws');
   const normalizeAttachUrl = (s, sessionId) => {
@@ -1454,6 +1688,20 @@ async function endSession(executorUrl, instanceId, sessionId) {
   };
 }
 
+async function findReusableSession(executorUrl, instanceId, sessionName) {
+  const sessions = (await getSessions(executorUrl, instanceId)).sessions;
+  return sessions.find((s) => String(s.session_name ?? s.sessionName ?? '') === String(sessionName));
+}
+
+function sessionResponseFromRow(row) {
+  return {
+    ...row,
+    id: row.id ?? row.session_id ?? row.sessionId,
+    attach_url: row.attach_url ?? row.attachUrl,
+    reused: true,
+  };
+}
+
 export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = ALLOW_MOCK_EXECUTOR, token } = {}) {
   const upstreamUrl = executorUrl;
   const TOKEN = token ?? randomBytes(24).toString('hex');
@@ -1576,6 +1824,10 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
         const { status, body } = await endSession(upstreamUrl, decodeURIComponent(m[1]), decodeURIComponent(m[2]));
         return json(res, status, body);
       }
+      if ((m = url.pathname.match(/^\/api\/instances\/([^/]+)\/sessions\/([^/]+)\/screen$/)) && req.method === 'GET') {
+        const { status, body } = await getSessionScreen(upstreamUrl, decodeURIComponent(m[1]), decodeURIComponent(m[2]));
+        return json(res, status, body);
+      }
       // registry-bound, data-driven core — live, no app restart (#1592)
       if (url.pathname === '/api/capabilities') {
         const q = (url.searchParams.get('q') || '').trim();
@@ -1664,6 +1916,7 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
         if (backend) qs.set('backend', backend);
         if (loadout) qs.set('loadout', loadout);
         const sessionAgentId = await resolveSessionAgentId(upstreamUrl, id);
+        const sessionName = sessionNameFor(id, { mode: mode || 'managed', backend: backend || 'tmux' });
         let sessionLaunch = defaultSessionLaunch();
         try {
           const inventory = await getInventory(upstreamUrl);
@@ -1672,28 +1925,41 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
           // Session creation can still proceed without an explicit cwd; the
           // executor/agent will fall back to its own process cwd.
         }
+        // No pre-create reuse lookup: every create request gets its own uniquely
+        // named session (multi-session per instance is supported). Recovery by
+        // name below still catches a create that timed out after succeeding.
+        const sessionBody = JSON.stringify({
+          session_name: sessionName,
+          session_backend: backend || 'tmux',
+          session_class: mode || 'managed',
+          command: sessionLaunch.command,
+          args: sessionLaunch.args,
+          ...(sessionLaunch.working_dir ? { working_dir: sessionLaunch.working_dir } : {}),
+        });
         const candidates = unique([sessionAgentId, id]).flatMap((agentId) => [
           {
             target: `${upstreamUrl}/api/v1/agents/${encodeURIComponent(agentId)}/sessions`,
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({
-              session_backend: backend || 'tmux',
-              session_class: mode || 'managed',
-              command: sessionLaunch.command,
-              args: sessionLaunch.args,
-              ...(sessionLaunch.working_dir ? { working_dir: sessionLaunch.working_dir } : {}),
-            }),
+            body: sessionBody,
           },
           {
             target: `${upstreamUrl}/agents/${encodeURIComponent(agentId)}/sessions?${qs.toString()}`,
             method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: sessionBody,
           },
         ]);
         let sessionCreate;
         try {
           sessionCreate = await fetchJsonFirst(candidates, { timeoutMs: 8000 });
         } catch (err) {
+          try {
+            const reusable = await findReusableSession(upstreamUrl, id, sessionName);
+            if (reusable) return json(res, 200, sessionResponseFromRow(reusable));
+          } catch {
+            // Preserve the original create failure; reuse is a recovery path only.
+          }
           return json(res, 409, {
             error: 'agent_not_registered',
             message: 'The instance is visible in inventory, but its agent has not registered yet; PTY sessions are not ready.',
@@ -1701,6 +1967,15 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
           });
         }
         const { status, body } = sessionCreate;
+        if (status < 200 || status >= 300) {
+          try {
+            const reusable = await findReusableSession(upstreamUrl, id, sessionName);
+            if (reusable) return json(res, 200, sessionResponseFromRow(reusable));
+          } catch {
+            // Return the upstream non-2xx response when no reusable session is visible.
+          }
+          return json(res, status, body);
+        }
         const wsBase = upstreamUrl.replace(/^http/i, 'ws');
         const sessionId = body.id ?? body.session_id ?? body.sessionId;
         if (status >= 200 && status < 300 && !sessionId && !body.attach_url && !body.attachUrl && !body.pty_ws_url && !body.ptyWsUrl) {
@@ -1716,8 +1991,8 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
         }
         // 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.
-        await appendAudit('session.start.requested', { instance_id: id, mode: mode || 'managed', backend: backend || 'tmux', loadout, status, session_id: sessionId });
-        return json(res, status, { ...body, id: sessionId, attach_url: attachUrl ?? `${wsBase}/agents/${encodeURIComponent(id)}/sessions/${encodeURIComponent(sessionId)}/attach` });
+        await appendAudit('session.start.requested', { instance_id: id, mode: mode || 'managed', backend: backend || 'tmux', loadout, status, session_id: sessionId, session_name: sessionName });
+        return json(res, status, { ...body, id: sessionId, session_name: body.session_name ?? body.sessionName ?? sessionName, attach_url: attachUrl ?? `${wsBase}/agents/${encodeURIComponent(id)}/sessions/${encodeURIComponent(sessionId)}/attach` });
       }
 
       // --- management surface (UC-012): lifecycle + task cancel ---
@@ -1729,6 +2004,11 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
         await appendAudit('instance.lifecycle.requested', { instance_id: decodeURIComponent(m[1]), action: m[2], status: result.status, result: result.body });
         return json(res, result.status, result.body);
       }
+      if ((m = url.pathname.match(/^\/api\/instances\/([^/]+)\/reconnect$/)) && req.method === 'POST') {
+        const { status, body } = await reconnectInstance(upstreamUrl, decodeURIComponent(m[1]));
+        await appendAudit('instance.reconnect.requested', { instance_id: decodeURIComponent(m[1]), status, result: body });
+        return json(res, status, body);
+      }
       if ((m = url.pathname.match(/^\/api\/instances\/([^/]+)$/)) && req.method === 'DELETE') {
         const { status, body } = await destroyInstance(upstreamUrl, decodeURIComponent(m[1]));
         await appendAudit('instance.destroy.requested', { instance_id: decodeURIComponent(m[1]), status, result: body });

package/bridge/src/smoke.mjs

@@ -51,9 +51,9 @@ try {
   const demo = sess.sessions.find((s) => s.id === 'demo-shell');
   assert.ok(demo, 'demo-shell session present');
   assert.match(demo.attach_url, /^ws:\/\/.*\/agents\/.*\/sessions\/demo-shell\/attach$/, 'ws attach_url shape');
-  assert.ok(demo.seq >= 3, 'demo session has a seeded transcript');
-  assert.equal(demo.mode, 'direct', 'demo session mode');
-  assert.equal(demo.backend, 'native', 'demo session backend');
+  assert.ok(demo.liveness.replay_newest_seq >= 3, 'demo session has a seeded transcript');
+  assert.equal(demo.session_class, 'direct', 'demo session class');
+  assert.equal(demo.session_backend, 'native', 'demo session backend');
   assert.equal(demo.role_policy, 'observe-default', 'session role policy');
 
   const qemuDedup = normalizeSessionRows({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cockpit",
-  "version": "2026.7.11",
+  "version": "2026.7.12",
   "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",
@@ -43,7 +43,7 @@
     "build:web": "npm --prefix web install --no-audit --no-fund && npm --prefix web run build",
     "pack:dry": "npm pack --dry-run",
     "publish:dry": "npm publish --dry-run --access public",
-    "smoke": "node mock-executor/src/smoke.mjs && node bridge/src/smoke.mjs && node shell-core/smoke.mjs",
+    "smoke": "node mock-executor/src/smoke.mjs && node bridge/src/smoke.mjs && node shell-core/smoke.mjs && node vscode/smoke.mjs",
     "poc": "node poc/kill-bridge-isolation.mjs && node poc/security-checks.mjs",
     "test:web": "npm --prefix web run typecheck && npm --prefix web run test",
     "test": "npm run smoke && npm run poc",

package/runtime-docs/README.md

@@ -26,8 +26,9 @@ Every shell (browser, VS Code, Tauri) resolves the Bridge the same way — see
 ## Security
 
 - The per-launch token is written to the OS credential backend when one is available:
-  macOS Keychain (`security`), Windows Credential Manager (`cmdkey`), Linux libsecret
-  (`secret-tool`), or opt-in KDE Wallet (`AIWG_COCKPIT_ENABLE_KWALLET=1`).
+  macOS Keychain (`security`), Windows Credential Manager via PowerShell
+  PasswordVault, Linux libsecret (`secret-tool`), or opt-in KDE Wallet
+  (`AIWG_COCKPIT_ENABLE_KWALLET=1`).
 - `bridge.json` holds **only the overlay's own per-launch token or token reference** —
   never a provider or stack credential (verified by
   `apps/cockpit/poc/security-checks.mjs`, property I1). Set