@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.0.0

package/src/lib/mirrorContract.js

@@ -0,0 +1,513 @@
+import { readFileSync } from 'node:fs';
+
+export const MIRROR_CONTRACT = Object.freeze(
+  JSON.parse(readFileSync(new URL('./mirror-contract.json', import.meta.url), 'utf8'))
+);
+export const MIRROR_LIMITS = MIRROR_CONTRACT.limits;
+export const MIRROR_PATH = MIRROR_CONTRACT.route.path;
+export const MIRROR_SCOPE = MIRROR_CONTRACT.route.scope;
+export const MIRROR_KINDS = MIRROR_CONTRACT.request.properties.items.items.properties.kind.enum;
+
+export const CONTRACT_VERSION = MIRROR_CONTRACT.contractVersion;
+export const CONTRACT_HEADER = MIRROR_CONTRACT.handshake.requestHeader.toLowerCase();
+export const CONTRACT_ACCEPTS_HEADER = MIRROR_CONTRACT.handshake.responseHeader.toLowerCase();
+
+/** The contract's secret table, compiled: `pattern` replaces every match, `probe` tests for one. */
+export const SECRET_RULES = Object.freeze(MIRROR_CONTRACT.privacy.secrets.map((rule) => Object.freeze({
+  id: rule.id,
+  replacement: rule.replacement,
+  pattern: new RegExp(rule.regex, rule.flags),
+  probe: new RegExp(rule.regex, rule.flags.replace('g', '')),
+})));
+export const CREDENTIAL_REPLACEMENT = '[redacted:credential]';
+
+const SECRET_KEYS = MIRROR_CONTRACT.privacy.secretKeys;
+const SECRET_KEY_FAMILIES = SECRET_KEYS.families.map((family) => ({
+  id: family.id,
+  replacement: family.replacement,
+  strict: family.strict === true,
+  pattern: new RegExp(family.regex, family.flags),
+}));
+const PLACEHOLDER = new RegExp(SECRET_KEYS.placeholder.regex, SECRET_KEYS.placeholder.flags);
+const NON_SECRET_WORD = new RegExp(SECRET_KEYS.nonSecretWords.regex, SECRET_KEYS.nonSecretWords.flags);
+const LINE_NET = MIRROR_CONTRACT.privacy.lineNet;
+const LINE_NET_FAMILIES = new Set(LINE_NET.families);
+const LINE_KEY = new RegExp(LINE_NET.key.regex, LINE_NET.key.flags);
+const LINE_SCOPE = new RegExp(LINE_NET.scope.regex, LINE_NET.scope.flags);
+const LINE_LITERAL = new RegExp(LINE_NET.literal.regex, LINE_NET.literal.flags);
+const LINE_VALUE = new RegExp(LINE_NET.value.regex, LINE_NET.value.flags);
+const BLOCK = LINE_NET.block;
+const BLOCK_OPEN = new RegExp(BLOCK.open.regex, BLOCK.open.flags);
+const BLOCK_RUN = new RegExp(BLOCK.run.regex, BLOCK.run.flags);
+const BLOCK_FENCE = new RegExp(BLOCK.fence.regex);
+export const WITHHELD_MARKER = BLOCK.withheld;
+const V1_WITHHOLD = new RegExp(MIRROR_CONTRACT.privacy.v1Withhold.pattern, MIRROR_CONTRACT.privacy.v1Withhold.flags.replace('g', ''));
+const GATE_MARKERS = new RegExp(MIRROR_CONTRACT.privacy.v1Gate.markers.regex, MIRROR_CONTRACT.privacy.v1Gate.markers.flags);
+const LINE_SPLIT = /(\r\n?|\n)/;
+const SPANS_LINES = /[\r\n]/;
+
+function secretKeyFamily(key) {
+  if (typeof key !== 'string' || key.length > 200) return null;
+  const name = key.replace(/([a-z0-9])([A-Z])/g, '$1_$2');
+  return SECRET_KEY_FAMILIES.find((entry) => entry.pattern.test(name)) ?? null;
+}
+
+/** The family's replacement for a non-empty string that is not a placeholder (nor, outside a strict family, `required`). */
+export function secretLeafReplacement(family, value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed || PLACEHOLDER.test(trimmed) || (!family.strict && NON_SECRET_WORD.test(trimmed))) return null;
+  return family.replacement;
+}
+
+/**
+ * The replacement for an object entry whose key names a secret (DB_PASSWORD, apiKey, client_secret) and whose value is
+ * a non-empty string that is not a placeholder (nor, outside the strict password family, a word like `required`);
+ * null for any other entry.
+ */
+export function secretKeyReplacement(key, value) {
+  if (typeof value !== 'string') return null;
+  const family = secretKeyFamily(key);
+  return family ? secretLeafReplacement(family, value) : null;
+}
+
+/** The family whose replacement every string leaf of an array or object under `key` takes (credentials: {user, pass}). */
+export function secretSubtreeFamily(key, value) {
+  if (!value || typeof value !== 'object') return null;
+  const family = secretKeyFamily(key);
+  return family && LINE_NET_FAMILIES.has(family.id) ? family : null;
+}
+
+/**
+ * The array or object under a secret-style key with every string leaf through secretLeafReplacement, and any other
+ * string or key through `text`; null when `key` names no such family or the value is not an array or object.
+ */
+export function redactSecretSubtree(key, value, text) {
+  const family = secretSubtreeFamily(key, value);
+  if (!family) return null;
+  const walk = (entry) => {
+    if (typeof entry === 'string') return secretLeafReplacement(family, entry) ?? text(entry);
+    if (Array.isArray(entry)) return entry.map(walk);
+    if (entry && typeof entry === 'object') return Object.fromEntries(Object.entries(entry).map(([name, item]) => [text(name), walk(item)]));
+    return entry;
+  };
+  return walk(value);
+}
+
+/**
+ * The contract's line net, after the table: on each line naming a secret-style key, every quoted literal that is not a
+ * placeholder, and every unquoted value after `=` or `:` in that key's statement, takes the net replacement.
+ */
+export function redactSecretLines(input) {
+  if (!LINE_KEY.test(input)) return { text: input, redactions: 0 };
+  let redactions = 0;
+  const replace = (...match) => {
+    const groups = match.at(-1);
+    if (groups.skip !== undefined) return groups.skip;
+    redactions += 1;
+    return `${groups.keep}${LINE_NET.replacement}${groups.tail ?? ''}`;
+  };
+  const text = input.split(LINE_SPLIT).map((part, index) => (index % 2 === 0 && LINE_KEY.test(part)
+    ? part.replace(LINE_SCOPE, (scope) => scope.replace(LINE_VALUE, replace)).replace(LINE_LITERAL, replace)
+    : part)).join('');
+  return { text, redactions };
+}
+
+const indentOf = (line) => line.length - line.trimStart().length;
+
+/** The line holding `at`: where it ends and where the next one starts (-1 on the last line); \r\n, \r and \n end a line. */
+function lineAt(text, at) {
+  for (let end = at; end < text.length; end += 1) {
+    const code = text.charCodeAt(end);
+    if (code === 10) return { end, next: end + 1 };
+    if (code === 13) return { end, next: text.charCodeAt(end + 1) === 10 ? end + 2 : end + 1 };
+  }
+  return { end: text.length, next: -1 };
+}
+
+/** The line end just before `at`, the start of a line. */
+const lineEndBefore = (text, at) => (text[at - 1] === '\n' && text[at - 2] === '\r' ? '\r\n' : text[at - 1]);
+
+/** Where the line holding each offset starts, for offsets met in increasing order: one forward pass over the string. */
+function lineStarts(text) {
+  let scanned = 0;
+  let start = 0;
+  return (at) => {
+    if (at < scanned) [scanned, start] = [0, 0];
+    for (; scanned < at; scanned += 1) {
+      const code = text.charCodeAt(scanned);
+      if (code === 10 || code === 13) start = scanned + 1;
+    }
+    return start;
+  };
+}
+
+/** Where the quote opened before `start` closes, a backslash escaping the next character in a single quote; -1 if not by `limit`. */
+function closingQuote(text, start, quote, limit) {
+  if (quote.length === 3) {
+    const at = text.indexOf(quote, start);
+    return at > limit ? -1 : at;
+  }
+  for (let at = start; at < text.length && at <= limit; at += 1) {
+    if (text[at] === '\\') at += 1;
+    else if (text[at] === quote) return at;
+  }
+  return -1;
+}
+
+/**
+ * Whether `quote` opens an odd number of times in text[from, to): the key after it sits inside such a literal. `seen`
+ * carries the scan per quote between calls on one string, so keys met in order cost one pass over each line.
+ */
+function insideLiteral(text, from, to, quote, seen) {
+  let state = seen.get(quote);
+  if (!state || state.from !== from || state.at > to) state = { from, at: from, open: false };
+  let { at, open } = state;
+  for (; at < to; at += 1) {
+    if (quote.length === 1 && text[at] === '\\') at += 1;
+    else if (text.startsWith(quote, at)) {
+      open = !open;
+      at += quote.length - 1;
+    }
+  }
+  seen.set(quote, { from, at, open });
+  return open;
+}
+
+/**
+ * The lines from `from` that belong to a block: up to (not including) the first line `ends` says closes it. Returns the
+ * offset of that line, or null when the block runs to the end of the string or past maxChars.
+ */
+function blockLines(text, from, ends) {
+  for (let at = from; at < text.length;) {
+    const { end, next } = lineAt(text, at);
+    if (ends(text.slice(at, end))) return at;
+    if (end - from > BLOCK.maxChars || next === -1) return null;
+    at = next;
+  }
+  return null;
+}
+
+/**
+ * What a block opener spans: { from, to, replacement }; { skip } for a quote that closes on its line within maxInline;
+ * false when the value opens no block; null when the block has no end within maxChars or before the end of the string.
+ * `lineStart` gives the start of the key's line (lineStarts).
+ */
+function blockSpan(text, match, literals, lineStart) {
+  const { groups } = match;
+  const start = match.index + match[0].length;
+  const limit = start + BLOCK.maxChars;
+  const span = (from, to, replacement) => (text.slice(from, to) === replacement ? false : { from, to, replacement });
+  const keyAt = match.index + (groups.lo?.length ?? 0);
+  const keyLine = lineStart(match.index);
+  const label = groups.lo !== undefined && (groups.lc !== undefined || groups.le !== undefined);
+  if (groups.close !== undefined) {
+    const keyQuoted = groups.kq && text[keyAt - 1] === groups.kq;
+    if (insideLiteral(text, keyLine, keyQuoted ? keyAt - 1 : keyAt, groups.close, literals)) return false;
+    const close = closingQuote(text, start, groups.close, limit);
+    if (close === -1) return null;
+    const inline = groups.close.length === 1 && close - start <= BLOCK.maxInline && !SPANS_LINES.test(text.slice(start, close));
+    return inline ? { skip: close + 1 } : span(start, close, BLOCK.replacement);
+  }
+  if (groups.run !== undefined) {
+    BLOCK_RUN.lastIndex = start;
+    const run = text.match(BLOCK_RUN)[0];
+    return run.length > BLOCK.maxChars ? null : span(start, start + run.length, BLOCK.replacement);
+  }
+  if (groups.inline !== undefined) {
+    if (!label) return false;
+    const { end } = lineAt(text, start);
+    return PLACEHOLDER.test(text.slice(start, end).trim()) ? false : span(start, end, BLOCK.replacement);
+  }
+  const from = lineAt(text, start).next;
+  if (from === -1 || from >= text.length) return false;
+  if (groups.cont !== undefined) {
+    for (let at = from; ;) {
+      const { end, next } = lineAt(text, at);
+      if (end - from > BLOCK.maxChars) return null;
+      if (end === at || text[end - 1] !== '\\') return span(from, end, BLOCK.replacement);
+      if (next === -1) return null;
+      at = next;
+    }
+  }
+  if (groups.heredoc !== undefined) {
+    const to = blockLines(text, from, (line) => line.trim() === groups.tag || line.trim() === `${groups.tag})`);
+    if (to === null) return null;
+    return to === from ? false : span(from, to, `${BLOCK.replacement}${lineEndBefore(text, to)}`);
+  }
+  const prefix = text.slice(keyLine, keyAt);
+  const depth = quoteDepth(prefix);
+  const content = lineContent(depth, indentOf(prefix), indentOf(depth ? afterQuotes(prefix, depth) : prefix));
+  let lead = null;
+  const to = blockLines(text, from, (line) => {
+    const { body, indent } = content(line);
+    if (!body.trim()) return false;
+    if (indentOf(body) <= indent) return true;
+    lead ??= line.slice(0, line.length - body.trimStart().length);
+    return false;
+  });
+  if (lead !== null) return to === null ? null : span(from, to, `${lead}${BLOCK.replacement}${lineEndBefore(text, to)}`);
+  return groups.yaml === '' ? nextLineValue(text, from, content, label, span) : false;
+}
+
+/**
+ * The text after the first `depth` blockquote markers of a line (each after at most 40 spaces or tabs); null when the
+ * line has fewer.
+ */
+function afterQuotes(line, depth) {
+  let at = 0;
+  for (let found = 0; found < depth; found += 1) {
+    let next = at;
+    while (next - at < 40 && (line[next] === ' ' || line[next] === '\t')) next += 1;
+    if (line[next] !== '>') return null;
+    at = next + 1;
+  }
+  return line.slice(at);
+}
+
+/** How many blockquote markers open a line, up to maxQuoteDepth. */
+function quoteDepth(line) {
+  let depth = 0;
+  while (depth < BLOCK.maxQuoteDepth && afterQuotes(line, depth + 1) !== null) depth += 1;
+  return depth;
+}
+
+/**
+ * For a key line opening with `depth` quote markers: a following line's body (after the same markers when it carries
+ * them) and the indentation it must exceed to belong to the key's block (the key line's, measured the same way).
+ */
+const lineContent = (depth, rawIndent, quotedIndent) => (line) => {
+  const quoted = depth ? afterQuotes(line, depth) : null;
+  return quoted === null ? { body: line, indent: rawIndent } : { body: quoted, indent: quotedIndent };
+};
+
+/**
+ * After an empty value with no deeper line: a fenced block on the next non-blank line is the block, else a label takes
+ * that line's text; false when neither applies, null for a fence with no close.
+ */
+function nextLineValue(text, from, content, label, span) {
+  for (let at = from; at < text.length;) {
+    const { end, next } = lineAt(text, at);
+    const line = text.slice(at, end);
+    const { body } = content(line);
+    const value = body.trim();
+    if (value) {
+      const lead = line.slice(0, line.length - body.trimStart().length);
+      const fence = value.match(BLOCK_FENCE);
+      if (fence) return fenceSpan(text, next, fence[1], content, lead, span);
+      return label && !PLACEHOLDER.test(value) ? span(at + lead.length, end, BLOCK.replacement) : false;
+    }
+    if (end - from > BLOCK.maxChars || next === -1) return false;
+    at = next;
+  }
+  return false;
+}
+
+/** The lines from `from` up to the fence that closes `marker`, replaced by one line with the fence's lead. */
+function fenceSpan(text, from, marker, content, lead, span) {
+  if (from === -1 || from >= text.length) return null;
+  const to = blockLines(text, from, (line) => {
+    const value = content(line).body.trim();
+    return value.length >= marker.length && value[0] === marker[0] && [...value].every((char) => char === marker[0]);
+  });
+  if (to === null) return null;
+  return to === from ? false : span(from, to, `${lead}${BLOCK.replacement}${lineEndBefore(text, to)}`);
+}
+
+/**
+ * The v1 gate, last on every string: whether v1's withhold pattern matches the text once every marker (with the quotes
+ * around it) is deleted. When it does, the item holding the text is withheld, as v1 would have withheld it.
+ */
+export function v1GateFires(text) {
+  return V1_WITHHOLD.test(text.replace(GATE_MARKERS, ''));
+}
+
+/**
+ * The contract's block pass, before the table: a secret-style key whose value opens a block (a YAML block scalar, a
+ * quote that spans lines or runs long, a triple quote, a heredoc, a backslash continuation, a long unquoted run) has the
+ * block replaced to its end. A block with no end found stops the text at the value with the withheld marker, and
+ * `withheld` says the item holding it is to be withheld.
+ */
+export function redactSecretBlocks(input) {
+  if (!LINE_KEY.test(input)) return { text: input, redactions: 0, withheld: false };
+  let text = '';
+  let at = 0;
+  let skip = 0;
+  let redactions = 0;
+  const literals = new Map();
+  const lineStart = lineStarts(input);
+  for (const match of input.matchAll(BLOCK_OPEN)) {
+    if (match.index < at || match.index < skip) continue;
+    const span = blockSpan(input, match, literals, lineStart);
+    if (span === null) {
+      const value = match.index + match[0].length - match.groups.value.length;
+      return { text: `${text}${input.slice(at, value)}${BLOCK.withheld}`, redactions: redactions + 1, withheld: true };
+    }
+    if (!span) continue;
+    if (span.skip !== undefined) {
+      skip = span.skip;
+      continue;
+    }
+    text += `${input.slice(at, span.from)}${span.replacement}`;
+    at = span.to;
+    redactions += 1;
+  }
+  return { text: `${text}${input.slice(at)}`, redactions, withheld: false };
+}
+
+/** `mirror/1-2` as { min: 1, max: 2 }; anything else is null. */
+export function parseAccepts(value) {
+  const match = String(value ?? '').trim().match(/^mirror\/([1-9][0-9]{0,3})(?:-([1-9][0-9]{0,3}))?$/);
+  if (!match) return null;
+  const min = Number(match[1]);
+  const max = Number(match[2] ?? match[1]);
+  return min <= max ? { min, max } : null;
+}
+
+const REJECT_KEYS = new Set(MIRROR_CONTRACT.privacy.rejectKeys);
+const SERVER_PATH = new RegExp(MIRROR_CONTRACT.privacy.rejectPathPattern);
+const NESTED_STRING_MAX = 2000;
+const NESTED_PROPERTIES_MAX = 16;
+const ENVELOPE_SLACK = 512;
+const INVALID = Symbol('invalid');
+const FREE = Object.freeze({ type: ['string', 'number', 'boolean', 'null', 'object', 'array'] });
+
+export function pathRejected(text) {
+  return SERVER_PATH.test(text);
+}
+
+/**
+ * Whether anything the secret table or a held credential matches is left, or a block with no end was withheld;
+ * redaction runs first, so for the table this is a backstop.
+ */
+export function contentWithheld(value, secrets = []) {
+  if (typeof value === 'string') {
+    return value.includes(WITHHELD_MARKER) || SECRET_RULES.some((rule) => rule.probe.test(value)) || secrets.some((secret) => secret && value.includes(secret));
+  }
+  if (Array.isArray(value)) return value.some((entry) => contentWithheld(entry, secrets));
+  if (value && typeof value === 'object') {
+    return Object.entries(value).some(([key, entry]) => contentWithheld(key, secrets) || contentWithheld(entry, secrets));
+  }
+  return false;
+}
+
+function typesOf(schema) {
+  if (Array.isArray(schema.type)) return schema.type;
+  return schema.type ? [schema.type] : FREE.type;
+}
+
+function truncate(value, max) {
+  if (value.length <= max) return value;
+  const points = Array.from(value);
+  return points.length <= max ? value : points.slice(0, max).join('');
+}
+
+function inRange(schema, value) {
+  return (schema.minimum === undefined || value >= schema.minimum) && (schema.maximum === undefined || value <= schema.maximum);
+}
+
+function project(schema, value, depth) {
+  if (value === undefined || depth > MIRROR_LIMITS.maxDepth) return INVALID;
+  const types = typesOf(schema);
+  if (value === null) return types.includes('null') ? null : INVALID;
+  if (typeof value === 'string') {
+    if (!types.includes('string')) return INVALID;
+    const text = truncate(value, schema.maxLength ?? NESTED_STRING_MAX);
+    if (schema.enum && !schema.enum.includes(text)) return INVALID;
+    if (schema.pattern && !new RegExp(schema.pattern).test(text)) return INVALID;
+    return text;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return INVALID;
+    let number;
+    if (types.includes('number')) number = value;
+    else if (types.includes('integer')) number = Math.round(value);
+    else return INVALID;
+    if (!inRange(schema, number) || (schema.enum && !schema.enum.includes(number))) return INVALID;
+    return number;
+  }
+  if (typeof value === 'boolean') return types.includes('boolean') ? value : INVALID;
+  if (Array.isArray(value)) {
+    if (!types.includes('array')) return INVALID;
+    return value
+      .slice(0, schema.maxItems ?? 100)
+      .map((item) => project(schema.items || FREE, item, depth + 1))
+      .filter((item) => item !== INVALID);
+  }
+  if (typeof value === 'object') {
+    if (!types.includes('object')) return INVALID;
+    const out = {};
+    if (schema.properties) {
+      for (const [key, child] of Object.entries(schema.properties)) {
+        if (!Object.hasOwn(value, key)) continue;
+        const projected = project(child, value[key], depth + 1);
+        if (projected !== INVALID) out[key] = projected;
+      }
+      return (schema.required || []).every((key) => Object.hasOwn(out, key)) ? out : INVALID;
+    }
+    const limit = schema.maxProperties ?? NESTED_PROPERTIES_MAX;
+    for (const [key, entry] of Object.entries(value)) {
+      if (Object.keys(out).length >= limit) break;
+      if (REJECT_KEYS.has(key)) continue;
+      const projected = project(FREE, entry, depth + 1);
+      if (projected !== INVALID) out[key] = projected;
+    }
+    return out;
+  }
+  return INVALID;
+}
+
+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));
+  return false;
+}
+
+function bytes(value) {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8') + ENVELOPE_SLACK;
+}
+
+function fit(kind, data, limit) {
+  if (bytes(data) <= limit) return data;
+  if ((kind === 'message' || kind === 'inbox') && typeof data.body === 'string') {
+    let body = data.body;
+    while (body.length > 0 && bytes({ ...data, body }) > limit) body = Array.from(body).slice(0, Math.floor(Array.from(body).length * 0.8)).join('');
+    return { ...data, body };
+  }
+  if (kind === 'rule_pack' && Array.isArray(data.rules)) {
+    const rules = [...data.rules];
+    while (rules.length > 0 && bytes({ ...data, rules }) > limit) rules.pop();
+    return { ...data, rules };
+  }
+  return null;
+}
+
+export function itemBytes(data) {
+  return bytes(data);
+}
+
+/**
+ * One row of a graph_window section, or one nested object such as its manager, checked on its own so a single bad row
+ * is dropped and counted instead of withholding the whole chunk. `depth` is where the value sits inside item data.
+ */
+export function sanitizePart(schema, value, { secrets = [], depth = 3 } = {}) {
+  const projected = project(schema, value, depth);
+  if (projected === INVALID) return { error: 'invalid_item' };
+  if (leaksPath(projected)) return { error: 'path_not_redacted' };
+  if (contentWithheld(projected, secrets)) return { error: 'content_withheld' };
+  return { data: projected };
+}
+
+export function sanitizeItem(kind, data, { secrets = [] } = {}) {
+  const schema = MIRROR_CONTRACT.kinds[kind];
+  if (!schema) return { error: 'invalid_item' };
+  const projected = project({ type: 'object', properties: schema.properties, required: schema.required }, data, 1);
+  if (projected === INVALID) return { error: 'invalid_item' };
+  if (leaksPath(projected)) return { error: 'path_not_redacted' };
+  if (contentWithheld(projected, secrets)) return { error: 'content_withheld' };
+  const limit = kind === 'rule_pack' ? MIRROR_LIMITS.maxRulePackBytes : MIRROR_LIMITS.maxItemBytes;
+  const fitted = fit(kind, projected, limit);
+  if (!fitted) return { error: 'item_too_large' };
+  return { data: fitted };
+}

