@chatpanel/events 0.85.0 → 0.89.0

package/scm-connection.js

@@ -0,0 +1,180 @@
+// An SCM CONNECTION — how a harness engine reaches the organisation's source-control hub —
+// and the two names a job gets in it: its branch and its worktree directory.
+// (architecture-pillars.md §14: the repository is the source of truth.)
+//
+// ChatPanel is not a git host and not a git client. The harness runs `git`, `gh`, `glab`;
+// ChatPanel brings the CREDENTIAL, the WORKTREE, the BRANCH NAME and the RECORD. This module
+// is the pure part: what a connection record holds, how a remote URL maps to one, what a
+// job's branch is called, and the environment that hands a token to git for ONE process
+// without writing it anywhere.
+//
+// THE TOKEN IS NEVER IN THE RECORD. A connection stores a `secretRef` — the name under which
+// the machine's keychain (or the bridge's secret store) holds the token. The record travels
+// with the client-prefs document (`connections` section) so both clients show the same
+// connections; the secret does not travel, and `normalizeConnection` REFUSES a record that
+// carries one, so a settings export, a sync, or a prompt can never carry it either.
+
+export const SCM_KINDS = Object.freeze(['github', 'github-enterprise', 'gitlab', 'bitbucket', 'gitea', 'azure-devops', 'git']);
+export const CONNECTION_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+export const SECRET_REF_RE = /^[a-zA-Z0-9_.:@/-]{1,200}$/;
+const SECRET_FIELDS = ['token', 'password', 'secret', 'pat', 'apiKey', 'key'];
+const DEFAULT_HOST = { github: 'github.com', gitlab: 'gitlab.com', bitbucket: 'bitbucket.org', 'azure-devops': 'dev.azure.com' };
+
+export class ScmError extends Error {
+  constructor(code, message) { super(message); this.name = 'ScmError'; this.code = code; }
+}
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** The host a connection serves: its baseUrl's, or the kind's public host. */
+export function hostOf(conn) {
+  const url = String(conn?.baseUrl || '').trim();
+  if (url) { try { return new URL(/^https?:\/\//i.test(url) ? url : `https://${url}`).host.toLowerCase(); } catch { return url.toLowerCase().replace(/^https?:\/\//, '').split('/')[0]; } }
+  return DEFAULT_HOST[conn?.kind] || '';
+}
+
+export function validateConnection(conn) {
+  const errors = [];
+  if (!isRecord(conn)) return { ok: false, errors: ['connection must be an object'] };
+  if (!CONNECTION_ID_RE.test(String(conn.id || ''))) errors.push('id: a short identifier (letters, digits, _ -)');
+  if (!SCM_KINDS.includes(conn.kind)) errors.push(`kind: one of ${SCM_KINDS.join(', ')}`);
+  const needsHost = ['github-enterprise', 'gitea', 'git'].includes(conn.kind);
+  if (needsHost && !String(conn.baseUrl || '').trim()) errors.push('baseUrl: the hub\'s URL');
+  if (conn.baseUrl && !/^(https?:\/\/)?[a-z0-9.-]+(:\d+)?(\/[^\s]*)?$/i.test(String(conn.baseUrl).trim())) errors.push('baseUrl: a host or URL');
+  const leaked = SECRET_FIELDS.filter((k) => conn[k] !== undefined && conn[k] !== null && conn[k] !== '');
+  if (leaked.length) errors.push(`${leaked.join(', ')}: a connection never stores a secret — store it in the keychain and reference it by secretRef`);
+  if (conn.secretRef !== undefined && conn.secretRef !== null && conn.secretRef !== '' && !SECRET_REF_RE.test(String(conn.secretRef))) errors.push('secretRef: a keychain / secret-store name');
+  if (conn.reach !== undefined && !Array.isArray(conn.reach)) errors.push('reach: a list of remotes or owners this connection may be used for');
+  return { ok: errors.length === 0, errors };
+}
+
+/** The stored form. Throws on a record that carries a secret. */
+export function normalizeConnection(conn) {
+  const v = validateConnection(conn);
+  if (!v.ok) throw new ScmError('INVALID', v.errors.join('; '));
+  const id = String(conn.id);
+  return {
+    id,
+    kind: conn.kind,
+    label: String(conn.label || conn.name || '').trim().slice(0, 80) || `${conn.kind} · ${hostOf(conn) || id}`,
+    ...(conn.baseUrl ? { baseUrl: String(conn.baseUrl).trim().replace(/\/+$/, '') } : {}),
+    // The secret's NAME — `chatpanel:scm:<id>` by default — under which the keychain holds it.
+    secretRef: String(conn.secretRef || '').trim() || `chatpanel:scm:${id}`,
+    ...(conn.username ? { username: String(conn.username).trim().slice(0, 80) } : {}),
+    // Which remotes it may be used for: `owner/*`, `owner/name`, or a host. Empty = any on its host.
+    reach: (Array.isArray(conn.reach) ? conn.reach : []).map((r) => String(r).trim().toLowerCase()).filter(Boolean).slice(0, 64),
+    enabled: conn.enabled !== false,
+    ...(conn.createdAt ? { createdAt: conn.createdAt } : {}),
+  };
+}
+
+/**
+ * A remote URL, read: `{ host, owner, name, protocol }` for https, ssh (`git@host:o/n.git`,
+ * `ssh://git@host/o/n`) and plain `host/o/n`. Credentials in the URL are dropped, never
+ * returned. Null for what cannot be read.
+ */
+export function parseRemote(url) {
+  const s = String(url || '').trim();
+  if (!s) return null;
+  let m = /^(?:ssh:\/\/)?(?:[\w.-]+@)?([a-z0-9.-]+)(?::\d+)?[:/]+([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(s.replace(/^https?:\/\/(?:[^@/]+@)?/i, ''));
+  if (m && !/^https?:/i.test(s)) return { host: m[1].toLowerCase(), owner: m[2], name: m[3], protocol: /^ssh:|^[\w.-]+@/.test(s) ? 'ssh' : 'plain' };
+  try {
+    const u = new URL(s);
+    const parts = u.pathname.replace(/\.git$/, '').split('/').filter(Boolean);
+    if (parts.length < 2) return null;
+    // Azure DevOps: /org/project/_git/repo; GitLab subgroups: /a/b/c/repo — owner is all but the last.
+    const name = parts.at(-1);
+    const owner = parts.slice(0, -1).filter((p) => p !== '_git').join('/');
+    return { host: u.host.toLowerCase(), owner, name, protocol: u.protocol.replace(':', '') };
+  } catch { return null; }
+}
+
+/**
+ * The connection to use for a remote: enabled, same host, and — when the connection lists
+ * a reach — the remote's `owner/name` or `owner/*` in it. The most specific reach wins.
+ */
+export function connectionFor(remote, connections = []) {
+  const r = typeof remote === 'string' ? parseRemote(remote) : remote;
+  if (!r) return null;
+  const slug = `${r.owner}/${r.name}`.toLowerCase();
+  let best = null; let bestScore = -1;
+  for (const c of connections || []) {
+    if (!c || c.enabled === false) continue;
+    if (hostOf(c) !== r.host) continue;
+    const reach = Array.isArray(c.reach) ? c.reach : [];
+    let score = reach.length ? -1 : 0;
+    for (const x of reach) {
+      if (x === slug) score = Math.max(score, 3);
+      else if (x.endsWith('/*') && slug.startsWith(x.slice(0, -1))) score = Math.max(score, 2);
+      else if (x === r.host) score = Math.max(score, 1);
+    }
+    if (score > bestScore) { best = c; bestScore = score; }
+  }
+  return best;
+}
+
+const slug = (s) => String(s || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 48) || 'x';
+
+/** A job's branch: `cp/<project>/<job>` — one branch per job, always under `cp/`, never a protected name. */
+export function branchFor(projectId, jobId) { return `cp/${slug(projectId)}/${slug(jobId)}`; }
+
+/** A job's worktree directory under the bridge's worktree root: `<project>/<job>`. */
+export function worktreeDirFor(projectId, jobId) { return `${slug(projectId)}/${slug(jobId)}`; }
+
+/**
+ * The environment that hands ONE process the token, scoped to the connection's host:
+ * git's `credential.<url>.helper` set through `GIT_CONFIG_*` (never a file, never the
+ * command line), a helper that reads the token from the environment, terminal prompts
+ * off, and the hub CLIs' own variables (`GH_TOKEN` / `GH_HOST`, `GITLAB_TOKEN`) so `gh` and
+ * `glab` work in the same process. The caller spawns with `{ ...process.env, ...env }` and
+ * the token dies with the process.
+ */
+export function credentialEnv(conn, token, { username = null } = {}) {
+  const c = conn || {};
+  const host = hostOf(c);
+  if (!host || !token) return {};
+  const user = username || c.username || ({ github: 'x-access-token', 'github-enterprise': 'x-access-token', gitlab: 'oauth2', bitbucket: 'x-token-auth', gitea: 'oauth2', 'azure-devops': 'pat' }[c.kind] || 'token');
+  const env = {
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_COUNT: '2',
+    GIT_CONFIG_KEY_0: `credential.https://${host}.helper`,
+    // A shell helper: on `get`, answer from the environment. Nothing is written anywhere.
+    GIT_CONFIG_VALUE_0: '!f() { if [ "$1" = get ]; then printf "username=%s\\npassword=%s\\n" "$CHATPANEL_SCM_USER" "$CHATPANEL_SCM_TOKEN"; fi; }; f',
+    GIT_CONFIG_KEY_1: `credential.https://${host}.useHttpPath`,
+    GIT_CONFIG_VALUE_1: 'false',
+    CHATPANEL_SCM_USER: user,
+    CHATPANEL_SCM_TOKEN: String(token),
+  };
+  if (c.kind === 'github' || c.kind === 'github-enterprise') {
+    env.GH_TOKEN = String(token);
+    if (c.kind === 'github-enterprise') { env.GH_ENTERPRISE_TOKEN = String(token); env.GH_HOST = host; }
+  }
+  if (c.kind === 'gitlab') { env.GITLAB_TOKEN = String(token); env.GITLAB_HOST = host; }
+  return env;
+}
+
+/** One line a person reads: "GitHub · github.com · acme/*". */
+export function describeConnection(conn) {
+  const c = conn || {};
+  const kindLabel = { github: 'GitHub', 'github-enterprise': 'GitHub Enterprise', gitlab: 'GitLab', bitbucket: 'Bitbucket', gitea: 'Gitea', 'azure-devops': 'Azure DevOps', git: 'Git' }[c.kind] || c.kind;
+  return `${kindLabel} · ${hostOf(c)}${c.reach?.length ? ` · ${c.reach.join(', ')}` : ''}${c.enabled === false ? ' (off)' : ''}`;
+}
+
+export function blankConnection() { return { id: '', kind: 'github', label: '', baseUrl: '', reach: [], username: '' }; }
+
+/** The editor's form → a connection, or the errors. The token is NOT part of the form's record: the host stores it separately. */
+export function connectionFromForm(form) {
+  const f = form || {};
+  const id = String(f.id || '').trim() || slug(f.label || `${f.kind}-${hostOf(f)}`);
+  const conn = {
+    id, kind: f.kind || 'github', label: String(f.label || '').trim(),
+    ...(f.baseUrl ? { baseUrl: String(f.baseUrl).trim() } : {}),
+    ...(f.username ? { username: String(f.username).trim() } : {}),
+    ...(f.secretRef ? { secretRef: String(f.secretRef).trim() } : {}),
+    reach: String(Array.isArray(f.reach) ? f.reach.join(',') : f.reach || '').split(/[,\s]+/).map((x) => x.trim()).filter(Boolean),
+    enabled: f.enabled !== false,
+    ...(f.createdAt ? { createdAt: f.createdAt } : {}),
+  };
+  const v = validateConnection(conn);
+  return v.ok ? { ok: true, connection: normalizeConnection(conn) } : { ok: false, errors: v.errors };
+}

package/scorecard.js

@@ -13,11 +13,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('');
@@ -60,6 +108,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() } : {}),
@@ -75,6 +125,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. */
@@ -120,13 +171,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);
@@ -142,6 +233,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,
@@ -156,7 +250,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);
@@ -174,11 +268,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');
@@ -187,5 +288,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/team-run.js

@@ -17,6 +17,7 @@
 // says so (`status: 'over-budget'`). Stop is one signal, fanned out.
 
 import { normalizeTeam } from './team.js';
+import { normalizeEngine, normalizeScm } from './scorecard.js';
 import { createBudget } from './budget.js';
 import { fixedPlan, plannerPrompt, parsePlan, waves } from './team-plan.js';
 import { createBoard, parseFindings, boardText, findingsInstruction, toBriefClaims, RUNNER } from './team-board.js';
@@ -79,9 +80,15 @@ export function dryRunTeam(team, request, { appoint = null } = {}) {
 
 /**
  * @param callModel  `async ({ runId, taskId, role, model, mode, system, prompt, tools, signal, onDelta }) =>
- *                   { ok, text, usage?, error?, aborted? }` — the host's model turn
+ *                   { ok, text, usage?, error?, aborted?, scm? }` — the host's model turn; `scm`
+ *                   is what a harness did in a git checkout (`{ repo, branch, head, headAfter,
+ *                   commits }`), when the bridge reported one
  * @param toolsFor   `(role) => toolset | undefined` — narrowed to the role's grants by the host
- * @param appoint    `(role) => { model, mode } | null` — the host's roster through cowriter-router
+ * @param appoint    `(role) => { model, mode, engine?, reasons?, alternatives? } | null` — the host's
+ *                   roster through cowriter-router. `engine` (`{ kind: 'model'|'harness', id,
+ *                   model? }`) says WHAT the model id is, so the record can split by it;
+ *                   `reasons` and `alternatives` are why this one and who else could have —
+ *                   said as `task.routed`, which every run records from here on (pillars §13)
  * @param runRecipe  `async (name, params) => result` for `mode: 'recipe'` roles (optional)
  * @param emit       `(type, payload)` — run.started · plan.ready · task.started · task.finding ·
  *                   task.done · task.failed · run.merging · run.done; the host forwards them to
@@ -129,6 +136,21 @@ export async function runTeam({
     return (appoint ? appoint(r, { exclude }) : null) || (r.model && !exclude?.has(r.model) ? { model: r.model, mode: r.mode } : null);
   };
   const MAX_APPOINTMENTS = 3;
+  // The routing decision, on the record: which engine, why, who else could have. A host that
+  // does not say the kind gets `model` — the honest default for a bare id; the pilot's hosts
+  // both say. Exploration (a tier cheaper on purpose) is the project loop's, later; false here.
+  const routeOf = (m, role, { attempt = 1, exclude = null, handoff = null } = {}) => {
+    const reasons = Array.isArray(m.reasons) ? m.reasons.map(String) : [];
+    if (handoff) reasons.unshift(`handed off by ${handoff.by}${handoff.reason ? ` — ${handoff.reason}` : ''}`);
+    else if (!reasons.length && role.model && m.model === role.model) reasons.push('pinned by the role');
+    if (attempt > 1 && exclude?.size) reasons.push(`after ${[...exclude].join(', ')} (unavailable)`);
+    return {
+      engine: normalizeEngine(m.engine || { id: m.model }),
+      reasons,
+      alternatives: (Array.isArray(m.alternatives) ? m.alternatives : []).slice(0, 5).map((a) => normalizeEngine(a)).filter(Boolean),
+      exploration: false,
+    };
+  };
   // A model that was not there for one member is not there for the next: what failed as
   // unavailable anywhere in this run is skipped by every later appointment. Two members
   // each spent two minutes finding out the same agent was down.
@@ -199,6 +221,8 @@ export async function runTeam({
       // the record. Only a task that has never been attempted starts from the bare prompt.
       let transcript = was ? [...was.transcript] : [];
       const attempts = was?.attempts ? [...was.attempts] : [];
+      let routed = null; // the last routing decision, on the task row
+      let scm = null; // what the last attempt did in a checkout
       // The task's own abort: an ask nobody answered in time stops THIS member's turn (the
       // run then checkpoints), without stopping the run's other members. A person's hand-off
       // aborts it too, and names where the task continues.
@@ -250,6 +274,7 @@ export async function runTeam({
           let lastModel = was?.attempts?.at?.(-1)?.model || null;
           for (let attempt = 1; ; attempt++) {
             let m;
+            const handoffNow = handoffTo;
             if (handoffTo) {
               // A person's hand-off names the model; the task continues there whatever the
               // roster would have chosen. Said on the board, so everyone knows who has it.
@@ -267,7 +292,9 @@ export async function runTeam({
             if (attempt > 1 && lastErr) say('task.reappointed', { taskId: task.id, role: role.id, model: m.model, after: [...exclude], error: lastErr });
             // Who is doing this task, for a ledger that shows the lanes — said per attempt.
             say('task.model', { taskId: task.id, role: role.id, model: m.model, attempt });
-            attempts.push({ model: m.model, at: now(), continued: !!note });
+            routed = routeOf(m, role, { attempt, exclude, handoff: handoffNow });
+            say('task.routed', { taskId: task.id, role: role.id, attempt, ...routed });
+            attempts.push({ model: m.model, engine: routed.engine, at: now(), continued: !!note });
             const sent = messagesFor({ transcript }, { prompt, note });
             // The record grows AS THE ATTEMPT GOES: a host that reports each wire message the
             // moment it exists (a tool call, its result) puts it on the record then, so a
@@ -283,6 +310,8 @@ export async function runTeam({
             });
             usage = res?.usage || null;
             if (usage) budget.charge(usage);
+            // What the attempt did in a checkout, when the host's harness reported one (§14).
+            if (normalizeScm(res?.scm)) { scm = normalizeScm(res.scm); say('task.scm', { taskId: task.id, role: role.id, ...scm }); }
             // Whatever the attempt did is the task's now — on the record, before any verdict.
             // What the host already reported step by step is not reported again.
             transcript = mergeTranscript(sent, res);
@@ -327,14 +356,14 @@ export async function runTeam({
       if (findings.length) { board.add(findings); for (const f of findings) say('task.finding', { taskId: task.id, role: role.id, finding: f }); }
       const thread = board.threadForTask(task.id);
       if (thread && status !== 'waiting') board.setThreadStatus(thread.id, 'resolved');
-      const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, transcript: clipTranscript(transcript), attempts, ...(askedAndWaiting ? { waitingOn: askedAndWaiting } : {}) };
+      const row = { id: task.id, role: task.role, title: task.title, status, text, error, usage, ms: now() - t0, findings, transcript: clipTranscript(transcript), attempts, ...(routed ? { routed } : {}), ...(scm ? { scm } : {}), ...(askedAndWaiting ? { waitingOn: askedAndWaiting } : {}) };
       tasksOut.push(row);
       say(status === 'ok' ? 'task.done' : 'task.failed', { taskId: task.id, role: task.role, status, error, ms: row.ms, findings: findings.length, ...(askedAndWaiting ? { threadId: askedAndWaiting } : {}) });
       // The fact for the member's scorecard (scorecard.js): how big, with what, alongside whom,
       // in which role — produced here, attested by the store, never written by the agent.
       if (status === 'ok' || status === 'failed') {
         say('task.scored', {
-          agentId: role.agent || role.id, taskId: task.id, role: role.id, model: lastModelOf(attempts), outcome: status === 'ok' ? 'task.done' : 'task.failed',
+          agentId: role.agent || role.id, taskId: task.id, role: role.id, model: lastModelOf(attempts), engine: routed?.engine || null, scm: scm || undefined, outcome: status === 'ok' ? 'task.done' : 'task.failed',
           size: { ms: row.ms, steps: (row.transcript || []).length, tools: (row.transcript || []).filter((m) => m.role === 'tool').length, findings: findings.length, tokens: usage ? Number(usage.input_tokens || usage.prompt_tokens || 0) + Number(usage.output_tokens || usage.completion_tokens || 0) : 0 },
           roleKind: 'ic', tools: toolNamesOf(row.transcript), with: t.roles.filter((r) => r.id !== role.id).map((r) => r.agent || r.id),
           refs: [`run:${id}`, ...(board.threadForTask(task.id) ? [`thread:${board.threadForTask(task.id).id}`] : [])], error: error || undefined,
@@ -383,11 +412,15 @@ export async function runTeam({
       let res = null;
       const excl = new Set();
       let judgeErr = '';
+      let judgeModel = null; // the appointment that answered (or the last one tried)
+      let judgeRoute = null;
       for (let attempt = 1; attempt <= MAX_APPOINTMENTS; attempt++) {
         const mm = attempt === 1 ? (runExclude.has(m?.model) ? modelFor(judge, excluding(excl)) : m) : modelFor(judge, excluding(excl));
         if (!mm?.model) break;
         if (attempt > 1) say('task.reappointed', { taskId: 'merge', role: judge.id, model: mm.model, after: [...excl], error: judgeErr });
         say('task.model', { taskId: 'merge', role: judge.id, model: mm.model, attempt });
+        judgeModel = mm; judgeRoute = routeOf(mm, judge, { attempt, exclude: excl });
+        say('task.routed', { taskId: 'merge', role: judge.id, attempt, ...judgeRoute });
         res = await callModel({ runId: id, taskId: 'merge', role: judge.id, model: mm.model, mode: 'model', system: judge.prompt, prompt, tools: judgeTools, signal, onDelta: (delta, full) => say('task.delta', { taskId: 'merge', role: judge.id, delta, text: full }) });
         if (res?.usage) budget.charge(res.usage);
         if (res?.ok && String(res.text || '').trim()) break;
@@ -397,7 +430,9 @@ export async function runTeam({
       }
       const judged = res?.ok && String(res.text || '').trim();
       say(judged ? 'task.done' : 'task.failed', { taskId: 'merge', role: judge.id, status: judged ? 'ok' : 'failed', error: judged ? null : (res?.error || 'the judge did not answer'), findings: 0 });
-      say('task.scored', { agentId: judge.id, taskId: 'merge', role: judge.id, model: res ? (excl.size ? [...excl].at(-1) : m?.model) : m?.model, outcome: judged ? 'task.done' : 'task.failed', size: { ms: 0, steps: 1, tools: 0, findings: board.all().length, tokens: 0 }, roleKind: 'orchestrator', tools: [], with: t.roles.filter((r) => r.id !== judge.id).map((r) => r.agent || r.id), refs: [`run:${id}`] });
+      const judgeScm = normalizeScm(res?.scm);
+      if (judgeScm) say('task.scm', { taskId: 'merge', role: judge.id, ...judgeScm });
+      say('task.scored', { agentId: judge.id, taskId: 'merge', role: judge.id, model: judgeModel?.model || m?.model, engine: judgeRoute?.engine || null, scm: judgeScm || undefined, outcome: judged ? 'task.done' : 'task.failed', size: { ms: 0, steps: 1, tools: 0, findings: board.all().length, tokens: 0 }, roleKind: 'orchestrator', tools: [], with: t.roles.filter((r) => r.id !== judge.id).map((r) => r.agent || r.id), refs: [`run:${id}`] });
       say('run.usage', { usage: budget.snapshot() });
       proposal = judged ? { kind: 'answer', text: String(res.text || ''), by: judge.id } : mergeCheap(t, board.all(), tasksOut);
     } else {

package/team-tool.js

@@ -36,7 +36,7 @@ export function teamToolSpec(teams) {
       + '{"action":"dry_run","name":"<team>","request":"…"} shows roles, models, tools and budget without running; '
       + '{"action":"save","team":{…}} proposes a NEW team after a task that would benefit from several roles — the user approves it on a card. '
       + 'A team: {"name":"research" (a short identifier: letters, digits, - _; used as /research),"description":"…","roles":[{"id":"researcher","prompt":"…","prefer":"balanced","grants":["data","web"]},{"id":"writer","prompt":"…","prefer":"strong","grants":["none"]}],"merge":"judge","judge":"writer","budget":{"tokens":40000,"ms":300000}}. '
-      + 'grants: none | data | web | history | mcp | mcp:<server>. merge: judge | converge | concat | first. A budget is required. '
+      + 'grants: none | data | web | history | mcp | mcp:<server> | shell | fs:write | scm:read | scm:push | scm:pr. A role may say "agent":"<id>" instead of a prompt to stand for an agent from the pool. merge: judge | converge | concat | first. A budget is required. '
       + 'Order the work with "dependsOn": a role that builds on another\'s findings (a budget checker on a researcher) lists it, so it runs after and reads the board instead of searching again. The judge does not need a task of its own - the merge is its work.',
     parameters: {
       type: 'object',
@@ -70,8 +70,16 @@ const json = (v) => JSON.stringify(v);
  * @param confirmSave  `async (detail, team) => 'allow' | 'deny'`; absent = save refused
  * @param saveTeam     `async (team) => void`
  */
-export function teamToolProvider({ teams = [], run = null, appoint = null, confirmSave = null, saveTeam = null } = {}) {
+/**
+ * `resolve` is the host's `(team) => team` that fills roles standing for agents from the
+ * pool (agent.js resolveTeam) — applied before a dry run and before a run, never to what is
+ * saved: the stored team keeps its references, the run gets the cards as they are now.
+ */
+export function teamToolProvider({ teams = [], run = null, appoint = null, confirmSave = null, saveTeam = null, resolve = null } = {}) {
   const byName = new Map(usable(teams).map((t) => [t.name, t]));
+  // A team whose roles stand for agents is filled from the pool on the way to a run; a
+  // resolver that throws (an agent missing from the pool) is the tool's error, not a crash.
+  const resolved = (t) => (typeof resolve === 'function' ? resolve(t) : t);
   let bound = null;
   // One run per team+request per turn. A run that failed, answered with nothing, or ran
   // out of budget comes back as a result the model must REPORT — asking for it again in the
@@ -97,7 +105,7 @@ export function teamToolProvider({ teams = [], run = null, appoint = null, confi
         if (byName.has(team.name)) return json({ error: `A team named "${team.name}" already exists. Pick another name.` });
         if (!confirmSave || !saveTeam) return json({ error: 'Saving a team needs the user\'s approval, which this surface cannot ask for. Describe the team and suggest saving it from the side panel or the desktop.' });
         const norm = normalizeTeam(team);
-        const dry = dryRunTeam(norm, '', { appoint });
+        const dry = dryRunTeam(resolved(norm), '', { appoint });
         const decision = await confirmSave(describeTeamForApproval(norm, dry), norm);
         if (decision !== 'allow') return json({ error: `The user did not save "${norm.name}". Do not propose it again this turn.`, declined: true });
         const stored = { ...norm, createdAt: Date.now() };
@@ -111,7 +119,8 @@ export function teamToolProvider({ teams = [], run = null, appoint = null, confi
       const request = String(input?.request || '').trim();
 
       if (action === 'dry_run') {
-        const dry = dryRunTeam(team, request, { appoint });
+        let dry;
+        try { dry = dryRunTeam(resolved(team), request, { appoint }); } catch (e) { return json({ error: e?.message || String(e) }); }
         return json({ name: team.name, ok: dry.ok, missing: dry.missing, roles: dry.roles, plan: dry.plan, tasks: dry.tasks, merge: dry.merge, budget: dry.budget });
       }
       if (action === 'run') {
@@ -123,9 +132,10 @@ export function teamToolProvider({ teams = [], run = null, appoint = null, confi
         const key = team.name;
         const prior = ran.get(key);
         if (prior) return json({ error: `The "${team.name}" team already ran in this turn (run ${prior.runId}, ${prior.status}). Do not run it again, even with a different request: report what it produced — ${prior.summary} — with its proposal, and ask the user how to proceed.`, runId: prior.runId, status: prior.status, tasks: prior.tasks, proposal: prior.proposal });
-        const dry = dryRunTeam(team, request, { appoint });
+        let dry;
+        try { dry = dryRunTeam(resolved(team), request, { appoint }); } catch (e) { return json({ error: e?.message || String(e) }); }
         if (!dry.ok) return json({ error: `No model is available for role(s): ${dry.missing.join(', ')}.`, roles: dry.roles });
-        const result = await run({ team, request, toolset: bound });
+        const result = await run({ team: resolved(team), request, toolset: bound });
         const findings = (result.board || []).map((f) => ({ role: f.role, kind: f.kind, text: f.text, refs: f.refs }));
         const tasks = (result.tasks || []).map((x) => ({ id: x.id, role: x.role, status: x.status, ms: x.ms, findings: (x.findings || []).length, error: x.error || undefined }));
         const failed = tasks.filter((x) => x.status !== 'ok');

package/team-trail.js

@@ -19,6 +19,10 @@ export function teamLine(ev) {
     case 'task.handoff': return { type: 'status', text: `${role} handed off ${ev.from ? `from ${ev.from} ` : ''}to ${ev.to} by ${ev.by || 'person'}${ev.reason ? ` — ${ev.reason}` : ''}` };
     case 'task.step': return null;
     case 'task.scored': return null;
+    // The route is the lane's business (task.model already names it); the reasons are a line
+    // only when there are any — a re-appointment says its own.
+    case 'task.routed': return ev.reasons?.length && ev.attempt === 1 ? { type: 'status', text: `${role} → ${ev.engine?.id || '?'}${ev.engine?.model ? `/${ev.engine.model}` : ''} (${ev.reasons.join('; ')})` } : null;
+    case 'task.scm': return ev.commits ? { type: 'status', text: `${role} committed ${ev.commits} on ${ev.branch || 'a branch'}${ev.headAfter ? ` @ ${String(ev.headAfter).slice(0, 7)}` : ''}` } : null;
     case 'task.reappointed': return { type: 'status', text: `${role} → ${ev.model} (${(ev.after || []).join(', ')} unavailable${ev.error ? `: ${String(ev.error).slice(0, 120)}` : ''})` };
     case 'task.tool': return { type: 'tool', name: ev.name, text: `${role} ran ${ev.name}${ev.text ? ` — ${ev.text}` : ''}` };
     case 'task.finding': return { type: 'status', text: `${role}: ${String(ev.finding?.text || '').slice(0, 140)}` };
@@ -40,6 +44,8 @@ export function teamLanes(prev, ev) {
     case 'task.delta': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], text: ev.text }; break;
     case 'task.finding': lanes.findings += 1; if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], findings: (lanes.tasks[ev.taskId].findings || 0) + 1 }; break;
     case 'task.model': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], model: ev.model }; break;
+    case 'task.routed': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], engine: ev.engine || null }; break;
+    case 'task.scm': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], scm: { branch: ev.branch, commits: ev.commits || 0, head: ev.headAfter || ev.head } }; break;
     case 'task.handoff': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], model: ev.to, handoffs: (lanes.tasks[ev.taskId].handoffs || 0) + 1 }; break;
     case 'task.step': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], steps: (lanes.tasks[ev.taskId].steps || 0) + (ev.steps || []).length }; break;
     case 'task.tool': if (lanes.tasks[ev.taskId]) lanes.tasks[ev.taskId] = { ...lanes.tasks[ev.taskId], tools: (lanes.tasks[ev.taskId].tools || 0) + 1, lastTool: ev.text ? `${ev.name} ${ev.text}` : ev.name }; break;