@chatpanel/gateway 0.6.87 → 0.6.91

package/src/scorecard.js

@@ -14,11 +14,59 @@
 // against a job's needs with that record — the same function the evaluator starts from, so
 // an application's fit has reasons a person can read and overrule.
 //
+// The model is a variable, not a constant (architecture-pillars.md §13): every task fact also
+// says which ENGINE did it — a model endpoint or a harness (a CLI coding agent), and for a
+// harness the model it was asked to run — so `summarize` can split the card by engine
+// (`byEngine`) and a recruiter can tell an agent that did well on a small model from one
+// that was carried by a large one. And where the task ran in a git checkout (§14), the fact
+// carries `scm`: the branch and HEAD before and after, commits made, a PR when one was
+// opened, and whether it merged — the one outcome that does not come from a judge.
+//
 // Dependency-free: hashing is `crypto.subtle` (browser, Node, a phone), injectable for tests.
 
 export const SCORECARD_ENTRY_KINDS = Object.freeze(['task.done', 'task.failed', 'rating', 'created', 'interaction', 'role']);
 export const ROLE_KINDS = Object.freeze(['ic', 'orchestrator', 'manager', 'manager-of-managers']);
 export const SCORECARD_VERSION = 1;
+export const ENGINE_KINDS = Object.freeze(['model', 'harness']);
+
+/**
+ * An engine as the record keeps it: `{ kind, id, model?, label? }`. `kind` is `model` (an
+ * endpoint the client calls) or `harness` (a CLI coding agent the bridge runs — `id` is the
+ * harness, `model` the model it was asked to run, when one was named). A host that does not
+ * say the kind gets `model`, which is the honest default for a bare model id. A string is
+ * an id.
+ */
+export function normalizeEngine(e) {
+  if (!e) return null;
+  const src = typeof e === 'string' ? { id: e } : e;
+  const id = String(src.id || src.harnessId || src.model || '').trim();
+  if (!id) return null;
+  const kind = ENGINE_KINDS.includes(src.kind) ? src.kind : (src.harnessId ? 'harness' : 'model');
+  const model = src.model != null && String(src.model).trim() && String(src.model) !== id ? String(src.model).trim() : undefined;
+  return { kind, id, ...(model ? { model } : {}), ...(src.label && String(src.label) !== id ? { label: String(src.label).slice(0, 120) } : {}) };
+}
+
+/** One key per engine — what `byEngine` groups on and what the model ledger will be keyed by. */
+export function engineKey(e) {
+  const n = normalizeEngine(e);
+  return n ? `${n.kind}:${n.id}${n.model ? `/${n.model}` : ''}` : null;
+}
+
+/** What a task did in a checkout, as the record keeps it. Strings clipped, counts rounded. */
+export function normalizeScm(s) {
+  if (!s || typeof s !== 'object') return null;
+  const str = (v, n = 200) => (v == null || v === '' ? undefined : String(v).slice(0, n));
+  const out = {
+    repo: str(s.repo, 300), remote: str(s.remote, 300), base: str(s.base, 120), branch: str(s.branch, 120),
+    head: str(s.head, 64), headAfter: str(s.headAfter, 64),
+    commits: s.commits != null ? Math.max(0, Math.round(Number(s.commits) || 0)) : undefined,
+    pr: str(s.pr, 300),
+    merged: s.merged === true ? true : s.merged === false ? false : undefined,
+    dirty: s.dirty === true ? true : s.dirty === false ? false : undefined,
+  };
+  for (const k of Object.keys(out)) if (out[k] === undefined) delete out[k];
+  return Object.keys(out).length ? out : null;
+}
 
 const enc = new TextEncoder();
 const hex = (buf) => [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, '0')).join('');
