@aiwg/cockpit 2026.6.10 → 2026.6.11

package/README.md

@@ -108,7 +108,7 @@ Cockpit package is installed under `~/.aiwg/cockpit/package`.
 
 ```
 operator / CLI:  aiwg cockpit
-       │  spawns the Bridge; writes ~/.aiwg/cockpit/runtime/bridge.json (token+port, 0600)
+       │  spawns the Bridge; writes OS keychain token + ~/.aiwg/cockpit/runtime/bridge.json (0600)
        ▼
 ┌─────────────────────────────────────────────────────────────┐
 │ Bridge (127.0.0.1, token-gated /api)                         │
@@ -228,7 +228,7 @@ React app token-injected, falling back to a legacy page when no build is present
 | `web/` | React 19 + Vite + TS UI (the surfaces above) |
 | `mock-executor/` | **automated-test-only** wire-faithful agentic-sandbox A2A v2 stand-in (conformance 33/0/17). The Bridge refuses it for human launches (needs `AIWG_COCKPIT_ALLOW_MOCK_EXECUTOR=1`); a contract guard (#1636) pins its legacy `/admin/{running,approvals,cost}` divergence from real v2 so new drift fails CI. |
 | `bridge/` | the registry-bound control-plane server + static serving |
-| `shell-core/` | the cross-shell handshake (runtime token → connect) |
+| `shell-core/` | the cross-shell handshake (runtime token reference or fallback token → connect) |
 | `vscode/` · `desktop/` | VS Code extension + Tauri shells over the same Bridge |
 | `contrib/` | declarative UI contributions + schema (actions inject commands) |
 | `poc/` | Iteration-1 risk-gate PoCs (kill-bridge isolation, security) |
@@ -317,11 +317,12 @@ injection can mutate target data, set
 managed PTY session on the same target, observes it, drives a shell command via
 `pty.session_input`, waits for `AIWG_COCKPIT_MUTATION_OK`, then reads the file
 from the test runner and verifies the exact content.
-The matrix report records each target family independently (`matrix host`,
-`matrix container`, `matrix vm`) with the instance, runtime family, selected
-session backend, provider, discovery expectation, and exact failure reason; the
-test aggregates those records and fails only after all three target families have
-been attempted. Mock-only success does not satisfy this gate;
+The matrix report records each target family independently (`provision host`,
+`matrix host`, `provision container`, `matrix container`, `provision vm`,
+`matrix vm`) with the instance, runtime family, selected session backend,
+provider, discovery expectation, running-projection count, report artifact paths,
+and exact failure reason; the test aggregates those records and fails only after
+all requested target families have been attempted. Mock-only success does not satisfy this gate;
 `AIWG_COCKPIT_LIVE_ALLOW_MOCK_MATRIX=1` exists only for harness development.
 
 To prove the launch path itself, set `AIWG_COCKPIT_LIVE_PROVISION=1`. In this

package/bridge/src/public/index.html

@@ -148,7 +148,11 @@
     const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
     // per-launch token injected by the Bridge for the gated control surface
     const TOKEN = window.__COCKPIT_TOKEN__ || '';
-    const api = (u, o = {}) => fetch(u, { ...o, headers: { ...(o.headers || {}), authorization: 'Bearer ' + TOKEN } });
+    const api = (u, o = {}) => {
+      const method = String(o.method || 'GET').toUpperCase();
+      const csrf = ['GET', 'HEAD', 'OPTIONS'].includes(method) ? {} : { 'x-cockpit-csrf': TOKEN };
+      return fetch(u, { ...o, headers: { ...(o.headers || {}), ...csrf, authorization: 'Bearer ' + TOKEN } });
+    };
 
     // --- Inventory ---
     async function loadInventory() {
@@ -379,7 +383,7 @@
       }
     }
 
-    document.getElementById('refresh').addEventListener('click', () => {
+    function refreshActive() {
       const active = tabs.find((t) => t.getAttribute('aria-selected') === 'true').id;
       if (active === 'tab-inventory') loadInventory();
       else if (active === 'tab-running') loadRunning();
@@ -387,7 +391,12 @@
       else if (active === 'tab-approvals') loadApprovals();
       else if (active === 'tab-actions') loadActions();
       else discover();
-    });
+    }
+    document.getElementById('refresh').addEventListener('click', refreshActive);
+    if ('EventSource' in window && TOKEN) {
+      const events = new EventSource('/api/events?token=' + encodeURIComponent(TOKEN));
+      events.addEventListener('cockpit.refresh', refreshActive);
+    }
 
     loadInventory();
   </script>

package/bridge/src/server.mjs

@@ -13,6 +13,7 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, basename, extname, resolve, sep } from 'node:path';
+import { storeCockpitToken } from '../../shell-core/keychain.mjs';
 
 const __dir = dirname(fileURLToPath(import.meta.url));
 // Primary seam for roctinam/aiwg#1589: Cockpit talks to a real agentic-sandbox
@@ -52,11 +53,47 @@ function authed(req, url, token) {
   try { return timingSafeEqual(Buffer.from(presented), Buffer.from(token)); } catch { return false; }
 }
 
+function isLocalHostName(hostname) {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]';
+}
+
+function validBrowserOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  try {
+    const o = new URL(String(origin));
+    const host = new URL(`http://${req.headers.host ?? 'localhost'}`);
+    return ['http:', 'https:'].includes(o.protocol) &&
+      isLocalHostName(o.hostname) &&
+      isLocalHostName(host.hostname) &&
+      (!o.port || !host.port || o.port === host.port);
+  } catch {
+    return false;
+  }
+}
+
+function validCsrf(req, token) {
+  if (['GET', 'HEAD', 'OPTIONS'].includes(req.method ?? 'GET')) return true;
+  if (!req.headers.origin) return true;
+  const csrf = String(req.headers['x-cockpit-csrf'] ?? '');
+  if (csrf.length !== token.length) return false;
+  try { return timingSafeEqual(Buffer.from(csrf), Buffer.from(token)); } catch { return false; }
+}
+
 /** Persist the per-launch token for the desktop/VS Code shells to read (mode 600). */
 async function writeRuntimeToken({ token, port, pid }) {
   await mkdir(RUNTIME_DIR, { recursive: true, mode: 0o700 });
   const file = join(RUNTIME_DIR, 'bridge.json');
-  await writeFile(file, JSON.stringify({ token, port, pid, started_at: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  const runtime = { token, port, pid, started_at: new Date().toISOString(), keychain_backed: false };
+  try {
+    runtime.token_ref = await storeCockpitToken(token, `bridge-${pid}`);
+    runtime.keychain_backed = true;
+    if (process.env.AIWG_COCKPIT_KEYCHAIN_STRICT === '1') delete runtime.token;
+  } catch (e) {
+    runtime.keychain_error = String(e?.message ?? e);
+    if (process.env.AIWG_COCKPIT_REQUIRE_KEYCHAIN === '1') throw e;
+  }
+  await writeFile(file, JSON.stringify(runtime, null, 2), { mode: 0o600 });
   await chmod(file, 0o600);
   return file;
 }
@@ -751,36 +788,129 @@ async function getRunning(executorUrl) {
   };
 }
 
+function textFromParts(parts) {
+  if (!Array.isArray(parts)) return '';
+  return parts
+    .map((p) => p?.text ?? p?.content ?? p?.value ?? '')
+    .filter((p) => typeof p === 'string' && p.trim())
+    .join('\n');
+}
+
+function approvalPromptFromTask(task) {
+  const meta = task.metadata ?? {};
+  const status = typeof task.status === 'object' ? task.status : {};
+  const prompt = [
+    meta.hitl_prompt?.prompt,
+    meta.hitlPrompt?.prompt,
+    meta.approval?.prompt,
+    meta.prompt,
+    status.message,
+    status.prompt,
+    textFromParts(task.artifacts?.flatMap((a) => a.parts ?? [])),
+    textFromParts(task.history?.at?.(-1)?.parts),
+  ].find((v) => typeof v === 'string' && v.trim());
+  return String(prompt || 'Human input required');
+}
+
+function approvalFromTask(instance, task) {
+  const state = taskState(task);
+  const meta = task.metadata ?? {};
+  const hasHitlPrompt = meta.hitl_prompt || meta.hitlPrompt || meta.approval || meta['hitl-prompt/v1'];
+  if (state !== 'input-required' && !hasHitlPrompt) return null;
+  const taskId = taskIdOf(task);
+  if (!taskId) return null;
+  return {
+    id: `${instance.id}::${taskId}`,
+    instance_id: instance.id,
+    task_id: taskId,
+    prompt: approvalPromptFromTask(task),
+    risk: meta.risk ?? meta.approval?.risk ?? meta.hitl_prompt?.risk ?? 'unknown',
+    created_at: task.created_at ?? task.createdAt ?? task.status?.timestamp ?? task.metadata?.created_at,
+    status: state === 'input-required' ? 'pending' : state,
+    tenant: taskTenantOf(task),
+    derived: 'a2a input-required task',
+  };
+}
+
 /**
- * Pending HITL approvals (the unified approval inbox). The real agentic-sandbox
- * v2 admin surface has no /approvals route — HITL prompts arrive via A2A
- * `input-required` / `hitl-prompt/v1`. Deriving the inbox (and routing the
- * decision back to the task) from that surface is the remaining half of the v2
- * work (#1639 follow-up, with #1565); until then degrade to an empty inbox
- * rather than 404 so the operator Home view stays usable against a real executor.
+ * Pending HITL approvals (the unified approval inbox) derived from real A2A
+ * `input-required` / `hitl-prompt/v1` task surfaces. The real agentic-sandbox
+ * v2 admin router has no approvals queue, so this deliberately does not probe
+ * `/admin/approvals`.
  */
 async function getApprovals(executorUrl, status) {
-  let body;
-  try {
-    ({ body } = await fetchJsonFirst([
-      `${executorUrl}/admin/approvals?status=${encodeURIComponent(status)}`,
-      `${executorUrl}/api/v2/admin/approvals?status=${encodeURIComponent(status)}`,
-    ]));
-  } catch {
-    return {
-      source: executorUrl,
-      fetched_at: new Date().toISOString(),
-      approvals: [],
-      derived: 'executor exposes no admin approvals endpoint',
-    };
-  }
+  const instances = (await getInventory(executorUrl)).instances;
+  const approvals = [];
+  await Promise.all(
+    instances.filter((i) => i.state === 'running').map(async (inst) => {
+      let tasks;
+      try { tasks = await listInstanceTasks(executorUrl, inst.id); } catch { return; }
+      for (const t of tasks) {
+        const approval = approvalFromTask(inst, t);
+        if (!approval) continue;
+        if (status && status !== 'all' && approval.status !== status) continue;
+        approvals.push(approval);
+      }
+    }),
+  );
   return {
     source: executorUrl,
     fetched_at: new Date().toISOString(),
-    approvals: asArrayFromEnvelope(body, ['approvals', 'items', 'data']),
+    approvals,
+    derived: 'per-instance A2A input-required tasks',
   };
 }
 
+async function respondApproval(executorUrl, approvalId, decision) {
+  if (!['approve', 'deny'].includes(decision)) return { status: 400, body: { error: 'decision must be approve|deny' } };
+  const [instanceId, taskId] = String(approvalId).split('::');
+  if (!instanceId || !taskId) return { status: 400, body: { error: 'invalid_approval_id' } };
+  const agentId = await resolveSessionAgentId(executorUrl, instanceId);
+  const message = {
+    message: {
+      messageId: `cockpit-hitl-${Date.now()}`,
+      role: 'user',
+      taskId,
+      contextId: taskId,
+      parts: [{ kind: 'text', text: decision }],
+      metadata: { hitl_response: { decision }, approval_decision: decision },
+    },
+  };
+  const response = JSON.stringify({ decision, response: message.message });
+  const candidates = unique([agentId, instanceId]).flatMap((id) => [
+    {
+      target: `${executorUrl}/api/v1/agents/${encodeURIComponent(id)}/tasks/${encodeURIComponent(taskId)}:respond`,
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: response,
+    },
+    {
+      target: `${executorUrl}/agents/${encodeURIComponent(id)}/tasks/${encodeURIComponent(taskId)}:respond`,
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: response,
+    },
+    {
+      target: `${executorUrl}/api/v1/agents/${encodeURIComponent(id)}/messages:send`,
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(message),
+    },
+    {
+      target: `${executorUrl}/agents/${encodeURIComponent(id)}/messages:send`,
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(message),
+    },
+  ]);
+  try {
+    const { status, body } = await fetchJsonFirst(candidates);
+    return { status, body };
+  } catch (e) {
+    return { status: 409, body: { error: 'approval_response_failed', detail: String(e?.message ?? e) } };
+  }
+}
+
 /**
  * Sessions for one instance, each with a direct attach_url. Control plane (this
  * list) goes through the Bridge; the data plane (the pty stream) connects direct
@@ -864,10 +994,16 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
     try {
       // unauthenticated liveness probe (no /api/ prefix) — for the shell to wait on
       if (url.pathname === '/healthz') return json(res, 200, { status: 'ok' });
+      if (url.pathname.startsWith('/api/') && !validBrowserOrigin(req)) {
+        return json(res, 403, { error: 'forbidden_origin' });
+      }
       // gate the control surface: per-launch bearer token on every /api/ call
       if (url.pathname.startsWith('/api/') && !authed(req, url, TOKEN)) {
         return json(res, 401, { error: 'unauthorized', detail: 'missing or invalid cockpit token' });
       }
+      if (url.pathname.startsWith('/api/') && !validCsrf(req, TOKEN)) {
+        return json(res, 403, { error: 'csrf_required' });
+      }
       if (url.pathname.startsWith('/api/')) {
         try {
           await assertRealExecutor(upstreamUrl, allowMockExecutor);
@@ -875,6 +1011,21 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
           return json(res, 502, { error: err.code ?? 'executor_refused', message: String(err?.message ?? err) });
         }
       }
+      if (url.pathname === '/api/events' && req.method === 'GET') {
+        res.writeHead(200, {
+          'content-type': 'text/event-stream',
+          'cache-control': 'no-cache',
+          connection: 'keep-alive',
+        });
+        const emit = (reason = 'heartbeat') => {
+          res.write(`event: cockpit.refresh\n`);
+          res.write(`data: ${JSON.stringify({ reason, ts: new Date().toISOString() })}\n\n`);
+        };
+        emit('connected');
+        const timer = setInterval(() => emit(), 5_000);
+        req.on('close', () => clearInterval(timer));
+        return;
+      }
       if (url.pathname === '/api/inventory') return json(res, 200, await getInventory(upstreamUrl));
       if (url.pathname === '/api/running') return json(res, 200, await getRunning(upstreamUrl));
       if (url.pathname === '/api/loadouts') return json(res, 200, await getLoadouts(upstreamUrl));
@@ -1066,8 +1217,10 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
       // --- approval inbox (UC-009) + cost (UC-010) ---
       if (url.pathname === '/api/approvals' && req.method === 'GET')
         return json(res, 200, await getApprovals(upstreamUrl, url.searchParams.get('status') || 'pending'));
-      if ((m = url.pathname.match(/^\/api\/approvals\/([^/]+)$/)) && req.method === 'POST')
-        return proxy(res, 'POST', `${upstreamUrl}/admin/approvals/${encodeURIComponent(m[1])}?decision=${encodeURIComponent(url.searchParams.get('decision') || '')}`);
+      if ((m = url.pathname.match(/^\/api\/approvals\/([^/]+)$/)) && req.method === 'POST') {
+        const { status, body } = await respondApproval(upstreamUrl, decodeURIComponent(m[1]), url.searchParams.get('decision') || '');
+        return json(res, status, body);
+      }
       if (url.pathname === '/api/cost' && req.method === 'GET')
         return proxy(res, 'GET', `${upstreamUrl}/admin/cost`);
 
@@ -1079,7 +1232,11 @@ export function createBridge({ executorUrl = EXECUTOR_URL, allowMockExecutor = A
         // Inject the per-launch token so the same-origin app can call the gated API.
         const html = raw.replace('</head>', `<script>window.__COCKPIT_TOKEN__=${JSON.stringify(TOKEN)}</script>\n</head>`);
         // never cache the shell — it must always reference the latest hashed bundle
-        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' });
+        res.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          'cache-control': 'no-cache',
+          'set-cookie': `cockpit_csrf=${TOKEN}; Path=/; SameSite=Strict`,
+        });
         return res.end(html);
       }
       // static assets from the built web app (e.g. /assets/*.js, *.css)

package/bridge/src/smoke.mjs

@@ -106,9 +106,11 @@ try {
 
   // 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');
+  assert.equal(pend.derived, 'per-instance A2A input-required tasks', 'approvals derive from A2A tasks');
+  assert.ok(pend.approvals.length >= 1, 'pending approvals seeded');
+  const approvalId = pend.approvals[0].id;
+  const apr = await (await f(`/api/approvals/${encodeURIComponent(approvalId)}?decision=approve`, { method: 'POST' })).json();
+  assert.equal(apr.status.state, 'completed', 'approval response completes the task');
   const pend2 = await (await f('/api/approvals?status=pending')).json();
   assert.equal(pend2.approvals.length, pend.approvals.length - 1, 'approved item leaves the queue');
 

package/desktop/README.md

@@ -3,14 +3,14 @@
 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.
+runtime handshake file (`~/.aiwg/cockpit/runtime/bridge.json`) and opens a window
+at the Bridge UI with the resolved per-launch token on the query string.
 
 ## Architecture
 
 ```
 operator/CLI: aiwg cockpit
-      │  (spawns the Bridge; writes runtime/bridge.json mode 600)
+      │  (spawns the Bridge; writes OS keychain token + runtime/bridge.json mode 600)
       ▼
 Bridge (127.0.0.1:PORT, token-gated /api) ── proxies ──▶ agentic-sandbox executor
       ▲
@@ -38,5 +38,6 @@ set needed by Tauri. `cargo tauri build` has been verified on Linux to produce
 ## 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).
+`apps/cockpit/shell-core/runtime.mjs`). The Bridge stores the per-launch token in
+the OS credential backend when available and records a `token_ref`; `bridge.json`
+is mode `600` and records explicit fallback evidence when no backend is usable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cockpit",
-  "version": "2026.6.10",
+  "version": "2026.6.11",
   "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/runtime-docs/README.md

@@ -8,7 +8,7 @@ the local control surface lives 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 |
+| `bridge.json` | the Bridge on launch | `0600` | `{ token_ref, port, pid, started_at, keychain_backed }` when OS-keychain storage succeeds; otherwise `{ token, port, pid, started_at, keychain_backed:false, keychain_error }` |
 
 The directory itself is `0700`. The Bridge **rewrites** `bridge.json` on each launch
 (the token is per-launch, not persistent).
@@ -18,18 +18,26 @@ The directory itself is `0700`. The Bridge **rewrites** `bridge.json` on each la
 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>`
+1. read `bridge.json` → `{ token_ref, port }` or fallback `{ token, port }`
+2. resolve `token_ref` through `apps/cockpit/shell-core/keychain.mjs` when present
+3. wait for `http://127.0.0.1:<port>/healthz`
+4. 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).
+- 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`).
+- `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
+  `AIWG_COCKPIT_KEYCHAIN_STRICT=1` to omit the inline token when keychain storage
+  succeeds; set `AIWG_COCKPIT_REQUIRE_KEYCHAIN=1` to fail Bridge launch if no OS
+  credential backend is usable.
 - `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.
+- Browser-origin `/api/*` calls are localhost-origin checked, and state-changing
+  browser calls must include the CSRF double-submit header emitted by the web clients.
 
 ## Launch-cwd model
 

package/shell-core/keychain.mjs

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+
+const SERVICE = 'aiwg-cockpit-bridge';
+const FOLDER = 'AIWG Cockpit';
+const WALLET = process.env.AIWG_COCKPIT_KWALLET || 'kdewallet';
+
+function collect(cmd, args, input, timeoutMs = 2_000) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      p.kill();
+      reject(new Error(`${cmd} timed out`));
+    }, timeoutMs);
+    p.stdout.on('data', (d) => { stdout += d; });
+    p.stderr.on('data', (d) => { stderr += d; });
+    p.once('error', (err) => { clearTimeout(timer); reject(err); });
+    p.once('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve(stdout);
+      else reject(new Error(stderr.trim() || `${cmd} exit ${code}`));
+    });
+    if (input !== undefined) p.stdin.end(input);
+    else p.stdin.end();
+  });
+}
+
+async function canRun(cmd) {
+  try {
+    if (process.platform === 'win32') await collect('where', [cmd]);
+    else await collect('sh', ['-lc', `command -v ${cmd}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function storeCockpitToken(token, account = `bridge-${process.pid}`) {
+  const os = platform();
+  if (os === 'darwin' && await canRun('security')) {
+    await collect('security', ['add-generic-password', '-a', account, '-s', SERVICE, '-w', token, '-U']);
+    return { backend: 'macos-keychain', service: SERVICE, account };
+  }
+  if (os === 'win32' && await canRun('cmdkey')) {
+    const target = `${SERVICE}:${account}`;
+    await collect('cmdkey', [`/generic:${target}`, `/user:${account}`, `/pass:${token}`]);
+    return { backend: 'windows-credential-manager', service: SERVICE, account, target };
+  }
+  if (await canRun('secret-tool')) {
+    await collect('secret-tool', ['store', '--label', 'AIWG Cockpit Bridge', 'service', SERVICE, 'account', account], token);
+    return { backend: 'libsecret', service: SERVICE, account };
+  }
+  if (process.env.AIWG_COCKPIT_ENABLE_KWALLET === '1' && await canRun('kwallet-query')) {
+    await collect('kwallet-query', ['-f', FOLDER, '-w', account, WALLET], token);
+    return { backend: 'kwallet', service: SERVICE, account, wallet: WALLET, folder: FOLDER };
+  }
+  throw new Error('no supported OS keychain command found');
+}
+
+export async function readCockpitToken(ref) {
+  if (!ref || typeof ref !== 'object') throw new Error('missing keychain reference');
+  if (ref.backend === 'macos-keychain') {
+    return (await collect('security', ['find-generic-password', '-a', ref.account, '-s', ref.service || SERVICE, '-w'])).trim();
+  }
+  if (ref.backend === 'windows-credential-manager') {
+    throw new Error('Windows Credential Manager read requires the shell-provided runtime token until native shell integration lands');
+  }
+  if (ref.backend === 'libsecret') {
+    return (await collect('secret-tool', ['lookup', 'service', ref.service || SERVICE, 'account', ref.account])).trim();
+  }
+  if (ref.backend === 'kwallet') {
+    return (await collect('kwallet-query', ['-f', ref.folder || FOLDER, '-r', ref.account, ref.wallet || WALLET])).trim();
+  }
+  throw new Error(`unsupported keychain backend: ${ref.backend}`);
+}

package/shell-core/runtime.mjs

@@ -1,19 +1,22 @@
 // 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
+// { token_ref, port } when OS-keychain storage is available, else { token, port }.
+// A shell resolves the token, 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';
+import { readCockpitToken } from './keychain.mjs';
 
 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}` };
+  const token = r.token || await readCockpitToken(r.token_ref);
+  if (!token || !r.port) throw new Error(`runtime file ${file} missing token/port`);
+  return { ...r, token, url: `http://127.0.0.1:${r.port}` };
 }
 
 /** Resolve + wait for the Bridge to be reachable; returns { token, port, url }.

package/vscode/README.md

@@ -8,12 +8,12 @@ contributed actions as command-palette entries. No build step (CommonJS
 
 | 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. |
+| **AIWG Cockpit: Open** | Opens the Cockpit UI in a webview (reads the Bridge runtime handshake, resolves the token, loads `http://127.0.0.1:PORT/?token=…`). |
+| **AIWG Cockpit: Audit Issues** | Opens Cockpit on the contributed Actions view; the action injects into an agentic session instead of running from the extension. |
 
 ## 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).
+1. Launch the Bridge: `aiwg cockpit` (or, in-repo, `node apps/cockpit/bridge/src/server.mjs`). It writes `~/.aiwg/cockpit/runtime/bridge.json` (token reference + port when OS-keychain storage is available, otherwise 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.
 

package/vscode/extension.js

@@ -7,18 +7,34 @@ const vscode = require('vscode');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const cp = require('child_process');
 
 function runtimeFile() {
   const override = vscode.workspace.getConfiguration('aiwg-cockpit').get('bridgeRuntimeFile');
   return override && override.length ? override : path.join(os.homedir(), '.aiwg', 'cockpit', 'runtime', 'bridge.json');
 }
 
+function readTokenRef(ref) {
+  if (!ref || !ref.backend) return '';
+  if (ref.backend === 'macos-keychain') {
+    return cp.execFileSync('security', ['find-generic-password', '-a', ref.account, '-s', ref.service || 'aiwg-cockpit-bridge', '-w'], { encoding: 'utf8' }).trim();
+  }
+  if (ref.backend === 'libsecret') {
+    return cp.execFileSync('secret-tool', ['lookup', 'service', ref.service || 'aiwg-cockpit-bridge', 'account', ref.account], { encoding: 'utf8' }).trim();
+  }
+  if (ref.backend === 'kwallet') {
+    return cp.execFileSync('kwallet-query', ['-f', ref.folder || 'AIWG Cockpit', '-r', ref.account, ref.wallet || 'kdewallet'], { encoding: 'utf8' }).trim();
+  }
+  throw new Error(`Unsupported Cockpit keychain backend: ${ref.backend}`);
+}
+
 /** Read the Bridge connection + confirm liveness; throws with a friendly hint if down. */
 async function ensureRuntime() {
   let rt;
   try {
     const r = JSON.parse(fs.readFileSync(runtimeFile(), 'utf8'));
-    rt = { ...r, url: `http://127.0.0.1:${r.port}` };
+    const token = r.token || readTokenRef(r.token_ref);
+    rt = { ...r, token, url: `http://127.0.0.1:${r.port}` };
   } catch {
     throw new Error('AIWG Cockpit Bridge not found. Start it with `aiwg cockpit` (or `node apps/cockpit/bridge/src/server.mjs`) and retry.');
   }
@@ -42,14 +58,7 @@ function activate(context) {
     vscode.commands.registerCommand('aiwg-cockpit.auditIssues', async () => {
       let rt;
       try { rt = await ensureRuntime(); } catch (e) { return vscode.window.showWarningMessage(e.message); }
-      const out = vscode.window.createOutputChannel('AIWG Cockpit');
-      out.show(true);
-      out.appendLine('Running contributed action: audit-issues…');
-      try {
-        const r = await fetch(`${rt.url}/api/actions/audit-issues/run`, { method: 'POST', headers: { authorization: `Bearer ${rt.token}` } });
-        const j = await r.json();
-        out.appendLine(j.output || JSON.stringify(j, null, 2));
-      } catch (e) { out.appendLine('Error: ' + e.message); }
+      vscode.env.openExternal(vscode.Uri.parse(`${rt.url}/?token=${encodeURIComponent(rt.token)}#actions`));
     }),
   );
 }

package/web/src/App.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useState, type ReactNode } from 'react';
 import { useSession } from './useSession';
-import { api } from './api';
+import { api, TOKEN } from './api';
 import type { Approval, Instance, ResponseNeeded } from './types';
 import { Welcome } from './components/Welcome';
 import { Inventory } from './components/Inventory';
@@ -37,7 +37,10 @@ interface ChromeStatus {
 const sleep = (ms: number) => new Promise((resolve) => window.setTimeout(resolve, ms));
 
 export function App() {
-  const [tab, setTab] = useState<TabId>('welcome');
+  const [tab, setTab] = useState<TabId>(() => {
+    const hash = window.location.hash.replace(/^#/, '');
+    return TABS.some((t) => t.id === hash) ? hash as TabId : 'welcome';
+  });
   const session = useSession();
   const [composer, setComposer] = useState('');
   const [chrome, setChrome] = useState<ChromeStatus | null>(null);
@@ -82,6 +85,23 @@ export function App() {
     return () => { cancelled = true; window.clearInterval(timer); };
   }, [session.responseNeeded.needed, refreshTick]);
 
+  useEffect(() => {
+    if (typeof EventSource === 'undefined' || !TOKEN) return;
+    const events = new EventSource(`/api/events?token=${encodeURIComponent(TOKEN)}`);
+    events.addEventListener('cockpit.refresh', () => setRefreshTick((t) => t + 1));
+    events.onerror = () => undefined;
+    return () => events.close();
+  }, []);
+
+  useEffect(() => {
+    const onHash = () => {
+      const hash = window.location.hash.replace(/^#/, '');
+      if (TABS.some((t) => t.id === hash)) setTab(hash as TabId);
+    };
+    window.addEventListener('hashchange', onHash);
+    return () => window.removeEventListener('hashchange', onHash);
+  }, []);
+
   // The onboarding primary verb: open the start-session picker (#1640/#1641). The picker
   // is the single home for both this dashboard verb and the Sessions-tab Start button —
   // neither launches blind with defaults, neither silently clobbers an attached session,
@@ -144,18 +164,18 @@ export function App() {
       <main>
         <Panel id="welcome" tab={tab}><Welcome onStartSession={() => requestStart()} onLaunchInstance={() => setLaunchOpen(true)} goTo={(t) => setTab(t as TabId)} /></Panel>
         <Panel id="inventory" tab={tab}><Inventory onStartSession={requestStart} onLaunchInstance={() => setLaunchOpen(true)} /></Panel>
-        <Panel id="running" tab={tab}><Running /></Panel>
+        <Panel id="running" tab={tab}><Running refreshTick={refreshTick} /></Panel>
         {/* Sessions stays mounted so the WebSocket survives tab switches */}
         <section id="panel-sessions" role="tabpanel" aria-labelledby="tab-sessions" hidden={tab !== 'sessions'}>
           <Sessions session={session} composer={composer} setComposer={setComposer} onRequestStart={requestStart} />
         </section>
-        <Panel id="approvals" tab={tab}><Approvals responses={session.responseNeeded.needed ? [sessionResponse(session)] : []} goSessions={() => setTab('sessions')} /></Panel>
+        <Panel id="approvals" tab={tab}><Approvals refreshTick={refreshTick} responses={session.responseNeeded.needed ? [sessionResponse(session)] : []} goSessions={() => setTab('sessions')} /></Panel>
         <Panel id="explore" tab={tab}><Explore /></Panel>
         <Panel id="library" tab={tab}>
           <Library session={session} setComposer={setComposer} goSessions={() => setTab('sessions')} />
         </Panel>
         <Panel id="actions" tab={tab}>
-          <Actions session={session} setComposer={setComposer} goSessions={() => setTab('sessions')} />
+          <Actions refreshTick={refreshTick} session={session} setComposer={setComposer} goSessions={() => setTab('sessions')} />
         </Panel>
       </main>
       <StartSessionModal

package/web/src/api.ts

@@ -7,7 +7,11 @@ declare global {
 const TOKEN = (typeof window !== 'undefined' && window.__COCKPIT_TOKEN__) || '';
 
 export function apiRaw(path: string, opts: RequestInit = {}): Promise<Response> {
-  return fetch(path, { ...opts, headers: { ...(opts.headers || {}), authorization: `Bearer ${TOKEN}` } });
+  const method = String(opts.method || 'GET').toUpperCase();
+  const headers = new Headers(opts.headers);
+  headers.set('authorization', `Bearer ${TOKEN}`);
+  if (!['GET', 'HEAD', 'OPTIONS'].includes(method)) headers.set('x-cockpit-csrf', TOKEN);
+  return fetch(path, { ...opts, headers });
 }
 
 export async function api<T = unknown>(path: string, opts: RequestInit = {}): Promise<T> {

package/web/src/components/Actions.tsx

@@ -4,14 +4,14 @@ import type { ContribAction } from '../types';
 import type { SessionApi } from '../useSession';
 
 // Actions INJECT a command into an agentic session — the Cockpit never runs the CLI.
-export function Actions({ session, setComposer, goSessions }: { session: SessionApi; setComposer: (v: string) => void; goSessions: () => void }) {
+export function Actions({ refreshTick = 0, session, setComposer, goSessions }: { refreshTick?: number; session: SessionApi; setComposer: (v: string) => void; goSessions: () => void }) {
   const [actions, setActions] = useState<ContribAction[]>([]);
   const [err, setErr] = useState('');
   const [note, setNote] = useState('');
 
   useEffect(() => {
     api<{ actions: ContribAction[] }>('/api/contributions').then((d) => setActions(d.actions)).catch((e) => setErr((e as Error).message));
-  }, []);
+  }, [refreshTick]);
 
   const inject = (a: ContribAction) => {
     let command = a.inject.command;

package/web/src/components/Approvals.tsx

@@ -3,7 +3,7 @@ import { api } from '../api';
 import { fmtId } from '../util';
 import type { Approval, ResponseNeeded } from '../types';
 
-export function Approvals({ responses = [], goSessions }: { responses?: ResponseNeeded[]; goSessions?: () => void }) {
+export function Approvals({ refreshTick = 0, responses = [], goSessions }: { refreshTick?: number; responses?: ResponseNeeded[]; goSessions?: () => void }) {
   const [items, setItems] = useState<Approval[] | null>(null);
   const [err, setErr] = useState('');
 
@@ -11,7 +11,7 @@ export function Approvals({ responses = [], goSessions }: { responses?: Response
     api<{ approvals: Approval[] }>('/api/approvals?status=pending')
       .then((d) => { setItems(d.approvals); setErr(''); }).catch((e) => setErr((e as Error).message));
   }, []);
-  useEffect(() => { load(); }, [load]);
+  useEffect(() => { load(); }, [load, refreshTick]);
 
   const decide = (id: string, decision: 'approve' | 'deny') =>
     api(`/api/approvals/${encodeURIComponent(id)}?decision=${decision}`, { method: 'POST' })

package/web/src/components/Running.tsx

@@ -5,7 +5,7 @@ import type { RunningTask, Cost } from '../types';
 
 interface Run { count: number; running: RunningTask[] }
 
-export function Running() {
+export function Running({ refreshTick = 0 }: { refreshTick?: number }) {
   const [run, setRun] = useState<Run | null>(null);
   const [cost, setCost] = useState<Cost | null>(null);
   const [err, setErr] = useState('');
@@ -14,7 +14,7 @@ export function Running() {
     api<Run>('/api/running').then((d) => { setRun(d); setErr(''); }).catch((e) => setErr((e as Error).message));
     api<Cost>('/api/cost').then(setCost).catch(() => setCost(null));
   }, []);
-  useEffect(() => { load(); }, [load]);
+  useEffect(() => { load(); }, [load, refreshTick]);
 
   const stop = (t: RunningTask) =>
     api(`/api/tasks/${encodeURIComponent(t.instance_id)}/${encodeURIComponent(t.task_id)}/cancel`, { method: 'POST' })