@chatpanel/gateway 0.6.90 → 0.6.91

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.90",
+  "version": "0.6.91",
   "description": "Local privacy gateway \u2014 redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -0,0 +1,250 @@
+// VENDORED from @chatpanel/events/agent.js — edit there, then copy over.
+// An AGENT, as data — the pool an org recruits from. Nothing runs here.
+//
+// A team's roles were inlined: each carried its own prompt, tier and grants, so the same
+// "researcher" existed once per team and an edit landed in one of them. An agent is the role
+// definition promoted out of the team (F8 §8 A1, architecture-pillars.md §9): a persistent
+// identity — name, purpose, prompt, skills, grants, egress class, ENGINE, memory namespace —
+// with a scorecard the runner writes and the store attests (scorecard.js). One agent stands
+// in many teams; a team's role says `agent: <id>` and `resolveTeam` fills the role from the
+// pool at run time, so the runner (team-run.js) is unchanged.
+//
+// The engine is a field on the card, never a nav item: `model` / `harness` / `auto` /
+// `assistant` (engine.js). The built-in ASSISTANT is the agent behind every plain chat: its
+// engine is whichever model the chat is on, which is why `engineOf` takes the chat's model.
+//
+// Trust is derived, never declared (the team.js rule): `builtin` only when the host says so.
+// Grants are the team's vocabulary (team.js GRANT_RE), including the work grants a harness
+// engine may hold; `page` is never grantable. The pool is shared through the client-prefs
+// document (`agents` section) like teams, skills and recipes.
+
+import { normalizeGrants, GRANT_RE, TeamError, normalizeTeam, slugTeamName } from './team.js';
+import { normalizeEngineSpec, validateEngineSpec, describeEngine, engineRef, tierOf } from './engine.js';
+
+export const AGENT_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+export const APPLIES_TO = Object.freeze(['jobs', 'meetings', 'notes']);
+export const EGRESS_CLASSES = Object.freeze(['redacted', 'delegated']);
+export const MAX_SKILLS = 32;
+export const ASSISTANT_ID = 'assistant';
+
+export class AgentError extends Error {
+  constructor(code, message) { super(message); this.name = 'AgentError'; this.code = code; }
+}
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const list = (xs, n, max) => [...new Set((Array.isArray(xs) ? xs : typeof xs === 'string' ? xs.split(/[,\s]+/) : []).map((x) => String(x || '').trim().slice(0, n)).filter(Boolean))].slice(0, max);
+
+export function validateAgent(agent) {
+  const errors = [];
+  if (!isRecord(agent)) return { ok: false, errors: ['agent must be an object'] };
+  if (!AGENT_ID_RE.test(String(agent.id || ''))) errors.push('id: a short identifier (letters, digits, _ -)');
+  if (!String(agent.name || agent.id || '').trim()) errors.push('name: what to call it');
+  if (!String(agent.prompt || '').trim() && String(agent.id) !== ASSISTANT_ID) errors.push('prompt: what this agent does');
+  errors.push(...validateEngineSpec(agent.engine, 'engine'));
+  const bad = (Array.isArray(agent.grants) ? agent.grants : []).filter((g) => !GRANT_RE.test(String(g)));
+  if (bad.length) errors.push(`grants: not grantable: ${bad.join(', ')}${bad.some((g) => /^page/.test(String(g))) ? ' (a tab is one person\'s; an agent may not act on it)' : ''}`);
+  if (agent.egress !== undefined && agent.egress !== null && !EGRESS_CLASSES.includes(agent.egress)) errors.push(`egress: one of ${EGRESS_CLASSES.join(', ')}`);
+  if (agent.appliesTo !== undefined && (!Array.isArray(agent.appliesTo) || agent.appliesTo.some((a) => !APPLIES_TO.includes(a)))) errors.push(`appliesTo: a list of ${APPLIES_TO.join(', ')}`);
+  if (agent.skills !== undefined && !Array.isArray(agent.skills) && typeof agent.skills !== 'string') errors.push('skills: a list of skill names');
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * The stored form. Defaults filled, grants normalized, engine normalized, trust derived. The
+ * memory namespace defaults to the agent's own (`agent:<id>`); a team may point several
+ * agents at one shared namespace by naming it.
+ */
+export function normalizeAgent(agent, { builtin = false } = {}) {
+  const v = validateAgent(agent);
+  if (!v.ok) throw new AgentError('INVALID', v.errors.join('; '));
+  const id = String(agent.id);
+  return {
+    id,
+    name: String(agent.name || id).trim().slice(0, 60),
+    purpose: String(agent.purpose || '').trim().slice(0, 300),
+    prompt: String(agent.prompt || '').trim().slice(0, 8000),
+    skills: list(agent.skills, 80, MAX_SKILLS),
+    grants: normalizeGrants(agent.grants),
+    engine: normalizeEngineSpec(agent.engine),
+    ...(EGRESS_CLASSES.includes(agent.egress) ? { egress: agent.egress } : {}),
+    appliesTo: Array.isArray(agent.appliesTo) && agent.appliesTo.length ? [...new Set(agent.appliesTo.filter((a) => APPLIES_TO.includes(a)))] : ['jobs'],
+    memoryScope: String(agent.memoryScope || '').trim().slice(0, 120) || `agent:${id}`,
+    ...(agent.workdir ? { workdir: String(agent.workdir).trim().slice(0, 400) } : {}),
+    createdBy: String(agent.createdBy || 'person').slice(0, 80),
+    enabled: agent.enabled !== false,
+    ...(agent.origin && isRecord(agent.origin) ? { origin: { ...agent.origin } } : {}),
+    ...(builtin ? { builtin: true } : {}),
+    ...(agent.createdAt ? { createdAt: agent.createdAt } : {}),
+  };
+}
+
+export function defineAgent(agent, opts) { return Object.freeze(normalizeAgent(agent, opts)); }
+
+/**
+ * The built-in Assistant — the agent behind every plain chat. Its engine is the chat's model
+ * (`engineOf` resolves it); its grants are whatever the chat has; it applies everywhere.
+ */
+export function assistantAgent({ grants = ['data', 'web', 'history', 'mcp'] } = {}) {
+  return defineAgent({
+    id: ASSISTANT_ID, name: 'Assistant', purpose: 'The chat itself: answers, uses the tools you connected, remembers what you tell it.',
+    prompt: '', engine: 'assistant', grants, appliesTo: ['jobs', 'meetings', 'notes'], createdBy: 'chatpanel',
+  }, { builtin: true });
+}
+
+/**
+ * WHAT RUNS this agent's turns, resolved: the Assistant's engine is the chat's model (the
+ * host passes `chatModel` as `{ providerId?, model }` or a string), which is why the
+ * Assistant has no engine of its own. Everything else returns its normalized spec. A legacy
+ * role (no `engine`) reads as `model` when it pins one, else `auto` at its tier.
+ */
+export function engineOf(agentOrRole, { chatModel = null } = {}) {
+  const a = agentOrRole || {};
+  if (a.engine !== undefined && a.engine !== null) {
+    const s = normalizeEngineSpec(a.engine);
+    if (s.kind !== 'assistant') return s;
+    if (chatModel) return normalizeEngineSpec(typeof chatModel === 'string' ? chatModel : { kind: 'model', providerId: chatModel.providerId, model: chatModel.model || chatModel.id });
+    return { kind: 'auto', policy: { prefer: 'balanced' } };
+  }
+  if (a.model) return normalizeEngineSpec({ kind: 'model', model: a.model });
+  const prefer = { cheap: 'cheapest-that-clears', strong: 'best-quality', balanced: 'balanced' }[a.prefer] || 'balanced';
+  return { kind: 'auto', policy: { prefer } };
+}
+
+/** The capability strip's first column (§8): what kind of thing this agent is, in a word. */
+export function describeAgent(agent, opts) {
+  const a = agent || {};
+  return `${a.name || a.id} — ${describeEngine(a.engine, opts)} · tools: ${(a.grants || ['none']).join(', ')}${a.skills?.length ? ` · skills: ${a.skills.join(', ')}` : ''}`;
+}
+
+export function slugAgentId(name) { return slugTeamName(name); }
+
+/**
+ * A team as the runner needs it: every role that says `agent` is filled from the pool —
+ * prompt, grants, skills, engine, working directory — and the role's own fields narrow it.
+ *
+ *   • prompt   the agent's, then the role's ("In this team: …") when the role adds one
+ *   • grants   the agent's, narrowed to the role's when the role lists any (a team may not
+ *              widen an agent; it may lend less)
+ *   • engine   the role's override when it has one, else the agent's, with the Assistant
+ *              resolved to `chatModel`; `prefer` follows for today's appointers
+ *   • model    what `callModel` is handed — `targetFor(engine)` when the host maps engines
+ *              to its target ids (the extension's endpoint ids, the desktop's gateway ids),
+ *              else the harness id or the model name
+ *
+ * A role naming an agent not in the pool throws NO_AGENT: a team is not run with a hole in
+ * it. Returns the normalized team plus `agents` — the resolved cards, by role id.
+ */
+export function resolveTeam(team, pool = [], { chatModel = null, targetFor = null } = {}) {
+  const t = normalizeTeam(team);
+  const byId = new Map((Array.isArray(pool) ? pool : []).filter((a) => a && a.id).map((a) => [String(a.id), a]));
+  const agents = {};
+  const roles = t.roles.map((r) => {
+    if (!r.agent) return r;
+    const raw = byId.get(r.agent) || (r.agent === ASSISTANT_ID ? assistantAgent() : null);
+    if (!raw) throw new TeamError('NO_AGENT', `role "${r.id}" names agent "${r.agent}", which is not in the pool`);
+    const a = normalizeAgent(raw, { builtin: !!raw.builtin });
+    if (a.enabled === false) throw new TeamError('NO_AGENT', `agent "${a.id}" is disabled`);
+    agents[r.id] = a;
+    const engine = engineOf(r.engine ? { engine: r.engine } : a, { chatModel });
+    const ref = engineRef(engine);
+    const target = ref ? (targetFor ? targetFor(engine, a) : (engine.kind === 'harness' ? engine.harnessId : engine.model)) : null;
+    const grants = !Array.isArray(r.grants) ? a.grants
+      : a.grants.includes('none') ? ['none']
+        : normalizeGrants(r.grants.filter((g) => a.grants.includes(g) || (g.startsWith('mcp:') && a.grants.includes('mcp'))));
+    const prompt = [a.prompt, r.prompt ? `In this team: ${r.prompt}` : ''].filter(Boolean).join('\n\n').slice(0, 8000);
+    return {
+      ...r,
+      name: r.name === r.id ? a.name : r.name,
+      prompt,
+      grants,
+      engine,
+      prefer: engine.kind === 'auto' ? tierOf(engine) : r.prefer,
+      ...(target ? { model: r.model || target } : {}),
+      ...(a.skills.length ? { skills: [...a.skills] } : {}),
+      ...(a.workdir ? { workdir: a.workdir } : {}),
+      ...(a.egress ? { egress: a.egress } : {}),
+      ...(a.memoryScope ? { memoryScope: a.memoryScope } : {}),
+    };
+  });
+  return { ...t, roles, agents };
+}
+
+// ── The standing org and the editor's form ────────────────────────────────────────────────
+//
+// "ChatPanel Engineering" (architecture-pillars.md §12.2) — the first standing agents,
+// offered as starters the way `research` and `review` are for teams. Every Implementer is
+// this ONE card with a different working directory: the org repo's `agents/*.json` (§14.3)
+// is where a company keeps one per repo. Engines are `auto` / `harness:<id>` so a starter
+// does not name a provider a person may not have; the Harness engines say `claude` because
+// that is the bridge's id for Claude Code and the pilot's choice — change it on the card.
+
+export const STARTER_AGENTS = Object.freeze([
+  { id: 'architect', name: 'Architect', purpose: 'Reads the docs and the repos; writes the project page and the jobs.',
+    prompt: 'You are the Architect. Read the feature doc, ROADMAP.md, naming-revamp.md and architecture-pillars.md before deciding anything. Write the project page (goal, done-when, budget) and post one job per repo that must change, saying which repo and what the guard is. Propose a new agent type only when no one in the pool fits. Never run a shell.',
+    skills: [], grants: ['data', 'history'], engine: { kind: 'auto', policy: { prefer: 'best-quality' } }, appliesTo: ['jobs'] },
+  { id: 'implementer', name: 'Implementer', purpose: 'Builds one job on a branch in one repo; runs the guard; posts on the thread. Never pushes to main, never publishes.',
+    prompt: 'You are an Implementer. Work only in the repository you were given, on the branch named for this job. Read the job thread first. Make the change, run the repository\'s guard (tools/test-*.mjs or npm test) until it passes, commit with a message that says what and why, and post a summary with the diff stat on the job thread. Do not push to main, do not publish, do not touch another repository.',
+    skills: [], grants: ['shell', 'fs:write', 'scm:read', 'scm:push', 'scm:pr'], engine: { kind: 'harness', harnessId: 'claude' }, appliesTo: ['jobs'] },
+  { id: 'reviewer', name: 'Reviewer', purpose: 'Reads the branch diff; posts findings on the thread. Approve or reject is a person\'s.',
+    prompt: 'You are the Reviewer. Read the diff of the job\'s branch against its base. Post each finding as a reply on the job thread: what, where (file:line), why it matters, what to do instead. Do not edit files. Do not approve or reject — say what you found and let a person decide.',
+    skills: ['review'], grants: ['shell', 'scm:read'], engine: { kind: 'harness', harnessId: 'claude' }, appliesTo: ['jobs'] },
+  { id: 'tester', name: 'Tester', purpose: 'Runs the repository\'s guard on the branch; reports the result. No writes.',
+    prompt: 'You are the Tester. Check out the job\'s branch in its worktree and run the repository\'s guard (tools/test-*.mjs, npm test, the build). Report pass/fail with the failing output verbatim. Do not change any file.',
+    skills: [], grants: ['shell', 'scm:read'], engine: { kind: 'harness', harnessId: 'claude' }, appliesTo: ['jobs'] },
+  { id: 'librarian', name: 'Librarian', purpose: 'Before every job: what was already done for this, and where.',
+    prompt: 'You are the Librarian. Before a job starts, search the runs, boards, briefs and docs for work that already covers it. Reply on the job thread with "already done in …" pointers and what could be reused or extended. Never do the job yourself.',
+    skills: [], grants: ['data', 'history'], engine: { kind: 'auto', policy: { prefer: 'cheapest-that-clears' } }, appliesTo: ['jobs'] },
+  { id: 'scribe', name: 'Scribe', purpose: 'Writes what the run taught into the roadmap and the status row — proposed, a person lands it.',
+    prompt: 'You are the Scribe. From the run\'s board and scorecards, write the "what this run taught" paragraph for the feature doc, the ROADMAP.md entry and the IMPLEMENTATION-STATUS.md row. Post them as a proposal on the thread; a person lands them. Say plainly what did not work.',
+    skills: [], grants: ['data', 'history'], engine: { kind: 'auto', policy: { prefer: 'balanced' } }, appliesTo: ['jobs', 'notes'] },
+  { id: 'release', name: 'Release', purpose: 'Version bump and changelog on the merged branch; asks before publish or push.',
+    prompt: 'You are Release. On the merged branch: bump the version, write the changelog line, run the guard. Before `npm publish` or any `git push`, stop and ask on the thread — a person answers. Never publish or push without that answer.',
+    skills: [], grants: ['shell', 'fs:write', 'scm:read', 'scm:push'], engine: { kind: 'harness', harnessId: 'claude' }, appliesTo: ['jobs'] },
+]);
+
+/** Fresh copies — a starter is a template, never the stored record. */
+export function starterAgents() {
+  return STARTER_AGENTS.map((a) => JSON.parse(JSON.stringify(a)));
+}
+
+/** A blank agent for the editor. */
+export function blankAgent() {
+  return { id: '', name: '', purpose: '', prompt: '', skills: [], grants: ['none'], engine: { kind: 'auto', policy: { prefer: 'balanced' } }, appliesTo: ['jobs'], memoryScope: '' };
+}
+
+/**
+ * The editor's form → an agent, or the errors. Grants and skills come as text ("web, data",
+ * "review, graphify"); the engine as the form's own shape (`{ kind, model, providerId,
+ * harnessId, prefer }`) or a string; a blank id is slugged from the name.
+ */
+export function agentFromForm(form) {
+  const f = form || {};
+  const id = String(f.id || '').trim() || slugAgentId(f.name);
+  const engine = isRecord(f.engine)
+    ? (f.engine.kind === 'auto' ? { kind: 'auto', policy: { prefer: f.engine.prefer || f.engine.policy?.prefer || 'balanced', ...(f.engine.policy || {}) } } : f.engine)
+    : f.engine;
+  const agent = {
+    id,
+    name: String(f.name || '').trim() || id,
+    purpose: String(f.purpose || '').trim(),
+    prompt: String(f.prompt || ''),
+    skills: list(f.skills, 80, MAX_SKILLS),
+    grants: list(f.grants, 80, 32).length ? list(f.grants, 80, 32) : ['none'],
+    engine,
+    ...(f.egress ? { egress: f.egress } : {}),
+    appliesTo: Array.isArray(f.appliesTo) && f.appliesTo.length ? f.appliesTo : ['jobs'],
+    ...(f.memoryScope ? { memoryScope: f.memoryScope } : {}),
+    ...(f.workdir ? { workdir: f.workdir } : {}),
+    createdBy: f.createdBy || 'person',
+    enabled: f.enabled !== false,
+    ...(f.origin && isRecord(f.origin) ? { origin: f.origin } : {}),
+    ...(f.createdAt ? { createdAt: f.createdAt } : {}),
+  };
+  const v = validateAgent(agent);
+  return v.ok ? { ok: true, agent: normalizeAgent(agent) } : { ok: false, errors: v.errors };
+}
+
+/** Which agents apply to jobs — the pool a job board recruits from. */
+export function poolFor(agents, surface = 'jobs') {
+  return (Array.isArray(agents) ? agents : []).filter((a) => a && a.enabled !== false && (Array.isArray(a.appliesTo) ? a.appliesTo : ['jobs']).includes(surface));
+}

package/src/job.js

@@ -97,12 +97,13 @@ export function defineJob(j) { return Object.freeze(normalizeJob(j)); }
 export function canTransition(from, to) { return (NEXT[from] || []).includes(to); }
 
 /** Applications are computed, not asked for: every eligible type in the pool applies at once. */
-export function applyAll(job, pool, fitFn, { cards = {} } = {}) {
-  const now = Date.now();
+export function applyAll(job, pool, fitFn, { cards = {}, now = Date.now() } = {}) {
+  // A fit function may also say which ENGINE the agent would run on (recruit.js does); an
+  // application without one is not recruitable right now and sorts after those that are.
   return (pool || [])
     .filter((a) => a && a.enabled !== false && (a.appliesTo || ['jobs']).includes('jobs'))
-    .map((a) => { const f = fitFn(job, a, cards[a.id] || null); return { agentId: a.id, fit: f.score, reasons: f.reasons, pitch: '', at: now }; })
-    .sort((x, y) => y.fit - x.fit)
+    .map((a) => { const f = fitFn(job, a, cards[a.id] || null); return { agentId: a.id, ...(f.engine ? { engine: f.engine } : {}), fit: f.score, reasons: f.reasons, pitch: '', at: now }; })
+    .sort((x, y) => (!!y.engine - !!x.engine) || (y.fit - x.fit))
     .slice(0, MAX_APPLICATIONS);
 }
 

package/src/model-ledger.js

@@ -197,9 +197,33 @@ export function summarizeEngine(entries, { minCalls = DEFAULT_MIN_CALLS, now = D
   };
 }
 
-// `cardOverride` and `applyCard` — the card over the name-based guess — live in
-// model-candidates.js beside `applyOverride`, the seam they feed; this module stays
-// importable by a store that has no router (the gateway vendors it with scorecard.js only).
+/**
+ * The override a card yields for model-candidates.js `applyOverride` — only the fields it
+ * has enough history for. `quality` is the mean rating (for `jobKind` when the card has
+ * ratings for it, else overall); `latencyMs` the observed p50 to first token (total when no
+ * ttft was recorded); `costPer1k` from the price when one is known; `available: false`
+ * only while it is declining right now. Returns `{ override, observed }`.
+ *
+ * Lives here, beside the card it reads, so recruit.js and a store without a router can use
+ * it; `applyCard` (the override over the guess) stays in model-candidates.js beside
+ * `applyOverride`, the seam it feeds.
+ */
+export function cardOverride(card, { minCalls = DEFAULT_MIN_CALLS, jobKind = null } = {}) {
+  const override = {}; const observed = [];
+  if (!card) return { override, observed };
+  const q = (jobKind && card.quality?.byJobKind?.[jobKind]?.count >= minCalls) ? card.quality.byJobKind[jobKind] : card.quality?.overall;
+  if (q && q.count >= minCalls && q.avg != null) { override.quality = q.avg; observed.push('quality'); }
+  const lat = card.latency?.ttft?.n >= minCalls ? card.latency.ttft.p50 : card.latency?.total?.n >= minCalls ? card.latency.total.p50 : null;
+  if (lat != null) { override.latencyMs = lat; observed.push('latencyMs'); }
+  // Six places, not three: a per-1k price is often 0.0004, and rounding it to 0 made a paid model read as free.
+  if (card.cost?.per1kIn != null && card.cost?.per1kOut != null) { override.costPer1k = Math.round(((card.cost.per1kIn + card.cost.per1kOut) / 2) * 1e6) / 1e6; observed.push('costPer1k'); }
+  if (card.availability?.decliningNow) { override.available = false; observed.push('available'); }
+  return { override, observed };
+}
+
+// `applyCard` — the card over the name-based guess — lives in model-candidates.js beside
+// `applyOverride`, the seam it feeds; this module stays importable by a store that has no
+// router (the gateway vendors it with scorecard.js only).
 // Agent scores normalised by engine (§13.3) live beside the card they adjust: scorecard.js
 // `adjustSummary` and `fit(job, type, summary, { qualityOf })`.
 export { adjustSummary } from './scorecard.js';

package/src/recruit.js

@@ -0,0 +1,425 @@
+// VENDORED from @chatpanel/events/recruit.js — edit there, then copy over.
+// Recruiting — applying and evaluating, the step between a posted job and a run (F8 §12.2.4,
+// architecture-pillars.md §13.4).
+//
+// Applications are COMPUTED, not asked for: every agent in the pool applies to every job at
+// once, scored by `fit` (scorecard.js) on its skills, tools, grants and its attested record —
+// the model-ADJUSTED rating when the engine rows say what its engines were worth. Recruiting
+// costs one model turn per job, not one per applicant, and that turn is optional.
+//
+// What is recruited is an (agent, engine) PAIR. An agent's engine may be fixed (`model`,
+// `harness`), the chat's (`assistant`), or `auto` with a policy; `routeFor` resolves it
+// against the ENGINE ROWS the host knows — every model or harness it can run, with reach,
+// capabilities, quality / latency / cost (the engine card's observed values over the router's
+// guess, `engineRow`) and whether it is available right now. Requirements eliminate first
+// (reach from the project's privacy setting — never learned, only typed; a work grant needs a
+// harness; tools need `tools`), the policy orders what survives over observed values, and the
+// agent's own record on each engine breaks ties. An agent whose engine does not clear is
+// still an applicant — a person should see it — but is not recruitable now.
+//
+// The EVALUATOR is one structured call (RECRUIT_SCHEMA) over the top applications: the pick
+// and why, or "none fits" with the agent that should exist. The call is the host's
+// (`runStructured` in a client; a gateway without a model skips it): `decide` takes its parsed
+// answer when there is one and falls back to the best fit above a floor when there is not, so
+// a job is recruited with or without a model. The decision lands on the project record as
+// events (`recruitEvents`) — the pick and the reasons on the job, a proposal as a decision a
+// person reads — never as a mutation.
+//
+// Pure, dependency-free; imports only what the gateway already vendors (scorecard.js,
+// model-ledger.js, engine.js, agent.js, job.js, team.js, structured.js, budget.js).
+
+import { fit, engineKey, normalizeEngine } from './scorecard.js';
+import { cardOverride, DEFAULT_MIN_CALLS } from './model-ledger.js';
+import { normalizeEngineSpec, engineKeyOf, describeEngine } from './engine.js';
+import { engineOf, agentFromForm } from './agent.js';
+import { applyAll } from './job.js';
+import { WORK_GRANTS } from './team.js';
+import { defineSchema, describeSchema, coerce } from './structured.js';
+import { normalizeBudget } from './budget.js';
+
+export const MIN_FIT = 0.5;
+export const TOP_APPLICANTS = 5;
+export const MAX_BRIEF_IN_PROMPT = 1500;
+const REACH_RANK = { device: 0, trusted: 1, any: 2 };
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const r3 = (v) => (v == null || !Number.isFinite(v) ? null : Math.round(v * 1000) / 1000);
+const clip = (s, n) => String(s || '').trim().slice(0, n);
+const lower = (xs) => (Array.isArray(xs) ? xs : []).map((x) => String(x).toLowerCase());
+
+// ── The evaluator's answer ────────────────────────────────────────────────────────────────
+
+export const RECRUIT_SCHEMA = defineSchema({
+  name: 'recruit',
+  purpose: 'which applicant gets the job, or that none fits and what agent should exist',
+  fields: {
+    // Not `required`: an emptied required field reads as "nothing" and would drop the proposal that rides beside it.
+    pick: { type: 'string', max: 64, describe: 'the id of the ONE applicant to recruit, or "" when none fits' },
+    why: { type: 'string', required: true, max: 400, describe: 'one or two sentences a person reads on the job page' },
+    confidence: { type: 'number', describe: '0 to 1' },
+    proposalName: { type: 'string', max: 60, describe: 'when none fits: the agent that should exist' },
+    proposalPurpose: { type: 'string', max: 300 },
+    proposalSkills: { type: 'string[]', maxItems: 12 },
+    proposalGrants: { type: 'string[]', maxItems: 8, describe: 'from: data, web, history, mcp, shell, fs:write, scm:read, scm:push, scm:pr' },
+  },
+  nothing: { pick: '', why: 'none fits' },
+});
+
+// ── Engine rows: what the host can run, as the recruiter reads it ─────────────────────────
+
+/**
+ * One row from a host's candidate (a router model — `inferCandidate`'s shape: `id`, `model`,
+ * `reach`, `capabilities`, `quality`, `latencyMs`, `costPer1k`, `available`, `classUsed`;
+ * or anything carrying an `engine` ref) with its engine CARD applied: observed quality,
+ * latency, cost and availability replace the guess where there is enough history, and a
+ * withdrawn capability is gone. A bridge agent (`classUsed 'A'` / `kind 'bridge'`) is a
+ * harness — `claude/opus` is the harness `claude` asked to run `opus` — keyed the way the
+ * desktop's appointer and the engine ledger key it.
+ */
+export function engineRow(candidate, { card = null, minCalls = DEFAULT_MIN_CALLS, jobKind = null } = {}) {
+  if (!isRecord(candidate)) return null;
+  const c = candidate;
+  let engine = c.engine ? normalizeEngine(c.engine) : null;
+  if (!engine) {
+    const name = String(c.model || c.id || '');
+    if (!name) return null;
+    if (c.kind === 'bridge' || c.kind === 'harness' || c.classUsed === 'A') {
+      const slash = name.indexOf('/');
+      engine = slash > 0 ? { kind: 'harness', id: name.slice(0, slash), model: name.slice(slash + 1) } : { kind: 'harness', id: name };
+    } else engine = { kind: 'model', id: name };
+  }
+  const key = engineKey(engine);
+  if (!key) return null;
+  const { override, observed } = cardOverride(card, { minCalls, jobKind });
+  const withdrawn = new Set(card?.capabilities?.withdrawn || []);
+  const capabilities = [...new Set(lower(c.capabilities))].filter((x) => !withdrawn.has(x));
+  if (withdrawn.size && lower(c.capabilities).some((x) => withdrawn.has(x))) observed.push('capabilities');
+  const num = (v) => (v == null || v === '' || !Number.isFinite(Number(v)) ? null : Number(v));
+  const reach = REACH_RANK[c.reach] != null ? c.reach : 'any';
+  // A model on this machine costs nothing per token — the router's own rule (`costOf`), kept
+  // here for a host that has no guess to offer; an unknown cost anywhere else stays unknown
+  // and orders as the dearest, so "we did not price it" never reads as "free".
+  const costPer1k = override.costPer1k ?? num(c.costPer1k) ?? (reach === 'device' && engine.kind === 'model' ? 0 : null);
+  return {
+    key,
+    engine,
+    label: clip(c.label || c.name || engineName(engine), 120),
+    reach,
+    capabilities,
+    quality: override.quality ?? num(c.quality),
+    latencyMs: override.latencyMs ?? num(c.latencyMs),
+    costPer1k,
+    costPerTask: num(card?.cost?.perTask),
+    availability: num(card?.availability?.rate),
+    available: override.available ?? (c.available !== false && c.usable !== false),
+    observed,
+  };
+}
+const engineName = (e) => `${e.id}${e.model && e.model !== e.id ? `/${e.model}` : ''}`;
+
+/** Rows from a host's candidates and the cards it holds (by key). */
+export function engineRows(candidates, { cards = {}, minCalls, jobKind } = {}) {
+  const out = []; const seen = new Set();
+  for (const c of Array.isArray(candidates) ? candidates : []) {
+    const row = engineRow(c, { card: null, minCalls, jobKind });
+    if (!row || seen.has(row.key)) continue;
+    seen.add(row.key);
+    out.push(cards[row.key] ? engineRow(c, { card: cards[row.key], minCalls, jobKind }) : row);
+  }
+  return out;
+}
+
+// ── What the job needs of an engine ───────────────────────────────────────────────────────
+
+/**
+ * Requirements eliminate; they are never traded for cost or speed. A work grant (`shell`,
+ * `fs:write`, `scm:*`) can only be exercised by a harness — a chat model has no shell. Tools
+ * or any grant beyond `none` mean the turn may call tools. Reach is the project's privacy
+ * ceiling, typed, never learned.
+ */
+export function needForJob(job, { reach = 'any' } = {}) {
+  const grants = lower(job?.needs?.grants).filter((g) => g !== 'none');
+  const tools = lower(job?.needs?.tools);
+  const harness = grants.some((g) => WORK_GRANTS.includes(g));
+  const capabilities = [];
+  const why = [];
+  if (tools.length || grants.length) { capabilities.push('tools'); why.push('the job uses tools'); }
+  if (harness) why.push(`a work grant (${grants.filter((g) => WORK_GRANTS.includes(g)).join(', ')}) needs a harness`);
+  const r = REACH_RANK[reach] != null ? reach : 'any';
+  if (r !== 'any') why.push(`reach ≤ ${r} (the project's privacy setting)`);
+  return { capabilities, harness, reach: r, why };
+}
+
+// ── Routing: the engine for this agent on this job ────────────────────────────────────────
+
+const meets = (row, need, policy) => {
+  const why = [];
+  if (row.available === false) why.push('unavailable right now');
+  if (REACH_RANK[row.reach] > REACH_RANK[need.reach]) why.push(`reach ${row.reach} exceeds ${need.reach}`);
+  if (need.harness && row.engine.kind !== 'harness') why.push('not a harness');
+  const missing = need.capabilities.filter((c) => !row.capabilities.includes(c));
+  // A harness brings its own tools; the capability list of a bridge agent is the host's guess.
+  if (missing.length && !(row.engine.kind === 'harness' && missing.every((c) => c === 'tools'))) why.push(`lacks ${missing.join(', ')}`);
+  if (policy) {
+    const matches = (refs) => (refs || []).some((k) => k === row.key || k === `${row.engine.kind}:${row.engine.id}` || k === row.engine.id || k === row.engine.model);
+    if (policy.allow?.length && !matches(policy.allow)) why.push('not on the policy\'s allow list');
+    if (policy.deny?.length && matches(policy.deny)) why.push('on the policy\'s deny list');
+    if (policy.floor?.quality != null && row.quality != null && row.quality < policy.floor.quality) why.push(`quality ${row.quality} under the floor ${policy.floor.quality}`);
+    if (policy.floor?.availability != null && row.availability != null && row.availability < policy.floor.availability) why.push(`availability ${row.availability} under the floor ${policy.floor.availability}`);
+    if (policy.ceiling?.costPerTask != null && row.costPerTask != null && row.costPerTask > policy.ceiling.costPerTask) why.push(`$${row.costPerTask}/task over the ceiling`);
+    if (policy.ceiling?.latencyMs != null && row.latencyMs != null && row.latencyMs > policy.ceiling.latencyMs) why.push(`${row.latencyMs} ms over the ceiling`);
+  }
+  return why;
+};
+
+const ownRating = (summary, key) => (summary?.byEngine || []).find((r) => r.key === key)?.rating?.avg ?? null;
+
+/** Order the rows that clear by the policy's preference; the agent's own record on an engine breaks ties. */
+function orderByPolicy(rows, prefer, summary) {
+  const q = (r) => r.quality ?? 0.5;
+  const cost = (r) => r.costPerTask ?? r.costPer1k ?? null;
+  const maxCost = Math.max(...rows.map((r) => cost(r) ?? 0), 0) || 1;
+  const maxLat = Math.max(...rows.map((r) => r.latencyMs ?? 0), 0) || 1;
+  const own = (r) => { const v = ownRating(summary, r.key); return v == null ? 0 : v - 0.5; };
+  const score = (r) => {
+    switch (prefer) {
+      case 'cheapest-that-clears': return -((cost(r) ?? maxCost) / maxCost) + q(r) * 0.01;
+      case 'best-quality': return q(r) - ((cost(r) ?? maxCost) / maxCost) * 0.01;
+      case 'fastest': return -((r.latencyMs ?? maxLat) / maxLat) + q(r) * 0.01;
+      default: return q(r) * 0.5 + (1 - (cost(r) ?? maxCost) / maxCost) * 0.25 + (1 - (r.latencyMs ?? maxLat) / maxLat) * 0.25;
+    }
+  };
+  return rows.map((r) => ({ row: r, score: score(r) + own(r) * 0.05 })).sort((a, b) => b.score - a.score).map((x) => x.row);
+}
+
+const rowLine = (r) => `${r.key} (quality ${r.quality ?? '?'}${r.observed.includes('quality') ? ' observed' : ''}${r.costPerTask != null ? `, $${r.costPerTask}/task` : r.costPer1k != null ? `, $${r.costPer1k}/1k` : ''}${r.latencyMs != null ? `, ${r.latencyMs} ms` : ''})`;
+
+/**
+ * The engine this agent would run this job on, and why — `{ engine, key, reasons,
+ * alternatives, exploration, clears }`; `clears: false` (engine null) when nothing does, with
+ * the reasons. `rows` are the host's `engineRows`; an empty roster trusts a fixed spec and
+ * refuses `auto` (nothing to pick from). `explore` takes one tier cheaper than the policy's
+ * pick when a cheaper row clears — the project loop's bounded exploration (§13.4); never for
+ * a harness.
+ */
+export function routeFor(agent, job, { rows = [], summary = null, need = null, reach = 'any', chatModel = null, explore = false } = {}) {
+  const n = need || needForJob(job, { reach });
+  const spec = engineOf(agent, { chatModel });
+  const list = Array.isArray(rows) ? rows.filter(Boolean) : [];
+  const none = (reasons) => ({ engine: null, key: null, reasons, alternatives: [], exploration: false, clears: false });
+  if (spec.kind !== 'auto') {
+    const key = engineKeyOf(spec);
+    const exact = list.find((r) => r.key === key);
+    // A harness card without a model matches any row of that harness; a model spec without a
+    // provider matches the row that runs that model anywhere.
+    const near = exact || list.find((r) => r.engine.kind === spec.kind && (spec.kind === 'harness' ? r.engine.id === spec.harnessId && !spec.model : (r.engine.id === spec.model || r.engine.model === spec.model) && !spec.providerId));
+    if (!list.length) return { engine: normalizeEngine({ kind: spec.kind, id: spec.kind === 'harness' ? spec.harnessId : (spec.providerId || spec.model), model: spec.model }), key, reasons: [`${describeEngine(spec)} — pinned by the agent; no roster to check it against`], alternatives: [], exploration: false, clears: true };
+    if (!near) return none([`${describeEngine(spec)} is pinned by the agent but is not installed or configured here`]);
+    const why = meets(near, n, null);
+    if (why.length) return none([`${describeEngine(spec)} is pinned by the agent but ${why.join('; ')}`]);
+    return { engine: near.engine, key: near.key, reasons: ['pinned by the agent', ...n.why], alternatives: [], exploration: false, clears: true };
+  }
+  if (!list.length) return none(['engine is auto and the roster is empty']);
+  const policy = spec.policy || {};
+  const rejected = [];
+  const cleared = list.filter((r) => { const why = meets(r, n, policy); if (why.length) rejected.push(`${r.key}: ${why.join('; ')}`); return !why.length; });
+  if (!cleared.length) return none([`no engine clears ${n.harness ? 'a harness with ' : ''}${n.capabilities.join(', ') || 'the requirements'}${n.reach !== 'any' ? ` within reach ${n.reach}` : ''}${policy.prefer ? ` under ${policy.prefer}` : ''}`, ...rejected.slice(0, 4)]);
+  const ordered = orderByPolicy(cleared, policy.prefer || 'balanced', summary);
+  let pick = ordered[0];
+  let exploration = false;
+  const cost = (r) => r.costPerTask ?? r.costPer1k ?? null;
+  if (explore && pick.engine.kind !== 'harness') {
+    const cheaper = ordered.filter((r) => r.engine.kind !== 'harness' && cost(r) != null && cost(pick) != null && cost(r) < cost(pick)).sort((a, b) => cost(b) - cost(a));
+    if (cheaper.length) { exploration = true; pick = cheaper[0]; }
+  }
+  const reasons = [
+    exploration ? `exploration: one tier cheaper than the policy's pick (${ordered[0].key})` : `${(policy.prefer || 'balanced').replace(/-/g, ' ')}: ${rowLine(pick)}`,
+    ...n.why,
+  ];
+  const own = ownRating(summary, pick.key);
+  if (own != null) reasons.push(`this agent rated ${Math.round(own * 100)}% on it before`);
+  if (policy.floor?.quality != null || policy.ceiling?.costPerTask != null || policy.ceiling?.latencyMs != null) reasons.push(`${cleared.length} of ${list.length} engines clear the policy`);
+  return { engine: pick.engine, key: pick.key, reasons, alternatives: ordered.filter((r) => r !== pick).slice(0, 4).map((r) => r.engine), exploration, clears: true };
+}
+
+// ── Applying: the whole pool at once ──────────────────────────────────────────────────────
+
+/** `qualityOf` / `costOf` for `adjustSummary`, read from the rows: what each engine is worth. */
+export function engineWorth(rows) {
+  const byKey = new Map((rows || []).filter(Boolean).map((r) => [r.key, r]));
+  return {
+    qualityOf: (key) => byKey.get(key)?.quality ?? null,
+    costOf: (key) => { const r = byKey.get(key); return r ? (r.costPerTask ?? null) : null; },
+  };
+}
+
+/**
+ * Every eligible agent applies: `fit` (needs → adjusted record → size) plus the engine it
+ * would run on. `summaries` are scorecard cards by agent id (`summarize()`); `rows` are
+ * `engineRows`. Best first, recruitable (an engine clears) before not. Each application is
+ * `{ agentId, engine?, fit, reasons, pitch, at, covers }` — job.js's shape, the record's, plus
+ * `covers` (has a skill the job names) for `decide`; the record drops it.
+ */
+export function applications(job, pool, { summaries = {}, rows = [], reach = 'any', chatModel = null, adjust = true, now = Date.now() } = {}) {
+  const need = needForJob(job, { reach });
+  const worth = engineWorth(rows);
+  const fitFn = (j, agent, summary) => {
+    const f = fit(j, { ...agent, tools: agent.tools || agent.grants }, summary, adjust ? worth : { adjust: false });
+    const route = routeFor(agent, j, { rows, summary, need, chatModel });
+    return { score: f.score, reasons: [...f.reasons, ...route.reasons].slice(0, 8), ...(route.clears ? { engine: route.engine } : {}), covers: coversSkills(j, agent) };
+  };
+  // `covers` — has at least one skill the job names (or the job names none) — rides on the
+  // live application for `decide`; the record keeps job.js's shape and drops it.
+  const covered = new Map((pool || []).map((a) => [a?.id, coversSkills(job, a)]));
+  return applyAll(job, pool, fitFn, { cards: summaries, now }).map((a) => ({ ...a, covers: covered.get(a.agentId) !== false }));
+}
+
+/** A job that names skills is not given to an agent with none of them on fit alone: tools and grants it never asked for count for nothing. */
+function coversSkills(job, agent) {
+  const want = lower(job?.needs?.skills);
+  if (!want.length) return true;
+  const has = new Set(lower(agent?.skills));
+  return want.some((s) => has.has(s));
+}
+
+// ── Evaluating: one structured call, or none ──────────────────────────────────────────────
+
+/** The evaluator's instruction: the job, the top applicants with their fit, engine and reasons, the shape to answer in. */
+export function evaluatorPrompt(job, apps, pool = [], { rows = [], top = TOP_APPLICANTS } = {}) {
+  const byId = new Map((pool || []).map((a) => [a.id, a]));
+  const rowOf = new Map((rows || []).filter(Boolean).map((r) => [r.key, r]));
+  const needs = job?.needs || {};
+  const lines = (apps || []).slice(0, top).map((a) => {
+    const agent = byId.get(a.agentId) || {};
+    const key = a.engine ? engineKey(a.engine) : null;
+    const row = key ? rowOf.get(key) : null;
+    return `- ${a.agentId} (fit ${Math.round((a.fit || 0) * 100)}%)${agent.purpose ? ` — ${clip(agent.purpose, 160)}` : ''}; skills: ${(agent.skills || []).join(', ') || 'none'}; grants: ${(agent.grants || []).join(', ') || 'none'}; ${key ? `engine: ${row ? rowLine(row) : key}` : 'NOT RECRUITABLE NOW — no engine clears'}; ${(a.reasons || []).slice(0, 4).join('; ')}`;
+  });
+  return [
+    `You are the evaluator for the job "${clip(job?.title, 200)}" on project ${job?.projectId || '?'}. Recruit ONE applicant, or say none fits.`,
+    `Brief: ${clip(job?.brief, MAX_BRIEF_IN_PROMPT)}`,
+    `Needs — skills: ${(needs.skills || []).join(', ') || 'none named'}; tools: ${(needs.tools || []).join(', ') || 'none named'}; grants: ${(needs.grants || []).join(', ') || 'none'}${job?.budget ? `; budget: ${Object.entries(job.budget).map(([k, v]) => `${v} ${k}`).join(', ')}` : ''}.`,
+    '',
+    'Applicants, best computed fit first (fit = the skills, tools and grants the job names, then the attested record, then size):',
+    ...(lines.length ? lines : ['- (no one applied)']),
+    '',
+    'Rules: prefer the applicant that has what the job names and a record of clearing work like it on the engine shown; never pick one marked NOT RECRUITABLE NOW; a lower fit is right only when its reasons show the higher one lacks something the brief needs. When no applicant has the skills the job names, answer pick "" and propose the agent that should exist.',
+    '',
+    describeSchema(RECRUIT_SCHEMA),
+  ].join('\n');
+}
+
+/**
+ * The evaluator's answer, read through the schema and checked against the applications: a
+ * pick must be a recruitable applicant, else it is "none". Returns `{ pick, why, confidence,
+ * proposal }` or null when the text is unreadable.
+ */
+export function parseEvaluation(text, apps = []) {
+  const got = coerce(text, RECRUIT_SCHEMA);
+  if (!got) return null;
+  const v = got.value;
+  const pick = String(v.pick || '').trim();
+  const app = pick ? (apps || []).find((a) => a.agentId === pick) : null;
+  const proposal = v.proposalName ? { name: clip(v.proposalName, 60), purpose: clip(v.proposalPurpose, 300), skills: (v.proposalSkills || []).map((s) => clip(s, 80)).filter(Boolean), grants: (v.proposalGrants || []).map((g) => clip(g, 64)).filter(Boolean) } : null;
+  if (app && app.engine) return { pick, why: clip(v.why, 400) || 'the evaluator\'s pick', confidence: r3(v.confidence), proposal: null };
+  return { pick: '', why: app ? `the evaluator picked ${pick}, which no engine can run right now` : clip(v.why, 400) || 'none fits', confidence: r3(v.confidence), proposal };
+}
+
+/**
+ * The decision: the evaluator's when one was made; else the best recruitable fit at or above
+ * `minFit`; else none, with the agent the job's needs describe as the proposal. Returns
+ * `{ kind: 'recruit', agentId, engine, fit, why, by }` or `{ kind: 'none', why, proposal, by }`.
+ */
+export function decide(job, apps, { evaluation = null, minFit = MIN_FIT } = {}) {
+  const list = apps || [];
+  if (evaluation && evaluation.pick) {
+    const app = list.find((a) => a.agentId === evaluation.pick && a.engine);
+    if (app) return { kind: 'recruit', agentId: app.agentId, engine: app.engine, fit: app.fit, why: evaluation.why, by: 'evaluator' };
+  }
+  if (evaluation && !evaluation.pick) return { kind: 'none', why: evaluation.why, proposal: evaluation.proposal || proposalFromNeeds(job), by: 'evaluator' };
+  const best = list.find((a) => a.engine && a.covers !== false);
+  if (best && best.fit >= minFit) return { kind: 'recruit', agentId: best.agentId, engine: best.engine, fit: best.fit, why: `best fit (${Math.round(best.fit * 100)}%): ${(best.reasons || [])[0] || 'meets the needs'}`, by: 'fit' };
+  const why = !list.length ? 'no one in the pool applies to jobs'
+    : !best ? (list.some((a) => a.engine) ? `no applicant has a skill the job names (${(job?.needs?.skills || []).join(', ')})` : `${list.length} applied but no engine clears for any of them: ${(list[0].reasons || []).find((r) => /engine|pinned|roster/.test(r)) || 'see the applications'}`)
+      : `the best fit is ${Math.round(best.fit * 100)}%, under the ${Math.round(minFit * 100)}% floor: ${(best.reasons || []).find((r) => /missing/.test(r)) || best.reasons?.[0] || ''}`;
+  return { kind: 'none', why, proposal: proposalFromNeeds(job), by: 'fit' };
+}
+
+/** The agent a job's needs describe — what to propose when no one fits. */
+export function proposalFromNeeds(job) {
+  const needs = job?.needs || {};
+  return { name: clip(job?.title, 60) || 'New agent', purpose: `Does jobs like "${clip(job?.title, 80)}".`, skills: [...(needs.skills || [])], grants: (needs.grants || []).length ? [...needs.grants] : ['none'] };
+}
+
+/**
+ * A proposal as an agent card for a person to approve — validated by the pool's own form
+ * (agentFromForm), engine `auto`, `createdBy: 'evaluator'`, its origin the job. Nothing
+ * joins the pool without a decision (D-A2): this returns the card, it does not store it.
+ */
+export function proposalToAgent(proposal, job, { by = 'evaluator' } = {}) {
+  const p = proposal || proposalFromNeeds(job);
+  const known = new Set(['data', 'web', 'history', 'mcp', ...WORK_GRANTS]);
+  const grants = (p.grants || []).map((g) => String(g).toLowerCase()).filter((g) => known.has(g) || /^mcp:/.test(g));
+  return agentFromForm({
+    name: p.name, purpose: p.purpose, skills: p.skills,
+    prompt: `You are ${p.name}. ${p.purpose || ''}\n\nYou were proposed for the job "${clip(job?.title, 200)}" because no agent in the pool fit it. Do work like it well; ask on the thread when the brief is unclear.`,
+    grants: grants.length ? grants : ['none'], engine: { kind: 'auto', prefer: 'balanced' }, appliesTo: ['jobs'], createdBy: by,
+    origin: { kind: 'proposal', projectId: job?.projectId, jobId: job?.id },
+  });
+}
+
+// ── Landing it on the record ──────────────────────────────────────────────────────────────
+
+/**
+ * The budget a recruit gets: the job's own when it has one, else an equal share of what the
+ * project has left (its budget minus its spend) across the jobs still to be recruited — so
+ * one unbudgeted job cannot take the whole project. `record` is the project record
+ * (project.js `foldProject`).
+ */
+export function carveBudget(job, record = null) {
+  if (job?.budget && Object.keys(job.budget).length) return normalizeBudget(job.budget);
+  const cap = record?.page?.budget || {};
+  const spent = record?.spend || {};
+  const waiting = Math.max(1, (record?.jobs || []).filter((j) => ['open', 'evaluating'].includes(j.status)).length);
+  const out = {};
+  for (const k of ['tokens', 'calls', 'ms', 'usd']) {
+    if (!(Number(cap[k]) > 0)) continue;
+    const left = Math.max(0, Number(cap[k]) - (Number(spent[k]) || 0));
+    if (left > 0) out[k] = k === 'usd' ? Math.round((left / waiting) * 100) / 100 : Math.max(1, Math.floor(left / waiting));
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * The events that record a recruiting pass on the project (project.js fold): the job moves
+ * to `evaluating` with its applications, then to `recruited` with the pair, the budget and
+ * the why — or back to `open`, with the proposal as a decision a person reads.
+ */
+export function recruitEvents(job, apps, decision, { by = 'evaluator', at = Date.now(), record = null } = {}) {
+  const events = [{ type: 'job.updated', at, job: { id: job.id, status: 'evaluating', applications: (apps || []).map(({ covers: _c, ...a }) => a) }, by }];
+  if (decision?.kind === 'recruit') {
+    const budget = carveBudget(job, record);
+    events.push({ type: 'job.updated', at, job: { id: job.id, status: 'recruited', recruited: { agentId: decision.agentId, engine: decision.engine, ...(budget ? { budget } : {}), by: decision.by || by, at, why: clip(decision.why, 600) } }, by });
+  } else {
+    events.push({ type: 'job.updated', at, job: { id: job.id, status: 'open' }, by });
+    const p = decision?.proposal;
+    events.push({ type: 'project.decision', at, by, kind: 'proposal', text: `No one in the pool fits "${clip(job.title, 120)}": ${clip(decision?.why, 400)}${p ? ` Proposed: ${p.name}${p.skills?.length ? ` — skills ${p.skills.join(', ')}` : ''}${p.grants?.length ? `; grants ${p.grants.join(', ')}` : ''}.` : ''}`, refs: [`job:${job.id}`] });
+  }
+  return events;
+}
+
+/**
+ * One pass, end to end: apply → (evaluate) → decide → the events. `ask(prompt) → text |
+ * null` is the host's structured call; absent or failing, the fit decides. Returns
+ * `{ applications, evaluation, decision, events, prompt }`.
+ */
+export async function recruitJob(job, pool, { summaries = {}, rows = [], reach = 'any', chatModel = null, record = null, ask = null, minFit = MIN_FIT, by = 'evaluator', now = Date.now() } = {}) {
+  const apps = applications(job, pool, { summaries, rows, reach, chatModel, now });
+  const prompt = evaluatorPrompt(job, apps, pool, { rows });
+  let evaluation = null;
+  if (ask && apps.some((a) => a.engine)) {
+    try { const text = await ask(prompt, RECRUIT_SCHEMA); evaluation = text == null ? null : (typeof text === 'string' ? parseEvaluation(text, apps) : parseEvaluation(JSON.stringify(text), apps)); } catch { evaluation = null; }
+  }
+  const decision = decide(job, apps, { evaluation, minFit });
+  return { applications: apps, evaluation, decision, events: recruitEvents(job, apps, decision, { by: decision.by === 'evaluator' ? by : 'fit', at: now, record }), prompt };
+}

package/src/recruiting.js

@@ -0,0 +1,93 @@
+// Recruiting on the gateway — the pool, the cards and the roster THIS machine knows, handed
+// to the shared recruiter (recruit.js, vendored) for one job.
+//
+// The pool is the shared `agents` prefs section; each agent's record is its attested
+// scorecard chain (scorecard-store.js); each engine's card is its attested ledger
+// (engine-ledger-store.js); the roster is the gateway's own model list — every destination it
+// routes to, with the bridge's word on which agents are installed. None of that is the
+// client's to claim: a client asks for the applications and posts the evaluator's answer, and
+// the gateway recomputes the fit before it records a pick. The gateway makes no model call of
+// its own here — the evaluator is the client's structured call (`runStructured`), and when no
+// client makes one the fit decides, so a job is recruitable from a curl.
+
+import { summarize } from './scorecard.js';
+import { applications, evaluatorPrompt, parseEvaluation, decide, recruitEvents, engineRows, MIN_FIT } from './recruit.js';
+import { aggregateModelsAsync, listDestinations } from './router.js';
+
+const REACH = new Set(['device', 'trusted', 'any']);
+
+/** Where a destination's model runs, typed from its address — never learned. */
+function reachOfDestination(d) {
+  if (!d || d.type === 'agent') return 'trusted';
+  const url = String(d.baseUrl || '');
+  if (/^https?:\/\/(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)(:|\/|$)/i.test(url)) return 'device';
+  if (/^https?:\/\/(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|[^/]+\.local(:|\/|$))/i.test(url)) return 'trusted';
+  return 'any';
+}
+
+/**
+ * The roster as engine rows: the gateway's model list (`aggregateModelsAsync`) with each
+ * engine's card applied. A bridge agent is a harness; an API model's reach is its
+ * destination's; `available` is the bridge's word for agents (absent = unknown, taken as
+ * usable) and `configured` for API destinations. Quality is the card's when observed —
+ * the gateway does not vendor the router's name-based guess, so an unrated engine is the
+ * 0.5 prior and the recruiter's reasons say so.
+ */
+export async function rosterRows(cfg, engines, { jobKind = null, minCalls, timeoutMs = 2500 } = {}) {
+  const models = await aggregateModelsAsync(cfg, { timeoutMs }).catch(() => ({ data: [] }));
+  const dests = new Map(listDestinations(cfg).map((d) => [d.id, d]));
+  const candidates = (models.data || []).map((m) => {
+    const agent = m.owned_by === 'chatpanel-bridge';
+    const d = dests.get(m.provider);
+    return {
+      id: m.id, model: m.id, kind: agent ? 'bridge' : 'api', label: m.model ? `${m.provider} · ${m.model}` : m.id,
+      reach: agent ? 'trusted' : reachOfDestination(d),
+      capabilities: ['tools'],
+      available: m.configured === false ? false : (m.available !== false),
+    };
+  });
+  const cards = Object.fromEntries((engines?.list?.({ minCalls }) || []).map((c) => [c.key, c]));
+  return engineRows(candidates, { cards, minCalls, jobKind });
+}
+
+/** The pool: the shared `agents` section, enabled cards only. */
+export function poolFrom(prefsStore) {
+  const v = prefsStore?.get?.('agents')?.agents?.value;
+  return (Array.isArray(v) ? v : []).filter((a) => a && a.id && a.enabled !== false);
+}
+
+/** Every applicant's card, from the attested chains. */
+export function summariesFrom(scorecards, pool) {
+  const out = {};
+  for (const a of pool) { const chain = scorecards?.chains?.get?.(a.id); if (chain?.length) out[a.id] = summarize(chain); }
+  return out;
+}
+
+/**
+ * The applications for a job as this gateway sees them, plus the evaluator's prompt a client
+ * runs through its structured layer. `reach` is the project's privacy ceiling, the client's
+ * to state (default `any`).
+ */
+export async function applicationsFor(job, { cfg, prefsStore, scorecards, engines, reach = 'any', chatModel = null, now = Date.now() } = {}) {
+  const pool = poolFrom(prefsStore);
+  const rows = await rosterRows(cfg, engines);
+  const summaries = summariesFrom(scorecards, pool);
+  const r = REACH.has(reach) ? reach : 'any';
+  const apps = applications(job, pool, { summaries, rows, reach: r, chatModel, now });
+  return { applications: apps, prompt: evaluatorPrompt(job, apps, pool, { rows }), rows: rows.map((x) => ({ key: x.key, label: x.label, reach: x.reach, quality: x.quality, costPer1k: x.costPer1k, latencyMs: x.latencyMs, available: x.available, observed: x.observed })), poolSize: pool.length };
+}
+
+/**
+ * One recruiting pass: recompute the applications (never trust a posted fit), read the
+ * client's evaluation when it sent one (`evaluation` parsed, or `text` raw — the schema
+ * reads it), decide, and return the events for the project record. The caller appends them.
+ */
+export async function recruitPass(job, { cfg, prefsStore, scorecards, engines, record = null, reach = 'any', chatModel = null, evaluation = null, text = null, by = 'evaluator', minFit = MIN_FIT, now = Date.now() } = {}) {
+  const { applications: apps, prompt } = await applicationsFor(job, { cfg, prefsStore, scorecards, engines, reach, chatModel, now });
+  let ev = null;
+  if (text != null) ev = parseEvaluation(String(text), apps);
+  else if (evaluation && typeof evaluation === 'object') ev = parseEvaluation(JSON.stringify({ pick: evaluation.pick, why: evaluation.why, confidence: evaluation.confidence, proposalName: evaluation.proposal?.name, proposalPurpose: evaluation.proposal?.purpose, proposalSkills: evaluation.proposal?.skills, proposalGrants: evaluation.proposal?.grants }), apps);
+  const decision = decide(job, apps, { evaluation: ev, minFit });
+  const events = recruitEvents(job, apps, decision, { by: decision.by === 'evaluator' ? by : 'fit', at: now, record });
+  return { applications: apps, evaluation: ev, decision, events, prompt };
+}

package/src/server.js

@@ -38,6 +38,7 @@ 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';
@@ -61,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.90';
+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.
@@ -844,6 +845,11 @@ export function createGateway(cfg = loadConfig()) {
     //   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') || '' }) });
@@ -855,10 +861,37 @@ export function createGateway(cfg = loadConfig()) {
       } 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}))?)?$/.exec(pathname);
+      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 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'))) {