@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/hub/workers/runner.mjs

@@ -0,0 +1,145 @@
+// agents-hub workers/runner.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Hub-owned agents. The hub starts them, owns their sessions, and delivers every message by running one turn of that
+// session with the message as the prompt; the turn's final answer is the reply. No parent chat has to stay alive, and
+// any provider with a driver can run them.
+import { execFile as execFileCb } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { isFyi } from '../core/ids.mjs';
+import { withTx } from '../core/db.mjs';
+import { RETRY_MS, guardTick, retryBusy } from '../core/ticks.mjs';
+import { CHANNEL_POST_RULE, DECISION_RULE, WRITING_GUIDE } from '../lib/writing.mjs';
+import { hubHome } from '../home.mjs';
+
+const execFile = promisify(execFileCb);
+const TICK_MS = 1500;
+const LEASE_MS = 60e3;
+const MAX_PARALLEL = 2;
+const MAX_ATTEMPTS = 3;
+const ROLE = /^[A-Z][A-Z -]{1,30}$/;
+const HUB_CLI = path.join(hubHome(), 'hub.mjs');
+
+/** What every hub-owned agent is told on its first turn, whatever its provider. */
+export function briefPrompt(run, brief) {
+  return [
+    `You are the ${run.role} on a delivery run by the Agent Hub. Your hub address is ${run.id}.`,
+    `Work only inside ${run.workspace}. Never push, release or touch production; never request extra permissions.`,
+    run.stream ? `Your task channel is ${run.workspace}/.agents/${run.stream.split('/').pop()}/channel.md: append posts to it (never rewrite), each starting with a header line \`## [${run.role}] HH:MM:SS TYPE — summary\`.` : null,
+    `To message another agent: node "${HUB_CLI}" bus publish --as ${run.id} --topic agent/<id> --type MESSAGE --body "<text>".`,
+    'Each message to you arrives as a new turn; your final answer in that turn is sent back to the sender as your reply.',
+    `${WRITING_GUIDE} ${CHANNEL_POST_RULE} ${DECISION_RULE}`,
+    '',
+    '## Your brief',
+    brief,
+  ].filter((x) => x !== null).join('\n');
+}
+
+export function messagePrompt(m) {
+  return [`Message from ${m.fromName || m.from} (${m.type}, id ${m.id}):`, '', m.text,
+    '', 'Answer it now; your final answer is sent back as your reply. Then carry on with your task if work remains.'].join('\n');
+}
+
+export function createRunner({ hub, drivers, run = execFile, workspaceRoot, onChange = () => {}, now = Date.now, log = console.error, retryMs = RETRY_MS }) {
+  const { registry, messaging } = hub;
+  const busy = new Map();
+  const aborts = new Map();
+  let timer = null;
+  const save = (r) => { registry.setFact('run', r.id, { ...r, updatedAt: Date.now() }); onChange(); return r; };
+  const runs = () => registry.facts('run').filter((r) => r.state !== 'stopped');
+
+  function inWorkspace(dir) {
+    try {
+      const real = fs.realpathSync(dir);
+      const root = fs.realpathSync(workspaceRoot);
+      return (real === root || real.startsWith(root + path.sep)) && fs.statSync(real).isDirectory() ? real : null;
+    } catch { return null; }
+  }
+
+  /** Start a hub-owned agent: create its session, register it, and queue its brief as its first message. */
+  async function start({ driver, role, workspace, brief, stream = null, parent = 'manager', name = null, mode = 'write' }) {
+    const d = drivers.get(driver);
+    if (!d) return { error: `unknown driver ${driver}` };
+    if (!ROLE.test(String(role || ''))) return { error: 'bad role' };
+    const ws = inWorkspace(workspace);
+    if (!ws) return { error: 'workspace must be a folder inside the hub workspace' };
+    if (typeof brief !== 'string' || !brief.trim()) return { error: 'empty brief' };
+    if (mode === 'write' && !d.can.edit) return { error: `${d.label} cannot edit; give it a read-only role` };
+    const id = (await d.newSession({ run, workspace: ws })) || crypto.randomUUID();
+    const rec = { id, driver, role, workspace: ws, stream, parent, name, mode, state: 'queued', sessionId: d.id === 'cursor' ? id : null, createdAt: Date.now(), turns: 0, costUsd: 0, lastError: null };
+    registry.upsertInferred({ id, node_type: 'agent', role, parent_id: parent, delivery_id: parent, stream_key: stream, persona_name: name, source: 'registered', repo: path.basename(ws), channel: stream ? stream.split('/').pop() : null, started_at: rec.createdAt, last_at: rec.createdAt });
+    save(rec);
+    messaging.publish({ from: 'user', fromName: 'You', topic: `agent/${id}`, type: 'BRIEF', body: brief.slice(0, 4000), needsAck: true, meta: { briefFull: brief.length > 4000 } }, registry.directory());
+    rec.brief = brief;
+    save(rec);
+    return { id, driver, state: rec.state };
+  }
+
+  async function turn(r, m) {
+    const d = drivers.get(r.driver);
+    const prompt = m.type === 'BRIEF' ? briefPrompt(r, r.brief || m.text) : messagePrompt(m);
+    save({ ...r, state: 'working', current: m.id, lastError: null });
+    registry.heartbeat(r.id, { event: 'runner', tool: d.id });
+    const keep = setInterval(() => {
+      try {
+        messaging.renewClaim(r.id, m.id, m.leaseToken, { leaseMs: LEASE_MS });
+        registry.heartbeat(r.id, { event: 'runner', tool: d.id });
+      } catch (e) { log(`runner keepalive for ${r.id} failed: ${e.message}`); }
+    }, 20e3);
+    const abort = new AbortController();
+    aborts.set(r.id, abort);
+    try {
+      const out = await d.turn({ run, sessionId: r.sessionId, workspace: r.workspace, prompt, mode: r.mode, signal: abort.signal });
+      if (abort.signal.aborted) return;
+      // The answer is delivered, acked and recorded together; a busy database retries that, never the turn.
+      await retryBusy(() => withTx(hub.db, () => {
+        const fresh = registry.fact('run', r.id) || r;
+        messaging.markDelivered(r.id, [m.id], { via: 'runner' });
+        messaging.ack(r.id, m.id, { reply: out.text || '(no answer)', fromName: fresh.name || fresh.role }, registry.directory());
+        save({ ...fresh, sessionId: out.sessionId || fresh.sessionId, state: 'idle', current: null, turns: (fresh.turns || 0) + 1, lastAt: Date.now(), costUsd: (fresh.costUsd || 0) + ((out.usage && out.usage.costUsd) || 0) });
+        registry.heartbeat(r.id, { event: 'stop', tool: d.id });
+      }, 'runner answer'), { delaysMs: retryMs, label: `runner answer for ${r.id}`, log });
+    } catch (e) {
+      if (abort.signal.aborted) return;
+      const failed = String(e && e.message ? e.message : e).slice(0, 500);
+      try {
+        const fresh = registry.fact('run', r.id) || r;
+        save({ ...fresh, state: 'error', current: null, lastError: failed, lastAt: Date.now() });
+      } catch (e2) { log(`runner ${r.id}: turn failed (${failed}) and recording it failed too: ${e2.message}`); }
+    } finally { clearInterval(keep); aborts.delete(r.id); }
+  }
+
+  const tick = guardTick('runner', () => {
+    for (const r of runs()) {
+      if (busy.has(r.id) || busy.size >= MAX_PARALLEL) continue;
+      const [m] = messaging.claim(r.id, { via: 'runner', limit: 1, leaseMs: LEASE_MS });
+      if (!m) continue;
+      if (isFyi(m) && m.type !== 'BRIEF') { messaging.ack(r.id, m.id, {}, registry.directory()); continue; }
+      if (m.attempts > MAX_ATTEMPTS) {
+        messaging.ack(r.id, m.id, { reply: `I could not run this after ${MAX_ATTEMPTS} tries. Last error: ${r.lastError || 'unknown'}` }, registry.directory());
+        continue;
+      }
+      busy.set(r.id, turn(r, m).catch((e) => log(`runner turn for ${r.id} failed: ${e.message}`)).finally(() => busy.delete(r.id)));
+    }
+  }, { now, log });
+
+  return {
+    start,
+    /** Stop a run: kill a turn in progress (its process) and take no more messages. */
+    stop(id) {
+      const r = registry.fact('run', id);
+      if (!r) return { error: 'no such run' };
+      const a = aborts.get(id);
+      if (a) a.abort();
+      save({ ...r, state: 'stopped', current: null });
+      return { ok: true, killed: !!a };
+    },
+    list() { return registry.facts('run').map(({ brief, ...r }) => ({ ...r, briefChars: brief ? brief.length : 0 })); },
+    drivers() { return [...drivers.values()].map((d) => ({ id: d.id, label: d.label, can: d.can })); },
+    tick,
+    begin() { if (!timer) { timer = setInterval(tick, TICK_MS); timer.unref(); } },
+    end() { if (timer) clearInterval(timer); timer = null; },
+    idle: () => Promise.all([...busy.values()]),
+  };
+}

