atris 3.69.0 → 3.71.0

package/lib/campaign-core.js

@@ -0,0 +1,330 @@
+// Campaign core: fold(events) -> view, decide(view) -> next move.
+// Pure: no I/O, no clock, no network. The rules are the cross-surface
+// contract in test/fixtures/campaign/README.md; every surface's fold must
+// match the golden files there.
+
+'use strict';
+
+const { TIMESTAMP, validateEvent, isHumanActor } = require('./campaign-schema');
+
+function cents(amount) {
+  return Math.floor(amount * 100 + 0.5);
+}
+
+function dollars(value) {
+  return value / 100;
+}
+
+// An instant at full precision: whole seconds since the epoch plus nine
+// fraction digits, so two events a microsecond apart never tie.
+function instant(at) {
+  const [, date, time, fraction = '', zone] = TIMESTAMP.exec(at);
+  return { seconds: Date.parse(`${date}T${time}${zone}`) / 1000, nanos: fraction.padEnd(9, '0') };
+}
+
+function compareEvents(a, b) {
+  const x = instant(a.at);
+  const y = instant(b.at);
+  if (x.seconds !== y.seconds) return x.seconds - y.seconds;
+  if (x.nanos !== y.nanos) return x.nanos < y.nanos ? -1 : 1;
+  if (a.origin !== b.origin) return a.origin < b.origin ? -1 : 1;
+  if (a.seq !== b.seq) return a.seq - b.seq;
+  if (a.id !== b.id) return a.id < b.id ? -1 : 1;
+  return 0;
+}
+
+function seatFrom(seat) {
+  if (typeof seat === 'string') return { member: seat, role: null };
+  return { member: seat.member, role: seat.role === undefined ? null : seat.role };
+}
+
+function addSeat(seats, seat) {
+  if (seats.some((s) => s.member === seat.member && s.role === seat.role)) return;
+  seats.push(seat);
+}
+
+// Statuses only move forward; dropped and vetoed are final.
+const STATUS_RANK = { proposed: 0, claimed: 1, running: 2, ended: 3 };
+
+function moveTo(m, status) {
+  const from = STATUS_RANK[m.status];
+  if (from === undefined || from >= STATUS_RANK[status]) return;
+  m.status = status;
+}
+
+function newMission(id) {
+  return {
+    id, member: null, status: 'proposed', outcome: null, costCents: null,
+    estimate_usd: null, steps: 0, kept: 0, reverted: 0,
+  };
+}
+
+// Returns the folded view, or { error } when the events must be refused.
+function fold(events) {
+  if (!Array.isArray(events)) return { error: 'invalid_event' };
+  for (const event of events) {
+    if (!validateEvent(event).ok) return { error: 'invalid_event' };
+  }
+  const campaignIds = new Set(events.map((e) => e.campaign_id));
+  if (campaignIds.size > 1) return { error: 'mixed_campaigns' };
+
+  const seen = new Set();
+  const unique = [];
+  for (const event of events) {
+    if (seen.has(event.id)) continue;
+    seen.add(event.id);
+    unique.push(event);
+  }
+  const ordered = unique.slice().sort(compareEvents);
+  const start = ordered.find((e) => e.type === 'campaign_started');
+  if (!start) return { error: 'no_start' };
+
+  const s = {
+    finished: null,
+    paused: false,
+    seats: [],
+    bet: null,
+    parent: null,
+    home: start.origin,
+    missions: new Map(),
+    claims: new Map(),
+    reservations: new Map(),
+    totalCents: cents(start.data.budget),
+    spentCents: 0,
+    asks: new Map(),
+    judgeRuns: [],
+    lastEndedPos: -1,
+    judgeSetPos: -1,
+    judge: start.data.judge,
+    lastJudgePos: -1,
+    warnings: [],
+  };
+  const d = start.data;
+  const owner = typeof d.owner === 'string' && d.owner ? d.owner : 'mission-lead';
+  for (const seat of d.seats || []) addSeat(s.seats, seatFrom(seat));
+  if (d.bet) s.bet = { text: d.bet, wrong_if: null };
+
+  const warn = (event, code) => s.warnings.push({ event_id: event.id, code });
+  const mission = (id) => {
+    if (!s.missions.has(id)) s.missions.set(id, newMission(id));
+    return s.missions.get(id);
+  };
+
+  const sequence = [start, ...ordered.filter((e) => e !== start)];
+  sequence.forEach((event, pos) => {
+    const data = event.data;
+    switch (event.type) {
+      case 'campaign_started':
+        if (event !== start) warn(event, 'duplicate_start');
+        break;
+      case 'seat_filled':
+        addSeat(s.seats, { member: data.member, role: data.role });
+        break;
+      case 'bet_set':
+        s.bet = { text: data.bet, wrong_if: data.wrong_if || null };
+        break;
+      case 'judge_set':
+        if (event.actor !== owner && !isHumanActor(event.actor)) {
+          warn(event, 'judge_set_not_owner');
+        } else {
+          s.judge = data.judge;
+          s.judgeSetPos = pos;
+        }
+        break;
+      case 'attached':
+        s.parent = data.parent_id;
+        break;
+      case 'mission_proposed':
+        if (!s.missions.has(data.mission_id)) {
+          const m = mission(data.mission_id);
+          m.member = data.member || null;
+          m.estimate_usd = typeof data.estimate_usd === 'number' ? dollars(cents(data.estimate_usd)) : null;
+        }
+        break;
+      case 'mission_claimed': {
+        const holder = s.claims.get(data.claim_key);
+        const m = mission(data.mission_id);
+        if (holder !== undefined && holder !== data.mission_id) {
+          warn(event, 'duplicate_claim');
+          if (m.status === 'proposed') m.status = 'dropped';
+        } else {
+          s.claims.set(data.claim_key, data.mission_id);
+          moveTo(m, 'claimed');
+        }
+        break;
+      }
+      case 'mission_vetoed': {
+        if (event.actor !== owner && !isHumanActor(event.actor)) {
+          warn(event, 'veto_not_owner');
+          break;
+        }
+        const m = mission(data.mission_id);
+        if (m.status === 'proposed' || m.status === 'claimed') m.status = 'vetoed';
+        break;
+      }
+      case 'mission_started': {
+        const m = mission(data.mission_id);
+        moveTo(m, 'running');
+        if (m.member === null) m.member = data.member;
+        else if (m.member !== data.member) warn(event, 'second_assignee');
+        break;
+      }
+      case 'step':
+      case 'kept':
+      case 'reverted': {
+        const m = mission(data.mission_id);
+        const key = event.type === 'step' ? 'steps' : event.type;
+        m[key] += 1;
+        break;
+      }
+      case 'mission_ended': {
+        const m = mission(data.mission_id);
+        m.status = 'ended';
+        m.outcome = data.outcome;
+        m.costCents = cents(data.cost_usd);
+        s.spentCents += m.costCents;
+        s.reservations.delete(data.mission_id);
+        s.lastEndedPos = pos;
+        break;
+      }
+      case 'budget_reserved': {
+        const m = s.missions.get(data.mission_id);
+        if (!m || m.status !== 'ended') s.reservations.set(data.mission_id, cents(data.amount_usd));
+        break;
+      }
+      case 'budget_released':
+        s.reservations.delete(data.mission_id);
+        break;
+      case 'budget_added':
+        s.totalCents += cents(data.amount_usd);
+        break;
+      case 'judge_ran':
+        s.judgeRuns.push({
+          passed: data.passed,
+          reading: typeof data.reading === 'number' ? data.reading : null,
+          summary: typeof data.summary === 'string' ? data.summary : null,
+          confidence: data.confidence || null,
+          at: event.at,
+        });
+        s.lastJudgePos = pos;
+        if (data.passed && !d.standing && !s.finished) s.finished = 'judge_passed';
+        break;
+      case 'ask_opened':
+        if (!s.asks.has(data.ask_id)) s.asks.set(data.ask_id, { id: data.ask_id, question: data.question, mission_id: data.mission_id || null });
+        break;
+      case 'ask_answered':
+        if (!isHumanActor(event.actor)) warn(event, 'ask_answered_by_agent');
+        else if (!s.asks.has(data.ask_id)) warn(event, 'unknown_ask');
+        else s.asks.delete(data.ask_id);
+        break;
+      case 'paused':
+        s.paused = true;
+        break;
+      case 'resumed':
+        s.paused = false;
+        break;
+      case 'stopped':
+        if (!s.finished) s.finished = 'stopped';
+        break;
+      case 'home_moved':
+        s.home = data.to;
+        break;
+      case 'done':
+        if (!isHumanActor(event.actor)) warn(event, 'done_without_judge');
+        else if (!s.finished) s.finished = 'done_by_human';
+        break;
+      default:
+        break;
+    }
+  });
+
+  const missions = [...s.missions.values()];
+  let state;
+  let stopReason = null;
+  if (s.finished) {
+    state = 'done';
+    stopReason = s.finished;
+  } else if (s.spentCents >= s.totalCents) {
+    state = 'out_of_budget';
+    stopReason = 'budget_spent';
+  } else if (s.paused) {
+    state = 'paused';
+  } else if (s.asks.size > 0) {
+    state = 'needs_you';
+  } else if (missions.some((m) => m.status === 'running')) {
+    state = 'running';
+  } else if (missions.some((m) => m.status === 'proposed' || m.status === 'claimed')) {
+    state = 'queued';
+  } else {
+    state = 'resting';
+  }
+
+  const runs = s.judgeRuns;
+  const latest = runs.length ? runs[runs.length - 1] : null;
+  let confidence = 'open';
+  if (latest && s.finished === 'judge_passed') {
+    confidence = 'answered';
+  } else if (latest && latest.passed) {
+    let streak = 0;
+    for (let i = runs.length - 1; i >= 0 && runs[i].passed; i--) streak++;
+    confidence = streak >= 3 ? 'stronger' : 'leaning';
+  } else if (latest) {
+    confidence = latest.confidence || 'open';
+  }
+
+  const reservedCents = [...s.reservations.values()].reduce((sum, value) => sum + value, 0);
+  return {
+    id: start.campaign_id,
+    title: d.title,
+    judge: s.judge,
+    owner,
+    standing: d.standing === true,
+    bet: s.bet,
+    parent: s.parent,
+    home: s.home,
+    created_from: d.created_from === undefined ? null : d.created_from,
+    seats: s.seats,
+    state,
+    stop_reason: stopReason,
+    answer: { text: latest ? latest.summary : null, confidence },
+    budget: {
+      total: dollars(s.totalCents),
+      spent: dollars(s.spentCents),
+      reserved: dollars(reservedCents),
+      available: dollars(s.totalCents - s.spentCents - reservedCents),
+    },
+    asks: [...s.asks.values()],
+    missions: missions.map((m) => ({
+      id: m.id,
+      member: m.member,
+      status: m.status,
+      outcome: m.outcome,
+      cost_usd: m.costCents === null ? null : dollars(m.costCents),
+      estimate_usd: m.estimate_usd,
+      steps: m.steps,
+      kept: m.kept,
+      reverted: m.reverted,
+    })),
+    judge_runs: runs.length,
+    judge_due: runs.length === 0 || Math.max(s.lastEndedPos, s.judgeSetPos) > s.lastJudgePos,
+    last_judge: latest ? { passed: latest.passed, reading: latest.reading, at: latest.at } : null,
+    warnings: s.warnings,
+  };
+}
+
+function decide(view) {
+  if (view.state === 'done') return { action: 'none', reason: 'finished' };
+  if (view.state === 'out_of_budget') return { action: 'none', reason: 'budget spent' };
+  if (view.state === 'paused') return { action: 'none', reason: 'paused' };
+  if (view.asks.length > 0) return { action: 'wait', reason: 'open asks', asks: view.asks.map((a) => a.id) };
+  if (view.judge_due) return { action: 'run_judge' };
+  const claimed = view.missions.filter((m) => m.status === 'claimed');
+  const available = cents(view.budget.available);
+  const fits = claimed.find((m) => cents(m.estimate_usd || 0) <= available);
+  if (fits) return { action: 'start_mission', mission_id: fits.id };
+  if (claimed.length > 0) return { action: 'wait', reason: 'budget' };
+  if (view.missions.some((m) => m.status === 'running')) return { action: 'wait', reason: 'missions running' };
+  return { action: 'propose', reason: 'no missions queued' };
+}
+
+module.exports = { cents, compareEvents, decide, fold };

