@ludi-uni/ludi-agent-kit 0.1.0

package/lib/orchestrator/turn-budget.mjs

@@ -0,0 +1,63 @@
+// Subagent execution budget: complexity classification, per-role initial turn
+// budgets, and deterministic progress evaluation for bounded extension.
+// Provider-agnostic — nothing here names a model or backend.
+
+export const COMPLEXITIES = ['simple', 'normal', 'heavy', 'repo-history-heavy'];
+
+const HEAVY_RE = /\b(git log|commit history|commit(s)? histor|across (the )?(repo|codebase)|multiple (directories|files|modules)|whole (repo|codebase)|all files|every file)\b|コミット履歴|履歴|横断|全体/i;
+const HISTORY_RE = /\b(git|commit|history|changelog|blame|past changes|previous commits)\b|コミット|変更履歴|過去/i;
+const MULTI_RE = /\b(and|&|plus|also|then combine|integrate|merge|compare|across)\b|かつ|と同時に|統合|比較|組み合わせ/i;
+
+/**
+ * Classify a task's investigation complexity from its goal/kind. Deterministic —
+ * no model call. repo-history-heavy needs git/commit-history analysis; heavy needs
+ * multi-area discovery+analysis; normal is a focused investigate; simple is trivial.
+ */
+export function classifyTaskComplexity(task) {
+  const text = `${task?.title ?? ''} ${task?.goal ?? ''}`.toLowerCase();
+  const deps = task?.dependencies?.length ?? 0;
+  const history = HISTORY_RE.test(text);
+  const heavy = HEAVY_RE.test(text) || MULTI_RE.test(text);
+  if (history && (heavy || /ux|preference|ui|implement|design|pattern/i.test(text))) return 'repo-history-heavy';
+  if (history) return 'repo-history-heavy';
+  if (heavy || deps >= 2) return 'heavy';
+  if (task?.kind === 'investigate' || task?.kind === 'review') return 'normal';
+  return 'simple';
+}
+
+/**
+ * Initial turn budget for a task = turn_budgets[role][complexity]
+ *   -> turn_budgets[role].normal -> turn_budgets.default[complexity] -> max_turns.
+ */
+export function initialTurnBudget(agentRuntime, role, complexity) {
+  const budgets = agentRuntime?.turn_budgets ?? {};
+  const roleB = budgets[role] ?? budgets.default ?? {};
+  const defB = budgets.default ?? {};
+  return roleB[complexity] ?? roleB.normal ?? defB[complexity] ?? defB.normal ?? agentRuntime?.max_turns ?? 12;
+}
+
+/**
+ * Deterministic progress score from a subagent's execution telemetry.
+ * Positive score = meaningful progress worth extending. No LLM judgement.
+ *   +2 per tool call, +3 per unique file inspected, +1 per successful command,
+ *   -2 per repeated identical command, -4 for zero tool calls.
+ */
+export function progressScore(telemetry) {
+  const toolCalls = telemetry?.toolCalls ?? 0;
+  const uniqueFiles = telemetry?.uniqueFiles?.size ?? telemetry?.uniqueFilesInspected ?? 0;
+  const commands = telemetry?.commands ?? [];
+  const successful = telemetry?.successfulToolCalls ?? commands.length;
+  const repeats = commands.length - new Set(commands).size;
+  const score = toolCalls * 2 + uniqueFiles * 3 + successful * 1 - repeats * 2 + (toolCalls === 0 ? -4 : 0);
+  const reasons = [];
+  if (toolCalls === 0) reasons.push('no tool calls');
+  if (uniqueFiles > 0) reasons.push(`${uniqueFiles} files inspected`);
+  if (repeats > 1) reasons.push(`${repeats} repeated commands`);
+  if (successful > 0) reasons.push(`${successful} commands run`);
+  return { score, reasons, meaningful: toolCalls > 0 && (uniqueFiles > 0 || successful > 0 || repeats <= 1) };
+}
+
+/** True when a turn-limit hit should be treated as no-progress (global model failure). */
+export function isNoProgressTimeout(telemetry) {
+  return !progressScore(telemetry).meaningful;
+}

package/lib/orchestrator/worktree.mjs

