@ludi-uni/ludi-agent-kit 0.1.0

package/tests/dirty-gate.test.mjs

@@ -0,0 +1,211 @@
+// Dirty-worktree gate state machine: user answers are honoured, agent-owned changes
+// are not "dirty", non-git workspaces are never gated, read-only work continues.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { DEFAULT_POLICY, mergePolicy } from '../lib/orchestrator/policy.mjs';
+import { createAgentRunner, evaluateDirtyGate, DIRTY_GATE_TYPE } from '../lib/orchestrator/runner.mjs';
+import { captureWorktree } from '../lib/orchestrator/worktree.mjs';
+import { orchestrate } from '../lib/orchestrator/orchestrator.mjs';
+import { openStore } from '../lib/orchestrator/store.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { agents } = loadAgents(join(kit, 'agents'), routing);
+const REG = { version: 1, backends: {
+  local: { provider: 'pl', model: 'ml', thinking: 'off' },
+  cheap: { provider: 'pc', model: 'mc', thinking: 'low' },
+  sol: { provider: 'ps', model: 'ms', thinking: 'high' },
+  astra: { provider: 'pa', model: 'ma', thinking: 'medium', vision: true },
+  codex: { provider: 'px', model: 'mx', thinking: 'high' },
+} };
+const policyWith = over => mergePolicy(DEFAULT_POLICY, over ?? {});
+const json = obj => `note\n\n\`\`\`json\n${JSON.stringify(obj)}\n\`\`\``;
+const okResult = extra => json({ status: 'completed', summary: 'done', acceptance: [{ id: 'A1', met: true, evidence: 'ran' }, { id: 'A2', met: true, evidence: 'ran' }], ...extra });
+const spec = (id, agent, dependencies = [], extra = {}) => ({ id, title: `task ${id}`, goal: `goal ${id}`, agent, dependencies, acceptance: ['done'], ...extra });
+const dbPath = () => join(mkdtempSync(join(tmpdir(), 'ludi-gate-')), 'state.db');
+
+function gitRepo({ dirty = [] } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'ludi-gate-repo-'));
+  assert.equal(spawnSync('git', ['init', '-q'], { cwd: root, encoding: 'utf8' }).status, 0, 'git init');
+  writeFileSync(join(root, 'base.txt'), 'base\n');
+  spawnSync('git', ['add', '.'], { cwd: root });
+  spawnSync('git', ['-c', 'user.email=t@example.com', '-c', 'user.name=t', 'commit', '-q', '-m', 'base'], { cwd: root });
+  for (const f of dirty) writeFileSync(join(root, f), 'user edit\n');
+  return root;
+}
+
+/** Subagent stub: writes `writes` files into cwd (simulating agent edits) then replies. */
+function subagentStub({ writes = [], reply = okResult() } = {}) {
+  const calls = [];
+  const runSubagent = async req => {
+    calls.push({ taskId: req.taskId, modelId: req.modelId });
+    for (const f of writes) writeFileSync(join(req.cwd, f), `agent ${calls.length}\n`);
+    const r = typeof reply === 'function' ? reply(req, calls.length) : reply;
+    return typeof r === 'string' ? { ok: true, text: r, child: { childSessionId: `c${calls.length}`, toolCalls: 3 } } : r;
+  };
+  return { calls, runSubagent };
+}
+
+const runOrch = ({ repoRoot, runner, plan, session = null, policy, ...o }) => orchestrate({
+  request: 'implement it', plan, agents, routing, registry: REG, policy: policyWith(policy), runner, repoRoot, session, ...o,
+});
+
+// ---------- unit: evaluateDirtyGate ----------
+test('unit: gate classifies clean / owned-only / unrelated / non-git / answered', () => {
+  const git = paths => ({ source: 'git', entries: Object.fromEntries(paths.map(p => [p, { code: ' M', hash: 'x' }])) });
+  assert.equal(evaluateDirtyGate({ before: git([]) }).gate, false);
+  assert.equal(evaluateDirtyGate({ before: git(['a.txt']), ownedPaths: ['a.txt'] }).gate, false);
+  const ask = evaluateDirtyGate({ before: git(['a.txt', 'b.txt']), ownedPaths: ['a.txt'] });
+  assert.equal(ask.action, 'ask');
+  assert.deepEqual(ask.paths, ['b.txt']);
+  assert.match(ask.key, new RegExp(`^${DIRTY_GATE_TYPE}:`));
+  assert.equal(ask.decision.decisionType, DIRTY_GATE_TYPE);
+  // Same condition, answered by id/type (not by parsing the question).
+  assert.equal(evaluateDirtyGate({ before: git(['a.txt', 'b.txt']), ownedPaths: ['a.txt'], decisions: [{ key: ask.key, optionId: 'proceed' }] }).action, 'proceed');
+  assert.equal(evaluateDirtyGate({ before: git(['a.txt', 'b.txt']), ownedPaths: ['a.txt'], decisions: [{ key: ask.key, optionId: 'abort' }] }).action, 'abort');
+  // A different dirty set is a different question.
+  assert.equal(evaluateDirtyGate({ before: git(['c.txt']), decisions: [{ key: ask.key, optionId: 'proceed' }] }).action, 'ask');
+  // Non-git inventory is never dirty.
+  assert.equal(evaluateDirtyGate({ before: { source: 'files', entries: { 'x.js': 'h', 'y.js': 'h' } } }).gate, false);
+  assert.equal(evaluateDirtyGate({ before: { available: false, entries: {} } }).gate, false);
+});
+
+// ---------- A: dirty -> decision -> proceed -> resume -> no re-ask ----------
+test('A: dirty -> decision -> proceed -> resume -> implementation runs once, no second question', async () => {
+  const repo = gitRepo({ dirty: ['user.txt'] });
+  const path = dbPath();
+  const session = openStore(path);
+  const { calls, runSubagent } = subagentStub({ writes: ['agent.txt'] });
+  const runner = createAgentRunner({ invoke: async () => ({ ok: false, error: 'no' }), runSubagent, agents, routing, registry: REG, repoRoot: repo });
+  const first = await runOrch({ repoRoot: repo, runner, plan: [spec('t1', 'coder', [], { kind: 'implement' })], session });
+  assert.equal(first.runStatus, 'waiting_for_user');
+  assert.equal(first.escalations.length, 1);
+  assert.match(first.escalations[0].question, /pre-existing uncommitted/);
+  assert.equal(calls.length, 0, 'no subagent launched before the decision');
+  assert.ok(first.trace.some(e => e.type === 'gate' && e.action === 'ask'));
+  const decisionId = first.escalations[0].id;
+  session.close();
+
+  const again = openStore(path);
+  const resumed = await runOrch({ repoRoot: repo, runner, plan: null, session: again, resumeRunId: first.runId, answers: [{ decisionId, answer: 'proceed' }] });
+  assert.equal(resumed.status, 'completed', JSON.stringify(resumed.tasks.map(t => [t.id, t.status, t.blockedReason])));
+  assert.equal(resumed.escalations.length, 0, 'no second question');
+  assert.equal(calls.length, 1, 'implementation ran exactly once');
+  assert.equal(again.listDecisions(first.runId, 'pending').length, 0);
+  const t = again.loadTasks(first.runId)[0];
+  assert.equal(t.decisions[0].optionId, 'proceed');
+  assert.ok(t.ownedPaths.includes('agent.txt'));
+  assert.ok(resumed.trace.some(e => e.type === 'gate' && e.action === 'proceed'));
+  again.close();
+});
+
+// ---------- B: dirty -> abort -> terminal, no re-ask ----------
+test('B: dirty -> abort -> task is blocked terminally and never re-asked', async () => {
+  const repo = gitRepo({ dirty: ['user.txt'] });
+  const path = dbPath();
+  const session = openStore(path);
+  const { calls, runSubagent } = subagentStub();
+  const runner = createAgentRunner({ invoke: async () => ({ ok: false, error: 'no' }), runSubagent, agents, routing, registry: REG, repoRoot: repo });
+  const first = await runOrch({ repoRoot: repo, runner, plan: [spec('t1', 'coder', [], { kind: 'implement' }), spec('t2', 'tester', ['t1'], { kind: 'verify' })], session });
+  const decisionId = first.escalations[0].id;
+  session.close();
+  const again = openStore(path);
+  const resumed = await runOrch({ repoRoot: repo, runner, plan: null, session: again, resumeRunId: first.runId, answers: [{ decisionId, answer: 'abort' }] });
+  assert.equal(resumed.escalations.length, 0);
+  assert.equal(calls.length, 0, 'nothing implemented');
+  const t1 = resumed.tasks.find(t => t.id === 't1');
+  assert.equal(t1.status, 'blocked');
+  assert.match(t1.blockedReason, /aborted by user decision/);
+  assert.equal(t1.attempts, 2, 'the abort attempt did not retry');
+  assert.equal(resumed.tasks.find(t => t.id === 't2').status, 'blocked');
+  assert.equal(resumed.runStatus, 'failed');
+  assert.ok(resumed.trace.some(e => e.type === 'task-blocked'));
+  // Resuming again does not revive the question.
+  const third = await runOrch({ repoRoot: repo, runner, plan: null, session: again, resumeRunId: first.runId });
+  assert.equal(third.escalations.length, 0);
+  assert.equal(calls.length, 0);
+  again.close();
+});
+
+// ---------- C: coder changed -> TEST_FAILURE -> retry: own changes are not dirty ----------
+test('C: coder edits, fails tests, retries: its own changes do not trigger the gate', async () => {
+  const repo = gitRepo();
+  const { calls, runSubagent } = subagentStub({ writes: ['src.js'], reply: (_req, n) => (n === 1
+    ? json({ status: 'failed', summary: 'tests failed: 1 failing', acceptance: [{ id: 'A1', met: false, evidence: 'npm test: 1 failing' }], verification: [{ command: 'npm test', result: 'fail' }] })
+    : okResult()) });
+  const runner = createAgentRunner({ invoke: async () => ({ ok: false, error: 'no' }), runSubagent, agents, routing, registry: REG, repoRoot: repo });
+  const r = await runOrch({ repoRoot: repo, runner, plan: [spec('t1', 'coder', [], { kind: 'implement' })] });
+  assert.equal(r.status, 'completed', JSON.stringify(r.tasks[0]));
+  assert.equal(calls.length, 2);
+  assert.equal(r.escalations.length, 0, 'retry on own dirty tree asked nothing');
+  assert.equal(r.tasks[0].attempts, 2);
+  assert.deepEqual(r.tasks[0].ownedPaths, ['src.js']);
+  assert.ok(!r.trace.some(e => e.type === 'gate'));
+});
+
+// ---------- D: reviewer finding -> rework: original implement changes are owned ----------
+test('D: review finds blocking issue -> rework task runs without the gate on the first implementation\'s changes', async () => {
+  const repo = gitRepo();
+  const { calls, runSubagent } = subagentStub({ writes: ['impl.js'], reply: req => {
+    if (req.taskId === 'rev') return json({ status: 'completed', summary: 'reviewed', acceptance: [{ id: 'A1', met: true, evidence: 'read diff' }], remainingIssues: [{ summary: 'missing null check', blocking: true }] });
+    if (req.taskId === 't3') return okResult(); // re-review: clean
+    return okResult();
+  } });
+  // Use the subagent path for reviewer too by making every agent run through the same stub.
+  const runner = createAgentRunner({ invoke: async () => ({ ok: false, error: 'no' }), runSubagent, agents, routing, registry: REG, repoRoot: repo });
+  const r = await runOrch({ repoRoot: repo, runner, plan: [spec('t1', 'coder', [], { kind: 'implement' }), spec('rev', 'reviewer', ['t1'], { kind: 'review' })], policy: { limits: { max_rework_cycles: 1 } } });
+  assert.equal(r.status, 'completed', JSON.stringify(r.tasks.map(t => [t.id, t.kind, t.status, t.blockedReason])));
+  assert.equal(r.escalations.length, 0, 'rework asked nothing about the tree the first implement dirtied');
+  const rework = r.tasks.find(t => t.kind === 'implement' && t.id !== 't1');
+  assert.ok(rework, 'a rework task was added');
+  assert.equal(rework.status, 'completed');
+  assert.ok(calls.some(c => c.taskId === rework.id));
+  assert.ok(!r.trace.some(e => e.type === 'gate'));
+});
+
+// ---------- E: pre-existing unrelated changes -> gate before implementation ----------
+test('E: pre-existing unrelated dirty files gate implementation (session-less run -> blocked)', async () => {
+  const repo = gitRepo({ dirty: ['unrelated.txt'] });
+  const { calls, runSubagent } = subagentStub();
+  const runner = createAgentRunner({ invoke: async () => ({ ok: false, error: 'no' }), runSubagent, agents, routing, registry: REG, repoRoot: repo });
+  const r = await runOrch({ repoRoot: repo, runner, plan: [spec('t1', 'coder', [], { kind: 'implement' })] });
+  assert.equal(calls.length, 0);
+  assert.equal(r.status, 'needs-user');
+  assert.equal(r.tasks[0].status, 'blocked');
+  assert.match(r.escalations[0].question, /unrelated\.txt/);
+  assert.deepEqual(r.escalations[0].options.map(o => o.id), ['proceed', 'abort']);
+});
+
+// ---------- F: read-only investigate on a dirty tree continues ----------
+test('F: read-only investigation on a dirty tree is not gated', async () => {
+  const repo = gitRepo({ dirty: ['user.txt'] });
+  const { calls, runSubagent } = subagentStub();
+  const runner = createAgentRunner({ invoke: async () => ({ ok: false, error: 'no' }), runSubagent, agents, routing, registry: REG, repoRoot: repo });
+  const r = await runOrch({ repoRoot: repo, runner, plan: [spec('s', 'scout', [], { kind: 'investigate', executionMode: 'subagent' }), spec('rv', 'reviewer', ['s'], { kind: 'review' })] });
+  assert.equal(r.status, 'completed', JSON.stringify(r.tasks.map(t => [t.id, t.status, t.blockedReason])));
+  assert.equal(calls.length, 2);
+  assert.equal(r.escalations.length, 0);
+});
+
+// ---------- G: non-git workspace is never gated by inventory count ----------
+test('G: non-git workspace: file inventory count is not a dirty count', async () => {
+  const repo = mkdtempSync(join(tmpdir(), 'ludi-gate-nogit-'));
+  for (let i = 0; i < 12; i++) writeFileSync(join(repo, `f${i}.txt`), 'x\n');
+  const before = captureWorktree(repo);
+  assert.equal(before.source, 'files');
+  assert.ok(Object.keys(before.entries).length >= 12);
+  const { calls, runSubagent } = subagentStub({ writes: ['out.js'] });
+  const runner = createAgentRunner({ invoke: async () => ({ ok: false, error: 'no' }), runSubagent, agents, routing, registry: REG, repoRoot: repo });
+  const r = await runOrch({ repoRoot: repo, runner, plan: [spec('t1', 'coder', [], { kind: 'implement' })] });
+  assert.equal(r.status, 'completed', JSON.stringify(r.tasks[0]));
+  assert.equal(calls.length, 1);
+  assert.equal(r.escalations.length, 0);
+  assert.ok(!r.trace.some(e => e.type === 'gate'));
+});

