@ludi-uni/ludi-agent-kit 0.1.0

package/lib/orchestrator/failures.mjs

@@ -0,0 +1,88 @@
+// Separates "try another model" from "the task itself failed".
+import { classifyBackendFailure } from './health.mjs';
+
+export const FAILURE_CLASSES = [
+  'MODEL_FAILURE', 'BACKEND_LIMIT', 'TOOL_FAILURE', 'TEST_FAILURE', 'TIMEOUT',
+  'NO_PROGRESS_TIMEOUT', 'PROGRESS_TIMEOUT',
+  'POLICY_BLOCK', 'USER_DECISION_REQUIRED', 'MALFORMED_RESULT', 'EMPTY_RESPONSE', 'UNKNOWN',
+];
+
+export const REASSIGN_CLASSES = new Set(['MODEL_FAILURE', 'BACKEND_LIMIT']);
+
+/**
+ * Failure classes that indicate a model/protocol-quality problem rather than a
+ * task problem. On these, retrying the SAME model is unlikely to help — advance
+ * to the next candidate (or escalate capability) instead of a same-model retry.
+ * EMPTY_RESPONSE and turn-limit TIMEOUT are included; MALFORMED_RESULT means the
+ * model could not honour the structured-result contract.
+ */
+export const PROTOCOL_FAILURE_CLASSES = new Set(['MALFORMED_RESULT', 'EMPTY_RESPONSE', 'TIMEOUT']);
+
+/**
+ * True when a failure should move to the next model candidate, not retry the same one.
+ * A TIMEOUT is only a protocol failure when the model made no real progress
+ * (turn limit with ~0 tool calls = the model spun without doing work). A timeout
+ * that followed genuine tool progress stays retryable on the same model.
+ */
+export function isProtocolFailure(failureClass, run = null) {
+  // A no-progress timeout is a model-quality problem -> advance candidate.
+  if (failureClass === 'NO_PROGRESS_TIMEOUT') return true;
+  // A progress timeout means the model WAS working — it is not a protocol-quality
+  // failure; it is recoverable (more turns / a bigger budget may finish it).
+  if (failureClass === 'PROGRESS_TIMEOUT') return false;
+  if (failureClass === 'TIMEOUT') {
+    const toolCalls = run?.child?.toolCalls ?? run?.toolCalls;
+    // No progress signal -> treat as protocol failure. Progress -> recoverable.
+    if (toolCalls !== undefined && toolCalls !== null) return toolCalls === 0 && !run?.structured && !run?.result?.summary;
+    return false; // unknown progress is not evidence of a protocol failure
+  }
+  return PROTOCOL_FAILURE_CLASSES.has(failureClass);
+}
+
+/**
+ * Should this failure mark the model as failed for the WHOLE task (across
+ * capabilities)? Task-global failures are model/protocol-quality problems that
+ * will almost certainly recur if the same canonical model is invoked again under
+ * a different capability — so the model is skipped task-wide, not just locally.
+ *
+ * Global:   MALFORMED_RESULT, EMPTY_RESPONSE, no-progress turn-limit TIMEOUT.
+ * Not global: transient tool failure, recoverable command error, task-specific
+ *             implementation/validation failure (feedback can fix those).
+ *
+ * @param {string} failureClass classified failure
+ * @param {object} [telemetry] optional { toolCalls, turns, hasOutput } for the
+ *   specific invocation — used only to judge TIMEOUT progress; never guessed.
+ */
+export function shouldMarkTaskGlobalFailure(failureClass, telemetry = null) {
+  if (failureClass === 'MALFORMED_RESULT' || failureClass === 'EMPTY_RESPONSE' || failureClass === 'MODEL_FAILURE') return true;
+  if (failureClass === 'NO_PROGRESS_TIMEOUT') return telemetry?.toolCalls === 0 && telemetry?.structuredProgress === false && telemetry?.hasFinalOutput === false;
+  // A PROGRESS_TIMEOUT means the model was making real progress — it is NOT a
+  // model-quality failure and must NOT be added to taskGlobalFailedModels.
+  if (failureClass === 'PROGRESS_TIMEOUT') return false;
+  if (failureClass === 'TIMEOUT') {
+    // A generic timeout is not sufficient: require turn-limit provenance and
+    // explicit evidence of zero tool calls, no structured progress and no final output.
+    return telemetry?.turnLimit === true && telemetry?.toolCalls === 0 &&
+      telemetry?.structuredProgress === false && telemetry?.hasFinalOutput === false;
+  }
+  return false;
+}
+
+export function classifyRun(run) {
+  if (run?.failureClass && FAILURE_CLASSES.includes(run.failureClass)) return run.failureClass;
+  const result = run?.result;
+  const text = `${run?.error ?? ''} ${result?.summary ?? ''}`;
+  if (classifyBackendFailure(text)) return 'BACKEND_LIMIT';
+  if (/timed out|timeout|ETIMEDOUT|tool call limit|turn limit/i.test(text)) return 'TIMEOUT';
+  if (/POLICY_BLOCK|policy block/i.test(text)) return 'POLICY_BLOCK';
+  if (result?.status === 'blocked' || result?.status === 'needs_decision') return 'USER_DECISION_REQUIRED';
+  if (!run?.structured && result?.status === 'unknown') return 'MALFORMED_RESULT';
+  if (/no bound model|capability/i.test(text)) return 'MODEL_FAILURE';
+  const verification = JSON.stringify(result?.verification ?? '');
+  if (/test fail|tests failed|assertionerror|npm ERR/i.test(`${text} ${verification}`)) return 'TEST_FAILURE';
+  if (/empty model response|empty response|no output|blank response/i.test(text)) return 'EMPTY_RESPONSE';
+  if (/tool error|command failed|ludi_exec/i.test(text)) return 'TOOL_FAILURE';
+  if (result?.status === 'failed') return 'TEST_FAILURE';
+  if (run?.error) return 'MODEL_FAILURE';
+  return 'UNKNOWN';
+}

