@chatpanel/events 0.85.0 → 0.88.0

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;

package/team.js

@@ -16,6 +16,7 @@
 // survive an `origin`, and a team a client stores as trusted is stored as nothing of the kind.
 
 import { validateBudget, normalizeBudget } from './budget.js';
+import { normalizeEngineSpec, validateEngineSpec, tierOf } from './engine.js';
 
 export const TEAM_NAME_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
 export const ROLE_ID_RE = /^[a-z][a-z0-9_-]{0,31}$/i;
@@ -23,10 +24,22 @@ export const ROLE_MODES = Object.freeze(['model', 'subagent', 'recipe']);
 export const ROLE_PREFERS = Object.freeze(['cheap', 'balanced', 'strong']);
 export const MERGE_POLICIES = Object.freeze(['judge', 'converge', 'concat', 'first']);
 export const PLAN_MODES = Object.freeze(['fixed', 'planner']);
-/** The tool groups a role may hold. `mcp:<server>` narrows to one server; `mcp` is all of them. */
-export const GRANTABLE = Object.freeze(['none', 'data', 'web', 'mcp', 'history']);
-export const GRANT_RE = /^(none|data|web|history|mcp|mcp:[a-zA-Z0-9_.:-]{1,64})$/;
+/**
+ * The tool groups a role may hold. `mcp:<server>` narrows to one server; `mcp` is all of them.
+ *
+ * The work grants (architecture-pillars.md §14.2) are for an agent whose engine is a harness
+ * running in a checkout: `shell` and `fs:write` say so explicitly instead of riding along
+ * with the harness; `scm:read` reads the repo and its hub, `scm:push` pushes ITS OWN branch
+ * (`cp/<project>/<job>`), `scm:pr` opens a pull request, and `scm:merge` is held by the
+ * Gate — grantable only where the org's `gate.json` allows it. A chat-model role that holds
+ * one of these holds nothing: only a harness engine can use them, and the bridge enforces it.
+ */
+export const GRANTABLE = Object.freeze(['none', 'data', 'web', 'mcp', 'history', 'shell', 'fs:write', 'scm:read', 'scm:push', 'scm:pr', 'scm:merge']);
+export const WORK_GRANTS = Object.freeze(['shell', 'fs:write', 'scm:read', 'scm:push', 'scm:pr', 'scm:merge']);
+export const GRANT_RE = /^(none|data|web|history|mcp|mcp:[a-zA-Z0-9_.:-]{1,64}|shell|fs:write|scm:(read|push|pr|merge))$/;
 export const MAX_ROLES = 8;
+/** A role that stands for an agent from the pool: `agent` names it (agent.js `AGENT_ID_RE`). */
+export const AGENT_REF_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
 
 export class TeamError extends Error {
   constructor(code, message) { super(message); this.name = 'TeamError'; this.code = code; }
@@ -59,7 +72,11 @@ export function validateTeam(team) {
       if (r.mode !== undefined && !ROLE_MODES.includes(r.mode)) errors.push(`${w}.mode: one of ${ROLE_MODES.join(', ')}`);
       if (r.prefer !== undefined && !ROLE_PREFERS.includes(r.prefer)) errors.push(`${w}.prefer: one of ${ROLE_PREFERS.join(', ')}`);
       if ((r.mode || 'model') === 'recipe' && !r.recipe) errors.push(`${w}.recipe: a recipe name is required in recipe mode`);
-      if ((r.mode || 'model') !== 'recipe' && !String(r.prompt || '').trim()) errors.push(`${w}.prompt: what this role does`);
+      if (r.agent !== undefined && r.agent !== null && !AGENT_REF_RE.test(String(r.agent))) errors.push(`${w}.agent: an agent id`);
+      // A role that stands for an agent takes its prompt from the pool (agent.js resolveTeam);
+      // a role that stands for nobody must say what it does.
+      if ((r.mode || 'model') !== 'recipe' && !r.agent && !String(r.prompt || '').trim()) errors.push(`${w}.prompt: what this role does`);
+      errors.push(...validateEngineSpec(r.engine, `${w}.engine`));
       const bad = (Array.isArray(r.grants) ? r.grants : []).filter((g) => !GRANT_RE.test(String(g)));
       if (bad.length) errors.push(`${w}.grants: not grantable: ${bad.join(', ')}${bad.some((g) => /^page/.test(String(g))) ? ' (a tab is one person\'s; a team may not act on it)' : ''}`);
     });