package/tests/e2e-browser.mjs

@@ -0,0 +1,66 @@
+// Opt-in real E2E for the browser capability: drives the *installed* agent-browser
+// CLI against the local fixture page, snapshot -> ref action -> snapshot.
+// Not part of `node --test`; it launches a real browser. Run:
+//   node tests/e2e-browser.mjs
+// Requires `agent-browser` on PATH (npm i -g agent-browser) and a local Chrome/Brave.
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import assert from 'node:assert/strict';
+import { runBrowser, locateAgentBrowser } from '../adapters/pi/browser/agent-browser.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const fixture = pathToFileURL(join(kit, 'tests/fixtures/browser-page/index.html')).href;
+const session = `ludi-e2e-${Date.now()}`;
+const env = { ...process.env };
+
+assert.ok(locateAgentBrowser(env), 'agent-browser binary not found; npm i -g agent-browser');
+
+const steps = [];
+const step = async (name, promise) => {
+  const res = await promise;
+  steps.push({ name, ok: res.ok, kind: res.kind, status: res.status, durationMs: res.durationMs });
+  if (!res.ok) { console.log(JSON.stringify({ steps, failed: name, stderr: res.stderr, stdout: res.stdout, error: res.error }, null, 2)); process.exit(1); }
+  return res;
+};
+const opt = { env, session, timeoutMs: 90000 };
+
+try {
+  // 1. open the local page
+  await step('open', runBrowser('open', { url: fixture }, opt));
+
+  // 2. snapshot -> interactive refs
+  const snap1 = await step('snapshot', runBrowser('snapshot', {}, opt));
+  const refs = [...snap1.stdout.matchAll(/@?e\d+/g)].map(m => m[0]);
+  assert.ok(refs.length >= 2, `expected >=2 interactive refs, got: ${snap1.stdout.slice(0, 500)}`);
+
+  // find the input ref (textbox) and the button ref from the snapshot text
+  const refOf = re => { const m = snap1.stdout.match(re); return m ? '@' + m[1] : null; };
+  const inputRef = refOf(/textbox[^\n]*ref=(e\d+)/i) ?? refOf(/input[^\n]*ref=(e\d+)/i);
+  const buttonRef = refOf(/button[^\n]*ref=(e\d+)/i);
+  assert.ok(inputRef, `no textbox ref in snapshot:\n${snap1.stdout.slice(0, 800)}`);
+  assert.ok(buttonRef, `no button ref in snapshot:\n${snap1.stdout.slice(0, 800)}`);
+
+  // 3. fill the input via its ref
+  await step('fill', runBrowser('fill', { ref: inputRef, text: 'hello' }, opt));
+
+  // 4. click the button via its ref
+  await step('click', runBrowser('click', { ref: buttonRef }, opt));
+
+  // 5. re-snapshot and read the result text
+  const snap2 = await step('snapshot-after', runBrowser('snapshot', {}, opt));
+  const resultRef = (snap2.stdout.match(/result[^\n]*ref=(e\d+)/i))?.[1];
+  // result <p> is not interactive, so read it by selector if no ref; use get text on the id
+  const textRes = resultRef
+    ? await step('getText', runBrowser('getText', { ref: resultRef }, opt))
+    : await step('getText-sel', runBrowser('getText', { ref: '#result' }, opt));
+  assert.match(textRes.stdout, /hello hello|hello\s+hello/i, `expected greeting, got: ${textRes.stdout.slice(0, 300)}`);
+
+  // 6. confirm the input kept the filled value
+  const val = await step('getValue', runBrowser('getValue', { ref: inputRef }, opt));
+  assert.match(val.stdout, /hello/);
+
+  console.log(JSON.stringify({ outcome: 'success', fixture, session, steps }, null, 2));
+} finally {
+  await runBrowser('close', {}, opt);
+}
+console.log('PASS: real browser E2E');