package/src/lib/mirrorDaemon.js

@@ -0,0 +1,127 @@
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { discoverLocalHub, LocalHubReader } from './localHub.js';
+import { MIRROR_SCOPE } from './mirrorContract.js';
+import { MirrorService } from './mirrorService.js';
+import { MirrorSource } from './mirrorSource.js';
+import { MirrorSync } from './mirrorSync.js';
+import { pairedStatus } from './pairedConfig.js';
+
+export const MIRROR_STATE_FILE = 'mirror-state.json';
+
+export function mirrorEnabled(config) {
+  return config?.mirror?.localHub === true;
+}
+
+export function localScopeCheckApplies(config) {
+  return !config?.paired?.target?.devOrg;
+}
+
+export class MirrorController {
+  constructor({
+    directory,
+    transportFactory,
+    tokenStore,
+    discover = discoverLocalHub,
+    createReader = (options) => new LocalHubReader(options),
+    serviceOptions = {},
+    log = () => {},
+  }) {
+    this.directory = directory;
+    this.transportFactory = transportFactory;
+    this.tokenStore = tokenStore;
+    this.discover = discover;
+    this.createReader = createReader;
+    this.serviceOptions = serviceOptions;
+    this.log = log;
+    this.stateFile = path.join(directory, MIRROR_STATE_FILE);
+    this.service = null;
+    this.key = null;
+    this.blockedCode = null;
+    this.state = { state: 'off' };
+    this.wanted = null;
+    this.applying = null;
+  }
+
+  /**
+   * Hands the mirror the heartbeat's config without waiting on it. The newest config is applied in a loop of its own,
+   * so discovery, a restart or a pass that is slow to stop never holds the heartbeat, its claims or its presence.
+   * Returns the state of the last config applied.
+   */
+  update(config) {
+    this.wanted = { config };
+    if (!this.applying) {
+      this.applying = (async () => {
+        while (this.wanted) {
+          const { config: next } = this.wanted;
+          this.wanted = null;
+          try {
+            this.state = await this.apply(next);
+          } catch (error) {
+            this.state = { state: 'blocked', code: error.code || 'HUB_MIRROR_FAILED' };
+          }
+        }
+        this.applying = null;
+      })();
+    }
+    return this.state;
+  }
+
+  /** The state once every config handed to update() so far is applied. */
+  async settled() {
+    while (this.applying) await this.applying;
+    return this.state;
+  }
+
+  async apply(config) {
+    try {
+      if (!mirrorEnabled(config) || !pairedStatus(config).ok) {
+        await this.#stopService();
+        this.blockedCode = null;
+        return { state: 'off' };
+      }
+      if (localScopeCheckApplies(config) && !(await this.tokenStore.scopes()).includes(MIRROR_SCOPE)) {
+        throw new HubError('HUB_MIRROR_SCOPE_MISSING', 'The Pulse sign-in lacks the mirror scope; run `agentpulse pulse login`');
+      }
+      const hub = await this.discover({ config });
+      const roots = (config.localRoots || []).map((root) => root.canonicalRoot).filter(Boolean).sort();
+      const key = JSON.stringify([config.paired.machineId, config.paired.policyVersion, config.paired.baseUrl, hub.dir, hub.port, roots]);
+      this.blockedCode = null;
+      if (this.service && this.key === key) {
+        return this.service.blocked ? { state: 'blocked', code: this.service.blocked.code } : { state: 'running' };
+      }
+      await this.#stopService();
+      const reader = this.createReader({ dir: hub.dir, port: hub.port });
+      const transport = await this.transportFactory(config);
+      const heldSecrets = () => transport.auth?.heldSecrets?.() ?? [];
+      const source = new MirrorSource({ reader, workspace: path.dirname(hub.dir), approvedRoots: roots, heldSecrets });
+      const sync = new MirrorSync({ source, transport, stateFile: this.stateFile });
+      this.service = new MirrorService({ sync, reader, log: this.log, ...this.serviceOptions });
+      this.key = key;
+      this.service.start();
+      return { state: 'running' };
+    } catch (error) {
+      await this.#stopService();
+      const code = error.code || 'HUB_MIRROR_FAILED';
+      if (code !== this.blockedCode) {
+        this.blockedCode = code;
+        this.log('mirror_blocked', { code });
+        await new MirrorSync({ stateFile: this.stateFile }).recordError(error).catch(() => {});
+      }
+      return { state: 'blocked', code };
+    }
+  }
+
+  async stop() {
+    this.wanted = null;
+    await this.settled();
+    await this.#stopService();
+  }
+
+  async #stopService() {
+    const service = this.service;
+    this.service = null;
+    this.key = null;
+    if (service) await service.stop();
+  }
+}