@@ -0,0 +1,72 @@
+// Baseline the worktree before a task and report only what changed. Never reset, checkout, or stash.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const SKIP = new Set(['.git', 'node_modules', 'out', 'dist', '.orchestration']);
+
+function hashFile(path) {
+  try { return createHash('sha256').update(readFileSync(path)).digest('hex'); }
+  catch { return null; }
+}
+
+function parsePorcelain(stdout) {
+  const parts = String(stdout ?? '').split('\0').filter(Boolean);
+  const entries = {};
+  for (let i = 0; i < parts.length; i++) {
+    const rec = parts[i];
+    const code = rec.slice(0, 2);
+    let file = rec.slice(3);
+    if ((code.startsWith('R') || code.startsWith('C')) && parts[i + 1]) file = parts[++i];
+    entries[file.replace(/\\/g, '/')] = code;
+  }
+  return entries;
+}
+
+function inventory(root, dir = root, out = {}, budget = { n: 0 }) {
+  if (budget.n > 400) return out;
+  let names = [];
+  try { names = readdirSync(dir); } catch { return out; }
+  for (const name of names) {
+    if (SKIP.has(name)) continue;
+    const abs = join(dir, name);
+    let st;
+    try { st = statSync(abs); } catch { continue; }
+    if (st.isDirectory()) inventory(root, abs, out, budget);
+    else if (st.isFile()) {
+      budget.n++;
+      out[relative(root, abs).replace(/\\/g, '/')] = hashFile(abs);
+    }
+  }
+  return out;
+}
+
+export function captureWorktree(root) {
+  if (!root || !existsSync(root)) return { available: false, entries: {} };
+  const status = spawnSync('git', ['status', '--porcelain', '-z'], { cwd: root, encoding: 'utf8', windowsHide: true });
+  if (status.error || status.status !== 0) return { available: false, entries: inventory(root), source: 'files' };
+  const codes = parsePorcelain(status.stdout);
+  const entries = {};
+  for (const [file, code] of Object.entries(codes)) entries[file] = { code, hash: hashFile(join(root, file)) };
+  return { available: true, entries, source: 'git' };
+}
+
+export function diffWorktree(before, after) {
+  if (!before?.source || before.source !== after?.source) return [];
+  const changed = [];
+  const keys = new Set([...Object.keys(before.entries ?? {}), ...Object.keys(after.entries ?? {})]);
+  for (const path of keys) {
+    const b = before.entries[path];
+    const a = after.entries[path];
+    if (JSON.stringify(b ?? null) === JSON.stringify(a ?? null)) continue;
+    const code = String(a?.code ?? '');
+    let kind = 'modified';
+    if (!a) kind = 'deleted';
+    else if (after.source === 'git' && code.includes('?')) kind = 'untracked';
+    else if (!b || (after.source === 'git' && code.includes('A'))) kind = 'added';
+    else if (after.source === 'git' && code.includes('D')) kind = 'deleted';
+    changed.push({ path, kind, before: b?.code ?? null, after: a?.code ?? null });
+  }
+  return changed;
+}

package/lib/pipeline.mjs

