@worca/app 1.5.0-rc.3 → 1.6.0-rc.1

package/src/cli/models.mjs

@@ -10,7 +10,7 @@ import { createInterface } from 'node:readline';
 import {
   providersState, beginCopilotLogin, pollCopilotLogin, copilotLogout, acknowledgeTerms,
   copilotModelsForImport, importCopilotModels, testProviderConnection, patchProvider,
-  endpointModelsForImport, importEndpointModels,
+  endpointModelsForImport, importEndpointModels, OPENROUTER_BASE_URL,
 } from '../core/bridge/provider-ops.mjs';
 import { listModels } from '../core/config.mjs';
 import { isTranslatedApi } from '../core/model-env.mjs';
@@ -26,13 +26,21 @@ Usage:
   worca models import copilot [--all | --pick <id,id,…>] [--yes]
                                           Add Copilot models to the catalog
   worca models import openai [--base-url <url>] [--all | --pick <id,id,…>] [--yes]
+                         [--search <text>] [--free] [--tools] [--min-context <n|64k>]
                                           Add what an OpenAI-compatible endpoint serves
-                                          (llama.cpp, Ollama, LM Studio, vLLM, a gateway)
-  worca models test <provider>            Reachability + auth check (copilot|openai|anthropic)
+                                          (llama.cpp, Ollama, LM Studio, vLLM, OpenRouter, a gateway);
+                                          the filters narrow the listing and --all
+  worca models import openrouter …        The same, against https://openrouter.ai/api/v1
+  worca models test <provider>            Reachability + auth check (copilot|openai|anthropic|openrouter);
+                                          for OpenRouter also the key's credit and free-model allowance
   worca models set <provider> <key>=<value> …
                                           Patch a provider: accountType, maxConcurrent, baseUrl, apiKey
+  worca models set openrouter apiKey='\${OPENROUTER_KEY}'
+                                          The openai provider, pointed at OpenRouter
 
 Notes:
+  OpenRouter is the openai (OpenAI-compatible) provider with OpenRouter's base URL — one key and
+  one concurrency cap. A model can still point elsewhere on its own Connection.
   Copilot: GitHub allows Copilot only through supported clients and has suspended
   access for automated use. \`login\` prints the notice; --accept-terms records the
   acknowledgement non-interactively. Pipelines are automated, high-volume use.
@@ -122,8 +130,13 @@ const sleep = (ms) => new Promise((r) => { const t = setTimeout(r, ms); if (t.un
  * @returns {Promise<number>} exit code
  */
 export async function cmdModels(argv, { out, c, fail, sleep: wait = sleep }) {
-  const args = modelsArgs(argv, ['--pick', '--base-url'], ['--accept-terms', '--all', '--yes', '-h', '--help'], fail);
+  const args = modelsArgs(argv, ['--pick', '--base-url', '--search', '--min-context'], ['--accept-terms', '--all', '--yes', '--free', '--tools', '-h', '--help'], fail);
   const [verb, ...rest] = args._;
+  // `openrouter` is not a provider of its own: it is the openai provider at OpenRouter's URL, so
+  // every verb below sees `openai` and a base URL that defaults to OpenRouter's.
+  const viaOpenRouter = rest[0] === 'openrouter';
+  if (viaOpenRouter) rest[0] = 'openai';
+  const baseUrlArg = args['base-url'] || (viaOpenRouter ? OPENROUTER_BASE_URL : '');
   if (!verb || args.help || args.h || verb === 'help') { out(MODELS_HELP); return 0; }
 
   if (verb === 'list') {
@@ -174,23 +187,36 @@ export async function cmdModels(argv, { out, c, fail, sleep: wait = sleep }) {
   if (verb === 'import' && provider === 'openai') {
     // §8.4 for a server you run: the endpoint is asked what it serves, and only a window it
     // really serves becomes a prompt limit — the rest is printed for the user to judge.
+    let minCtx = 0;
+    if (args['min-context'] !== undefined) {
+      const mm = /^(\d+(?:\.\d+)?)([km]?)$/i.exec(String(args['min-context']).trim());
+      if (!mm) return fail('--min-context takes a token count: 65536, 64k or 1m');
+      minCtx = Math.round(Number(mm[1]) * ({ k: 1000, m: 1e6 }[mm[2].toLowerCase()] || 1));
+    }
     let out0;
-    try { out0 = await endpointModelsForImport({ baseUrl: args['base-url'] || '' }); } catch (err) { return fail(err.message || String(err)); }
+    try { out0 = await endpointModelsForImport({ baseUrl: baseUrlArg }); } catch (err) { return fail(err.message || String(err)); }
     const fmtCtx = (m) => (m.servedContext ? `${Math.round(m.servedContext / 1000)}k` : m.trainedContext ? `?/${Math.round(m.trainedContext / 1000)}k` : '-');
+    // A hosted catalog is hundreds of rows: the filters narrow the listing AND what --all takes.
+    const q = String(args.search || '').trim().toLowerCase();
+    const shown = out0.models.filter((m) => (!q || m.id.toLowerCase().includes(q) || String(m.name || '').toLowerCase().includes(q))
+      && (!args.free || m.free === true) && (!args.tools || m.toolCalls === true) && (!minCtx || (m.servedContext || 0) >= minCtx));
+    const hosted = out0.server === 'openrouter';
     let ids;
     if (args.pick) ids = String(args.pick).split(',').map((x) => x.trim()).filter(Boolean);
-    else if (args.all) ids = out0.models.filter((m) => m.importable).map((m) => m.id);
+    else if (args.all) ids = shown.filter((m) => m.importable).map((m) => m.id);
     else {
-      out(`${out0.serverLabel} at ${out0.baseUrl} (pass --all, or --pick id,id,…):`);
-      for (const m of out0.models) {
-        out(`  ${m.id.padEnd(34)} ${fmtCtx(m).padStart(7)}  ${m.toolCalls ? 'tools' : m.toolCalls === null ? 'tools?' : '     '} ${m.vision ? 'vision' : '      '}${m.loaded === true ? ' loaded' : ''}${m.inCatalog ? '  (in catalog)' : ''}${m.importable ? '' : `  (${m.blocked})`}`);
+      out(`${out0.serverLabel} at ${out0.baseUrl} (pass --all, or --pick id,id,…)${shown.length < out0.models.length ? ` — ${shown.length} of ${out0.models.length} match` : ''}:`);
+      // One id column as wide as the longest shown id (OpenRouter's run past 34).
+      const idWidth = Math.max(34, ...shown.map((m) => m.id.length));
+      for (const m of shown) {
+        out(`  ${m.id.padEnd(idWidth)} ${fmtCtx(m).padStart(7)}  ${m.toolCalls ? 'tools' : m.toolCalls === null ? 'tools?' : '     '} ${m.vision ? 'vision' : '      '}${m.loaded === true ? ' loaded' : ''}${hosted && m.detail ? `  ${m.detail}` : ''}${m.inCatalog ? '  (in catalog)' : ''}${m.importable ? '' : `  (${m.blocked})`}`);
       }
       for (const w of out0.warnings) out(c('yellow', `  ! ${w}`));
       return 0;
     }
     for (const w of out0.warnings) out(c('yellow', `! ${w}`));
     if (!(await confirm(`Import ${ids.length} model${ids.length === 1 ? '' : 's'} into the catalog?`, args.yes, { c }))) return fail('cancelled');
-    const r = await importEndpointModels(ids, { baseUrl: args['base-url'] || '' });
+    const r = await importEndpointModels(ids, { baseUrl: baseUrlArg });
     for (const id of r.created) out(`  + ${id}`);
     for (const id of r.updated) out(`  ~ ${id} (upstream refreshed)`);
     for (const sk of r.skipped) out(`  - ${sk.id} (skipped: ${sk.why})`);
@@ -222,10 +248,15 @@ export async function cmdModels(argv, { out, c, fail, sleep: wait = sleep }) {
   }
 
   if (verb === 'test') {
-    if (!provider) return fail('usage: worca models test <copilot|openai|anthropic>');
-    const r = await testProviderConnection(provider);
-    if (r.ok) { out(c('green', `✓ ${provider} reachable${r.models != null ? ` — ${r.models} models listed` : ''}`)); return 0; }
-    out(c('red', `✗ ${provider}: ${r.message}`));
+    if (!provider) return fail('usage: worca models test <copilot|openai|anthropic|openrouter>');
+    const label = viaOpenRouter ? 'openrouter' : provider;
+    const r = await testProviderConnection(provider, viaOpenRouter ? { baseUrl: baseUrlArg } : {});
+    if (r.ok) {
+      out(c('green', `✓ ${label} reachable${r.models != null ? ` — ${r.models} models listed` : ''}`));
+      if (r.detail) out(`  key: ${r.detail}`);
+      return 0;
+    }
+    out(c('red', `✗ ${label}: ${r.message}`));
     return 1;
   }
 
@@ -238,6 +269,7 @@ export async function cmdModels(argv, { out, c, fail, sleep: wait = sleep }) {
       const k = kv.slice(0, i); const v = kv.slice(i + 1);
       patch[k] = k === 'maxConcurrent' ? Number(v) : v;
     }
+    if (viaOpenRouter && patch.baseUrl === undefined) patch.baseUrl = OPENROUTER_BASE_URL;
     if (!Object.keys(patch).length) return fail('nothing to set');
     try { await patchProvider(provider, patch); } catch (err) { return fail(err.message || String(err)); }
     for (const line of formatProviders(await providersState())) out(line);

package/src/cli/render.mjs

@@ -122,6 +122,27 @@ export function formatTotals({ executions = 0, activeMs = 0, costUsd = 0 } = {})
   return `${executions} execution${executions === 1 ? '' : 's'} · ${fmtDur(activeMs)} active · ${usd(costUsd)}`;
 }
 
+/** The count-only twin of formatRunSummary's execution rows: v2 stepper rows that
+ *  carry a real executionId (bookends excluded). null for a v1/no-stepper run —
+ *  callers omit the count rather than claim one. */
+export function executionCount(state) {
+  const st = state || {};
+  if (!(st.stepper && st.stepper.version === 2)) return null;
+  return (Array.isArray(st.steps) ? st.steps : [])
+    .filter((s) => s && s.executionId && !BOOKEND_EXECUTION_IDS.includes(s.executionId)).length;
+}
+
+/** The loop-delivery total the History Overview's DURATION sub-line renders
+ *  (ui/public/graph/run-decor.mjs): the sum over the stepper's LOOP wires of the
+ *  run's wireDeliveries count. null without a v2 stepper. */
+export function loopDeliveries(state) {
+  const st = state || {};
+  if (!(st.stepper && st.stepper.version === 2)) return null;
+  const wires = (st.stepper.graph && st.stepper.graph.wires) || [];
+  const deliveries = st.wireDeliveries && typeof st.wireDeliveries === 'object' ? st.wireDeliveries : {};
+  return wires.reduce((a, w) => a + (w.loop ? (Number(deliveries[w.id]) || 0) : 0), 0);
+}
+
 /**
  * The v2 run summary the CLI prints under `Pipeline complete.` — pure, so the
  * quiescence arm and the executions count are testable without spawning a run.

package/src/cli/runs.mjs

@@ -0,0 +1,296 @@
+// src/cli/runs.mjs
+// `worca runs` — list and inspect pipeline runs from the terminal (issue #481).
+//
+// The CLI could START, RESUME and SCHEDULE runs but not SEE them: the run list
+// lived only in the web UI (ui/server.mjs /api/runs + /api/history) and the
+// store. This module reads the same store directly — listAllPipelines() for the
+// list (the exact reader /api/history uses, in `lite` form: no git/gh spawns),
+// a prefix lookup on the pipelines table for the detail view — so listing works
+// with NO Worca server up. Only the `worca ui` deep link at the bottom of the
+// detail view needs a server (and it is just a URL, not a request).
+
+import { basename } from 'node:path';
+
+import { getDb } from '../core/db.mjs';
+import { listAllPipelines, readPipelineByKey, readStoreMeta } from '../core/artifacts.mjs';
+import { readUiInstance } from '../core/ui-instance.mjs';
+import { fmtDur, executionCount, loopDeliveries } from './render.mjs';
+import { formatInstant } from '../shared/schedule/recurrence.mjs';
+
+export const RUNS_HELP = `worca runs — list and inspect pipeline runs
+
+Usage:
+  worca runs                      All runs across projects, newest first
+  worca runs --status <s>         Filter by status: created | running | paused |
+                                  stopped | interrupted | done
+  worca runs --project <name>     Filter by project name or key
+  worca runs <id>                 One run in detail (any unique prefix)
+  worca runs show <id>            One run in detail (same as "worca runs <id>")
+  worca runs --json               Machine-readable output (list and detail)
+
+Reads come straight from the Worca store — no Worca server needs to be up.
+A paused run shows its pause reason next to the status; the detail view adds
+the full message.
+`;
+
+/** The statuses a pipelines row carries today (writeState / reconcileStaleRunning). */
+const STATUSES = ['created', 'running', 'paused', 'stopped', 'interrupted', 'done'];
+
+const STATUS_COLOR = { running: 'cyan', paused: 'yellow', interrupted: 'yellow', done: 'green', stopped: 'red' };
+
+const usd = (n) => `$${(Number(n) || 0).toFixed(2)}`;
+
+/** "just now" / "5m ago" / "2h ago" / "3d ago" — the list's time column. */
+function ago(iso) {
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms)) return '—';
+  const s = Math.max(0, Math.round((Date.now() - ms) / 1000));
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+const oneLine = (s, max = 60) => {
+  const line = String(s || '').split('\n').map((l) => l.trim()).find(Boolean) || '';
+  return line.length > max ? `${line.slice(0, max)}…` : line;
+};
+
+/** `--status paused` and `--status=paused` both land here; null when unset. */
+function valueFlag(rest, name) {
+  const i = rest.indexOf(`--${name}`);
+  const inline = rest.find((a) => a.startsWith(`--${name}=`));
+  if (inline !== undefined) return inline.slice(name.length + 3);
+  if (i !== -1) {
+    const v = rest[i + 1];
+    if (v === undefined || v.startsWith('-')) return null; // a flag, not a value
+    return v;
+  }
+  return null;
+}
+
+/**
+ * `<id or prefix>` -> the one pipelines row, straight from the DB (the
+ * resolveAfterId idiom: LIKE with escaped metacharacters, capped at 21 so the
+ * ambiguity count stays exact). `unknownVerb` only changes the not-found
+ * message: a bare `worca runs lst` must not read as "your runs are gone".
+ */
+function resolveRunRef(ref, fail, { unknownVerb = false } = {}) {
+  const q = String(ref || '').trim();
+  if (!q) fail('an id is required (see: worca runs list)');
+  const hits = getDb().prepare(
+    "SELECT id FROM pipelines WHERE id LIKE ? ESCAPE '\\' ORDER BY COALESCE(updated_at, started_at) DESC LIMIT 21",
+  ).all(`${q.replace(/[\\%_]/g, '\\$&')}%`);
+  if (!hits.length) {
+    fail(unknownVerb
+      ? `no run matches "${q}", and "${q}" is not a known verb either (see: worca runs help)`
+      : `no run matches "${q}" (see: worca runs list)`);
+  }
+  if (hits.length > 1) fail(`"${q}" matches ${hits.length > 20 ? 'more than 20' : hits.length} runs — use a longer id`);
+  return hits[0].id;
+}
+
+/** The store key a row lives under (workspaces route to their own subtree). */
+const storeKeyOf = (row) => (row.target === 'workspace' && row.workspace_key ? row.workspace_key : row.project_key);
+
+/** The list/detail "project" label: the registered name, else the raw store key. */
+function projectLabel(row) {
+  const m = readStoreMeta(storeKeyOf(row));
+  const name = m && (m.name || m.workspaceName);
+  return name ? String(name) : storeKeyOf(row);
+}
+
+/** `worca ui`'s URL for one run's detail screen (app.js routes `#history/<key>/<id>`). */
+function uiUrl(row) {
+  const inst = readUiInstance();
+  if (!inst) return null;
+  const host = !inst.host || inst.host === '0.0.0.0' ? 'localhost' : inst.host;
+  return `http://${host}:${inst.port}/#history/${encodeURIComponent(storeKeyOf(row))}/${row.id}`;
+}
+
+// ── list ────────────────────────────────────────────────────────────────────────
+
+async function runsList(rest, { out, c, fail }) {
+  // `--status`/`--project` given but valueless fail here, not silently as "unset".
+  for (const name of ['status', 'project']) {
+    if (rest.includes(`--${name}`) && valueFlag(rest, name) === null && !rest.some((a) => a.startsWith(`--${name}=`))) {
+      fail(`--${name} needs a value (see: worca runs help)`);
+    }
+  }
+  const status = valueFlag(rest, 'status');
+  const project = valueFlag(rest, 'project');
+  const json = rest.includes('--json');
+  const unknown = rest.filter((a) => a.startsWith('-')
+    && !['--json', '--status', '--project'].includes(a)
+    && !a.startsWith('--status=') && !a.startsWith('--project='));
+  if (unknown.length) fail(`unknown option(s): ${unknown.join(' ')} — see: worca runs help`);
+  if (status !== null && !STATUSES.includes(String(status).toLowerCase())) {
+    fail(`--status must be one of ${STATUSES.join(', ')}, got: ${status}`);
+  }
+
+  const entries = (await listAllPipelines({ lite: true })) || [];
+  const q = String(project || '').toLowerCase();
+  const runs = entries.filter((e) => {
+    if (status !== null && String(e.status || '').toLowerCase() !== String(status).toLowerCase()) return false;
+    if (q && !`${e.projectName}`.toLowerCase().includes(q) && !`${e.projectKey}`.toLowerCase().includes(q)) return false;
+    return true;
+  });
+
+  if (json) { out(JSON.stringify(runs, null, 2)); return 0; }
+  if (!runs.length) {
+    out(entries.length
+      ? 'No runs match the given filters (see: worca runs help).'
+      : 'No pipeline runs yet. Start one with: worca --prompt "<task>"');
+    return 0;
+  }
+  const rows = [];
+  for (const r of runs) {
+    const st = r.pauseReason
+      ? `${r.status} (${String(r.pauseReason).replace(/_/g, ' ')})`
+      : String(r.status || 'unknown');
+    rows.push({ id: r.id, status: st, color: STATUS_COLOR[r.status] || '', started: ago(r.startedAt), project: oneLine(r.projectName || r.projectKey || '—', 24), title: oneLine(r.title) });
+  }
+  // Padded columns, widths from the data (capped where a value can be long).
+  // Widths are computed on PLAIN text; the status cell is colored after padding,
+  // so ANSI codes never break the alignment.
+  const HEADER = ['ID', 'STATUS', 'STARTED', 'PROJECT', 'TITLE'];
+  const cell = (r) => [r.id, r.status, r.started, r.project, r.title];
+  const width = (i) => Math.max(HEADER[i].length, ...rows.map((r) => cell(r)[i].length));
+  const [wId, wStatus, wStarted, wProject] = [width(0), width(1), width(2), width(3)];
+  out(c('bold', `  ${'ID'.padEnd(wId)}  ${'STATUS'.padEnd(wStatus)}  ${'STARTED'.padEnd(wStarted)}  ${'PROJECT'.padEnd(wProject)}  TITLE`));
+  for (const r of rows) {
+    const [id, status, started, project, title] = cell(r);
+    out(`  ${id.padEnd(wId)}  ${c(r.color, status.padEnd(wStatus))}  ${started.padEnd(wStarted)}  ${project.padEnd(wProject)}  ${title}`);
+  }
+  return 0;
+}
+
+// ── detail ──────────────────────────────────────────────────────────────────────
+
+async function runsShow(argv, { out, c, fail, unknownVerb = false }) {
+  const json = argv.includes('--json');
+  const unknown = argv.filter((a) => a.startsWith('-') && a !== '--json');
+  if (unknown.length) fail(`unknown option(s): ${unknown.join(' ')} — see: worca runs help`);
+  const ref = argv.find((a) => !a.startsWith('-'));
+  const id = resolveRunRef(ref, fail, { unknownVerb });
+
+  // One row by id — the same columns listAllPipelines SELECTs, plus phase/cycle
+  // for the detail view. pauseReason/pauseDetail live in the resume_point JSON.
+  const row = getDb().prepare(`
+    SELECT id, project_key, workspace_key, target, title, status, phase, cycle,
+           started_at, updated_at, total_cost_usd, total_active_ms, started_by, prompt, branch,
+           json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseReason') AS pause_reason,
+           json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseDetail') AS pause_detail
+    FROM pipelines WHERE id = ?
+  `).get(id);
+  if (!row) fail(`no run matches "${ref}" (see: worca runs list)`);
+
+  // The same full read the web UI's detail screen does (run-report readPipelineByKey),
+  // for the two fields it shows that the DB row alone cannot answer: the persisted
+  // diff summary (+A −R, results.json) and the End result. Nulls mean "not there".
+  const full = await readPipelineByKey(storeKeyOf(row), id).catch(() => null);
+  const sums = full && full.results && full.results.summary ? full.results.summary : null;
+  const added = sums ? sums.linesAdded : null;
+  const removed = sums ? sums.linesRemoved : null;
+  const st = (full && full.state) || {};
+  const resultPath = st.endReached === true && st.result && st.result.path ? String(st.result.path) : null;
+  const completed = st.endReached === true;
+  // The identity convention (identity.mjs, as schedule.mjs' person()): 'local' is
+  // the machine, never shown — only a real person's name is worth a line.
+  const startedBy = typeof row.started_by === 'string' && row.started_by && row.started_by !== 'local' ? row.started_by : null;
+  const executions = executionCount(st);
+  const loops = loopDeliveries(st);
+  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  const startedClock = Number.isFinite(Date.parse(row.started_at))
+    ? formatInstant(Date.parse(row.started_at), tz)
+    : null;
+
+  const branch = (() => {
+    try { const b = JSON.parse(row.branch); return b && typeof b === 'object' ? b : null; } catch { return null; }
+  })();
+  const link = uiUrl(row);
+
+  if (json) {
+    out(JSON.stringify({
+      id: row.id,
+      title: row.title ?? row.id,
+      project: { key: storeKeyOf(row), name: projectLabel(row) },
+      status: row.status,
+      phase: row.phase,
+      cycle: row.cycle,
+      pauseReason: row.pause_reason ?? null,
+      pauseDetail: row.pause_detail ?? null,
+      startedAt: row.started_at ?? null,
+      updatedAt: row.updated_at ?? null,
+      costUsd: Number(row.total_cost_usd) || 0,
+      activeMs: Number(row.total_active_ms) || 0,
+      executions,
+      loopDeliveries: loops,
+      sourceBranch: (branch && branch.source) || null,
+      featureBranch: (branch && branch.feature) || null,
+      linesAdded: added,
+      linesRemoved: removed,
+      resultPath,
+      startedBy,
+      uiUrl: link,
+    }, null, 2));
+    return 0;
+  }
+
+  out(c('bold', row.title || row.id));
+  out(`  id       ${row.id}`);
+  out(`  project  ${projectLabel(row)}${row.target === 'workspace' ? `  (${basename(String(row.workspace_key || ''))})` : ''}`);
+  const where = row.pause_detail ? ` — ${row.pause_detail}` : '';
+  out(`  status   ${row.status}${row.pause_reason ? ` (${String(row.pause_reason).replace(/_/g, ' ')})${where}` : ''}`);
+  // The cycle scalar is harness-local (run-harness _phase) — the UI never shows
+  // it either; it surfaces loop traffic as "N loop deliveries" instead. JSON keeps it.
+  out(`  phase    ${row.phase || '—'}`);
+  out(`  started  ${ago(row.started_at)}${startedClock ? ` (${startedClock})` : ''}`);
+  const updatedClock = Number.isFinite(Date.parse(row.updated_at))
+    ? formatInstant(Date.parse(row.updated_at), tz)
+    : null;
+  if (row.updated_at) out(`  updated  ${ago(row.updated_at)}${updatedClock ? ` (${updatedClock})` : ''}`);
+  // The DURATION sub-line's counts, the web UI's wording (app.js histCountsLine):
+  // `9 executions · 2 loop deliveries`.
+  const counts = [];
+  if (executions != null) counts.push(`${executions} execution${executions === 1 ? '' : 's'}`);
+  if (loops != null) counts.push(`${loops} loop deliver${loops === 1 ? 'y' : 'ies'}`);
+  out(`  duration ${fmtDur(row.total_active_ms)}${counts.length ? ` · ${counts.join(' · ')}` : ''}`);
+  // COST's sub-line, the web UI's wording (app.js: `across ${steps.length} steps`).
+  const steps = Array.isArray(st.steps) ? st.steps : [];
+  out(`  cost     ${usd(row.total_cost_usd)}${steps.length ? ` · across ${steps.length} step${steps.length === 1 ? '' : 's'}` : ''}`);
+  if (branch && (branch.feature || branch.source)) {
+    // The web UI's order (hd-base: `dev → worca-cc/…`), for one mental model.
+    const b = branch.source && branch.feature
+      ? `${branch.source} → ${branch.feature}`
+      : (branch.feature || `from ${branch.source}`);
+    out(`  branch   ${b}`);
+  }
+  if (added != null && removed != null) out(`  changes  +${added} -${removed}`);
+  if (resultPath) out(`  result   ${resultPath}`);
+  else if (completed) out('  result   completed');
+  if (startedBy) out(`  by       ${startedBy}`);
+  const task = oneLine(row.prompt, 100);
+  if (task) out(`  task     ${task}`);
+  if (link) out(c('gray', `  open     ${link}`));  // only when a Worca server is recorded — no nag line otherwise
+  return 0;
+}
+
+// ── dispatch ────────────────────────────────────────────────────────────────────
+
+/**
+ * `worca runs` — the bare command lists; a known verb dispatches; anything else
+ * is read as a run id (unique prefix). Unknown input never falls through to a
+ * full list: it resolves as an id first and the combined error names BOTH
+ * readings, so a typo'd verb cannot masquerade as a missing run.
+ * @returns {Promise<number>} exit code
+ */
+export async function cmdRuns(argv, { out, c, fail }) {
+  const verb = argv[0];
+  const rest = argv.slice(1);
+  if (verb === 'help' || verb === '--help' || verb === '-h') { process.stdout.write(RUNS_HELP); return 0; }
+  if (verb === 'list') return runsList(rest, { out, c, fail });
+  if (verb === 'show') return runsShow(rest, { out, c, fail });
+  if (!verb || verb.startsWith('-')) return runsList(argv, { out, c, fail });  // flags belong to the list
+  return runsShow(argv, { out, c, fail, unknownVerb: true });                  // a run id (or a typo)
+}