@@ -89,12 +106,21 @@ export function normalizeTeam(team, { builtin = false } = {}) {
       id: String(r.id),
       name: String(r.name || r.id).slice(0, 60),
       mode: ROLE_MODES.includes(r.mode) ? r.mode : 'model',
-      prefer: ROLE_PREFERS.includes(r.prefer) ? r.prefer : 'balanced',
+      prefer: ROLE_PREFERS.includes(r.prefer) ? r.prefer : (r.engine ? tierOf(r.engine) : 'balanced'),
       ...(r.model ? { model: String(r.model) } : {}),
+      ...(r.agent ? { agent: String(r.agent) } : {}),
+      ...(r.engine ? { engine: normalizeEngineSpec(r.engine) } : {}),
       prompt: String(r.prompt || '').trim().slice(0, 4000),
-      grants: normalizeGrants(r.grants),
+      // A role that stands for an agent holds the agent's grants unless it narrows them: no
+      // list means "the agent's", so the key is left out rather than stored as `none`.
+      ...(r.agent && !(Array.isArray(r.grants) && r.grants.length) ? {} : { grants: normalizeGrants(r.grants) }),
       ...(r.recipe ? { recipe: String(r.recipe) } : {}),
       ...(Array.isArray(r.dependsOn) ? { dependsOn: r.dependsOn.map(String).filter((d) => d !== r.id) } : {}),
+      // What agent.js resolveTeam fills from the pool; kept so the runner's roles carry it.
+      ...(Array.isArray(r.skills) && r.skills.length ? { skills: r.skills.map(String).slice(0, 32) } : {}),
+      ...(r.workdir ? { workdir: String(r.workdir).slice(0, 400) } : {}),
+      ...(r.egress === 'redacted' || r.egress === 'delegated' ? { egress: r.egress } : {}),
+      ...(r.memoryScope ? { memoryScope: String(r.memoryScope).slice(0, 120) } : {}),
     })),
     budget: normalizeBudget(team.budget),
     enabled: team.enabled !== false,
@@ -115,11 +141,25 @@ export function grantAllows(grants, groupId, serverId = '') {
   return g.includes(groupId);
 }
 
+/**
+ * The SCM ladder: `merge` ⊃ `pr` ⊃ `push` ⊃ `read` — a role that may open a PR may push the
+ * branch the PR is from, and anyone who may push may read. `push` is the role's OWN branch
+ * only; the bridge names it (`cp/<project>/<job>`) and refuses any other.
+ */
+const SCM_LADDER = ['read', 'push', 'pr', 'merge'];
+export function scmAllows(grants, action) {
+  const g = normalizeGrants(grants);
+  const want = SCM_LADDER.indexOf(String(action || '').replace(/^scm:/, ''));
+  if (want < 0 || g.includes('none')) return false;
+  const held = Math.max(-1, ...g.filter((x) => x.startsWith('scm:')).map((x) => SCM_LADDER.indexOf(x.slice(4))));
+  return held >= want;
+}
+
 /** One line a person reads per role: name · tier/model · grants · mode. */
 export function describeRole(r) {
   const who = r.model || r.prefer || 'balanced';
   const grants = (r.grants || ['none']).join(', ');
-  return `${r.name || r.id} — ${who}${r.mode && r.mode !== 'model' ? ` (${r.mode})` : ''} · tools: ${grants}`;
+  return `${r.name || r.id}${r.agent ? ` (agent: ${r.agent})` : ''} — ${who}${r.mode && r.mode !== 'model' ? ` (${r.mode})` : ''} · tools: ${grants}`;
 }
 
 // ── Starters and the editor's form ───────────────────────────────────────────────────────
@@ -150,6 +190,55 @@ export const STARTER_TEAMS = Object.freeze([
     ],
     budget: { tokens: 30000, ms: 240000 },
   },