package/lib/campaign-holdout.js

@@ -0,0 +1,65 @@
+// Held-out judge data: `atris campaign start --holdout <file>` moves the file
+// out of the repo into the campaign's own folder beside the campaign store, so
+// agents working in the checkout never read it. The judge finds it through
+// ATRIS_CAMPAIGN_HOLDOUT, and any of its lines the judge echoes are scrubbed
+// before the reading is stored, so show and export cannot print them.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MASK = '[held out]';
+
+function holdoutDir(root, campaignId) {
+  return path.join(root, 'campaigns', campaignId, 'holdout');
+}
+
+// The held-out file for a campaign, or null when it has none.
+function findHoldout(root, campaignId) {
+  const dir = holdoutDir(root, campaignId);
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return null; }
+  const name = names.sort().find((n) => fs.statSync(path.join(dir, n)).isFile());
+  return name ? path.join(dir, name) : null;
+}
+
+function moveFile(from, to) {
+  try {
+    fs.renameSync(from, to);
+  } catch (error) {
+    if (error.code !== 'EXDEV') throw error;
+    fs.copyFileSync(from, to);
+    fs.unlinkSync(from);
+  }
+}
+
+// Moves the file in and returns its new path, or { error } in plain words.
+function moveHoldoutIn(root, campaignId, source) {
+  const from = path.resolve(source);
+  if (!fs.existsSync(from) || !fs.statSync(from).isFile()) return { error: `--holdout ${source} is not a file` };
+  const dir = holdoutDir(root, campaignId);
+  fs.mkdirSync(dir, { recursive: true });
+  const to = path.join(dir, path.basename(from));
+  moveFile(from, to);
+  return { path: to, from };
+}
+
+// Puts the file back where it came from, for a start that was refused.
+function moveHoldoutBack(moved) {
+  if (moved && moved.path && fs.existsSync(moved.path) && !fs.existsSync(moved.from)) moveFile(moved.path, moved.from);
+}
+
+// Replaces every held-out line that shows up in text.
+function scrub(text, holdoutPath) {
+  if (typeof text !== 'string' || !text || !holdoutPath) return text;
+  let content;
+  try { content = fs.readFileSync(holdoutPath, 'utf8'); } catch { return text; }
+  const lines = [...new Set(content.split('\n').map((line) => line.trim()).filter((line) => line.length >= 4))];
+  lines.sort((a, b) => b.length - a.length);
+  let out = text;
+  for (const line of lines) out = out.split(line).join(MASK);
+  return out;
+}
+
+module.exports = { findHoldout, holdoutDir, moveHoldoutBack, moveHoldoutIn, scrub };

