atris 3.70.0 → 3.71.0

package/lib/campaign-store.js

@@ -0,0 +1,380 @@
+// Campaign store: append-only events behind one small interface, with a
+// SQLite adapter (one file per workspace) and an in-memory adapter for tests.
+//
+// Built so Campaign does not inherit the mission ledger's problems
+// (atris/features/campaign/build.md Phase -1): every append is one
+// transaction, events carry a unique id plus a per-origin sequence, writers
+// can demand an expected version, and a corrupt row fails closed.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+// task-db installs the narrow node:sqlite warning filter and owns the shared
+// busy retry; load it before node:sqlite so the filter is in place.
+const { withBusyRetry } = require('./task-db');
+const { DatabaseSync } = require('node:sqlite');
+const { mainCheckoutRoot } = require('./engine-registry');
+const { validateEvent } = require('./campaign-schema');
+const { fold } = require('./campaign-core');
+
+// Any event naming a mission ties that mission to its campaign.
+function missionIdOf(event) {
+  return event.data && typeof event.data.mission_id === 'string' && event.data.mission_id ? event.data.mission_id : null;
+}
+
+function storeError(code, message) {
+  const error = new Error(message || code);
+  error.code = code;
+  return error;
+}
+
+// The checkout holding root, so a call from a subfolder finds the same store.
+function checkoutRoot(root) {
+  let dir = path.resolve(root);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(root);
+    dir = parent;
+  }
+}
+
+function campaignDbPath(root = process.cwd()) {
+  if (process.env.ATRIS_CAMPAIGN_DB) return process.env.ATRIS_CAMPAIGN_DB;
+  const checkout = checkoutRoot(root);
+  const home = mainCheckoutRoot(checkout) || checkout;
+  return path.join(home, '.atris', 'state', 'atris.db');
+}
+
+// Files a campaign owns (like a copied judge script) live beside the store.
+function campaignFolder(campaignId, root = process.cwd()) {
+  return path.join(path.dirname(campaignDbPath(root)), 'campaigns', campaignId);
+}
+
+function newCampaignId(title = '') {
+  const slug = String(title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24).replace(/-+$/, '');
+  const suffix = crypto.randomBytes(2).toString('hex');
+  return slug ? `cmp-${slug}-${suffix}` : `cmp-${suffix}`;
+}
+
+function newOrigin() {
+  return `c-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+// Fill the fields the store owns, then validate the whole event.
+function completeEvent(input, origin, seq, now) {
+  const event = {
+    id: input.id || `evt-${crypto.randomUUID()}`,
+    campaign_id: input.campaign_id,
+    type: input.type,
+    at: input.at || now(),
+    origin,
+    seq,
+    actor: input.actor,
+    data: input.data || {},
+  };
+  const check = validateEvent(event);
+  if (!check.ok) throw storeError('invalid_event', `invalid ${input.type || 'event'}: ${check.errors.join(', ')}`);
+  return event;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS campaigns (
+  id TEXT PRIMARY KEY,
+  created_at TEXT NOT NULL,
+  origin TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS events (
+  pos INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  campaign_id TEXT NOT NULL,
+  origin TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  type TEXT NOT NULL,
+  at TEXT NOT NULL,
+  actor TEXT NOT NULL,
+  data TEXT NOT NULL,
+  UNIQUE (origin, seq)
+);
+CREATE INDEX IF NOT EXISTS events_by_campaign ON events (campaign_id, pos);
+CREATE TABLE IF NOT EXISTS missions (
+  mission_id TEXT PRIMARY KEY,
+  campaign_id TEXT NOT NULL
+);
+`;
+
+function createSqliteStore(dbPath, options = {}) {
+  const now = options.now || (() => new Date().toISOString());
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  let readOnly = false;
+  let db;
+  try {
+    fs.accessSync(fs.existsSync(dbPath) ? dbPath : path.dirname(dbPath), fs.constants.W_OK);
+    db = new DatabaseSync(dbPath);
+    withBusyRetry(() => db.exec('PRAGMA journal_mode = WAL'));
+    db.exec('PRAGMA busy_timeout = 30000');
+    withBusyRetry(() => db.exec(SCHEMA));
+    withBusyRetry(() => db.exec('PRAGMA user_version = 1'));
+  } catch (error) {
+    // A store someone can only read still shows its campaigns; writes say why they cannot.
+    if (!fs.existsSync(dbPath)) throw error;
+    if (db) try { db.close(); } catch {}
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    readOnly = true;
+  }
+
+  const tx = (fn) => {
+    if (readOnly) throw storeError('read_only', `the campaign store at ${dbPath} is read-only`);
+    withBusyRetry(() => db.exec('BEGIN IMMEDIATE'));
+    try {
+      const result = fn();
+      db.exec('COMMIT');
+      return result;
+    } catch (error) {
+      try { db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  };
+
+  const origin = readOnly ? ((db.prepare("SELECT value FROM meta WHERE key = 'origin'").get() || {}).value || 'read-only') : tx(() => {
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'origin'").get();
+    if (row) return row.value;
+    const value = options.origin || newOrigin();
+    db.prepare("INSERT INTO meta (key, value) VALUES ('origin', ?)").run(value);
+    return value;
+  });
+
+  const linkMission = (event) => {
+    const missionId = missionIdOf(event);
+    if (!missionId) return;
+    const row = db.prepare('SELECT campaign_id FROM missions WHERE mission_id = ?').get(missionId);
+    if (row && row.campaign_id !== event.campaign_id) {
+      throw storeError('mission_in_other_campaign', `mission ${missionId} already belongs to ${row.campaign_id}`);
+    }
+    if (!row) db.prepare('INSERT INTO missions (mission_id, campaign_id) VALUES (?, ?)').run(missionId, event.campaign_id);
+  };
+
+  const insert = (event) => {
+    db.prepare('INSERT INTO events (id, campaign_id, origin, seq, type, at, actor, data) VALUES (?, ?, ?, ?, ?, ?, ?, ?)')
+      .run(event.id, event.campaign_id, event.origin, event.seq, event.type, event.at, event.actor, JSON.stringify(event.data));
+  };
+
+  const count = (campaignId) => db.prepare('SELECT COUNT(*) AS n FROM events WHERE campaign_id = ?').get(campaignId).n;
+
+  const readEvents = (campaignId) => db.prepare('SELECT * FROM events WHERE campaign_id = ? ORDER BY pos').all(campaignId).map((row) => {
+    let data;
+    try {
+      data = JSON.parse(row.data);
+    } catch {
+      throw storeError('corrupt_event', `event ${row.id} in ${campaignId} has unreadable data`);
+    }
+    return {
+      id: row.id, campaign_id: row.campaign_id, type: row.type, at: row.at,
+      origin: row.origin, seq: row.seq, actor: row.actor, data,
+    };
+  });
+
+  return {
+    kind: 'sqlite',
+    path: dbPath,
+    origin,
+    readOnly,
+
+    // Write a new event from this computer. options.expectedVersion is the
+    // event count the writer last read; a mismatch refuses the write.
+    append(input, appendOptions = {}) {
+      return tx(() => {
+        const campaignId = input.campaign_id;
+        if (appendOptions.expectedVersion !== undefined && count(campaignId) !== appendOptions.expectedVersion) {
+          throw storeError('version_conflict', `campaign ${campaignId} changed since version ${appendOptions.expectedVersion}`);
+        }
+        const exists = db.prepare('SELECT 1 FROM campaigns WHERE id = ?').get(campaignId);
+        if (input.type === 'campaign_started' && exists) throw storeError('campaign_exists', `campaign ${campaignId} already started`);
+        if (input.type !== 'campaign_started' && !exists) throw storeError('unknown_campaign', `no campaign ${campaignId}`);
+        // A check that must see the campaign as it is at the moment of the
+        // write, such as a budget reservation, runs inside this transaction.
+        if (appendOptions.check) appendOptions.check(fold(readEvents(campaignId)));
+        const last = db.prepare('SELECT MAX(seq) AS seq FROM events WHERE origin = ?').get(origin).seq || 0;
+        const event = completeEvent(input, origin, last + 1, now);
+        if (input.type === 'campaign_started') {
+          db.prepare('INSERT INTO campaigns (id, created_at, origin) VALUES (?, ?, ?)').run(campaignId, event.at, origin);
+        }
+        linkMission(event);
+        insert(event);
+        return event;
+      });
+    },
+
+    // Take an event written elsewhere (sync). Returns false for one already
+    // held; a different event claiming the same origin and seq is refused.
+    ingest(event) {
+      const check = validateEvent(event);
+      if (!check.ok) throw storeError('invalid_event', `invalid ${event && event.type}: ${check.errors.join(', ')}`);
+      return tx(() => {
+        if (db.prepare('SELECT 1 FROM events WHERE id = ?').get(event.id)) return false;
+        const clash = db.prepare('SELECT id FROM events WHERE origin = ? AND seq = ?').get(event.origin, event.seq);
+        if (clash) throw storeError('seq_conflict', `origin ${event.origin} seq ${event.seq} is already ${clash.id}`);
+        if (event.type === 'campaign_started') {
+          db.prepare('INSERT OR IGNORE INTO campaigns (id, created_at, origin) VALUES (?, ?, ?)').run(event.campaign_id, event.at, event.origin);
+        }
+        linkMission(event);
+        insert(event);
+        return true;
+      });
+    },
+
+    read: readEvents,
+
+    version: count,
+
+    campaignIds() {
+      return db.prepare('SELECT id FROM campaigns ORDER BY created_at, id').all().map((row) => row.id);
+    },
+
+    campaignForMission(missionId) {
+      const row = db.prepare('SELECT campaign_id FROM missions WHERE mission_id = ?').get(missionId);
+      return row ? row.campaign_id : null;
+    },
+
+    // Small notes the store keeps beside the events, such as a campaign's
+    // cloud link and the last cloud seq pulled (lib/campaign-sync.js).
+    getMeta(key) {
+      const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+      return row ? row.value : null;
+    },
+
+    setMeta(key, value) {
+      tx(() => db.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, String(value)));
+    },
+
+    close() {
+      db.close();
+    },
+  };
+}
+
+function createMemoryStore(options = {}) {
+  const now = options.now || (() => new Date().toISOString());
+  const origin = options.origin || newOrigin();
+  const events = [];
+  const campaigns = new Map();
+  const missions = new Map();
+  const seqByOrigin = new Map();
+  const meta = new Map();
+
+  const clone = (value) => JSON.parse(JSON.stringify(value));
+  const count = (campaignId) => events.filter((e) => e.campaign_id === campaignId).length;
+  const checkMission = (event) => {
+    const missionId = missionIdOf(event);
+    if (!missionId) return;
+    const owner = missions.get(missionId);
+    if (owner && owner !== event.campaign_id) {
+      throw storeError('mission_in_other_campaign', `mission ${missionId} already belongs to ${owner}`);
+    }
+  };
+  const commit = (event) => {
+    const missionId = missionIdOf(event);
+    if (missionId && !missions.has(missionId)) missions.set(missionId, event.campaign_id);
+    seqByOrigin.set(event.origin, Math.max(seqByOrigin.get(event.origin) || 0, event.seq));
+    events.push(clone(event));
+  };
+
+  return {
+    kind: 'memory',
+    path: null,
+    origin,
+    append(input, appendOptions = {}) {
+      const campaignId = input.campaign_id;
+      if (appendOptions.expectedVersion !== undefined && count(campaignId) !== appendOptions.expectedVersion) {
+        throw storeError('version_conflict', `campaign ${campaignId} changed since version ${appendOptions.expectedVersion}`);
+      }
+      if (input.type === 'campaign_started' && campaigns.has(campaignId)) throw storeError('campaign_exists', `campaign ${campaignId} already started`);
+      if (input.type !== 'campaign_started' && !campaigns.has(campaignId)) throw storeError('unknown_campaign', `no campaign ${campaignId}`);
+      if (appendOptions.check) appendOptions.check(fold(events.filter((e) => e.campaign_id === campaignId)));
+      const event = completeEvent(input, origin, (seqByOrigin.get(origin) || 0) + 1, now);
+      checkMission(event);
+      if (input.type === 'campaign_started') campaigns.set(campaignId, event.at);
+      commit(event);
+      return clone(event);
+    },
+    ingest(event) {
+      const check = validateEvent(event);
+      if (!check.ok) throw storeError('invalid_event', `invalid ${event && event.type}: ${check.errors.join(', ')}`);
+      if (events.some((e) => e.id === event.id)) return false;
+      const clash = events.find((e) => e.origin === event.origin && e.seq === event.seq);
+      if (clash) throw storeError('seq_conflict', `origin ${event.origin} seq ${event.seq} is already ${clash.id}`);
+      checkMission(event);
+      if (event.type === 'campaign_started' && !campaigns.has(event.campaign_id)) campaigns.set(event.campaign_id, event.at);
+      commit(event);
+      return true;
+    },
+    read(campaignId) {
+      return events.filter((e) => e.campaign_id === campaignId).map(clone);
+    },
+    version: count,
+    campaignIds() {
+      return [...campaigns.entries()].sort((a, b) => (a[1] === b[1] ? (a[0] < b[0] ? -1 : 1) : (a[1] < b[1] ? -1 : 1))).map(([id]) => id);
+    },
+    campaignForMission(missionId) {
+      return missions.get(missionId) || null;
+    },
+    getMeta(key) {
+      return meta.has(key) ? meta.get(key) : null;
+    },
+    setMeta(key, value) {
+      meta.set(key, String(value));
+    },
+    close() {},
+  };
+}
+
+const openStores = new Map();
+
+function openCampaignStore(root = process.cwd()) {
+  const dbPath = campaignDbPath(root);
+  if (!openStores.has(dbPath)) openStores.set(dbPath, createSqliteStore(dbPath));
+  return openStores.get(dbPath);
+}
+
+function closeCampaignStores() {
+  for (const store of openStores.values()) store.close();
+  openStores.clear();
+}
+
+function getCampaign(storeOrRoot, campaignId) {
+  const store = typeof storeOrRoot === 'string' ? openCampaignStore(storeOrRoot) : storeOrRoot;
+  const events = store.read(campaignId);
+  if (events.length === 0) return null;
+  return fold(events);
+}
+
+// One unreadable campaign never hides the others: it comes back as { id, error }.
+function listCampaigns(storeOrRoot) {
+  const store = typeof storeOrRoot === 'string' ? openCampaignStore(storeOrRoot) : storeOrRoot;
+  return store.campaignIds().map((id) => {
+    try {
+      const view = fold(store.read(id));
+      return view.error ? { id, error: view.error } : view;
+    } catch (error) {
+      return { id, error: error.code || error.message };
+    }
+  });
+}
+
+module.exports = {
+  campaignDbPath,
+  campaignFolder,
+  closeCampaignStores,
+  createMemoryStore,
+  createSqliteStore,
+  getCampaign,
+  listCampaigns,
+  newCampaignId,
+  openCampaignStore,
+};

package/lib/campaign-sync.js

@@ -0,0 +1,302 @@
+// Campaign cloud sync: a campaign on this computer and its copy in the Atris
+// cloud trade events by id, so web and iOS show it and a person's answer from
+// a phone reaches a running loop. Contract: atris/features/campaign/api.md.
+//
+// Push sends the events the cloud lacks; pull ingests the ones this computer
+// lacks (answers and actions from screens). Both are idempotent by event id.
+// A 403 or 409 is the cloud saying no on purpose, so it is reported plainly
+// and never retried.
+//
+// A computer that has never seen the campaign (an Atris cloud computer told to
+// run it) pulls the whole log first, campaign_started before anything else.
+
+'use strict';
+
+const fs = require('fs');
+const { apiRequestJson, getApiBaseUrl } = require('../utils/api');
+const { loadCredentials } = require('../utils/auth');
+const { CAMPAIGN_ID } = require('./campaign-schema');
+
+const PUSH_BATCH = 200;
+const PULL_LIMIT = 500;
+const REQUEST_TIMEOUT_MS = 15000;
+// Only a person's screen may send these to the cloud (api.md, Write). A local
+// copy stays local; a person answers on the phone, the web, or with
+// atris campaign answer, which goes to the cloud for a synced campaign.
+const PERSON_ONLY = new Set(['ask_answered', 'budget_added', 'done']);
+
+const metaKey = (campaignId) => `campaign_sync:${campaignId}`;
+
+function readState(store, campaignId) {
+  const raw = store.getMeta(metaKey(campaignId));
+  if (!raw) return null;
+  try {
+    const state = JSON.parse(raw);
+    return state && typeof state === 'object' ? state : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(store, campaignId, state) {
+  store.setMeta(metaKey(campaignId), JSON.stringify(state));
+}
+
+// The cloud link for a campaign, or null when it has never been synced.
+function cloudLink(store, campaignId) {
+  const state = readState(store, campaignId);
+  return state && state.link ? state : null;
+}
+
+function plainError(response) {
+  const status = response && response.status;
+  const said = response && (response.error || (response.data && (response.data.error || response.data.detail)));
+  if (!status) return `could not reach the Atris cloud${said ? ` (${said})` : ''}`;
+  if (status === 401) return 'the Atris cloud did not accept your login. run: atris login';
+  if (status === 403) return `the Atris cloud refused this (403)${said ? `: ${said}` : ''}`;
+  if (status === 409) return `the Atris cloud holds a different event at the same place (409)${said ? `: ${said}` : ''}`;
+  return `the Atris cloud answered ${status}${said ? `: ${said}` : ''}`;
+}
+
+function failure(result, response) {
+  return { ...result, ok: false, status: (response && response.status) || 0, error: plainError(response) };
+}
+
+function tokenFrom(load) {
+  try {
+    const credentials = load();
+    const token = credentials && String(credentials.token || '').trim();
+    return token || null;
+  } catch {
+    return null;
+  }
+}
+
+// Every event the cloud holds for a campaign this computer has never seen,
+// ingested with campaign_started first. Returns { ok, pulled, last_seq } or
+// { ok: false, status, error } with what exactly went wrong.
+async function pullWholeCampaign(store, campaignId, call) {
+  const base = `/campaigns/${encodeURIComponent(campaignId)}`;
+  const incoming = [];
+  let after = 0;
+  for (;;) {
+    const response = await call(`${base}/events?after=${after}&limit=${PULL_LIMIT}`, { method: 'GET' });
+    if (response && response.status === 404) {
+      return { ok: false, status: 404, error: `the Atris cloud has no campaign ${campaignId} for this login, so there is nothing to pull. Start it with --cloud on the computer that has it, or check the login (atris whoami)` };
+    }
+    if (!response || !response.ok) return { ok: false, status: (response && response.status) || 0, error: plainError(response) };
+    const data = response.data || {};
+    const page = (Array.isArray(data.events) ? data.events : []).filter((event) => event && event.campaign_id === campaignId);
+    incoming.push(...page);
+    const seq = Number(data.last_event_seq);
+    if (Number.isInteger(seq) && seq > after) after = seq;
+    if (!Array.isArray(data.events) || data.events.length < PULL_LIMIT) break;
+  }
+  if (!incoming.length) {
+    return { ok: false, status: 404, error: `the Atris cloud has no events for ${campaignId}, so there is nothing to pull. Start it with --cloud on the computer that has it` };
+  }
+  const starts = incoming.filter((event) => event.type === 'campaign_started');
+  if (starts.length !== 1) {
+    return { ok: false, status: 0, error: `the cloud copy of ${campaignId} has ${starts.length} campaign_started events, not 1, so this computer cannot start it` };
+  }
+  let pulled = 0;
+  for (const event of [starts[0], ...incoming.filter((e) => e !== starts[0])]) {
+    try {
+      if (store.ingest(event)) pulled += 1;
+    } catch (error) {
+      return { ok: false, status: 0, error: `cloud event ${event.id} could not be taken in: ${error.message}` };
+    }
+  }
+  return { ok: true, pulled, last_seq: after };
+}
+
+// An Atris cloud computer running a campaign holds a token for that one
+// campaign's sync routes, in a file the backend placed (0600). The path comes
+// in ATRIS_CAMPAIGN_TOKEN_FILE. It is read once and taken out of the
+// environment, so no mission, engine, or child CLI started here inherits it.
+const CAMPAIGN_TOKEN_ENV = 'ATRIS_CAMPAIGN_TOKEN_FILE';
+
+function takeCampaignToken(env = process.env, read = fs.readFileSync) {
+  if (!env || env[CAMPAIGN_TOKEN_ENV] === undefined) return null;
+  const file = String(env[CAMPAIGN_TOKEN_ENV]).trim();
+  delete env[CAMPAIGN_TOKEN_ENV];
+  try {
+    const body = JSON.parse(read(file, 'utf8'));
+    const token = body && typeof body.token === 'string' ? body.token.trim() : '';
+    if (token && CAMPAIGN_ID.test(String(body.campaign_id || ''))) return { campaign_id: body.campaign_id, token };
+  } catch {}
+  return { error: `the campaign token file ${file} could not be read` };
+}
+
+// The token a sync of this campaign uses: the campaign's own token when this
+// computer holds one (never the login, even if that fails), else the login.
+function syncToken(campaignId, deps) {
+  const scoped = deps.campaignToken;
+  if (scoped) {
+    if (scoped.error) return { error: scoped.error };
+    if (scoped.campaign_id !== campaignId) return { error: `the campaign token here is for ${scoped.campaign_id}, not ${campaignId}` };
+    return { token: scoped.token };
+  }
+  const token = tokenFrom(deps.loadCredentials || loadCredentials);
+  return token ? { token } : { error: 'not logged in to Atris. run: atris login' };
+}
+
+// One sync of one campaign. Never throws for cloud trouble; returns
+// { ok, pushed, duplicates, held, pulled, last_seq, link, error?, status? }.
+async function syncCampaign(store, campaignId, deps = {}) {
+  const request = deps.apiRequestJson || apiRequestJson;
+  const now = deps.now || (() => new Date().toISOString());
+  const base = `/campaigns/${encodeURIComponent(campaignId)}`;
+  const state = readState(store, campaignId) || { pushed: 0, last_seq: 0 };
+  // A campaign this computer has never seen is linked only once its pull
+  // works, so a wrong id leaves nothing behind.
+  const firstPull = store.read(campaignId).length === 0;
+  const link = state.link || { url: `${getApiBaseUrl()}${base}`, linked_at: now() };
+  if (!state.link && !firstPull) {
+    // Linked from the first try, so a computer that is offline now keeps
+    // trying on every later run step.
+    state.link = link;
+    writeState(store, campaignId, state);
+  }
+  const result = { ok: true, campaign_id: campaignId, pushed: 0, duplicates: 0, held: 0, pulled: 0, last_seq: state.last_seq || 0, link: link.url };
+
+  const { token, error: tokenError } = syncToken(campaignId, deps);
+  if (!token) return { ...result, ok: false, status: 401, error: tokenError };
+  const call = (path, options) => request(path, { token, retries: 0, timeoutMs: REQUEST_TIMEOUT_MS, ...options });
+
+  if (firstPull) {
+    const whole = await pullWholeCampaign(store, campaignId, call);
+    if (!whole.ok) return { ...result, ok: false, status: whole.status, error: whole.error, first_pull: true };
+    // Everything here came from the cloud, so none of it needs pushing back.
+    state.link = link;
+    state.pushed = store.read(campaignId).length;
+    state.last_seq = whole.last_seq;
+    writeState(store, campaignId, state);
+    result.pulled = whole.pulled;
+    result.first_pull = true;
+  }
+
+  // Push: every local event past the last one the cloud is known to hold.
+  const events = store.read(campaignId);
+  if (!events.length) return { ...result, ok: false, error: `no campaign ${campaignId} on this computer` };
+  const known = new Set();
+  const outgoing = [];
+  for (const event of events.slice(state.pushed || 0)) {
+    if (event.origin === 'cloud') { known.add(event.id); continue; }
+    if (PERSON_ONLY.has(event.type)) { result.held += 1; known.add(event.id); continue; }
+    outgoing.push(event);
+  }
+  for (let i = 0; i < outgoing.length; i += PUSH_BATCH) {
+    const batch = outgoing.slice(i, i + PUSH_BATCH);
+    const response = await call(`${base}/events`, { method: 'POST', body: { events: batch } });
+    if (!response || !response.ok) return failure(result, response);
+    const data = response.data || {};
+    result.pushed += Number(data.accepted) || 0;
+    result.duplicates += Number(data.duplicates) || 0;
+    for (const event of batch) known.add(event.id);
+  }
+
+  // Pull: everything the cloud took in after the last seq seen here.
+  let after = state.last_seq || 0;
+  for (;;) {
+    const response = await call(`${base}/events?after=${after}&limit=${PULL_LIMIT}`, { method: 'GET' });
+    if (!response || !response.ok) {
+      state.pushed = advance(events, state.pushed || 0, known);
+      writeState(store, campaignId, state);
+      return failure(result, response);
+    }
+    const data = response.data || {};
+    const incoming = Array.isArray(data.events) ? data.events : [];
+    for (const event of incoming) {
+      if (!event || event.campaign_id !== campaignId) continue;
+      try {
+        if (store.ingest(event)) result.pulled += 1;
+      } catch (error) {
+        state.pushed = advance(events, state.pushed || 0, known);
+        writeState(store, campaignId, state);
+        return { ...result, ok: false, status: 0, error: `a cloud event could not be taken in: ${error.message}` };
+      }
+      known.add(event.id);
+    }
+    const seq = Number(data.last_event_seq);
+    if (Number.isInteger(seq) && seq > after) after = seq;
+    state.last_seq = after;
+    if (incoming.length < PULL_LIMIT) break;
+  }
+  result.last_seq = after;
+
+  // Everything the cloud now holds, including what was just pulled.
+  state.pushed = advance(store.read(campaignId), state.pushed || 0, known);
+  state.synced_at = now();
+  writeState(store, campaignId, state);
+  return result;
+}
+
+// Move the pushed mark forward over events the cloud is known to hold, and
+// stop at the first one it may not have, so an event written mid-sync is sent
+// next time.
+function advance(events, from, known) {
+  let mark = from;
+  while (mark < events.length && known.has(events[mark].id)) mark += 1;
+  return mark;
+}
+
+// A person's answer or action on a synced campaign goes through the cloud's
+// person routes, then comes back down by pull. Returns { ok, error?, status? }.
+async function sendPersonAction(store, campaignId, action, deps = {}) {
+  const request = deps.apiRequestJson || apiRequestJson;
+  const token = tokenFrom(deps.loadCredentials || loadCredentials);
+  if (!token) return { ok: false, status: 401, error: 'not logged in to Atris. run: atris login' };
+  const base = `/campaigns/${encodeURIComponent(campaignId)}`;
+  const route = action.ask_id ? `${base}/asks/${encodeURIComponent(action.ask_id)}/answer` : `${base}/actions`;
+  const body = action.ask_id ? { answer: action.answer } : { action: action.action, amount_usd: action.amount_usd };
+  const response = await request(route, { method: 'POST', token, retries: 0, timeoutMs: REQUEST_TIMEOUT_MS, body });
+  if (!response || !response.ok) return failure({}, response);
+  const synced = await syncCampaign(store, campaignId, deps);
+  return synced.ok ? { ok: true, sync: synced } : { ok: true, sync: synced, warning: synced.error };
+}
+
+// Ask the cloud to run a campaign on the person's Atris computer
+// (POST /campaigns/<id>/run-in-cloud), or read how that run is going
+// (GET /campaigns/<id>/cloud-run). Returns { ok, data } or { ok: false, status, error }.
+const CLOUD_RUN_TIMEOUT_MS = 120000; // waking a computer can take most of a minute
+
+async function runInCloud(campaignId, body, deps = {}) {
+  const request = deps.apiRequestJson || apiRequestJson;
+  const token = tokenFrom(deps.loadCredentials || loadCredentials);
+  if (!token) return { ok: false, status: 401, error: 'not logged in to Atris. run: atris login' };
+  const response = await request(`/campaigns/${encodeURIComponent(campaignId)}/run-in-cloud`, {
+    method: 'POST', token, retries: 0, timeoutMs: CLOUD_RUN_TIMEOUT_MS, body,
+  });
+  if (!response || !response.ok) return cloudRunFailure(response);
+  return { ok: true, data: response.data || {} };
+}
+
+async function cloudRunStatus(campaignId, deps = {}) {
+  const request = deps.apiRequestJson || apiRequestJson;
+  const token = tokenFrom(deps.loadCredentials || loadCredentials);
+  if (!token) return { ok: false, status: 401, error: 'not logged in to Atris. run: atris login' };
+  const response = await request(`/campaigns/${encodeURIComponent(campaignId)}/cloud-run`, {
+    method: 'GET', token, retries: 0, timeoutMs: REQUEST_TIMEOUT_MS,
+  });
+  if (!response || !response.ok) return cloudRunFailure(response);
+  return { ok: true, data: response.data || {} };
+}
+
+// The run routes answer in plain sentences, so pass the cloud's own words on.
+function cloudRunFailure(response) {
+  const status = (response && response.status) || 0;
+  const said = response && ((response.data && (response.data.error || response.data.detail)) || response.error);
+  if (!status) return { ok: false, status, error: plainError(response) };
+  if (status === 401) return { ok: false, status, error: plainError(response) };
+  if (status === 404 && !(response.data && response.data.error)) {
+    return { ok: false, status, error: 'the Atris cloud does not run campaigns on computers yet (404). Try again after the next backend deploy' };
+  }
+  return { ok: false, status, error: typeof said === 'string' && said ? said : plainError(response) };
+}
+
+// What this CLI can do for an Atris cloud computer; the backend checks it
+// (atris campaign features --json) before it starts a cloud run here.
+const CLOUD_FEATURES = ['cloud_pull', 'campaign_token_file'];
+
+module.exports = { CAMPAIGN_TOKEN_ENV, CLOUD_FEATURES, cloudLink, cloudRunStatus, runInCloud, sendPersonAction, syncCampaign, takeCampaignToken };