@aiwg/cockpit 2026.8.3 → 2026.8.4

package/bridge/src/server.mjs

@@ -8,7 +8,7 @@
 import http from 'node:http';
 import https from 'node:https';
 import { spawn } from 'node:child_process';
-import { readFile, mkdir, writeFile, chmod, readdir, cp, rm, stat, appendFile } from 'node:fs/promises';
+import { readFile, mkdir, writeFile, rename, chmod, readdir, cp, rm, stat, appendFile } from 'node:fs/promises';
 import { existsSync, realpathSync } from 'node:fs';
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -42,7 +42,13 @@ const auditLog = () => join(auditDir(), 'events.jsonl');
 // legacy vanilla page so the Bridge works even before a web build.
 const WEB_DIST = fileURLToPath(new URL('../../web/dist', import.meta.url));
 const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.json': 'application/json', '.ico': 'image/x-icon', '.png': 'image/png', '.woff2': 'font/woff2', '.map': 'application/json' };
-const CAPABILITY_TYPES = new Set(['skill', 'agent', 'command', 'rule', 'flow']);
+// Discovery indexes more than the four executable provider artifacts. Keep the
+// Bridge filter aligned with the complete corpus so Explore does not hide
+// extension and documentation surfaces (#1592).
+const CAPABILITY_TYPES = new Set([
+  'skill', 'agent', 'command', 'rule', 'flow', 'behavior', 'hook', 'template',
+  'tool', 'addon', 'framework', 'extension', 'plugin', 'provider', 'document',
+]);
 const mcSessionsDir = () => join(process.cwd(), '.aiwg', 'ralph-external', 'mc', 'sessions');
 const executorRequestContext = new AsyncLocalStorage();
 
@@ -177,13 +183,88 @@ function spawnCollect(cmd, args) {
     p.stdout.on('data', (d) => (out += d));
     p.stderr.on('data', (d) => (err += d));
     p.once('error', reject);
-    p.once('close', (code) => (code === 0 ? resolve(out) : reject(new Error(err.trim() || `aiwg exit ${code}`))));
+    p.once('close', (code) => {
+      if (code === 0) return resolve(out);
+      const failure = new Error(err.trim() || `aiwg exit ${code}`);
+      failure.exitCode = code;
+      failure.stdout = out;
+      reject(failure);
+    });
   });
 }
 async function runAiwg(args) {
   try { return await spawnCollect('aiwg', args); }
   catch (e) { if (e && e.code === 'ENOENT') return spawnCollect(process.execPath, [REPO_BIN, ...args]); throw e; }
 }
