@webority/ensemble 0.5.5 → 0.5.8

package/README.md

@@ -1,8 +1,9 @@
 # @webority/ensemble
 
 Connect a machine to your [Ensemble](https://ensemble.host) Console. Installs the local **agent
-runner** (runs your AI coding sessions, appears in your fleet) and wires **ensemble-bus** into your
-coding CLIs so your sessions message each other — all **scoped to your organization**.
+runner** (runs your AI coding sessions, appears in your fleet) and wires the **ensemble** session bus into your
+coding CLIs — **lifecycle hooks** (mail at turn boundaries) **and MCP** (first-class
+who/send/read/reply tools) — so sessions message each other, scoped to your organization.
 
 ## Install & enrol
 Get an **enrollment token** from the portal → *Connect Runner*, then:
@@ -25,14 +26,34 @@ irm https://ensemble.host/install.ps1 | iex   # then: ensemble enroll --token <T
 ```
 
 `enroll` exchanges your enrollment token for a **per-machine token** (revocable individually from the
-portal), downloads + configures + auto-starts the runner, and wires the bus into whichever of
-`claude` / `codex` / `grok` / `gemini` / `opencode` it finds. **Your subscription logins never leave
-your machine** — the server only ever sees a machine token.
+portal), downloads + configures + auto-starts the runner, and for **each detected coding agent**:
+
+| Agent | Hooks | MCP |
+|---|---|---|
+| Claude | `~/.claude/settings.json` | `~/.claude.json` → `ensemble` |
+| Codex | `~/.codex/hooks.json` | `~/.codex/config.toml` |
+| Grok | `~/.grok/hooks/agent-bus.json` | `~/.grok/config.toml` |
+| OpenCode | (MCP primary) | `~/.config/opencode/opencode.json` → `mcp.ensemble` |
+| OMP (oh-my-pi) | `~/.omp/agent/ensemble-hooks.json` | `~/.omp/agent/mcp.json` |
+| Gemini | best-effort | `~/.gemini/settings.json` |
+| Antigravity | `~/.antigravity/hooks.json` | `~/.antigravity/mcp.json` |
+
+1. **Hooks** — mail at turn boundaries  
+2. **MCP** — `ensemble mcp --engine <e>` as server name **`ensemble`**
+
+Fleet playbook: `docs/FLEET.md`.  
+**Your subscription logins never leave your machine.** Restart open agent sessions after enroll/hooks.
 
 ## Commands
-- `ensemble enroll --token <t> [--api <url>] [--name <machine>]`
-- `ensemble status` — connection + your org's live session mailboxes
-- `ensemble hooks` — re-wire the bus after installing a new coding CLI
+- `ensemble login` / `ensemble enroll --token <t>` — auth + install runtime + wire hooks/MCP
+- `ensemble install` — force-refresh runner/runtime into `~/.ensemble`; re-wires hooks/MCP if already enrolled
+- `ensemble status` — connection, engines detected, Grok MCP path check
+- `ensemble hooks` — re-wire **hooks + MCP** into every detected coding CLI (safe on existing configs)
+
+### Grok / Codex MCP (existing config)
+When `~/.grok/config.toml` (or Codex) already exists, install **upserts** only
+`[mcp_servers.ensemble]` — other servers (e.g. weborityos) and UI/cli sections are kept.
+Command points at `~/.ensemble/bin/ensemble-runtime` only (no `ensemble-bus` binary or alias).
 
 ## Security model
 Machine ⇄ server auth is a **per-machine token**, resolved server-side to your organization; every

package/bin/ensemble.js

@@ -3,8 +3,35 @@
 const os = require('os');
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const core = require('../lib/core');
 
+// Bus subcommands are handled by the internal `ensemble-runtime` binary; the Node CLI forwards argv
+// through to it (inherited stdio, same exit code) so users type only one command: `ensemble <sub>`.
+const BUS_SUBCOMMANDS = new Set([
+  'send', 'who', 'read', 'reply', 'label', 'hook', 'mcp', 'register', 'detach', 'ask',
+  'rooms', 'room-create', 'room-send', 'room-messages', 'room-add', 'room-remove',
+]);
+
+function forwardToRuntime(argv) {
+  const runtimePath = core.runtimeBin();
+  if (!core.isUsableBinary(runtimePath)) {
+    core.die('the Ensemble runtime is not installed — run `ensemble install` to download it.');
+  }
+  // Prefer env; else load ~/.ensemble/machine-token so bus subcommands work in shells that never
+  // got setx/export (common after enroll from another terminal).
+  const env = { ...process.env };
+  if (!env.ENSEMBLE_MACHINE_TOKEN) {
+    const tokenFile = path.join(core.ENSEMBLE_DIR, 'machine-token');
+    if (fs.existsSync(tokenFile)) {
+      env.ENSEMBLE_MACHINE_TOKEN = fs.readFileSync(tokenFile, 'utf8').trim();
+    }
+  }
+  const r = spawnSync(runtimePath, argv, { stdio: 'inherit', env });
+  if (r.error) core.die(r.error.message);
+  process.exit(r.status == null ? 1 : r.status);
+}
+
 function parseArgs(argv) {
   const args = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -19,10 +46,11 @@ function parseArgs(argv) {
 }
 
 function reportSetup(wired) {
-  core.log('• wired session hooks: ' + (wired.join(', ') || '(no supported coding CLI found — run `ensemble hooks` after installing claude/codex/grok)'));
+  core.log('• wired hooks+MCP: ' + (wired.join(', ') || '(no supported coding CLI found — run `ensemble hooks` after installing agents)'));
   core.log('• installed auto-start + launched the runner');
-  core.log('\n✓ Done. This machine runs your Ensemble runner and its coding sessions now share the bus (scoped to your org).');
-  core.log('  Open a NEW terminal (so ENSEMBLE_MACHINE_TOKEN loads), then start Claude/Codex/Grok as usual.');
+  core.log('\n✓ Done. This machine runs your Ensemble runner; sessions share the bus (hooks + MCP).');
+  core.log('  Restart open coding agents so they load the ensemble MCP server.');
+  core.log('  Supported: claude, codex, grok, opencode, omp (oh-my-pi), gemini, antigravity.');
 }
 
 // Browser sign-in (device flow) — no token to copy. The recommended path.
@@ -56,15 +84,26 @@ async function waitForApproval(api, grant) {
   core.die('timed out waiting for approval — nothing was installed. Run `ensemble login` again.');
 }
 
-// Explicit (re)install of the runner + bus. Normally runs automatically at `npm install`.
+// Explicit (re)install of the runner + runtime into ~/.ensemble. Always refreshes binaries so
+// upgrades replace stubs / old builds. If already enrolled, re-wires hooks+MCP (Grok/Codex/… with
+// existing config.toml get [mcp_servers.ensemble] upserted without wiping other servers).
+// `npm install` does NOT populate ~/.ensemble — there is no postinstall.
 async function install() {
   core.assertSupported();
-  await core.ensureBinaries();
-  core.log('✓ Ensemble runtime installed. Next:  ensemble login');
+  await core.ensureBinaries({ force: true });
+  const tokenFile = path.join(core.ENSEMBLE_DIR, 'machine-token');
+  if (fs.existsSync(tokenFile)) {
+    const wired = core.wireHooks();
+    core.log('✓ Ensemble runtime reinstalled.');
+    core.log('• re-wired hooks+MCP: ' + (wired.join(', ') || '(no coding CLI detected)'));
+    core.log('  Restart open coding agents so they load the ensemble MCP server.');
+  } else {
+    core.log('✓ Ensemble runtime installed. Next:  ensemble login');
+  }
 }
 
-// Headless / CI path: enrol with a copy-pasted enrollment token. Auth only — the runtime is
-// installed at `npm install` (or `ensemble install`).
+// Headless / CI path: enrol with a copy-pasted enrollment token. The runtime is populated into
+// ~/.ensemble here (ensureRuntime) if it isn't already — same as `ensemble install`/`login`.
 async function enroll(args) {
   const token = args.token || process.env.ENSEMBLE_ENROLL_TOKEN;
   if (!token) core.die('missing --token <enrollment-token> — get it from your Ensemble portal → Connect Runner, or use `ensemble login` for browser sign-in');
@@ -80,13 +119,41 @@ async function enroll(args) {
 async function status(args) {
   const api = args.api || core.DEFAULT_API;
   const tokenFile = path.join(core.ENSEMBLE_DIR, 'machine-token');
-  if (!fs.existsSync(tokenFile)) return core.log('not enrolled — run: ensemble enroll --token <token>');
+  if (!fs.existsSync(tokenFile)) return core.log('not enrolled — run: ensemble enroll --token <token>  (or: ensemble login)');
   const t = fs.readFileSync(tokenFile, 'utf8').trim();
+  core.log('Ensemble status @ ' + api);
+  const runtimeExe = core.runtimeBin();
+  core.log('• runtime binary: ' + (core.isUsableBinary(runtimeExe) ? 'ok (' + runtimeExe + ')' : 'MISSING/STUB — ensemble install'));
+  const engines = ['claude', 'codex', 'grok', 'opencode', 'omp', 'gemini', 'antigravity'];
+  const present = engines.filter((e) => core.enginePresent(e));
+  core.log('• engines detected: ' + (present.join(', ') || 'none'));
+  // Quick MCP path check for engines that use a known config file.
+  if (core.enginePresent('grok')) {
+    const grokToml = path.join(os.homedir(), '.grok', 'config.toml');
+    if (fs.existsSync(grokToml)) {
+      const txt = fs.readFileSync(grokToml, 'utf8');
+      const hasEnsemble = /\[mcp_servers\.ensemble\]/.test(txt);
+      const pointsRuntime = /ensemble-runtime/.test(txt);
+      const hasLegacyBus = /ensemble-bus/.test(txt);
+      core.log('• grok MCP: ' + (hasEnsemble && pointsRuntime && !hasLegacyBus
+        ? 'configured (ensemble-runtime) in ~/.grok/config.toml'
+        : hasLegacyBus
+          ? 'LEGACY ensemble-bus path — run: ensemble hooks'
+          : 'NOT wired — run: ensemble hooks'));
+    } else {
+      core.log('• grok MCP: no ~/.grok/config.toml — run: ensemble hooks');
+    }
+  }
+  core.log('• run `ensemble hooks` to (re)wire hooks+MCP for all detected engines');
   const res = await core.request('GET', api.replace(/\/$/, '') + '/api/bus/who', { 'X-Ensemble-Machine-Token': t });
   if (res.status === 200) {
     const mbx = JSON.parse(res.body);
-    core.log('✓ connected to ' + api + ' — your org has ' + mbx.length + ' mailbox(es):');
-    mbx.slice(0, 25).forEach((m) => core.log('   ' + m.name + '  (' + m.engine + ')'));
+    core.log('✓ connected — ' + mbx.length + ' mailbox(es) (label / focus / engine):');
+    mbx.slice(0, 30).forEach((m) => {
+      const label = m.label ? m.label : '-';
+      const focus = m.focus ? m.focus : '-';
+      core.log('   ' + m.name + '  [' + (m.engine || '?') + ']  ' + (m.status || '') + '  label=' + label + '  focus=' + focus);
+    });
   } else {
     core.log('✗ machine token not accepted (HTTP ' + res.status + ') — re-enroll with a fresh enrollment token.');
   }
@@ -100,11 +167,21 @@ function usage() {
         sign in via your browser + set up this machine (downloads the runtime on first run)
   ensemble enroll --token <enrollment-token> [--api <url>] [--name <machine>]
         headless / CI: enrol with an enrollment token from the portal
-  ensemble install        (re)download the runner + bus for this platform
+  ensemble install        (re)download the runner + runtime for this platform
   ensemble status         show connection + your org's live session mailboxes
-  ensemble hooks          (re)wire ensemble-bus into installed coding CLIs
+  ensemble hooks          (re)wire ensemble hooks + MCP into installed coding CLIs
   ensemble version
 
+Session bus — message other agent sessions (forwarded to the ensemble runtime):
+  ensemble who [--all] [--label <f>]        list live session mailboxes
+  ensemble label "<purpose>" --engine <e>   set this session's discovery label/focus
+  ensemble send <to> "<msg>" --from <me> [--intent <i>] [--expect none|ack|reply|done]
+  ensemble read --from <me> [--peek]        read + mark-read this mailbox
+  ensemble reply "<msg>" --from <me> --thread <guid>
+  ensemble ask "<question>" --engine <e>    ask the human (default: mobile)
+  ensemble rooms | room-create | room-add | room-remove | room-send | room-messages
+  ensemble register | detach | hook | mcp   (used by lifecycle hooks + MCP wiring)
+
 Run \`ensemble login\` and approve the machine in your browser.`);
 }
 
