@aiwg/cockpit 2026.6.3

package/bridge/src/smoke.mjs

@@ -0,0 +1,158 @@
+// End-to-end data-path smoke: executor fixture (admin) -> Bridge (/api/inventory) -> served screen.
+// Self-contained (own ports); no deps. Exits non-zero on failure.
+import assert from 'node:assert/strict';
+import { createExecutor } from '../../mock-executor/src/server.mjs';
+import { createBridge } from './server.mjs';
+
+const mock = createExecutor();
+await new Promise((r) => mock.listen(0, '127.0.0.1', r));
+const executorUrl = `http://127.0.0.1:${mock.address().port}`;
+
+const bridge = createBridge({ executorUrl, allowMockExecutor: true });
+await new Promise((r) => bridge.listen(0, '127.0.0.1', r));
+const base = `http://127.0.0.1:${bridge.address().port}`;
+// authed fetch helper — every /api/ call carries the per-launch bearer token
+const f = (p, o = {}) => fetch(base + p, { ...o, headers: { ...(o.headers || {}), authorization: 'Bearer ' + bridge.cockpitToken } });
+
+try {
+  // auth gate: /api/ without the token is 401; /healthz is open
+  assert.equal((await fetch(`${base}/api/inventory`)).status, 401, 'gate: no token -> 401');
+  assert.equal((await fetch(`${base}/api/inventory?token=wrong`)).status, 401, 'gate: bad token -> 401');
+  assert.equal((await fetch(`${base}/healthz`)).status, 200, 'healthz open (no token)');
+
+  // data path: Bridge reads the executor admin inventory
+  const r = await f('/api/inventory');
+  assert.equal(r.status, 200, 'inventory 200 (authed)');
+  const inv = await r.json();
+  assert.equal(inv.count, 4, 'four demo instances');
+  const ids = inv.instances.map((i) => i.id);
+  assert.ok(ids.includes('550e8400-e29b-41d4-a716-446655440000'), 'default instance present');
+  assert.equal(inv.instances.find((i) => i.runtime === 'host')?.runtime_posture.isolation, 'least', 'host is least-isolated');
+  assert.equal(inv.instances.find((i) => i.runtime === 'wasm-edge')?.runtime_posture.isolation, 'opaque', 'future runtime is opaque');
+  assert.equal(inv.instances.find((i) => i.transport?.mode === 'shared-secret')?.transport.trust, 'compatibility', 'legacy secret transport is compatibility posture');
+  const i0 = inv.instances[0];
+  for (const k of ['id', 'runtime', 'loadout', 'state', 'tenant', 'card_url', 'runtime_posture', 'host_daemon', 'transport', 'launch_context', 'session_backends']) assert.ok(k in i0, `field ${k}`);
+  assert.ok(['vm', 'container', 'host', 'wasm-edge'].includes(i0.runtime), 'runtime kind');
+
+  // running board: seeded working tasks on the running instances
+  const rr = await f("/api/running");
+  assert.equal(rr.status, 200, 'running 200');
+  const run = await rr.json();
+  assert.ok(run.count >= 2, 'at least two running tasks seeded');
+  for (const k of ['instance_id', 'task_id', 'state', 'tenant']) assert.ok(k in run.running[0], `running field ${k}`);
+  for (const k of ['runtime_posture', 'transport']) assert.ok(k in run.running[0], `running posture field ${k}`);
+  assert.equal(run.running[0].state, 'working', 'running task is working');
+
+  // sessions: the demo pty session is listed with a direct ws attach_url
+  const sr = await f("/api/sessions?instance=550e8400-e29b-41d4-a716-446655440000");
+  assert.equal(sr.status, 200, 'sessions 200');
+  const sess = await sr.json();
+  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.equal(demo.role_policy, 'observe-default', 'session role policy');
+
+  // missing instance param is a 400
+  assert.equal((await f("/api/sessions")).status, 400, 'sessions requires instance');
+
+  // loadout catalog passthrough — the start-session picker offers the full set (#1641)
+  const lo = await (await f('/api/loadouts')).json();
+  assert.ok(Array.isArray(lo.loadouts) && lo.loadouts.length >= 3, 'loadout catalog returned');
+  assert.ok(lo.loadouts.every((l) => typeof l.id === 'string' && typeof l.label === 'string'), 'loadouts carry id+label');
+  assert.ok(lo.loadouts.some((l) => l.id === 'security-audit'), 'catalog includes a non-default loadout');
+
+  // registry binding: discover + show through the aiwg CLI (#1592)
+  const cap = await (await f("/api/capabilities?q=" + encodeURIComponent("deploy production") + "&limit=4")).json();
+  assert.ok(Array.isArray(cap.results) && cap.results.length >= 1, 'discover returns results');
+  const hit = cap.results.find((r) => r.name === 'flow-deploy-to-production');
+  assert.ok(hit, 'flow-deploy-to-production discoverable');
+  assert.ok(hit.name && hit.type, 'result carries name+type for show');
+  const shown = await (await f("/api/show?type=skill&name=flow-deploy-to-production")).json();
+  assert.match(shown.body, /name:\s*flow-deploy-to-production/, 'show returns the skill body');
+  assert.equal((await f("/api/capabilities")).status, 400, 'capabilities requires q');
+  // show by discovered PATH — deterministic, sidesteps ambiguous same-named artifacts (#1643)
+  const shownByPath = await (await f(`/api/show?path=${encodeURIComponent(hit.path)}`)).json();
+  assert.match(shownByPath.body, /name:\s*flow-deploy-to-production/, 'show-by-path returns the body');
+  assert.equal(shownByPath.path, hit.path, 'show-by-path echoes the resolved path');
+  // a missing artifact is a 4xx, never a 502 (ambiguous/not-found map to operator-correctable input)
+  assert.equal((await f('/api/show?type=agent&name=__definitely_not_a_real_artifact__')).status, 404, 'unknown artifact -> 404 not 502');
+  // a path outside the AIWG corpus is refused (no traversal)
+  assert.equal((await f(`/api/show?path=${encodeURIComponent('/etc/passwd')}`)).status, 400, 'path outside corpus -> 400');
+
+  // contribution model: actions INJECT a command into a session — the Cockpit never
+  // runs the CLI (adr-cockpit-session-control-not-cli-runner) (#1591)
+  const contrib = await (await f("/api/contributions")).json();
+  assert.ok(contrib.sources.some((s) => s.id === 'aiwg-core'), 'aiwg-core contribution loaded');
+  const audit = contrib.actions.find((a) => a.id === 'audit-issues');
+  assert.ok(audit && typeof audit.inject.command === 'string', 'audit-issues declares an inject command');
+  assert.match(audit.inject.command, /issue-audit/, 'audit-issues injects the issue-audit command');
+  // the spawn-aiwg run endpoint is removed
+  assert.equal((await f("/api/actions/audit-issues/run", { method: 'POST' })).status, 404, 'action run endpoint gone (no Bridge CLI run for actions)');
+
+  // management: lifecycle (UC-012)
+  const stoppedId = '9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b';
+  assert.equal((await (await f(`/api/instances/${stoppedId}/start`, { method: 'POST' })).json()).state, 'running', 'start -> running');
+  assert.equal((await (await f(`/api/instances/${stoppedId}/stop`, { method: 'POST' })).json()).state, 'stopped', 'stop -> stopped');
+
+  // management: cancel a running task
+  const before = await (await f('/api/running')).json();
+  const victim = before.running[0];
+  assert.equal((await f(`/api/tasks/${victim.instance_id}/${victim.task_id}/cancel`, { method: 'POST' })).status, 200, 'task cancel 200');
+  const after = await (await f('/api/running')).json();
+  assert.ok(after.count < before.count, 'cancel removed a running task');
+
+  // approval inbox (UC-009)
+  const pend = await (await f('/api/approvals?status=pending')).json();
+  assert.ok(pend.approvals.length >= 2, 'pending approvals seeded');
+  const apr = await (await f('/api/approvals/apr-001?decision=approve', { method: 'POST' })).json();
+  assert.equal(apr.status, 'approved', 'approval resolves to approved');
+  const pend2 = await (await f('/api/approvals?status=pending')).json();
+  assert.equal(pend2.approvals.length, pend.approvals.length - 1, 'approved item leaves the queue');
+
+  // cost rollup (UC-010)
+  const cost = await (await f('/api/cost')).json();
+  assert.ok(cost.total.usd > 0 && cost.per_instance.length >= 1, 'cost rollup present');
+
+  // destroy
+  assert.equal((await (await f(`/api/instances/${stoppedId}`, { method: 'DELETE' })).json()).destroyed, stoppedId, 'destroy returns id');
+
+  // user asset library: clone a catalog asset into the library, list it, delete it.
+  // (AIWG source is read-only — clone copies into ~/.aiwg/cockpit/library, never the reverse.)
+  const cloneRes = await f(`/api/library/clone?type=${encodeURIComponent(hit.type)}&name=${encodeURIComponent(hit.name)}&path=${encodeURIComponent(hit.path)}`, { method: 'POST' });
+  assert.ok([201, 400].includes(cloneRes.status), 'clone returns 201 (new) or 400 (already present)');
+  const lib1 = await (await f('/api/library')).json();
+  assert.ok(lib1.library.some((a) => a.name === hit.name), 'cloned asset appears in the user library');
+  assert.equal((await f(`/api/library/${encodeURIComponent(hit.name)}`, { method: 'DELETE' })).status, 200, 'library delete 200');
+  const lib2 = await (await f('/api/library')).json();
+  assert.ok(!lib2.library.some((a) => a.name === hit.name), 'deleted asset removed from library');
+  // a path that escapes the library is refused
+  assert.equal((await f('/api/library/..%2f..%2fevil', { method: 'DELETE' })).status, 404, 'escape attempt refused');
+
+  // start a session (onboarding primary verb): create + issue a ws attach_url
+  const started = await (await f('/api/instances/550e8400-e29b-41d4-a716-446655440000/sessions', { method: 'POST' })).json();
+  assert.match(started.id ?? '', /^sess-/, 'start-session returns a new session id');
+  assert.match(started.attach_url ?? '', /\/sessions\/sess-[^/]+\/attach$/, 'start-session issues a ws attach_url');
+
+  // app shell served with the per-launch token injected (React build if present, else
+  // the legacy fallback — both carry the title + token)
+  const html = await (await fetch(base + "/")).text();
+  assert.match(html, /AIWG.?Cockpit/i, 'app title rendered');
+  assert.ok(html.includes(`window.__COCKPIT_TOKEN__=${JSON.stringify(bridge.cockpitToken)}`), 'token injected into the served app');
+  // strip HTML comments BEFORE matching — a module script trapped inside a comment
+  // (the Vite '</head>'-in-comment gotcha) must not count as "referenced".
+  const live = html.replace(/<!--[\s\S]*?-->/g, '');
+  const shell = /assets\//.test(html) ? 'react' : 'legacy';
+  if (shell === 'react') {
+    const asset = live.match(/<script[^>]+type="module"[^>]+src="([^"]*assets\/[^"]+\.js)"/);
+    assert.ok(asset, 'React build present → module bundle must be referenced outside comments');
+    assert.equal((await fetch(base + asset[1].replace(/^\.\//, '/'))).status, 200, 'built React bundle served');
+  }
+
+  console.log(`SMOKE OK — inventory(4) + running(${run.count}) + sessions(demo-shell) + registry(discover→${cap.results.length}) + contrib(${contrib.actions.length}) + shell(${shell})`);
+} finally {
+  bridge.close();
+  mock.close();
+}

package/contrib/aiwg-core.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "./contribution.schema.json",
+  "id": "aiwg-core",
+  "version": "1.0.0",
+  "title": "AIWG Core Actions",
+  "contributes": {
+    "actions": [
+      { "id": "audit-issues",   "title": "Audit Issues",   "icon": "🔍", "group": "issues",      "inject": { "command": "/issue-audit", "target": "focused" } },
+      { "id": "address-issues", "title": "Address Issues", "icon": "🛠️", "group": "issues",      "inject": { "command": "/address-issues", "target": "focused", "needs_args": true, "args_hint": "issue numbers, space-separated" } },
+      { "id": "doctor",         "title": "Doctor",          "icon": "🩺", "group": "maintenance", "inject": { "command": "/aiwg-doctor", "target": "focused" } }
+    ],
+    "screens": [],
+    "hooks": []
+  }
+}

package/contrib/contribution.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://aiwg.io/cockpit/contribution/v1",
+  "title": "AIWG Cockpit UI Contribution (#1591)",
+  "description": "Declarative extension of the Cockpit UI: screens, actions, and event-hooks. Loaded from apps/cockpit/contrib/ and (future) installed AIWG extensions. An action INJECTS a command into an agentic session (focused, else a new one) — the Cockpit never runs the CLI itself; the agent in the session does. See adr-cockpit-session-control-not-cli-runner.md.",
+  "type": "object",
+  "required": ["id", "version", "contributes"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$" },
+    "version": { "type": "string" },
+    "title": { "type": "string" },
+    "contributes": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "actions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "inject"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$" },
+              "title": { "type": "string" },
+              "icon": { "type": "string" },
+              "group": { "type": "string" },
+              "inject": {
+                "type": "object",
+                "required": ["command"],
+                "additionalProperties": false,
+                "properties": {
+                  "command": { "type": "string", "description": "command/prompt injected into an agentic session" },
+                  "target": { "type": "string", "enum": ["focused", "new"], "default": "focused", "description": "focused = inject into the attached session, else offer a new one; new = always a fresh session" },
+                  "needs_args": { "type": "boolean", "description": "prompt for arguments before injecting" },
+                  "args_hint": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "screens": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "source"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$" },
+              "title": { "type": "string" },
+              "source": { "type": "string", "description": "url or path the screen iframe/region loads" }
+            }
+          }
+        },
+        "hooks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["on", "action"],
+            "properties": {
+              "on": { "type": "string", "description": "event name, e.g. session.output, instance.state-changed" },
+              "action": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$", "description": "id of a contributed action to run" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/desktop/README.md

@@ -0,0 +1,42 @@
+# AIWG Cockpit — Desktop shell (Tauri v2)
+
+A lightweight native window hosting the **same registry-bound Bridge UI** as the
+VS Code shell and the browser. The shell does not replace the CLI or reimplement
+the control plane — `src-tauri/src/main.rs` waits for the Bridge's per-launch
+runtime token file (`~/.aiwg/cockpit/runtime/bridge.json`) and opens a window at
+the Bridge UI with the token on the query string.
+
+## Architecture
+
+```
+operator/CLI: aiwg cockpit
+      │  (spawns the Bridge; writes runtime/bridge.json mode 600)
+      ▼
+Bridge (127.0.0.1:PORT, token-gated /api) ── proxies ──▶ agentic-sandbox executor
+      ▲
+      │  loads http://127.0.0.1:PORT/?token=…
+desktop window  (this app)   ◀── same UI ──▶   VS Code webview  /  browser
+```
+
+## Build (toolchain-gated)
+
+Requires the Rust toolchain + Tauri prerequisites. On Linux: `webkit2gtk-4.1`,
+`libsoup-3.0`, `libappindicator`. Then:
+
+```bash
+cargo install tauri-cli --version '^2'   # once
+cd apps/cockpit/desktop
+cargo tauri init                          # generates icons/ + capabilities/ boilerplate (one-time)
+cargo tauri dev                           # run against a launched Bridge
+cargo tauri build                         # produce a bundle
+```
+
+> The repo ships the load-the-Bridge logic (`main.rs`), the Tauri config, and the
+> frontend splash. `cargo tauri init` fills in the platform boilerplate (icons,
+> v2 capabilities) that is environment-specific and not checked in.
+
+## Why a token file (not a socket handshake)
+
+The runtime file is the cross-platform handshake every shell shares (see
+`apps/cockpit/shell-core/runtime.mjs`). It is mode `600`; OS-keychain storage is a
+per-platform hardening follow-up (roctinam/aiwg#1595).

package/desktop/src-tauri/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "aiwg-cockpit-desktop"
+version = "0.0.0"
+edition = "2021"
+description = "AIWG Cockpit desktop shell — observe/drive/coordinate multi-stack agentic sessions over the registry-bound Bridge."
+license = "MIT"
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+serde_json = "1"
+
+[[bin]]
+name = "aiwg-cockpit-desktop"
+path = "src/main.rs"

package/desktop/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

package/desktop/src-tauri/frontend/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8" /><title>AIWG Cockpit</title>
+<style>html,body{margin:0;height:100%;background:#0f1115;color:#9aa3b2;font:15px system-ui,sans-serif;display:grid;place-items:center}</style>
+</head>
+<body>
+  <!-- Splash only. main.rs opens the real window at the Bridge UI once the runtime
+       token file appears; this placeholder satisfies Tauri's frontendDist. -->
+  <p>Starting AIWG Cockpit — waiting for the Bridge…</p>
+</body>
+</html>

package/desktop/src-tauri/src/main.rs

@@ -0,0 +1,55 @@
+// AIWG Cockpit — Tauri v2 desktop shell (#1594).
+//
+// The desktop window hosts the SAME registry-bound Bridge UI as the VS Code shell
+// and the browser. It does not replace the CLI or reimplement the control plane:
+// it waits for the Bridge's per-launch runtime token file and opens a window at the
+// Bridge UI (token on the query string).
+//
+// Build is toolchain-gated: requires the Rust toolchain + Tauri prerequisites
+// (on Linux, webkit2gtk + libsoup). Run `cargo tauri init` once to generate icons
+// and capabilities, then `cargo tauri build`. See README.md.
+use std::{fs, path::PathBuf, thread, time::Duration};
+use tauri::{WebviewUrl, WebviewWindowBuilder};
+
+fn runtime_file() -> PathBuf {
+    let home = std::env::var("HOME")
+        .or_else(|_| std::env::var("USERPROFILE"))
+        .unwrap_or_default();
+    PathBuf::from(home).join(".aiwg/cockpit/runtime/bridge.json")
+}
+
+/// Read { port, token } from the Bridge runtime file, if present.
+fn read_runtime() -> Option<(u16, String)> {
+    let raw = fs::read_to_string(runtime_file()).ok()?;
+    let v: serde_json::Value = serde_json::from_str(&raw).ok()?;
+    let port = v.get("port")?.as_u64()? as u16;
+    let token = v.get("token")?.as_str()?.to_string();
+    Some((port, token))
+}
+
+fn main() {
+    tauri::Builder::default()
+        .setup(|app| {
+            let handle = app.handle().clone();
+            // Poll for the Bridge runtime file (operator/CLI launches `aiwg cockpit`),
+            // then open the window at the Bridge UI with the token.
+            thread::spawn(move || {
+                for _ in 0..100 {
+                    if let Some((port, token)) = read_runtime() {
+                        let url = format!("http://127.0.0.1:{port}/?token={token}");
+                        if let Ok(parsed) = url.parse() {
+                            let _ = WebviewWindowBuilder::new(&handle, "main", WebviewUrl::External(parsed))
+                                .title("AIWG Cockpit")
+                                .inner_size(1100.0, 760.0)
+                                .build();
+                        }
+                        return;
+                    }
+                    thread::sleep(Duration::from_millis(150));
+                }
+            });
+            Ok(())
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running AIWG Cockpit");
+}

package/desktop/src-tauri/tauri.conf.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "AIWG Cockpit",
+  "version": "0.0.0",
+  "identifier": "io.aiwg.cockpit",
+  "build": {
+    "frontendDist": "../frontend"
+  },
+  "app": {
+    "withGlobalTauri": false,
+    "security": {
+      "csp": "default-src 'none'; frame-src http://127.0.0.1:* http://localhost:*; style-src 'unsafe-inline'"
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "icon": ["icons/icon.png"]
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@aiwg/cockpit",
+  "version": "2026.6.3",
+  "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",
+  "bin": {
+    "aiwg-cockpit": "bridge/src/server.mjs"
+  },
+  "files": [
+    "README.md",
+    "bridge/",
+    "contrib/",
+    "runtime-docs/",
+    "shell-core/",
+    "web/dist/",
+    "web/index.html",
+    "web/src/",
+    "web/package.json",
+    "vscode/",
+    "desktop/README.md",
+    "desktop/src-tauri/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "workspaces": [
+    "mock-executor",
+    "bridge",
+    "vscode",
+    "desktop",
+    "web"
+  ],
+  "scripts": {
+    "start:bridge": "node bridge/src/server.mjs",
+    "dev": "bash scripts/cockpit-dev.sh",
+    "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",
+    "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",
+    "check": "npm run build:web && npm run test:web && npm run test"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/runtime-docs/README.md

@@ -0,0 +1,38 @@
+# Cockpit runtime directory — `~/.aiwg/cockpit/runtime/`
+
+The Cockpit installs **globally** (one tool at `~/`), and the operator sets the
+working directories that agent instances launch from. Per-launch runtime state for
+the local control surface lives here.
+
+## What lands here
+
+| File | Written by | Mode | Contents |
+|---|---|---|---|
+| `bridge.json` | the Bridge on launch | `0600` | `{ token, port, pid, started_at }` — the per-launch handshake every shell reads |
+
+The directory itself is `0700`. The Bridge **rewrites** `bridge.json` on each launch
+(the token is per-launch, not persistent).
+
+## How the shells use it
+
+Every shell (browser, VS Code, Tauri) resolves the Bridge the same way — see
+`apps/cockpit/shell-core/runtime.mjs`:
+
+1. read `bridge.json` → `{ token, port }`
+2. wait for `http://127.0.0.1:<port>/healthz`
+3. load the UI at `http://127.0.0.1:<port>/?token=<token>`
+
+## Security
+
+- `bridge.json` holds **only the overlay's own per-launch token** — never a provider
+  or stack credential (verified by `apps/cockpit/poc/security-checks.mjs`, property I1).
+- `token` gates every `/api/*` call (constant-time bearer check); `tenant_id` elsewhere
+  is a **routing** token, never authentication.
+- OS-keychain storage of the token is the platform-specific hardening follow-up
+  (roctinam/aiwg#1595); the `0600` file is the cross-platform handshake.
+
+## Launch-cwd model
+
+The Bridge runs on `127.0.0.1`; agent instances launch from operator-set working
+directories (not the install root). Runtime-level operator docs (this directory) are
+distinct from the install (`$AIWG_ROOT`) and from project artifacts (`.aiwg/`).

package/shell-core/runtime.mjs

@@ -0,0 +1,45 @@
+// Shell-core: the handshake every Cockpit shell (VS Code, Tauri, browser) shares.
+// The Bridge writes ~/.aiwg/cockpit/runtime/bridge.json (mode 600) on launch with
+// { token, port }. A shell reads it, waits for liveness, and loads the Bridge UI at
+// <url>/?token=<token>. Control plane is the gated Bridge API; data plane (pty) is
+// the executor URL the Bridge issues. This module is the one source of that contract.
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const RUNTIME_FILE = join(homedir(), '.aiwg', 'cockpit', 'runtime', 'bridge.json');
+
+/** Read the per-launch Bridge connection (token, port, url). Throws if not launched. */
+export async function readRuntime(file = RUNTIME_FILE) {
+  const r = JSON.parse(await readFile(file, 'utf8'));
+  if (!r.token || !r.port) throw new Error(`runtime file ${file} missing token/port`);
+  return { ...r, url: `http://127.0.0.1:${r.port}` };
+}
+
+/** Resolve + wait for the Bridge to be reachable; returns { token, port, url }.
+ *  Polls both the runtime file (it may not exist yet) and liveness. */
+export async function connect({ timeoutMs = 5000, file = RUNTIME_FILE } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      const rt = await readRuntime(file);
+      const live = await fetch(`${rt.url}/healthz`);
+      if (live.ok) {
+        const authed = await api(rt, '/api/health');
+        if (authed.ok) return rt;
+      }
+    } catch { /* file missing or Bridge not up yet */ }
+    if (Date.now() > deadline) throw new Error(`Bridge not reachable (runtime ${file})`);
+    await new Promise((r) => setTimeout(r, 100));
+  }
+}
+
+/** The webview URL a shell loads — Bridge UI with the token on the query string. */
+export function webviewUrl(rt) {
+  return `${rt.url}/?token=${encodeURIComponent(rt.token)}`;
+}
+
+/** Authed fetch against the Bridge control surface, for shells that call the API directly. */
+export function api(rt, path, opts = {}) {
+  return fetch(rt.url + path, { ...opts, headers: { ...(opts.headers || {}), authorization: `Bearer ${rt.token}` } });
+}

package/shell-core/smoke.mjs

@@ -0,0 +1,36 @@
+// Shell handshake smoke: launch the real Bridge CLI (which writes the runtime token
+// file), then drive the shell-core contract both VS Code and Tauri rely on —
+// resolve token+url, confirm liveness, authed call works, unauthed is rejected.
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BRIDGE = fileURLToPath(new URL('../bridge/src/server.mjs', import.meta.url));
+const PORT = 8147;
+const home = await mkdtemp(join(tmpdir(), 'cockpit-shell-smoke-'));
+process.env.HOME = home;
+
+const { connect, webviewUrl, api } = await import('./runtime.mjs');
+const child = spawn(process.execPath, [BRIDGE], {
+  env: { ...process.env, HOME: home, PORT: String(PORT), AIWG_COCKPIT_EXECUTOR_URL: 'http://127.0.0.1:1' }, // no live executor needed for the handshake
+  stdio: 'ignore',
+});
+
+try {
+  const rt = await connect({ timeoutMs: 6000 });   // reads ~/.aiwg/cockpit/runtime/bridge.json + waits for /healthz
+  assert.equal(rt.port, PORT, 'runtime port matches the launched Bridge');
+  assert.ok(rt.token && rt.token.length >= 32, 'runtime carries a per-launch token');
+  assert.match(webviewUrl(rt), /\/\?token=/, 'webview url carries the token');
+
+  // the shell handshake: authed call succeeds, unauthed is gated
+  assert.equal((await api(rt, '/api/health')).status, 200, 'authed /api/health 200');
+  assert.equal((await fetch(rt.url + '/api/health')).status, 401, 'unauthed /api/health 401');
+
+  console.log(`SMOKE OK — shell handshake: runtime file -> token+url (:${rt.port}) -> authed Bridge, gate enforced`);
+} finally {
+  child.kill();
+  await rm(home, { recursive: true, force: true });
+}

package/vscode/README.md

@@ -0,0 +1,25 @@
+# AIWG Cockpit — VS Code shell
+
+Hosts the registry-bound Cockpit UI inside a VS Code webview and surfaces
+contributed actions as command-palette entries. No build step (CommonJS
+`extension.js`); the same Bridge core as the desktop app and browser.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| **AIWG Cockpit: Open** | Opens the Cockpit UI in a webview (reads the Bridge runtime token, loads `http://127.0.0.1:PORT/?token=…`). |
+| **AIWG Cockpit: Audit Issues** | Runs the contributed `audit-issues` action through the Bridge and prints the result to an output channel. |
+
+## Run it
+
+1. Launch the Bridge: `aiwg cockpit` (or, in-repo, `node apps/cockpit/bridge/src/server.mjs`). It writes `~/.aiwg/cockpit/runtime/bridge.json` (token + port, mode 600).
+2. In VS Code: **F5** (Extension Development Host) from this folder, or install the packaged `.vsix`.
+3. Run **AIWG Cockpit: Open** from the command palette.
+
+If the Bridge isn't running, the commands show a hint to start it — the shell
+never replaces the CLI; it fronts it.
+
+## Settings
+
+- `aiwg-cockpit.bridgeRuntimeFile` — override the runtime file path (default `~/.aiwg/cockpit/runtime/bridge.json`).