agentlinkops 0.5.0

package/cli/delivery.js

@@ -0,0 +1,67 @@
+// Signed DP-0004 notifications wake the existing authenticated pull; they are never facts.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { readFile, appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { cloudObservationRows } from './sync.js';
+import { readObservations, appendObservations, writeObservations, observationKey, dedupeObservations } from './mirror.js';
+
+export function verifyDelivery({ body, headers, secret, workspaceId, now = Date.now() }) {
+  if (typeof secret !== 'string' || !secret || !workspaceId) throw new Error('delivery requires secret and workspace identity');
+  if (typeof body !== 'string' || Buffer.byteLength(body) > 262144) throw new Error('invalid delivery body');
+  const h = new Headers(headers);
+  // DP-0029: deliveries carry AgentLinkOps-* headers, and Linktrail-* alongside them for the
+  // compatibility window. Either set verifies; the new one is read first.
+  const header = name => h.get(`AgentLinkOps-${name}`) ?? h.get(`Linktrail-${name}`);
+  const timestamp = header('Timestamp');
+  if (!/^\d+$/.test(timestamp ?? '') || Math.abs(now / 1000 - Number(timestamp)) > 300) throw new Error('expired or invalid delivery timestamp');
+  const expected = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest();
+  const valid = (header('Signature') ?? '').split(/\s+/).some(part => {
+    if (!/^v1=[a-f0-9]{64}$/.test(part)) return false;
+    return timingSafeEqual(expected, Buffer.from(part.slice(3), 'hex'));
+  });
+  if (!valid) throw new Error('invalid delivery signature');
+  const payload = JSON.parse(body);
+  if (payload.v !== 1 || payload.workspace_id !== workspaceId || !['events', 'target_events'].includes(payload.feed)
+    || !payload.id || !Number.isSafeInteger(payload.sequence) || payload.sequence < 1) throw new Error('invalid delivery identity');
+  return payload;
+}
+
+export async function appendEventHistory(path, events) {
+  let text = '';
+  try { text = await readFile(path, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const key = event => {
+    if (!event.id) throw new Error('event missing stable identity');
+    // Event IDs have feed-specific prefixes; include explicit feed when present.
+    return `${event.feed ?? (event.target_id ? 'target_events' : 'events')}|${event.id}`;
+  };
+  const seen = new Set(text.split('\n').filter(line => line.trim()).map(line => key(JSON.parse(line))));
+  const fresh = events.filter(event => { const id = key(event); if (seen.has(id)) return false; seen.add(id); return true; });
+  if (fresh.length) {
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, (text && !text.endsWith('\n') ? '\n' : '') + fresh.map(row => JSON.stringify(row)).join('\n') + '\n');
+  }
+  return fresh.length;
+}
+
+export async function persistPulledHistory(config, events, targetEvents, index) {
+  const existing = await readObservations(config.paths.observations);
+  if (existing.problems.length) throw new Error('cannot replay into malformed observation history');
+  let repaired=0;
+  if(existing.rows.some(row=>row.source==='cloud'&&!row.projection_version)) {
+    let raw='';
+    try { raw=await readFile(config.paths.events,'utf8'); } catch(error) { if(error.code!=='ENOENT')throw error; }
+    const held=raw.split('\n').filter(line=>line.trim()).map(line=>JSON.parse(line));
+    const corrected=new Map(cloudObservationRows([...held,...events],index).map(row=>[observationKey(row),row]));
+    existing.rows=existing.rows.map(row=>{
+      const replacement=corrected.get(observationKey(row));
+      if(row.source==='cloud'&&!row.projection_version&&replacement){repaired++;return replacement;}
+      return row;
+    });
+    if(repaired)await writeObservations(config.paths.observations,existing.rows);
+  }
+  const rows = cloudObservationRows(events, index);
+  const { fresh, duplicates } = dedupeObservations(existing.rows, rows);
+  await appendObservations(config.paths.observations, fresh);
+  await appendEventHistory(config.paths.events, [...events, ...targetEvents]);
+  return { fresh, duplicates, repaired };
+}

package/cli/doctor.js

@@ -0,0 +1,283 @@
+// `agentlinkops doctor` — one command that says whether this installation works.
+//
+// Each check is one plain line with a verdict, and a failing line carries exactly one fix.
+// The command deliberately runs where the ledger cannot yet be trusted: its whole job is to
+// name what is broken, so it dispatches before main.js's ledger requirement and inspects every
+// file itself. Nothing here repairs anything.
+//
+// Two boundaries worth naming. The cloud reachability probe is ANONYMOUS — no Authorization
+// header reaches it, so reachability can never depend on (or leak) a credential. The token
+// probe does send the token, but only to the configured origin, on the same read sync already
+// makes; a token's scope lives server-side, so presence alone cannot answer the scope
+// question. No secret value is ever printed, recorded or measured — not even its length.
+//
+// The observation mirror is deliberately not scanned: it can be megabytes a doctor run would
+// re-parse for no decision, and `status`/`check` already refuse malformed rows loudly.
+import { access } from 'node:fs/promises';
+import assert from 'node:assert/strict';
+import { loadConfig, setNoticeSink } from './config.js';
+import { readLedger } from './ledger.js';
+import { readReceipts } from './receipts.js';
+import { readState, writeState } from './state.js';
+import { createClient, CloudError } from './client.js';
+import { cloudConnection } from './connection.js';
+import { validatePublicUrl, parseLinks, transitionState, checkObservationKind } from '../src/verifier/index.js';
+import { matchesTarget } from '../src/verifier/url.js';
+
+const USAGE = 'agentlinkops doctor   (no flags; verifies ledger, verifier, cloud and token)';
+
+const TOKEN_SHAPE = /^lt_[0-9a-f]{64}$/u;
+
+/**
+ * Runs the real verifier exports against fixed local expectations — no network, no fixtures
+ * directory, nothing metered. This is not a benchmark; it answers "did the verifier arrive in
+ * this install intact", the way `ssh -V` answers whether ssh works at all.
+ */
+export function verifierSelfTest() {
+  const failures = [];
+  const step = (name, run) => {
+    try { run(); } catch (error) { failures.push(`${name}: ${error?.message ?? String(error)}`); }
+  };
+
+  step('url screen', () => {
+    const page = validatePublicUrl('https://example.com/post');
+    assert.ok(page.valid, `public URL refused (${page.reason})`);
+    const refused = validatePublicUrl('http://192.168.0.10/admin');
+    assert.ok(!refused.valid, 'a private IP literal passed the public screen');
+    assert.equal(refused.reason, 'ip_literal_not_supported');
+  });
+
+  const document = '<html><body><p>See the <a href="/guide" rel="nofollow ugc">outreach guide</a> for details.</p></body></html>';
+  let occurrences = [];
+  step('parser', () => {
+    occurrences = parseLinks(document, 'https://example.com/post');
+    assert.equal(occurrences.length, 1, `expected one occurrence, found ${occurrences.length}`);
+    assert.equal(occurrences[0].targetUrl, 'https://example.com/guide');
+    assert.equal(occurrences[0].anchor, 'outreach guide');
+    assert.deepEqual(occurrences[0].rel, ['nofollow', 'ugc']);
+    assert.ok(matchesTarget(occurrences[0].targetUrl, 'https://example.com/guide', 'exact'), 'exact match failed');
+    assert.ok(!matchesTarget(occurrences[0].targetUrl, 'https://example.com/other', 'exact'), 'a different path matched');
+  });
+
+  const at = Date.parse('2026-09-12T12:00:00Z');
+  let acquired = null;
+  step('reducer', () => {
+    const present = {
+      state: 'present', reason: 'link_found', sourceUrl: 'https://example.com/post',
+      finalUrl: 'https://example.com/post', targetUrl: 'https://example.com/guide', targetScope: 'exact',
+      httpStatus: 200, checkedAt: new Date(at).toISOString(), occurrences,
+      directives: { noindex: false, nofollow: false }, evidence: { complete: true },
+    };
+    acquired = transitionState(null, present);
+    assert.equal(acquired.state, 'present');
+    assert.equal(acquired.event?.type, 'placement_acquired', 'first present observation emitted no acquisition event');
+    const absent = { ...present, state: 'absent', reason: 'no_matching_link_in_complete_html', occurrences: [],
+      checkedAt: new Date(at + 40 * 60 * 1000).toISOString() };
+    const missing = transitionState(acquired, absent);
+    assert.equal(missing.state, 'suspected_missing', 'one absent observation confirmed loss early');
+    assert.ok(missing.nextCheckAt, 'suspected missing scheduled no confirmation check');
+  });
+
+  step('kind check', () => {
+    const inside = checkObservationKind({ kind: 'internal', sourceUrl: 'https://example.com/post', targetUrl: 'https://example.com/guide' }, ['example.com']);
+    assert.ok(inside.valid, `internal kind refused inside the declared site (${inside.reason})`);
+    const outside = checkObservationKind({ kind: 'internal', sourceUrl: 'https://example.com/post', targetUrl: 'https://other.com/guide' }, ['example.com']);
+    assert.ok(!outside.valid, 'an internal receipt outside the declared site passed');
+    assert.match(outside.reason, /other\.com/u, 'the refusal does not name the offending host');
+  });
+
+  return { ok: failures.length === 0, failures, steps: ['url screen', 'parser', 'reducer', 'kind check'] };
+}
+
+/**
+ * Anonymous, bounded reachability probe of the configured cloud. No credential is sent, no
+ * redirect is followed, and the outcome is meant to be recorded: a doctor run months later
+ * should be able to say when the cloud was last reachable from this machine.
+ */
+export async function probeCloud({ origin, fetchImpl, timeoutMs = 5000 }) {
+  const base = String(origin).replace(/\/$/u, '');
+  const started = Date.now();
+  try {
+    const response = await fetchImpl(`${base}/healthz`, { method: 'GET', redirect: 'error', signal: AbortSignal.timeout(timeoutMs) });
+    return { reachable: true, ok: response.ok, status: response.status, ms: Date.now() - started };
+  } catch (error) {
+    const timedOut = error?.name === 'TimeoutError' || error?.name === 'AbortError';
+    return { reachable: false, ok: false, status: null, ms: Date.now() - started,
+      error: timedOut ? 'timeout' : 'network error', timedOut };
+  }
+}
+
+/**
+ * Asks the cloud whether the configured token actually works, using the same client sync
+ * uses. Scope is a server-side fact, so this read (a plain watch listing, metered as none) is
+ * the only honest answer to "is this token good for anything here".
+ */
+export async function probeToken({ origin, token, workspaceId, fetchImpl }) {
+  try {
+    await createClient({ origin, token, workspaceId, fetchImpl }).listWatches({ limit: 1 });
+    return { verified: true };
+  } catch (error) {
+    if (error instanceof CloudError) return { verified: false, code: error.code, status: error.status, scope: error.details?.scope ?? null };
+    return { verified: null, error: error?.name ?? 'network error' };
+  }
+}
+
+/** One line per check, a fix under every failure. Plain words, no symbols to look up. */
+function render(checks, out) {
+  let ok = 0, skip = 0, fail = 0;
+  for (const check of checks) {
+    if (check.status === 'ok') ok++; else if (check.status === 'skip') skip++; else fail++;
+    out(`${check.status.padEnd(6)} ${check.name.padEnd(9)} — ${check.detail}`);
+    if (check.status === 'fail' && check.fix) out(`${''.padEnd(6)} ${'fix'.padEnd(9)} — ${check.fix}`);
+  }
+  out('');
+  out(fail ? `${fail} of ${checks.length} check(s) failed` : `all checks passed (${ok} ok, ${skip} skipped)`);
+  return fail;
+}
+
+export async function doctorMain(argv = [], { cwd = process.cwd(), out = console.log, err = console.error,
+  env = process.env, fetchImpl = globalThis.fetch, timeoutMs = 5000 } = {}) {
+  if (argv.length) { err(USAGE); return 2; }
+  setNoticeSink(err);
+
+  const config = await loadConfig({ cwd });
+  const checks = [];
+
+  const ledger = await readLedger(config.paths.ledger);
+  if (ledger.missing) {
+    checks.push({ status: 'fail', name: 'ledger', detail: `no ledger at ${config.paths.ledger}`,
+      fix: 'run `agentlinkops init` in the repository root' });
+  } else if (ledger.problems.length) {
+    const first = ledger.problems[0];
+    checks.push({ status: 'fail', name: 'ledger',
+      detail: `${ledger.problems.length} unreadable line(s); first at line ${first.line}: ${first.reason}`,
+      fix: 'repair that line in the ledger file; `agentlinkops fmt` lists every problem without writing' });
+  } else {
+    const n = ledger.entries.length;
+    checks.push({ status: 'ok', name: 'ledger', detail: `${n} ${n === 1 ? 'entry parses' : 'entries parse'}` });
+  }
+
+  // Receipts are optional until the first claim is written; unreadable once written is fatal
+  // to every receipt verb, so doctor names it the same way the verbs will.
+  const hasReceipts = await access(config.paths.receipts).then(() => true, () => false);
+  if (!hasReceipts) {
+    checks.push({ status: 'skip', name: 'receipts', detail: 'none written yet' });
+  } else {
+    try {
+      const receipts = await readReceipts(config.paths.receipts);
+      checks.push({ status: 'ok', name: 'receipts', detail: `${receipts.length} ${receipts.length === 1 ? 'claim parses' : 'claims parse'}` });
+    } catch (error) {
+      checks.push({ status: 'fail', name: 'receipts', detail: error.message,
+        fix: 'repair or remove the named line in receipts.jsonl; a claim that cannot parse was never verified' });
+    }
+  }
+
+  let state = null;
+  try {
+    state = await readState(config.paths.state);
+    checks.push({ status: 'ok', name: 'state', detail: `v${state.v}, ${Object.keys(state.entries).length} entr${Object.keys(state.entries).length === 1 ? 'y' : 'ies'} tracked` });
+  } catch (error) {
+    checks.push({ status: 'fail', name: 'state', detail: `state.json is not readable: ${error.message}`,
+      fix: `restore ${config.dirName}/state.json from version control (cursors and first-present dates live there)` });
+  }
+
+  const selfTest = verifierSelfTest();
+  checks.push(selfTest.ok
+    ? { status: 'ok', name: 'verifier', detail: `self-test passed (${selfTest.steps.join(', ')})` }
+    : { status: 'fail', name: 'verifier', detail: `self-test failed: ${selfTest.failures[0]}`,
+        fix: 'the verifier modules are broken in this install; re-install or check local modifications under src/verifier/' });
+
+  // Cloud reachability: anonymous, bounded, recorded. A repository with no cloud configured is
+  // a legitimate local-only install, reported as a skip rather than a failure.
+  const connection = cloudConnection(config, env);
+  const origin = connection.origin || null;
+  const record = { at: new Date().toISOString() };
+  let probed = false;
+  if (!origin) {
+    checks.push({ status: 'skip', name: 'cloud', detail: 'no cloud configured (local-only repository)' });
+  } else {
+    const cloud = await probeCloud({ origin, fetchImpl, timeoutMs });
+    record.cloud = { ok: cloud.ok, status: cloud.status, ms: cloud.ms };
+    if (!cloud.reachable) {
+      checks.push({ status: 'fail', name: 'cloud',
+        detail: `cannot reach ${origin} (${cloud.error}${cloud.timedOut ? ` after ${timeoutMs} ms` : ''})`,
+        fix: `check the network and cloud.origin in ${config.dirName}/config.json` });
+    } else if (!cloud.ok) {
+      checks.push({ status: 'fail', name: 'cloud', detail: `${origin} answered HTTP ${cloud.status}`,
+        fix: 'the cloud is reachable but unhealthy; check its deployment before syncing' });
+    } else {
+      checks.push({ status: 'ok', name: 'cloud', detail: `${origin} answered ${cloud.status} in ${cloud.ms} ms` });
+    }
+    probed = true;
+  }
+
+  // Token: presence, shape, and — only when the cloud just proved reachable — whether the
+  // cloud accepts it. The value itself is never printed, hashed or measured here.
+  const token = connection.token || null;
+  const source = connection.tokenSource ? `the environment (${connection.tokenSource})` : `${config.dirName}/config.json (cloud.token)`;
+  if (!token) {
+    if (origin) {
+      checks.push({ status: 'fail', name: 'token', detail: 'no token is set; sync and receive need one',
+        fix: 'run agentlinkops connect for the app API-key setup path; supply AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY in the environment' });
+    } else {
+      checks.push({ status: 'skip', name: 'token', detail: 'no token (and no cloud configured)' });
+    }
+  } else if (!TOKEN_SHAPE.test(token)) {
+    checks.push({ status: 'fail', name: 'token', detail: `set in ${source} but it does not look like an AgentLinkOps API key (lt_ plus 64 hex characters)`,
+      fix: 'copy the full key without truncation or line breaks; the key itself is never printed here' });
+  } else if (!origin) {
+    checks.push({ status: 'skip', name: 'token', detail: `set in ${source}; no cloud configured to verify against` });
+  } else {
+    const cloudLine = checks.find(check => check.name === 'cloud');
+    if (cloudLine?.status === 'ok') {
+      const probed = await probeToken({ origin, token, workspaceId: config.cloud?.workspaceId, fetchImpl });
+      if (probed.verified) {
+        record.token = { ok: true };
+        checks.push({ status: 'ok', name: 'token', detail: `set in ${source}; the cloud accepted it (watches:read works)` });
+      } else if (probed.verified === false) {
+        record.token = { ok: false, code: probed.code };
+        const fix = probed.code === 'INSUFFICIENT_SCOPE' ? `issue a key carrying ${probed.scope ?? 'watches:read'}`
+          : probed.code === 'WORKSPACE_DENIED' ? `check cloud.workspaceId in ${config.dirName}/config.json against the workspace the key belongs to`
+          : probed.code === 'UNAUTHORIZED' ? 'issue a fresh key (this one is invalid or expired) and update where it is set'
+          : 'sync will fail the same way; act on the code above';
+        const detail = probed.code === 'INSUFFICIENT_SCOPE' ? `the cloud accepted it but scope ${probed.scope ?? 'watches:read'} is missing`
+          : probed.code === 'WORKSPACE_DENIED' ? 'the credential belongs to a different workspace'
+          : probed.code === 'UNAUTHORIZED' ? 'the cloud rejected it (invalid or expired)'
+          : `the cloud answered ${probed.code}${probed.status ? ` (HTTP ${probed.status})` : ''}`;
+        checks.push({ status: 'fail', name: 'token', detail, fix });
+      } else {
+        checks.push({ status: 'skip', name: 'token', detail: `set in ${source}; not verified (${probed.error})` });
+      }
+    } else {
+      checks.push({ status: 'skip', name: 'token', detail: `set in ${source}; not verified (cloud unreachable)` });
+    }
+  }
+  // Citation engines: presence only, never the value. A missing credential is a skip,
+  // not a failure — the mock engine runs everything, and a repository that never set a
+  // live key has not broken anything it asked for.
+  if (env.PERPLEXITY_API_KEY) {
+    checks.push({ status: 'ok', name: 'citations', detail: 'PERPLEXITY_API_KEY is set; live citation runs available' });
+  } else {
+    checks.push({ status: 'skip', name: 'citations', detail: 'no engine credential set; mock citation runs work, live runs need PERPLEXITY_API_KEY' });
+  }
+
+  out(`agentlinkops doctor — ${config.dir}`);
+
+  // Record the probe outcomes beside the cursors they protect — BEFORE rendering, so the
+  // "(recorded in state.json)" note on the cloud line is a fact rather than an intention. A
+  // state file that cannot be read was already reported above; the note then says so instead
+  // of failing doctor twice.
+  if (probed) {
+    const cloudLine = checks.find(check => check.name === 'cloud');
+    try {
+      const current = state ?? await readState(config.paths.state);
+      await writeState(config.paths.state, { ...current, doctor: record });
+      if (cloudLine) cloudLine.detail += ' (recorded in state.json)';
+    } catch (error) {
+      if (cloudLine) cloudLine.detail += ` (result NOT recorded: ${error.message})`;
+    }
+  }
+
+  const failed = render(checks, out);
+  return failed ? 1 : 0;
+}

package/cli/env.js

@@ -0,0 +1,66 @@
+// Environment variable names, and the compatibility window between the two sets of them.
+//
+// The product is AgentLinkOps. "Linktrail" was a working name, and the private pilot's installed
+// CLI and LaunchAgent still export `LINKTRAIL_*` (DP-0029 inventory, 2026-09-15). So every
+// variable has exactly two spellings here: the AgentLinkOps name is preferred, the Linktrail name
+// is an alias, and the rules are the same for every pair:
+//
+//   - only the new name set      -> used, silently
+//   - only the old name set      -> used, with ONE warning per process naming the new variable
+//   - both set, same value       -> used, silently (an operator mid-migration exports both)
+//   - both set, different values -> ConfigError, the same conflict rule that already refuses a
+//                                   TOKEN that disagrees with an API_KEY. Guessing between two
+//                                   credentials is how a sync lands in the wrong workspace.
+//
+// No value is ever printed: the warning and the error name variables, never contents.
+import { ConfigError, noticeOnce, resetCompatibilityNotices, setNoticeSink } from './config.js';
+
+export { resetCompatibilityNotices, setNoticeSink };
+
+export const ENV_PREFIX = 'AGENTLINKOPS';
+export const LEGACY_ENV_PREFIX = 'LINKTRAIL';
+
+/** Every suffix the CLI reads from the environment. */
+export const ENV_NAMES = Object.freeze(['TOKEN', 'API_KEY', 'API_URL', 'WEBHOOK_SECRET', 'GSC_TOKEN', 'GA4_TOKEN']);
+
+export const envName = suffix => `${ENV_PREFIX}_${suffix}`;
+export const legacyEnvName = suffix => `${LEGACY_ENV_PREFIX}_${suffix}`;
+
+export function deprecationNotice(oldName, newName) {
+  return `${oldName} is deprecated; set ${newName} instead. The old name keeps working during the pilot compatibility window.`;
+}
+
+/**
+ * Reads one variable under both names. Returns `{ value, name }` where `name` is the variable
+ * the value actually came from (or null), so a caller can say "set in the environment (X)"
+ * truthfully.
+ */
+export function readEnv(env, suffix, { warn = null } = {}) {
+  const preferred = envName(suffix), legacy = legacyEnvName(suffix);
+  const fresh = env[preferred], old = env[legacy];
+  if (fresh !== undefined && fresh !== '' && old !== undefined && old !== '' && fresh !== old)
+    throw new ConfigError(`${preferred} and ${legacy} disagree; select one value.`);
+  if (fresh !== undefined && fresh !== '') return { value: fresh, name: preferred };
+  if (old !== undefined && old !== '') {
+    // Once per process, per variable, so a command that resolves the environment in three
+    // places (config, doctor, context) warns once rather than three times.
+    if (warn) warn(deprecationNotice(legacy, preferred));
+    else noticeOnce(`legacy-env:${legacy}`, deprecationNotice(legacy, preferred));
+    return { value: old, name: legacy };
+  }
+  return { value: undefined, name: null };
+}
+
+/**
+ * Every variable the CLI reads, resolved through the alias rule. `values` is keyed by suffix
+ * (`TOKEN`, `API_KEY`, …); `sources` says which spelling supplied each one.
+ */
+export function resolveEnv(env = process.env, options = {}) {
+  const values = {}, sources = {};
+  for (const suffix of ENV_NAMES) {
+    const { value, name } = readEnv(env, suffix, options);
+    values[suffix] = value;
+    sources[suffix] = name;
+  }
+  return { values, sources };
+}

package/cli/fleet.js

@@ -0,0 +1,82 @@
+// `agentlinkops fleet`: one summary over several project ledgers, each read on its own.
+//
+// The fleet question is scale ("how much intent does the whole operation hold?"), and the one
+// rule that makes the command safe is that it NEVER merges intent across repos. A platform
+// that is `expected` for one site and merely `wanted` for another is two entries in two files,
+// and a summary that deduplicated them would silently pick one. So every number below is
+// per project, the only cross-project arithmetic is a sum of counts, and the output says so.
+//
+// "Earned" follows the ledger contract, not a status column: an entry is earned when its
+// latest OBSERVATION says present. A project with no observation file has earned nothing and
+// is reported as never checked rather than as zero links.
+import { readLedger } from './ledger.js';
+import { readObservations, latestByEntry } from './mirror.js';
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** One project's row. Everything is computed inside the project; nothing crosses the boundary. */
+export async function fleetProject(name, ledgerPath, observationsPath) {
+  const ledger = await readLedger(ledgerPath);
+  if (ledger.missing) { const error = new Error(`no ledger at ${ledgerPath}`); error.code = 'NO_LEDGER'; throw error; }
+  const byIntent = { wanted: 0, expected: 0, retired: 0 };
+  for (const entry of ledger.entries) byIntent[entry.intent] = (byIntent[entry.intent] ?? 0) + 1;
+
+  const { rows } = observationsPath ? await readObservations(observationsPath) : { rows: [] };
+  const latest = latestByEntry(rows);
+  let earned = 0, observed = 0;
+  for (const [id, row] of latest) {
+    if (!ledger.entries.some(entry => entry.id === id)) continue; // observations from another ledger's ids
+    observed++;
+    if (row.state === 'present') earned++;
+  }
+  const lastCheck = rows.length ? rows.map(row => row.checked_at).sort().at(-1) : null;
+  return {
+    project: name, ledger: ledgerPath,
+    entries: ledger.entries.length, ...byIntent,
+    problems: ledger.problems.length,
+    observed_entries: observed, earned,
+    never_checked: ledger.entries.filter(entry => entry.intent !== 'retired').length - observed,
+    last_observation: lastCheck,
+    // Due volume, the same arithmetic the dogfood records use to price a fleet.
+    implied_weekly_checks: byIntent.wanted + byIntent.expected * 7,
+  };
+}
+
+/** Summons the fleet. Same numbers per project, one sum of counts, no merged intent. */
+export async function fleetSummary(projects, { observationsOf = {} } = {}) {
+  const rows = [];
+  for (const { name, ledger } of projects) rows.push(await fleetProject(name, ledger, observationsOf[name] ?? null));
+  const totals = rows.reduce((acc, row) => {
+    for (const key of ['entries', 'wanted', 'expected', 'retired', 'earned', 'observed_entries', 'never_checked', 'implied_weekly_checks']) {
+      acc[key] = (acc[key] ?? 0) + row[key];
+    }
+    return acc;
+  }, {});
+  return {
+    v: 1, projects: rows, totals,
+    // The sum answers "how big is the operation". It is not a merged view: the same platform
+    // counted in two projects is two intents, and only a human can say which one they meant.
+    intent_merged_across_repos: false,
+  };
+}
+
+export function renderFleet(summary, out = console.log) {
+  out(`${plural(summary.projects.length, 'project')}; counts summed for scale only — intent is never merged across repos`);
+  out('');
+  out('project        entries  wanted  expected  retired  earned  never-checked  last-observation');
+  for (const row of summary.projects) {
+    out(`${row.project.padEnd(14)} ${String(row.entries).padStart(7)} ${String(row.wanted).padStart(7)} `
+      + `${String(row.expected).padStart(9)} ${String(row.retired).padStart(8)} ${String(row.earned).padStart(7)} `
+      + `${String(row.never_checked).padStart(13)}  ${row.last_observation?.slice(0, 10) ?? 'never checked'}`);
+  }
+  const t = summary.totals;
+  out(`${'TOTAL'.padEnd(14)} ${String(t.entries).padStart(7)} ${String(t.wanted).padStart(7)} `
+    + `${String(t.expected).padStart(9)} ${String(t.retired).padStart(8)} ${String(t.earned).padStart(7)} `
+    + `${String(t.never_checked).padStart(13)}  (sum of counts)`);
+  out('');
+  out(`implied weekly check volume across the fleet: ${t.implied_weekly_checks}`);
+  if (summary.projects.some(row => row.problems)) {
+    out(`ledger problems: ${summary.projects.map(row => `${row.project}=${row.problems}`).filter(s => !s.endsWith('=0')).join(', ')}`);
+  }
+  return 0;
+}