+  // ── The engineering teams (architecture-pillars.md §12.2) — roles stand for the standing
+  // agents in agent.js STARTER_AGENTS; a role's prompt is the agent's, its engine the agent's.
+  // A feature that crosses repos recruits one Implementer per repo (the role says which via
+  // its prompt); these starters name one.
+  {
+    name: 'feature',
+    description: 'Architect plans, an Implementer builds on a branch, Reviewer and Tester check, Scribe writes it up. The Architect judges.',
+    plan: 'planner', merge: 'judge', judge: 'architect',
+    roles: [
+      { id: 'architect', agent: 'architect' },
+      { id: 'implementer', agent: 'implementer', dependsOn: ['architect'] },
+      { id: 'reviewer', agent: 'reviewer', dependsOn: ['implementer'] },
+      { id: 'tester', agent: 'tester', dependsOn: ['implementer'] },
+      { id: 'scribe', agent: 'scribe', dependsOn: ['reviewer', 'tester'] },
+    ],
+    budget: { tokens: 400000, ms: 3600000 },
+  },
+  {
+    name: 'fix',
+    description: 'One Implementer fixes it on a branch, the Tester runs the guard, the Scribe notes it.',
+    plan: 'fixed', merge: 'concat',
+    roles: [
+      { id: 'implementer', agent: 'implementer' },
+      { id: 'tester', agent: 'tester', dependsOn: ['implementer'] },
+      { id: 'scribe', agent: 'scribe', dependsOn: ['tester'] },
+    ],
+    budget: { tokens: 150000, ms: 1800000 },
+  },
+  {
+    name: 'docs',
+    description: 'The Architect decides what the docs should say; the Scribe proposes the text.',
+    plan: 'fixed', merge: 'concat',
+    roles: [
+      { id: 'architect', agent: 'architect' },
+      { id: 'scribe', agent: 'scribe', dependsOn: ['architect'] },
+    ],
+    budget: { tokens: 80000, ms: 900000 },
+  },
+  {
+    name: 'release',
+    description: 'The Tester runs the guard on the merged branch, Release bumps and asks before publishing, the Scribe records the version.',
+    plan: 'fixed', merge: 'concat',
+    roles: [
+      { id: 'tester', agent: 'tester' },
+      { id: 'release', agent: 'release', dependsOn: ['tester'] },
+      { id: 'scribe', agent: 'scribe', dependsOn: ['release'] },
+    ],
+    budget: { tokens: 60000, ms: 1800000 },
+  },
 ]);
 
 /**
@@ -163,7 +252,7 @@ export function slugTeamName(name) {
 
 /** Fresh copies — a starter is a template, never the stored record. */
 export function starterTeams() {
-  return STARTER_TEAMS.map((t) => ({ ...t, roles: t.roles.map((r) => ({ ...r, grants: [...r.grants] })), budget: { ...t.budget } }));
+  return STARTER_TEAMS.map((t) => ({ ...t, roles: t.roles.map((r) => ({ ...r, ...(r.grants ? { grants: [...r.grants] } : {}), ...(r.dependsOn ? { dependsOn: [...r.dependsOn] } : {}) })), budget: { ...t.budget } }));
 }
 
 /** A blank team for the editor: one role, the smallest budget that is still a budget. */