@@ -61,6 +109,8 @@ export async function makeEntry(fact, prev, { now = () => Date.now(), subtle } =
     ...(fact.runId ? { runId: String(fact.runId) } : {}),
     ...(fact.taskId ? { taskId: String(fact.taskId) } : {}),
     ...(fact.model ? { model: String(fact.model) } : {}),
+    ...(normalizeEngine(fact.engine) ? { engine: normalizeEngine(fact.engine) } : {}),
+    ...(normalizeScm(fact.scm) ? { scm: normalizeScm(fact.scm) } : {}),
     ...(fact.size ? { size: sizeOf(fact.size) } : {}),
     ...(fact.roleKind ? { roleKind: ROLE_KINDS.includes(fact.roleKind) ? fact.roleKind : 'ic' } : {}),
     ...(Array.isArray(fact.tools) && fact.tools.length ? { tools: [...new Set(fact.tools.map(String))].sort() } : {}),
@@ -76,6 +126,7 @@ export async function makeEntry(fact, prev, { now = () => Date.now(), subtle } =
 }
 
 const clamp01 = (n) => Math.max(0, Math.min(1, Number(n) || 0));
+const r3 = (v) => (v == null ? null : Math.round(v * 1000) / 1000);
 const sizeOf = (s) => ({ ms: Math.max(0, Math.round(Number(s.ms) || 0)), steps: Math.max(0, Math.round(Number(s.steps) || 0)), tools: Math.max(0, Math.round(Number(s.tools) || 0)), findings: Math.max(0, Math.round(Number(s.findings) || 0)), tokens: Math.max(0, Math.round(Number(s.tokens) || 0)) });
 
 /** Does every link hold? Returns `{ ok, at }` — `at` is the seq of the first broken entry. */
@@ -121,13 +172,53 @@ export function summarize(entries, { recent = 5 } = {}) {
   const tools = new Set(); const withAgents = new Set(); const created = new Set();
   const roles = { ic: 0, orchestrator: 0, manager: 0, 'manager-of-managers': 0 };
   const models = new Map();
+  // Per engine: how many tasks, how they went, how big, and the ratings that were ABOUT a
+  // task on it. A rating names its task by `about` (the seq of the entry it rates), by
+  // taskId, or — failing both — by runId when that run had exactly one task on the card.
+  const engines = new Map(); // key -> { engine, tasks, done, failed, tokens, ratings[] }
+  const engineOfEntry = new Map(); // seq -> key
+  const byTask = new Map(); const byRun = new Map(); // taskId -> seq, runId -> [seq]
+  const scm = { tasks: 0, commits: 0, prs: 0, merged: 0 };
   for (const e of list) {
     for (const t of e.tools || []) tools.add(t);
     for (const a of e.with || []) withAgents.add(a);
     for (const a of e.created || []) created.add(a);
     if (e.roleKind && (e.kind === 'task.done' || e.kind === 'task.failed' || e.kind === 'role')) roles[e.roleKind] = (roles[e.roleKind] || 0) + 1;
     if (e.model) models.set(e.model, (models.get(e.model) || 0) + 1);
+    if (e.kind === 'task.done' || e.kind === 'task.failed') {
+      const key = engineKey(e.engine);
+      if (key) {
+        const row = engines.get(key) || { engine: normalizeEngine(e.engine), tasks: 0, done: 0, failed: 0, tokens: 0, ratings: [] };
+        row.tasks += 1; row[e.kind === 'task.done' ? 'done' : 'failed'] += 1; row.tokens += e.size?.tokens || 0;
+        engines.set(key, row);
+        engineOfEntry.set(e.seq, key);
+        if (e.taskId) byTask.set(`${e.runId || ''}/${e.taskId}`, e.seq);
+        if (e.runId) byRun.set(e.runId, [...(byRun.get(e.runId) || []), e.seq]);
+      }
+      if (e.scm) { scm.tasks += 1; scm.commits += e.scm.commits || 0; if (e.scm.pr) scm.prs += 1; if (e.scm.merged) scm.merged += 1; }
+    }
+  }
+  for (const e of list) {
+    if (e.kind !== 'rating' || !e.rating) continue;
+    const seq = e.rating.about != null ? e.rating.about
+      : e.taskId && byTask.has(`${e.runId || ''}/${e.taskId}`) ? byTask.get(`${e.runId || ''}/${e.taskId}`)
+        : e.runId && (byRun.get(e.runId) || []).length === 1 ? byRun.get(e.runId)[0] : null;
+    const key = seq != null ? engineOfEntry.get(seq) : null;
+    if (key) engines.get(key).ratings.push(e.rating.score);
   }
+  const mean = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null);
+  const byEngine = [...engines.values()].sort((a, b) => b.tasks - a.tasks).map((r) => ({
+    key: engineKey(r.engine), ...r.engine, tasks: r.tasks, done: r.done, failed: r.failed,
+    failRate: r.tasks ? Math.round((r.failed / r.tasks) * 1000) / 1000 : 0,
+    tokens: r.tasks ? Math.round(r.tokens / r.tasks) : 0, // mean per task — the cost proxy until the ledger prices it
+    rating: { avg: mean(r.ratings), count: r.ratings.length },
+  }));
+  // 1 − spread of rating across engines it was rated on (≥ 2): low spread = robust to routing;
+  // high spread = it NEEDS a particular engine, a fact a recruiter respects, not a penalty.
+  const ratedEngines = byEngine.filter((r) => r.rating.avg != null).map((r) => r.rating.avg);
+  const engineIndependence = ratedEngines.length >= 2 ? Math.round((1 - (Math.max(...ratedEngines) - Math.min(...ratedEngines))) * 1000) / 1000 : null;
+  // Leverage (rating above the engine's own mean) and efficiency (rating ÷ cost) wait on the
+  // model ledger (§13.2, with A1): they need every engine's mean, which one card cannot know.
   const ratings = list.filter((e) => e.kind === 'rating' && e.rating).map((e) => e.rating.score);
   const avg = ratings.length ? ratings.reduce((a, b) => a + b, 0) / ratings.length : null;
   const recentRatings = ratings.slice(-recent);
@@ -143,6 +234,9 @@ export function summarize(entries, { recent = 5 } = {}) {
     created: [...created],
     roles,
     models: [...models.entries()].sort((a, b) => b[1] - a[1]).map(([m, n]) => ({ model: m, tasks: n })),
+    byEngine,
+    engineIndependence,
+    scm,
     rating: { avg, count: ratings.length, recent: recentRatings.length ? recentRatings.reduce((a, b) => a + b, 0) / recentRatings.length : null },
     refs,
     since: list[0]?.at || null,
@@ -157,7 +251,7 @@ export function summarize(entries, { recent = 5 } = {}) {
  * summary is `summarize()`'s. Returns `{ score, reasons }` in [0, 1] — needs first (a type
  * without the tools cannot do the job), track record second, size third.
  */
-export function fit(job, type, summary = null) {
+export function fit(job, type, summary = null, { qualityOf = null, costOf = null, adjust = true } = {}) {
   const needs = job?.needs || {};
   const have = (xs) => new Set((xs || []).map((x) => String(x).toLowerCase()));
   const skills = have(type?.skills); const tools = have(type?.tools); const grants = have(type?.grants);
@@ -175,11 +269,18 @@ export function fit(job, type, summary = null) {
   const needScore = (cSkills * 0.5 + cTools * 0.3 + cGrants * 0.2);
   if (needScore === 1) reasons.push('has every skill, tool and grant the job names');
   let record = 0.5; // a fresh type is neither trusted nor distrusted
+  let adjusted = null;
   if (summary && summary.entries) {
     const doneRate = summary.jobsDone + summary.jobsFailed ? summary.jobsDone / (summary.jobsDone + summary.jobsFailed) : 0.5;
-    const rated = summary.rating.avg == null ? 0.5 : summary.rating.avg;
+    // The track record uses the MODEL-ADJUSTED rating when the caller can say what the
+    // engines were worth (§13.3): an agent rated 0.82 mostly on a weak engine ranks above
+    // one rated 0.82 on a frontier model. The reasons say so, and a person can turn it off.
+    adjusted = adjust && qualityOf && summary.rating.avg != null ? adjustSummary(summary, { qualityOf, costOf: costOf || undefined }) : null;
+    const rated = summary.rating.avg == null ? 0.5 : (adjusted?.adjusted ?? summary.rating.avg);
     record = doneRate * 0.5 + rated * 0.5;
-    reasons.push(`${summary.jobsDone} done, ${summary.jobsFailed} failed${summary.rating.avg != null ? `, rated ${Math.round(summary.rating.avg * 100)}%` : ''}`);
+    reasons.push(`${summary.jobsDone} done, ${summary.jobsFailed} failed${summary.rating.avg != null ? (adjusted && adjusted.adjusted !== adjusted.raw ? `, rated ${Math.round(adjusted.raw * 100)}% raw, ${Math.round(adjusted.adjusted * 100)}% adjusted — ${adjusted.basis[0] || 'engine-corrected'}` : `, rated ${Math.round(summary.rating.avg * 100)}%`) : ''}`);
+    if (adjusted?.leverage != null && adjusted.leverage > 0.05) reasons.push(`adds ${adjusted.leverage} over its engines' own quality`);
+    if (adjusted?.efficiency) reasons.push(`cleared the bar cheapest on ${adjusted.efficiency.engine}`);
     if (summary.roles.orchestrator + summary.roles.manager + summary.roles['manager-of-managers'] > 0) reasons.push(`has led: ${summary.roles.orchestrator} as orchestrator, ${summary.roles.manager} as manager`);
   } else {
     reasons.push('no record yet');
@@ -188,5 +289,48 @@ export function fit(job, type, summary = null) {
   const sizeScore = !wantSize ? 1 : Math.min(1, (summary?.size?.largestSteps || 0) / wantSize) * 0.5 + 0.5;
   if (wantSize && (summary?.size?.largestSteps || 0) < wantSize) reasons.push(`largest task so far ${summary?.size?.largestSteps || 0} steps; this one is ~${wantSize}`);
   const score = Math.round((needScore * 0.6 + record * 0.3 + sizeScore * 0.1) * 1000) / 1000;
-  return { score, reasons, parts: { needs: needScore, record, size: sizeScore } };
+  return { score, reasons, parts: { needs: needScore, record, size: sizeScore }, ...(adjusted ? { adjusted } : {}) };
 }
+
+// ── Agent scores, normalised by engine (§13.3) — what the model ledger's cards make possible ──
+
+/**
+ * The model-adjusted view of an agent's card (scorecard.js `summarize()`), given what its
+ * engines are worth: `qualityOf(key)` → the engine's quality in [0, 1] (the card's mean
+ * rating for the job kind when observed, else the router's guess) or null when unknown.
+ *
+ *   leverage      rating on an engine minus that engine's quality, weighted by tasks — what
+ *                 the agent's prompt and tools add that the model does not supply on its own
+ *   adjusted      the raw rating corrected for the engines it ran on: work done on a weak
+ *                 engine counts for more, on a strong one for less; `k` bounds the correction
+ *   efficiency    adjusted rating ÷ cost per task on the cheapest engine that cleared `bar`
+ *                 (`costOf(key)` → $/task or a token proxy; null when nothing is priced)
+ *
+ * Returns `{ raw, adjusted, leverage, efficiency, basis[] }` with `basis` the reasons a
+ * person reads ("60 % of its tasks ran on a 0.3-quality engine").
+ */
+export function adjustSummary(summary, { qualityOf = () => null, costOf = () => null, reference = 0.6, k = 0.3, bar = 0.5 } = {}) {
+  const raw = summary?.rating?.avg ?? null;
+  const rows = (summary?.byEngine || []).filter((r) => r.key);
+  const known = rows.map((r) => ({ ...r, quality: qualityOf(r.key) })).filter((r) => Number.isFinite(r.quality));
+  const totalTasks = known.reduce((n, r) => n + r.tasks, 0);
+  const basis = [];
+  if (raw == null || !known.length || !totalTasks) return { raw, adjusted: raw, leverage: null, efficiency: null, basis: raw == null ? ['not rated yet'] : ['engines not rated yet — raw rating used'] };
+  // Correction: how far below the reference the engines it ran on sit, task-weighted.
+  const correction = k * known.reduce((s, r) => s + (r.tasks / totalTasks) * (reference - r.quality), 0);
+  const adjusted = Math.max(0, Math.min(1, raw + correction));
+  const weak = known.filter((r) => r.quality < reference);
+  if (weak.length) basis.push(`${Math.round((weak.reduce((n, r) => n + r.tasks, 0) / totalTasks) * 100)} % of its tasks ran on ${weak.length === 1 ? `a ${weak[0].quality}-quality engine` : 'engines below the reference'}`);
+  const strong = known.filter((r) => r.quality > reference);
+  if (strong.length && !weak.length) basis.push(`ran on engines above the reference (${strong.map((r) => r.quality).join(', ')})`);
+  // Leverage over the engines it was rated on.
+  const rated = known.filter((r) => r.rating?.avg != null);
+  const ratedTasks = rated.reduce((n, r) => n + r.rating.count, 0);
+  const leverage = ratedTasks ? r3(rated.reduce((s, r) => s + (r.rating.count / ratedTasks) * (r.rating.avg - r.quality), 0)) : null;
+  if (leverage != null) basis.push(`${leverage >= 0 ? '+' : ''}${leverage} over its engines' own quality`);
+  // Efficiency on the cheapest engine that cleared the bar.
+  const cleared = rated.filter((r) => r.rating.avg >= bar).map((r) => ({ ...r, cost: costOf(r.key) ?? (r.tokens || null) })).filter((r) => r.cost != null && r.cost > 0).sort((a, b) => a.cost - b.cost);
+  const efficiency = cleared.length ? { value: r3(adjusted / cleared[0].cost), engine: cleared[0].key, costPerTask: cleared[0].cost } : null;
+  return { raw: r3(raw), adjusted: r3(adjusted), leverage, efficiency, basis };
+}
+

package/src/server.js

@@ -36,6 +36,9 @@ import { createMemoryStore } from './memory-store.js';
 import { createPrefsStore } from './prefs-store.js';
 import { createTeamStore, loadOrCreateKey as loadTeamKey } from './team-store.js';
 import { createScorecardStore } from './scorecard-store.js';
+import { createEngineLedgerStore } from './engine-ledger-store.js';
+import { createProjectStore } from './project-store.js';
+import { applicationsFor, recruitPass } from './recruiting.js';
 import { createHistoryStore } from './sqlite-store.js';
 import { ingestBackups } from './backup-ingest.js';
 import * as nerEngine from './ner-engine.js';
@@ -59,7 +62,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.87';
+export const VERSION = '0.6.91';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -69,7 +72,9 @@ const historyStore = await createHistoryStore();
 const memoryStore = await createMemoryStore();
 const prefsStore = createPrefsStore();
 const scorecards = createScorecardStore({ key: loadTeamKey() });
-const teamStore = createTeamStore({ scorecards });
+const engines = createEngineLedgerStore({ key: loadTeamKey() });
+const projectStore = createProjectStore({ key: loadTeamKey() });
+const teamStore = createTeamStore({ scorecards, engines });
 // Who is watching prefs change — a client with a live subscription is told the moment a
 // section is written by the other client, instead of waiting for its next focus.
 const prefsWatchers = new Set();
@@ -165,6 +170,12 @@ function fmtTimings(t) {
 //   restore  model output → harness[restore] → user response (non-stream; for
 //            streams restore is inline per chunk, so it's folded into stream)
 //   total    end-to-end through the gateway
+/** `model:<id>[/<model>]` / `harness:<id>[/<model>]` → the record's engine, or null. */
+function engineFromKey(key) {
+  const m = /^(model|harness):([^/]+)(?:\/(.+))?$/.exec(String(key || ''));
+  return m ? { kind: m[1], id: m[2], ...(m[3] ? { model: m[3] } : {}) } : null;
+}
+
 function mkTrace(sink) {
   const start = performance.now();
   const timings = {};
@@ -397,8 +408,12 @@ async function pumpRelay(res, s, shaper, trace) {
 }
 
 // New tool-enabled turn: open the bridge with the client's tools as MCP specs.
-async function startRelay(req, res, { kind, adapter, agent }, body, vault, cfg, isPro, tools, harness = null, trace = null) {
+async function startRelay(req, res, { kind, adapter, agent, run = null }, body, vault, cfg, isPro, tools, harness = null, trace = null) {
   const { messages, system } = adapter.toTurn(body);
+  // The model half of `claude/opus` and the team role's run options travel with a
+  // tool-using turn the same as with a plain one (handleBridge below).
+  const { agentModel } = parseAgentModel(body?.model, cfg);
+  const options = bridgeAgentOptions(cfg, { ...(agentModel ? { model: agentModel } : {}), ...(run || {}) });
   const token = readBridgeToken(cfg.bridge.token);
   const shaper = shaperFor(kind, body?.model || agent);
   // Full tier for everyone here (the free allowance is enforced in the main
@@ -412,7 +427,7 @@ async function startRelay(req, res, { kind, adapter, agent }, body, vault, cfg,
   // redaction in the main handler), so toTurn() carried it here — nothing to add.
   let resp;
   try {
-    resp = await openBridgeChat({ bridgeUrl, agent, token, messages, system, specs: toolsToSpecs(tools), options: bridgeAgentOptions(cfg), signal: undefined });
+    resp = await openBridgeChat({ bridgeUrl, agent, token, messages, system, specs: toolsToSpecs(tools), options, signal: undefined });
   } catch (e) { endRelaySession(s.id); trace?.commit(); return sendJson(res, 502, { error: { message: `bridge: ${e.message}`, type: 'bridge_error' } }); }
   s.reader = resp.body.getReader();
   res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
@@ -436,7 +451,7 @@ async function resumeRelay(res, s, toolContent, model, trace = null) {
   return pumpRelay(res, s, shaper, trace);
 }
 
-async function handleBridge(req, res, { kind, adapter, redactable, pathname, agentOverride, harness, trace }, body, vault, cfg, isPro) {
+async function handleBridge(req, res, { kind, adapter, redactable, pathname, agentOverride, harness, trace, run = null }, body, vault, cfg, isPro) {
   if (!redactable) {
     trace?.commit();
     return sendJson(res, 404, { error: `endpoint ${pathname} not supported by the bridge backend` });
@@ -455,7 +470,7 @@ async function handleBridge(req, res, { kind, adapter, redactable, pathname, age
     }
     const tools = adapter.extractTools(body);
     if (tools.length && body?.stream === true) {
-      return startRelay(req, res, { kind, adapter, agent: agentOverride || pickAgent(body?.model, cfg) }, body, vault, cfg, isPro, tools, harness, trace);
+      return startRelay(req, res, { kind, adapter, agent: agentOverride || pickAgent(body?.model, cfg), run }, body, vault, cfg, isPro, tools, harness, trace);
     }
   }
 
@@ -481,7 +496,7 @@ async function handleBridge(req, res, { kind, adapter, redactable, pathname, age
     bridgeUrl: await resolveBridgeUrl(cfg), agent, token, messages, system, signal: ac.signal,
     // Permissions and working directory from the gateway's config (the desktop's Settings →
     // Engine → Agents), plus the model half of `claude/opus` when the caller named one.
-    options: bridgeAgentOptions(cfg, agentModel ? { model: agentModel } : {}),
+    options: bridgeAgentOptions(cfg, { ...(agentModel ? { model: agentModel } : {}), ...(run || {}) }),
   };
 
   if (!wantStream) {
@@ -708,7 +723,7 @@ export function createGateway(cfg = loadConfig()) {
     // Client preferences travel between the extension and the desktop through here, and an
     // MCP server entry can carry an Authorization header — so READS are gated too, unlike
     // history and memory. A drive-by page must not learn what tools the user connected.
-    if ((pathname === '/v1/prefs' || pathname.startsWith('/v1/prefs/') || pathname.startsWith('/v1/teams') || pathname.startsWith('/v1/agents')) && !isAdminAuthorized(req)) {
+    if ((pathname === '/v1/prefs' || pathname.startsWith('/v1/prefs/') || pathname.startsWith('/v1/teams') || pathname.startsWith('/v1/agents') || pathname.startsWith('/v1/projects')) && !isAdminAuthorized(req)) {
       return sendJson(res, 403, { error: { message: 'prefs: extension origin or gateway token required', type: 'forbidden' } });
     }
     // The access log is who-read-what — sensitive, and writable only by the local MCP
@@ -822,6 +837,87 @@ export function createGateway(cfg = loadConfig()) {
       return undefined;
     }
 
+    // --- PROJECTS. The page a goal starts on and everything done for it (project-store.js):
+    //   GET  /v1/projects[?limit&status]        → { ok, projects }   newest activity first, jobs counted
+    //   POST /v1/projects { id, project, by }    → { ok, project }    open a record (idempotent) / update the page
+    //   GET  /v1/projects/jobs                   → { ok, jobs }       the job board: every open posting across projects
+    //   GET  /v1/projects/:id[?events=1]         → { ok, project }    the record: jobs, runs, spend, decisions, report
+    //   POST /v1/projects/:id/events { events }  → { ok, project }    the executive loop appends (status, run.linked, run.spent, decision, report)
+    //   POST /v1/projects/:id/jobs { job, by }   → { ok, project }    post a job
+    //   POST /v1/projects/:id/jobs/:jobId { patch, by } → { ok, project }  move it along its machine / applications / recruited / result
+    //   GET  /v1/projects/:id/jobs/:jobId/applications[?reach&chatModel] → { ok, job, applications, prompt, rows }
+    //                                              the pool applies at once (recruiting.js); `prompt` is the evaluator's, for the client's structured call
+    //   POST /v1/projects/:id/jobs/:jobId/recruit { by, reach, chatModel, evaluation? | text? } → { ok, project, decision, applications }
+    //                                              one pass: fit recomputed here, the client's evaluation read through the schema, the pick (or the
+    //                                              proposal) landed as events — with no evaluation the fit decides
+    //   GET  /v1/projects/:id/events[?after]     (SSE)                hello, replay, then live
+    //   DELETE /v1/projects/:id
+    if (pathname === '/v1/projects' && req.method === 'GET') return sendJson(res, 200, { ok: true, projects: projectStore.list({ limit: url.searchParams.get('limit') || 50, status: url.searchParams.get('status') || '' }) });
+    if (pathname === '/v1/projects/jobs' && req.method === 'GET') return sendJson(res, 200, { ok: true, jobs: projectStore.openJobs() });
+    if (pathname === '/v1/projects' && req.method === 'POST') {
+      try {
+        const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+        return sendJson(res, 200, { ok: true, project: projectStore.create({ id: body.id || body.project?.id, project: body.project || null, by: body.by }) });
+      } catch (e) { return sendJson(res, 400, { error: { message: `project: ${e.message}`, type: 'project_error' } }); }
+    }
+    {
+      const m = /^\/v1\/projects\/([a-zA-Z0-9_-]{1,64})(\/events|\/jobs(?:\/([a-zA-Z0-9_-]{1,64})(\/applications|\/recruit)?)?)?$/.exec(pathname);
+      if (m) {
+        const id = m[1]; const sub = m[2] || ''; const jobId = m[3] || ''; const act = m[4] || '';
+        const notFound = () => sendJson(res, 404, { error: { message: `no project ${id}`, type: 'not_found' } });
+        if (act) {
+          const rec = projectStore.get(id);
+          if (!rec) return notFound();
+          const job = rec.jobs.find((j) => j.id === jobId);
+          if (!job) return sendJson(res, 404, { error: { message: `no job ${jobId}`, type: 'not_found' } });
+          const stores = { cfg, prefsStore, scorecards, engines };
+          if (act === '/applications' && req.method === 'GET') {
+            const out = await applicationsFor(job, { ...stores, reach: url.searchParams.get('reach') || 'any', chatModel: url.searchParams.get('chatModel') || null });
+            return sendJson(res, 200, { ok: true, job, ...out });
+          }
+          if (act === '/recruit' && req.method === 'POST') {
+            if (!['open', 'evaluating'].includes(job.status)) return sendJson(res, 400, { error: { message: `job ${jobId} is ${job.status}; only an open job is recruited`, type: 'project_error' } });
+            try {
+              const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+              const by = String(body.by || 'evaluator').slice(0, 80);
+              const pass = await recruitPass(job, { ...stores, record: rec, reach: body.reach || 'any', chatModel: body.chatModel || null, evaluation: body.evaluation || null, text: body.text ?? null, by });
+              // Through the store's own moves, so the job's machine is checked on every step.
+              let project = null;
+              for (const e of pass.events) {
+                if (e.type === 'job.updated') project = projectStore.updateJob(id, jobId, e.job, { by: e.by || by });
+                else project = projectStore.append(id, [e]);
+              }
+              return sendJson(res, 200, { ok: true, project, decision: pass.decision, applications: pass.applications, evaluation: pass.evaluation });
+            } catch (e) { return sendJson(res, 400, { error: { message: `recruit: ${e.message}`, type: 'project_error' } }); }
+          }
+          return sendJson(res, 405, { error: { message: 'method not allowed', type: 'project_error' } });
+        }
+        if (!sub && req.method === 'GET') { const p = projectStore.get(id, { events: url.searchParams.get('events') === '1' }); return p ? sendJson(res, 200, { ok: true, project: p }) : notFound(); }
+        if (!sub && req.method === 'DELETE') return sendJson(res, 200, { ok: true, removed: projectStore.remove(id) });
+        if (req.method === 'POST' && (sub === '/events' || sub.startsWith('/jobs'))) {
+          try {
+            const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+            const by = String(body.by || 'person').slice(0, 80);
+            const project = sub === '/events' ? projectStore.append(id, body.events || [])
+              : jobId ? projectStore.updateJob(id, jobId, body.patch || body, { by })
+                : projectStore.postJob(id, body.job || body, { by });
+            return sendJson(res, 200, { ok: true, project });
+          } catch (e) { return sendJson(res, e.message.startsWith('no ') ? 404 : 400, { error: { message: `project: ${e.message}`, type: 'project_error' } }); }
+        }
+        if (sub === '/events' && req.method === 'GET') {
+          if (!projectStore.get(id)) return notFound();
+          res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+          const sendEv = (ev) => res.write(`data: ${JSON.stringify(ev)}\n\n`);
+          let last = url.searchParams.has('after') ? Number(url.searchParams.get('after')) : -1;
+          sendEv({ seq: -1, type: 'hello', at: Date.now(), payload: { project: projectStore.get(id), after: last } });
+          const off = projectStore.watch(id, (ev) => { if (ev.seq > last) { last = ev.seq; sendEv(ev); } });
+          for (const ev of projectStore.eventsSince(id, last)) { last = ev.seq; sendEv(ev); }
+          const beat = setInterval(() => { try { res.write(': keep\n\n'); } catch { /* closed */ } }, 25_000);
+          req.on('close', () => { clearInterval(beat); off(); });
+          return undefined;
+        }
+      }
+    }
     // --- SCORECARDS. Every agent's attested record (scorecard-store.js): the chain, its card,
     //     whether it verifies; a person's rating appended from either client.
     if (pathname === '/v1/agents/scorecards' && req.method === 'GET') return sendJson(res, 200, { ok: true, agents: scorecards.list() });
@@ -834,11 +930,43 @@ export function createGateway(cfg = loadConfig()) {
           try {
             const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
             const entry = await scorecards.append({ agentId, kind: 'rating', runId: body.runId, taskId: body.taskId, jobId: body.jobId, rating: { by: String(body.by || 'person').slice(0, 40), score: body.score, note: body.note, about: body.about }, refs: body.refs });
+            // The verdict is the engine's too: it lands on the ledger of what served the task.
+            engines.fromRating(scorecards.chains.get(agentId) || [], { ...entry, jobKind: body.jobKind ? String(body.jobKind).slice(0, 60) : undefined });
             return sendJson(res, 200, { ok: true, entry });
           } catch (e) { return sendJson(res, 400, { error: { message: `scorecard: ${e.message}`, type: 'scorecard_error' } }); }
         }
       }
     }
+    // --- ENGINES. Every model's / harness's attested ledger (engine-ledger-store.js): the
+    //     card a client feeds applyCard, the chain on request; a host's observed call, a
+    //     person's price or capability proof appended from either client.
+    //   GET  /v1/engines[?minCalls]                → { ok, engines: [card] }
+    //   GET  /v1/engines/:key/card[?entries=1]     → { ok, key, card, entries?, verified?, attested? }
+    //   POST /v1/engines/:key/entries { kind, engine, call|rating|price|capability|declined, … }
+    if (pathname === '/v1/engines' && req.method === 'GET') {
+      const minCalls = Number(url.searchParams.get('minCalls')) || undefined;
+      return sendJson(res, 200, { ok: true, engines: engines.list({ minCalls }) });
+    }
+    {
+      const m = /^\/v1\/engines\/(.+)\/(card|entries)$/.exec(pathname);
+      if (m) {
+        const key = decodeURIComponent(m[1]).slice(0, 300);
+        if (m[2] === 'card' && req.method === 'GET') {
+          const minCalls = Number(url.searchParams.get('minCalls')) || undefined;
+          return sendJson(res, 200, { ok: true, ...(await engines.get(key, { entries: url.searchParams.get('entries') === '1', minCalls })) });
+        }
+        if (m[2] === 'entries' && req.method === 'POST') {
+          try {
+            const body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')) || {};
+            const engine = body.engine || engineFromKey(key);
+            if (!engine) return sendJson(res, 400, { error: { message: 'model-ledger: engine required', type: 'model_ledger_error' } });
+            const entry = await engines.append({ ...body, engine, kind: body.kind || 'call' });
+            if (entry.key !== key) return sendJson(res, 400, { error: { message: `model-ledger: entry is for ${entry.key}, not ${key}`, type: 'model_ledger_error' } });
+            return sendJson(res, 200, { ok: true, entry });
+          } catch (e) { return sendJson(res, 400, { error: { message: `model-ledger: ${e.message}`, type: 'model_ledger_error' } }); }
+        }
+      }
+    }
     // --- TEAM RUNS. The board every client can read (team-store.js).
     //   GET  /v1/teams/runs[?limit&team]     → { ok, runs }            newest first, no boards
     //   POST /v1/teams/runs { id, team, request, client } → { ok, run }
@@ -2031,6 +2159,10 @@ export function createGateway(cfg = loadConfig()) {
     const hint = {
       destination: String(req.headers['x-chatpanel-destination'] || legacy?.destination || '').trim(),
       reach: String(req.headers['x-chatpanel-reach'] || legacy?.reach || '').trim(),
+      // A TEAM ROLE'S RUN, for the bridge (pillars §14.2): `{ grants, workspace, connectionId }`
+      // — URI-encoded JSON in a header (the body belongs to the provider), the legacy body
+      // field also honoured. Only the bridge path reads it; an API destination never sees it.
+      run: readRunHint(req.headers['x-chatpanel-run'], legacy?.run),
     };
     const dest = resolveDestination(body?.model, cfg, r.kind, { destination: hint.destination });
     // An EXPLICIT destination that does not resolve is an error, not an invitation to fall
@@ -2057,10 +2189,25 @@ export function createGateway(cfg = loadConfig()) {
       }
       return handleApi(req, res, { ...r, pathname, search: url.search, base: dest.baseUrl, destKey: dest.apiKey, destProtocol: dest.protocol, harness, trace }, outBody, vault);
     }
-    return handleBridge(req, res, { ...r, pathname, agentOverride: dest?.agent, harness, trace }, body, vault, cfg, isPro);
+    return handleBridge(req, res, { ...r, pathname, agentOverride: dest?.agent, harness, trace, run: hint.run }, body, vault, cfg, isPro);
   });
 }
 
+/** `{ grants[], workspace{ repo, projectId, jobId, base? }, connectionId }` from the header or the legacy field — shaped, never a token. */
+function readRunHint(header, legacy) {
+  let raw = legacy && typeof legacy === 'object' ? legacy : null;
+  if (!raw && header) { try { raw = JSON.parse(decodeURIComponent(String(header))); } catch { raw = null; } }
+  if (!raw || typeof raw !== 'object') return null;
+  const out = {};
+  if (Array.isArray(raw.grants)) out.grants = raw.grants.map((g) => String(g).slice(0, 80)).slice(0, 32);
+  if (raw.workspace && typeof raw.workspace === 'object' && raw.workspace.repo) {
+    const w = raw.workspace;
+    out.workspace = { repo: String(w.repo).slice(0, 400), projectId: String(w.projectId || '').slice(0, 120), jobId: String(w.jobId || '').slice(0, 120), ...(w.base ? { base: String(w.base).slice(0, 120) } : {}) };
+  }
+  if (raw.connectionId) out.connectionId = String(raw.connectionId).slice(0, 64);
+  return Object.keys(out).length ? out : null;
+}
+
 export function start(cfg = loadConfig()) {
   installTimestampedConsole(); // every gateway log line gets a clock — before anything logs
   ensureGatewayToken(); // M2: load/create the admin-route token (best-effort)

package/src/team-store.js

@@ -58,8 +58,9 @@ const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)
 export function applyEvent(run, ev) { return foldRun(run, ev); }
 
 export class TeamStore {
-  constructor({ storePath = STORE_PATH, now = () => Date.now(), staleAfterMs = STALE_AFTER_MS, scorecards = null } = {}) {
+  constructor({ storePath = STORE_PATH, now = () => Date.now(), staleAfterMs = STALE_AFTER_MS, scorecards = null, engines = null } = {}) {
     this.scorecards = scorecards; // the agents' ledgers (scorecard-store.js), fed by task.scored
+    this.engines = engines; // the engines' ledgers (engine-ledger-store.js), fed by task.routed / reappointed / handoff / scored
     this.path = storePath;
     this.now = now;
     this.staleAfterMs = staleAfterMs;
@@ -134,6 +135,8 @@ export class TeamStore {
       applyEvent(run, ev);
       // A finished task's fact goes to the member's scorecard — chained and attested there.
       if (this.scorecards && ev.type === 'task.scored') this.scorecards.fromRunEvent(ev, run);
+      // …and to the engine's ledger: the call, or the decline / rotation that preceded it.
+      if (this.engines && (ev.type === 'task.routed' || ev.type === 'task.reappointed' || ev.type === 'task.handoff' || ev.type === 'task.scored')) this.engines.fromRunEvent(ev, run);
       for (const fn of this.watchers.get(run.id) || []) { try { fn(ev); } catch { /* a dead watcher */ } }
     }
     this.save();