@ludi-uni/ludi-agent-kit 0.1.0

package/lib/orchestrator/permissions.mjs

@@ -0,0 +1,64 @@
+// Tool access is separate from routing capability. `tools:` on an agent remains the pi tool-name
+// list; `access` says what the orchestrator may actually grant.
+export const EXECUTION_MODES = ['oneshot', 'subagent', 'pipeline'];
+const FILESYSTEM = new Set(['read', 'read-write']);
+const SHELL = new Set(['false', 'limited', 'true']);
+const GIT = new Set(['none', 'read']);
+
+export function accessOf(agent) {
+  const raw = agent?.meta?.access;
+  if (raw && typeof raw === 'object') {
+    return {
+      filesystem: FILESYSTEM.has(raw.filesystem) ? raw.filesystem : 'read',
+      shell: SHELL.has(String(raw.shell)) ? String(raw.shell) : 'false',
+      git: GIT.has(raw.git) ? raw.git : 'none',
+      network: raw.network === true,
+    };
+  }
+  const names = String(agent?.meta?.tools ?? '').split(',').map(s => s.trim()).filter(Boolean);
+  const write = names.some(n => n === 'edit' || n === 'write');
+  const shell = names.some(n => n === 'powershell' || n === 'bash');
+  return { filesystem: write ? 'read-write' : 'read', shell: shell ? 'limited' : 'false', git: 'read', network: false };
+}
+
+export function validateAccess(access, name) {
+  const errors = [];
+  if (!access || typeof access !== 'object') return errors;
+  if (access.filesystem !== undefined && !FILESYSTEM.has(access.filesystem)) errors.push(`agent ${name}: access.filesystem must be read|read-write`);
+  if (access.shell !== undefined && !SHELL.has(String(access.shell))) errors.push(`agent ${name}: access.shell must be false|limited|true`);
+  if (access.git !== undefined && !GIT.has(access.git)) errors.push(`agent ${name}: access.git must be none|read`);
+  if (access.network !== undefined && typeof access.network !== 'boolean') errors.push(`agent ${name}: access.network must be boolean`);
+  return errors;
+}
+
+/** pi --tools allowlist. Raw bash/powershell are never granted; shell goes through ludi_exec. */
+export function piToolsForAccess(access) {
+  const tools = ['read', 'grep', 'find', 'ls'];
+  if (access.filesystem === 'read-write') tools.push('edit', 'write');
+  if (access.shell !== 'false') tools.push('ludi_exec');
+  return tools;
+}
+
+/** Mode named by the task or the agent file, before runner availability is applied. */
+export function declaredMode(agent, task, { pipelineAgents = [] } = {}) {
+  if (pipelineAgents.includes(agent?.meta?.name) || task?.executionMode === 'pipeline') return 'pipeline';
+  const requested = task?.executionMode ?? agent?.meta?.execution?.preferred_mode ?? agent?.meta?.execution;
+  if (EXECUTION_MODES.includes(requested)) return requested;
+  if (['coder', 'tester'].includes(agent?.meta?.name)) return 'subagent';
+  return 'oneshot';
+}
+
+export function resolveExecutionMode(agent, task, { pipelineAgents = [], hasSubagent = false } = {}) {
+  if (pipelineAgents.includes(agent?.meta?.name)) return 'pipeline';
+  const requested = task?.executionMode ?? agent?.meta?.execution?.preferred_mode ?? agent?.meta?.execution;
+  if (requested === 'pipeline') return 'pipeline';
+  if (requested === 'oneshot') return 'oneshot';
+  if (requested === 'subagent') return hasSubagent ? 'subagent' : 'oneshot';
+  if (hasSubagent && ['coder', 'tester'].includes(agent?.meta?.name)) return 'subagent';
+  return 'oneshot';
+}
+
+export function workspaceOf(task, repoRoot) {
+  const path = task?.workspace?.path ?? repoRoot ?? null;
+  return { path, repository: task?.workspace?.repository ?? repoRoot ?? path };
+}

package/lib/orchestrator/planner.mjs