package/src/cli/worca-cc.mjs

@@ -38,6 +38,7 @@ import { collectAnswer } from '../shared/forms/answer.mjs';
 import { pauseExitCode, describePauseReason, promptOptions, REASON } from '../core/failure-policy.mjs';
 import { effectiveDebugSpawn } from '../core/settings.mjs';
 import { SCHEDULE_VALUE_FLAGS, wantsSchedule, readScheduleFlags, createFromFlags, waitAndRun, cmdSchedule } from './schedule.mjs';
+import { cmdRuns } from './runs.mjs';
 import { cmdModels } from './models.mjs';
 import { cmdContainer } from './container.mjs';
 import {
@@ -259,6 +260,8 @@ Subcommands:
   resume <pipelineId>         Continue a paused pipeline (re-attaches Claude sessions).
     [--ignore-cost-cap]       Resume past this pipeline's cost cap (persists on the run).
     [--past-team-cap]         Continue past a TEAM cap (soft; recorded to team metrics). Add --reason "<why>".
+  runs [list|show|<id>]       List pipeline runs across projects, or show one in detail
+                              (any unique prefix; --json for machines). See: worca runs help
   doctor                      Reconcile crashed runs and sweep leftover run roots.
   plugin <cmd> [...]          Manage plugins: add|install|list|update|remove|purge|enable|
                               disable|doctor|link|reimport|init|validate|exec. See: worca plugin help
@@ -277,7 +280,10 @@ Subcommands:
                               See: worca models help
   container <cmd> [...]       Run Worca in a container: init|up|down|status|logs|pull|login|shell|run|where.
                               See: worca container help (docs/docker.md)
-  help                        Print this help (same as --help).
+  broker [serve|secrets|revoke --person <email>]
+                              The credential broker: holds model keys outside worca's container
+                              (docs/credential-broker.md)
+  help                       Print this help (same as --help).
   version                     Print the version (same as --version).
 
 Options:
@@ -3104,7 +3110,7 @@ async function drainMetricsFlushes() {
 
 // ── main ──────────────────────────────────────────────────────────────────────────
 
-const SUBCOMMANDS = new Set(['add', 'list', 'remove', 'resume', 'doctor', 'plugin', 'marketplace', 'config', 'ui', 'workflow', 'metrics', 'script', 'policy', 'schedule', 'models', 'container']);
+const SUBCOMMANDS = new Set(['add', 'list', 'remove', 'resume', 'runs', 'doctor', 'plugin', 'marketplace', 'config', 'ui', 'workflow', 'metrics', 'script', 'policy', 'schedule', 'models', 'container', 'broker']);
 
 /** Levenshtein distance, two-row. Only ever called on short argv tokens. */
 function editDistance(a, b) {
@@ -3158,6 +3164,7 @@ async function main() {
     if (sub === 'list') return cmdList();
     if (sub === 'remove') return cmdRemove(rest);
     if (sub === 'resume') return cmdResume(rest);
+    if (sub === 'runs') return cmdRuns(rest, { out, c, fail });
     if (sub === 'doctor') return cmdDoctor();
     if (sub === 'plugin') return cmdPlugin(rest);
     if (sub === 'marketplace') return cmdMarketplace(rest);
@@ -3170,6 +3177,11 @@ async function main() {
     if (sub === 'schedule') return cmdSchedule(rest, { out, c, fail });
     if (sub === 'models') return cmdModels(rest, { out, c, fail });
     if (sub === 'container') return cmdContainer(rest, { out, c, fail });
+    if (sub === 'broker') {
+      // Loaded lazily: the broker is its own process and needs none of the core graph.
+      const { runBrokerCli } = await import('../broker/main.mjs');
+      return runBrokerCli(rest);
+    }
   }
   // `worca --ui [...]` is the historical spelling of `worca ui start [...]`; hand the
   // remaining tokens to the ui parser so --port/--open/--mock work with either.

package/src/core/agent-pool.mjs

@@ -0,0 +1,76 @@
+// src/core/agent-pool.mjs
+// One agent user per signed-in person (credential broker, docs/credential-broker.md).
+// With a single `worca-agent`, every person's agents share one uid and can read each
+// other's processes — including the broker token in a live spawn's environment. The
+// entrypoint creates a pool (worca-agent-01..16, WORCA_AGENT_POOL) and a HOME for each
+// (WORCA_AGENT_HOMES/<user>); this module gives each person a user of their own, for good:
+// Claude Code keeps a person's sessions in that user's HOME, so a resumed chat or run must
+// land on the same one. Assignments are stored in <worca home>/agent-pool.json.
+//
+// Nobody in particular ('local', no signed-in person) keeps the shared WORCA_AGENT_USER.
+// More people than users: the rest share by a stable hash, with one warning — still
+// better than one uid for everyone, and the operator can raise the pool.
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join } from 'node:path';
+import { agentIdentity } from './agent-user.mjs';
+import { worcaHome } from './projects.mjs';
+
+const USER_RE = /^[a-z_][a-z0-9_-]{0,31}$/;
+let warnedFull = false;
+
+/** {users, homes} when a pool is configured, else null. Pure: reads only `env`. */
+export function agentPool(env = process.env) {
+  const users = String(env.WORCA_AGENT_POOL || '').split(',').map((s) => s.trim()).filter((u) => USER_RE.test(u));
+  const homes = String(env.WORCA_AGENT_HOMES || '').trim();
+  if (!users.length || !isAbsolute(homes)) return null;
+  return { users, homes };
+}
+
+/**
+ * The pool user for `person` given the current assignments. Pure.
+ * @returns {{user:string, assignments:Record<string,string>, shared:boolean}}
+ */
+export function assignPoolUser(person, users, assignments = {}) {
+  if (assignments[person] && users.includes(assignments[person])) return { user: assignments[person], assignments, shared: false };
+  const taken = new Set(Object.values(assignments));
+  const free = users.find((u) => !taken.has(u));
+  if (free) return { user: free, assignments: { ...assignments, [person]: free }, shared: false };
+  const i = createHash('sha256').update(person).digest().readUInt32BE(0) % users.length;
+  return { user: users[i], assignments, shared: true };
+}
+
+function stateFile() { return join(worcaHome(), 'agent-pool.json'); }
+
+function readAssignments(file) {
+  try { return existsSync(file) ? (JSON.parse(readFileSync(file, 'utf8')).people || {}) : {}; } catch { return {}; }
+}
+
+/**
+ * The agent identity for work `person` owns: their pool user (and its HOME), or the shared
+ * agent user when there is no pool or no person, or null when agents run as the server.
+ * @param {string|null} person  a lower-cased email, 'local', or null
+ */
+export function agentIdentityFor(person, env = process.env, { file = null } = {}) {
+  const base = agentIdentity(env);
+  if (!base) return null;
+  const pool = agentPool(env);
+  const who = typeof person === 'string' ? person.trim().toLowerCase() : '';
+  if (!pool || !who || who === 'local' || !who.includes('@')) return base;
+  const f = file || stateFile();
+  const before = readAssignments(f);
+  const r = assignPoolUser(who, pool.users, before);
+  if (r.assignments !== before) {
+    try {
+      const tmp = `${f}.tmp-${process.pid}`;
+      writeFileSync(tmp, JSON.stringify({ people: r.assignments }, null, 2), { mode: 0o600 });
+      renameSync(tmp, f);
+    } catch (err) { console.warn(`[worca] agent pool: could not save the assignment for ${who}: ${err.message}`); }
+  }
+  if (r.shared && !warnedFull) {
+    warnedFull = true;
+    console.warn(`[worca] agent pool: all ${pool.users.length} agent users are assigned; more people now share one. Their agents can read each other's processes.`);
+  }
+  // dedicated: this person's user is theirs alone (not the shared fallback, not hash-shared)
+  return { user: r.user, home: join(pool.homes, r.user), gid: base.gid, dedicated: !r.shared };
+}