@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.3

package/src/lib/mirrorContract.js

@@ -457,7 +457,7 @@ function project(schema, value, depth) {
   return INVALID;
 }
 
-function leaksPath(value) {
+export function leaksPath(value) {
   if (typeof value === 'string') return pathRejected(value);
   if (Array.isArray(value)) return value.some(leaksPath);
   if (value && typeof value === 'object') return Object.entries(value).some(([key, entry]) => pathRejected(key) || leaksPath(entry));

package/src/lib/mirrorService.js

@@ -56,6 +56,7 @@ export class MirrorService {
     this.windowsRunning = false;
     this.windowsDeferredGapMs = null;
     this.windowsChanged = false;
+    this.echoDuringWindows = false;
     this.reconcileMs = reconcileMs;
     this.maxFullDelayMs = maxFullDelayMs;
     this.lastFullCompletedAt = -Infinity;
@@ -113,6 +114,7 @@ export class MirrorService {
     // in a loop. While windows passes keep finding changes the hub is busy, and it refreshes at the normal gap.
     const ours = this.reader.graphReadRecently?.(this.echoMs) ?? false;
     const echo = !this.windowsChanged && ours;
+    if (echo && this.windowsPass && kinds.includes('hub')) this.echoDuringWindows = true;
     const news = kinds.filter((kind) => kind !== 'presence');
     if (news.some((kind) => CHANGE_SOURCES[kind]) && !(ours && news.every((kind) => kind === 'hub'))) this.#preemptFull();
     for (const kind of kinds) {
@@ -214,6 +216,7 @@ export class MirrorService {
     const slow = this.now() >= this.lastSlowWindowsAt + this.slowWindowsGapMs;
     const sources = new Set(slow ? ['graph', 'windows'] : ['recent']);
     this.windowsRunning = true;
+    this.echoDuringWindows = false;
     this.windowsPass = this.#pass({ full: false, sources, lane: 'windows' }).finally(() => {
       this.windowsPass = null;
       this.lastWindowsAt = this.now();
@@ -283,7 +286,11 @@ export class MirrorService {
         this.refusals = 0;
         if (full) this.lastFullCompletedAt = this.now();
         if (result.briefsPending) this.pendingSources.add('briefs');
-        if (lane === 'windows') this.windowsChanged = result.pushed + result.tombstoned > 0;
+        if (lane === 'windows') {
+          this.windowsChanged = result.pushed + result.tombstoned > 0;
+          // The hub can echo this pass's reads before its result is in; that echo was judged as if the hub were quiet.
+          if (this.windowsChanged && this.echoDuringWindows) this.#requestWindows(this.windowsGapMs);
+        }
         this.log('mirror', { full, pushed: result.pushed, tombstoned: result.tombstoned, rejected: result.rejected.length });
       })
       .catch((error) => {

package/src/lib/mirrorSource.js

@@ -1,12 +1,10 @@
 import { createHash } from 'node:crypto';
 import os from 'node:os';
-import path from 'node:path';
 import { GRAPH_HOURS as WINDOW_HOURS, mergeWindows, RowMemo, windowRows } from './graphWindows.js';
 import { HubError } from './errors.js';
-import { MIRROR_CONTRACT, redactSecretSubtree, sanitizeItem, secretKeyReplacement } from './mirrorContract.js';
-import { createPathRedactor } from './pathRedaction.js';
-import { redactSecrets } from './redaction.js';
+import { MIRROR_CONTRACT, sanitizeItem } from './mirrorContract.js';
 import { readRulePacks } from './rulePacks.js';
+import { UploadRedactor } from './uploadRedactor.js';
 
 export const MIRROR_SOURCES = Object.freeze(['deliveries', 'graph', 'channels', 'inbox', 'rules', 'windows', 'briefs']);
 /**
@@ -27,7 +25,6 @@ const SOURCE_KINDS = Object.freeze({
 });
 const BRIEF_READS_IN_FLIGHT = 4;
 const GRAPH_HOURS = 168;
-const SECRET_SEEN_MAX = 100_000;
 const TASK_KEY = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 const BRIEF = MIRROR_CONTRACT.kinds.brief.properties;
 const longer = (text, max) => typeof text === 'string' && Array.from(text).length > max;
@@ -150,10 +147,9 @@ export class MirrorSource {
     this.now = now;
     this.maxMessagesPerChannel = maxMessagesPerChannel;
     this.briefBudgetMs = briefBudgetMs;
-    this.repoRoots = new Map(approvedRoots.map((root) => [root, path.basename(root)]));
+    this.redaction = new UploadRedactor({ workspace, home, approvedRoots });
     this.windowCache = new Map();
     this.rowMemo = new RowMemo();
-    this.worktreeRoots = new Map();
     this.briefs = new Map();
     this.taskKeys = null;
   }
@@ -197,37 +193,16 @@ export class MirrorSource {
     return !failed && index === stale.length;
   }
 
-  #learnRepos(deliveries) {
-    for (const stream of deliveries.flatMap((delivery) => delivery.streams || [])) {
-      const git = stream.git || {};
-      if (typeof git.mainRepo === 'string' && path.isAbsolute(git.mainRepo)) this.repoRoots.set(git.mainRepo, path.basename(git.mainRepo));
-      for (const extra of [git.worktreePath, git.channelCheckout]) {
-        if (typeof extra === 'string' && path.isAbsolute(extra) && !this.repoRoots.has(extra)) this.worktreeRoots.set(extra, path.basename(extra));
-      }
-    }
+  get repoRoots() {
+    return this.redaction.repoRoots;
   }
 
-  /**
-   * Secrets first, then paths, on every string and key: a secret inside a path is never cut down to a last segment
-   * that still holds it, and nothing is projected, truncated or hashed before both have run.
-   */
-  #redactor(secrets) {
-    const repos = [...this.repoRoots, ...this.worktreeRoots].map(([root, name]) => ({ root, name }));
-    const paths = createPathRedactor({ repos, workspace: this.workspace, home: this.home });
-    const seen = new Map();
-    const redactString = (input) => {
-      const original = String(input ?? '');
-      let text = seen.get(original);
-      if (text === undefined) {
-        text = paths.redactString(redactSecrets(original, { secrets }).text);
-        if (seen.size >= SECRET_SEEN_MAX) seen.clear();
-        seen.set(original, text);
-      }
-      return text;
-    };
-    const entry = (key, item) => secretKeyReplacement(key, item) ?? redactSecretSubtree(key, item, redactString);
-    const redactValue = (value, { keep = [] } = {}) => paths.redactValue(value, { keep, redactString, entry });
-    return { redactString, redactValue };
+  get worktreeRoots() {
+    return this.redaction.worktreeRoots;
+  }
+
+  #learnRepos(deliveries) {
+    this.redaction.learnRepos(deliveries);
   }
 
   async collect({ full = false, sources = new Set(MIRROR_SOURCES), channelLastAt = new Map(), signal } = {}) {
@@ -412,7 +387,7 @@ export class MirrorSource {
 
     checkpoint();
     const secrets = [await this.reader.tokenValue().catch(() => null), ...this.heldSecrets()].filter(Boolean);
-    const redactor = this.#redactor(secrets);
+    const redactor = this.redaction.redactor(secrets);
     const items = new Map();
     for (const entry of raw) {
       if (typeof entry.externalId !== 'string' || !entry.externalId) continue;
@@ -430,7 +405,7 @@ export class MirrorSource {
     const graphDropped = {};
     if (windows.length === WINDOW_HOURS.length) {
       // A row's redacted, checked form depends on the roots the redactor knows and the secrets, and on nothing else.
-      this.rowMemo.begin(JSON.stringify([[...this.repoRoots], [...this.worktreeRoots], this.workspace, this.home, secrets]));
+      this.rowMemo.begin(this.redaction.basis(secrets));
       const options = { redact: (value) => redactor.redactValue(value), secrets, memo: this.rowMemo };
       const built = mergeWindows(windows.map(({ hours, body, fresh }) => {
         if (!fresh) return this.windowCache.get(hours).rows;

package/src/lib/nodeFloor.js

@@ -0,0 +1,19 @@
+import { HubError } from './errors.js';
+
+export const NODE_FLOOR_MAJOR = 24;
+
+/** Whether this Node can run Pulse; on Node 22 and older, fetch can lose an abort on a long-lived stream (NODE22-01). */
+export function nodeFloor(version = process.versions.node) {
+  if (Number(version.split('.')[0]) >= NODE_FLOOR_MAJOR) return { ok: true, version };
+  return {
+    ok: false,
+    code: 'HUB_NODE_TOO_OLD',
+    version,
+    message: `Pulse needs Node ${NODE_FLOOR_MAJOR} or newer; this is Node ${version}. Install Node ${NODE_FLOOR_MAJOR} (Active LTS), then run \`agentpulse pulse install\` and \`agentpulse pulse start\`.`,
+  };
+}
+
+export function assertNodeFloor(version) {
+  const floor = nodeFloor(version);
+  if (!floor.ok) throw new HubError(floor.code, floor.message);
+}

package/src/lib/outboxFlusher.js

@@ -0,0 +1,75 @@
+import { fullJitterDelay } from './backoff.js';
+import { HubError } from './errors.js';
+
+// I3: a command gets at most this many retryable refusals before it is set aside, so it can block its group only so long.
+export const MAX_ATTEMPTS = 6;
+// The cloud holds a command behind an earlier refused command of its group; it goes again as soon as that one does.
+const HELD_CODE = 'held_by_group';
+const HELD_RETRY_MS = 1_000;
+
+/**
+ * Sends the runner store's outbox to Pulse, one batch at a time and in enqueue order (design §6.3 flush loop). Each
+ * command carries its ordering group, so the cloud holds a group's later commands behind one it refused for now, and
+ * the store holds them locally while it backs off. Per item: stored or duplicate → acked; retryable → backoff (then
+ * dead after MAX_ATTEMPTS); any other refusal → dead with its code. A refusal of the whole batch is thrown.
+ */
+export class OutboxFlusher {
+  constructor({ store, transport, random = Math.random, maxAttempts = MAX_ATTEMPTS }) {
+    this.store = store;
+    this.transport = transport;
+    this.random = random;
+    this.maxAttempts = maxAttempts;
+  }
+
+  /** One batch; resolves to its tally, or null when nothing is due. */
+  async flushOnce() {
+    const batch = this.store.nextBatch();
+    if (!batch.length) return null;
+    const response = await this.transport.commands({
+      commands: batch.map((row) => ({ type: row.type, idempotencyKey: row.key, payload: row.payload, group: row.group })),
+    });
+    const results = Array.isArray(response?.results) ? response.results : [];
+    const tally = { sent: batch.length, written: 0, duplicate: 0, retried: 0, held: 0, dead: 0 };
+    batch.forEach((row, index) => {
+      const result = results[index];
+      if (!result || result.key !== row.key) {
+        this.store.retry(row.key, { code: 'no_result', delayMs: fullJitterDelay(row.attempts, { random: this.random }) });
+        tally.retried += 1;
+        return;
+      }
+      if (!result.error) {
+        this.store.acked(row.key, { seq: result.seq ?? null, duplicate: Boolean(result.duplicate) });
+        tally[result.duplicate ? 'duplicate' : 'written'] += 1;
+        return;
+      }
+      const { code = 'refused', retryable = false, message = null } = result.error;
+      if (code === HELD_CODE) {
+        this.store.hold(row.key, { code, delayMs: HELD_RETRY_MS });
+        tally.held += 1;
+        return;
+      }
+      if (retryable && row.attempts + 1 < this.maxAttempts) {
+        this.store.retry(row.key, { code, delayMs: fullJitterDelay(row.attempts, { random: this.random }) });
+        tally.retried += 1;
+        return;
+      }
+      this.store.dead(row.key, { code: retryable ? `max_attempts:${code}` : code, message });
+      tally.dead += 1;
+    });
+    return tally;
+  }
+
+  /** Batches until the outbox has nothing due, `maxBatches` were sent or the signal fires; the summed tally. */
+  async drain({ maxBatches = Infinity, signal } = {}) {
+    const total = { batches: 0, sent: 0, written: 0, duplicate: 0, retried: 0, held: 0, dead: 0 };
+    while (total.batches < maxBatches) {
+      if (signal?.aborted) throw new HubError('HUB_SHADOW_STOPPED', 'The shadow feed stopped');
+      const tally = await this.flushOnce();
+      if (!tally) break;
+      total.batches += 1;
+      for (const key of Object.keys(tally)) total[key] += tally[key];
+      if (tally.written + tally.duplicate + tally.dead === 0) break;
+    }
+    return total;
+  }
+}

package/src/lib/pairingLifecycle.js

@@ -94,7 +94,7 @@ export async function pairConnector({
   cliDefaults,
   now = Date.now,
   pairingPolicy = {
-    capabilities: ['workspace.read', 'git.read'],
+    capabilities: ['workspace.read', 'git.read', 'hub.sync', 'log.write'],
     providerPolicy: { providers: {}, maxConcurrency: 1, maxTokensPerRun: 1, maxCostUsd: 0 },
   },
   platformUrl,

package/src/lib/reconcile.js

@@ -0,0 +1,316 @@
+import { lstat, readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { channelFiles, splitPosts } from './channelScanner.js';
+import { HubDbReader } from './hubDbReader.js';
+import { FACT_KINDS, SKIPPED_FACT_KINDS } from './hubScan.js';
+import { bodyDigest, RECONCILE_TYPES, reconcileEntry, reconcileFamilies } from './reconcileView.js';
+import { openDatabase } from './sqlite.js';
+
+const NAMED = 50;
+const SOURCE_TABLES = Object.freeze({ actors: 'actors', messages: 'messages', events: 'events', presence: 'presence' });
+
+/**
+ * How many rows each source holds, counted straight from the snapshot without the scanner, so a scanner that drops
+ * a row is caught even though the import and the reconcile run the same scanner.
+ */
+export async function sourceCounts({ hubDir, roots }) {
+  const counts = {};
+  const db = openDatabase(path.join(hubDir, 'state', 'hub.db'), { readOnly: true });
+  try {
+    for (const [source, table] of Object.entries(SOURCE_TABLES)) counts[source] = Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n);
+    const kinds = [...FACT_KINDS, ...Object.keys(SKIPPED_FACT_KINDS)];
+    counts.facts = Number(db.prepare(`SELECT COUNT(*) AS n FROM facts WHERE kind IN (${kinds.map(() => '?').join(', ')})`).get(...kinds).n);
+  } finally {
+    db.close();
+  }
+  try {
+    const personas = JSON.parse(await readFile(path.join(hubDir, 'state', 'personas.json'), 'utf8'));
+    counts.personas = Object.keys(personas && typeof personas === 'object' ? personas : {}).length;
+  } catch {
+    counts.personas = 0;
+  }
+  counts.chat = 0;
+  const chatDir = path.join(hubDir, 'state', 'chat');
+  for (const name of (await readdir(chatDir).catch(() => [])).filter((entry) => entry.endsWith('.jsonl'))) {
+    counts.chat += (await readFile(path.join(chatDir, name), 'utf8')).split('\n').filter(Boolean).length;
+  }
+  const { files, collisions, unnamed } = await channelFiles(roots);
+  counts.channels = collisions.length + unnamed.length;
+  for (const file of files) counts.channels += splitPosts(await readFile(file.file, 'utf8'), file.mtimeMs).length;
+  return counts;
+}
+
+/** Receipt states a recipient ends in under the hub's (and the cloud's) rules, applied to the commands in order. */
+function receiptStates(commands) {
+  const state = new Map();
+  const topicOf = new Map();
+  for (const command of commands) {
+    const p = command.payload;
+    switch (command.type) {
+      case 'message.published':
+        topicOf.set(p.id, p.topic);
+        for (const to of p.to) state.set(`${p.id}\0${to}`, 'queued');
+        break;
+      case 'receipt.delivered':
+      case 'receipt.acked':
+      case 'receipt.expired': {
+        const id = `${p.messageId}\0${p.recipient}`;
+        const was = state.get(id);
+        if (was === undefined) break;
+        if (command.type === 'receipt.acked') state.set(id, 'acked');
+        else if (command.type === 'receipt.delivered' && (was === 'queued' || was === 'delivered')) state.set(id, 'delivered');
+        else if (command.type === 'receipt.expired' && was === 'queued') state.set(id, 'expired');
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  const byTopic = {};
+  for (const [id, value] of state) {
+    const topic = topicOf.get(id.slice(0, id.indexOf('\0')));
+    byTopic[topic] ??= {};
+    byTopic[topic][value] = (byTopic[topic][value] || 0) + 1;
+  }
+  return byTopic;
+}
+
+/** The local side: the reconcile view of a fresh scan's commands, its receipts, and what it withheld or cut. */
+export function localReconcile({ commands, dead }) {
+  const withBody = (command) => (['post.created', 'message.published'].includes(command.type) ? bodyDigest(command.payload.body) : null);
+  const { view, sets } = reconcileFamilies(commands.filter((command) => RECONCILE_TYPES.includes(command.type))
+    .map((command) => reconcileEntry(command.type, command.key, command.payload, withBody(command))));
+  const byTopic = new Map();
+  for (const [id, { topic }] of sets.messages) byTopic.set(topic, [...(byTopic.get(topic) || []), id]);
+  return {
+    view,
+    // The identities behind each channel and conversation, so a difference can be classified (CUT-02).
+    keys: { posts: new Map([...sets.posts].map(([channel, list]) => [channel, list.map((post) => post.key)])), messages: byTopic },
+    receipts: receiptStates(commands),
+    cut: commands.filter((command) => command.type === 'post.created' && command.payload.truncated).map((command) => command.key).sort(),
+    withheld: dead.map((row) => ({ key: row.key, type: row.type, code: row.code })),
+  };
+}
+
+/**
+ * A rescan keys a post by the digest of its block as it is now. A post edited in place after it was sent is known to
+ * Pulse by its first key, and the delta carried the edit as `post.edited` against that key. So each post takes the key
+ * the live store ingested for the same channel and block (`ingestedKey(channel, '<digest>:<n>')`), and a carried edit
+ * compares as the post it edited.
+ */
+export function resolvePostKeys(commands, ingestedKey) {
+  return commands.map((command) => {
+    if (command.type !== 'post.created' || !command.key.startsWith('post:')) return command;
+    const known = ingestedKey(command.payload.channel, command.key.split(':').slice(-2).join(':'));
+    return known && known !== command.key ? { ...command, key: known } : command;
+  });
+}
+
+const TASK_CHANNEL = /^task:([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)$/;
+const isDirectory = (dir) => stat(dir).then((info) => info.isDirectory(), () => false);
+
+/**
+ * Where a task channel's file is now: 'absent' only when every channel root is a readable directory and none holds
+ * <repo>/.agents/<task>/channel.md; 'present' when one does; 'unknown' otherwise (a root missing, an error other than
+ * not-found, a channel that is not a task channel). Only 'absent' makes a channel retired.
+ */
+export async function channelOnDisk(channel, roots) {
+  const parts = String(channel).match(TASK_CHANNEL)?.slice(1);
+  if (!parts || !roots.length || parts.some((part) => part === '.' || part === '..')) return 'unknown';
+  for (const root of roots) {
+    if (!(await isDirectory(root))) return 'unknown';
+    try {
+      await stat(path.join(root, parts[0], '.agents', parts[1], 'channel.md'));
+      return 'present';
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') return 'unknown';
+    }
+  }
+  return 'absent';
+}
+
+/** Channels the cloud has posts in that the rescan has none in: the ones whose file must be looked for on disk. */
+export function cloudOnlyChannels(local, cloud) {
+  return Object.keys(cloud.view?.posts?.byChannel ?? {}).filter((channel) => !local.view.posts.byChannel[channel]).sort();
+}
+
+/** The id a classified channel or conversation goes by in the `redacted` map. */
+export const itemId = (family, item) => `${family}\0${item}`;
+
+/**
+ * One differing channel (`posts.byChannel`) or conversation (`messages.byTopic`), classified (CUT-02, the 12:44:58
+ * DECISION):
+ * - `retired`: the cloud has a channel whose file is gone from disk under every root. Listed and allowed.
+ * - `redacted`: same identities, and a rescan with more redaction roots gives exactly the cloud's sha (`redacted`
+ *   holds those items and their roots). The cloud keeps its more-redacted text; nothing is sent. Allowed.
+ * - `drift`: same identities, other content, not explained by redaction. Every local key is one the cloud acknowledged
+ *   (`runner.db` sent) and the counts are equal, so only bodies differ. Fails: sending local text could un-redact.
+ * - `missing`: a local key the cloud never acknowledged, or a channel or conversation it lacks. Fails.
+ * - `unexplained`: anything else (a cloud-only channel whose file is there or cannot be checked, extra cloud items in a
+ *   live channel, no record of what was sent). Fails.
+ */
+function classify({ family, item, local, cloud, keys, sent, onDisk, redacted }) {
+  const type = family === 'posts.byChannel' ? 'post.created' : 'message.published';
+  if (!cloud) return { class: 'missing', note: 'not in Pulse' };
+  if (!local) {
+    if (family === 'posts.byChannel' && onDisk[item] === 'absent') return { class: 'retired', note: 'its channel file is gone from disk' };
+    return { class: 'unexplained', note: family === 'posts.byChannel' ? `only in Pulse, and its channel file is ${onDisk[item] ?? 'unknown'} on disk` : 'only in Pulse' };
+  }
+  if (!sent) return { class: 'unexplained', note: 'no record of what this machine sent' };
+  const lost = keys.filter((key) => !sent.sentAs(key, type));
+  if (lost.length) return { class: 'missing', note: `${lost.length} local item(s) Pulse never acknowledged, e.g. ${lost[0]}` };
+  if (local.count !== cloud.count) return { class: 'unexplained', note: `${local.count} here, ${cloud.count} in Pulse, every local one acknowledged` };
+  const roots = redacted.get(itemId(family, item));
+  if (roots) return { class: 'redacted', roots, note: 'Pulse holds the same text, redacted with more roots' };
+  return { class: 'drift', note: 'same items, other content, and no redaction root explains it' };
+}
+
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Redaction roots a drifted item's text may have been sent with (CUT-02): for each path under the workspace that the
+ * text names, its shallowest directory that no longer exists, a worktree or repo deleted since. Only a candidate;
+ * the proof is a rescan that gives exactly the cloud's sha.
+ */
+export async function redactionCandidates({ texts, workspace }) {
+  const base = workspace.replace(/\/+$/, '');
+  const named = new RegExp(`${escapeRegExp(base)}((?:/[^\\s"'\`<>()\\[\\]{},;/]+)+)`, 'g');
+  const found = new Set();
+  for (const text of texts) {
+    for (const match of String(text).matchAll(named)) {
+      let dir = base;
+      for (const part of match[1].split('/').filter(Boolean)) {
+        if (part === '.' || part === '..') break;
+        dir = path.join(dir, part);
+        const info = await lstat(dir).catch((error) => (error.code === 'ENOENT' ? null : error));
+        if (info === null) found.add(dir);
+        if (!info?.isDirectory?.()) break;
+      }
+    }
+  }
+  return [...found].sort();
+}
+
+/**
+ * The raw text behind each drifted item, from the import's snapshot: a task channel's posts as blocks, a
+ * conversation's message bodies. Keyed by `itemId`. A project channel (chat) has none here.
+ */
+export async function driftTexts({ snapshotHubDir, snapshotRoots }, drift) {
+  const texts = new Map();
+  const channels = new Set(drift.filter((entry) => entry.family === 'posts.byChannel').map((entry) => entry.item));
+  if (channels.size) {
+    const { files } = await channelFiles(snapshotRoots);
+    for (const file of files.filter((entry) => channels.has(`task:${entry.key}`))) {
+      texts.set(itemId('posts.byChannel', `task:${file.key}`), splitPosts(await readFile(file.file, 'utf8'), file.mtimeMs).map((post) => post.text));
+    }
+  }
+  const topics = new Set(drift.filter((entry) => entry.family === 'messages.byTopic').map((entry) => entry.item));
+  if (topics.size) {
+    for (const message of new HubDbReader({ hubDir: snapshotHubDir }).read((snapshot) => snapshot.messagesSince(0))) {
+      if (!topics.has(message.topic)) continue;
+      const id = itemId('messages.byTopic', message.topic);
+      texts.set(id, [...(texts.get(id) || []), message.body]);
+    }
+  }
+  return texts;
+}
+
+// Key order carries no meaning: the cloud answers receipt states and topics in its own order.
+const canonical = (value) => {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value ?? null;
+};
+const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+
+const differingKeys = (local = {}, cloud = {}) => [...new Set([...Object.keys(local), ...Object.keys(cloud)])].sort().filter((key) => !same(local[key], cloud[key]));
+
+function named(mismatches, family, items) {
+  mismatches.push(...items.slice(0, NAMED));
+  if (items.length > NAMED) mismatches.push({ family, item: `… ${items.length - NAMED} more`, local: null, cloud: null });
+}
+
+function compareMap(mismatches, family, local = {}, cloud = {}) {
+  named(mismatches, family, differingKeys(local, cloud).map((key) => ({ family, item: key, local: local[key] ?? null, cloud: cloud[key] ?? null })));
+}
+
+/**
+ * Local scan against the cloud's answer (GET /connector/parity?view=reconcile), and the scan's own rows against the
+ * sources counted without it. Every differing channel and conversation is classified (`classify`): `retired` and
+ * `redacted` ones are listed and allowed, `drift`, `missing` and `unexplained` ones are mismatches. The `channels`,
+ * `posts` and `messages` totals differ only by what is retired or redacted, so the counts must add up to exactly that.
+ * Status: `equal` (nothing differs), `explained` (only retired or redacted items do) or `mismatch`. Every other
+ * family, the receipt counts, the cut list, every logged item being in the cloud's state tables and every source row
+ * being accounted for are compared exactly, as before. `sent` (the live runner store: `sentAs(key, type)`) proves
+ * which items the cloud acknowledged; `onDisk` maps each cloud-only channel to `channelOnDisk`; `redacted` maps the
+ * `itemId` of each item a rescan proved to the roots it took.
+ */
+export function compareReconcile({ local, cloud, counts, report, sent = null, onDisk = {}, redacted = new Map() }) {
+  const mismatches = [];
+  const items = [];
+  for (const [family, localMap, cloudMap, keysOf] of [
+    ['posts.byChannel', local.view.posts.byChannel, cloud.view?.posts?.byChannel, local.keys?.posts],
+    ['messages.byTopic', local.view.messages.byTopic, cloud.view?.messages?.byTopic, local.keys?.messages],
+  ]) {
+    for (const item of differingKeys(localMap, cloudMap)) {
+      const [l, c] = [localMap[item] ?? null, cloudMap?.[item] ?? null];
+      items.push({ family, item, local: l, cloud: c, ...classify({ family, item, local: l, cloud: c, keys: keysOf?.get(item) ?? [], sent, onDisk, redacted }) });
+    }
+  }
+  const retired = items.filter((entry) => entry.class === 'retired');
+  const proven = items.filter((entry) => entry.class === 'redacted');
+  const drift = items.filter((entry) => entry.class === 'drift');
+  const failing = items.filter((entry) => ['drift', 'missing', 'unexplained'].includes(entry.class));
+  const failed = (family) => failing.some((entry) => entry.family === family);
+  const retiredPosts = retired.reduce((n, entry) => n + entry.cloud.count, 0);
+  const totals = {
+    channels: local.view.channels.count + retired.length === cloud.view?.channels?.count && !failed('posts.byChannel'),
+    posts: local.view.posts.count + retiredPosts === cloud.view?.posts?.count && !failed('posts.byChannel'),
+    messages: local.view.messages.count === cloud.view?.messages?.count && !failed('messages.byTopic'),
+  };
+  const sources = Object.fromEntries(Object.entries(report.sources).map(([source, stats]) => {
+    const accounted = stats.planned + stats.unchanged + Object.values(stats.skipped).reduce((n, v) => n + v, 0)
+      + Object.values(stats.refused).reduce((n, v) => n + v, 0);
+    return [source, { counted: counts[source] ?? null, read: stats.read, accounted }];
+  }));
+  for (const [source, row] of Object.entries(sources)) {
+    if (row.counted !== null && row.counted !== row.read) mismatches.push({ family: 'source', item: source, local: row.read, cloud: null, note: `${row.counted} rows in the source, ${row.read} read` });
+    if (row.read !== row.accounted) mismatches.push({ family: 'source', item: source, local: row.accounted, cloud: null, note: `${row.read} read, ${row.accounted} accounted for` });
+  }
+  for (const family of ['actors', 'agentRows', 'personas', 'statusOverrides']) {
+    if (!same(local.view[family], cloud.view?.[family])) mismatches.push({ family, local: local.view[family], cloud: cloud.view?.[family] ?? null });
+  }
+  for (const family of ['channels', 'posts', 'messages']) {
+    const { count, sha } = local.view[family];
+    const other = cloud.view?.[family] ?? {};
+    if ((count !== other.count || sha !== other.sha) && !totals[family]) {
+      const note = retired.length ? { note: `${retired.length} retired channel(s) do not explain the difference` } : {};
+      mismatches.push({ family, class: 'unexplained', local: { count, sha }, cloud: { count: other.count ?? null, sha: other.sha ?? null }, ...note });
+    }
+  }
+  for (const family of ['posts.byChannel', 'messages.byTopic']) named(mismatches, family, failing.filter((entry) => entry.family === family));
+  compareMap(mismatches, 'facts', local.view.facts, cloud.view?.facts);
+  compareMap(mismatches, 'receipts', local.receipts, cloud.receipts);
+  // A retired channel's cut posts stay in Pulse's cut list; the rescan cannot have them.
+  const retiredPrefixes = retired.map((entry) => `post:${entry.item.slice('task:'.length)}:`);
+  const cloudCut = (cloud.cut ?? []).filter((key) => !retiredPrefixes.some((prefix) => key.startsWith(prefix)));
+  if (!same(local.cut, cloudCut)) mismatches.push({ family: 'cut', local: local.cut, cloud: cloud.cut ?? null });
+  for (const [family, absent] of Object.entries(cloud.missing || {})) {
+    mismatches.push({ family: `missing.${family}`, local: null, cloud: absent, note: 'in the log but not in the state tables' });
+  }
+  const classes = { retired: retired.length, redacted: proven.length, drift: 0, missing: 0, unexplained: 0 };
+  for (const entry of failing) classes[entry.class] += 1;
+  const status = mismatches.length ? 'mismatch' : retired.length || proven.length ? 'explained' : 'equal';
+  return {
+    status,
+    mismatches,
+    sources,
+    classes,
+    retired: retired.map((entry) => ({ channel: entry.item, posts: entry.cloud.count })),
+    redacted: proven.map(({ family, item, local: l, roots }) => ({ family, item, count: l.count, roots })),
+    drift: drift.map(({ family, item, local: l, cloud: c }) => ({ family, item, count: l.count, local: l.sha, cloud: c.sha })),
+  };
+}
+
+/** A reconcile that the cutover may go on from: nothing differs, or only retired and redacted items do. */
+export const reconcilePasses = (status) => status === 'equal' || status === 'explained';