atris 3.69.0 → 3.71.0

package/lib/campaign-missions.js

@@ -0,0 +1,237 @@
+// Missions that belong to a campaign (build.md Phase 3). commands/mission.js
+// calls these at start and on every save; a mission with no campaign_id never
+// reaches the store, so plain missions run exactly as before.
+
+'use strict';
+
+const { decide } = require('./campaign-core');
+const { getCampaign, openCampaignStore } = require('./campaign-store');
+
+const DEFAULT_RESERVE_USD = 5;
+const CLOSED_STATES = new Set(['done', 'out_of_budget', 'paused']);
+
+function storeFor(root, deps = {}) {
+  return deps.store || openCampaignStore(root);
+}
+
+function warn(message) {
+  process.stderr.write(`campaign: ${message}\n`);
+}
+
+// How much a new mission holds back: what missions in this campaign have cost
+// on average, or $5 before any has ended. --reserve overrides.
+function defaultReserve(view) {
+  const ended = view.missions.filter((m) => m.status === 'ended' && typeof m.cost_usd === 'number');
+  if (!ended.length) return DEFAULT_RESERVE_USD;
+  const average = ended.reduce((sum, m) => sum + m.cost_usd, 0) / ended.length;
+  return Math.max(0.01, Math.ceil(average * 100) / 100);
+}
+
+// Checked before a mission creates anything, so a refusal leaves nothing behind.
+function checkCampaignStart(root, campaignId, options = {}, deps = {}) {
+  const store = storeFor(root, deps);
+  const view = getCampaign(store, campaignId);
+  if (!view) return { ok: false, error: `no campaign ${campaignId}. See them with: atris campaign` };
+  if (view.error) return { ok: false, error: `campaign ${campaignId} cannot be read: ${view.error}` };
+  if (CLOSED_STATES.has(view.state)) {
+    return { ok: false, error: `campaign ${campaignId} is ${view.state.replace(/_/g, ' ')}, so it takes no new missions` };
+  }
+  if (options.missionId) {
+    const owner = store.campaignForMission(options.missionId);
+    if (owner && owner !== campaignId) return { ok: false, error: `mission ${options.missionId} already belongs to campaign ${owner}` };
+  }
+  const reserve = options.reserveUsd !== undefined && options.reserveUsd !== null && options.reserveUsd !== ''
+    ? Number(options.reserveUsd)
+    : defaultReserve(view);
+  if (!(reserve >= 0) || !Number.isFinite(reserve)) return { ok: false, error: '--reserve takes dollars, for example --reserve 5' };
+  if (reserve > view.budget.available) {
+    return {
+      ok: false,
+      error: `campaign ${campaignId} has $${view.budget.available.toFixed(2)} left and this mission would hold $${reserve.toFixed(2)}. Add money with: atris campaign budget ${campaignId} --add <dollars>`,
+    };
+  }
+  return { ok: true, campaign: view, reserve };
+}
+
+// Hold the reserve in one transaction with the check, so missions starting at
+// the same moment can never hold more than the campaign has left.
+function reserveCampaignMission(root, campaignId, missionId, amount, actor, deps = {}) {
+  if (!(amount > 0)) return null;
+  const store = storeFor(root, deps);
+  return store.append({ campaign_id: campaignId, type: 'budget_reserved', actor, data: { mission_id: missionId, amount_usd: amount } }, {
+    check: (view) => {
+      if (view.error) throw Object.assign(new Error(`campaign ${campaignId} cannot be read: ${view.error}`), { code: 'campaign_unreadable' });
+      if (CLOSED_STATES.has(view.state)) throw Object.assign(new Error(`campaign ${campaignId} is ${view.state.replace(/_/g, ' ')}, so it takes no new missions`), { code: 'campaign_closed' });
+      if (amount > view.budget.available) {
+        throw Object.assign(new Error(`campaign ${campaignId} has $${view.budget.available.toFixed(2)} left and this mission would hold $${amount.toFixed(2)}. Add money with: atris campaign budget ${campaignId} --add <dollars>`), { code: 'campaign_tank' });
+      }
+    },
+  });
+}
+
+// Before each tick: a mission stops working when its campaign is done,
+// paused, or out of money. Returns the pause reason, or null to keep going.
+function campaignGate(root, mission, deps = {}) {
+  if (!mission || !mission.campaign_id) return null;
+  try {
+    const view = getCampaign(storeFor(root, deps), mission.campaign_id);
+    if (!view || view.error) return null;
+    if (CLOSED_STATES.has(view.state)) return `campaign-${view.state.replace(/_/g, '-')}`;
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function readMissionLedger(root) {
+  const file = require('path').join(root, '.atris', 'state', 'missions.jsonl');
+  const latest = new Map();
+  let text = '';
+  try { text = require('fs').readFileSync(file, 'utf8'); } catch { return latest; }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row && row.id) latest.set(row.id, row);
+    } catch {}
+  }
+  return latest;
+}
+
+// Missions the campaign still counts as running whose mission record says
+// they are over, or that never got a record (a start that crashed after its
+// reserve): end them in the campaign so their reserve comes back.
+function reconcileCampaign(root, campaignId, terminalStatuses, deps = {}) {
+  const store = storeFor(root, deps);
+  const view = getCampaign(store, campaignId);
+  if (!view || view.error) return [];
+  const ledger = (deps.readLedger || readMissionLedger)(root);
+  const ended = [];
+  const reservedOnly = new Set();
+  for (const event of store.read(campaignId)) {
+    if (event.type === 'budget_reserved' && !view.missions.some((m) => m.id === event.data.mission_id)) reservedOnly.add(event.data.mission_id);
+    if (event.type === 'budget_released') reservedOnly.delete(event.data.mission_id);
+  }
+  for (const missionId of reservedOnly) {
+    if (ledger.has(missionId)) continue;
+    store.append({ campaign_id: campaignId, type: 'budget_released', actor: 'system', data: { mission_id: missionId, reason: 'mission was never created' } });
+    ended.push(missionId);
+  }
+  for (const m of view.missions) {
+    if (m.status !== 'running' || m.id.startsWith('plan-')) continue;
+    const record = ledger.get(m.id);
+    if (record && !terminalStatuses.has(record.status)) continue;
+    if (!record && !deps.endMissing) continue;
+    const result = recordCampaignMissionEnded(root, { status: 'running' }, { ...(record || { id: m.id, owner: m.member, status: 'stopped' }), campaign_id: campaignId }, terminalStatuses, deps);
+    if (result) ended.push(m.id);
+  }
+  return ended;
+}
+
+function memberOf(mission) {
+  return mission.owner || mission.executed_by || 'mission-lead';
+}
+
+// After the mission is saved: it starts in the campaign and holds its reserve.
+function recordCampaignMissionStarted(root, mission, reserve, deps = {}) {
+  if (!mission || !mission.campaign_id) return null;
+  try {
+    const store = storeFor(root, deps);
+    const actor = memberOf(mission);
+    store.append({
+      campaign_id: mission.campaign_id, type: 'mission_started', actor,
+      data: {
+        mission_id: mission.id, member: actor, objective: String(mission.objective || '').slice(0, 200),
+        ...(mission.runner && mission.runner !== 'auto' ? { engine: mission.runner } : {}),
+        ...(mission.model ? { model: mission.model } : {}),
+      },
+    });
+    if (reserve > 0) {
+      store.append({ campaign_id: mission.campaign_id, type: 'budget_reserved', actor, data: { mission_id: mission.id, amount_usd: reserve } });
+    }
+    return getCampaign(store, mission.campaign_id);
+  } catch (error) {
+    warn(`mission ${mission.id} started, but campaign ${mission.campaign_id} did not record it: ${error.message}`);
+    return null;
+  }
+}
+
+// Each tick writes a step into the campaign with the dollars its engine
+// reported, so the campaign's own log holds the spend: no lookback window, and
+// every runner counts, including ones that run without a roster pick.
+function recordCampaignTick(root, mission, usage = {}, deps = {}) {
+  if (!mission || !mission.campaign_id) return;
+  const data = { mission_id: mission.id };
+  if (typeof usage.cost_usd === 'number' && Number.isFinite(usage.cost_usd)) data.cost_usd = usage.cost_usd;
+  if (typeof usage.tokens === 'number' && Number.isFinite(usage.tokens)) data.tokens = usage.tokens;
+  // Which engine did the work: traces and per-engine cost need it.
+  if (typeof usage.engine === 'string' && usage.engine) data.engine = usage.engine;
+  try {
+    storeFor(root, deps).append({ campaign_id: mission.campaign_id, type: 'step', actor: memberOf(mission), data });
+  } catch (error) {
+    warn(`a tick of mission ${mission.id} was not recorded in campaign ${mission.campaign_id}: ${error.message}`);
+  }
+}
+
+// Dollars the mission's ticks reported, from the campaign's own steps. Ticks
+// without a dollar figure (engines that print tokens only) are counted so the
+// campaign can say spend is partial.
+function missionCost(root, missionId, deps = {}) {
+  const store = storeFor(root, deps);
+  const campaignId = store.campaignForMission(missionId);
+  const rows = campaignId
+    ? store.read(campaignId).filter((e) => e.type === 'step' && e.data.mission_id === missionId).map((e) => e.data)
+    : [];
+  let cents = 0;
+  let uncosted = 0;
+  // A cost that is not a real, non-negative number never blocks the mission's
+  // end; that tick counts as one without a dollar figure.
+  for (const row of rows) {
+    if (typeof row.cost_usd === 'number' && Number.isFinite(row.cost_usd) && row.cost_usd >= 0) cents += Math.floor(row.cost_usd * 100 + 0.5);
+    else uncosted += 1;
+  }
+  return { cost_usd: cents / 100, runs: rows.length, uncosted_runs: uncosted };
+}
+
+function outcomeFor(mission) {
+  return mission.status === 'complete' ? 'kept' : 'failed';
+}
+
+// Called from saveMission with the record before and after. Only the step
+// into a final status ends the mission in its campaign.
+function recordCampaignMissionEnded(root, previous, next, terminalStatuses, deps = {}) {
+  if (!next || !next.campaign_id || !terminalStatuses.has(next.status)) return null;
+  if (previous && terminalStatuses.has(previous.status)) return null;
+  try {
+    const store = storeFor(root, deps);
+    const view = getCampaign(store, next.campaign_id);
+    const known = view && !view.error && view.missions.find((m) => m.id === next.id);
+    if (known && known.status === 'ended') return null;
+    const cost = missionCost(root, next.id, deps);
+    const actor = memberOf(next);
+    store.append({
+      campaign_id: next.campaign_id, type: 'mission_ended', actor,
+      data: {
+        mission_id: next.id, outcome: outcomeFor(next), cost_usd: cost.cost_usd,
+        runs: cost.runs, uncosted_runs: cost.uncosted_runs, receipt_path: next.receipt_path || null,
+      },
+    });
+    const after = getCampaign(store, next.campaign_id);
+    return after ? { campaign: after, next: decide(after), cost } : null;
+  } catch (error) {
+    warn(`mission ${next.id} ended, but campaign ${next.campaign_id} did not record it: ${error.message}`);
+    return null;
+  }
+}
+
+module.exports = {
+  campaignGate,
+  reconcileCampaign,
+  reserveCampaignMission,
+  checkCampaignStart,
+  defaultReserve,
+  missionCost,
+  recordCampaignMissionEnded,
+  recordCampaignMissionStarted,
+  recordCampaignTick,
+};