@@ -0,0 +1,279 @@
+// Minimal executable path: task -> scout -> Context Pack -> coder -> validation -> success | escalation.
+// Adapter-agnostic: the caller supplies `invoke({ modelId, provider, model, thinking, systemPrompt, prompt, cwd })`
+// returning { ok, text, error?, durationMs }. Nothing here knows provider names.
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync, mkdirSync } from 'node:fs';
+import { join, relative, resolve, dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { resolveCapability } from './resolve.mjs';
+import { LANGUAGE_POLICY } from './language-policy.mjs';
+import { normalizeContextPack } from './normalize.mjs';
+import { toMarkdown } from './context-pack.mjs';
+
+export const DEFAULT_MAX_ATTEMPTS = 2;
+const IGNORE_DIRS = new Set(['.git', 'node_modules', 'out', 'dist', '.pi']);
+
+// ---------- repository survey (deterministic pre-pass; keeps the scout prompt small) ----------
+export function surveyRepo(repoRoot, { maxFiles = 200, maxInlineBytes = 4000, maxTotalInline = 24000 } = {}) {
+  const files = [];
+  const walk = dir => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (IGNORE_DIRS.has(e.name)) continue;
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p); else files.push(p);
+      if (files.length >= maxFiles) return;
+    }
+  };
+  walk(repoRoot);
+  const rel = files.map(f => ({ path: relative(repoRoot, f).replace(/\\/g, '/'), size: statSync(f).size }));
+  let budget = maxTotalInline;
+  const inline = [];
+  for (const f of rel) {
+    if (f.size > maxInlineBytes || budget <= 0 || /\.(png|jpg|mp4|wav|lock)$/.test(f.path)) continue;
+    const content = readFileSync(join(repoRoot, f.path), 'utf8');
+    inline.push({ path: f.path, content });
+    budget -= f.size;
+  }
+  return { files: rel, inline };
+}
+
+export function detectTestCommand(repoRoot) {
+  const pkg = join(repoRoot, 'package.json');
+  if (existsSync(pkg)) {
+    const json = JSON.parse(readFileSync(pkg, 'utf8'));
+    if (json.scripts?.test) return 'npm test';
+  }
+  return null;
+}
+
+export function runTests(repoRoot, command) {
+  if (!command) return { ok: false, skipped: true, output: 'no test command' };
+  const shell = process.platform === 'win32' ? ['pwsh', ['-NoProfile', '-Command', command]] : ['sh', ['-c', command]];
+  // Strip node test-runner context so a nested `node --test` reports to us, not to an outer runner.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('NODE_TEST_') && k !== 'NODE_OPTIONS'));
+  const r = spawnSync(shell[0], shell[1], { cwd: repoRoot, encoding: 'utf8', timeout: 120000, windowsHide: true, env });
+  return { ok: r.status === 0, status: r.status, output: ((r.stdout ?? '') + (r.stderr ?? '')).slice(-6000) };
+}
+
+// ---------- prompts ----------
+export function scoutPrompt({ task, survey, testOutput, testCommand }) {
+  const tree = survey.files.map(f => `- ${f.path} (${f.size} B)`).join('\n');
+  const contents = survey.inline.map(f => `### \`${f.path}\`\n\`\`\`\n${f.content}\n\`\`\``).join('\n\n');
+  return [
+    `Task: ${task}`,
+    '', '## Repository files', tree,
+    '', '## File contents (bounded)', contents,
+    testOutput ? `\n## Failing test output\n\`\`\`\n${testOutput}\n\`\`\`` : '',
+    testCommand ? `\n## Test command\n- \`${testCommand}\`` : '',
+    '', 'Produce the Context Pack now. Start with the line `# Context Pack`. If the task needs files that do not exist yet,',
+    'list them in `## relevant_files` with the reason prefixed by `(new)`. If no existing file is relevant, add',
+    '`## discovery` containing `none — <why>`. Use repository-relative paths only.',
+    '', 'Write natural-language content (goal, reasons, constraints, notes) in Japanese unless the user requested another language.',
+    'CRITICAL: `##` section headings must be the EXACT schema names — `## task`, `## goal`, `## constraints`, `## relevant_files`, `## relevant_snippets`, `## repo_rules`, `## observed_errors`, `## test_commands`, `## previous_attempts`, `## expected_output`. Never translate or annotate a heading (no "## 課題", no "## task Japanese"). Only the prose under each heading is Japanese.',
+  ].join('\n');
+}
+
+export function coderPrompt({ pack, repoRoot }) {
+  const files = pack.relevant_files.map(f => {
+    const p = join(repoRoot, f.path);
+    return existsSync(p) ? `### \`${f.path}\`\n\`\`\`\n${readFileSync(p, 'utf8')}\n\`\`\`` : `### \`${f.path}\` (does not exist yet${f.create ? '; you may create it' : ''})`;
+  }).join('\n\n');
+  return [
+    toMarkdown(pack),
+    '', '## Current contents of relevant_files', files,
+    '', 'Return the complete new contents of every file you change using exactly this format and nothing else:',
+    '=== FILE: <repo-relative path> ===', '<full file content>', '=== END ===',
+    'Only paths listed in relevant_files may be changed or created. Do not explain.',
+    '', 'Any prose you must include (commit-style notes, comments) should be in Japanese unless the user requested another language; code and file contents stay as-is.',
+  ].join('\n');
+}
+
+export function parseFileBlocks(text) {
+  const blocks = [];
+  const re = /=== FILE: (.+?) ===\r?\n([\s\S]*?)\r?\n=== END ===/g;
+  let m;
+  while ((m = re.exec(text))) blocks.push({ path: m[1].trim().replace(/\\/g, '/'), content: m[2] });
+  return blocks;
+}
+
+export function applyFileBlocks(repoRoot, blocks, allowed) {
+  const applied = [], rejected = [];
+  const allow = new Set(allowed.map(f => f.path));
+  for (const b of blocks) {
+    if (!allow.has(b.path) || b.path.includes('..')) { rejected.push(b.path); continue; }
+    const target = resolve(repoRoot, b.path);
+    if (!target.startsWith(resolve(repoRoot))) { rejected.push(b.path); continue; }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, b.content.endsWith('\n') ? b.content : b.content + '\n');
+    applied.push(b.path);
+  }
+  return { applied, rejected };
+}
+
+// ---------- escalation core ----------
+/**
+ * Try `fn(candidate)` on the capability chain: primary, then fallback[0], ... bounded by maxAttempts.
+ * The same modelId is never tried twice. Each failure is appended to pack.previous_attempts.
+ * Optional hooks: `skip(candidate)` returns a reason to pass over a candidate without spending an attempt
+ * (e.g. a backend known to be out of quota); `onFailure(candidate, reason)` observes each failed attempt.
+ */
+export async function withEscalation({ routing, registry, capability, agent, pack, maxAttempts = DEFAULT_MAX_ATTEMPTS, trace, fn, skip = null, onFailure = null, excludeModels = null, taskGlobalFailedModels = null, invocationsBudget = null }) {
+  const resolved = resolveCapability(routing, registry, capability);
+  if (!resolved.candidates.length) throw new Error(`no bound model for capability "${capability}" (unbound=${resolved.unbound.join(',')}, placeholder=${resolved.placeholder.join(',')})`);
+  // Candidates already tried (and failed) on earlier attempts of this task are
+  // passed in via excludeModels so a retried task advances to a NEW candidate
+  // instead of restarting at candidate[0]. They are recorded as skipped, not run.
+  //
+  // Counter semantics (attempt budget applies to invocationsStarted only):
+  //   candidatesConsidered = every candidate the loop looked at
+  //   candidatesSkipped    = health/availability/already-tried skips (NO invocation)
+  //   invocationsStarted   = candidates actually invoked (attempt budget unit)
+  //   invokedModels        = modelIds actually invoked this call (NOT excludeModels)
+  const alreadyTried = new Set(excludeModels ?? []);
+  const globallyFailed = new Set(taskGlobalFailedModels ?? []);
+  const invokedSet = new Set(); // dedup within this call: identical modelId on two backends runs once
+  const invokedModels = [];
+  const skipped = [];
+  let last = null, attempts = 0, i = 0, considered = 0;
+  // The capability is freshly resolved each call. Filter task-global failures
+  // before the first invocation, including candidates after an early success.
+  const eligible = resolved.candidates.filter(c => {
+    if (!globallyFailed.has(c.modelId)) return true;
+    considered++;
+    skipped.push({ backend: c.backend, modelId: c.modelId, reason: 'task-global-failed' });
+    trace.push({ step: agent, agent, capability, backend: c.backend, provider: c.provider, model: c.model, modelId: c.modelId, skipped: true, ok: false, reason: 'task-global-failed', startedAt: new Date().toISOString(), durationMs: 0 });
+    return false;
+  });
+  // invocationsBudget caps ACTUAL invocations across the whole task (not just this
+  // call), so a retried task cannot overspend max_total_attempts_per_task.
+  const invocationsLeft = () => (invocationsBudget == null ? Infinity : invocationsBudget - invokedModels.length);
+  for (; i < eligible.length && attempts < maxAttempts && invocationsLeft() > 0; i++) {
+    const c = eligible[i];
+    considered++;
+    if (alreadyTried.has(c.modelId) || invokedSet.has(c.modelId)) { const reason = 'already-tried'; skipped.push({ backend: c.backend, modelId: c.modelId, reason }); trace.push({ step: agent, agent, capability, backend: c.backend, provider: c.provider, model: c.model, modelId: c.modelId, skipped: true, ok: false, reason, startedAt: new Date().toISOString(), durationMs: 0 }); continue; }
+    const why = skip?.(c);
+    if (why) {
+      skipped.push({ backend: c.backend, modelId: c.modelId, reason: why });
+      trace.push({ step: agent, agent, capability, backend: c.backend, provider: c.provider, model: c.model, modelId: c.modelId, skipped: true, ok: false, reason: why, startedAt: new Date().toISOString(), durationMs: 0 });
+      continue;
+    }
+    invokedSet.add(c.modelId);
+    invokedModels.push(c.modelId);
+    const attempt = attempts++;
+    const entry = { step: agent, attempt: attempt + 1, agent, capability, backend: c.backend, provider: c.provider, model: c.model, thinking: c.thinking, modelId: c.modelId, degraded: c.degraded, startedAt: new Date().toISOString() };
+    const started = Date.now();
+    try {
+      const result = await fn(c, attempt);
+      entry.durationMs = Date.now() - started;
+      entry.ok = result.ok;
+      entry.reason = result.reason;
+      if (result.protocolFailure) entry.protocolFailure = result.protocolFailure; // model-quality failure for task-global marking
+      if (result.failureClass) entry.failureClass = result.failureClass;
+      // Per-candidate execution telemetry — preserved on the step so a later
+      // candidate's record never overwrites an earlier one (e.g. Devin's run is
+      // kept even when a subsequent candidate also runs).
+      if (result.child) entry.child = result.child;
+      if (result.telemetry) entry.telemetry = result.telemetry;
+      trace.push(entry);
+      if (result.ok) return { ok: true, candidate: c, result, attempts: attempt + 1, escalated: attempt > 0, skipped, invokedModels, counters: { candidatesConsidered: considered, candidatesSkipped: skipped.length, invocationsStarted: invokedModels.length } };
+      last = result;
+    } catch (e) {
+      entry.durationMs = Date.now() - started; entry.ok = false; entry.reason = e.message; trace.push(entry);
+      last = { ok: false, reason: e.message };
+    }
+    onFailure?.(c, String(last.reason ?? 'failed'));
+    pack.previous_attempts = pack.previous_attempts ?? [];
+    pack.previous_attempts.push({ summary: `${agent} on backend ${c.backend} (${c.modelId}) attempt ${attempt + 1}`, outcome: String(last.reason ?? 'failed').slice(0, 400) });
+  }
+  const counters = { candidatesConsidered: considered, candidatesSkipped: skipped.length, invocationsStarted: invokedModels.length };
+  if (!attempts && skipped.length) {
+    return { ok: false, attempts: 0, unavailable: true, exhausted: true, escalationCandidate: null, skipped, invokedModels, counters, last: { ok: false, reason: `all model candidates unavailable: ${skipped.map(s => `${s.modelId} (${s.reason})`).join('; ')}` } };
+  }
+  const next = eligible[i];
+  return { ok: false, attempts, exhausted: !next, escalationCandidate: next ? { backend: next.backend, modelId: next.modelId } : null, last, skipped, invokedModels, counters };
+}
+
+// ---------- full pipeline ----------
+export async function runPipeline({ repoRoot, task, routing, registry, agents, invoke, outDir, maxAttempts = DEFAULT_MAX_ATTEMPTS, skipScout = false, packPath = null, health = null }) {
+  const hooks = health ? { skip: health.skip, onFailure: health.report } : {};
+  repoRoot = resolve(repoRoot);
+  mkdirSync(outDir, { recursive: true });
+  const trace = [];
+  const byName = Object.fromEntries(agents.map(a => [a.meta.name, a]));
+  const scoutAgent = byName.scout, coderAgent = byName.coder;
+  if (!scoutAgent || !coderAgent) throw new Error('pipeline requires scout and coder agents');
+  const testCommand = detectTestCommand(repoRoot);
+  const baseline = runTests(repoRoot, testCommand);
+  const summary = { task, repoRoot, testCommand, baselineTestsPass: baseline.ok, steps: trace };
+
+  // ---- scout -> Context Pack ----
+  let pack;
+  if (packPath) {
+    const n = normalizeContextPack(readFileSync(packPath, 'utf8'), { repoRoot, task, capability: coderAgent.meta.capability });
+    if (n.errors.length) throw new Error(`supplied Context Pack invalid: ${n.errors.join('; ')}`);
+    pack = n.pack;
+    summary.scoutNormalizerReport = n.report;
+    summary.packSource = packPath;
+    if (testCommand && !(pack.test_commands ?? []).length) pack.test_commands = [testCommand];
+  } else if (skipScout) {
+    throw new Error('skipScout requires packPath');
+  } else {
+    const survey = surveyRepo(repoRoot);
+    const prompt = scoutPrompt({ task, survey, testOutput: baseline.ok ? null : baseline.output, testCommand });
+    const scout = await withEscalation({
+      routing, registry, capability: scoutAgent.meta.capability, agent: 'scout', pack: { previous_attempts: [] }, maxAttempts, trace, ...hooks,
+      fn: async c => {
+        const r = await invoke({ ...c, systemPrompt: scoutAgent.body, prompt, cwd: repoRoot });
+        if (!r.ok) return { ok: false, reason: r.error ?? 'invoke failed' };
+        writeFileSync(join(outDir, `scout.output.${c.backend}.md`), r.text);
+        let n;
+        try { n = normalizeContextPack(r.text, { repoRoot, task, capability: coderAgent.meta.capability, producedBy: `scout@${c.modelId}` }); }
+        catch (e) { return { ok: false, reason: `scout output not a Context Pack: ${e.message}` }; }
+        if (n.errors.length) return { ok: false, reason: `Context Pack invalid: ${n.errors.join('; ')}` };
+        if (testCommand && !(n.pack.test_commands ?? []).length) n.pack.test_commands = [testCommand];
+        return { ok: true, reason: 'context pack produced', pack: n.pack, report: n.report, raw: r.text };
+      },
+    });
+    if (!scout.ok) { summary.outcome = 'scout-failed'; summary.escalationCandidate = scout.escalationCandidate; writeOut(outDir, summary); return summary; }
+    pack = scout.result.pack;
+    summary.scoutNormalizerReport = scout.result.report;
+    writeFileSync(join(outDir, 'scout.raw.md'), scout.result.raw);
+  }
+  const packFile = join(outDir, 'context-pack.md');
+  writeFileSync(packFile, toMarkdown(pack));
+  summary.contextPack = packFile;
+  summary.contextPackFiles = pack.relevant_files.map(f => f.path);
+
+  // ---- coder -> apply -> validate, with escalation ----
+  const coder = await withEscalation({
+    routing, registry, capability: coderAgent.meta.capability, agent: 'coder', pack, maxAttempts, trace, ...hooks,
+    fn: async c => {
+      const prompt = coderPrompt({ pack, repoRoot });
+      writeFileSync(join(outDir, `coder.input.${c.backend}.md`), `<!-- system -->\n${coderAgent.body}\n\n<!-- user -->\n${prompt}`);
+      const r = await invoke({ ...c, systemPrompt: coderAgent.body, prompt, cwd: repoRoot });
+      if (!r.ok) return { ok: false, reason: r.error ?? 'invoke failed' };
+      writeFileSync(join(outDir, `coder.output.${c.backend}.md`), r.text);
+      const blocks = parseFileBlocks(r.text);
+      if (!blocks.length) return { ok: false, reason: 'coder returned no FILE blocks' };
+      const { applied, rejected } = applyFileBlocks(repoRoot, blocks, pack.relevant_files);
+      if (!applied.length) return { ok: false, reason: `all ${rejected.length} file blocks rejected (outside relevant_files)` };
+      const tests = runTests(repoRoot, pack.test_commands?.[0] ?? testCommand);
+      if (!tests.ok) {
+        pack.observed_errors = [tests.output.slice(-2000)];
+        return { ok: false, reason: `tests failed after applying ${applied.join(', ')}`, applied, rejected, tests };
+      }
+      return { ok: true, reason: 'tests pass', applied, rejected, tests };
+    },
+  });
+  summary.outcome = coder.ok ? 'success' : (coder.exhausted ? 'exhausted' : 'escalation-candidate');
+  summary.escalated = coder.escalated ?? false;
+  summary.attempts = coder.attempts;
+  summary.escalationCandidate = coder.escalationCandidate ?? null;
+  summary.applied = coder.result?.applied ?? null;
+  writeFileSync(packFile, toMarkdown(pack)); // includes previous_attempts / observed_errors updates
+  writeOut(outDir, summary);
+  return summary;
+}
+
+function writeOut(outDir, summary) {
+  writeFileSync(join(outDir, 'trace.json'), JSON.stringify(summary, null, 2));
+}