@@ -0,0 +1,194 @@
+// Planner: high-level request -> task specs. Two strategies, same output shape:
+//   rules - deterministic keyword template (no model call; default, used by dry-run)
+//   model - the orchestrator agent returns a JSON plan; invalid output falls back to rules
+import { withEscalation } from '../pipeline.mjs';
+import { routeTask, workerAgents, ORCHESTRATOR_AGENT } from './router.mjs';
+import { findCycle } from './task-store.mjs';
+
+const RE = {
+  implement: /\b(implement|fix|add|create|build|refactor|update|change|migrate|write|support)\b|進め|実装|修正|追加|作成|対応|改善|変更|移行|作る/i,
+  review: /\b(review|audit)\b|レビュー|監査/i,
+  investigate: /\b(investigate|explain|analy[sz]e|research|survey|find out)\b|調査|説明|分析|調べ/i,
+  visual: /\b(screenshot|visual|ui|image|animation|video|render(ing)?)\b|画面|見た目|画像|アニメ|動画|描画/i,
+  browser: /\b(browser|web ?page|localhost|url)\b|ブラウザ|webページ|ウェブ/i,
+  history: /\b(commit history|git log|past commits|previous commits|commit(s)? histor\w*|changelog|previous changes)\b|コミット履歴|変更履歴|過去のコミット/i,
+  // ASCII words need \b on both sides ("build", "guide", "linux", "requires" must
+  // not match); Japanese has no word boundary, so 画面/好み stand alone.
+  ui: /\b(ui|ux|interface|screen|design|layout|preference)\b|画面|好み/i,
+};
+
+// Context-aware history detection: bare "コミット"/"commit" alone is not a history
+// investigation ("このコミットを修正して", "add a pre-commit hook" are single-commit
+// or tooling work). It is one only when combined with ANALYSIS context (infer
+// preferences / style / patterns / trends). Everyday words ("from", "instructions",
+// "から") are deliberately NOT context.
+const HISTORY_CONTEXT = {
+  ja: /コミット(?!を(修正|直し|適用|打ち|作|追加|戻|取り消))/i,
+  jaContext: /好み|推測|推定|傾向|履歴|分析|スタイル|方針|パターン/i,
+  en: /(?<![\w-])commits?\b/i, // excludes "pre-commit", "post-commit"
+  enContext: /\b(infer|guess|preferences?|style|patterns?|history|past|previous|trends?|analy[sz]e|author'?s?)\b/i,
+};
+
+function detectHistory(request) {
+  if (RE.history.test(request)) return true;
+  // Japanese: コミット + analysis/preference context, but not コミットを修正/fix.
+  if (HISTORY_CONTEXT.ja.test(request) && HISTORY_CONTEXT.jaContext.test(request)) return true;
+  // English: commit(s) + analysis/preference context.
+  if (HISTORY_CONTEXT.en.test(request) && HISTORY_CONTEXT.enContext.test(request)) return true;
+  return false;
+}
+
+// Explicit stage gating: "まずPhase 0だけを開始", "Phase 0の調査が終わるまでは実装を
+// 始めない", "start only phase 0", "don't implement until the investigation is
+// done". The user authorized ONE stage now, so keywords belonging to later phases
+// (実装, fix, browser check, review) must not spawn implement/verify/review tasks.
+const STAGED = {
+  // A numbered phase explicitly narrowed with だけ/のみ/only.
+  phaseOnly: /(phase|stage|step|フェーズ|段階)\s*\d+\s*(だけ|のみ|only)|\bonly\b[^.\n]{0,15}\b(phase|stage|step)\s*\d+/i,
+  // Investigation/research only.
+  invOnly: /(調査|分析|investigat\w*|research|analysis)\s*(だけ|のみ)|\b(?:investigat\w*|research|analysis)\b[^.\n]{0,20}\bonly\b|\bonly\b[^.\n]{0,20}\b(?:investigat\w*|research|analysis)\b/i,
+  // "まず〜だけ/のみ" or "〜だけ/のみを開始・着手" — one stage authorized now. On its
+  // own this is ambiguous ("まずこれだけ直して" is a scoped fix), so it counts only
+  // when a phase/investigation marker is present too (see isStagedScope).
+  firstOnly: /まず[^。\n]{0,60}?(だけ|のみ)|(だけ|のみ)(?:を|の)(?:開始|着手|実行|進め)/i,
+  phaseOrInv: /phase|stage|step|フェーズ|段階|調査|分析|investigat|research/i,
+  // An explicit hold on implementation: "〜までは実装を始めない", "実装はまだ",
+  // "do not implement until ...", "hold off on implementation".
+  hold: /までは?[^。\n]{0,60}?(始めない|しない|やめ|待)|実装(を|は|への)?(始めない|しない|着手しない|入らない|まだ|後で|待って)|\b(?:do not|don'?t|not yet|hold off)\b[^.\n]{0,60}\b(?:implement\w*|cod\w*|build|chang\w*|develop\w*|modif\w*)\b|\bwait\b[^.\n]{0,40}\buntil\b[^.\n]{0,40}\b(?:implement\w*|chang\w*|build)\b|\b(?:implement\w*|development|coding)\b[^.\n]{0,40}\buntil\b/i,
+};
+
+function isStagedScope(request) {
+  if (STAGED.hold.test(request) || STAGED.phaseOnly.test(request) || STAGED.invOnly.test(request)) return true;
+  return STAGED.firstOnly.test(request) && STAGED.phaseOrInv.test(request);
+}
+
+export function classifyRequest(request) {
+  const has = k => RE[k].test(request);
+  const staged = isStagedScope(request);
+  const implement = !staged && (has('implement') || (!has('review') && !has('investigate')));
+  return { implement, review: !staged && (has('review') || implement), visual: !staged && has('visual'), browser: !staged && has('browser'), history: detectHistory(request), ui: has('ui'), staged };
+}
+
+/**
+ * A request that mixes several independent investigation concerns (e.g. commit
+ * history AND current-implementation analysis AND preference extraction) is too
+ * big for one scout pass — it blows the turn budget. Split it into focused
+ * sub-investigations plus a synthesis step so each subagent stays small.
+ */
+function splitInvestigation(request, c, add) {
+  const concerns = [];
+  if (c.history) concerns.push({ key: 'history', title: 'Analyze commit history for preferences', goal: `From the repository's commit history, extract the author's preferences and working style relevant to: ${request}` });
+  if (c.ui || c.visual) concerns.push({ key: 'ui', title: 'Inspect current UI/UX implementation', goal: `Investigate the current UI/UX implementation relevant to: ${request}. Identify concrete files and patterns.` });
+  // Only split when there are genuinely independent concerns; otherwise one scout.
+  if (concerns.length < 2) return null;
+  const ids = [];
+  for (const con of concerns) {
+    const id = add('scout', { kind: 'investigate', title: con.title, goal: con.goal, dependencies: [],
+      acceptance: ['concrete evidence (files, commits, or patterns) is reported', 'findings are specific, not generic'] });
+    if (id) ids.push(id);
+  }
+  const synth = add('scout', { kind: 'investigate', title: 'Synthesize implementation context', goal: `Combine the investigation results into a single implementation context for: ${request}`, dependencies: ids,
+    acceptance: ['relevant files, constraints and test commands are identified', 'open questions are listed, or explicitly none'] });
+  return synth ? [synth] : ids;
+}
+
+export function planRules(request, { agents, policy = null }) {
+  const names = new Set(workerAgents(agents).map(a => a.meta.name));
+  const c = classifyRequest(request);
+  const tasks = [];
+  const add = (agent, spec) => { if (!names.has(agent)) return null; const id = `t${tasks.length + 1}`; tasks.push({ id, agent, ...spec }); return id; };
+  // Split a multi-concern investigation into focused sub-tasks + a synthesis step
+  // so no single scout is overloaded (prevents turn-limit stalls on big repos).
+  // Runs whenever the request mixes independent concerns, not only when the
+  // 'investigate' keyword fired — an implement+history+ui request still needs it.
+  const split = splitInvestigation(request, c, add);
+  const base = split ?? (() => {
+    const scout = add('scout', { kind: 'investigate', title: 'Investigate scope and context', goal: `Identify the files, constraints, open questions and test commands needed for: ${request}`, dependencies: [],
+      acceptance: ['relevant files, constraints and test commands are identified', 'open questions are listed, or explicitly none'] });
+    return scout ? [scout] : [];
+  })();
+  const impl = c.implement ? add('coder', { kind: 'implement', title: 'Implement the change', goal: `Implement the smallest sufficient change for: ${request}`, dependencies: base,
+    acceptance: ['the requested change is implemented within the investigated constraints', 'the relevant tests were run and pass, or the failure is reported'] }) : null;
+  const verify = policy?.verification?.require_tester !== false;
+  const tested = impl && verify ? add('tester', { kind: 'verify', title: 'Run tests', goal: `Run the repository tests for: ${request}. Do not implement further changes unless a test command itself is misconfigured.`, dependencies: [impl],
+    acceptance: ['the relevant tests were executed', 'pass or fail is reported with the command and output'] }) : null;
+  const after = tested ? [tested] : impl ? [impl] : base;
+  const checks = [];
+  if (c.visual) checks.push(add('visual', { kind: 'verify', title: 'Verify visual result', goal: `Verify the visual outcome of: ${request}`, dependencies: after,
+    acceptance: ['the visual result was inspected with concrete evidence'] }));
+  if (c.browser) checks.push(add('browser', { kind: 'verify', title: 'Verify in browser', goal: `Verify the browser behavior of: ${request}`, dependencies: after,
+    acceptance: ['the page behavior was exercised and observed'] }));
+  if (c.review) add('reviewer', { kind: 'review', title: 'Review result and risks', goal: `Review the outcome of "${request}" for correctness, regressions and risk`, dependencies: [...after, ...checks.filter(Boolean)],
+    acceptance: ['findings are listed by severity, or explicitly none', 'verified checks are separated from read-only observations'] });
+  return { planner: 'rules', classification: c, tasks };
+}
+
+/** Validate task specs (from any planner or from agent-discovered work) and route them. */
+export function validatePlan(specs, { agents, routing, policy, existingIds = [] }) {
+  const errors = [];
+  if (!Array.isArray(specs) || !specs.length) return { errors: ['plan: at least one task is required'], tasks: [] };
+  const max = policy.limits.max_tasks;
+  if (specs.length + existingIds.length > max) errors.push(`plan: ${specs.length + existingIds.length} tasks exceed limits.max_tasks=${max}`);
+  const ids = new Set(existingIds);
+  const tasks = [];
+  for (const s of specs) {
+    if (!s || typeof s.id !== 'string' || !s.id) { errors.push('plan: every task needs a string id'); continue; }
+    if (ids.has(s.id)) errors.push(`plan: duplicate task id "${s.id}"`);
+    ids.add(s.id);
+    if (typeof s.title !== 'string' || typeof s.goal !== 'string' || !s.goal.trim()) errors.push(`plan: task "${s.id}" needs title and goal`);
+    const r = routeTask(s, { agents, routing });
+    if (r.error) { errors.push(`plan: ${r.error}`); continue; }
+    tasks.push({ id: s.id, title: s.title, goal: s.goal, kind: s.kind, assignedAgent: r.agent, capability: r.capability,
+      dependencies: Array.isArray(s.dependencies) ? s.dependencies : [], acceptance: Array.isArray(s.acceptance) ? s.acceptance.map(String) : [], outputs: Array.isArray(s.outputs) ? s.outputs.map(String) : [] });
+  }
+  for (const t of tasks) for (const d of t.dependencies) if (!ids.has(d)) errors.push(`plan: task "${t.id}" depends on unknown task "${d}"`);
+  const cycle = findCycle(tasks);
+  if (cycle) errors.push(`plan: dependency cycle ${cycle.join(' -> ')}`);
+  return { errors, tasks };
+}
+
+/** Fenced blocks paired line by line, so an earlier ```bash block cannot swallow a later ```json fence. */
+export function fencedBlocks(text) {
+  const blocks = [];
+  let open = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    const fence = /^\s*```\s*([\w-]*)\s*$/.exec(line);
+    if (open) { if (fence && !fence[1]) { blocks.push(open); open = null; } else open.body.push(line); }
+    else if (fence) open = { lang: fence[1].toLowerCase(), body: [] };
+  }
+  return blocks.map(b => ({ lang: b.lang, content: b.body.join('\n') }));
+}
+
+export function parseJsonBlock(text) {
+  const blocks = fencedBlocks(text).reverse();
+  for (const b of [...blocks.filter(b => b.lang === 'json'), ...blocks.filter(b => !b.lang)]) { try { return JSON.parse(b.content); } catch { /* try next */ } }
+  try { return JSON.parse(String(text).trim()); } catch { return null; }
+}
+
+export function plannerPrompt(request, { agents, routing, policy }) {
+  const roster = workerAgents(agents).map(a => `- ${a.meta.name} (capability ${a.meta.capability}): ${a.meta.description}`).join('\n');
+  const caps = Object.entries(routing.capabilities).map(([k, v]) => `- ${k}: ${v.description ?? ''}`).join('\n');
+  return [
+    `Request: ${request}`, '', '## Agents', roster, '', '## Capabilities', caps, '',
+    `Decompose the request into at most ${policy.limits.max_tasks} tasks. Reply with one fenced json block:`,
+    '{"tasks":[{"id":"t1","title":"...","goal":"...","agent":"<agent>","kind":"investigate|implement|verify|review","dependencies":[],"acceptance":["..."]}]}',
+    'Use only the agents listed. Every task needs verifiable acceptance criteria. Do not ask the user anything.',
+  ].join('\n');
+}
+
+export async function planWithModel(request, { agents, routing, registry, policy, invoke, cwd, trace = [], health = null }) {
+  const orch = agents.find(a => a.meta.name === ORCHESTRATOR_AGENT);
+  const fallback = reason => ({ ...planRules(request, { agents, policy }), fallbackFrom: 'model', fallbackReason: reason });
+  if (!orch) return fallback('orchestrator agent not found');
+  let r;
+  try {
+    r = await withEscalation({ routing, registry, capability: orch.meta.capability, agent: ORCHESTRATOR_AGENT, pack: { previous_attempts: [] }, maxAttempts: policy.limits.model_attempts_per_task, trace, skip: health?.skip, onFailure: health?.report,
+      fn: async c => { const x = await invoke({ ...c, systemPrompt: orch.body, prompt: plannerPrompt(request, { agents, routing, policy }), cwd }); return x.ok ? { ok: true, reason: 'plan received', text: x.text } : { ok: false, reason: x.error ?? 'invoke failed' }; } });
+  } catch (e) { return fallback(e.message); }
+  if (!r.ok) return fallback(r.last?.reason ?? 'planner model failed');
+  const json = parseJsonBlock(r.result.text);
+  if (!json?.tasks) return fallback('planner output had no JSON tasks');
+  const { errors } = validatePlan(json.tasks, { agents, routing, policy });
+  if (errors.length) return fallback(errors.join('; '));
+  return { planner: 'model', modelId: r.candidate.modelId, tasks: json.tasks };
+}

package/lib/orchestrator/policy.mjs

@@ -0,0 +1,134 @@
+// Decision policy + orchestration limits. Defaults here are overlaid by orchestration/decision-policy.json
+// and an optional decision-policy.local.json, so behavior is configuration, not code.
+import { readFileSync, existsSync } from 'node:fs';
+
+export const ESCALATION_FLAGS = [
+  'external_publish', 'destructive_action', 'production_risk', 'high_cost',
+  'project_cancellation', 'major_direction_change', 'user_value_judgement',
+];
+const AUTO_MODES = new Set(['auto', 'escalate']);
+
+export const DEFAULT_POLICY = {
+  version: 1,
+  decision_policy: {
+    prefer_maintainability: true,
+    prefer_existing_assets: true,
+    prefer_reversible_actions: true,
+    max_parallel_tasks: 3,
+    poc: { prefer_if_estimated_hours_lte: 2 },
+    escalation: Object.fromEntries(ESCALATION_FLAGS.map(f => [f, true])),
+    escalation_keywords: {},
+    high_cost_threshold_usd: 50,
+    major_direction_change_weeks: 2,
+    default_behavior: { reversible_decision: 'auto', low_risk_decision: 'auto' },
+    reassign_on_failure: true,
+  },
+  limits: {
+    max_tasks: 12, max_retries: 2, max_rounds: 12, max_rework_cycles: 1,
+    // Attempt budget. model_attempts_per_task caps candidates tried per task
+    // attempt (candidate progression within an attempt). max_total_attempts_per_task
+    // caps total model calls across retries so a protocol-failing model cannot
+    // consume the whole budget before a different candidate is reached.
+    model_attempts_per_task: 3, max_total_attempts_per_task: 4,
+  },
+  backend_health: { usage_exhausted_ttl_hours: 6, rate_limited_ttl_minutes: 15, unavailable_ttl_minutes: 10 },
+  verification: { require_tester: true, require_reviewer: true },
+  agent_runtime: {
+    max_runtime_ms: 600000, max_tool_calls: 40, max_turns: 12,
+    // Per-role / per-complexity turn budgets. A task's initial turn budget is
+    // turn_budgets[<role>][<complexity>] falling back to turn_budgets[<role>].normal
+    // then max_turns. Bounded progress extension: when a subagent reaches its
+    // initial budget but is still making meaningful progress, it may be granted up
+    // to extension_turns more turns, at most max_extensions times, never exceeding
+    // absolute_max_turns. No unbounded growth.
+    turn_budgets: {
+      default:    { simple: 12, normal: 16, heavy: 20, 'repo-history-heavy': 24 },
+      scout:      { simple: 12, normal: 16, heavy: 20, 'repo-history-heavy': 24 },
+      coder:      { simple: 16, normal: 20, heavy: 24, 'repo-history-heavy': 24 },
+      tester:     { simple: 12, normal: 16, heavy: 20, 'repo-history-heavy': 20 },
+      reviewer:   { simple: 12, normal: 16, heavy: 20, 'repo-history-heavy': 20 },
+    },
+    extension_turns: 8, max_extensions: 2, absolute_max_turns: 32,
+  },
+};
+
+const isObj = v => v && typeof v === 'object' && !Array.isArray(v);
+
+export function mergePolicy(base, override) {
+  if (!isObj(override)) return structuredClone(base);
+  const out = structuredClone(base);
+  for (const [k, v] of Object.entries(override)) out[k] = isObj(v) && isObj(out[k]) ? mergePolicy(out[k], v) : structuredClone(v);
+  return out;
+}
+
+export function validatePolicy(p) {
+  const errors = [];
+  const err = m => errors.push(`policy: ${m}`);
+  if (!isObj(p)) return ['policy: root must be an object'];
+  if (p.version !== 1) err('version must be 1');
+  const d = p.decision_policy, l = p.limits;
+  if (!isObj(d)) err('decision_policy must be an object');
+  else {
+    for (const k of ['prefer_maintainability', 'prefer_existing_assets', 'prefer_reversible_actions', 'reassign_on_failure']) if (typeof d[k] !== 'boolean') err(`decision_policy.${k} must be boolean`);
+    if (!Number.isInteger(d.max_parallel_tasks) || d.max_parallel_tasks < 1) err('decision_policy.max_parallel_tasks must be an integer >= 1');
+    if (typeof d.poc?.prefer_if_estimated_hours_lte !== 'number') err('decision_policy.poc.prefer_if_estimated_hours_lte must be a number');
+    for (const [k, v] of Object.entries(d.escalation ?? {})) {
+      if (!ESCALATION_FLAGS.includes(k)) err(`decision_policy.escalation has unknown flag "${k}"`);
+      if (typeof v !== 'boolean') err(`decision_policy.escalation.${k} must be boolean`);
+    }
+    for (const [k, v] of Object.entries(d.escalation_keywords ?? {})) {
+      if (!ESCALATION_FLAGS.includes(k)) err(`decision_policy.escalation_keywords has unknown flag "${k}"`);
+      if (!Array.isArray(v) || v.some(s => typeof s !== 'string')) err(`decision_policy.escalation_keywords.${k} must be a string array`);
+    }
+    for (const k of ['reversible_decision', 'low_risk_decision']) if (!AUTO_MODES.has(d.default_behavior?.[k])) err(`decision_policy.default_behavior.${k} must be auto|escalate`);
+  }
+  if (!isObj(l)) err('limits must be an object');
+  else for (const k of ['max_tasks', 'max_retries', 'max_rounds', 'max_rework_cycles', 'model_attempts_per_task', 'max_total_attempts_per_task']) {
+    const min = k === 'max_retries' || k === 'max_rework_cycles' ? 0 : 1;
+    if (l[k] !== undefined && (!Number.isInteger(l[k]) || l[k] < min)) err(`limits.${k} must be an integer >= ${min}`);
+  }
+  const h = p.backend_health;
+  if (h !== undefined) {
+    if (!isObj(h)) err('backend_health must be an object');
+    else {
+      if (typeof h.usage_exhausted_ttl_hours !== 'number' || h.usage_exhausted_ttl_hours <= 0) err('backend_health.usage_exhausted_ttl_hours must be a number > 0');
+      for (const k of ['rate_limited_ttl_minutes', 'unavailable_ttl_minutes']) if (typeof h[k] !== 'number' || h[k] <= 0) err(`backend_health.${k} must be a number > 0`);
+    }
+  }
+  if (p.verification !== undefined) {
+    if (!isObj(p.verification)) err('verification must be an object');
+    else for (const k of ['require_tester', 'require_reviewer']) if (p.verification[k] !== undefined && typeof p.verification[k] !== 'boolean') err(`verification.${k} must be boolean`);
+  }
+  if (p.agent_runtime !== undefined) {
+    const ar = p.agent_runtime;
+    if (!isObj(ar)) err('agent_runtime must be an object');
+    else {
+      for (const k of ['max_runtime_ms', 'max_tool_calls', 'max_turns']) if (!Number.isInteger(ar[k]) || ar[k] < 1) err(`agent_runtime.${k} must be an integer >= 1`);
+      for (const k of ['extension_turns', 'max_extensions', 'absolute_max_turns']) if (ar[k] !== undefined && (!Number.isInteger(ar[k]) || ar[k] < 0)) err(`agent_runtime.${k} must be an integer >= 0`);
+      if (ar.absolute_max_turns !== undefined && ar.absolute_max_turns < ar.max_turns) err('agent_runtime.absolute_max_turns must be >= max_turns');
+      if (ar.turn_budgets !== undefined) {
+        if (!isObj(ar.turn_budgets)) err('agent_runtime.turn_budgets must be an object');
+        else for (const [role, tiers] of Object.entries(ar.turn_budgets)) {
+          if (!isObj(tiers)) err(`agent_runtime.turn_budgets.${role} must be an object`);
+          else for (const [tier, v] of Object.entries(tiers)) if (!Number.isInteger(v) || v < 1) err(`agent_runtime.turn_budgets.${role}.${tier} must be an integer >= 1`);
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+/** DEFAULT_POLICY <- policyPath <- localPath (each optional). Throws on invalid result. */
+export function loadPolicy(policyPath, localPath = null) {
+  let p = DEFAULT_POLICY;
+  const sources = [];
+  for (const path of [policyPath, localPath]) {
+    if (!path || !existsSync(path)) continue;
+    const { $comment, ...rest } = JSON.parse(readFileSync(path, 'utf8'));
+    p = mergePolicy(p, rest);
+    sources.push(path);
+  }
+  const errors = validatePolicy(p);
+  if (errors.length) throw new Error(errors.join('\n'));
+  return { policy: p, sources };
+}

package/lib/orchestrator/router.mjs

@@ -0,0 +1,45 @@
+// Router adapter: task -> capability -> agent -> model, entirely through the existing
+// agents/*.md capability binding, routing.json and the adapter model registry (lib/resolve.mjs).
+import { resolveCapability } from '../resolve.mjs';
+
+export const ORCHESTRATOR_AGENT = 'orchestrator';
+
+/** Agents that may receive delegated work (the orchestrator never assigns work to itself). */
+export function workerAgents(agents) {
+  return agents.filter(a => a.meta.name !== ORCHESTRATOR_AGENT);
+}
+
+export function agentForCapability(agents, capability) {
+  return workerAgents(agents).find(a => a.meta.capability === capability) ?? null;
+}
+
+/**
+ * Fill in agent/capability for a task spec and check both against the kit.
+ * An explicit agent keeps its role; an explicit capability overrides only the model route.
+ */
+export function routeTask(spec, { agents, routing }) {
+  const byName = Object.fromEntries(workerAgents(agents).map(a => [a.meta.name, a]));
+  let agent = spec.assignedAgent ?? spec.agent;
+  let capability = spec.capability;
+  if (agent === ORCHESTRATOR_AGENT) return { error: `task "${spec.id}": work cannot be assigned to the orchestrator itself` };
+  if (agent && !byName[agent]) return { error: `task "${spec.id}": unknown agent "${agent}"` };
+  if (!agent && capability) agent = agentForCapability(agents, capability)?.meta.name;
+  if (!agent) return { error: `task "${spec.id}": no agent for capability "${capability}"` };
+  capability = capability ?? byName[agent].meta.capability;
+  if (!routing.capabilities[capability]) return { error: `task "${spec.id}": capability "${capability}" is not defined in routing` };
+  return { agent, capability };
+}
+
+/** Concrete model chain for a task's capability (report shape from resolveCapability). */
+export function resolveTaskModels(task, { routing, registry }) {
+  return resolveCapability(routing, registry, task.capability);
+}
+
+/** Next capability after `capability` in any routing escalation ladder (e.g. cheap-code -> strong-code). */
+export function nextLadderCapability(routing, capability) {
+  for (const steps of Object.values(routing.escalation?.ladders ?? {})) {
+    const i = steps.indexOf(capability);
+    if (i >= 0 && i + 1 < steps.length) return steps[i + 1];
+  }
+  return null;
+}