package/lib/campaign-new.js

@@ -0,0 +1,251 @@
+// atris campaign new "<goal>": the owner's engine drafts a judge for the goal,
+// the CLI runs it to prove it fails today, shows the draft, and with --yes
+// starts the campaign. A judge is a script outside the model: exit 0 means the
+// goal is met. Asking goes through the read-only engine ask runner, the same
+// way the campaign loop asks the owner for missions.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { newCampaignId } = require('./campaign-store');
+
+const DEFAULT_BUDGET = 20;
+const DEFAULT_OWNER = 'mission-lead';
+const DRAFT_TIMEOUT_SECONDS = 10 * 60;
+const ASK_TIMEOUT_MS = 5 * 60 * 1000;
+const ATTEMPTS = 2;
+const MAX_SEATS = 3;
+const MAX_SCRIPT_BYTES = 8 * 1024;
+
+function money(value) {
+  return `$${Number(value).toFixed(2)}`;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+// Members with a MEMBER.md can take a seat.
+function teamMembers(root) {
+  const dir = path.join(root, 'atris', 'team');
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith('_') && fs.existsSync(path.join(dir, entry.name, 'MEMBER.md')))
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+// A few facts about the workspace so the judge uses commands that exist here.
+function workspaceHints(root) {
+  const lines = [];
+  try {
+    const entries = fs.readdirSync(root).filter((name) => !name.startsWith('.')).sort().slice(0, 30);
+    if (entries.length) lines.push(`Top-level files: ${entries.join(', ')}`);
+  } catch {}
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    const scripts = Object.entries(pkg.scripts || {}).slice(0, 15).map(([name, cmd]) => `  npm run ${name}: ${String(cmd).slice(0, 120)}`);
+    if (scripts.length) lines.push('package.json scripts:', ...scripts);
+  } catch {}
+  return lines;
+}
+
+function judgePrompt({ goal, members, hints, previous }) {
+  return [
+    'You write the judge for a new Atris campaign. Answer with JSON only.',
+    '',
+    `Goal: ${goal}`,
+    ...hints,
+    members.length ? `Members who can work on it: ${members.join(', ')}` : '',
+    '',
+    'A judge is a POSIX sh script that runs from the workspace root. It exits 0 only when the goal is met.',
+    'Today the goal is not met, so today it must exit non-zero.',
+    'Rules:',
+    '- Check real outcomes outside any model: run tests, count files, grep output, run a local command. Never ask a model whether it is done.',
+    '- Print graded progress so a person sees how close it is: a line "ℹ pass N" and a line "ℹ fail M" (checks met, checks not met).',
+    '- Read and run only; change nothing. Finish in under two minutes. Use only commands that exist here.',
+    previous ? `Your last draft did not work: ${previous}. Write a different judge.` : '',
+    '',
+    'Reply with one JSON object and nothing else:',
+    `{"title": "<short name, under 60 characters>", "judge_script": "<the whole sh script>", "why": "<one sentence: what it checks and why it fails today>", "seats": ["<up to ${MAX_SEATS} members from the list who should work on this>"]}`,
+  ].filter((line) => line !== '').join('\n');
+}
+
+function parseDraft(text, members) {
+  const match = String(text || '').match(/\{[\s\S]*\}/);
+  if (!match) return null;
+  let row;
+  try {
+    row = JSON.parse(match[0]);
+  } catch {
+    return null;
+  }
+  if (!row || typeof row.judge_script !== 'string' || !row.judge_script.trim()) return null;
+  if (Buffer.byteLength(row.judge_script) > MAX_SCRIPT_BYTES) return null;
+  const known = new Set(members);
+  const seats = Array.isArray(row.seats) ? [...new Set(row.seats.filter((s) => typeof s === 'string' && known.has(s)))].slice(0, MAX_SEATS) : [];
+  return {
+    title: typeof row.title === 'string' && row.title.trim() ? row.title.trim().slice(0, 80) : '',
+    script: row.judge_script.trim(),
+    why: typeof row.why === 'string' ? row.why.trim().slice(0, 300) : '',
+    seats,
+  };
+}
+
+// The owner's engine 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 new judge' }], { root, timeoutMs: ASK_TIMEOUT_MS });
+  return { text: (answer && answer.stdout) || '', engine, ok: Boolean(answer && answer.ok) };
+}
+
+function writeJudge(root, id, script) {
+  const rel = path.join('atris', 'campaigns', id, 'judge.sh');
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const body = script.startsWith('#!') ? script : `#!/bin/sh\n${script}`;
+  fs.writeFileSync(file, body.endsWith('\n') ? body : `${body}\n`, { mode: 0o755 });
+  return rel.split(path.sep).join('/');
+}
+
+// 126 and 127 mean the shell could not run a command; null means it hung or
+// never started. Those are broken judges, not failing ones.
+function brokenReading(reading) {
+  return reading.exit === null || reading.exit === undefined || reading.exit === 126 || reading.exit === 127;
+}
+
+// Ask, write, run; one retry with the reason when the draft passes today,
+// cannot run, or is not a script.
+async function draftJudge({ root, goal, owner, idFlag, timeout, ask, judge }) {
+  const members = teamMembers(root);
+  const hints = workspaceHints(root);
+  let previous = '';
+  let id = idFlag || '';
+  let last = null;
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+    const prompt = judgePrompt({ goal, members, hints, previous });
+    const answer = await ask(root, { id: id || 'new', owner, title: goal }, prompt);
+    const draft = parseDraft(answer.text, members);
+    if (!draft) {
+      previous = 'the reply was not one JSON object with a judge_script';
+      last = { error: `${owner}'s engine (${answer.engine || 'unknown'}) did not return a judge script` };
+      continue;
+    }
+    if (!draft.title) draft.title = goal.slice(0, 80);
+    if (!id) id = newCampaignId(draft.title);
+    const judgeFile = writeJudge(root, id, draft.script);
+    const command = `sh ${judgeFile}`;
+    const reading = await judge(command, timeout);
+    const result = { id, draft, judgeFile, command, reading, engine: answer.engine };
+    if (reading.passed) {
+      previous = `it passed today (${reading.summary || 'exit 0'}), so it cannot tell when the goal is met`;
+      last = { ...result, error: `the drafted judge already passes (${reading.summary || 'exit 0'}); a judge must fail first` };
+      continue;
+    }
+    if (brokenReading(reading)) {
+      previous = `it could not run (${reading.summary || `exit ${reading.exit}`})`;
+      last = { ...result, error: `the drafted judge could not run: ${reading.summary || `exit ${reading.exit}`}` };
+      continue;
+    }
+    return { ok: true, ...result };
+  }
+  if (id && !idFlag) fs.rmSync(path.join(root, 'atris', 'campaigns', id), { recursive: true, force: true });
+  return { ok: false, ...last };
+}
+
+function startArgs(result, { budget, owner, run }) {
+  const args = ['start', result.draft.title, '--judge', result.command, '--budget', String(budget), '--id', result.id, '--owner', owner];
+  for (const seat of result.draft.seats) args.push('--seat', seat);
+  if (run) args.push('--run');
+  return args;
+}
+
+function startCommand(result, options) {
+  const seats = result.draft.seats.map((seat) => ` --seat ${seat}`).join('');
+  return `atris campaign start ${shellQuote(result.draft.title)} --judge ${shellQuote(result.command)} --budget ${options.budget} --id ${result.id} --owner ${options.owner}${seats}`;
+}
+
+function renderDraft(result, options) {
+  const lines = [
+    `draft for: ${options.goal}`,
+    '',
+    `title     ${result.draft.title}`,
+    `judge     ${result.command}`,
+    `today     fails, as it should: ${result.reading.summary || `exit ${result.reading.exit}`}`,
+  ];
+  if (result.draft.why) lines.push(`checks    ${result.draft.why}`);
+  lines.push(`owner     ${options.owner}`);
+  lines.push(`seats     ${result.draft.seats.length ? result.draft.seats.join(', ') : 'none yet'}`);
+  lines.push(`budget    ${money(options.budget)}`);
+  lines.push('', `read or edit the judge: ${result.judgeFile}`);
+  return lines.join('\n');
+}
+
+function askAtTerminal(question) {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) return Promise.resolve(false);
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => rl.question(question, (answer) => {
+    rl.close();
+    resolve(/^y(es)?$/i.test(answer.trim()));
+  }));
+}
+
+// deps.start is the start verb; deps.ask replaces the owner's engine in tests.
+async function draftAndStart(args, ctx, deps = {}) {
+  const { readFlag } = require('./arg-parser');
+  const goal = String(deps.goal || '').trim();
+  if (!goal) return ctx.fail('say the goal: atris campaign new "<goal>" [--budget 20] [--owner <member>] [--yes] [--run]');
+  const budgetText = readFlag(args, '--budget', '');
+  const budget = budgetText ? Number(budgetText) : DEFAULT_BUDGET;
+  if (!(budget > 0)) return ctx.fail('--budget must be dollars above 0');
+  const owner = readFlag(args, '--owner', '') || DEFAULT_OWNER;
+  const timeout = Number(readFlag(args, '--timeout', '')) || DRAFT_TIMEOUT_SECONDS;
+  const options = { goal, budget, owner, run: args.includes('--run') };
+  if (!ctx.asJson) console.error(`asking ${owner}'s engine to draft a judge that fails today`);
+
+  const result = await draftJudge({
+    root: deps.root || process.cwd(), goal, owner, timeout,
+    idFlag: readFlag(args, '--id', ''),
+    ask: deps.ask || askOwner,
+    judge: ctx.judge,
+  });
+  if (!result.ok) {
+    if (ctx.asJson) {
+      console.log(JSON.stringify({ ok: false, error: result.error, draft: result.draft || null, reading: result.reading || null }));
+      return 1;
+    }
+    return ctx.fail(`${result.error}. Write the judge yourself: atris campaign start "<title>" --judge "<command that fails today>" --budget ${budget}`, 1);
+  }
+
+  const draft = { id: result.id, title: result.draft.title, judge: result.command, judge_file: result.judgeFile, why: result.draft.why, seats: result.draft.seats, owner, budget, engine: result.engine };
+  // Only a person at a terminal can say yes here; agents and pipes pass --yes.
+  const confirm = deps.confirm || askAtTerminal;
+  const canAsk = deps.confirm ? true : Boolean(process.stdin.isTTY && process.stderr.isTTY);
+  const asked = !args.includes('--yes') && !ctx.asJson && canAsk;
+  const yes = args.includes('--yes') || (asked && await confirm(`${renderDraft(result, options)}\n\nstart it${options.run ? ' and run it' : ''}? [y/N] `));
+  if (!yes) {
+    const command = startCommand(result, options);
+    const shown = asked ? 'not started.' : renderDraft(result, options);
+    ctx.out(`${shown}\nstart it:  ${command}\n(or run this again with --yes)`,
+      { ok: true, action: 'campaign_drafted', draft, reading: result.reading, start_command: command });
+    return 0;
+  }
+  // Start with the reading already taken, so the judge does not run twice.
+  if (!ctx.asJson && args.includes('--yes')) console.log(renderDraft(result, options));
+  const startCtx = {
+    ...ctx,
+    judge: async () => result.reading,
+    out: (human, json) => ctx.out(human, { ...json, draft }),
+  };
+  return deps.start(startArgs(result, options), startCtx);
+}
+
+module.exports = { draftAndStart, judgePrompt, parseDraft };