+
+const MISSION_CONTROL_ID_RE = /^[a-zA-Z0-9._-]+$/;
+async function controlMission({ action, sessionId, missionId, expectedUpdatedAt, requestId }) {
+  if (!['pause', 'resume', 'cancel'].includes(action)) throw Object.assign(new Error('unsupported mission control action'), { status: 400 });
+  if (!MISSION_CONTROL_ID_RE.test(sessionId) || (missionId && !MISSION_CONTROL_ID_RE.test(missionId))) {
+    throw Object.assign(new Error('invalid Mission control identifier'), { status: 400 });
+  }
+  const args = ['mc', action, sessionId];
+  if (action === 'cancel') {
+    if (!missionId) throw Object.assign(new Error('mission id required'), { status: 400 });
+    args.push(missionId);
+  }
+  if (expectedUpdatedAt) args.push('--expected-updated-at', String(expectedUpdatedAt));
+  if (requestId) args.push('--request-id', String(requestId));
+  await appendAudit('mission.control.requested', {
+    action,
+    session_id: sessionId,
+    mission_id: missionId ?? null,
+    expected_updated_at: expectedUpdatedAt ?? null,
+    request_id: requestId ?? null,
+  });
+  try {
+    await runAiwg(args);
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    const status = error?.exitCode === 3 || /mission_conflict/.test(message) ? 409 : 422;
+    await appendAudit('mission.control.rejected', { action, session_id: sessionId, mission_id: missionId ?? null, request_id: requestId ?? null, status, reason: message });
+    throw Object.assign(new Error(message), { status });
+  }
+  await appendAudit('mission.control.completed', { action, session_id: sessionId, mission_id: missionId ?? null, request_id: requestId ?? null });
+  return { ok: true, action, session_id: sessionId, mission_id: missionId ?? null, request_id: requestId ?? null };
+}
+
+async function dispatchMission(body, upstreamUrl) {
+  const sessionId = String(body?.session_id ?? '');
+  const objective = String(body?.objective ?? '').trim();
+  const completion = String(body?.completion ?? '').trim();
+  const requestId = String(body?.request_id ?? randomBytes(16).toString('hex'));
+  if (!MISSION_CONTROL_ID_RE.test(sessionId)) throw Object.assign(new Error('invalid Mission control session id'), { status: 400 });
+  if (!objective || objective.length > 4096) throw Object.assign(new Error('objective is required and must be at most 4096 characters'), { status: 400 });
+  if (completion.length > 4096) throw Object.assign(new Error('completion must be at most 4096 characters'), { status: 400 });
+  if (!MISSION_CONTROL_ID_RE.test(requestId)) throw Object.assign(new Error('request_id must contain only letters, digits, dot, underscore, or hyphen'), { status: 400 });
+  const args = ['mc', 'dispatch', sessionId, objective, '--request-id', requestId];
+  if (completion) args.push('--completion', completion);
+  if (body?.priority) args.push('--priority', String(body.priority));
+  if (body?.expected_updated_at) args.push('--expected-updated-at', String(body.expected_updated_at));
+  if (body?.max_iterations !== undefined) {
+    const maxIterations = Number(body.max_iterations);
+    if (!Number.isInteger(maxIterations) || maxIterations < 1 || maxIterations > 10_000) {
+      throw Object.assign(new Error('max_iterations must be an integer from 1 to 10000'), { status: 400 });
+    }
+    args.push('--max-iterations', String(maxIterations));
+  }
+  await appendAudit('mission.dispatch.requested', { session_id: sessionId, request_id: requestId, objective_digest: `sha256:${createHash('sha256').update(objective).digest('hex')}` });
+  try {
+    await runAiwg(args);
+    if (body?.run === true) {
+      await runAiwg(['mc', 'run', sessionId, ...(body?.accept_cost === true ? ['--accept-cost'] : [])]);
+    }
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    const status = error?.exitCode === 3 || /mission_conflict/.test(message) ? 409 : 422;
+    await appendAudit('mission.dispatch.rejected', { session_id: sessionId, request_id: requestId, status, reason: message });
+    throw Object.assign(new Error(message), { status });
+  }
+  const missionId = `m-${createHash('sha256').update(requestId).digest('hex').slice(0, 16)}`;
+  await appendAudit('mission.dispatch.completed', { session_id: sessionId, mission_id: missionId, request_id: requestId, run: body?.run === true });
+  return { ok: true, session_id: sessionId, mission_id: missionId, request_id: requestId, projection: await getMissions(upstreamUrl) };
+}
 // --- user asset library (#1591/#1593): the operator's OWN copied/cloned/imported
 // assets, on disk under ~/.aiwg/cockpit/library. AIWG install files are NEVER written
 // (clone reads the catalog read-only, writes only into the library). ---