package/lib/orchestrator/health.mjs

@@ -0,0 +1,53 @@
+// Backend health for one run, and a short-lived cross-run mark when usage is exhausted.
+// There is no permanent blacklist: every record has expiresAt. Unknown durations use the policy TTL.
+import { DEFAULT_POLICY } from './policy.mjs';
+
+export function classifyBackendFailure(reason) {
+  const t = String(reason ?? '').toLowerCase();
+  if (t.includes('usage limit has been reached') || t.includes('usage limit') || t.includes('insufficient_quota')) return 'usage_exhausted';
+  if (t.includes('rate limit') || t.includes('too many requests')) return 'rate_limited';
+  if (t.includes('temporarily unavailable') || t.includes('service unavailable') || t.includes('overloaded')) return 'temporarily_unavailable';
+  return null;
+}
+
+export function healthTtlMs(policy, state) {
+  const h = policy?.backend_health ?? DEFAULT_POLICY.backend_health;
+  if (state === 'usage_exhausted') return h.usage_exhausted_ttl_hours * 3600 * 1000;
+  if (state === 'rate_limited') return h.rate_limited_ttl_minutes * 60 * 1000;
+  return h.unavailable_ttl_minutes * 60 * 1000;
+}
+
+/**
+ * skip/report hooks for withEscalation. bindRun(id) before the first model call.
+ * Without a session, health lives in this object for the current process only.
+ */
+export function createHealthMonitor({ session = null, policy, now = () => new Date().toISOString() } = {}) {
+  let runId = null;
+  const local = [];
+  return {
+    bindRun(id) { runId = id; },
+    skip(candidate) {
+      if (!runId) return null;
+      const at = now();
+      if (session) {
+        const row = session.activeHealth({ provider: candidate.provider, model: candidate.model, runId, now: at });
+        return row ? `${row.state} until ${row.expiresAt}` : null;
+      }
+      const row = local.find(r => r.provider === candidate.provider && r.model === candidate.model && r.expiresAt > at && (r.runId === runId || r.runId === ''));
+      return row ? `${row.state} until ${row.expiresAt}` : null;
+    },
+    report(candidate, reason) {
+      const state = classifyBackendFailure(reason);
+      if (!state || !runId) return null;
+      const ttlMs = healthTtlMs(policy, state);
+      const at = now();
+      if (session) return session.recordHealth({ provider: candidate.provider, model: candidate.model, state, reason, runId, ttlMs, now: at });
+      const expiresAt = new Date(Date.parse(at) + ttlMs).toISOString();
+      const rowRun = state === 'usage_exhausted' ? '' : runId;
+      const row = { provider: candidate.provider, model: candidate.model, state, reason: String(reason).slice(0, 500), detectedAt: at, retryAfter: expiresAt, expiresAt, runId: rowRun };
+      const i = local.findIndex(r => r.provider === row.provider && r.model === row.model && r.runId === rowRun);
+      if (i >= 0) local[i] = row; else local.push(row);
+      return row;
+    },
+  };
+}

package/lib/orchestrator/orchestrator.mjs

