@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.0.0

package/README.md

@@ -1,48 +1,85 @@
-# @agentpulselabs/cli-plugin-pulse
+# Pulse connector plugin
 
-An [oclif](https://oclif.io) plugin that adds the **`pulse`** topic — a portable, contract-enforced build
-discipline — to the `agentpulse` CLI. It is a thin `argv → core → stdout` seam over
-[`@agentpulselabs/pulse`](https://github.com/ashishcloud/agentpulse-pulse); all discipline lives in the core.
+`@agentpulselabs/cli-plugin-pulse` contributes the `agentpulse pulse` command group.
 
-> **Published to public npm** under the `@agentpulselabs` org (`publishConfig.access: "public"`). The CLI
-> (`@agentpulselabs/cli`) supports plugins via `@oclif/plugin-plugins`; this plugin installs through it.
+Commands:
 
-## Install
+```text
+agentpulse pulse install
+agentpulse pulse pair [--org <slug>] [--platform <url>] --root <rootId>=<path>
+agentpulse pulse login [--platform <url>]
+agentpulse pulse start
+agentpulse pulse status
+agentpulse pulse doctor
+agentpulse pulse stop
+agentpulse pulse restart
+agentpulse pulse mirror on|off|status
+agentpulse pulse hub-write on|off|status
+```
+
+## Replaces the deprecated build-discipline Pulse plugin
+
+Version 1.0.0 takes over the package name and the `pulse` topic from the deprecated build-discipline plugin (`@agentpulselabs/cli-plugin-pulse` 0.2.0, with `pulse gate|next|start|status|submit|verify`). Those commands are gone. The connector was previously developed as `@agentpulselabs/cli-plugin-hub`.
+
+Remove the old plugin first for a clean replace, then install or link the connector. Always use the full scoped name; a bare `pulse` resolves to an unrelated npm package.
 
 ```bash
-npm i -g @agentpulselabs/cli                              # the CLI (if not already installed)
-agentpulse plugins install @agentpulselabs/cli-plugin-pulse
-agentpulse pulse --help
+agentpulse plugins uninstall @agentpulselabs/cli-plugin-pulse
+agentpulse plugins install @agentpulselabs/cli-plugin-pulse   # once published
+agentpulse plugins link <path-to-this-repo>                   # local development instead of install
 ```
 
-This is the **user-installed** integration path (design decision): opt-in, decoupled release cadence, and the
-same mechanism any third party uses to add `agentpulse` commands.
+`agentpulse plugins update` does not move you to 1.0.0, because the old install is pinned to `0.2.0`; run `plugins install` explicitly. After `plugins unlink`, no `pulse` plugin is left, so install it again.
 
-## Commands
+A machine paired before the rename keeps its pairing, sign-in and state: the Keychain items, the `~/.config/agentpulse/hub` directory, the service label and the wire identifiers did not change. The installed launchd or systemd service still holds the absolute paths of the old install, though. If the daemon path changed, or the node binary it names was removed (for example by a node upgrade), `agentpulse pulse status`, `agentpulse pulse doctor` and `agentpulse pulse start` report `HUB_SERVICE_PATH_STALE`. Run `agentpulse pulse install` once, then `agentpulse pulse start`.
 
-| Command | What it does |
-|---|---|
-| `agentpulse pulse start --requirements "…" --name <name>` | Begin an engagement in the current repo (`.pulse/`). |
-| `agentpulse pulse next` | Emit the current phase work-list (prompts + JSON schema; contract injected). |
-| `agentpulse pulse submit --results-file r.json` | Validate your model's structured results vs schema + contract. |
-| `agentpulse pulse gate --approved [--decisions-file d.json]` | The human gate — advance the phase; lock product decisions. |
-| `agentpulse pulse verify` | Run the contract's gate command (`npm run check`); exits non-zero if red. |
-| `agentpulse pulse status` | Phase, contract, board progress. |
+## How it works
 
-The MCP server (`pulse-mcp`, shipped by `@agentpulselabs/pulse`) is the primary seam for interactive agents
-(Cursor/Codex/Claude). This CLI plugin is the universal shell fallback: same core, same `.pulse/` state.
+The plugin manages a separate launchd (macOS) or systemd-user (Linux) companion. The oclif command process is never the daemon. Local configuration and state are owner-only. The OAuth tokens and the local Ed25519 key live only in Keychain or libsecret; if neither is available the connector fails closed.
 
-## Architecture
+Authentication is the platform's OAuth (Phase 1). `agentpulse pulse pair` and `agentpulse pulse login` run the same browser PKCE flow as `agentpulse login` (public client `agentpulse-cli`, loopback `127.0.0.1`), but keep their own token store and never write the CLI's `config.json`. The CLI config is only read for the default platform URL and dev-org slug.
 
-```
-argv → src/commands/pulse/<verb>.js  (thin oclif Command, parses flags)
-          → src/runPulse.js           (pure: verb → engine method; no oclif, testable)
-             → @agentpulselabs/pulse       (the brain: state machine + contract + validator + gates)
-                → .pulse/ in the repo  (durable, git-tracked truth)
-```
+Pairing resolves the dev-org through `/api/team/dev-orgs`, mints a dev-org token through `/api/team/dev-orgs/:id/cli-token`, and registers the machine with `POST /api/agent-hub/user/machines` and a frozen least-authority grant. Every connector request carries `Authorization: Bearer`, `X-Serverless-Authorization` on Cloud Run dev-orgs, and the machine, session and policy-version headers.
+
+If the platform can't be reached to refresh the sign-in, the daemon reports `reconnecting`, claims nothing and retries with backoff. When a refresh is refused (`invalid_grant`), it stops claiming work and `agentpulse pulse status` prints the commands to run. Today that refusal is expected about every 12 hours, until the platform fixes refresh for the `agentpulse-cli` client. A revoked machine stops for good; signing in again never revives it. The Ed25519 identity is kept locally for Phase 2 (DPoP) and is not used for authentication.
+
+The daemon restarts itself by exiting with code 75; launchd (`KeepAlive.SuccessfulExit=false`) and systemd (`Restart=on-failure`) start it again. It does so when any file under its own `src/` (data files such as `mirror-contract.json` included, dotfiles not) or its `package.json` changes (2 s after the last write, and only if the contents differ), when `restart.request` appears in its config directory, or when the cycle or a mirror pass makes no progress for 3 minutes (`cycle_stalled` in `daemon-error.log`). A code or request restart drains first: it claims no new job, lets running jobs finish and settle (health shows `restarting` with the job ids), and only aborts them, as `HUB_DAEMON_RESTARTING`, after 15 minutes. A stall aborts at once. A request older than the running process is dropped, since the restart it asked for already happened. `agentpulse pulse restart` writes that file and waits up to 60 s for a new process, so it needs no `launchctl` or `systemctl`; it refuses when the daemon has no fresh heartbeat. After more than 5 restarts in 5 minutes the daemon stays up instead, `agentpulse pulse status` reports `restart_loop`, and a pending restart is deferred until the window clears. `pulse stop` and SIGTERM always win and exit 0.
+
+The connector accepts only registered intents:
+
+- `workspace.read` and `workspace.write`
+- `git.read` and `git.write`
+- `worktree.create`
+- `agent.cursor.invoke` and `agent.claude.invoke`
+- `hub.write`, only after `agentpulse pulse hub-write on`
+
+It does not accept shell commands, absolute cloud paths, package installation, secret reads, permission changes, push, release, production actions, or remote grant expansion.
+
+## Acting on the local Agent Hub from Pulse
+
+`agentpulse pulse hub-write on` lets Pulse post to the local Agent Hub as you: a chat message, a NUDGE or STATUS? to agents, a decision or change request on a stream, accepting a delivery, or a reply to a bus ask. It is off on a new pairing. `on` and `off` replace this machine's cloud grant with `hub.write` added or removed (nothing else changes) and store the new policy version in the daemon config; the daemon adopts it on its next heartbeat. `status` reads the grant from Pulse.
+
+Each action arrives as a typed `hub.*` job and becomes exactly one POST to the hub on `127.0.0.1` with the hub token, as the principal `user`, to `/api/chat/post`, `/api/message`, `/api/decision`, `/api/accept` or `/bus/ack`, and nothing else. If the hub may have taken a write whose result was never recorded (the daemon stopped mid-request, or the hub did not answer), the action ends as `hub_write_unconfirmed` instead of being sent twice; check the hub before sending it again. A hub that is not running gives `hub_unreachable`; a write the hub rejects gives `hub_refused` with its reason.
+
+## Mirroring the local Agent Hub
+
+`agentpulse pulse mirror on` lets the paired daemon mirror your local Agent Hub into Pulse, so its deliveries, streams, agents, graph, chat (task, project, one-to-one and bus threads), inbox and Cursor rule packs show there read-only. It is off on a new install. `on` and `off` change only `mirror.localHub` in the daemon config, and the daemon picks the change up within a heartbeat. `off` stops pushing; items already mirrored stay in Pulse. `status` shows the last sync, how many items are mirrored, and how many were not mirrored, by kind and reason.
+
+The mirror needs the `agent-hub:connector:mirror` scope. A sign-in from before this version lacks it; run `agentpulse pulse login` once.
+
+How it reads and what it sends:
+
+- It finds the hub from the `com.agentpulse.agents-hub` launch agent (or `mirror.hub.dir` and `mirror.hub.port` in the daemon config) and only sends GETs to an allow-list of endpoints on `127.0.0.1`, with the hub's `state/hub.token`. It never writes to the hub, never runs `hub.mjs`, and never opens `state/` files other than the token.
+- It follows the hub's `/api/stream` feed, re-reads only the affected endpoints about 300 ms after a change, runs a full reconcile 60 seconds after the last one ended, and reconnects with backoff.
+- The four graph windows (which also carry edges and bus messages) are the hub's slowest read. After a change they are re-read in a pass of their own, at most once every 3 seconds counted from the end of the last one. The hub announces each of the connector's own graph reads as a change, so a hub change that arrives during one of those reads or within 1.5 seconds after it is most likely an echo, so it re-reads the windows only after 10 seconds; any other change brings the 3 second gap back. Task briefs follow in the next pass, four at a time and for at most 3 seconds. `agentpulse pulse mirror status` shows how long the last pass took.
+- Only new or changed items are sent, in batches of at most 500 items and 2 MiB. Items that disappear are deleted in Pulse on the full reconcile, and only for sources that were read completely.
+- Absolute paths are rewritten before upload: paths in a known repo become repo-relative, workspace and home paths lose their prefix, and any other path keeps only its last segment. A home folder never shows its user name. An item that still carries a path, a token-looking string or the hub token is withheld and counted, never sent.
+- 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.
 
-## Test
+## Local checks
 
 ```bash
-node --test "test/**/*.test.js"   # exercises runPulse over a real .pulse/, no @oclif/core needed
+npm test
+npm run check
 ```

package/package.json

@@ -1,20 +1,10 @@
 {
   "name": "@agentpulselabs/cli-plugin-pulse",
-  "version": "0.2.0",
-  "description": "oclif plugin that adds the `pulse` topic (portable, contract-enforced build discipline) to the agentpulse CLI. User-installed: `agentpulse plugins install @agentpulselabs/cli-plugin-pulse`. A thin argv→core seam over @agentpulselabs/pulse.",
+  "version": "1.0.0",
+  "description": "AgentPulse CLI plugin for installing and operating the Pulse local connector (replaces the deprecated build-discipline Pulse plugin).",
   "type": "module",
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ashishcloud/agentpulse-cli-plugin-pulse.git"
-  },
-  "homepage": "https://github.com/ashishcloud/agentpulse-cli-plugin-pulse#readme",
-  "bugs": {
-    "url": "https://github.com/ashishcloud/agentpulse-cli-plugin-pulse/issues"
-  },
+  "private": false,
   "files": [
     "src",
     "README.md"
@@ -24,12 +14,13 @@
     "topicSeparator": " ",
     "topics": {
       "pulse": {
-        "description": "Run a contract-enforced build discipline engagement (Discovery → Stories → Architecture → Build → Deliver)."
+        "description": "Install, pair, and operate the Pulse local connector."
       }
     }
   },
   "scripts": {
-    "test": "node --test \"test/**/*.test.js\""
+    "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"
   },
   "engines": {
     "node": ">=20"
@@ -38,12 +29,13 @@
     "oclif-plugin",
     "agentpulse",
     "pulse",
+    "agent-hub",
     "cli"
   ],
-  "dependencies": {
-    "@agentpulselabs/pulse": "^0.1.0"
-  },
   "peerDependencies": {
     "@oclif/core": ">=3"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/commands/pulse/doctor.js

@@ -0,0 +1,14 @@
+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);
+    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/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/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/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/start.js

@@ -1,26 +1,14 @@
-import { Flags } from '@oclif/core';
 import BaseCommand from '../../lib/BaseCommand.js';
-import { runPulse } from '../../runPulse.js';
+import { getDefaultApplication } from '../../lib/application.js';
 
-/** `agentpulse pulse start` — begin an engagement in the current repo (.pulse/). Thin argv→core shim. */
 export default class PulseStart extends BaseCommand {
-  static description = 'Begin a Pulse engagement in the current repo (.pulse/).';
-  static examples = ['<%= config.bin %> pulse start --requirements "Build a widget store" --name widgets'];
-  static flags = {
-    requirements: Flags.string({ description: 'Raw requirements text (or use --requirements-file).', required: false }),
-    'requirements-file': Flags.string({ description: 'Path to a file containing the requirements.' }),
-    grounding: Flags.string({ description: 'Optional domain grounding notes.' }),
-    name: Flags.string({ description: 'Short engagement name (used for filenames).', default: 'engagement' }),
-  };
+  static description = 'Start the installed Pulse companion daemon.';
+  static examples = ['<%= config.bin %> pulse start'];
 
   async run() {
     const { flags } = await this.parse(PulseStart);
-    const fs = await import('node:fs');
-    const requirements = flags['requirements-file']
-      ? fs.readFileSync(flags['requirements-file'], 'utf8')
-      : (flags.requirements || '');
-    const result = await runPulse('start', { requirements, grounding: flags.grounding, name: flags.name });
-    this.log(JSON.stringify(result, null, 2)); // default: raw JSON (auto-silenced under --json)
-    return result;                              // --json: standard envelope
+    const result = await (this.runtime || getDefaultApplication()).start(flags);
+    this.log(result.message);
+    return result;
   }
 }

package/src/commands/pulse/status.js

@@ -1,14 +1,14 @@
 import BaseCommand from '../../lib/BaseCommand.js';
-import { runPulse } from '../../runPulse.js';
+import { getDefaultApplication } from '../../lib/application.js';
 
-/** `agentpulse pulse status` — where does the engagement stand? Phase, contract, board progress. */
 export default class PulseStatus extends BaseCommand {
-  static description = 'Show engagement status: phase, contract, board progress.';
+  static description = 'Show Pulse companion service, pairing, and health status.';
   static examples = ['<%= config.bin %> pulse status'];
 
   async run() {
-    const result = await runPulse('status', {});
-    this.log(JSON.stringify(result, null, 2)); // default: raw JSON (auto-silenced under --json)
-    return result;                              // --json: standard envelope
+    const { flags } = await this.parse(PulseStatus);
+    const result = await (this.runtime || getDefaultApplication()).status(flags);
+    this.log(result.message);
+    return result;
   }
 }

package/src/commands/pulse/stop.js

@@ -0,0 +1,24 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseStop extends BaseCommand {
+  static description = 'Stop the Pulse companion and optionally revoke this machine.';
+  static examples = [
+    '<%= config.bin %> pulse stop',
+    '<%= config.bin %> pulse stop --revoke',
+  ];
+  static flags = {
+    revoke: Flags.boolean({
+      description: 'Revoke this machine after stopping the companion.',
+      default: false,
+    }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseStop);
+    const result = await (this.runtime || getDefaultApplication()).stop(flags);
+    this.log(result.message);
+    return result;
+  }
+}

package/src/daemon/main.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultConfigDirectory } from '../lib/application.js';
+import { runDaemon } from '../lib/daemonProcess.js';
+import { ServiceManager } from '../lib/serviceManager.js';
+
+const MIRROR_FAILURES = new Set(['mirror_failed', 'mirror_blocked', 'mirror_stream_failed']);
+const ERROR_EVENTS = new Set([
+  'job_failed', 'job_refused', 'job_settle_failed', 'cycle_stalled', 'drain_timed_out', 'daemon_start_failed',
+  'daemon_shutdown_failed', 'source_watch_refused', 'source_watch_failed',
+]);
+
+/** One redacted line per job, local hub or restart event; failures go to daemon-error.log, the rest to daemon.log. */
+function logEvent(event, details) {
+  const line = `Pulse ${event} ${JSON.stringify({ at: new Date().toISOString(), ...details })}\n`;
+  (ERROR_EVENTS.has(event) ? process.stderr : process.stdout).write(line);
+}
+
+function configDirectory(argv) {
+  const index = argv.indexOf('--config-dir');
+  return index === -1 ? defaultConfigDirectory() : path.resolve(argv[index + 1]);
+}
+
+runDaemon({
+  directory: configDirectory(process.argv.slice(2)),
+  pluginRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..'),
+  logDir: new ServiceManager({}).logDir,
+  log: logEvent,
+  mirrorLog: (event, details) => {
+    if (MIRROR_FAILURES.has(event)) process.stderr.write(`Pulse ${event}: ${details.code}\n`);
+  },
+}).catch((error) => {
+  process.stderr.write(`Pulse daemon failed: ${error.code || 'HUB_DAEMON_FAILED'}: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/src/lib/BaseCommand.js

@@ -1,37 +1,37 @@
 import { Command } from '@oclif/core';
 
-/**
- * BaseCommand — the pulse plugin's half of the machine-readable CLI contract (docs/PLAN.md M0), matching the host
- * CLI's BaseCommand so `agentpulse pulse <verb> --json` yields the SAME standard envelope as first-party commands:
- *
- *   success:  { tool:'agentpulse', command:'pulse status', version, ok:true,  result }
- *   error:    { tool:'agentpulse', command:'pulse status', version, ok:false, error:{ code, message } }
- *
- * Behavior note (deliberate, back-compat): pulse output is machine-oriented (work-lists with prompts + JSON
- * schemas an agent consumes), so the DEFAULT (no --json) still prints the raw engine result as pretty JSON —
- * exactly as before. `--json` layers the standard envelope on top. Both are JSON; --json is the stable contract.
- */
 export default class BaseCommand extends Command {
   static enableJsonFlag = true;
 
   toSuccessJson(result) {
-    const marked = result && typeof result === 'object' && result.__ap === true;
-    const ok = marked ? result.ok : true;
-    const payload = marked ? result.result : result;
-    return { tool: 'agentpulse', command: this.commandName(), version: this.config?.version, ok, result: payload };
+    return {
+      tool: 'agentpulse',
+      command: this.commandName(),
+      version: this.config?.version,
+      ok: true,
+      result,
+    };
   }
 
-  toErrorJson(err) {
+  toErrorJson(error) {
     return {
-      tool: 'agentpulse', command: this.commandName(), version: this.config?.version, ok: false,
-      error: { code: (err && err.code) || 'E_ERROR', message: (err && err.message) || String(err) },
+      tool: 'agentpulse',
+      command: this.commandName(),
+      version: this.config?.version,
+      ok: false,
+      error: {
+        code: error?.code || 'HUB_ERROR',
+        message: error?.message || String(error),
+      },
     };
   }
 
-  commandName() { return String(this.id || this.ctor?.id || '').replace(/:/g, ' '); }
-
-  fail(code, message, exit = 1) { process.exitCode = exit; this.error(message, { code, exit }); }
+  commandName() {
+    return String(this.id || this.ctor?.id || '').replace(/:/g, ' ');
+  }
 
-  /** A successful run that reports ok:false and exits non-zero, carrying its full payload (e.g. `verify` red). */
-  problem(payload, exit = 1) { process.exitCode = exit; return { __ap: true, ok: false, result: payload }; }
+  fail(code, message, exit = 1) {
+    process.exitCode = exit;
+    this.error(message, { code, exit });
+  }
 }