@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/README.md

@@ -77,6 +77,52 @@ How it reads and what it sends:
 - Rule packs include only `*.mdc` under `.cursor/rules/`, plus `AGENTS.md` and `CLAUDE.md`, from the workspace, each repo and your user folder. Files named like `.env*`, `*secret*` or `*token*`, symlinks that leave the pack, and oversized files are skipped.
 - Transcripts, diffs, raw provider output, the hub token, Keychain and OAuth material are never read for the mirror or sent.
 
+## Import and shadow into the Pulse log (cloud-first preview)
+
+These need your team's Pulse cloud-first flag on, set by a team owner or admin, and Node 24 or later.
+
+- `agentpulse pulse import --dry-run` reads the local Agent Hub without changing anything and prints, for each source, the rows it read and what it would send, skip or refuse.
+- `agentpulse pulse import` snapshots the hub's sources (`hub.db`, personas, chat files and every channel file) into the connector's folder, then brings the snapshot into the Pulse log. `--reuse-snapshot` imports the same snapshot again, which writes nothing new. A later `pulse import` takes a new snapshot and sends only what changed since, so the final catch-up at cutover is an import, not the shadow tail.
+- `agentpulse pulse import --reconcile` rescans the last snapshot from scratch and compares it with what Pulse holds for this machine: every channel's posts, every conversation's messages and receipts, actors, personas, agent rows and facts, by count and hash, plus every withheld or cut item by key. Each differing channel or conversation is classified. `retired` means a channel whose `channel.md` is gone from disk under every root. `redacted` means Pulse holds the same text redacted with a root deleted since; a rescan with that root must give exactly Pulse's hash, and the root is then kept. `drift`, `missing` and `unexplained` are mismatches. It exits 1 on any mismatch, never sends anything, and keeps the report, with the counts per class, in `reconcile-last.json`. `pulse cutover` records the classes, the retired channels and the redacted items in `cutover.json`.
+- `agentpulse pulse shadow on` makes the daemon tail the live hub into the log after an import. It is meant for cutover only.
+- `agentpulse pulse parity` shows how the Pulse log and this machine's mirror agree while the shadow runs. `--now` asks the daemon for a fresh check.
+
+Everything sent goes through the same secret and path filter as the mirror, and the cloud filters it again.
+
+## Bus identity and delivery states (1.1.1)
+
+After cutover the runner hosts the bus, and `hub.mjs bus` works as before with these additions:
+
+- **One identity per session.** A session's bus address is its Cursor conversation id, which for a subagent is its Task agent id. `bus register --as <nickname>`, run as a Shell command inside the session, binds the nickname to it, and the hook says whether the binding took. Mail to the nickname then reaches that session.
+- **Delivery states.** `bus publish` and `bus ask` add `delivery` (`queued` or `undeliverable`, and why) and print one stderr line for each recipient nobody can read. `bus status --id m-…` shows each recipient as `undeliverable`, `queued`, `delivered`, `read`, `skipped`, `acked` or `expired`.
+  - `read` means a step of the recipient's session ran after the message was shown, or the manager recorded a DONE or STATUS.
+  - `acked` comes only from `bus ack`, `bus reply`, a captured answer to your message, or a manager answer.
+- **`bus who`** lists active sessions by default; `--all` lists history.
+
+**Known limits:**
+
+- A binding is recorded on the machine whose hook saw the register. Other machines learn that the alias is live from presence within about 30 seconds (beats are coalesced), and then report it `queued`. A send from another machine inside that window is reported `undeliverable`, though it is still queued and delivered. From 1.1.2 it is refused as unknown instead (see below).
+- A `bus register` chained to a failing command binds only if `~/.cursor/hooks.json` sends `postToolUseFailure` to the hub hook; `pulse doctor` says which events are missing.
+- `bus listen`, `bus ack` and `bus reply` send the Cursor session they run in (`CURSOR_CONVERSATION_ID`).
+  - The session holding an alias acts for its whole inbox, whether it names itself or the alias.
+  - Another Cursor session is refused on an alias a live session holds ("held by S", exit 2), before anything is claimed.
+  - A command run outside Cursor sends no session. It gets the mail sent literally to the address it names, as before 1.1.1, and never the holder's own mail.
+- **Threat model.** The session field guards agents against each other's mistakes: a subagent listening as a nickname it shouldn't, or a stale script left running. It is not a security boundary. Any local process that can read `state/hub.token` can set the field, or do anything else the hub allows, exactly as before 1.1.1.
+- The binding parser matches only `node <path>/hub.mjs bus register|listen … --as X`, with the path written out. A command such as `node "$HUB" …` does not bind.
+
+**Release note:** from this version the plugin needs **Node 24 or later**: `runner.db` and the read-only `hub.db` reader use `node:sqlite`, and on Node 22 and older `fetch` can lose an abort on a long-lived stream. On older Node, `agentpulse pulse start`, `agentpulse pulse doctor` and the daemon refuse with a clear message.
+
+## Delivery discipline checks (1.1.2)
+
+The runner checks the delivery-discipline rules itself, from the Cursor hook and the manager lease holder's sweep:
+
+- **Unknown addresses (E1).** Mail to an `agent/<x>` that is neither a known session nor a bound alias is refused (`E_UNKNOWN_ADDRESS`, exit 2), with the closest addresses. Known means: a session a hook has shown (here or on another machine), a bound alias, an address that has listened, or a session or Task id (UUID-shaped) that ran `bus register` itself. That last case takes no proof, so a Task id can be mailed as soon as it registers. A nickname nobody bound is refused. Mail to an address idle more than 2 h is kept, and the sender sees `undeliverable: <x> offline since <t>`.
+- **Channels (E2, E3, E4).** Which posts a session wrote is learned from its own tool calls: the channel they name and the header lines they write. A session that ends with a non-terminal newest post gets an automatic `STOPPED`. A channel whose newest post isn't terminal gets `STATUS?` to its owner at 30 minutes, and one escalation to its architect and to you at 60 minutes. A header stamped more than 5 minutes ahead of the clock is flagged to its writer and on the Board.
+- **Subagents (E5).** A Task launch in this workspace is denied unless its brief names a `.agents/<task>/channel.md` with a KICKOFF. Read-only subagents (`explore` and the like, or `readonly: true`) and resumes are exempt.
+- **Permission prompts (E6).** A Shell call with `required_permissions` posts a BLOCKER to its session's channel and to you, and the call's end clears it. It fires on every such call, including ones Cursor approves on its own.
+
+**Known limits:** another machine learns of an alias bound here only from presence, within about 30 seconds (beats are coalesced). Until then it doesn't know the alias at all and refuses a send to it with `E_UNKNOWN_ADDRESS` (1.1.1 queued it as undeliverable); a retry after that window goes through. A subagent's end reaches its parent as `subagentStop`, which carries no subagent id, so E2 covers subagents only through E3's 30- and 60-minute checks. Whether Cursor sends `required_permissions` in `preToolUse`, before its prompt, is unverified live; the runner records each event's field names in `state/hook-shapes.jsonl`.
+
 ## Local checks
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentpulselabs/cli-plugin-pulse",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "description": "AgentPulse CLI plugin for installing and operating the Pulse local connector (replaces the deprecated build-discipline Pulse plugin).",
   "type": "module",
   "license": "MIT",