package/lib/registry.mjs

@@ -0,0 +1,63 @@
+// Adapter model registry: models.json (shared template) overlaid by models.local.json (gitignored).
+// Validates against routing backends. Contains no provider/model names.
+import { readFileSync, existsSync } from 'node:fs';
+
+const BINDING_KEYS = new Set(['provider', 'model', 'thinking', 'note', 'vision']);
+const THINKING = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+const SECRET_KEYS = /^(apiKey|api_key|token|secret|password|bearer|authorization)$/i;
+const SECRET_VALUE = /(sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN)/;
+
+export function validateRegistry(registry, routing, label = 'registry') {
+  const errors = [];
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) return [`${label}: root must be an object`];
+  for (const key of Object.keys(registry)) {
+    if (!['version', 'backends', '$comment'].includes(key)) errors.push(`${label}: unknown top-level key "${key}"`);
+  }
+  if (registry.version !== 1) errors.push(`${label}: version must be 1`);
+  if (!registry.backends || typeof registry.backends !== 'object' || Array.isArray(registry.backends)) {
+    errors.push(`${label}: backends must be an object`);
+    return errors;
+  }
+  for (const [backend, binding] of Object.entries(registry.backends)) {
+    if (routing && !(backend in routing.backends)) errors.push(`${label}: backend "${backend}" is not defined in routing`);
+    if (!binding || typeof binding !== 'object' || Array.isArray(binding)) { errors.push(`${label}: backend "${backend}" binding must be an object`); continue; }
+    for (const key of Object.keys(binding)) {
+      if (SECRET_KEYS.test(key)) errors.push(`${label}: backend "${backend}" must not store credentials ("${key}")`);
+      else if (!BINDING_KEYS.has(key)) errors.push(`${label}: backend "${backend}" has unknown key "${key}"`);
+      if (typeof binding[key] === 'string' && SECRET_VALUE.test(binding[key])) errors.push(`${label}: backend "${backend}".${key} looks like a credential`);
+    }
+    if (binding.provider !== undefined && (typeof binding.provider !== 'string' || !binding.provider.trim())) errors.push(`${label}: backend "${backend}".provider must be a non-empty string`);
+    if (binding.model !== undefined && (typeof binding.model !== 'string' || !binding.model.trim())) errors.push(`${label}: backend "${backend}".model must be a non-empty string`);
+    if (binding.thinking !== undefined && !THINKING.has(binding.thinking)) errors.push(`${label}: backend "${backend}".thinking must be one of ${[...THINKING].join('|')}`);
+  }
+  return errors;
+}
+
+/** Shallow-per-backend merge: local binding fields override template fields; local may add backends. */
+export function mergeRegistries(base, local) {
+  const out = { version: 1, backends: {} };
+  for (const [b, v] of Object.entries(base?.backends ?? {})) out.backends[b] = { ...v };
+  for (const [b, v] of Object.entries(local?.backends ?? {})) out.backends[b] = { ...(out.backends[b] ?? {}), ...v };
+  return out;
+}
+
+export function isPlaceholder(binding) {
+  return !binding || !binding.provider || !binding.model || /^TODO/i.test(binding.provider) || /^TODO/i.test(binding.model);
+}
+
+/**
+ * Load <adapterDir>/models.json overlaid with <adapterDir>/models.local.json (if present).
+ * Throws on validation errors of either file or of the merged result.
+ */
+export function loadRegistry(modelsPath, localPath, routing) {
+  const base = JSON.parse(readFileSync(modelsPath, 'utf8'));
+  const errors = validateRegistry(base, routing, 'models.json');
+  let local = null;
+  if (localPath && existsSync(localPath)) {
+    local = JSON.parse(readFileSync(localPath, 'utf8'));
+    errors.push(...validateRegistry(local, routing, 'models.local.json'));
+  }
+  if (errors.length) throw new Error(errors.join('\n'));
+  const merged = mergeRegistries(base, local);
+  return { registry: merged, sources: { models: modelsPath, local: local ? localPath : null } };
+}