package/tests/e2e-real-orchestrator-resume.mjs

@@ -0,0 +1,101 @@
+// Opt-in real resume through the installed pi CLI (not part of `node --test`; spends a little quota).
+//   node tests/e2e-real-orchestrator-resume.mjs
+// Starts a process that completes scout, stops on an intentional user decision, then a second
+// process answers and resumes. The completed scout task must not run again.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, cpSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { loadPolicy, mergePolicy } from '../lib/orchestrator/policy.mjs';
+import { openStore } from '../lib/orchestrator/store.mjs';
+import { createHealthMonitor } from '../lib/orchestrator/health.mjs';
+import { createAgentRunner } from '../lib/orchestrator/runner.mjs';
+import { orchestrate, formatReport } from '../lib/orchestrator/orchestrator.mjs';
+import { createPiInvoker } from '../adapters/pi/lib/invoke.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const here = fileURLToPath(import.meta.url);
+const phase = process.argv[2] ?? 'all';
+
+const plan = [
+  { id: 't1', title: 'Locate the average() defect', goal: 'Find why the average() test fails in this repository. Do not change files.', agent: 'scout', kind: 'investigate', capability: 'cheap-code', dependencies: [],
+    acceptance: ['the file and function containing the defect are named', 'the cause of the failing test is stated'] },
+  { id: 't2', title: 'Ask whether to apply the fix', goal: [
+    'Do not edit files.',
+    'If the orchestrator already recorded a decision for "Apply the average() fix now?", return status "completed", quote that decision, and do not ask again.',
+    'If no decision is recorded, do not choose. Return status "blocked" with exactly one decision and no acceptance met:',
+    '{"key":"apply-fix","question":"Apply the average() fix now?","flags":["user_value_judgement"],"options":[{"id":"now","summary":"apply the fix now","reversible":false,"risk":"medium"},{"id":"later","summary":"leave the fixture for now","reversible":false,"risk":"medium"}]}',
+  ].join('\n'), agent: 'scout', kind: 'investigate', capability: 'cheap-code', dependencies: ['t1'],
+    acceptance: ['the user has chosen whether to apply the fix'] },
+  { id: 't3', title: 'Confirm the recorded decision', goal: 'Quote the user decision already recorded for t2. Do not change files. Do not ask the user anything.', agent: 'reviewer', kind: 'review', capability: 'cheap-code', dependencies: ['t2'],
+    acceptance: ['the user decision from t2 is quoted'] },
+];
+
+function context(repo) {
+  const routing = loadRouting(join(kit, 'routing/routing.json'));
+  const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+  const { agents } = loadAgents(join(kit, 'agents'), routing);
+  const { policy } = loadPolicy(join(kit, 'orchestration/decision-policy.json'));
+  // Stay on cheap-code so a hosted usage limit falls through to the local candidate instead of the hosted-only ladder.
+  return { routing, registry, agents, policy: mergePolicy(policy, { decision_policy: { reassign_on_failure: false } }) };
+}
+
+if (phase === 'all') {
+  const root = mkdtempSync(join(tmpdir(), 'ludi-real-resume-'));
+  const repo = join(root, 'repo');
+  const store = join(root, 'state.db');
+  cpSync(join(kit, 'tests/fixtures/math-repo'), repo, { recursive: true });
+  const start = spawnSync(process.execPath, [here, 'start', store, repo], { encoding: 'utf8', timeout: 300000 });
+  if (start.status !== 0) { console.error(start.stdout); console.error(start.stderr); process.exit(start.status ?? 1); }
+  const info = JSON.parse(start.stdout.trim().split(/\r?\n/).at(-1));
+  console.log('start', info);
+  assert.equal(info.runStatus, 'waiting_for_user');
+  assert.equal(info.tasks.find(t => t.id === 't1').status, 'completed');
+  assert.equal(info.tasks.find(t => t.id === 't2').status, 'waiting_for_user');
+  assert.equal(info.tasks.find(t => t.id === 't3').status, 'blocked');
+  const resume = spawnSync(process.execPath, [here, 'resume', store, repo, info.runId, info.decisionId], { encoding: 'utf8', timeout: 300000 });
+  if (resume.status !== 0) { console.error(resume.stdout); console.error(resume.stderr); process.exit(resume.status ?? 1); }
+  console.log(resume.stdout);
+  console.log('PASS: real pi orchestrator resume');
+} else if (phase === 'start') {
+  const [, , , store, repo] = process.argv;
+  const { routing, registry, agents, policy } = context(repo);
+  const session = openStore(store);
+  const health = createHealthMonitor({ session, policy });
+  const runner = createAgentRunner({ invoke: createPiInvoker(), agents, routing, registry, repoRoot: repo, maxModelAttempts: policy.limits.model_attempts_per_task, health });
+  try {
+    const result = await orchestrate({ request: 'Diagnose the failing average() test and stop before applying a fix', plan, agents, routing, registry, policy, runner, repoRoot: repo, session, health });
+    writeFileSync(join(repo, 'start-trace.json'), JSON.stringify(result, null, 2));
+    console.log(formatReport(result));
+    console.log(JSON.stringify({ runId: result.runId, runStatus: result.runStatus, decisionId: result.escalations[0]?.id, tasks: result.tasks.map(t => ({ id: t.id, status: t.status })) }));
+    if (result.runStatus !== 'waiting_for_user') process.exitCode = 1;
+  } finally { session.close(); }
+} else if (phase === 'resume') {
+  const [, , , store, repo, runId, decisionId] = process.argv;
+  const { routing, registry, agents, policy } = context(repo);
+  const session = openStore(store);
+  const before = session.loadTrace(runId).filter(e => e.type === 'result' && e.taskId === 't1').length;
+  const health = createHealthMonitor({ session, policy });
+  const runner = createAgentRunner({ invoke: createPiInvoker(), agents, routing, registry, repoRoot: repo, maxModelAttempts: policy.limits.model_attempts_per_task, health });
+  try {
+    const result = await orchestrate({
+      request: '', resumeRunId: runId, answers: [{ decisionId, answer: 'later' }],
+      agents, routing, registry, policy, runner, repoRoot: repo, session, health,
+    });
+    const t1Runs = result.trace.filter(e => e.type === 'result' && e.taskId === 't1');
+    writeFileSync(join(repo, 'resume-trace.json'), JSON.stringify({ status: result.status, runStatus: result.runStatus, tasks: result.tasks, t1Runs: t1Runs.length }, null, 2));
+    console.log(formatReport(result));
+    assert.equal(before, 1);
+    assert.equal(t1Runs.length, 1, 'completed scout task was executed again');
+    assert.equal(result.tasks.find(t => t.id === 't3').status, 'completed');
+    assert.equal(result.status, 'completed');
+  } finally { session.close(); }
+} else {
+  console.error(`unknown phase ${phase}`);
+  process.exit(2);
+}