@@ -117,8 +194,20 @@ Run \`ensemble login\` and approve the machine in your browser.`);
     else if (cmd === 'enroll') await enroll(args);
     else if (cmd === 'install') await install();
     else if (cmd === 'status') await status(args);
-    else if (cmd === 'hooks') { core.log('wired: ' + (core.wireHooks().join(', ') || 'none')); }
+    else if (cmd === 'hooks') {
+      // Ensure a usable (non-stub) runtime BEFORE wiring — otherwise every engine gets pointed at a
+      // dead path. Fails closed on unsupported platforms. No ensemble-bus compat alias.
+      await core.ensureRuntime();
+      core.removeLegacyBusArtifacts();
+      const wired = core.wireHooks();
+      core.log('wired hooks+MCP: ' + (wired.join(', ') || 'none'));
+      if (!wired.some((w) => w.endsWith(':mcp'))) {
+        core.log('(no MCP wired — install a coding CLI, then re-run ensemble hooks)');
+      }
+      core.log('(restart open coding-agent sessions so they pick up MCP server changes)');
+    }
     else if (cmd === 'version' || cmd === '--version' || cmd === '-v') core.log(require('../package.json').version);
+    else if (BUS_SUBCOMMANDS.has(cmd)) forwardToRuntime(argv);
     else usage();
   } catch (e) {
     core.die(e && e.message ? e.message : String(e));

package/lib/core.js

@@ -82,32 +82,129 @@ function runtimePaths() {
   const pf = platform();
   return {
     pf,
-    busPath: path.join(BIN_DIR, 'ensemble-bus' + pf.exe),
+    runtimePath: path.join(BIN_DIR, 'ensemble-runtime' + pf.exe),
     runnerPath: path.join(RUNNER_DIR, 'Ensemble.Runner' + pf.exe),
   };
 }
 
-// The runner + bus are downloaded at `npm install` (postinstall) or `ensemble install` — NOT at login.
+// The ensemble-runtime binary path (the internal .NET CLI the Node wrapper forwards bus subcommands to).
+function runtimeBin() {
+  return runtimePaths().runtimePath;
+}
+
+// Real runtime/runner single-file binaries are tens of MB. Anything smaller is corrupt/stub.
+const MIN_BINARY_BYTES = 1_000_000;
+
+function isUsableBinary(filePath) {
+  try {
+    return fs.existsSync(filePath) && fs.statSync(filePath).size >= MIN_BINARY_BYTES;
+  } catch (e) {
+    return false;
+  }
+}
+
+// The npm package version is the release version-of-record (published packages carry the real value;
+// a repo checkout is 0.0.0). The installed runtime records the version it was written for in
+// ~/.ensemble/.runtime-version; a later login/enroll/hooks after an `npm upgrade` sees the mismatch
+// and force-refreshes the binaries — this is what actually lands a new release across the fleet.
+// Previously only an explicit `ensemble install` upgraded, so login/enroll/hooks kept the stale
+// runner/runtime forever. [BUG-06673]
+const PKG_VERSION = (() => {
+  try { return String(require('../package.json').version || ''); } catch (e) { return ''; }
+})();
+const VERSION_MARKER = path.join(ENSEMBLE_DIR, '.runtime-version');
+
+function readInstalledVersion() {
+  try { return fs.readFileSync(VERSION_MARKER, 'utf8').trim(); } catch (e) { return ''; }
+}
+function writeInstalledVersion() {
+  try { fs.writeFileSync(VERSION_MARKER, PKG_VERSION + '\n'); } catch (e) { /* best-effort */ }
+}
+// Stale when the marker doesn't match the current package version. An unknown package version (dev
+// checkout = 0.0.0/empty) never counts as stale, so a dev tree doesn't thrash on every command; an
+// ABSENT marker (a pre-versioning 0.5.x install) counts as stale so the first run upgrades it.
+function installedVersionCurrent() {
+  if (!PKG_VERSION || PKG_VERSION === '0.0.0') return true;
+  return readInstalledVersion() === PKG_VERSION;
+}
+
+// Move a freshly-written temp binary onto dest, tolerating a Windows lock on the old binary (the
+// running runner holds Ensemble.Runner.exe open). Windows permits renaming a running exe, so rename
+// the locked old file aside, then move the new one into place; the old process keeps its aside until
+// it restarts. Stale asides are swept best-effort.
+function placeBinary(tmp, dest) {
+  let aside = null;
+  try {
+    if (fs.existsSync(dest)) {
+      // Always move the current binary aside FIRST (Windows permits renaming even a running exe), so
+      // dest is never left missing if the place step then fails. The old process keeps its aside.
+      aside = dest + '.old-' + Date.now();
+      fs.renameSync(dest, aside);
+    }
+    fs.renameSync(tmp, dest);
+  } catch (e) {
+    // Cross-device or rename edge — fall back to a copy.
+    try {
+      fs.copyFileSync(tmp, dest);
+      try { fs.unlinkSync(tmp); } catch (_) { /* ignore */ }
+    } catch (e2) {
+      // Both placements failed — restore the original so dest is never left missing.
+      if (aside && !fs.existsSync(dest)) { try { fs.renameSync(aside, dest); aside = null; } catch (_) { /* ignore */ } }
+      throw e2;
+    }
+  }
+  // Sweep now-unlocked old asides from earlier upgrades.
+  try {
+    const dir = path.dirname(dest);
+    const prefix = path.basename(dest) + '.old-';
+    for (const f of fs.readdirSync(dir)) {
+      if (f.indexOf(prefix) === 0) { try { fs.unlinkSync(path.join(dir, f)); } catch (_) { /* still locked */ } }
+    }
+  } catch (_) { /* ignore */ }
+}
+
+// After the runner binary is replaced, the OLD runner process is still executing old code (it kept
+// the renamed-aside file). Restart it so the new build runs. Best-effort: Windows kill+relaunch;
+// mac/linux reload the launchd/systemd unit. Failure just defers the new runner to next launch.
+function restartRunner(pf, runnerPath) {
+  try {
+    if (pf.os === 'windows') {
+      spawnSync('taskkill', ['/IM', 'Ensemble.Runner.exe', '/F'], { stdio: 'ignore' });
+      startRunner(runnerPath);
+    } else {
+      installAutostart(runnerPath); // unload+load (launchd) / enable --now (systemd) → picks up new binary
+    }
+  } catch (e) { /* best-effort — the new binary is on disk and runs on next launch */ }
+}
+
+// The runner + runtime are copied into ~/.ensemble by `ensemble install` (or on first
+// `ensemble login`/`enroll`). `npm install` alone does NOT populate ~/.ensemble — there is no
+// postinstall; it only places the per-platform binary package under node_modules.
 function runtimeInstalled() {
   const p = runtimePaths();
-  const ok = (f) => fs.existsSync(f) && fs.statSync(f).size > 0;
-  return ok(p.busPath) && ok(p.runnerPath);
+  return isUsableBinary(p.runtimePath) && isUsableBinary(p.runnerPath);
 }
 
 function requireRuntime() {
   if (!runtimeInstalled()) {
-    die('the Ensemble runtime is not installed — run `ensemble install` (or reinstall @webority/ensemble).');
+    die('the Ensemble runtime is not installed — run `ensemble install` to download it.');
   }
   return runtimePaths();
 }
 
-// Ensure the runner + bus are present, downloading them if this is the first run. Called by
+// Ensure the runner + runtime are present, downloading them if this is the first run. Called by
 // `login`/`enroll` AFTER authentication, so the whole thing is: `npm i` then `ensemble login`.
+// Also reinstalls when an existing binary is a tiny stub (broken prior install).
 async function ensureRuntime() {
-  if (runtimeInstalled()) {
-    return runtimePaths();
+  // Fleet auto-upgrade: refresh when a binary is missing/stub OR was installed for an OLDER package
+  // version (an `npm upgrade` bumped us). This makes login/enroll/hooks land a new release — not only
+  // an explicit `ensemble install`, which was the only upgrade path before and left the fleet stale. [BUG-06673]
+  if (runtimeInstalled() && installedVersionCurrent()) {
+    const p = runtimePaths();
+    removeLegacyBusArtifacts();
+    return p;
   }
-  return ensureBinaries();
+  return ensureBinaries({ force: true });
 }
 
 // The per-platform npm optionalDependency (esbuild model): npm installs only the one matching this
@@ -130,36 +227,104 @@ function platformPackageDir() {
   }
 }
 
-// Put the runner + bus in ~/.ensemble (the stable location the daemon, hooks, and autostart use).
+// No backward-compat binary. Delete leftover ensemble-bus* (and framework-dependent debris that
+// sometimes landed next to a bad publish) so only ensemble-runtime remains the bus CLI.
+function removeLegacyBusArtifacts() {
+  ensureDirs();
+  let names;
+  try {
+    names = fs.readdirSync(BIN_DIR);
+  } catch (e) {
+    return;
+  }
+  for (const name of names) {
+    const lower = name.toLowerCase();
+    const drop =
+      lower.startsWith('ensemble-bus')
+      || lower.startsWith('microsoft.')
+      || lower.startsWith('modelcontextprotocol')
+      || lower === 'system.diagnostics.eventlog.dll'
+      || lower === 'runtimes';
+    if (!drop) continue;
+    const full = path.join(BIN_DIR, name);
+    try {
+      if (fs.statSync(full).isDirectory()) {
+        fs.rmSync(full, { recursive: true, force: true });
+      } else {
+        fs.unlinkSync(full);
+      }
+    } catch (e) {
+      // Locked (running MCP still holds a handle): rename aside so nothing can launch it by name.
+      try {
+        const trash = full + '.trash-' + Date.now();
+        fs.renameSync(full, trash);
+        warn('moved locked legacy ' + name + ' aside → ' + path.basename(trash) +
+          ' (delete after restarting agents)');
+      } catch (e2) {
+        warn('could not remove legacy ' + name + ' (locked) — restart agents and re-run `ensemble install`. (' +
+          (e2 && e2.message ? e2.message : e2) + ')');
+      }
+    }
+  }
+}
+
+function shouldRefreshBinary(dest, src, force) {
+  if (force) return true;
+  if (!isUsableBinary(dest)) return true; // missing or stub
+  // If the npm platform package has a different-sized binary, refresh (upgrade path).
+  if (src && isUsableBinary(src) && fs.statSync(src).size !== fs.statSync(dest).size) return true;
+  return false;
+}
+
+// Put the runner + runtime in ~/.ensemble (the stable location the daemon, hooks, and autostart use).
 // Source them from the npm-installed platform package (instant copy, no download); only if that
-// package isn't present do we download from the CDN. So `npm i` delivers the binary and `login`
-// just copies + wires it.
-async function ensureBinaries() {
+// package isn't present do we download from the CDN. `npm i` only places the platform package under
+// node_modules — `ensemble install` (or first `ensemble login`) is what copies them into ~/.ensemble.
+//
+// opts.force: always re-copy/download (used by `ensemble install` so upgrades land).
+async function ensureBinaries(opts) {
+  const force = !!(opts && opts.force);
   ensureDirs();
   const pf = platform();
   assertSupported();
-  const busPath = path.join(BIN_DIR, 'ensemble-bus' + pf.exe);
+  const runtimePath = path.join(BIN_DIR, 'ensemble-runtime' + pf.exe);
   const runnerPath = path.join(RUNNER_DIR, 'Ensemble.Runner' + pf.exe);
   const pkgDir = platformPackageDir();
   const targets = [
-    { src: pkgDir && path.join(pkgDir, 'ensemble-bus' + pf.exe), cdn: 'ensemble-bus-' + pf.key + pf.exe, dest: busPath },
+    { src: pkgDir && path.join(pkgDir, 'ensemble-runtime' + pf.exe), cdn: 'ensemble-runtime-' + pf.key + pf.exe, dest: runtimePath },
     { src: pkgDir && path.join(pkgDir, 'Ensemble.Runner' + pf.exe), cdn: 'ensemble-runner-' + pf.key + pf.exe, dest: runnerPath },
   ];
+  let runnerRefreshed = false;
   for (const t of targets) {
-    if (fs.existsSync(t.dest) && fs.statSync(t.dest).size > 0) continue;
-    if (t.src && fs.existsSync(t.src) && fs.statSync(t.src).size > 0) {
-      fs.copyFileSync(t.src, t.dest); // from the npm platform package — no download
+    if (!shouldRefreshBinary(t.dest, t.src, force)) continue;
+    // Write to a temp then atomically place onto dest — placeBinary tolerates a Windows lock on the
+    // running runner (rename-aside), so an upgrade never fails just because the daemon is up.
+    const tmp = t.dest + '.new';
+    if (t.src && isUsableBinary(t.src)) {
+      log('  installing ' + path.basename(t.dest) + ' from npm package …');
+      fs.copyFileSync(t.src, tmp);
     } else {
       log('  downloading ' + t.cdn + ' …');
-      await downloadTo(DL_BASE + '/' + t.cdn, t.dest);
+      await downloadTo(DL_BASE + '/' + t.cdn, tmp);
+    }
+    if (!isUsableBinary(tmp)) {
+      try { fs.unlinkSync(tmp); } catch (_) { /* ignore */ }
+      throw new Error('installed binary looks corrupt or too small: ' + t.dest +
+        ' (expected ≥ ' + MIN_BINARY_BYTES + ' bytes). Check CDN / platform package.');
     }
+    placeBinary(tmp, t.dest);
+    if (t.dest === runnerPath) runnerRefreshed = true;
     if (pf.os !== 'windows') {
       fs.chmodSync(t.dest, 0o755);
       // macOS requires at least an ad-hoc signature to run an unsigned binary.
       if (pf.os === 'mac') spawnSync('codesign', ['-s', '-', '-f', t.dest], { stdio: 'ignore' });
     }
   }
-  return { busPath, runnerPath, pf };
+  removeLegacyBusArtifacts();
+  writeInstalledVersion();
+  // A replaced runner binary only takes effect once the daemon restarts onto it.
+  if (runnerRefreshed) restartRunner(pf, runnerPath);
+  return { runtimePath, runnerPath, pf };
 }
 
 // --- enrollment: exchange the enrollment token for a per-machine runner token ---
@@ -182,7 +347,7 @@ function writeRunnerConfig(api, machineToken) {
     Ensemble: { HubUrl: hubUrl, MachineToken: machineToken },
   };
   fs.writeFileSync(path.join(RUNNER_DIR, 'appsettings.json'), JSON.stringify(cfg, null, 2));
-  // ensemble-bus reads ENSEMBLE_MACHINE_TOKEN from env — persist it to the shell rc + a dotfile.
+  // ensemble-runtime reads ENSEMBLE_MACHINE_TOKEN from env — persist it to the shell rc + a dotfile.
   fs.writeFileSync(path.join(ENSEMBLE_DIR, 'machine-token'), machineToken, { mode: 0o600 });
   const pf = platform();
   if (pf.os === 'windows') {
@@ -199,25 +364,322 @@ function writeRunnerConfig(api, machineToken) {
   } catch (e) { /* best-effort */ }
 }
 
-// --- wire ensemble-bus into each installed harness's session hooks ---
+// --- wire ensemble-runtime into each installed harness (hooks + MCP) ---
+// Fleet engines: Claude, Codex, Grok, OpenCode, OMP (oh-my-pi), Gemini, Antigravity (when present).
+// Hooks = mail at turn boundaries. MCP = who/send/read/reply tools every turn.
+
+const ENGINE_CMDS = {
+  claude: ['claude'],
+  codex: ['codex'],
+  grok: ['grok'],
+  opencode: ['opencode'],
+  omp: ['omp', 'oh-my-pi', 'pi'],
+  gemini: ['gemini'],
+  antigravity: ['antigravity'],
+};
+
 function wireHooks() {
   const pf = platform();
-  const busExe = path.join(BIN_DIR, 'ensemble-bus' + pf.exe);
-  const busInvoke = pf.os === 'windows' ? busExe.replace(/\\/g, '\\\\') : busExe;
-  const wired = [];
-
-  // Claude Code — settings.json hooks
-  const claudeSettings = path.join(HOME, '.claude', 'settings.json');
-  if (has('claude')) { mergeClaudeHooks(claudeSettings, busInvoke); wired.push('claude'); }
-
-  // Codex — ~/.codex/hooks.json
-  if (has('codex')) { writeEngineHooks(path.join(HOME, '.codex', 'hooks.json'), busInvoke, 'codex'); wired.push('codex'); }
-  // Grok — ~/.grok/hooks/agent-bus.json
-  if (has('grok')) { writeEngineHooks(path.join(HOME, '.grok', 'hooks', 'agent-bus.json'), busInvoke, 'grok'); wired.push('grok'); }
-  // Gemini / OpenCode — best-effort (same hook shape if the engine supports lifecycle hooks)
-  if (has('gemini')) wired.push('gemini(detected)');
-  if (has('opencode')) wired.push('opencode(detected)');
-  return wired;
+  const runtimeExe = path.join(BIN_DIR, 'ensemble-runtime' + pf.exe);
+  // Never wire hooks/MCP to a runtime binary that isn't present — that silently points every engine
+  // at a dead path (hook + MCP death). Callers (`login`/`enroll`) run ensureRuntime first, and the
+  // `hooks` command does too; this guard fails closed if the binary is somehow still missing.
+  if (!isUsableBinary(runtimeExe)) {
+    throw new Error('the Ensemble runtime binary is missing or a stub at ' + runtimeExe +
+      ' — run `ensemble install` to download it before wiring hooks.');
+  }
+  const runtimeInvoke = pf.os === 'windows' ? runtimeExe.replace(/\\/g, '\\\\') : runtimeExe;
+  const runtimeCmd = runtimeExe.replace(/\\/g, '/');
+  const report = [];
+
+  // --- hooks ---
+  // Report a head only when the write actually succeeded; a skipped (malformed-JSON) write returns
+  // false and must NOT be reported as wired.
+  if (enginePresent('claude')) {
+    if (mergeClaudeHooks(path.join(HOME, '.claude', 'settings.json'), runtimeInvoke)) report.push('claude:hooks');
+  }
+  if (enginePresent('codex')) {
+    if (writeEngineHooks(path.join(HOME, '.codex', 'hooks.json'), runtimeInvoke, 'codex')) report.push('codex:hooks');
+  }
+  if (enginePresent('grok')) {
+    if (writeEngineHooks(path.join(HOME, '.grok', 'hooks', 'agent-bus.json'), runtimeInvoke, 'grok')) report.push('grok:hooks');
+  }
+  // OpenCode: no stable global lifecycle-hooks file yet — MCP is the primary path.
+  if (enginePresent('opencode')) report.push('opencode:hooks?');
+  // OMP (oh-my-pi): NO JSON lifecycle-hooks mechanism — hooks are a JS/TS extension API (pi.on(...)),
+  // so a hooks.json is inert (consumed by nothing). MCP (below) is omp's integration path.
+  if (enginePresent('omp')) report.push('omp:hooks?');
+  if (enginePresent('gemini')) {
+    // Gemini CLI hook surface varies; still register MCP below.
+    report.push('gemini:hooks?');
+  }
+  // Antigravity uses a DIFFERENT hooks schema (a named-hook wrapper at ~/.gemini/config/hooks.json,
+  // where only a Stop-family event maps) — the old ~/.antigravity/hooks.json we wrote is never read.
+  // Left to MCP (below) until a native Antigravity hook writer lands.
+  if (enginePresent('antigravity')) report.push('antigravity:hooks?');
+
+  // --- MCP ---
+  if (enginePresent('claude')) {
+    if (upsertClaudeMcp(runtimeCmd, 'claude')) report.push('claude:mcp');
+  }
+  if (enginePresent('codex')) {
+    if (upsertTomlMcp(path.join(HOME, '.codex', 'config.toml'), 'ensemble', runtimeCmd, ['mcp', '--engine', 'codex'])) {
+      report.push('codex:mcp');
+    }
+  }
+  if (enginePresent('grok')) {
+    if (upsertTomlMcp(path.join(HOME, '.grok', 'config.toml'), 'ensemble', runtimeCmd, ['mcp', '--engine', 'grok'])) {
+      report.push('grok:mcp');
+    }
+  }
+  if (enginePresent('opencode')) {
+    if (upsertOpenCodeMcp(runtimeCmd)) report.push('opencode:mcp');
+  }
+  if (enginePresent('omp')) {
+    if (upsertOmpMcp(runtimeCmd)) report.push('omp:mcp');
+  }
+  if (enginePresent('gemini')) {
+    if (upsertJsonMcp(path.join(HOME, '.gemini', 'settings.json'), 'ensemble', runtimeCmd, ['mcp', '--engine', 'gemini'])) {
+      report.push('gemini:mcp');
+    }
+  }
+  if (enginePresent('antigravity')) {
+    // Prefer Claude-shaped global json if Antigravity is a Claude-family fork; also write local mcp.json.
+    if (upsertJsonMcp(path.join(HOME, '.antigravity', 'mcp.json'), 'ensemble', runtimeCmd, ['mcp', '--engine', 'antigravity'])) {
+      report.push('antigravity:mcp');
+    }
+  }
+
+  return report;
+}
+
+// A genuine-install marker per engine — deliberately NOT a bare engine dir (the wiring itself
+// creates `~/.gemini`, `~/.codex`, etc., and an empty staging dir would then count), and
+// deliberately NOT a file Ensemble authors (settings.json / hooks.json / config.toml / mcp.json),
+// so a prior `ensemble hooks` run can't make an uninstalled engine look present. PATH detection
+// stays the primary, strongest signal; these are the fallback for when the CLI isn't on PATH.
+function engineMarkers(engine) {
+  switch (engine) {
+    case 'claude': return [path.join(HOME, '.claude.json'), path.join(HOME, '.claude', 'projects')];
+    case 'codex': return [path.join(HOME, '.codex', 'auth.json'), path.join(HOME, '.codex', 'config.toml')];
+    case 'grok': return [path.join(HOME, '.grok', 'auth.json'), path.join(HOME, '.grok', 'config.toml')];
+    case 'opencode': return [path.join(HOME, '.config', 'opencode', 'opencode.json'), path.join(HOME, '.local', 'share', 'opencode'), path.join(HOME, '.opencode')];
+    case 'omp': return [path.join(HOME, '.omp', 'auth.json'), path.join(HOME, '.omp', 'config.json')];
+    case 'gemini': return [path.join(HOME, '.gemini', 'oauth_creds.json'), path.join(HOME, '.gemini', 'google_accounts.json'), path.join(HOME, '.gemini', 'installation_id')];
+    case 'antigravity': return [path.join(process.env.LOCALAPPDATA || '', 'Antigravity'), path.join(process.env.LOCALAPPDATA || '', 'antigravity'), path.join(HOME, '.antigravity', 'config.json')];
+    default: return [];
+  }
+}
+
+/** Detect an engine by a resolvable binary on PATH, else a genuine-install marker file. */
+function enginePresent(engine) {
+  const cmds = ENGINE_CMDS[engine] || [engine];
+  for (const c of cmds) {
+    if (has(c)) return true;
+  }
+  for (const m of engineMarkers(engine)) {
+    if (m && fs.existsSync(m)) return true;
+  }
+  return false;
+}
+
+function wireMcpServers(runtimeExe) {
+  // Back-compat alias — full wiring is wireHooks().
+  return wireHooks().filter((x) => x.endsWith(':mcp')).map((x) => x.replace(/:mcp$/, ''));
+}
+
+// A config file exists but is not valid JSON. Fail CLOSED: never overwrite it — resetting to {} and
+// writing would destroy the user's real config — just warn and skip wiring this engine. Returns
+// false so callers propagate "not wired".
+function skipMalformedJson(file, label, err) {
+  warn('ensemble: ' + label + ' at ' + file + ' is not valid JSON (' +
+    (err && err.message ? err.message : String(err)) +
+    ') — leaving it untouched and skipping. Fix or remove the file, then run `ensemble hooks`.');
+  return false;
+}
+
+function upsertClaudeMcp(runtimeCmd, engine) {
+  // Claude Code global MCP registry lives in ~/.claude.json → mcpServers
+  const file = path.join(HOME, '.claude.json');
+  let j = {};
+  if (fs.existsSync(file)) {
+    try {
+      j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (e) {
+      return skipMalformedJson(file, 'Claude MCP config (~/.claude.json)', e);
+    }
+  }
+  if (!j || typeof j !== 'object') j = {};
+  j.mcpServers = j.mcpServers || {};
+  delete j.mcpServers['ensemble-bus'];
+  j.mcpServers['ensemble'] = {
+    type: 'stdio',
+    command: runtimeCmd,
+    args: ['mcp', '--engine', engine],
+  };
+  try {
+    fs.writeFileSync(file, JSON.stringify(j, null, 2) + '\n');
+    return true;
+  } catch (e) {
+    warn('could not write Claude MCP config: ' + (e.message || e));
+    return false;
+  }
+}
+
+/// OpenCode: mcp.<name> = { type: "local", command: [...], enabled: true } in opencode.json
+function upsertOpenCodeMcp(runtimeCmd) {
+  try {
+    const dir = path.join(HOME, '.config', 'opencode');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, 'opencode.json');
+    let j = {};
+    if (fs.existsSync(file)) {
+      try { j = JSON.parse(fs.readFileSync(file, 'utf8')); }
+      catch (e) { return skipMalformedJson(file, 'OpenCode config (opencode.json)', e); }
+    }
+    if (!j || typeof j !== 'object') j = {};
+    j.mcp = j.mcp || {};
+    j.mcp.ensemble = {
+      type: 'local',
+      command: [runtimeCmd, 'mcp', '--engine', 'opencode'],
+      enabled: true,
+    };
+    // OpenCode rejects a stray top-level `mcpServers` key ("Unrecognized key: mcpServers") so the
+    // whole config fails to load. Older ensemble wiring left one (usually empty {}). Migrate ALL
+    // supported transports/fields into the accepted `mcp` shape — local (command → command,
+    // env → environment) AND remote (url/type:remote → url, headers) — never silently drop a user's
+    // servers. OpenCode's `mcp` schema has no place for cwd/timeout (or an unrecognized transport):
+    // rather than dropping those fields, back the file up and fail with guidance so nothing is lost.
+    if (j.mcpServers && typeof j.mcpServers === 'object') {
+      const migrated = {};
+      const unconvertible = [];
+      for (const [name, s] of Object.entries(j.mcpServers)) {
+        if (name === 'ensemble' || j.mcp[name]) continue;
+        if (!s || typeof s !== 'object') { unconvertible.push(name); continue; }
+        // OpenCode's mcp entries can't represent cwd/timeout — refuse rather than drop them.
+        if (s.cwd != null || s.timeout != null) { unconvertible.push(name); continue; }
+        const isRemote = !!s.url && !s.command;
+        if (isRemote) {
+          const entry = { type: 'remote', url: s.url, enabled: s.enabled !== false };
+          if (s.headers && typeof s.headers === 'object') entry.headers = s.headers;
+          migrated[name] = entry;
+        } else if (s.command) {
+          const cmd = Array.isArray(s.command) ? s.command.slice() : [s.command, ...(s.args || [])];
+          const entry = { type: 'local', command: cmd, enabled: s.enabled !== false };
+          const env = s.environment || s.env;
+          if (env && typeof env === 'object') entry.environment = env;
+          migrated[name] = entry;
+        } else {
+          unconvertible.push(name); // neither command nor url — unknown transport
+        }
+      }
+      if (unconvertible.length) {
+        const bak = file + '.bak';
+        try { fs.copyFileSync(file, bak); } catch (e) { /* best-effort backup */ }
+        warn('ensemble: OpenCode config ' + file + ' has mcpServers entries that cannot be safely ' +
+          'migrated to the `mcp` shape (' + unconvertible.join(', ') + ') — they use cwd/timeout or ' +
+          'an unrecognized transport OpenCode\'s schema does not support. Backed up to ' + bak +
+          ' and left the original untouched. Migrate those servers into `mcp` by hand, then run ' +
+          '`ensemble hooks`.');
+        return false;
+      }
+      Object.assign(j.mcp, migrated);
+      delete j.mcpServers;
+    }
+    fs.writeFileSync(file, JSON.stringify(j, null, 2) + '\n');
+    return true;
+  } catch (e) {
+    warn('could not write OpenCode MCP config: ' + (e.message || e));
+    return false;
+  }
+}
+
+/// OMP (oh-my-pi): ~/.omp/agent/mcp.json → mcpServers
+function upsertOmpMcp(runtimeCmd) {
+  const file = path.join(HOME, '.omp', 'agent', 'mcp.json');
+  return upsertJsonMcp(file, 'ensemble', runtimeCmd, ['mcp', '--engine', 'omp'], {
+    $schema: 'https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json',
+    type: 'stdio',
+  });
+}
+
+/// Upsert [mcp_servers.<name>] in a TOML config (Codex / Grok). No TOML library — line surgery only.
+/// Idempotent against an already-populated config: other tables (e.g. weborityos, [ui], [cli]) stay.
+function upsertTomlMcp(filePath, serverName, command, argsArr) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    let text = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    const header = '[mcp_servers.' + serverName + ']';
+    // Drop our server table AND any of its CHILD tables ([mcp_servers.ensemble.env],
+    // [mcp_servers.ensemble.tools.x], the ensemble-bus variants) so a re-run replaces our entry
+    // cleanly and never leaves an orphaned sub-table that redefines the parent later (invalid TOML).
+    const esc = serverName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const ownTable = (h) =>
+      new RegExp('^\\[mcp_servers\\.(' + esc + '|ensemble-bus)(\\.|\\])').test(h) ||
+      new RegExp('^\\[mcp_servers\\."(' + esc + '|ensemble-bus)"(\\.|\\])').test(h);
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    let skipping = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (/^\[mcp_servers\./.test(trimmed)) {
+        skipping = ownTable(trimmed); // our table or a child of it — drop; other servers stay
+        if (skipping) continue;
+      } else if (skipping && /^\[/.test(trimmed)) {
+        skipping = false; // a different table begins — keep this line
+      }
+      if (!skipping) out.push(line);
+    }
+    while (out.length && out[out.length - 1].trim() === '') out.pop();
+    const argsToml = argsArr.map((a) => '"' + String(a).replace(/\\/g, '/') + '"').join(', ');
+    const cmd = command.replace(/\\/g, '/');
+    out.push('');
+    out.push(header);
+    out.push('command = "' + cmd + '"');
+    out.push('args = [' + argsToml + ']');
+    out.push('enabled = true');
+    out.push('');
+    fs.writeFileSync(filePath, out.join('\n'));
+    // Verify the write stuck (catches partial writes / ACL issues).
+    const written = fs.readFileSync(filePath, 'utf8');
+    if (!written.includes(header) || !written.includes(cmd)) {
+      warn('TOML MCP write verification failed for ' + filePath);
+      return false;
+    }
+    return true;
+  } catch (e) {
+    warn('could not write TOML MCP config ' + filePath + ': ' + (e.message || e));
+    return false;
+  }
+}
+
+/// Upsert mcpServers.<name> in a JSON settings file (Gemini / OMP / Antigravity).
+function upsertJsonMcp(filePath, serverName, command, argsArr, extras) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    let j = {};
+    if (fs.existsSync(filePath)) {
+      try { j = JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+      catch (e) { return skipMalformedJson(filePath, 'MCP config', e); }
+    }
+    if (!j || typeof j !== 'object') j = {};
+    if (extras && extras.$schema && !j.$schema) j.$schema = extras.$schema;
+    // Support mcp.servers, mcpServers map
+    if (j.mcp && typeof j.mcp === 'object' && !Array.isArray(j.mcp) && j.mcp.servers) {
+      j.mcp.servers[serverName] = { command, args: argsArr, type: (extras && extras.type) || 'stdio' };
+    } else {
+      j.mcpServers = j.mcpServers || {};
+      delete j.mcpServers['ensemble-bus'];
+      const entry = { command, args: argsArr };
+      if (extras && extras.type) entry.type = extras.type;
+      j.mcpServers[serverName] = entry;
+    }
+    fs.writeFileSync(filePath, JSON.stringify(j, null, 2) + '\n');
+    return true;
+  } catch (e) {
+    warn('could not write JSON MCP config ' + filePath + ': ' + (e.message || e));
+    return false;
+  }
 }
 
 function has(cmd) {
@@ -226,38 +688,85 @@ function has(cmd) {
   return which.status === 0;
 }
 
-function writeEngineHooks(file, busInvoke, engine) {
+// True if a hook handler entry (string command, or an object carrying a command field) is one
+// Ensemble owns — used to dedup on re-run so our entry never stacks.
+function isEnsembleHook(h) {
+  const cmd = typeof h === 'string' ? h : (h && (h.command || h.cmd || h.run)) || '';
+  // Match ensemble-runtime and any leftover ensemble-bus paths so re-wire strips outdated entries.
+  return /ensemble-(bus|runtime)/i.test(String(cmd));
+}
+
+// Codex + Grok use the SAME hooks schema as Claude Code: PascalCase event names, each mapping to an
+// array of matcher-groups { matcher?, hooks: [{ type: "command", command }] }. (Verified against
+// Codex's config-advanced docs and Grok's bundled ~/.grok/docs hooks guide.) The old FLAT
+// lowercase-scalar form we wrote ({ "session-start": "<cmd>" }) is silently ignored by both engines,
+// so their SessionStart/Stop/SessionEnd hooks never fired (auto-register / idle-wake / detach dead;
+// only MCP worked). MERGE-preserving: keep other events + the user's own groups on our events, dedup
+// our entry so re-runs don't stack, and migrate away the legacy lowercase keys. [BUG-06673-hooks]
+// Returns true when written, false when skipped (malformed JSON left untouched).
+function writeEngineHooks(file, runtimeInvoke, engine) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  const hook = (ev) => `"${busInvoke}" hook ${ev} --engine ${engine}`;
-  const cfg = {
-    hooks: {
-      'session-start': hook('session-start'),
-      'user-prompt': hook('user-prompt'),
-      'stop': hook('stop'),
-      'session-end': hook('session-end'),
-    },
-  };
-  fs.writeFileSync(file, JSON.stringify(cfg, null, 2));
+  let existing = {};
+  if (fs.existsSync(file)) {
+    try { existing = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch (e) { return skipMalformedJson(file, engine + ' hooks config', e); }
+  }
+  if (!existing || typeof existing !== 'object') existing = {};
+  const hooks = (existing.hooks && typeof existing.hooks === 'object' && !Array.isArray(existing.hooks))
+    ? existing.hooks : {};
+  // Remove the legacy flat lowercase keys we used to write (both engines ignore them). Preserve any
+  // non-Ensemble handler a user happened to place on a lowercase key; drop only ours.
+  for (const legacy of ['session-start', 'user-prompt', 'stop', 'session-end']) {
+    const v = hooks[legacy];
+    if (typeof v === 'string' && isEnsembleHook(v)) delete hooks[legacy];
+    else if (Array.isArray(v)) {
+      const rest = v.filter((h) => !isEnsembleHook(h));
+      if (rest.length === 0) delete hooks[legacy]; else hooks[legacy] = rest;
+    }
+  }
+  // JSON key = the PascalCase event the engine matches on; the command's `hook <ev>` arg stays
+  // lowercase — that's what our runtime's hook dispatcher parses. No bash suffix: Codex/Grok run the
+  // command directly and the hook handler is already silent-safe on failure.
+  const events = { SessionStart: 'session-start', UserPromptSubmit: 'user-prompt', Stop: 'stop', SessionEnd: 'session-end' };
+  for (const [evt, ev] of Object.entries(events)) {
+    const command = `"${runtimeInvoke}" hook ${ev} --engine ${engine}`;
+    const groups = Array.isArray(hooks[evt]) ? hooks[evt] : (hooks[evt] == null ? [] : [hooks[evt]]);
+    const kept = groups
+      .filter((g) => g && typeof g === 'object' && !Array.isArray(g))
+      .map((g) => ({ ...g, hooks: (Array.isArray(g.hooks) ? g.hooks : []).filter((h) => !isEnsembleHook(h)) }))
+      .filter((g) => (g.hooks || []).length > 0 || g.matcher);
+    kept.push({ hooks: [{ type: 'command', command }] });
+    hooks[evt] = kept;
+  }
+  existing.hooks = hooks;
+  fs.writeFileSync(file, JSON.stringify(existing, null, 2) + '\n');
+  return true;
 }
 
-function mergeClaudeHooks(file, busInvoke) {
+// Returns true when the settings were written, false when skipped (malformed JSON left untouched).
+function mergeClaudeHooks(file, runtimeInvoke) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   let s = {};
-  try { if (fs.existsSync(file)) s = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { s = {}; }
+  if (fs.existsSync(file)) {
+    try { s = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch (e) { return skipMalformedJson(file, 'Claude settings (~/.claude/settings.json)', e); }
+  }
+  if (!s || typeof s !== 'object') s = {};
   s.hooks = s.hooks || {};
   // APPEND our bus hook, never replace — preserve the user's other hooks (config sync, etc.).
-  // Re-enroll is idempotent: strip any prior ensemble-bus hook first, then add the current one.
+  // Re-enroll is idempotent: strip any prior ensemble-bus/ensemble-runtime hook first, then add the current one.
   const events = { SessionStart: 'session-start', UserPromptSubmit: 'user-prompt', Stop: 'stop', SessionEnd: 'session-end' };
   for (const [evt, ev] of Object.entries(events)) {
-    const command = `"${busInvoke}" hook ${ev} --engine claude 2>/dev/null || true`;
+    const command = `"${runtimeInvoke}" hook ${ev} --engine claude 2>/dev/null || true`;
     const groups = Array.isArray(s.hooks[evt]) ? s.hooks[evt] : [];
     const kept = groups
-      .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !/ensemble-bus/i.test(h.command || '')) }))
+      .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !isEnsembleHook(h)) }))
       .filter((g) => (g.hooks || []).length > 0);
     kept.push({ hooks: [{ type: 'command', command }] });
     s.hooks[evt] = kept;
   }