package/lib/resolve.mjs

@@ -0,0 +1,35 @@
+// agent -> capability -> routing backends -> registry binding -> concrete model candidates.
+// Generic over adapters: the registry decides what "provider/model" means. No names hardcoded.
+import { resolveBackends, degradedBackends } from './routing.mjs';
+import { isPlaceholder } from './registry.mjs';
+
+/** Format a binding as pi-style "provider/model[:thinking]" (pi CLI --model / pi-subagents model syntax). */
+export function formatModelId(binding, { withThinking = true } = {}) {
+  const id = `${binding.provider}/${binding.model}`;
+  return withThinking && binding.thinking ? `${id}:${binding.thinking}` : id;
+}
+
+/** Ordered candidate chain for one capability. Placeholders/unbound backends are excluded but reported. */
+export function resolveCapability(routing, registry, capability) {
+  const chain = resolveBackends(routing, capability);
+  const degraded = new Set(degradedBackends(routing, capability));
+  const candidates = [], unbound = [], placeholder = [];
+  for (const backend of chain) {
+    const binding = registry.backends?.[backend];
+    if (!binding) { unbound.push(backend); continue; }
+    if (isPlaceholder(binding)) { placeholder.push(backend); continue; }
+    candidates.push({ backend, provider: binding.provider, model: binding.model, thinking: binding.thinking, modelId: formatModelId(binding), degraded: degraded.has(backend) || undefined });
+  }
+  return { capability, chain, candidates, unbound, placeholder };
+}
+
+/** Resolve every agent (from lib/agents.mjs loadAgents) to its capability chain. */
+export function resolveAgents(agents, routing, registry) {
+  const out = {};
+  for (const agent of agents) {
+    const capability = agent.meta.capability;
+    if (!(capability in routing.capabilities)) continue;
+    out[agent.meta.name] = { agent: agent.meta.name, ...resolveCapability(routing, registry, capability) };
+  }
+  return out;
+}