package/tests/e2e-real-orchestrator.mjs

@@ -0,0 +1,41 @@
+// Opt-in real orchestrator run through the installed pi CLI (not part of `node --test`; spends a little quota).
+//   node tests/e2e-real-orchestrator.mjs
+// Two read-only tasks on the math fixture, both routed to the cheap-code capability to keep cost low:
+// scout investigates, reviewer (role kept, model route overridden) checks the finding. No files are written.
+import { mkdtempSync, cpSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { loadPolicy } from '../lib/orchestrator/policy.mjs';
+import { createAgentRunner } from '../lib/orchestrator/runner.mjs';
+import { orchestrate, formatReport } from '../lib/orchestrator/orchestrator.mjs';
+import { createPiInvoker } from '../adapters/pi/lib/invoke.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { agents } = loadAgents(join(kit, 'agents'), routing);
+const { policy } = loadPolicy(join(kit, 'orchestration/decision-policy.json'));
+const repo = mkdtempSync(join(tmpdir(), 'ludi-real-orch-'));
+cpSync(join(kit, 'tests/fixtures/math-repo'), repo, { recursive: true });
+
+const plan = [
+  { id: 't1', title: 'Locate the average() defect', goal: 'Find why the average() test fails in this repository. Do not change files.', agent: 'scout', kind: 'investigate', capability: 'cheap-code', dependencies: [],
+    acceptance: ['the file and function containing the defect are named', 'the cause of the failing test is stated'] },
+  { id: 't2', title: 'Check the diagnosis', goal: 'Check whether the diagnosis from t1 is correct against the source. Do not change files.', agent: 'reviewer', kind: 'review', capability: 'cheap-code', dependencies: ['t1'],
+    acceptance: ['the diagnosis is confirmed or refuted with a code reference'] },
+];
+const runner = createAgentRunner({ invoke: createPiInvoker(), agents, routing, registry, repoRoot: repo, maxModelAttempts: policy.limits.model_attempts_per_task });
+const result = await orchestrate({ request: 'Diagnose the failing average() test', plan, agents, routing, registry, policy, runner, repoRoot: repo });
+const traceFile = join(repo, 'orchestration-trace.json');
+writeFileSync(traceFile, JSON.stringify(result, null, 2));
+console.log(formatReport(result));
+console.log(JSON.stringify({ trace: traceFile, runs: result.trace.filter(e => e.type === 'result').map(e => ({ task: e.taskId, attempt: e.attempt, modelId: e.modelId, verdict: e.verdict, reasons: e.reasons, ms: e.steps?.reduce((s, x) => s + (x.durationMs ?? 0), 0) })) }, null, 2));
+assert.equal(result.tasks.length, 2);
+assert.ok(result.tasks.every(t => ['completed', 'failed', 'blocked'].includes(t.status)), 'every task reached a terminal state');
+assert.equal(result.status, 'completed');
+console.log('PASS: real pi orchestrator E2E');

package/tests/e2e-real-pi.mjs

@@ -0,0 +1,27 @@
+// Opt-in real E2E through the installed pi CLI and the machine-local model registry.
+// Not part of `node --test`; it spends real model quota. Run:
+//   node tests/e2e-real-pi.mjs
+// Requires adapters/pi/models.local.json with ready providers (`pi auth check --provider <p>`).
+import { mkdtempSync, cpSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { runPipeline, runTests } from '../lib/pipeline.mjs';
+import { createPiInvoker } from '../adapters/pi/lib/invoke.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { agents } = loadAgents(join(kit, 'agents'), routing);
+const repo = mkdtempSync(join(tmpdir(), 'ludi-real-e2e-'));
+cpSync(join(kit, 'tests/fixtures/math-repo'), repo, { recursive: true });
+assert.equal(runTests(repo, 'npm test').ok, false, 'fixture must start red');
+const summary = await runPipeline({ repoRoot: repo, task: 'Fix the failing average() test in this repository', routing, registry, agents, invoke: createPiInvoker(), outDir: join(repo, '.pipeline-out') });
+console.log(JSON.stringify({ outcome: summary.outcome, steps: summary.steps.map(s => ({ step: s.step, backend: s.backend, modelId: s.modelId, ok: s.ok, durationMs: s.durationMs })), applied: summary.applied, out: join(repo, '.pipeline-out') }, null, 2));
+assert.equal(summary.outcome, 'success');
+assert.equal(runTests(repo, 'npm test').ok, true);
+console.log('PASS: real pi E2E');

package/tests/e2e-real-tool-orchestrator.mjs

@@ -0,0 +1,66 @@
+// Opt-in tool-capable run through the installed pi CLI (not part of `node --test`).
+//   node tests/e2e-real-tool-orchestrator.mjs
+// Scout reads the fixture, coder edits average(), tester runs the tests, reviewer checks the diff.
+// All four stay on cheap-code so a hosted usage limit can fall through to the local model.
+import { mkdtempSync, cpSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { loadRouting } from '../lib/routing.mjs';
+import { loadRegistry } from '../lib/registry.mjs';
+import { loadAgents } from '../lib/agents.mjs';
+import { loadPolicy, mergePolicy } from '../lib/orchestrator/policy.mjs';
+import { openStore } from '../lib/orchestrator/store.mjs';
+import { createHealthMonitor } from '../lib/orchestrator/health.mjs';
+import { createAgentRunner } from '../lib/orchestrator/runner.mjs';
+import { orchestrate, formatReport } from '../lib/orchestrator/orchestrator.mjs';
+import { createPiInvoker } from '../adapters/pi/lib/invoke.mjs';
+import { createPiSubagentRunner } from '../adapters/pi/lib/subagent.mjs';
+
+const kit = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const root = mkdtempSync(join(tmpdir(), 'ludi-real-tools-'));
+const repo = join(root, 'repo');
+const storePath = join(root, 'state.db');
+cpSync(join(kit, 'tests/fixtures/math-repo'), repo, { recursive: true });
+for (const args of [['init'], ['add', '-A'], ['-c', 'user.email=ludi@example.com', '-c', 'user.name=ludi', 'commit', '-m', 'fixture']]) {
+  const git = spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
+  if (git.status !== 0) { console.error(git.stderr); process.exit(git.status ?? 1); }
+}
+
+const plan = [
+  { id: 't1', title: 'Find the average() defect', goal: 'Read the repository and name the file, function, and cause of the failing average() test. Do not edit files.', agent: 'scout', kind: 'investigate', capability: 'cheap-code', executionMode: 'subagent', dependencies: [], acceptance: ['the file and function are named', 'the cause is stated from the source'] },
+  { id: 't2', title: 'Fix average()', goal: 'Change average() so it divides by values.length. Do not change tests or unrelated files.', agent: 'coder', kind: 'implement', capability: 'cheap-code', executionMode: 'subagent', dependencies: ['t1'], acceptance: ['src/math.js divides by values.length', 'no other source file was rewritten'] },
+  { id: 't3', title: 'Run the tests', goal: 'Run npm test in this repository and report the result. Do not edit files.', agent: 'tester', kind: 'verify', capability: 'cheap-code', executionMode: 'subagent', dependencies: ['t2'], acceptance: ['npm test was executed', 'the command exited successfully'] },
+  { id: 't4', title: 'Review the diff', goal: 'Review the uncommitted diff against the goal. Do not edit files or push.', agent: 'reviewer', kind: 'review', capability: 'cheap-code', executionMode: 'subagent', dependencies: ['t3'], acceptance: ['the diff matches the average() fix', 'no publish or destructive command is proposed'] },
+];
+
+const routing = loadRouting(join(kit, 'routing/routing.json'));
+const { registry } = loadRegistry(join(kit, 'adapters/pi/models.json'), join(kit, 'adapters/pi/models.local.json'), routing);
+const { agents } = loadAgents(join(kit, 'agents'), routing);
+const { policy } = loadPolicy(join(kit, 'orchestration/decision-policy.json'));
+const active = mergePolicy(policy, { decision_policy: { reassign_on_failure: false }, limits: { max_retries: 1 }, agent_runtime: { max_runtime_ms: 180000, max_tool_calls: 25, max_turns: 8 } });
+const session = openStore(storePath);
+const health = createHealthMonitor({ session, policy: active });
+const runner = createAgentRunner({
+  invoke: createPiInvoker(), runSubagent: createPiSubagentRunner(), agents, routing, registry, repoRoot: repo, policy: active, health,
+  maxModelAttempts: active.limits.model_attempts_per_task,
+});
+try {
+  const result = await orchestrate({ request: 'Fix the failing average() test', plan, agents, routing, registry, policy: active, runner, repoRoot: repo, session, health });
+  writeFileSync(join(root, 'trace.json'), JSON.stringify(result, null, 2));
+  console.log(formatReport(result));
+  const children = result.trace.filter(e => e.type === 'child');
+  console.log(JSON.stringify({ runId: result.runId, status: result.status, children: children.map(c => ({ task: c.taskId, id: c.childSessionId, tools: c.toolCalls, turns: c.turns, status: c.status })), tasks: result.tasks.map(t => ({ id: t.id, status: t.status, files: t.result?.filesChanged ?? [] })) }, null, 2));
+  assert.equal(result.status, 'completed');
+  assert.equal(result.escalations.length, 0);
+  assert.ok(children.length >= 4, 'child sessions missing');
+  assert.ok(children.some(c => (c.toolCalls ?? 0) > 0), 'no tool call was recorded');
+  assert.ok(result.tasks.find(t => t.id === 't2').result.filesChanged.some(f => f.includes('math.js')));
+  const tests = spawnSync('npm', ['test'], { cwd: repo, encoding: 'utf8', shell: true });
+  assert.equal(tests.status, 0, tests.stdout + tests.stderr);
+  console.log('PASS: real pi tool-capable E2E');
+} finally {
+  session.close();
+}

package/tests/fixtures/browser-page/index.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>ludi browser fixture</title>
+</head>
+<body>
+  <h1>Browser fixture</h1>
+  <label for="name">Name</label>
+  <input id="name" name="name" type="text" placeholder="type a name">
+  <button id="greet" type="button">Greet</button>
+  <p id="result" aria-live="polite"></p>
+  <script>
+    document.getElementById('greet').addEventListener('click', () => {
+      const v = document.getElementById('name').value;
+      document.getElementById('result').textContent = v ? `hello ${v}` : 'hello (empty)';
+    });
+  </script>
+</body>
+</html>

package/tests/fixtures/maintenance/availability.txt

@@ -0,0 +1,5 @@
+# availability fixture: one provider/model per line (pi --list-models-like)
+openai-codex/gpt-5.6-sol
+openai-codex/gpt-6-astra
+openai-codex/gpt-5.5
+qoder/Qwen3.9-Flash

package/tests/fixtures/maintenance/catalog.json

@@ -0,0 +1,74 @@
+{
+  "$comment": "Fixture catalog for the Qoder/Qwen3.8-Flash scenario. Ids are fictional test data.",
+  "version": 1,
+  "updatedAt": "2026-03-02",
+  "models": [
+    {
+      "provider": "qoder",
+      "model": "Qwen3.8-Flash",
+      "status": "free-campaign",
+      "cost": { "free": true },
+      "postCampaignCost": { "usdPerMInput": 0.3, "usdPerMOutput": 1.2, "free": false },
+      "contextK": 256,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "low",
+      "scores": { "coding": 62, "reasoning": 55, "speed": 85 }
+    },
+    {
+      "provider": "qoder",
+      "model": "Qwen3.9-Flash",
+      "status": "active",
+      "cost": { "usdPerMInput": 0.25, "usdPerMOutput": 1.0 },
+      "contextK": 256,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "low",
+      "scores": { "coding": 70, "reasoning": 62, "speed": 85 }
+    },
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.6-luna",
+      "status": "active",
+      "cost": { "usdPerMInput": 0.4, "usdPerMOutput": 1.6 },
+      "contextK": 272,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "low",
+      "scores": { "coding": 68, "reasoning": 60, "speed": 80 }
+    },
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.6-sol",
+      "status": "active",
+      "cost": { "usdPerMInput": 1.5, "usdPerMOutput": 6.0 },
+      "contextK": 400,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "medium",
+      "scores": { "coding": 85, "reasoning": 82, "speed": 55 }
+    },
+    {
+      "provider": "openai-codex",
+      "model": "gpt-6-astra",
+      "status": "active",
+      "cost": { "usdPerMInput": 2.5, "usdPerMOutput": 10.0 },
+      "contextK": 400,
+      "vision": true,
+      "toolUse": "good",
+      "thinking": "medium",
+      "scores": { "coding": 88, "reasoning": 90, "speed": 50 }
+    },
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.5",
+      "status": "active",
+      "cost": { "usdPerMInput": 1.25, "usdPerMOutput": 5.0 },
+      "contextK": 400,
+      "vision": false,
+      "toolUse": "good",
+      "thinking": "high",
+      "scores": { "coding": 82, "reasoning": 84, "speed": 45 }
+    }
+  ]
+}

package/tests/fixtures/maintenance/events.json

@@ -0,0 +1,13 @@
+{
+  "$comment": "Fixture: the Qoder provider ends the free campaign for Qwen3.8-Flash on 2026-03-01. Used by tests/maintenance.test.mjs; ids are fictional.",
+  "version": 1,
+  "events": [
+    {
+      "type": "free-campaign-ended",
+      "provider": "qoder",
+      "model": "Qwen3.8-Flash",
+      "asOf": "2026-03-01",
+      "note": "Qoder free promotion for Qwen3.8-Flash ends; pay-as-you-go pricing applies afterwards."
+    }
+  ]
+}