package/src/lib/application.js

@@ -6,13 +6,15 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { readCliDefaults } from './cliDefaults.js';
 import { CloudAuth } from './cloudAuth.js';
+import { hubHooks, postgresHeadroom } from './doctorWarnings.js';
 import { createClaudeDriver, createCursorDriver } from './drivers.js';
-import { HubError } from './errors.js';
+import { HubError, SCOPE_FIX } from './errors.js';
 import { fetchJson } from './http.js';
 import { loadIdentity, loadOrCreateIdentity } from './identity.js';
 import { MIRROR_SCOPE } from './mirrorContract.js';
 import { localScopeCheckApplies, MIRROR_STATE_FILE, mirrorEnabled } from './mirrorDaemon.js';
 import { MirrorSync, requestResend } from './mirrorSync.js';
+import { assertNodeFloor, nodeFloor } from './nodeFloor.js';
 import { loginWithBrowser } from './oauthLogin.js';
 import { assertPairedConfig, pairedStatus } from './pairedConfig.js';
 import { pairConnector } from './pairingLifecycle.js';
@@ -20,13 +22,14 @@ import { ProcessSupervisor } from './processSupervisor.js';
 import { defaultSecretStore } from './secretStore.js';
 import { consumeRestartRequest, RESTART_REQUEST_FILE } from './selfRestart.js';
 import { ServiceManager } from './serviceManager.js';
