@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.1.2

package/src/clients/hub.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+// agents-hub. Usage:
+//   node hub.mjs serve [--port 8890]                       map UI at http://127.0.0.1:8890  (?demo = scripted mockup)
+//   node hub.mjs map [--hours 6]                           text summary of the same map, for a chat session
+//   node hub.mjs request --from <id> --kind platform|script|rule --title "…" [--files a,b]
+//   node hub.mjs post --from <id> --to <id|*> --type NOTE --text "…"
+//   node hub.mjs wait --for <id> [--timeout 900]
+//   node hub.mjs bus publish|ask|listen|reply|register|who  durable addressed messages with acknowledgements
+//
+// The Pulse runner's thin client for `hub.mjs`: the same commands, flags, output and exit codes, carried over HTTP to
+// the runner on 127.0.0.1. It opens no database. Writes made while the runner is down go to an append-only spool
+// that the runner imports once, under the id printed here. Node built-ins only, so it runs from any folder.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const PULSE = /*PULSE_CLIENT_CONFIG*/ null;
+const config = PULSE || JSON.parse(process.env.PULSE_CLIENT_CONFIG || 'null');
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const opt = (name, fallback) => { const i = args.indexOf(`--${name}`); return i > 0 && args[i + 1] !== undefined ? args[i + 1] : fallback; };
+const VALUE_OPTIONS = new Set(['id', 'as', 'reply', 'body', 'name', 'reaction', 'topic', 'type', 'ttl-ms', 'role', 'topics', 'parent',
+  'timeout', 'for', 'from', 'to', 'text', 'kind', 'title', 'files', 'hours', 'port', 'supersedes', 'minutes'].map((o) => `--${o}`));
+const FLAGS = new Set(['--ack', '--reload', '--all']);
+/**
+ * Bare words after the subcommand, e.g. the answer in `bus reply --id m-… --as <me> "<answer>"`. Only known options
+ * take a value; after `--` everything is the answer, so text like "--force is needed" stays whole.
+ */
+function positional(from) {
+  const out = [];
+  for (let i = from; i < args.length; i++) {
+    if (args[i] === '--') { out.push(...args.slice(i + 1)); break; }
+    if (VALUE_OPTIONS.has(args[i])) { i++; continue; }
+    if (FLAGS.has(args[i])) continue;
+    out.push(args[i]);
+  }
+  return out.join(' ').trim();
+}
+
+// The hub's own checks (core/ids.mjs at 6b2fb0b), so a write spooled offline is one the runner will accept.
+const TOPIC = /^(agent\/[A-Za-z0-9-]{8,80}|agent\/(manager|user)|stream\/[A-Za-z0-9._-]{1,80}\/[A-Za-z0-9._-]{1,80}|delivery\/[A-Za-z0-9-]{8,80}|role\/[A-Z][A-Z0-9-]{0,30}|manager|user|broadcast)$/;
+const TYPE = /^[A-Z][A-Z0-9 _-]{0,30}$/;
+const ADDRESS = /^([A-Za-z0-9-]{8,80}|manager|user)$/;
+const MESSAGE_ID = /^m-[a-z0-9-]{4,120}$/;
+const BODY_MAX = 4000;
+const DEFAULT_TTL_MS = 24 * 3600e3;
+
+/** Held at most this long by the runner; the client waits a little longer, so the runner always answers first. */
+const LISTEN_HOLD_S = 25;
+const LISTEN_MARGIN_MS = 3000;
+const WRITE_TIMEOUT_MS = 8000;
+const READ_TIMEOUT_MS = 8000;
+
+const print = (value, pretty = false) => console.log(pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value));
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const newId = (at = Date.now()) => `m-${at.toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+const replyId = (id, as) => `m-r-${crypto.createHash('sha256').update(['r', id, as].join('\0')).digest('hex').slice(0, 24)}`;
+/** The Cursor session this command runs in, when it runs in one: the runner lets only that session act for its aliases. */
+const SESSION = ADDRESS.test(String(process.env.CURSOR_CONVERSATION_ID || '')) ? process.env.CURSOR_CONVERSATION_ID : null;
+const withSession = (body) => (SESSION ? { ...body, session: SESSION } : body);
+
+/** Thrown for anything that means "the runner did not answer": not listening, timed out, 5xx, or no token to send. */
+class Unreachable extends Error {}
+
+function token() {
+  try {
+    const value = fs.readFileSync(config.tokenFile, 'utf8').trim();
+    if (value) return value;
+  } catch { /* no token */ }
+  throw new Unreachable('no hub token');
+}
+
+async function call(method, route, body, timeoutMs) {
+  // During a cutover's freeze the client is installed offline: every write spools, nothing reaches any hub.
+  if (!config || config.offline) throw new Unreachable(config ? 'offline' : 'not configured');
+  let res;
+  try {
+    res = await fetch(`http://127.0.0.1:${config.port}${route}`, {
+      method,
+      headers: { authorization: `Bearer ${token()}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    if (error instanceof Unreachable) throw error;
+    throw new Unreachable(error && error.message);
+  }
+  if (res.status >= 500 && res.status !== 507) throw new Unreachable(`runner answered ${res.status}`);
+  let parsed;
+  try { parsed = JSON.parse(await res.text()); } catch { throw new Unreachable('runner answered with no JSON'); }
+  if (!parsed || typeof parsed !== 'object') throw new Unreachable('runner answered with no JSON');
+  return { status: res.status, body: parsed };
+}
+
+/** One spool line per write: append-only, owner-only, imported once by the runner under the same id. */
+function spool(op, body) {
+  const dir = config && config.spoolDir;
+  if (!dir) throw new Error('no spool folder');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const at = Date.now();
+  const day = new Date(at).toISOString().slice(0, 10).replaceAll('-', '');
+  const fd = fs.openSync(path.join(dir, `${day}.jsonl`), fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT, 0o600);
+  try { fs.writeSync(fd, `${JSON.stringify({ v: 1, at, op, body })}\n`); } finally { fs.closeSync(fd); }
+  return at;
+}
+
+/**
+ * What a publish could not reach, on stderr, so it is seen even when stdout is cut short: one line per recipient
+ * nobody can read now, or one line when the topic reached nobody. The command still succeeds.
+ */
+function warnUndelivered(answer) {
+  if (answer && answer.error === 'E_UNKNOWN_ADDRESS') {
+    const near = Array.isArray(answer.didYouMean) ? answer.didYouMean.map((d) => `agent/${d.address}${d.label ? ` (${d.label})` : ''}`) : [];
+    console.error(`unknown address: agent/${answer.address} is not a known session id or bound alias; nothing was sent${near.length ? `. Did you mean ${near.join(', ')}?` : ''}`);
+    return;
+  }
+  if (!answer || answer.error || !Array.isArray(answer.delivery)) return;
+  if (Array.isArray(answer.to) && !answer.to.length) {
+    console.error(`no recipients: ${answer.topic} reaches nobody right now, so nothing was queued`);
+    return;
+  }
+  const hours = Math.round((Number(answer.expiresAt) - Number(answer.at)) / 3600e3) || 24;
+  for (const d of answer.delivery) {
+    if (d.state !== 'undeliverable') continue;
+    if (d.reason === 'offline') {
+      console.error(`undeliverable: ${d.to} offline since ${new Date(d.offlineSince).toISOString()} (queued ${hours} h; it is delivered if its session comes back, binds or listens)`);
+      continue;
+    }
+    const why = d.reason === 'stale' ? `its session ${d.session} has had no activity for ${d.idleMin} min` : 'has no reader seen from this machine';
+    console.error(`undeliverable: ${d.to} ${why} (queued ${hours} h; it is delivered if a session binds or listens)`);
+  }
+}
+
+/** A write: answered by the runner when it is up, spooled when it isn't. Prints what the hub would have printed. */
+async function write(route, op, body, offline) {
+  try {
+    const { status, body: answer } = await call('POST', route, body, WRITE_TIMEOUT_MS);
+    print(answer);
+    if (status >= 400 || answer.error) process.exitCode = 2;
+    if (route === '/bus/publish' || route === '/bus/ack') warnUndelivered(answer);
+    return;
+  } catch (error) {
+    if (!(error instanceof Unreachable)) throw error;
+  }
+  let at;
+  try { at = spool(op, body); } catch {
+    print({ error: 'pulse_offline_spool_failed' });
+    process.exitCode = 2;
+    return;
+  }
+  print({ ...offline(at), spooled: true });
+}
+
+function offlineFailure() {
+  print({ error: 'pulse_offline' });
+  process.exitCode = 2;
+}
+
+async function listen() {
+  const as = opt('as');
+  const deadline = Date.now() + Math.max(0, Number(opt('timeout', 25))) * 1000;
+  if (as) {
+    try {
+      await call('POST', '/bus/register', { id: as, role: opt('role'), name: opt('name'), topics: String(opt('topics', '')).split(',').filter(Boolean), parent: opt('parent') }, WRITE_TIMEOUT_MS);
+    } catch (error) {
+      if (!(error instanceof Unreachable)) throw error;
+    }
+  }
+  do {
+    const left = Math.max(0, deadline - Date.now());
+    if (!as) { await sleep(Math.min(left, 1000)); continue; }
+    const hold = Math.min(LISTEN_HOLD_S, Math.ceil(left / 1000));
+    try {
+      const { body } = await call('POST', '/bus/listen', withSession({ as, timeout: hold, heartbeat: true }), hold * 1000 + LISTEN_MARGIN_MS);
+      if (body.error === 'held') { print(body); process.exitCode = 2; return; }
+      if (Array.isArray(body.messages) && body.messages.length) { print({ messages: body.messages }); return; }
+      if (body.error) await sleep(Math.min(left, 1000));
+    } catch (error) {
+      if (!(error instanceof Unreachable)) throw error;
+      await sleep(Math.min(left, 1000));
+    }
+  } while (Date.now() < deadline);
+  print({ messages: [], type: 'TIMEOUT' });
+}
+
+async function busCli() {
+  const action = args[1];
+  if (action === 'register') {
+    const body = { id: opt('as'), role: opt('role'), name: opt('name'), topics: String(opt('topics', '')).split(',').filter(Boolean), parent: opt('parent') };
+    if (!ADDRESS.test(String(body.id || ''))) { print({ error: 'bad address' }); process.exitCode = 2; return; }
+    return write('/bus/register', 'register', body, () => ({ id: body.id }));
+  }
+  if (action === 'publish' || action === 'ask') {
+    const at = Date.now();
+    const body = {
+      id: newId(at), from: opt('as'), fromName: opt('name'), topic: opt('topic'), type: opt('type', action === 'ask' ? 'QUESTION' : 'MESSAGE'),
+      body: opt('body') || positional(2), needsAck: action === 'ask' || args.includes('--ack'), ttlMs: Number(opt('ttl-ms')) || undefined,
+      ...(opt('supersedes') !== undefined ? { supersedes: opt('supersedes') } : {}),
+    };
+    const refused = !ADDRESS.test(String(body.from || '')) ? 'bad sender' : !TOPIC.test(String(body.topic || '')) ? 'bad topic'
+      : !TYPE.test(String(body.type || '')) ? 'bad type' : (typeof body.body !== 'string' || !body.body.trim()) ? 'empty body'
+        : (body.supersedes !== undefined && !MESSAGE_ID.test(String(body.supersedes))) ? 'bad supersedes' : null;
+    if (refused) { print({ error: refused }); process.exitCode = 2; return; }
+    return write('/bus/publish', 'publish', body, (spooledAt) => ({
+      id: body.id, at: spooledAt, from: body.from, fromName: typeof body.fromName === 'string' ? body.fromName.slice(0, 80) : null,
+      topic: body.topic, type: body.type, body: body.body.slice(0, BODY_MAX), needsAck: !!body.needsAck,
+      expiresAt: spooledAt + Math.max(60e3, Math.min(Number(body.ttlMs) || DEFAULT_TTL_MS, 7 * DEFAULT_TTL_MS)),
+      replyTo: null, reaction: null, to: [], meta: body.supersedes ? { supersedes: body.supersedes } : {},
+    }));
+  }
+  if (action === 'listen') return listen();
+  if (action === 'ack' || action === 'reply') {
+    const body = { as: opt('as'), id: opt('id'), reply: opt('reply') || opt('body') || positional(2) || undefined, fromName: opt('name'), reaction: opt('reaction') };
+    if (!ADDRESS.test(String(body.as || '')) || !MESSAGE_ID.test(String(body.id || ''))) { print({ error: 'bad ack' }); process.exitCode = 2; return; }
+    const wantsReply = (typeof body.reply === 'string' && body.reply.trim()) || body.reaction;
+    return write('/bus/ack', 'ack', withSession(body), () => ({ ok: true, reply: wantsReply ? replyId(body.id, body.as) : null }));
+  }
+  if (action === 'who') {
+    // Active sessions only, unless --all (F4); a runner from before 1.1.1 has no /bus/who and answers the old list.
+    const query = `all=${args.includes('--all') ? 1 : 0}${opt('minutes') ? `&minutes=${encodeURIComponent(opt('minutes'))}` : ''}`;
+    try {
+      const who = await call('GET', `/bus/who?${query}`, null, READ_TIMEOUT_MS);
+      if (who.status === 404) print({ registrations: (await call('GET', '/bus/directory', null, READ_TIMEOUT_MS)).body.registrations }, true);
+      else print(who.body, true);
+    } catch (error) {
+      if (!(error instanceof Unreachable)) throw error;
+      offlineFailure();
+    }
+    return;
+  }
+  if (action === 'status') {
+    const id = opt('id');
+    if (!MESSAGE_ID.test(String(id || ''))) { print({ error: 'bad id' }); process.exitCode = 2; return; }
+    try {
+      const { status, body: answer } = await call('GET', `/bus/status?id=${encodeURIComponent(id)}`, null, READ_TIMEOUT_MS);
+      print(answer, true);
+      if (status >= 400 || answer.error) process.exitCode = 2;
+    } catch (error) {
+      if (!(error instanceof Unreachable)) throw error;
+      offlineFailure();
+    }
+    return;
+  }
+  if (action === 'messages') {
+    const since = Number(opt('since')) || 0;
+    try { print({ messages: (await call('GET', `/bus/messages?since=${since}&limit=200`, null, READ_TIMEOUT_MS)).body.messages }, true); } catch (error) {
+      if (!(error instanceof Unreachable)) throw error;
+      offlineFailure();
+    }
+    return;
+  }
+  console.error('bus: publish|ask|listen|ack|reply|register|who|messages');
+  process.exitCode = 2;
+}
+
+function fmtDur(ms) { const m = Math.round(ms / 60e3); return m < 60 ? `${m}m` : `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}`; }
+function fmtTok(n) { return n == null ? '—' : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${Math.round(n / 1e3)}k` : String(n); }
+
+async function printMap() {
+  let g;
+  try { g = (await call('GET', `/api/legacy/map?hours=${Number(opt('hours', 6))}`, null, 60e3)).body; } catch (error) {
+    if (!(error instanceof Unreachable)) throw error;
+    offlineFailure();
+    return;
+  }
+  const t = g.totals;
+  console.log(`Last ${g.hours} h: ${t.sessions} sessions, ${t.agents} agents (${t.active} active), ${t.messages} messages, ≈${fmtTok(t.tokensEst)} tokens (estimate), ${t.requests} shared-change requests\n`);
+  const kids = new Map();
+  for (const n of g.nodes) if (n.parent) { if (!kids.has(n.parent)) kids.set(n.parent, []); kids.get(n.parent).push(n); }
+  const line = (n, pad) => console.log(`${pad}${n.status === 'active' ? '●' : n.status === 'idle' ? '◐' : '○'} ${n.label.padEnd(pad ? 22 : 46)} ${(n.channel || '').padEnd(14)} ${fmtDur(n.lastAt - n.startedAt).padStart(6)}  ≈${fmtTok(n.tokensEst).padStart(5)}  ${n.msgsOut}↑ ${n.msgsIn}↓`);
+  for (const s of g.nodes.filter((n) => n.kind === 'session' && !n.parent).sort((a, b) => b.lastAt - a.lastAt)) {
+    line(s, '');
+    for (const k of (kids.get(s.id) || []).sort((a, b) => b.lastAt - a.lastAt)) line(k, '   └ ');
+  }
+  const loose = g.nodes.filter((n) => n.kind === 'agent' && !n.parent);
+  if (loose.length) { console.log('\nAgents without a known parent session:'); for (const n of loose) line(n, '   '); }
+  if (g.requests.length) { console.log('\nShared-change requests:'); for (const r of g.requests.slice(0, 15)) console.log(`   [${r.status}] ${r.title}  (${r.channel || r.from.join(',')})`); }
+}
+
+async function legacy(route, body) {
+  try {
+    const { status, body: answer } = await call('POST', route, body, WRITE_TIMEOUT_MS);
+    print(answer);
+    if (status >= 400 || answer.error) process.exitCode = 2;
+  } catch (error) {
+    if (!(error instanceof Unreachable)) throw error;
+    offlineFailure();
+  }
+}
+
+async function wait() {
+  const me = opt('for');
+  if (!me) { console.error('wait: --for <id> is required'); process.exit(2); }
+  const deadline = Date.now() + Number(opt('timeout', 900)) * 1000;
+  const started = Date.now();
+  while (Date.now() < deadline) {
+    try {
+      const { body } = await call('POST', '/api/legacy/wait', { for: me, since: started }, WRITE_TIMEOUT_MS);
+      if (body.message || body.event) { print(body.message || body.event); return; }
+    } catch (error) {
+      if (!(error instanceof Unreachable)) throw error;
+    }
+    await sleep(5000);
+  }
+  print({ type: 'TIMEOUT' });
+}
+
+switch (cmd) {
+  case 'serve':
+    console.error('The local Agent Hub is retired on this machine: the Pulse runner serves 127.0.0.1:8890. Undo with `agentpulse pulse cutover --undo`.');
+    process.exitCode = 78;
+    break;
+  case 'map': await printMap(); break;
+  case 'request':
+    await legacy('/api/legacy/request', { from: opt('from'), kind: opt('kind'), title: opt('title'), files: opt('files') });
+    break;
+  case 'post':
+    await legacy('/api/legacy/post', { from: opt('from'), to: opt('to'), type: opt('type'), text: opt('text') });
+    break;
+  case 'wait': await wait(); break;
+  case 'bus': await busCli(); break;
+  default: console.log(fs.readFileSync(new URL(import.meta.url), 'utf8').split('\n').slice(1, 8).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'));
+}

package/src/commands/pulse/cutover.js

@@ -0,0 +1,39 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { createCutover } from '../../lib/cutoverWiring.js';
+
+export default class PulseCutover extends BaseCommand {
+  static description = 'Move this machine\'s local Agent Hub into the Pulse daemon (a short freeze, a backup kept), check first with --dry-run, or go back with --rollback (restores the backup; loses only what was written after the switch).';
+  static examples = [
+    '<%= config.bin %> pulse cutover --dry-run',
+    '<%= config.bin %> pulse cutover --smoke-channel agentpulse-agent-hub/cf-phase3',
+    '<%= config.bin %> pulse cutover --rollback',
+  ];
+  static flags = {
+    'dry-run': Flags.boolean({ description: 'Check everything and say what would change; change nothing', default: false }),
+    rollback: Flags.boolean({ description: 'Back to the local hub from the backup', default: false, exclusive: ['dry-run'] }),
+    'smoke-channel': Flags.string({ description: 'A task channel (<repo>/<task>) for the smoke test\'s one channel post' }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseCutover);
+    const cutover = this.cutover || await createCutover({ configDir: defaultConfigDirectory(), log: (event, details) => this.log(`${event} ${JSON.stringify(details)}`) });
+    if (flags['dry-run']) {
+      const report = await cutover.dryRun();
+      for (const check of report.checks) this.log(`${check.ok ? 'ok  ' : 'FAIL'} ${check.name}${check.detail ? `: ${check.detail}` : ''}${!check.ok && check.fix ? ` (fix: ${check.fix})` : ''}`);
+      this.log(`Outage while it runs: ${report.outage.what}; at most ${Math.round(report.outage.boundMs / 60_000)} min.`);
+      this.log(report.message);
+      if (!report.ok) process.exitCode = 1;
+      return report;
+    }
+    if (flags.rollback) {
+      const report = await cutover.rollback();
+      this.log(report.message);
+      return report;
+    }
+    const journal = await cutover.run({ smokeChannel: flags['smoke-channel'] ?? null });
+    this.log(`Cut over: the Pulse daemon serves 127.0.0.1:${journal.port}. The backup is ${journal.backup.file}. Go back any time with \`agentpulse pulse cutover --rollback\`.`);
+    return journal;
+  }
+}

package/src/commands/pulse/doctor.js

@@ -0,0 +1,15 @@
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseDoctor extends BaseCommand {
+  static description = 'Diagnose the Pulse companion installation and local providers.';
+  static examples = ['<%= config.bin %> pulse doctor'];
+
+  async run() {
+    const { flags } = await this.parse(PulseDoctor);
+    const result = await (this.runtime || getDefaultApplication()).doctor(flags);
+    this.log(result.message);
+    for (const warning of result.warnings || []) this.log(`Warning: ${warning}`);
+    return result;
+  }
+}

package/src/commands/pulse/hub-write.js

@@ -0,0 +1,26 @@
+import { Args } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseHubWrite extends BaseCommand {
+  static description = 'Let Pulse post to the local Agent Hub as you (the hub.write grant), stop it, or show whether it can.';
+  static examples = [
+    '<%= config.bin %> pulse hub-write status',
+    '<%= config.bin %> pulse hub-write on',
+    '<%= config.bin %> pulse hub-write off',
+  ];
+  static args = {
+    action: Args.string({
+      description: 'on, off or status',
+      options: ['on', 'off', 'status'],
+      default: 'status',
+    }),
+  };
+
+  async run() {
+    const { args } = await this.parse(PulseHubWrite);
+    const result = await (this.runtime || getDefaultApplication()).hubWrite({ action: args.action });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/import.js

@@ -0,0 +1,62 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { CloudFirstCommands } from '../../lib/cloudFirstCommands.js';
+
+export default class PulseImport extends BaseCommand {
+  static description = 'Import the local Agent Hub into the Pulse log from a snapshot of its sources (idempotent: a re-run on the same snapshot writes nothing). --dry-run reads only and prints what it would send; --reconcile rescans the snapshot and compares it with Pulse, exiting 1 on any mismatch.';
+  static examples = ['<%= config.bin %> pulse import --dry-run', '<%= config.bin %> pulse import', '<%= config.bin %> pulse import --reconcile', '<%= config.bin %> pulse import --reuse-snapshot'];
+  static flags = {
+    'dry-run': Flags.boolean({ description: 'Read the local hub and report per source; send and write nothing', default: false }),
+    wait: Flags.boolean({ description: 'Follow the import until it has fully drained', default: true, allowNo: true }),
+    reconcile: Flags.boolean({ description: 'Rescan the last import\'s snapshot and compare every family, channel and conversation with Pulse', default: false }),
+    'reuse-snapshot': Flags.boolean({ description: 'Import the last snapshot again instead of taking a new one', default: false }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseImport);
+    const commands = this.cloudFirst || new CloudFirstCommands({ configDir: defaultConfigDirectory() });
+    if (flags['dry-run']) {
+      const result = await commands.dryRun();
+      for (const row of result.sources) {
+        const detail = [...Object.entries(row.skipped).map(([k, v]) => `skipped ${k} ${v}`), ...Object.entries(row.refused).map(([k, v]) => `refused ${k} ${v}`)];
+        this.log(`${row.source.padEnd(9)} read ${row.read}  planned ${row.planned}  unchanged ${row.unchanged}  redactions ${row.redactions}${row.cut ? `  cut ${row.cut}` : ''}${detail.length ? `  (${detail.join(', ')})` : ''}`);
+        if (Object.keys(row.events).length) this.log(`          events ${Object.entries(row.events).map(([type, n]) => `${type} ${n}`).join(', ')}`);
+      }
+      this.log(result.message);
+      if (!result.totals.balanced) process.exitCode = 1;
+      return result;
+    }
+    let last = '';
+    if (flags.reconcile) {
+      const result = await commands.reconcile({
+        onProgress: (progress) => {
+          const line = `Reconcile: ${progress.state}${progress.code ? ` (${progress.code})` : ''}`;
+          if (line !== last) this.log(line);
+          last = line;
+        },
+      });
+      for (const [family, row] of Object.entries(result.families || {})) {
+        this.log(`${family.padEnd(18)} local ${String(row.local).padStart(6)}  pulse ${String(row.cloud).padStart(6)}  ${row.equal ? 'equal' : 'DIFFERS'}`);
+      }
+      for (const [source, row] of Object.entries(result.sources || {})) {
+        this.log(`source ${source.padEnd(9)} rows ${row.counted ?? '—'}  read ${row.read}  accounted ${row.accounted}`);
+      }
+      for (const item of (result.mismatches || []).slice(0, 20)) this.log(`MISMATCH ${item.family}${item.item ? ` ${item.item}` : ''}${item.note ? `: ${item.note}` : ''}`);
+      this.log(result.message);
+      process.exitCode = result.exitCode;
+      return result;
+    }
+    const result = await commands.import({
+      wait: flags.wait,
+      reuseSnapshot: flags['reuse-snapshot'],
+      onProgress: (progress) => {
+        const line = `Import: ${progress.state}${progress.code ? ` (${progress.code})` : ''}${progress.pending !== null && progress.pending !== undefined ? `, ${progress.pending} commands waiting` : ''}`;
+        if (line !== last) this.log(line);
+        last = line;
+      },
+    });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/install.js

@@ -0,0 +1,14 @@
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseInstall extends BaseCommand {
+  static description = 'Install or atomically update the Pulse companion daemon service.';
+  static examples = ['<%= config.bin %> pulse install'];
+
+  async run() {
+    const { flags } = await this.parse(PulseInstall);
+    const result = await (this.runtime || getDefaultApplication()).install(flags);
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/log-write.js

@@ -0,0 +1,26 @@
+import { Args } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseLogWrite extends BaseCommand {
+  static description = 'Let this machine read and write your Pulse log (hub.sync and log.write), stop it writing, or show whether it can.';
+  static examples = [
+    '<%= config.bin %> pulse log-write status',
+    '<%= config.bin %> pulse log-write on',
+    '<%= config.bin %> pulse log-write off',
+  ];
+  static args = {
+    action: Args.string({
+      description: 'on, off or status',
+      options: ['on', 'off', 'status'],
+      default: 'status',
+    }),
+  };
+
+  async run() {
+    const { args } = await this.parse(PulseLogWrite);
+    const result = await (this.runtime || getDefaultApplication()).logWrite({ action: args.action });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/login.js

@@ -0,0 +1,20 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseLogin extends BaseCommand {
+  static description = 'Sign the Pulse connector in again with your AgentPulse account (browser OAuth with PKCE).';
+  static examples = ['<%= config.bin %> pulse login', '<%= config.bin %> pulse login --platform https://app.agentpulse.example.com'];
+  static flags = {
+    platform: Flags.string({
+      description: 'Platform URL to sign in to (defaults to the paired platform).',
+    }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseLogin);
+    const result = await (this.runtime || getDefaultApplication()).login({ platformUrl: flags.platform });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/mirror.js

@@ -0,0 +1,27 @@
+import { Args } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseMirror extends BaseCommand {
+  static description = 'Turn mirroring of the local Agent Hub into Pulse on or off, show its status, or send the items Pulse refused again.';
+  static examples = [
+    '<%= config.bin %> pulse mirror status',
+    '<%= config.bin %> pulse mirror on',
+    '<%= config.bin %> pulse mirror off',
+    '<%= config.bin %> pulse mirror resend-rejected',
+  ];
+  static args = {
+    action: Args.string({
+      description: 'on, off, status or resend-rejected',
+      options: ['on', 'off', 'status', 'resend-rejected'],
+      default: 'status',
+    }),
+  };
+
+  async run() {
+    const { args } = await this.parse(PulseMirror);
+    const result = await (this.runtime || getDefaultApplication()).mirror({ action: args.action });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/pair.js

@@ -0,0 +1,38 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulsePair extends BaseCommand {
+  static description = 'Pair this machine with Pulse using your AgentPulse sign-in.';
+  static examples = [
+    '<%= config.bin %> pulse pair --org builddevorg8 --root agent-hub=~/src/agent-hub',
+    '<%= config.bin %> pulse pair --platform https://app.agentpulse.example.com --org my-dev-org --root app=.',
+  ];
+  static flags = {
+    org: Flags.string({
+      description: 'Dev-org slug that hosts Pulse (defaults to the agentpulse CLI active org).',
+    }),
+    platform: Flags.string({
+      description: 'Platform URL to sign in to (defaults to the agentpulse CLI active profile).',
+    }),
+    name: Flags.string({
+      description: 'Display name for this machine.',
+    }),
+    root: Flags.string({
+      description: 'Approve a local root as <rootId>=<path> (repeatable).',
+      multiple: true,
+    }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulsePair);
+    const result = await (this.runtime || getDefaultApplication()).pair({
+      org: flags.org,
+      platformUrl: flags.platform,
+      displayName: flags.name,
+      roots: flags.root || [],
+    });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/parity.js

@@ -0,0 +1,20 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { CloudFirstCommands } from '../../lib/cloudFirstCommands.js';
+
+export default class PulseParity extends BaseCommand {
+  static description = 'Show how this machine\'s Pulse mirror and the Pulse log agree: the last parity check and its history, or a fresh one.';
+  static examples = ['<%= config.bin %> pulse parity', '<%= config.bin %> pulse parity --now --hours 6'];
+  static flags = {
+    hours: Flags.integer({ description: 'Window in hours (1 to 168)', default: 6, min: 1, max: 168 }),
+    now: Flags.boolean({ description: 'Ask the daemon for a fresh check and wait for it', default: false }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseParity);
+    const result = await (this.cloudFirst || new CloudFirstCommands({ configDir: defaultConfigDirectory() })).parity({ hours: flags.hours, now: flags.now });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/restart.js

@@ -0,0 +1,14 @@
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseRestart extends BaseCommand {
+  static description = 'Ask the running Pulse daemon to restart itself and wait for the new process (no launchctl or systemctl needed).';
+  static examples = ['<%= config.bin %> pulse restart'];
+
+  async run() {
+    await this.parse(PulseRestart);
+    const result = await (this.runtime || getDefaultApplication()).restart();
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/shadow.js

@@ -0,0 +1,19 @@
+import { Args } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { CloudFirstCommands } from '../../lib/cloudFirstCommands.js';
+
+export default class PulseShadow extends BaseCommand {
+  static description = 'Turn the Pulse shadow feed (the local hub, tailed into the Pulse log) on or off, or show its status.';
+  static examples = ['<%= config.bin %> pulse shadow status', '<%= config.bin %> pulse shadow on', '<%= config.bin %> pulse shadow off'];
+  static args = {
+    action: Args.string({ description: 'on, off or status', options: ['on', 'off', 'status'], default: 'status' }),
+  };
+
+  async run() {
+    const { args } = await this.parse(PulseShadow);
+    const result = await (this.cloudFirst || new CloudFirstCommands({ configDir: defaultConfigDirectory() })).shadow({ action: args.action });
+    this.log(result.message);
+    return result;
+  }
+}