@@ -0,0 +1,483 @@
+// Orchestration loop: plan -> route -> delegate (bounded concurrency) -> evaluate -> retry / reassign /
+// decide / add work -> integrated report. With a store session the same loop is resumable: task state,
+// counters, decisions and trace are written before and after each unit of work.
+import { planRules, planWithModel, validatePlan } from './planner.mjs';
+import { createTaskStore, createNullProjectStore, newTask, runnableTasks, strandedTasks } from './task-store.mjs';
+import { resolveTaskModels, nextLadderCapability, agentForCapability } from './router.mjs';
+import { evaluateResult } from './evaluator.mjs';
+import { evaluateDecision, decisionKey } from './escalation.mjs';
+import { classifyRun, REASSIGN_CLASSES, isProtocolFailure, shouldMarkTaskGlobalFailure } from './failures.mjs';
+import { declaredMode, accessOf, piToolsForAccess, workspaceOf } from './permissions.mjs';
+
+const STOP = new Set(['failed', 'blocked', 'waiting_for_user']);
+
+async function makePlan(request, { planner, plan, agents, routing, registry, policy, invoke, cwd, trace, health }) {
+  if (plan) return { planner: 'explicit', tasks: plan };
+  if (planner === 'model') return planWithModel(request, { agents, routing, registry, policy, invoke, cwd, trace, health });
+  return planRules(request, { agents, policy });
+}
+
+/** Plan and route only; no agent runs (model planner still calls the orchestrator model once). */
+export async function dryRun(request, { planner = 'rules', plan = null, agents, routing, registry, policy, invoke = null, cwd }) {
+  const p = await makePlan(request, { planner, plan, agents, routing, registry, policy, invoke, cwd, trace: [] });
+  const { errors, tasks } = validatePlan(p.tasks, { agents, routing, policy });
+  return {
+    mode: 'dry-run', request, planner: p.planner, fallbackReason: p.fallbackReason, errors,
+    limits: policy.limits, maxParallelTasks: policy.decision_policy.max_parallel_tasks,
+    tasks: tasks.map(t => {
+      const m = resolveTaskModels(t, { routing, registry });
+      const agent = agents.find(a => a.meta.name === t.assignedAgent);
+      const access = accessOf(agent);
+      return {
+        ...t, executionMode: declaredMode(agent, t), tools: piToolsForAccess(access), access, workspace: workspaceOf(t, cwd),
+        models: { chain: m.chain, candidates: m.candidates.map(c => c.modelId), unbound: m.unbound, placeholder: m.placeholder },
+      };
+    }),
+  };
+}
+
+export function formatPlan(dry) {
+  const index = Object.fromEntries(dry.tasks.map((t, i) => [t.id, `Task ${i + 1}`]));
+  const lines = [`Plan: ${dry.tasks.length} tasks (planner: ${dry.planner}${dry.fallbackReason ? `, fallback: ${dry.fallbackReason}` : ''})`, ''];
+  dry.tasks.forEach((t, i) => {
+    lines.push(`Task ${i + 1} [${t.id}] ${t.title}`, `  capability: ${t.capability}`, `  agent: ${t.assignedAgent}`, `  mode: ${t.executionMode}`);
+    lines.push(`  workspace: ${t.workspace?.path ?? '(cwd)'}`);
+    lines.push(`  tools: ${(t.tools ?? []).join(', ') || '(none)'}`);
+    lines.push(`  model: ${t.models.candidates.length ? t.models.candidates.join(' -> ') : `(unbound: ${[...t.models.placeholder, ...t.models.unbound].join(', ')})`}`);
+    if (t.acceptance?.length) lines.push(`  acceptance: ${t.acceptance.join('; ')}`);
+    if (t.dependencies.length) lines.push(`  depends_on: ${t.dependencies.map(d => index[d] ?? d).join(', ')}`);
+    lines.push('');
+  });
+  if (dry.errors.length) lines.push('Errors:', ...dry.errors.map(e => `- ${e}`));
+  return lines.join('\n').trimEnd();
+}
+
+function runStatusOf(status, escalations, tasks) {
+  if (escalations.length || tasks.some(t => t.status === 'waiting_for_user')) return 'waiting_for_user';
+  if (status === 'completed') return 'completed';
+  return 'failed';
+}
+
+/** Dependents parked because a dependency was waiting become pending once that dependency can run again. */
+function releaseRecoverable(store) {
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const t of store.list()) {
+      if (t.status !== 'blocked' || !String(t.blockedReason ?? '').startsWith('dependency ')) continue;
+      const stopping = t.dependencies.some(id => STOP.has(store.get(id)?.status));
+      if (!stopping) { store.update(t.id, { status: 'pending', blockedReason: undefined }); changed = true; }
+    }
+  }
+}
+
+export async function orchestrate(options) {
+  const { session, resumeRunId } = options;
+  let ownedRun = resumeRunId ?? null;
+  let token = session && resumeRunId ? session.claimRun(resumeRunId) : null;
+  try {
+    return await orchestrateImpl({ ...options, onRunCreated(id) {
+      ownedRun = id;
+      token = session.claimRun(id);
+    } });
+  } finally {
+    if (token && ownedRun) {
+      try { session.releaseRun(ownedRun, token); } catch { /* preserve the original run result/error; dead owners are reclaimed */ }
+    }
+  }
+}
+
+async function orchestrateImpl({ request: requestArg, planner = 'rules', plan = null, agents, routing, registry, policy, runner, invoke = null, repoRoot = null, projectStore = createNullProjectStore(), now = () => new Date().toISOString(), session = null, resumeRunId = null, answers = [], health = null, activity = null, onRunCreated = () => {} }) {
+  let request = requestArg;
+  let activePolicy = policy;
+  let dp = activePolicy.decision_policy, limits = activePolicy.limits;
+  let runId = null, p = { planner }, round = 0, reworkCycles = 0, seq = 0;
+  const trace = [], autoDecisions = [], escalations = [], unresolved = [], decisionLog = [];
+  const limitsHit = new Set();
+  let store = null, planning = true, recovered = [];
+  const scopeKeyOf = () => repoRoot ?? (runId ? session?.getRun(runId)?.scopeKey : null) ?? 'default';
+  // Live-activity bridge: the tracker decides whether an event type is significant
+  // (persist to the run trace) or high-frequency (live snapshot only, e.g. turns).
+  const event = (type, data = {}) => {
+    const entry = { at: now(), round, type, ...data };
+    const persist = activity?.emit?.(type, { runId, ...data })?.persist ?? true;
+    if (!persist) return entry;
+    trace.push(entry);
+    if (session && runId) session.appendTrace(runId, entry);
+    return entry;
+  };
+  const syncActivity = (state = null) => { if (activity && runId) activity.syncTasks({ runId, tasks: store ? store.list() : [], state }); };
+  const persistMeta = (status = 'running') => {
+    if (!session || !runId) return;
+    session.updateRun(runId, {
+      status, round, reworkCycles, seq, planner: p.planner,
+      counters: { autoDecisions, unresolved, limitsHit: [...limitsHit], decisionLog },
+    });
+  };
+  const decide = d => { autoDecisions.push(d); event('auto-decision', d); persistMeta(); };
+  const hitLimit = (limit, detail) => { limitsHit.add(limit); event('limit', { limit, detail }); persistMeta(); };
+
+  if (resumeRunId) {
+    if (!session) throw new Error('orchestrate: resume requires a persistent store');
+    const run = session.getRun(resumeRunId);
+    if (!run) throw new Error(`orchestrate: run not found: ${resumeRunId}`);
+    if (run.status === 'cancelled') throw new Error(`orchestrate: run ${resumeRunId} is cancelled`);
+    runId = run.id;
+    request = run.request;
+    activePolicy = run.policySnapshot?.limits ? run.policySnapshot : policy;
+    dp = activePolicy.decision_policy; limits = activePolicy.limits;
+    p = { planner: run.planner ?? planner };
+    round = run.round; reworkCycles = run.reworkCycles; seq = run.seq;
+    for (const l of run.counters.limitsHit ?? []) limitsHit.add(l);
+    autoDecisions.push(...(run.counters.autoDecisions ?? []));
+    unresolved.push(...(run.counters.unresolved ?? []));
+    decisionLog.push(...(run.counters.decisionLog ?? []));
+    trace.push(...session.loadTrace(runId));
+    health?.bindRun?.(runId);
+    activity?.bindRun?.({ runId, repoRoot: run.repoRoot ?? repoRoot });
+    recovered = session.recoverStale(runId);
+    for (const a of answers) {
+      const res = session.answerDecision({ runId, decisionId: a.decisionId, answer: a.answer, scopeKey: scopeKeyOf() });
+      if (res.idempotent && !res.same) unresolved.push(`decision ${a.decisionId} already answered; kept the first answer`);
+    }
+    store = session.openTaskStore(runId);
+    releaseRecoverable(store);
+    planning = store.size() === 0;
+    for (const d of session.listDecisions(runId, 'pending')) escalations.push(toEscalation(d));
+    event('resume', { runId, recovered, planning, answers: answers.map(a => a.decisionId) });
+  }
+
+  try {
+  if (planning) {
+    if (session && !runId) {
+      runId = session.createRun({ request, policy, repoRoot, planner, scopeKey: repoRoot ?? 'default' });
+      onRunCreated(runId);
+      // Bind the owning client immediately so its public snapshot exists from the start.
+      activity?.bindRun?.({ runId, repoRoot });
+    }
+    health?.bindRun?.(runId);
+    store = store ?? (session ? session.openTaskStore(runId) : createTaskStore());
+    p = await makePlan(request, { planner, plan, agents, routing, registry, policy: activePolicy, invoke, cwd: repoRoot ?? process.cwd(), trace, health });
+    if (p.fallbackReason) decide({ subject: 'planner', choice: 'rules planner', reason: `model plan unusable (${p.fallbackReason}); reversible`, step: 'reversible' });
+    const v = validatePlan(p.tasks, { agents, routing, policy: activePolicy });
+    event('plan', { planner: p.planner, tasks: v.tasks.map(t => ({ id: t.id, agent: t.assignedAgent, capability: t.capability, dependencies: t.dependencies })), errors: v.errors });
+    if (v.errors.length) return finish('plan-invalid', v.errors);
+    for (const t of v.tasks) {
+      store.add(newTask(t));
+      seq = Math.max(seq, Number(/^t(\d+)$/.exec(t.id)?.[1] ?? 0));
+      const m = resolveTaskModels(t, { routing, registry });
+      event('routing', { taskId: t.id, capability: t.capability, agent: t.assignedAgent, candidates: m.candidates.map(c => c.modelId) });
+    }
+    persistMeta('running');
+    syncActivity('running');
+    await projectStore.onPlan(store.snapshot());
+  } else {
+    syncActivity('running');
+    await projectStore.onPlan(store.snapshot());
+  }
+
+  function addTask(spec, sourceId) {
+    if (store.size() >= limits.max_tasks) { hitLimit('max_tasks', spec.title); unresolved.push(`not added (max_tasks=${limits.max_tasks}): ${spec.title}`); return null; }
+    let id; do id = `t${++seq}`; while (store.has(id));
+    const { errors, tasks } = validatePlan([{ ...spec, id, dependencies: spec.dependencies ?? (sourceId ? [sourceId] : []) }], { agents, routing, policy: activePolicy, existingIds: store.list().map(t => t.id) });
+    if (errors.length) { unresolved.push(`discovered task rejected: ${errors.join('; ')}`); event('task-rejected', { spec, errors }); return null; }
+    store.add(newTask({ ...tasks[0], origin: sourceId ?? 'orchestrator' }));
+    persistMeta();
+    event('task-added', { taskId: id, source: sourceId, agent: tasks[0].assignedAgent });
+    return id;
+  }
+
+  function retryOrFail(t, run, reasons) {
+    const failureClass = classifyRun({ ...run, failureClass: run?.failureClass });
+    // Models actually invoked this attempt (NOT health-skipped / already-tried /
+    // unavailable candidates). invocationsStarted is the attempt-budget unit.
+    const invoked = run?.invokedModels ?? (run?.modelId ? [run.modelId] : []);
+    const counters = run?.counters ?? { candidatesConsidered: invoked.length, candidatesSkipped: 0, invocationsStarted: invoked.length };
+    const record = { attempt: t.attempts, failureClass, reasons, summary: run?.result?.summary ?? run?.error ?? '', modelId: run?.modelId ?? invoked.at(-1), counters, filesChanged: run?.worktree?.agentChanges?.map(c => c.path) ?? run?.result?.filesChanged ?? [], commandsRun: run?.result?.commandsRun ?? [], verification: run?.result?.verification ?? [] };
+    const attemptsLog = [...(t.attemptsLog ?? []), record];
+    // Accumulate the modelIds this task should NOT retry. On a protocol failure OR a
+    // backend/model failure (REASSIGN_CLASSES: the model/backend itself is dead) every
+    // invoked model is excluded so the retry advances to an untried candidate. Only on
+    // a recoverable failure (test/tool) does the LAST invoked model stay retryable so a
+    // same-model feedback retry is still possible.
+    const protocol = isProtocolFailure(failureClass, run);
+    const reassign = REASSIGN_CLASSES.has(failureClass);
+    const toExclude = protocol || reassign ? invoked : invoked.slice(0, -1);
+    const attemptedModels = [...new Set([...(t.capabilityLocalTriedModels ?? t.attemptedModels ?? []), ...toExclude].filter(Boolean))];
+    // TASK-GLOBAL failed models: a model that hit a protocol-quality failure
+    // (malformed / empty / no-progress turn-limit) is skipped for the WHOLE task,
+    // even after a capability escalation re-resolves the candidate list. The main
+    // loop already accumulated per-invocation protocol failures onto the task; if
+    // this attempt's overall failure is itself a global failure, add its models too.
+    const taskGlobalFailedModels = [...new Set([...(run?.taskGlobalFailedModels ?? t.taskGlobalFailedModels ?? [])].filter(Boolean))];
+    // Attempt budget counts ACTUAL invocations only — never health skips,
+    // unavailable candidates, already-tried skips, or enumeration. The counter was
+    // already incremented in the main loop for this result; reuse the fresh value.
+    const totalModelAttempts = run?.totalModelAttempts ?? (t.totalModelAttempts ?? 0) + counters.invocationsStarted;
+    const budgetLeft = limits.max_total_attempts_per_task == null || totalModelAttempts < limits.max_total_attempts_per_task;
+    // How many candidates remain untried at the CURRENT capability (excluding both
+    // capability-local tried AND task-global-failed models).
+    const untriedAtCapability = () => {
+      try { return resolveTaskModels(t, { routing, registry }).candidates.filter(c => !attemptedModels.includes(c.modelId) && !taskGlobalFailedModels.includes(c.modelId)).length; }
+      catch { return 0; }
+    };
+    // Escalate capability when (a) a hard backend/model failure, or (b) a protocol
+    // failure with no untried candidate left at this capability. The next attempt
+    // re-resolves the NEW capability's candidate list from live routing.
+    const escalateNow = dp.reassign_on_failure && (reassign || (protocol && untriedAtCapability() === 0));
+    const next = escalateNow ? nextLadderCapability(routing, t.capability) : null;
+    // Nothing left to invoke at this capability and no ladder step: fail now instead
+    // of spending rounds on attempts that would invoke nothing.
+    const nothingLeft = !next && (protocol || reassign) && invoked.length > 0 && untriedAtCapability() === 0;
+    if (nothingLeft) {
+      store.update(t.id, { status: 'failed', blockedReason: `no untried model candidate left on ${t.capability}: ${reasons.join('; ')}`, attemptsLog, failureClass, attemptedModels, taskGlobalFailedModels, totalModelAttempts });
+      event('task-failed', { taskId: t.id, reasons, failureClass, totalModelAttempts, exhaustedCandidates: true });
+      return;
+    }
+    if ((t.attempts > limits.max_retries || !budgetLeft) && !next) {
+      const why = !budgetLeft ? `model attempt budget exhausted (${totalModelAttempts}/${limits.max_total_attempts_per_task})` : reasons.join('; ');
+      store.update(t.id, { status: 'failed', blockedReason: why, attemptsLog, failureClass, attemptedModels, taskGlobalFailedModels, totalModelAttempts });
+      event('task-failed', { taskId: t.id, reasons, failureClass, totalModelAttempts });
+      return;
+    }
+    const patch = { status: 'pending', feedback: reasons, attemptsLog, failureClass, totalModelAttempts, taskGlobalFailedModels };
+    const was = t.capability;
+    if (next) {
+      // Capability escalation -> re-resolve the new capability's candidates and
+      // reset the CAPABILITY-LOCAL tried list. taskGlobalFailedModels is NOT reset:
+      // a model that protocol-failed stays skipped across capabilities.
+      patch.capability = next;
+      patch.attemptedModels = [];
+      patch.capabilityLocalTriedModels = [];
+    } else {
+      patch.attemptedModels = attemptedModels;
+      patch.capabilityLocalTriedModels = attemptedModels;
+    }
+    store.update(t.id, patch);
+    event('retry', { taskId: t.id, attempt: t.attempts, failureClass, from: was, to: next ?? was, modelId: record.modelId, protocol, invoked, counters, taskGlobalFailedModels, reasons });
+    if (next) event('fallback', { taskId: t.id, from: was, to: next });
+    // Report the concrete model progression: which model failed (capability +
+    // modelId + failureClass) and what action follows. This makes strong-code
+    // escalations visible in the user-facing report, not just the internal trace.
+    const failedModel = record.modelId ? `${record.modelId} on ${was}` : was;
+    const action = next ? `escalate to ${next}` : protocol || reassign ? `next untried candidate on ${was}` : `retry ${was} with feedback`;
+    const choice = `${failedModel} → ${failureClass} → ${action}`;
+    decide({ taskId: t.id, subject: `${t.id} failed attempt ${t.attempts}`, capability: was, modelId: record.modelId, failureClass, action, choice, reason: `${failureClass}: ${reasons[0]}; attempt ${t.attempts}`, step: 'policy' });
+  }
+
+  function gate(t, requests) {
+    const made = [], waitFor = [], drafts = [];
+    let escalate = false;
+    for (const d of requests) {
+      const memory = session ? session.lookupMemory({ key: decisionKey(d), scopeKey: scopeKeyOf() }) : [];
+      const g = evaluateDecision(d, { policy: activePolicy, decisionLog, memory });
+      const log = { ...g, taskId: t.id };
+      if (g.step === 'memory') event('memory-lookup', { taskId: t.id, key: g.key, optionId: g.optionId, memoryId: g.memoryId, scope: g.scope });
+      if (g.action === 'experiment') {
+        const agent = g.experiment.agent ?? agentForCapability(agents, 'strong-code')?.meta.name ?? t.assignedAgent;
+        const id = addTask({ title: `Experiment: ${d.question}`, goal: g.experiment.goal, agent, kind: 'experiment', dependencies: [],
+          acceptance: ['each option was tried or assessed with concrete evidence', 'one option is recommended with rationale'] }, null);
+        if (id) { waitFor.push(id); decisionLog.push(log); decide({ taskId: t.id, subject: d.question, choice: `run experiment ${id}`, reason: g.reason, step: g.step }); continue; }
+        log.action = 'escalate'; log.reason = 'experiment needed but no task budget left';
+      }
+      decisionLog.push(log);
+      if (log.action === 'decide') {
+        const o = d.options.find(x => x.id === g.optionId);
+        const choice = o.summary ? `${o.id}: ${o.summary}` : o.id;
+        made.push({ question: d.question, choice, reason: `${g.step}: ${g.reason}` });
+        decide({ taskId: t.id, subject: d.question, choice, reason: g.reason, step: g.step });
+      } else {
+        escalate = true;
+        drafts.push({
+          taskId: t.id, question: d.question, options: d.options ?? [], reason: log.reason,
+          escalationType: (g.flags ?? [])[0] ?? g.step, flags: g.flags ?? [], key: g.key, recommended: d.recommended,
+        });
+      }
+    }
+    const decisions = [...t.decisions, ...made];
+    if (escalate) {
+      const patch = { status: session ? 'waiting_for_user' : 'blocked', decisions, dependencies: [...t.dependencies, ...waitFor], blockedReason: 'waiting for user decision' };
+      let ids = [];
+      if (session) ids = session.persistWaiting(runId, { ...store.get(t.id), ...patch, updatedAt: now() }, drafts);
+      store.update(t.id, patch);
+      drafts.forEach((draft, i) => {
+        const e = { id: ids[i], taskId: t.id, question: draft.question, reason: draft.reason, flags: draft.flags, options: draft.options.map(o => ({ id: o.id, summary: o.summary })), recommended: draft.recommended };
+        escalations.push(e); event('escalation', e);
+      });
+      return store.get(t.id);
+    }
+    if (t.attempts > limits.max_retries) return store.update(t.id, { status: 'failed', decisions, blockedReason: 'retry limit reached while resolving decisions' });
+    store.update(t.id, { status: 'pending', decisions, dependencies: [...t.dependencies, ...waitFor] });
+  }
+
+  function rework(t, issues) {
+    const list = issues.map(i => i.summary).join('; ');
+    if (reworkCycles >= limits.max_rework_cycles) { unresolved.push(`${t.id} review: blocking issues remain after ${reworkCycles} rework cycle(s): ${list}`); persistMeta(); return; }
+    reworkCycles++;
+    const impl = store.list().filter(x => x.kind === 'implement').at(-1);
+    const fix = addTask({ title: `Rework after review ${t.id}`, goal: `Address these review findings: ${list}${impl ? `\nOriginal goal: ${impl.goal}` : ''}`, agent: impl?.assignedAgent ?? agentForCapability(agents, 'strong-code')?.meta.name, kind: 'implement',
+      acceptance: ['every listed finding is fixed or explicitly rebutted with evidence', 'the relevant tests were run and pass, or the failure is reported'] }, t.id);
+    if (!fix) return;
+    addTask({ title: `Re-review after ${fix}`, goal: t.goal, agent: t.assignedAgent, kind: 'review', acceptance: t.acceptance, dependencies: [fix] }, null);
+    decide({ taskId: t.id, subject: `review ${t.id} found blocking issues`, choice: `send back to ${store.get(fix).assignedAgent} (${fix}) and re-review`, reason: `rework cycle ${reworkCycles}/${limits.max_rework_cycles}`, step: 'policy' });
+  }
+
+  const depResults = t => t.dependencies.map(id => store.get(id)).map(d => ({ id: d.id, agent: d.assignedAgent, title: d.title, ...(d.result ?? {}) }));
+  // Paths changed by ANY agent of this run so far (retry / rework must not treat them
+  // as pre-existing dirty changes) and every answered decision in the run (a rework
+  // task inherits the dirty-gate answer given for the original implementation).
+  const ownedPaths = () => [...new Set(store.list().flatMap(x => x.ownedPaths ?? []))];
+  const runDecisions = () => store.list().flatMap(x => x.decisions ?? []);
+
+  while (true) {
+    const ready = runnableTasks(store);
+    if (!ready.length) break;
+    if (round >= limits.max_rounds) { hitLimit('max_rounds', `${ready.length} runnable task(s) left`); break; }
+    round++;
+    const batch = ready.slice(0, dp.max_parallel_tasks);
+    for (const t of batch) store.update(t.id, { status: 'running', attempts: t.attempts + 1 });
+    persistMeta('running');
+    syncActivity('running');
+    event('round', { running: batch.map(t => t.id), deferred: ready.slice(batch.length).map(t => t.id) });
+    const owned = ownedPaths(), decided = runDecisions();
+    const runs = await Promise.all(batch.map(t => Promise.resolve().then(() => runner.run(t, { dependencyResults: depResults(t), runId, ownedPaths: owned, runDecisions: decided, onEvent: (type, data) => event(type, { runId, ...data }) })).catch(e => ({ ok: false, error: e.message }))));
+    for (const [i, t] of batch.entries()) {
+      const run = runs[i];
+      const ev = evaluateResult(t, run, { repoRoot });
+      if (run.child) event('child', run.child);
+      event('result', { taskId: t.id, agent: t.assignedAgent, capability: t.capability, attempt: t.attempts, executor: run.executor, modelId: run.modelId, verdict: ev.verdict, reasons: ev.reasons, failureClass: classifyRun(run), steps: run.steps, counters: run.counters, invokedModels: run.invokedModels, raw: run.raw });
+      // Accumulate real invocations on EVERY result (success or failure) so the
+      // budget reflects actual model calls, not just failed attempts.
+      const invokedThisRound = run?.counters?.invocationsStarted ?? (run?.invokedModels?.length ?? (run?.modelId ? 1 : 0));
+      const totalModelAttempts = (t.totalModelAttempts ?? 0) + invokedThisRound;
+      run.totalModelAttempts = totalModelAttempts; // hand the fresh count to retryOrFail
+      // Mark task-global failed models from EVERY invocation that hit a protocol
+      // failure — even when the task ultimately recovers on a later candidate.
+      // This is what stops a malformed/empty/no-progress-timeout model from being
+      // re-invoked after a capability escalation.
+      const globalFailedNow = (run?.steps ?? []).filter(s => s.protocolFailure && shouldMarkTaskGlobalFailure(s.protocolFailure, {
+        toolCalls: s.child?.toolCalls ?? s.telemetry?.toolCalls,
+        turnLimit: ['no-progress-turn-limit', 'absolute-turn-limit'].includes(s.child?.stopReason) || /turn limit/i.test(s.reason ?? ''),
+        structuredProgress: s.child?.structuredProgress ?? (s.protocolFailure === 'NO_PROGRESS_TIMEOUT' ? false : undefined),
+        hasFinalOutput: s.child?.hasFinalOutput ?? (s.protocolFailure === 'NO_PROGRESS_TIMEOUT' ? false : undefined),
+      })).map(s => s.modelId).filter(Boolean);
+      const taskGlobalFailedModels = [...new Set([...(t.taskGlobalFailedModels ?? []), ...globalFailedNow])];
+      run.taskGlobalFailedModels = taskGlobalFailedModels;
+      for (const step of run.steps ?? []) {
+        if (step.skipped && step.reason === 'task-global-failed') {
+          decide({ taskId: t.id, subject: `${t.id} candidate skip`, capability: step.capability, modelId: step.modelId, failureClass: 'task-global-failed', action: 'skip', choice: `${step.modelId} on ${step.capability} → task-global-failed skip`, reason: 'protocol failure on an earlier capability', step: 'policy' });
+        } else if (!step.ok && !step.skipped && step.modelId && step.failureClass && step.capability === 'strong-code') {
+          decide({ taskId: t.id, subject: `${t.id} candidate failed`, capability: step.capability, modelId: step.modelId, failureClass: step.failureClass, action: 'next candidate', choice: `${step.modelId} on ${step.capability} → ${step.failureClass} → next candidate`, reason: step.reason, step: 'policy' });
+        }
+      }
+      const changedNow = (run?.worktree?.agentChanges ?? []).map(c => c.path);
+      const ownedNow = [...new Set([...(t.ownedPaths ?? []), ...changedNow])];
+      store.update(t.id, { result: run.result ?? { status: 'failed', summary: run.error }, modelId: run.modelId, totalModelAttempts, taskGlobalFailedModels, ownedPaths: ownedNow });
+      if (run.gate) event('gate', { taskId: t.id, gateType: run.gate.type, action: run.gate.action, key: run.gate.key, paths: run.gate.paths });
+      if (run.abort) {
+        // Runner-level terminal stop (e.g. user answered "abort" to the dirty-worktree
+        // gate): the task is blocked for good; never retried, never re-asked.
+        store.update(t.id, { status: 'blocked', blockedReason: run.error ?? 'aborted by user decision' });
+        event('task-blocked', { taskId: t.id, reason: run.error, gate: run.gate });
+        await projectStore.onTaskUpdate(structuredClone(store.get(t.id)));
+        continue;
+      }
+      if (ev.verdict === 'success') {
+        if (t.attempts > 1 && run.modelId && t.capability === 'strong-code') {
+          decide({ taskId: t.id, subject: `${t.id} escalated invocation`, capability: t.capability, modelId: run.modelId, failureClass: null, action: 'completed', choice: `${run.modelId} on ${t.capability} → completed`, reason: 'escalation recovered the task', step: 'policy' });
+        }
+        store.update(t.id, { status: 'completed', feedback: [] });
+        for (const spec of ev.newTasks) addTask(spec, t.id);
+        if (ev.blockingIssues.length) rework(t, ev.blockingIssues);
+      } else if (ev.verdict === 'blocked') {
+        gate(t, ev.decisions);
+      } else {
+        retryOrFail(t, run, ev.reasons);
+      }
+      await projectStore.onTaskUpdate(structuredClone(store.get(t.id)));
+      syncActivity();
+    }
+  }
+
+  for (let stranded = strandedTasks(store); stranded.length; stranded = strandedTasks(store)) {
+    for (const t of stranded) {
+      const dep = t.dependencies.map(d => store.get(d)).find(d => d && STOP.has(d.status));
+      store.update(t.id, { status: 'blocked', blockedReason: `dependency ${dep.id} is ${dep.status}` });
+    }
+  }
+  } catch (e) {
+    // Exception-safe termination: never leave the run (or its in-flight tasks) as
+    // `running` in the store. If the store itself is unwritable we report that
+    // limitation instead of masking the original error.
+    const persisted = terminateOnError(e);
+    const err = new Error(`orchestrate: ${e.message}${persisted.ok ? '' : ` (run state could not be persisted: ${persisted.error})`}`);
+    err.cause = e; err.runId = runId; err.persisted = persisted.ok;
+    throw err;
+  }
+  const open = store.list().filter(t => t.status !== 'completed');
+  const status = escalations.length ? 'needs-user' : open.length || unresolved.length ? 'incomplete' : 'completed';
+  return finish(status, []);
+
+  function terminateOnError(e) {
+    if (!session || !runId) return { ok: true, skipped: true };
+    try {
+      session.transaction(() => {
+        for (const t of session.loadTasks(runId)) {
+          if (t.status !== 'running') continue;
+          session.saveTask(runId, { ...t, status: 'failed', blockedReason: `run aborted by error: ${String(e.message).slice(0, 300)}` });
+        }
+        session.appendTrace(runId, { at: now(), round, type: 'error', message: String(e.message).slice(0, 2000), stack: String(e.stack ?? '').slice(0, 4000) });
+        session.updateRun(runId, { status: 'failed', round, reworkCycles, seq, planner: p.planner, counters: { autoDecisions, unresolved: [...unresolved, `run aborted: ${e.message}`], limitsHit: [...limitsHit], decisionLog } });
+      });
+      syncActivity('failed');
+      activity?.finishRun?.(runId);
+      return { ok: true };
+    } catch (e2) {
+      return { ok: false, error: e2.message };
+    }
+  }
+
+  async function finish(status, errors) {
+    const tasks = store ? store.snapshot() : [];
+    const runStatus = session ? runStatusOf(status, escalations, tasks) : undefined;
+    if (session && runId) persistMeta(runStatus);
+    syncActivity(runStatus ?? status);
+    if (['completed', 'failed', 'cancelled'].includes(runStatus ?? status)) activity?.finishRun?.(runId);
+    const result = { status, runStatus, runId, request, planner: p.planner, rounds: round, reworkCycles, errors, tasks, autoDecisions, escalations, unresolved, limitsHit: [...limitsHit], trace, recovered };
+    await projectStore.onFinal(result);
+    return result;
+  }
+}
+
+export function toEscalation(d) {
+  return { id: d.id, taskId: d.taskId, question: d.question, reason: d.reason, flags: d.flags ?? [], options: (d.options ?? []).map(o => ({ id: o.id, summary: o.summary })), recommended: d.recommended };
+}
+
+const first = (s, n = 160) => { const line = String(s ?? '').split(/\r?\n/).find(x => x.trim()) ?? ''; return line.length > n ? `${line.slice(0, n)}…` : line; };
+
+/** Human-facing summary. Detailed agent exchanges stay in result.trace. */
+export function formatReport(result) {
+  const done = result.tasks.filter(t => t.status === 'completed');
+  const open = result.tasks.filter(t => t.status !== 'completed');
+  const head = result.runId ? `状態: ${result.status} (run ${result.runId}, ${result.runStatus})` : `状態: ${result.status}`;
+  const lines = [`${head} (tasks ${done.length}/${result.tasks.length}, rounds ${result.rounds})`, '', '完了:'];
+  lines.push(...(done.length ? done.map(t => `- [${t.id}] ${t.title}: ${first(t.result?.summary)}`) : ['- なし']));
+  lines.push('', '自動判断:');
+  lines.push(...(result.autoDecisions.length ? result.autoDecisions.map(d => `- ${d.subject} → ${d.choice}（${d.reason}）`) : ['- なし']));
+  lines.push('', '未解決:');
+  const openLines = [
+    ...result.errors.map(e => `- ${e}`),
+    ...open.map(t => `- [${t.id}] ${t.title}: ${t.status}${t.blockedReason ? ` — ${first(t.blockedReason, 240)}` : ''}`),
+    ...result.unresolved.map(u => `- ${u}`),
+    ...result.limitsHit.map(l => `- limit reached: ${l}`),
+  ];
+  lines.push(...(openLines.length ? openLines : ['- なし']));
+  lines.push('', 'ユーザー判断が必要:');
+  lines.push(...(result.escalations.length ? result.escalations.map(e => `- [${e.taskId}]${e.id ? ` ${e.id}` : ''} ${e.question} — ${e.reason}${e.options.length ? ` (options: ${e.options.map(o => o.summary ? `${o.id}=${o.summary}` : o.id).join(' / ')})` : ''}`) : ['- なし']));
+  return lines.join('\n');
+}
+
+export function formatRunList(rows) {
+  if (!rows.length) return 'runs: none';
+  return rows.map(r => `${r.id}  ${r.status}  ${r.completed}/${r.total}  decisions:${r.pendingDecisions}  ${r.updatedAt}  ${String(r.request).replace(/\s+/g, ' ').slice(0, 72)}`).join('\n');
+}