+import { importEnabled } from './shadowService.js';
 import {
   ensureOwnerOnlyDirectory,
   readOwnerOnlyJson,
   writeOwnerOnlyJson,
 } from './storage.js';
 import { TokenStore } from './tokenStore.js';
-import { USER_API_BASE } from './transportContract.js';
+import { CONNECTOR_SCOPES, USER_API_BASE } from './transportContract.js';
 
 const CONFIG_FILE = 'config.json';
 const HUB_WRITE = 'hub.write';
@@ -37,8 +40,11 @@ const DAEMON_PATH = fileURLToPath(new URL('../daemon/main.js', import.meta.url))
 const SIGN_IN_HINT = 'Run `agentpulse pulse login`, then `agentpulse pulse start`.';
 const STALE_SERVICE_MESSAGE = 'The Pulse connector service points at an old daemon path.';
 const RECONCILE_STALE_MS = 5 * 60_000;
+/** A new pairing reads and writes its owner's Pulse log (hub.sync, log.write); Pulse running hub.* jobs (hub.write) is opt-in. */
+export const DEFAULT_PAIRING_CAPABILITIES = Object.freeze(['workspace.read', 'git.read', 'hub.sync', 'log.write']);
+const LOG_CAPABILITIES = Object.freeze(['hub.sync', 'log.write']);
 const DEFAULT_PAIRING_POLICY = Object.freeze({
-  capabilities: Object.freeze(['workspace.read', 'git.read']),
+  capabilities: DEFAULT_PAIRING_CAPABILITIES,
   providerPolicy: Object.freeze({
     providers: Object.freeze({}),
     maxConcurrency: 1,
@@ -71,6 +77,14 @@ async function openInBrowser(url) {
 }
 
 const BUSY_STATES = new Set(['running', 'idle_unpaired', 'starting']);
+/** SCOPE-02: what reading and writing the Pulse log needs from the sign-in; `pulse start` checks it first. */
+const LOG_SCOPES = Object.freeze(CONNECTOR_SCOPES.filter((scope) => scope === 'agent-hub:connector:sync' || scope === 'agent-hub:connector:commands'));
+
+/** The Pulse log scopes a sign-in lacks, when this machine uses the log (import, shadow or runner) on Pulse itself. */
+export function missingLogScopes(config, granted) {
+  if (!localScopeCheckApplies(config) || !(importEnabled(config) || config?.cloudFirst?.mode === 'runner')) return [];
+  return LOG_SCOPES.filter((scope) => !granted.includes(scope));
+}
 
 /** What the daemon's last heartbeat says beyond "running": not taking work, jobs being recovered, settlements given up. */
 function healthSummary(health) {
@@ -93,6 +107,10 @@ function healthSummary(health) {
   for (const job of health.settleFailed || []) {
     summary += ` Gave up settling job ${job.jobId} (${job.code}); the cloud will expire it as connector_no_result.`;
   }
+  const sync = health.runner?.runner;
+  if (sync?.state === 'blocked') summary += ` The runner is blocked: ${sync.reason}. Run \`${sync.fix}\`.`;
+  else if (sync?.state === 'error') summary += ` The runner stopped syncing: ${sync.reason} (applied ${sync.applied} of ${sync.head}).`;
+  else if (sync?.reason?.startsWith('sync failing')) summary += ` The runner is ${sync.state}: ${sync.reason}, ${sync.failures} failures in a row.`;
   return summary;
 }
 
@@ -103,6 +121,7 @@ export class ConnectorApplication {
     serviceManager = new ServiceManager({ daemonPath: DAEMON_PATH, configDir }),
     pairingPolicy = DEFAULT_PAIRING_POLICY,
     providerProbes = null,
+    doctorWarnings = { postgres: postgresHeadroom, hooks: hubHooks },
     fetch = globalThis.fetch,
     login = null,
     cliDefaults = readCliDefaults,
@@ -110,7 +129,9 @@ export class ConnectorApplication {
     log = (line) => process.stderr.write(`${line}\n`),
     startHealthTimeoutMs = 10_000,
     restartTimeoutMs = 60_000,
+    nodeVersion = process.versions.node,
   } = {}) {
+    this.nodeVersion = nodeVersion;
     this.startHealthTimeoutMs = startHealthTimeoutMs;
     this.restartTimeoutMs = restartTimeoutMs;
     this.configDir = configDir;
@@ -118,6 +139,7 @@ export class ConnectorApplication {
     this.serviceManager = serviceManager;
     this.pairingPolicy = structuredClone(pairingPolicy);
     this.providerProbes = providerProbes || this.#defaultProviderProbes.bind(this);
+    this.doctorWarnings = doctorWarnings;
     this.fetch = fetch;
     this.browserLogin = login || ((options) => loginWithBrowser({
       ...options,
@@ -236,12 +258,19 @@ export class ConnectorApplication {
   }
 
   async start() {
+    assertNodeFloor(this.nodeVersion);
     const config = await this.#config();
     const servicePath = await this.#servicePath();
     if (!servicePath.ok) throw new HubError(servicePath.code, `${STALE_SERVICE_MESSAGE} ${servicePath.hint}`);
     assertPairedConfig(config);
     const auth = await this.#authStatus();
     if (!auth.ok) throw new HubError('HUB_LOGIN_REQUIRED', `Pulse connector is not signed in. ${SIGN_IN_HINT}`);
+    const missingScopes = missingLogScopes(config, await this.tokenStore.scopes());
+    if (missingScopes.length) {
+      throw new HubError('HUB_SCOPE_MISSING', `The Pulse sign-in lacks ${missingScopes.join(', ')}, which the Pulse log needs. Run \`${SCOPE_FIX}\`, then start again.`, {
+        details: { missingScopes, fix: SCOPE_FIX },
+      });
+    }
     const requestedAt = Date.now();
     const service = await this.serviceManager.start();
     let daemonState = null;
@@ -372,7 +401,7 @@ export class ConnectorApplication {
   }
 
   async doctor() {
-    const checks = {};
+    const checks = { node: nodeFloor(this.nodeVersion) };
     const config = await this.#config(false);
     try {
       const directory = await lstat(this.configDir);
@@ -399,7 +428,13 @@ export class ConnectorApplication {
     checks.providers = await this.providerProbes();
     checks.pairing = pairedStatus(config);
     checks.auth = config ? await this.#authStatus() : { ok: false, code: 'HUB_NOT_INSTALLED' };
+    // Warnings only: they are reported, and never make the installation unhealthy.
+    const [postgres, hooks] = await Promise.all([this.doctorWarnings.postgres(), this.doctorWarnings.hooks()]);
+    checks.postgres = postgres;
+    checks.hooks = hooks;
+    const warnings = [postgres, hooks].filter((c) => c.warn).map((c) => c.message);
     const ok =
+      checks.node.ok &&
       checks.storage.ok &&
       checks.identity.ok &&
       checks.service.ok &&
@@ -411,9 +446,10 @@ export class ConnectorApplication {
       state: ok ? 'healthy' : 'unhealthy',
       ok,
       checks,
+      warnings,
       message: ok
         ? 'Pulse local installation, pairing and sign-in are healthy.'
-        : 'Pulse local installation has failed checks.',
+        : checks.node.ok ? 'Pulse local installation has failed checks.' : checks.node.message,
     };
   }
 
@@ -521,6 +557,38 @@ export class ConnectorApplication {
   }
 
   async hubWrite({ action }) {
+    return this.#grantToggle({
+      action, command: 'hub-write', add: [HUB_WRITE], remove: [HUB_WRITE],
+      messages: {
+        status: (on) => (on
+          ? 'Pulse may post to the local Agent Hub as you (hub.write is granted).'
+          : 'Pulse cannot post to the local Agent Hub (hub.write is off). Turn it on with `agentpulse pulse hub-write on`.'),
+        same: (on) => `hub.write is already ${on ? 'on' : 'off'}.`,
+        changed: (on) => (on
+          ? 'hub.write is on: Pulse can post, nudge, decide and accept on the local Agent Hub as you. The daemon picks up the new grant within a heartbeat.'
+          : 'hub.write is off: Pulse can no longer post to the local Agent Hub. Actions still queued for this machine expire.'),
+      },
+    });
+  }
+
+  /** The machine's access to its owner's Pulse log: hub.sync to read it, log.write to write it (apart from hub.write). */
+  async logWrite({ action }) {
+    return this.#grantToggle({
+      action, command: 'log-write', add: LOG_CAPABILITIES, remove: ['log.write'],
+      messages: {
+        status: (on) => (on
+          ? 'This machine reads and writes your Pulse log (hub.sync and log.write are granted).'
+          : 'This machine cannot write your Pulse log (log.write is off). Turn it on with `agentpulse pulse log-write on`.'),
+        same: (on) => `log.write is already ${on ? 'on' : 'off'}.`,
+        changed: (on) => (on
+          ? 'log.write is on: this machine reads and writes your Pulse log. The daemon picks up the new grant within a heartbeat.'
+          : 'log.write is off: this machine can still read your Pulse log, but no longer writes to it.'),
+      },
+    });
+  }
+
+  /** Grant or withdraw capabilities through the replace-grant path, and adopt the new grant version. */
+  async #grantToggle({ action, command, add, remove, messages }) {
     const config = await this.#config();
     if (!config.paired) {
       throw new HubError('HUB_NOT_PAIRED', 'This machine is not paired; run `agentpulse pulse pair` first.');
@@ -545,33 +613,21 @@ export class ConnectorApplication {
     if (!grant || grant.state !== 'active' || !Array.isArray(grant.capabilities)) {
       throw new HubError('HUB_GRANT_MISSING', 'This machine has no active grant in Pulse; pair it again.');
     }
-    const granted = grant.capabilities.includes(HUB_WRITE);
+    const granted = add.every((capability) => grant.capabilities.includes(capability));
     if (action === 'status') {
-      return {
-        command: 'hub-write',
-        enabled: granted,
-        policyVersion: grant.version,
-        message: granted
-          ? 'Pulse may post to the local Agent Hub as you (hub.write is granted).'
-          : 'Pulse cannot post to the local Agent Hub (hub.write is off). Turn it on with `agentpulse pulse hub-write on`.',
-      };
+      return { command, enabled: granted, policyVersion: grant.version, message: messages.status(granted) };
     }
     if (action !== 'on' && action !== 'off') {
-      throw new HubError('HUB_WRITE_ACTION_INVALID', `Unknown hub-write action: ${action}`);
+      throw new HubError(command === 'hub-write' ? 'HUB_WRITE_ACTION_INVALID' : 'HUB_GRANT_ACTION_INVALID', `Unknown ${command} action: ${action}`);
     }
     const enable = action === 'on';
-    if (enable === granted) {
-      return {
-        command: 'hub-write',
-        enabled: granted,
-        policyVersion: grant.version,
-        changed: false,
-        message: `hub.write is already ${granted ? 'on' : 'off'}.`,
-      };
+    const has = enable ? granted : remove.some((capability) => grant.capabilities.includes(capability));
+    if (enable ? has : !has) {
+      return { command, enabled: granted, policyVersion: grant.version, changed: false, message: messages.same(granted) };
     }
     const capabilities = enable
-      ? [...grant.capabilities, HUB_WRITE]
-      : grant.capabilities.filter((capability) => capability !== HUB_WRITE);
+      ? [...grant.capabilities, ...add.filter((capability) => !grant.capabilities.includes(capability))]
+      : grant.capabilities.filter((capability) => !remove.includes(capability));
     const replaced = await fetchJson({
       fetch: this.fetch,
       method: 'PUT',
@@ -594,15 +650,7 @@ export class ConnectorApplication {
       capabilities,
       paired: { ...config.paired, policyVersion: version },
     });
-    return {
-      command: 'hub-write',
-      enabled: enable,
-      policyVersion: version,
-      changed: true,
-      message: enable
-        ? 'hub.write is on: Pulse can post, nudge, decide and accept on the local Agent Hub as you. The daemon picks up the new grant within a heartbeat.'
-        : 'hub.write is off: Pulse can no longer post to the local Agent Hub. Actions still queued for this machine expire.',
-    };
+    return { command, enabled: enable, policyVersion: version, changed: true, message: messages.changed(enable) };
   }
 
   async stop({ revoke = false } = {}) {

package/src/lib/channelScanner.js

@@ -0,0 +1,99 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+// Ported from agents-hub lib/channels.mjs at 37a0b2f: the post header, role aliases, the header type and the walk that
+// dates headers (which carry a time but no date) backwards from the file's modified time.
+export const HEADER = /^## \[([A-Z][A-Z0-9 -]*?)\] (\d{1,2}):(\d{2})(?::(\d{2}))?(?: (IST|UTC|GMT))? ([^\n]*)$/;
+const ROLE_ALIASES = { 'PLATFORM-AUDITOR': 'PLATFORM AUDITOR', AUDITOR: 'PLATFORM AUDITOR' };
+export const normRole = (role) => {
+  const upper = String(role || '').toUpperCase().trim();
+  return ROLE_ALIASES[upper] || upper;
+};
+const DAY_S = 86400;
+const DAY_JUMP_S = 2 * 3600;
+const NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Every task channel the local hub shows: <root>/<repo>/.agents/<task>/channel.md, roots in the hub's order. A
+ * `<repo>/<task>` present under two roots is the first root's (as the hub resolves it); the others are returned in
+ * `collisions`. Names outside the channel key charset are returned in `unnamed`.
+ */
+export async function channelFiles(roots) {
+  const files = [];
+  const collisions = [];
+  const unnamed = [];
+  const seen = new Map();
+  for (const root of roots) {
+    let repos = [];
+    try {
+      repos = (await readdir(root)).sort();
+    } catch {
+      continue;
+    }
+    for (const repo of repos) {
+      const dir = path.join(root, repo, '.agents');
+      let tasks = [];
+      try {
+        tasks = (await readdir(dir)).sort();
+      } catch {
+        continue;
+      }
+      for (const task of tasks) {
+        const file = path.join(dir, task, 'channel.md');
+        let info;
+        try {
+          info = await stat(file);
+        } catch {
+          continue;
+        }
+        if (!info.isFile()) continue;
+        const key = `${repo}/${task}`;
+        if (!NAME.test(repo) || !NAME.test(task)) {
+          unnamed.push({ key, file });
+          continue;
+        }
+        if (seen.has(key)) {
+          collisions.push({ key, file, kept: seen.get(key) });
+          continue;
+        }
+        seen.set(key, file);
+        files.push({ key, repo, task, file, mtimeMs: info.mtimeMs, size: info.size });
+      }
+    }
+  }
+  return { files, collisions, unnamed };
+}
+
+export const readChannel = (file) => readFile(file, 'utf8');
+
+/**
+ * The posts of a channel file as whole blocks: each header line and every line up to the next header, with no line or
+ * character cap (the hub's parsePosts caps a body; an import must not). Text before the first header is not a post.
+ * `at` is each header's time on the date the backwards walk gives it.
+ */
+export function splitPosts(text, mtimeMs, utcOffsetS = -new Date(mtimeMs).getTimezoneOffset() * 60) {
+  const lines = String(text).replace(/\r/g, '').split('\n');
+  const raw = [];
+  let current = null;
+  for (const line of lines) {
+    const match = line.match(HEADER);
+    if (match) {
+      const head = match[6].trim();
+      let sec = Number(match[2]) * 3600 + Number(match[3]) * 60 + Number(match[4] || 0) + (match[5] === 'UTC' || match[5] === 'GMT' ? utcOffsetS : 0);
+      sec -= Math.floor(sec / DAY_S) * DAY_S;
+      current = { role: normRole(match[1]), head, type: head.split(/ [—(-] | — /)[0].trim().slice(0, 40), sec, lines: [line] };
+      raw.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  const mt = new Date(mtimeMs);
+  const day = new Date(mt.getFullYear(), mt.getMonth(), mt.getDate());
+  let later = mt.getHours() * 3600 + mt.getMinutes() * 60 + mt.getSeconds() + 600;
+  for (let k = raw.length - 1; k >= 0; k -= 1) {
+    if (raw[k].sec > later + DAY_JUMP_S) day.setDate(day.getDate() - 1);
+    later = raw[k].sec;
+    raw[k].at = day.getTime() + raw[k].sec * 1000;
+  }
+  return raw.map(({ role, head, type, at, lines: block }) => ({ role, head, type, at, text: block.join('\n').trimEnd() }));
+}

package/src/lib/clientInstaller.js

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import { chmod, copyFile, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HubError } from './errors.js';
+
+const CLIENTS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'clients');
+const MARKER = '/*PULSE_CLIENT_CONFIG*/ null';
+
+/**
+ * The agents-hub entry points every agent and hook already calls, with their git blob at the frozen 6b2fb0b. Cutover
+ * replaces each with the Pulse thin client, keeping the original beside it; rollback puts the original back.
+ */
+export const ENTRY_POINTS = Object.freeze([
+  { name: 'hub.mjs', client: 'hub.mjs', relative: 'hub.mjs', blob: 'f83f19a2bb6ed6236c48ed219e33a54998358731' },
+  { name: 'hook', client: 'hub-bridge.mjs', relative: path.join('hooks', 'hub-bridge.mjs'), blob: '3caacb1771e5efa0f354f9a0757c3c6f3561acae' },
+]);
+export const ORIGINAL_SUFFIX = '.pre-cutover';
+
+export const gitBlobSha = (bytes) => createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+
+/** A thin client with its configuration written in: `{ port, tokenFile, spoolDir, cliPath, offline }`. */
+export async function renderClient(client, config) {
+  const source = await readFile(path.join(CLIENTS, client), 'utf8');
+  if (source.split(MARKER).length !== 2) throw new HubError('HUB_CLIENT_TEMPLATE', `${client} has no configuration marker`);
+  return source.replace(MARKER, () => JSON.stringify(config));
+}
+
+export function clientConfig({ hubHome, port = 8890, offline = false }) {
+  return {
+    port,
+    tokenFile: path.join(hubHome, 'state', 'hub.token'),
+    spoolDir: path.join(hubHome, 'state', 'spool'),
+    cliPath: path.join(hubHome, 'hub.mjs'),
+    offline,
+  };
+}
+
+async function atomicWrite(file, text, mode) {
+  const temp = `${file}.pulse-${process.pid}.tmp`;
+  await writeFile(temp, text, { mode });
+  await chmod(temp, mode);
+  await rename(temp, file);
+}
+
+async function readOrNull(file) {
+  try {
+    return await readFile(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/**
+ * Install the thin clients over the entry points, online or offline. The first install keeps each original as
+ * `<file>.pre-cutover` and refuses unless it is exactly the 6b2fb0b blob; a later call only switches the client.
+ */
+export async function installClients({ hubHome, port = 8890, offline = false }) {
+  const config = clientConfig({ hubHome, port, offline });
+  const installed = [];
+  for (const entry of ENTRY_POINTS) {
+    const file = path.join(hubHome, entry.relative);
+    const original = `${file}${ORIGINAL_SUFFIX}`;
+    if (!(await readOrNull(original))) {
+      const current = await readOrNull(file);
+      if (!current) throw new HubError('HUB_ENTRY_POINT_MISSING', `${file} is missing`);
+      if (gitBlobSha(current) !== entry.blob) {
+        throw new HubError('HUB_ENTRY_POINT_CHANGED', `${file} is not agents-hub 6b2fb0b; cutover will not replace it`, { details: { file, blob: gitBlobSha(current) } });
+      }
+      await copyFile(file, original);
+      await chmod(original, 0o444);
+    }
+    await atomicWrite(file, await renderClient(entry.client, config), 0o755);
+    installed.push({ name: entry.name, file, offline });
+  }
+  return installed;
+}
+
+/** Put the 6b2fb0b entry points back, byte for byte, and drop the kept copies. */
+export async function restoreClients({ hubHome }) {
+  const restored = [];
+  for (const entry of ENTRY_POINTS) {
+    const file = path.join(hubHome, entry.relative);
+    const original = `${file}${ORIGINAL_SUFFIX}`;
+    const kept = await readOrNull(original);
+    if (!kept) {
+      const current = await readOrNull(file);
+      if (current && gitBlobSha(current) === entry.blob) { restored.push({ name: entry.name, file, already: true }); continue; }
+      throw new HubError('HUB_ENTRY_POINT_LOST', `${original} is missing, and ${file} is not the original`);
+    }
+    if (gitBlobSha(kept) !== entry.blob) throw new HubError('HUB_ENTRY_POINT_CHANGED', `${original} is not agents-hub 6b2fb0b`);
+    await chmod(original, 0o644);
+    await rename(original, file);
+    restored.push({ name: entry.name, file });
+  }
+  return restored;
+}
+
+/** Which entry points are the thin client now, and whether it is offline. */
+export async function clientState({ hubHome }) {
+  const out = {};
+  for (const entry of ENTRY_POINTS) {
+    const current = await readOrNull(path.join(hubHome, entry.relative));
+    const text = current ? current.toString('utf8') : '';
+    out[entry.name] = !current ? 'missing'
+      : gitBlobSha(current) === entry.blob ? 'original'
+        : /"offline":true/.test(text) ? 'client-offline' : /"offline":false/.test(text) ? 'client-online' : 'changed';
+  }
+  return out;
+}