package/lib/routing.mjs

@@ -0,0 +1,137 @@
+// Minimal routing config loader/validator. No provider or model names are hardcoded here;
+// everything comes from routing.json (logical backends) and adapter model maps (concrete bindings).
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+const TIERS = new Set(['free', 'low', 'mid', 'high']);
+
+export function validateRouting(config) {
+  const errors = [];
+  const err = m => errors.push(m);
+  if (!config || typeof config !== 'object' || Array.isArray(config)) return ['routing: root must be an object'];
+  if (config.version !== 1) err('routing: version must be 1');
+  const backends = config.backends;
+  if (!backends || typeof backends !== 'object' || Object.keys(backends).length === 0) {
+    err('routing: backends must be a non-empty object');
+  } else {
+    for (const [name, b] of Object.entries(backends)) {
+      if (!NAME.test(name)) err(`routing: invalid backend name "${name}"`);
+      if (!b || typeof b !== 'object') { err(`routing: backend "${name}" must be an object`); continue; }
+      if (b.tier !== undefined && !TIERS.has(b.tier)) err(`routing: backend "${name}" has invalid tier "${b.tier}"`);
+      if (b.vision !== undefined && typeof b.vision !== 'boolean') err(`routing: backend "${name}".vision must be boolean`);
+    }
+  }
+  const caps = config.capabilities;
+  if (!caps || typeof caps !== 'object' || Object.keys(caps).length === 0) {
+    err('routing: capabilities must be a non-empty object');
+  } else {
+    for (const [name, c] of Object.entries(caps)) {
+      if (!NAME.test(name)) err(`routing: invalid capability name "${name}"`);
+      if (!c || typeof c !== 'object') { err(`routing: capability "${name}" must be an object`); continue; }
+      if (typeof c.primary !== 'string') err(`routing: capability "${name}" requires string primary`);
+      else if (backends && !(c.primary in backends)) err(`routing: capability "${name}" primary "${c.primary}" is not a defined backend`);
+      const fallback = c.fallback ?? [];
+      if (!Array.isArray(fallback)) err(`routing: capability "${name}".fallback must be an array`);
+      else {
+        const seen = new Set();
+        for (const f of fallback) {
+          if (typeof f !== 'string') { err(`routing: capability "${name}" fallback entries must be strings`); continue; }
+          if (backends && !(f in backends)) err(`routing: capability "${name}" fallback "${f}" is not a defined backend`);
+          if (f === c.primary) err(`routing: capability "${name}" fallback repeats primary "${f}"`);
+          if (seen.has(f)) err(`routing: capability "${name}" fallback repeats "${f}"`);
+          seen.add(f);
+        }
+      }
+      // requires.vision is enforced on primary; fallbacks may be degraded (reported by resolveBackends).
+      if (c.requires?.vision === true && backends && backends[c.primary] && backends[c.primary].vision !== true) {
+        err(`routing: capability "${name}" requires vision but primary backend "${c.primary}" is not vision-capable`);
+      }
+    }
+  }
+  if (config.escalation?.ladders) {
+    for (const [ladder, steps] of Object.entries(config.escalation.ladders)) {
+      if (!Array.isArray(steps) || steps.length === 0) { err(`routing: ladder "${ladder}" must be a non-empty array`); continue; }
+      for (const s of steps) if (caps && !(s in caps)) err(`routing: ladder "${ladder}" references unknown capability "${s}"`);
+    }
+  }
+  return errors;
+}
+
+// Machine-local capability overrides: null disables a shared capability;
+// an object overrides its route or adds a new capability. The shared file is
+// never modified. Deleted capabilities are removed from escalation ladders
+// in the effective view; agents referencing them are unavailable.
+export function mergeLocalRouting(base, local) {
+  if (!local || local.version !== 1 || !local.capabilities || typeof local.capabilities !== 'object' || Array.isArray(local.capabilities) ||
+      Object.keys(local).some(k => !['version', 'capabilities', '$comment'].includes(k))) {
+    throw new Error('routing.local.json: expected version 1 and capabilities object');
+  }
+  const config = { ...base, capabilities: { ...base.capabilities } };
+  for (const [name, override] of Object.entries(local.capabilities)) {
+    if (!NAME.test(name)) throw new Error(`routing.local.json: invalid capability name "${name}"`);
+    if (override === null) {
+      if (!(name in base.capabilities)) throw new Error(`routing.local.json: cannot delete unknown capability "${name}"`);
+      delete config.capabilities[name];
+      continue;
+    }
+    if (!override || typeof override !== 'object' || Array.isArray(override) ||
+        Object.keys(override).some(k => !['primary', 'fallback', 'description'].includes(k))) {
+      throw new Error(`routing.local.json: invalid capability override "${name}"`);
+    }
+    if (override.primary !== undefined && typeof override.primary !== 'string') throw new Error(`routing.local.json: capability "${name}" primary must be a string`);
+    if (override.fallback !== undefined && (!Array.isArray(override.fallback) || override.fallback.some(value => typeof value !== 'string'))) throw new Error(`routing.local.json: capability "${name}" fallback must be an array of strings`);
+    if (override.description !== undefined && typeof override.description !== 'string') throw new Error(`routing.local.json: capability "${name}" description must be a string`);
+    config.capabilities[name] = { ...(base.capabilities[name] ?? {}), ...override };
+  }
+  if (base.escalation?.ladders) {
+    const ladders = Object.fromEntries(Object.entries(base.escalation.ladders)
+      .map(([name, steps]) => [name, steps.filter(step => step in config.capabilities)])
+      .filter(([, steps]) => steps.length));
+    config.escalation = { ...base.escalation, ladders };
+  }
+  const errors = validateRouting(config);
+  if (errors.length) throw new Error(errors.join('\n'));
+  return config;
+}
+
+export function loadRouting(path) {
+  const config = JSON.parse(readFileSync(path, 'utf8'));
+  const errors = validateRouting(config);
+  if (errors.length) throw new Error(errors.join('\n'));
+  const localPath = join(dirname(path), 'routing.local.json');
+  return existsSync(localPath) ? mergeLocalRouting(config, JSON.parse(readFileSync(localPath, 'utf8'))) : config;
+}
+
+/** Ordered backend candidates for a capability: primary first, then fallbacks. */
+export function resolveBackends(config, capability) {
+  const cap = config.capabilities[capability];
+  if (!cap) throw new Error(`routing: unknown capability "${capability}"`);
+  return [cap.primary, ...(cap.fallback ?? [])];
+}
+
+/** Backends in the chain that do not satisfy the capability's `requires` (e.g. non-vision fallback). */
+export function degradedBackends(config, capability) {
+  const cap = config.capabilities[capability];
+  if (!cap?.requires) return [];
+  return resolveBackends(config, capability).filter(b => {
+    const backend = config.backends[b] ?? {};
+    return cap.requires.vision === true && backend.vision !== true;
+  });
+}
+
+/**
+ * Resolve a capability to concrete provider/model candidates using an adapter model map
+ * of shape { backends: { <backend>: { provider, model, ... } } }. Backends without a
+ * binding are skipped (reported in `unbound`), so a missing local model never breaks routing.
+ */
+export function resolveModels(config, modelMap, capability) {
+  const bound = [], unbound = [];
+  const degraded = degradedBackends(config, capability);
+  for (const backend of resolveBackends(config, capability)) {
+    const binding = modelMap?.backends?.[backend];
+    if (binding && binding.provider && binding.model) bound.push({ backend, ...binding, degraded: degraded.includes(backend) || undefined });
+    else unbound.push(backend);
+  }
+  return { capability, candidates: bound, unbound, degraded };
+}