@@ -176,6 +265,7 @@ export function blankTeam() {
  * the budget as numbers that may be blank; a blank judge under `merge: judge` is the last
  * role, which is the writer in every starter.
  */
+const grantsText = (g) => String(Array.isArray(g) ? g.join(',') : g || '').split(/[,\s]+/).map((x) => x.trim()).filter(Boolean);
 export function teamFromForm(form) {
   const roles = (Array.isArray(form.roles) ? form.roles : []).map((r) => ({
     id: String(r.id || '').trim(),
@@ -183,7 +273,12 @@ export function teamFromForm(form) {
     prompt: String(r.prompt || ''),
     prefer: r.prefer || 'balanced',
     ...(r.model ? { model: String(r.model) } : {}),
-    grants: String(Array.isArray(r.grants) ? r.grants.join(',') : r.grants || 'none').split(/[,\s]+/).map((g) => g.trim()).filter(Boolean),
+    ...(r.agent ? { agent: String(r.agent).trim() } : {}),
+    ...(r.engine ? { engine: r.engine } : {}),
+    ...(Array.isArray(r.dependsOn) ? { dependsOn: r.dependsOn.map(String) } : {}),
+    // Blank grants on a role that stands for an agent mean "the agent's"; on any other role
+    // they mean none.
+    ...(grantsText(r.grants).length ? { grants: grantsText(r.grants) } : r.agent ? {} : { grants: ['none'] }),
   }));
   const budget = {};
   for (const k of ['tokens', 'calls', 'ms', 'usd']) {

package/voice-speaker.js

@@ -0,0 +1,98 @@
+// WHOSE VOICE IS THIS — the gate that keeps a conversation to the person having it.
+//
+// In a voice conversation every finalized sentence is SENT, so anything the microphone hears
+// becomes a question: a television, a colleague at the next desk, someone answering their own
+// phone behind you. The engine transcribes them all perfectly and correctly, and the
+// assistant answers the room.
+//
+// The gateway already computes a 512-d speaker fingerprint per committed segment and clusters
+// it into a stable label for the session (`diarize-engine.js`). All that is missing is the
+// DECISION, which is this file: the first voice in a conversation is the person who started
+// it, and later sentences from a different voice are not their turn.
+//
+// THE FAILURE DIRECTION MATTERS MORE THAN THE FEATURE. An assistant that occasionally answers
+// the television is annoying; one that ignores YOU is broken, and from the outside the two
+// look identical — a mic that is open and going nowhere. So every uncertain case sends:
+//
+//   · no speaker on the final (diarization off, model missing, embedding failed) → send;
+//   · no primary enrolled yet → this is the first voice, enroll it and send;
+//   · the primary has not been heard for a long time → adopt whoever is talking now and
+//     send, because the phone may have been handed over, or the first voice may have been
+//     the television while the user was drawing breath.
+//
+// Only one case holds: a DIFFERENT voice, while the person having the conversation is still
+// in it. That is the case the user asked for and the only one we can be confident about.
+//
+// The engine's own honesty note applies here too: embeddings separate different speakers
+// well, but similar voices can merge — so this gate can let a very similar voice through. It
+// never claims to be security, only to keep the room out of the conversation.
+
+/** How long the primary must be silent before another voice may take over the conversation. */
+export const RE_ENROLL_MS = 45_000;
+
+/** A label the gateway pins to the microphone channel; never a guess, so always the primary. */
+export const PINNED_SELF = 'You';
+
+const labelOf = (speaker) => {
+  if (!speaker) return '';
+  if (typeof speaker === 'string') return speaker;
+  return String(speaker.label || speaker.id || '');
+};
+
+/**
+ * A per-conversation speaker gate.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.reEnrollMs]  silence after which another voice may take over
+ * @param {() => number} [opts.now]   injected clock, so the rules are testable without waiting
+ */
+export function createSpeakerGate({ reEnrollMs = RE_ENROLL_MS, now = Date.now } = {}) {
+  let primary = '';        // the label of the person having this conversation
+  let lastHeard = 0;       // when the primary last said something
+  let held = 0;            // sentences kept out, for the UI to report honestly
+
+  return {
+    /** The enrolled voice, or '' before anyone has spoken. */
+    primary: () => primary,
+    /** How many sentences this gate has held back. */
+    heldCount: () => held,
+
+    /**
+     * Should this finalized sentence become a turn?
+     *
+     * @param {{ speaker?: any }} [final]
+     * @returns {{ send: boolean, reason: 'no-speaker'|'enrolled'|'primary'|'adopted'|'other', speaker: string }}
+     */
+    admit(final = {}) {
+      const label = labelOf(final.speaker);
+      // Diarization is optional and fails open — a sentence with no speaker is always sent.
+      if (!label) return { send: true, reason: 'no-speaker', speaker: '' };
+
+      const t = now();
+      if (!primary) {
+        primary = label;
+        lastHeard = t;
+        return { send: true, reason: 'enrolled', speaker: label };
+      }
+      if (label === primary) {
+        lastHeard = t;
+        return { send: true, reason: 'primary', speaker: label };
+      }
+      // A different voice. Only take over when the conversation has clearly moved on.
+      if (t - lastHeard >= reEnrollMs) {
+        primary = label;
+        lastHeard = t;
+        return { send: true, reason: 'adopted', speaker: label };
+      }
+      held += 1;
+      return { send: false, reason: 'other', speaker: label };
+    },
+
+    /**
+     * Forget who was talking. Called when a conversation starts, and by a user who wants the
+     * gate to hear them again — a voice it merged or mislabelled must be recoverable without
+     * ending the session.
+     */
+    reset() { primary = ''; lastHeard = 0; held = 0; },
+  };
+}