@@ -256,23 +337,32 @@ function resolveCorpusPath(p) {
 // --- UI contribution model (#1591): declarative screens/actions/event-hooks ---
 const ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
 /** Validate one contribution manifest. Throws with a precise message on bad shape. */
-function validateContribution(m, where) {
+function validateContribution(m, where, { firstParty = false } = {}) {
   const fail = (msg) => { throw new Error(`${where}: ${msg}`); };
   if (!m || typeof m !== 'object') fail('manifest must be an object');
   if (!ID_RE.test(m.id || '')) fail('id must match [a-z0-9._-]{1,64}');
-  if (typeof m.version !== 'string') fail('version (string) required');
+  if (typeof m.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(m.version)) fail('version must be semantic version syntax');
   const c = m.contributes || {};
+  const actionIds = new Set();
   for (const a of c.actions || []) {
     if (!ID_RE.test(a.id || '')) fail(`action.id invalid: ${a.id}`);
+    if (actionIds.has(a.id)) fail(`duplicate action.id: ${a.id}`);
+    actionIds.add(a.id);
     if (typeof a.title !== 'string') fail(`action ${a.id}: title required`);
     // An action INJECTS a command into an agentic session — it does NOT run the CLI.
     if (!a.inject || typeof a.inject.command !== 'string') fail(`action ${a.id}: inject.command (string) required`);
+    if (!/^\/[a-z0-9][a-z0-9._-]*(?:\s[^\r\n]*)?$/i.test(a.inject.command)) fail(`action ${a.id}: inject.command must be one slash command without newlines`);
     if (a.inject.target && !['focused', 'new'].includes(a.inject.target)) fail(`action ${a.id}: inject.target must be focused|new`);
   }
   for (const s of c.screens || []) {
     if (!ID_RE.test(s.id || '')) fail(`screen.id invalid: ${s.id}`);
     if (typeof s.title !== 'string') fail(`screen ${s.id}: title required`);
     if (typeof s.source !== 'string') fail(`screen ${s.id}: source required`);
+    if (firstParty) {
+      if (!s.source.startsWith('cockpit://')) fail(`screen ${s.id}: first-party source must use cockpit://`);
+    } else if (!s.source.startsWith(`sandbox://${m.id}/`)) {
+      fail(`screen ${s.id}: third-party source must use sandbox://${m.id}/`);
+    }
   }
   for (const w of c.workflows || []) {
     if (!ID_RE.test(w.id || '')) fail(`workflow.id invalid: ${w.id}`);
@@ -280,24 +370,39 @@ function validateContribution(m, where) {
     if (!Array.isArray(w.steps) || w.steps.length === 0) fail(`workflow ${w.id}: steps required`);
     for (const step of w.steps) {
       if (!step || typeof step !== 'object' || !ID_RE.test(step.action || '')) fail(`workflow ${w.id}: step.action invalid`);
+      if (!actionIds.has(step.action)) fail(`workflow ${w.id}: unknown action ${step.action}`);
     }
   }
-  for (const h of c.hooks || []) { if (typeof h.on !== 'string' || !ID_RE.test(h.action || '')) fail(`hook invalid: on=${h.on}`); }
+  for (const h of c.hooks || []) {
+    if (typeof h.on !== 'string' || !ID_RE.test(h.action || '') || !actionIds.has(h.action)) fail(`hook invalid: on=${h.on}`);
+  }
   return m;
 }
 /** Load + validate + merge all contribution manifests across the configured dirs. */
 async function loadContributions() {
   const sources = [], actions = [], screens = [], hooks = [], workflows = [];
-  for (const dir of CONTRIB_DIRS) {
+  const manifestIds = new Set();
+  const itemIds = new Set();
+  for (const [dirIndex, dir] of CONTRIB_DIRS.entries()) {
+    const trustTier = dirIndex === 0 ? 'first-party' : 'sandboxed-third-party';
     let entries = [];
     try { entries = (await readdir(dir)).filter((f) => f.endsWith('.json') && f !== 'contribution.schema.json'); } catch { continue; }
     for (const file of entries) {
-      const m = validateContribution(JSON.parse(await readFile(join(dir, file), 'utf8')), file);
-      sources.push({ id: m.id, version: m.version, title: m.title ?? m.id, file });
-      for (const a of m.contributes?.actions || []) actions.push({ ...a, source: m.id });
-      for (const s of m.contributes?.screens || []) screens.push({ ...s, contribution: m.id });
-      for (const h of m.contributes?.hooks || []) hooks.push({ ...h, source: m.id });
-      for (const w of m.contributes?.workflows || []) workflows.push({ ...w, source: m.id });
+      const m = validateContribution(JSON.parse(await readFile(join(dir, file), 'utf8')), file, { firstParty: dirIndex === 0 });
+      if (manifestIds.has(m.id)) throw new Error(`${file}: duplicate contribution id ${m.id}`);
+      manifestIds.add(m.id);
+      sources.push({ id: m.id, version: m.version, title: m.title ?? m.id, file, trust_tier: trustTier });
+      for (const [kind, rows] of Object.entries({ actions: m.contributes?.actions || [], screens: m.contributes?.screens || [], hooks: m.contributes?.hooks || [], workflows: m.contributes?.workflows || [] })) {
+        for (const row of rows) {
+          const globalId = `${kind}:${row.id ?? `${row.on}:${row.action}`}`;
+          if (itemIds.has(globalId)) throw new Error(`${file}: duplicate ${globalId}`);
+          itemIds.add(globalId);
+        }
+      }
+      for (const a of m.contributes?.actions || []) actions.push({ ...a, source: m.id, trust_tier: trustTier });
+      for (const s of m.contributes?.screens || []) screens.push({ ...s, contribution: m.id, trust_tier: trustTier });
+      for (const h of m.contributes?.hooks || []) hooks.push({ ...h, source: m.id, trust_tier: trustTier });
+      for (const w of m.contributes?.workflows || []) workflows.push({ ...w, source: m.id, trust_tier: trustTier });
     }
   }
   return { sources, actions, screens, hooks, workflows };
@@ -356,6 +461,42 @@ async function rebuildIndex(req) {
   return { status: 200, body: { ok: true, command: `aiwg ${args.join(' ')}`, output, status } };
 }
 
+export async function createUserIndexGraph(body, projectRoot = process.cwd()) {
+  const name = safeIndexGraph(body?.name);
+  if (!name || ['project', 'codebase', 'framework'].includes(name)) {
+    throw new Error('name must be a non-built-in graph identifier');
+  }
+  const scanDirs = Array.isArray(body?.scanDirs) ? body.scanDirs.map((value) => String(value).trim()) : [];
+  if (!scanDirs.length || scanDirs.some((value) => !value || value.startsWith('/') || value.split(/[\\/]+/).includes('..'))) {
+    throw new Error('scanDirs must contain safe project-relative paths');
+  }
+  const extensions = Array.isArray(body?.extensions) && body.extensions.length
+    ? body.extensions.map((value) => String(value).trim())
+    : ['.md', '.yaml', '.json'];
+  if (extensions.some((value) => !/^\.[a-z0-9]+$/i.test(value))) {
+    throw new Error('extensions must use forms such as .md or .json');
+  }
+  const configDir = join(projectRoot, '.aiwg');
+  const configPath = join(configDir, 'aiwg.config');
+  await mkdir(configDir, { recursive: true, mode: 0o700 });
+  let config = {};
+  try { config = JSON.parse(await readFile(configPath, 'utf8')); }
+  catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  config.index = config.index && typeof config.index === 'object' ? config.index : {};
+  config.index.graphs = config.index.graphs && typeof config.index.graphs === 'object' ? config.index.graphs : {};
+  if (config.index.graphs[name]) throw new Error(`graph '${name}' already exists`);
+  config.index.graphs[name] = {
+    scanDirs,
+    extensions,
+    defaultBuild: body?.defaultBuild === true,
+    shared: body?.shared === true,
+  };
+  const temporary = `${configPath}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, configPath);
+  return { name, definition: config.index.graphs[name], config_path: configPath };
+}
+
 function json(res, status, body) {
   res.writeHead(status, { 'content-type': 'application/json' });
   res.end(JSON.stringify(body));
@@ -2518,7 +2659,12 @@ export function createBridge({
       if (url.pathname === '/api/mcp/discovery' && req.method === 'GET') return json(res, 200, await getMcpDiscovery(upstreamUrl));
       if (url.pathname === '/api/mcp' && req.method === 'POST') return proxyMcpRequest(req, res, upstreamUrl, MCP_TOKEN_FILE);
       if (url.pathname === '/api/running') return json(res, 200, await getRunning(upstreamUrl));
-      if (url.pathname === '/api/missions') return json(res, 200, await getMissions(upstreamUrl));
+      if (url.pathname === '/api/missions' && req.method === 'GET') return json(res, 200, await getMissions(upstreamUrl));
+      if (url.pathname === '/api/missions' && req.method === 'POST') {
+        const parsed = await readJsonBody(req);
+        if (parsed.error) return json(res, 400, { error: parsed.error });
+        return json(res, 201, await dispatchMission(parsed.body, upstreamUrl));
+      }
       if (url.pathname === '/api/events/snapshot') return json(res, 200, await getEventSnapshot(upstreamUrl));
       if (url.pathname === '/api/loadouts') return json(res, 200, await getLoadouts(upstreamUrl));
       if (url.pathname === '/api/index/status' && req.method === 'GET') return json(res, 200, await getIndexStatus());
@@ -2530,6 +2676,19 @@ export function createBridge({
         const result = await rebuildIndex(req);
         return json(res, result.status, result.body);
       }
+      if (url.pathname === '/api/index/graphs' && req.method === 'POST') {
+        const parsed = await readJsonBody(req);
+        if (parsed.error) return json(res, 400, { error: parsed.error });
+        const requested = await appendAudit('index.graph.create.requested', { graph: parsed.body?.name ?? null });
+        try {
+          const graph = await createUserIndexGraph(parsed.body);
+          await appendAudit('index.graph.create.completed', { request_ts: requested.ts, graph: graph.name });
+          return json(res, 201, { ok: true, graph });
+        } catch (error) {
+          await appendAudit('index.graph.create.rejected', { request_ts: requested.ts, reason: String(error?.message ?? error) });
+          return json(res, 400, { error: 'invalid_graph_definition', detail: String(error?.message ?? error) });
+        }
+      }
       if (url.pathname === '/api/audit' && req.method === 'GET') {
         const limit = Math.max(1, Math.min(200, Number(url.searchParams.get('limit') || 50)));
         return json(res, 200, { source: 'cockpit-bridge-audit/v1', audit: await readAudit({ limit }) });
@@ -2620,7 +2779,7 @@ export function createBridge({
         if (type && type !== 'all') {
           const types = type.split(',').map((t) => t.trim()).filter(Boolean);
           if (!types.length || types.some((t) => !CAPABILITY_TYPES.has(t))) {
-            return json(res, 400, { error: 'invalid_type', detail: 'type must be all, skill, agent, command, rule, flow, or a comma list of those kinds' });
+            return json(res, 400, { error: 'invalid_type', detail: `type must be all or a comma list of: ${[...CAPABILITY_TYPES].join(', ')}` });
           }
           args.push('--type', types.join(','));
         }
@@ -2821,6 +2980,29 @@ export function createBridge({
         await appendAudit('instance.destroy.requested', { instance_id: decodeURIComponent(m[1]), status, result: body });
         return json(res, status, body);
       }
+      if ((m = url.pathname.match(/^\/api\/missions\/([^/]+)\/(pause|resume)$/)) && req.method === 'POST') {
+        const parsed = await readJsonBody(req);
+        if (parsed.error) return json(res, 400, { error: parsed.error });
+        const result = await controlMission({
+          action: m[2],
+          sessionId: decodeURIComponent(m[1]),
+          expectedUpdatedAt: parsed.body?.expected_updated_at,
+          requestId: parsed.body?.request_id,
+        });
+        return json(res, 200, { ...result, projection: await getMissions(upstreamUrl) });
+      }
+      if ((m = url.pathname.match(/^\/api\/missions\/([^/]+)\/([^/]+)\/cancel$/)) && req.method === 'POST') {
+        const parsed = await readJsonBody(req);
+        if (parsed.error) return json(res, 400, { error: parsed.error });
+        const result = await controlMission({
+          action: 'cancel',
+          sessionId: decodeURIComponent(m[1]),
+          missionId: decodeURIComponent(m[2]),
+          expectedUpdatedAt: parsed.body?.expected_updated_at,
+          requestId: parsed.body?.request_id,
+        });
+        return json(res, 200, { ...result, projection: await getMissions(upstreamUrl) });
+      }
       if ((m = url.pathname.match(/^\/api\/tasks\/([^/]+)\/([^/]+)\/cancel$/)) && req.method === 'POST') {
         await appendAudit('task.cancel.requested', { instance_id: decodeURIComponent(m[1]), task_id: decodeURIComponent(m[2]) });
         return proxy(res, 'POST', `${upstreamUrl}/agents/${encodeURIComponent(m[1])}/tasks/${encodeURIComponent(m[2])}:cancel`);
@@ -2867,7 +3049,7 @@ export function createBridge({
       }
       json(res, 404, { error: 'not_found', path: url.pathname });
     } catch (err) {
-      const status = Number(err?.upstreamStatus) || 502;
+      const status = Number(err?.status) || Number(err?.upstreamStatus) || 502;
       json(res, status, { error: err?.code ?? 'bridge_upstream_error', message: String(err?.message ?? err) });
     }
   };

package/contrib/contribution.schema.json

@@ -31,7 +31,7 @@
                 "required": ["command"],
                 "additionalProperties": false,
                 "properties": {
-                  "command": { "type": "string", "description": "command/prompt injected into an agentic session" },
+                  "command": { "type": "string", "pattern": "^/[a-zA-Z0-9][a-zA-Z0-9._-]*(\\s[^\\r\\n]*)?$", "description": "single slash command injected into an agentic session; newlines are forbidden" },
                   "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" }
@@ -49,7 +49,7 @@
             "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" }
+              "source": { "type": "string", "pattern": "^(cockpit|sandbox)://", "description": "first-party cockpit:// route or third-party sandbox://<contribution-id>/ resource" }
             }
           }
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cockpit",
-  "version": "2026.8.3",
+  "version": "2026.8.4",
   "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/shell-core/keychain.mjs

@@ -3,7 +3,6 @@ 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) => {
@@ -37,74 +36,94 @@ async function canRun(cmd) {
   }
 }
 
-async function windowsPowerShell() {
-  if (await canRun('powershell')) return 'powershell';
-  if (await canRun('pwsh')) return 'pwsh';
-  throw new Error('no supported Windows PowerShell command found');
-}
+/**
+ * Build the cross-platform keychain adapter around injectable platform and
+ * process seams. Production uses the defaults below; tests exercise the exact
+ * argv/stdin contract for every OS without pretending the CI host is macOS or
+ * Windows.
+ */
+export function createKeychainAdapter({
+  os = platform(),
+  env = process.env,
+  run = collect,
+  commandAvailable = canRun,
+} = {}) {
+  const wallet = env.AIWG_COCKPIT_KWALLET || 'kdewallet';
 
-async function storeWindowsCredential(token, account) {
-  const ps = await windowsPowerShell();
-  const script = [
-    '[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]',
-    '$vault = New-Object Windows.Security.Credentials.PasswordVault',
-    'try { $vault.Remove($vault.Retrieve($args[0], $args[1])) } catch {}',
-    '$password = [Console]::In.ReadToEnd()',
-    '$credential = New-Object Windows.Security.Credentials.PasswordCredential -ArgumentList $args[0], $args[1], $password',
-    '$vault.Add($credential)',
-  ].join('; ');
-  await collect(ps, ['-NoProfile', '-NonInteractive', '-Command', script, SERVICE, account], token);
-  return { backend: 'windows-credential-manager', service: SERVICE, account, target: `${SERVICE}:${account}` };
-}
+  async function windowsPowerShell() {
+    if (await commandAvailable('powershell')) return 'powershell';
+    if (await commandAvailable('pwsh')) return 'pwsh';
+    throw new Error('no supported Windows PowerShell command found');
+  }
+
+  async function storeWindowsCredential(token, account) {
+    const ps = await windowsPowerShell();
+    const script = [
+      '[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]',
+      '$vault = New-Object Windows.Security.Credentials.PasswordVault',
+      'try { $vault.Remove($vault.Retrieve($args[0], $args[1])) } catch {}',
+      '$password = [Console]::In.ReadToEnd()',
+      '$credential = New-Object Windows.Security.Credentials.PasswordCredential -ArgumentList $args[0], $args[1], $password',
+      '$vault.Add($credential)',
+    ].join('; ');
+    await run(ps, ['-NoProfile', '-NonInteractive', '-Command', script, SERVICE, account], token);
+    return { backend: 'windows-credential-manager', service: SERVICE, account, target: `${SERVICE}:${account}` };
+  }
 
-async function readWindowsCredential(ref) {
-  const ps = await windowsPowerShell();
-  const script = [
-    '[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]',
-    '$vault = New-Object Windows.Security.Credentials.PasswordVault',
-    '$credential = $vault.Retrieve($args[0], $args[1])',
-    '$credential.RetrievePassword()',
-    '[Console]::Out.Write($credential.Password)',
-  ].join('; ');
-  return (await collect(ps, ['-NoProfile', '-NonInteractive', '-Command', script, ref.service || SERVICE, ref.account])).trim();
+  async function readWindowsCredential(ref) {
+    const ps = await windowsPowerShell();
+    const script = [
+      '[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]',
+      '$vault = New-Object Windows.Security.Credentials.PasswordVault',
+      '$credential = $vault.Retrieve($args[0], $args[1])',
+      '$credential.RetrievePassword()',
+      '[Console]::Out.Write($credential.Password)',
+    ].join('; ');
+    return (await run(ps, ['-NoProfile', '-NonInteractive', '-Command', script, ref.service || SERVICE, ref.account])).trim();
+  }
+
+  return {
+    async store(token, account = `bridge-${process.pid}`) {
+      if (env.AIWG_COCKPIT_KEYCHAIN_DISABLED === '1') {
+        throw new Error('OS keychain disabled by AIWG_COCKPIT_KEYCHAIN_DISABLED');
+      }
+      if (os === 'darwin' && await commandAvailable('security')) {
+        await run('security', ['add-generic-password', '-a', account, '-s', SERVICE, '-w', token, '-U']);
+        return { backend: 'macos-keychain', service: SERVICE, account };
+      }
+      if (os === 'win32') return storeWindowsCredential(token, account);
+      if (await commandAvailable('secret-tool')) {
+        await run('secret-tool', ['store', '--label', 'AIWG Cockpit Bridge', 'service', SERVICE, 'account', account], token);
+        return { backend: 'libsecret', service: SERVICE, account };
+      }
+      if (env.AIWG_COCKPIT_ENABLE_KWALLET === '1' && await commandAvailable('kwallet-query')) {
+        await run('kwallet-query', ['-f', FOLDER, '-w', account, wallet], token);
+        return { backend: 'kwallet', service: SERVICE, account, wallet, folder: FOLDER };
+      }
+      throw new Error('no supported OS keychain command found');
+    },
+
+    async read(ref) {
+      if (!ref || typeof ref !== 'object') throw new Error('missing keychain reference');
+      if (ref.backend === 'macos-keychain') {
+        return (await run('security', ['find-generic-password', '-a', ref.account, '-s', ref.service || SERVICE, '-w'])).trim();
+      }
+      if (ref.backend === 'windows-credential-manager') return readWindowsCredential(ref);
+      if (ref.backend === 'libsecret') {
+        return (await run('secret-tool', ['lookup', 'service', ref.service || SERVICE, 'account', ref.account])).trim();
+      }
+      if (ref.backend === 'kwallet') {
+        return (await run('kwallet-query', ['-f', ref.folder || FOLDER, '-r', ref.account, ref.wallet || wallet])).trim();
+      }
+      throw new Error(`unsupported keychain backend: ${ref.backend}`);
+    },
+  };
 }
 
 export async function storeCockpitToken(token, account = `bridge-${process.pid}`) {
-  if (process.env.AIWG_COCKPIT_KEYCHAIN_DISABLED === '1') {
-    throw new Error('OS keychain disabled by AIWG_COCKPIT_KEYCHAIN_DISABLED');
-  }
-  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') {
-    return storeWindowsCredential(token, account);
-  }
-  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');
+  return createKeychainAdapter().store(token, account);
 }
 
 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') {
-    return readWindowsCredential(ref);
-  }
-  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}`);
+  return createKeychainAdapter().read(ref);
 }