package/lib/campaign-protect.js

@@ -0,0 +1,75 @@
+// Protected paths: files a campaign's agents must not touch, like the judge's
+// questions. Start saves the paths and the commit they started from in the
+// campaign folder beside the campaign store, outside the checkout, so agents
+// cannot edit the list; guard names any of them changed since, committed or not.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function git(root, args) {
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  return { ok: result.status === 0, out: (result.stdout || '').trim(), err: (result.stderr || '').trim() };
+}
+
+function checkoutTop(root) {
+  const top = git(root, ['rev-parse', '--show-toplevel']);
+  return top.ok ? fs.realpathSync(top.out) : null;
+}
+
+// The folder holding every campaign's own files, beside the campaign store.
+function campaignHome(store) {
+  const { campaignDbPath } = require('./campaign-store');
+  return path.dirname((store && store.path) || campaignDbPath());
+}
+
+function protectFile(home, campaignId) {
+  return path.join(home, 'campaigns', campaignId, 'protect.json');
+}
+
+// The commit and checkout-relative paths to save, or an error in plain words.
+function planProtect(root, paths) {
+  const topDir = checkoutTop(root);
+  if (!topDir) return { error: '--protect needs a git checkout' };
+  const head = git(root, ['rev-parse', 'HEAD']);
+  if (!head.ok) return { error: '--protect needs a checkout with at least one commit' };
+  const here = fs.realpathSync(root);
+  const rels = [];
+  for (const given of paths) {
+    const rel = path.relative(topDir, path.resolve(here, given)).split(path.sep).join('/');
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return { error: `--protect ${given} is not inside this checkout` };
+    if (!rels.includes(rel)) rels.push(rel);
+  }
+  return { paths: rels, base_commit: head.out };
+}
+
+function saveProtect(home, campaignId, plan) {
+  const file = protectFile(home, campaignId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify({ paths: plan.paths, base_commit: plan.base_commit }, null, 2)}\n`);
+  return file;
+}
+
+function readProtect(home, campaignId) {
+  try {
+    return JSON.parse(fs.readFileSync(protectFile(home, campaignId), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Protected paths that differ from the base commit: committed, staged,
+// unstaged, deleted, or new and untracked. Root is the checkout top, since
+// the saved paths are relative to it.
+function changedProtected(root, saved) {
+  const spec = ['--', ...saved.paths.map((rel) => `:(top,literal)${rel}`)];
+  const diff = git(root, ['diff', '--name-only', saved.base_commit, ...spec]);
+  if (!diff.ok) return { error: `cannot compare with ${String(saved.base_commit).slice(0, 12)}: ${diff.err || 'git diff failed'}` };
+  const untracked = git(root, ['ls-files', '--others', '--exclude-standard', '--full-name', ...spec]);
+  const changed = [...diff.out.split('\n'), ...untracked.out.split('\n')].filter(Boolean);
+  return { changed: [...new Set(changed)].sort() };
+}
+
+module.exports = { campaignHome, changedProtected, checkoutTop, planProtect, protectFile, readProtect, saveProtect };