package/lib/campaign-loop.js

@@ -0,0 +1,242 @@
+// The campaign loop: a campaign runs itself until its judge passes, its money
+// runs out, or it needs a person. Each step asks decide what to do, then does
+// it: run the judge, start claimed missions (several at once), or ask the
+// owner's engine to propose the next missions. Campaigns decide, missions do.
+
+'use strict';
+
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+const { decide } = require('./campaign-core');
+const { getCampaign, openCampaignStore } = require('./campaign-store');
+const { defaultReserve, reconcileCampaign } = require('./campaign-missions');
+const { judgeRanData, latestJudgeOutput } = require('./campaign-reading');
+
+const TERMINAL = new Set(['stopped', 'complete']);
+
+const CLI = path.join(__dirname, '..', 'bin', 'atris.js');
+const PROPOSE_TIMEOUT_MS = 5 * 60 * 1000;
+
+function claimKey(objective) {
+  return String(objective).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().slice(0, 160);
+}
+
+function proposalId(objective) {
+  const slug = String(objective).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '');
+  return `m-${slug || 'mission'}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+// What the owner's engine reads before proposing: the goal, how it is judged,
+// what has been tried, and how it went.
+function proposalPrompt(view, count, judgeOutput = null, lessons = '') {
+  const tried = view.missions.slice(-12).map((m) => `- ${m.id}: ${m.status}${m.outcome ? ` (${m.outcome})` : ''}${m.cost_usd !== null ? `, $${m.cost_usd}` : ''}`).join('\n') || '- none yet';
+  const seats = view.seats.map((s) => s.member).filter(Boolean);
+  const members = [...new Set([view.owner, ...seats])];
+  return [
+    `You plan the next missions for an Atris campaign. Answer with JSON only.`,
+    ``,
+    `Campaign: ${view.title}`,
+    `Judge (the campaign is done when this command exits 0): ${view.judge}`,
+    `Last judge reading: ${view.last_judge ? `${view.last_judge.passed ? 'passed' : 'failed'}${typeof view.last_judge.reading === 'number' ? ` (${view.last_judge.reading} of 1)` : ''}: ${view.answer.text || ''}` : 'never run'}`,
+    judgeOutput ? `Last judge output:\n\`\`\`\n${judgeOutput.replace(/```/g, "'''")}\n\`\`\`` : '',
+    view.bet ? `Current bet: ${view.bet.text}${view.bet.wrong_if ? ` (wrong if ${view.bet.wrong_if})` : ''}` : '',
+    `Money left: $${view.budget.available.toFixed(2)} of $${view.budget.total.toFixed(2)}`,
+    `Members who can take a mission: ${members.join(', ')}`,
+    `Missions so far:`,
+    tried,
+    lessons ? `Lessons from earlier rounds (follow them):\n${lessons}` : '',
+    ``,
+    `Propose at most ${count} missions that move the judge toward passing. Each is one member, one run, one checkable result.`,
+    `Do not repeat a mission that was already kept. Prefer small, independent missions that can run at the same time.`,
+    `Reply with a JSON array and nothing else:`,
+    `[{"objective": "<one sentence, imperative>", "member": "<one of the members above>", "verify": "<shell command that exits 0 when this mission's result is real>", "estimate_usd": <dollars, small>}]`,
+  ].filter((line) => line !== '').join('\n');
+}
+
+function parseProposals(text, view, count) {
+  const match = String(text || '').match(/\[[\s\S]*\]/);
+  if (!match) return [];
+  let rows;
+  try {
+    rows = JSON.parse(match[0]);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(rows)) return [];
+  const members = new Set([view.owner, ...view.seats.map((s) => s.member)]);
+  return rows.slice(0, count)
+    .filter((row) => row && typeof row.objective === 'string' && row.objective.trim())
+    .map((row) => ({
+      objective: row.objective.trim().slice(0, 300),
+      member: members.has(row.member) ? row.member : view.owner,
+      verify: typeof row.verify === 'string' && row.verify.trim() ? row.verify.trim() : view.judge,
+      estimate_usd: typeof row.estimate_usd === 'number' && row.estimate_usd > 0 ? Math.min(row.estimate_usd, view.budget.available) : null,
+    }));
+}
+
+// Ask the owner's engine for proposals through the read-only ask runner.
+async function askOwner(root, view, prompt) {
+  const { resolveEngineForMember } = require('./member-engine');
+  const { runEngineAskJobs } = require('./engine-ask');
+  const pick = resolveEngineForMember(view.owner, root) || {};
+  const engine = (pick.engine && pick.engine.id) || 'claude';
+  const [answer] = await runEngineAskJobs([{ engine, model: pick.model || '', prompt, label: `campaign ${view.id} plan` }], { root, timeoutMs: PROPOSE_TIMEOUT_MS });
+  return { text: (answer && answer.stdout) || '', engine, ok: Boolean(answer && answer.ok) };
+}
+
+// Run one atris command and resolve with its exit code and output.
+function runCli(args, { cwd, env = process.env, onLine = null } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CLI, ...args], { cwd, env: { ...env, ATRIS_SKIP_UPDATE_CHECK: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (chunk) => {
+      out += chunk;
+      if (onLine) String(chunk).split('\n').filter(Boolean).forEach(onLine);
+    });
+    child.stderr.on('data', (chunk) => { err += chunk; });
+    child.on('close', (code) => resolve({ code, out, err }));
+  });
+}
+
+function makeLoop(root, options = {}, deps = {}) {
+  const store = deps.store || openCampaignStore(root);
+  const log = deps.log || ((line) => console.log(line));
+  const parallel = Math.max(1, Number(options.parallel) || 3);
+  const maxTicks = Math.max(1, Number(options.maxTicks) || 3);
+  const runner = options.runner || 'auto';
+  const actor = options.actor || 'mission-lead';
+  const ask = deps.ask || askOwner;
+  const cli = deps.cli || ((args) => runCli(args, { cwd: root }));
+  const judge = deps.judge;
+
+  const view = (id) => getCampaign(store, id);
+  const append = (id, type, data, as = actor) => store.append({ campaign_id: id, type, actor: as, data });
+
+  async function propose(id, count = parallel) {
+    const current = view(id);
+    const prompt = proposalPrompt(current, count, latestJudgeOutput(store.read(id)), deps.lessons ? deps.lessons(id) : '');
+    const answer = await ask(root, current, prompt);
+    const proposals = parseProposals(answer.text, current, count);
+    // Planning costs money too. It rides on the first mission it produced as a
+    // step, so it is counted when that mission ends without making the judge
+    // due. A plan that produced nothing becomes its own ended mission.
+    const plan = { kind: 'plan', engine: answer.engine };
+    if (typeof answer.cost_usd === 'number') plan.cost_usd = answer.cost_usd;
+    proposals.forEach((proposal, index) => {
+      const missionId = proposalId(proposal.objective);
+      append(id, 'mission_proposed', { mission_id: missionId, member: proposal.member, objective: proposal.objective, verify: proposal.verify, estimate_usd: proposal.estimate_usd || undefined }, proposal.member);
+      append(id, 'mission_claimed', { mission_id: missionId, claim_key: claimKey(proposal.objective) }, proposal.member);
+      if (index === 0) append(id, 'step', { mission_id: missionId, ...plan }, current.owner);
+    });
+    if (!proposals.length) {
+      const planId = `plan-${crypto.randomBytes(3).toString('hex')}`;
+      append(id, 'mission_started', { mission_id: planId, member: current.owner, kind: 'plan' }, current.owner);
+      append(id, 'mission_ended', { mission_id: planId, outcome: 'failed', cost_usd: plan.cost_usd || 0, uncosted_runs: plan.cost_usd === undefined ? 1 : 0, engine: answer.engine }, current.owner);
+    }
+    return proposals;
+  }
+
+  // The proposal data behind each claimed mission (the fold keeps only ids).
+  function claimedWork(id) {
+    const current = view(id);
+    const proposals = new Map();
+    for (const event of store.read(id)) {
+      if (event.type === 'mission_proposed' && event.data.objective) proposals.set(event.data.mission_id, event.data);
+    }
+    return current.missions
+      .filter((m) => m.status === 'claimed' && proposals.has(m.id))
+      .map((m) => ({ ...proposals.get(m.id), mission_id: m.id, member: m.member || proposals.get(m.id).member || current.owner }));
+  }
+
+  async function startAndRun(id, work) {
+    const current = view(id);
+    const reserve = work.estimate_usd || defaultReserve(current);
+    const started = await cli([
+      'mission', 'start', work.objective, '--mission-id', work.mission_id, '--owner', work.member,
+      '--runner', runner, '--verify', work.verify || current.judge, '--campaign', id, '--reserve', String(reserve), '--json',
+    ]);
+    if (started.code !== 0) {
+      const why = (started.out + started.err).trim().split('\n').pop();
+      log(`  ${work.mission_id} did not start: ${why}`);
+      append(id, 'mission_vetoed', { mission_id: work.mission_id, reason: why.slice(0, 200) }, current.owner);
+      return { mission_id: work.mission_id, started: false };
+    }
+    log(`  ${work.mission_id} started for ${work.member}: ${work.objective}`);
+    const ran = await cli(['mission', 'run', work.mission_id, '--max-ticks', String(maxTicks), '--complete-on-pass']);
+    const after = view(id).missions.find((m) => m.id === work.mission_id);
+    if (after && after.status !== 'ended') {
+      // The run stopped without finishing (tick cap, error): close it so its
+      // reserve comes back and its cost is counted.
+      await cli(['mission', 'stop', work.mission_id, '--reason', `campaign loop: run ended without finishing (exit ${ran.code})`]);
+    }
+    const final = view(id).missions.find((m) => m.id === work.mission_id) || {};
+    log(`  ${work.mission_id} ${final.outcome || 'ended'} · $${(final.cost_usd || 0).toFixed(2)}`);
+    return { mission_id: work.mission_id, started: true, outcome: final.outcome || null };
+  }
+
+  // A campaign linked to the cloud trades events before and after every step,
+  // so a person's answer from a phone reaches this loop. A failed sync never
+  // stops the loop; deps.sync warns, keeps running offline, and resolves with
+  // how many events it pulled.
+  const sync = deps.sync || (async () => 0);
+
+  // One step, with a sync on each side.
+  async function step(id) {
+    await sync(id);
+    const result = await stepOnce(id);
+    await sync(id);
+    return result;
+  }
+
+  // One step. Returns { stop, reason } or { stop: false, did }.
+  async function stepOnce(id) {
+    // Missions that ended without telling the campaign give their reserve back first.
+    if (!deps.skipReconcile) {
+      try { reconcileCampaign(root, id, TERMINAL, { store }); } catch {}
+    }
+    const current = view(id);
+    if (!current) return { stop: true, reason: `no campaign ${id}` };
+    if (current.error) return { stop: true, reason: `campaign cannot be read: ${current.error}` };
+    const move = decide(current);
+    if (move.action === 'none') return { stop: true, reason: move.reason };
+    if (move.action === 'wait' && move.reason === 'open asks') return { stop: true, reason: `needs you: ${move.asks.length} open ask${move.asks.length === 1 ? '' : 's'}` };
+    if (move.action === 'run_judge') {
+      const reading = await judge(current.judge);
+      append(id, 'judge_ran', judgeRanData(reading), 'judge');
+      log(`judge ${reading.passed ? 'passed' : 'failed'}: ${reading.summary || `exit ${reading.exit}`}`);
+      return { stop: false, did: 'judge' };
+    }
+    if (move.action === 'start_mission' || (move.action === 'wait' && move.reason === 'budget')) {
+      const work = claimedWork(id).slice(0, parallel);
+      if (!work.length) return { stop: true, reason: 'claimed missions have no objective to run; start them by hand or veto them' };
+      log(`starting ${work.length} mission${work.length === 1 ? '' : 's'} at once`);
+      const results = await Promise.all(work.map((w) => startAndRun(id, w)));
+      if (!results.some((r) => r.started)) return { stop: true, reason: 'no claimed mission could start' };
+      return { stop: false, did: 'missions' };
+    }
+    if (move.action === 'wait') return { stop: true, reason: `waiting: ${move.reason} (started elsewhere)` };
+    log(`asking ${current.owner} to propose up to ${parallel} missions`);
+    const proposals = await propose(id, parallel);
+    if (!proposals.length) return { stop: true, reason: `${current.owner} proposed nothing usable` };
+    for (const p of proposals) log(`  proposed for ${p.member}: ${p.objective}`);
+    return { stop: false, did: 'propose' };
+  }
+
+  async function run(id, maxSteps = 20) {
+    await sync(id);
+    for (let i = 0; i < maxSteps; i++) {
+      const result = await stepOnce(id);
+      // An answer pulled just now can unblock a step that stopped for a person.
+      const pulled = await sync(id);
+      if (result.stop && pulled > 0) continue;
+      if (result.stop) return { steps: i, reason: result.reason, campaign: view(id) };
+    }
+    return { steps: maxSteps, reason: `stopped after ${maxSteps} steps`, campaign: view(id) };
+  }
+
+  return { step, run, propose };
+}
+
+module.exports = { askOwner, makeLoop, parseProposals, proposalPrompt };