-  fs.writeFileSync(file, JSON.stringify(s, null, 2));
+  fs.writeFileSync(file, JSON.stringify(s, null, 2) + '\n');
+  return true;
 }
 
 // --- per-user auto-start of the runner (per OS), plus start it now ---
@@ -351,7 +860,9 @@ function finishSetup(api, machineToken, runnerPath) {
 
 module.exports = {
   log, warn, die, platform, DEFAULT_API, ENSEMBLE_DIR, RUNNER_DIR, BIN_DIR,
-  ensureBinaries, enrollMachine, writeRunnerConfig, wireHooks, installAutostart, startRunner, request,
+  ensureBinaries, enrollMachine, writeRunnerConfig, wireHooks, wireMcpServers, enginePresent, installAutostart, startRunner, request,
   sleep, openBrowser, startDevice, pollDevice, finishSetup, assertSupported,
-  runtimePaths, runtimeInstalled, requireRuntime, ensureRuntime,
+  runtimePaths, runtimeBin, runtimeInstalled, requireRuntime, ensureRuntime,
+  isUsableBinary, removeLegacyBusArtifacts, MIN_BINARY_BYTES,
+  writeEngineHooks, upsertTomlMcp, installedVersionCurrent, readInstalledVersion, PKG_VERSION,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@webority/ensemble",
-  "version": "0.5.5",
-  "description": "Connect this machine to Ensemble — runs the local agent runner and wires the ensemble-bus session bus so your coding sessions talk (per-org, isolated).",
+  "version": "0.5.8",
+  "description": "Connect this machine to Ensemble — runs the local agent runner and wires the ensemble session bus so your coding sessions talk (per-org, isolated).",
   "bin": {
     "ensemble": "bin/ensemble.js"
   },
@@ -9,11 +9,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@webority/ensemble-darwin-arm64": "0.5.5",
-    "@webority/ensemble-darwin-x64": "0.5.5",
-    "@webority/ensemble-linux-arm64": "0.5.5",
-    "@webority/ensemble-linux-x64": "0.5.5",
-    "@webority/ensemble-win-x64": "0.5.5"
+    "@webority/ensemble-darwin-arm64": "0.5.8",
+    "@webority/ensemble-darwin-x64": "0.5.8",
+    "@webority/ensemble-linux-arm64": "0.5.8",
+    "@webority/ensemble-linux-x64": "0.5.8",
+    "@webority/ensemble-win-x64": "0.5.8"
   },
   "files": [
     "bin",