@@ -19,11 +19,14 @@
     }
   },
   "scripts": {
-    "test": "node --import ./test/support/register-loader.mjs --test \"test/**/*.test.js\"",
-    "check": "node --check src/commands/pulse/install.js && node --check src/commands/pulse/pair.js && node --check src/commands/pulse/login.js && node --check src/commands/pulse/start.js && node --check src/commands/pulse/status.js && node --check src/commands/pulse/doctor.js && node --check src/commands/pulse/stop.js && node --check src/commands/pulse/restart.js && node --check src/lib/selfRestart.js && node --check src/lib/subprocess.js && node --check src/lib/daemonProcess.js && node --check src/commands/pulse/mirror.js && node --check src/commands/pulse/hub-write.js && node --check src/lib/localHubWriter.js && node --check src/lib/hubActions.js && node --check src/lib/localHub.js && node --check src/lib/pathRedaction.js && node --check src/lib/rulePacks.js && node --check src/lib/mirrorContract.js && node --check src/lib/graphWindows.js && node --check src/lib/mirrorSource.js && node --check src/lib/mirrorSync.js && node --check src/lib/mirrorService.js && node --check src/lib/mirrorDaemon.js && node --check src/lib/daemonComposition.js && node --check src/lib/daemonRuntime.js && node --check src/lib/daemonLoop.js && node --check src/daemon/main.js"
+    "test": "node --import ./test/support/register-loader.mjs --test \"test/*.test.js\" \"test/hub/*.test.js\"",
+    "contract:check": "node scripts/sync-contract.mjs --local",
+    "check": "node --check src/commands/pulse/install.js && node --check src/commands/pulse/pair.js && node --check src/commands/pulse/login.js && node --check src/commands/pulse/start.js && node --check src/commands/pulse/status.js && node --check src/commands/pulse/doctor.js && node --check src/commands/pulse/stop.js && node --check src/commands/pulse/restart.js && node --check src/lib/selfRestart.js && node --check src/lib/subprocess.js && node --check src/lib/daemonProcess.js && node --check src/commands/pulse/mirror.js && node --check src/commands/pulse/hub-write.js && node --check src/lib/localHubWriter.js && node --check src/lib/hubActions.js && node --check src/lib/localHub.js && node --check src/lib/pathRedaction.js && node --check src/lib/rulePacks.js && node --check src/lib/mirrorContract.js && node --check src/lib/graphWindows.js && node --check src/lib/mirrorSource.js && node --check src/lib/mirrorSync.js && node --check src/lib/mirrorService.js && node --check src/lib/mirrorDaemon.js && node --check src/lib/daemonComposition.js && node --check src/lib/daemonRuntime.js && node --check src/lib/daemonLoop.js && node --check src/daemon/main.js && node --check src/lib/sqlite.js && node --check src/lib/nodeFloor.js && node --check src/lib/runnerStore.js && node --check src/lib/hubDbReader.js && node --check src/lib/channelScanner.js && node --check src/lib/uploadRedactor.js && node --check src/lib/hubScan.js && node --check src/lib/outboxFlusher.js && node --check src/lib/hubSnapshot.js && node --check src/lib/reconcileView.js && node --check src/lib/reconcile.js && node --check src/lib/shadowService.js && node --check src/lib/cloudFirstCommands.js && node --check src/commands/pulse/import.js && node --check src/commands/pulse/shadow.js && node --check src/commands/pulse/parity.js && node --check src/runner/main.js && node --check src/runner/runnerProcess.js && node --check src/runner/facade.js && node --check src/runner/bridge.js && node --check src/runner/runnerChild.js && node --check src/runner/applier.js && node --check src/runner/capture.js && node --check src/runner/hubCapture.js && node --check src/clients/hub.mjs && node --check src/clients/hub-bridge.mjs && node --check src/runner/busIdentity.js && node --check src/runner/deliveryStates.js && node --check src/lib/doctorWarnings.js && node --check src/hub/lib/closure.mjs && node --check src/runner/channelDiscipline.js",
+    "test:t2": "node --import ./test/support/register-loader.mjs --test --test-timeout=120000 \"test/t2/*.test.js\"",
+    "test:t3": "node --import ./test/support/register-loader.mjs --test --test-concurrency=1 --test-timeout=240000 \"test/t3/*.test.js\""
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "keywords": [
     "oclif-plugin",

package/src/clients/hub-bridge.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * The Pulse runner's thin Cursor hook: forwards the hook input, cut to the fields the runner reads, to the runner on
+ * 127.0.0.1 (`POST /hook`, where handleHook runs unchanged) and prints its answer. It opens no database.
+ * Always fails open: any problem prints {} within 3.5 s, so the chat is never blocked.
+ */
+import fs from 'node:fs';
+
+const PULSE = /*PULSE_CLIENT_CONFIG*/ null;
+const config = PULSE || JSON.parse(process.env.PULSE_CLIENT_CONFIG || 'null');
+
+/**
+ * Hard stop, armed before anything else and counted from process start: well under Cursor's 5 s hook timeout even if
+ * stdin never closes and the runner is silent. The runner gives up on a hook after 1.5 s and rolls back, inside this
+ * client's 2 s call, so it never commits a delivery this client didn't see.
+ */
+const HARD_EXIT_MS = 2500;
+const STDIN_MS = 1000;
+const CALL_MS = 2000;
+
+let finished = false;
+const done = (o = {}) => {
+  if (finished) return;
+  finished = true;
+  process.stdout.write(JSON.stringify(o));
+  process.exit(0);
+};
+setTimeout(() => done(), Math.max(0, HARD_EXIT_MS - performance.now())).unref();
+
+/** The fields the runner reads, and the size each may take; a tool's output never goes (it can pass the runner's 64 KB cap). */
+const FIELDS = { hook_event_name: 100, conversation_id: 200, tool_name: 200, text: 32_000, status: 100, tool_use_id: 200, cwd: 1000, reason: 40 };
+const COMMAND_MAX = 4000;
+/** Pulse 1.1.2: a Task brief (E5), a Shell call's permissions and folder (E6), and its other short fields. */
+const TOOL_FIELDS = { prompt: 16_000, description: 1000, resume: 200, subagent_type: 60, cwd: 1000, working_directory: 1000 };
+const HEADER = /^## \[[A-Z][A-Z0-9 -]*\] \S+ /;
+const CHANNEL_LINE = /\.agents\/[A-Za-z0-9._-]+/;
+
+/**
+ * E2, E4: the post headers a call wrote and the lines naming the channel folder it wrote them to, from any string the
+ * tool took (a Shell heredoc, a Write's contents, a StrReplace's new text, a path). Only when something names channel.md.
+ */
+function channelWrites(tool) {
+  const texts = Object.values(tool).filter((v) => typeof v === 'string');
+  if (!texts.some((t) => t.includes('channel.md'))) return {};
+  const lines = texts.flatMap((t) => t.split('\n'));
+  const headers = lines.filter((l) => HEADER.test(l.trim())).slice(0, 20).map((l) => l.trim().slice(0, 300));
+  const channels = lines.filter((l) => CHANNEL_LINE.test(l)).slice(0, 10).map((l) => l.slice(0, 600));
+  return headers.length && channels.length ? { headers, channels } : {};
+}
+
+/** The hook input cut to what the runner uses: handleHook's fields, a Shell command (for bus binding), and key names only. */
+function trimmed(input) {
+  const out = {};
+  for (const [key, max] of Object.entries(FIELDS)) if (typeof input[key] === 'string') out[key] = input[key].slice(0, max);
+  if (!out.conversation_id && typeof input.session_id === 'string') out.conversation_id = input.session_id.slice(0, 200);
+  if (Number.isFinite(input.loop_count)) out.loop_count = input.loop_count;
+  if (Array.isArray(input.workspace_roots)) out.workspace_roots = input.workspace_roots.filter((r) => typeof r === 'string').slice(0, 20).map((r) => r.slice(0, 1000));
+  const tool = input.tool_input && typeof input.tool_input === 'object' && !Array.isArray(input.tool_input) ? input.tool_input : null;
+  if (tool) {
+    const kept = {};
+    if (typeof tool.command === 'string') kept.command = tool.command.slice(0, COMMAND_MAX);
+    for (const [key, max] of Object.entries(TOOL_FIELDS)) if (typeof tool[key] === 'string') kept[key] = tool[key].slice(0, max);
+    if (typeof tool.readonly === 'boolean') kept.readonly = tool.readonly;
+    if (Array.isArray(tool.required_permissions)) kept.required_permissions = tool.required_permissions.filter((p) => typeof p === 'string').slice(0, 10).map((p) => p.slice(0, 40));
+    Object.assign(kept, channelWrites(tool));
+    if (Object.keys(kept).length) out.tool_input = kept;
+  }
+  out._keys = { input: Object.keys(input).slice(0, 50), ...(tool ? { tool_input: Object.keys(tool).slice(0, 50) } : {}) };
+  return out;
+}
+
+async function forward(raw) {
+  let input;
+  try { input = JSON.parse(raw || '{}'); } catch { return {}; }
+  if (!input || typeof input !== 'object' || Array.isArray(input) || !config || config.offline) return {};
+  const token = fs.readFileSync(config.tokenFile, 'utf8').trim();
+  const res = await fetch(`http://127.0.0.1:${config.port}/hook`, {
+    method: 'POST',
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify(trimmed(input)),
+    signal: AbortSignal.timeout(CALL_MS),
+  });
+  if (res.status !== 200) return {};
+  const answer = JSON.parse(await res.text());
+  return answer && typeof answer === 'object' && !Array.isArray(answer) ? answer : {};
+}
+
+let raw = '';
+let sent = false;
+const read = () => {
+  if (sent) return;
+  sent = true;
+  forward(raw).then(done, () => done());
+};
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => { raw += c; });
+process.stdin.on('end', read);
+process.stdin.on('error', () => done());
+setTimeout(() => { process.stdin.pause(); read(); }, STDIN_MS).unref();

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

@@ -9,6 +9,7 @@ export default class PulseDoctor extends BaseCommand {
     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/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;
+  }
+}