@ours.network/install 0.18.0-nightly.4 → 0.18.0-nightly.6

package/lib/orchestrate.mjs

@@ -23,7 +23,7 @@
 //   ask(prompt, default)   -> boolean       (never called when assumeYes)
 //   now()                  -> number
 
-import { join } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { parseInstallArgs, resolveTarget, InstallUsageError } from './target.mjs';
 import { planDaemonConfig, planServiceInstall, serviceInstallCommand } from './plan.mjs';
 import {
@@ -37,12 +37,31 @@ import { configJournal, reportRollback } from './journal.mjs';
 import { detectDaemons, planDaemonSelection, resolveSelection } from './detect.mjs';
 import { detectPlatform, resolveChannel } from './logic.mjs';
 import { daemonEnv } from './effects.mjs';
+import {
+  buildClaudeMarketplace, buildCodexMarketplace, marketplaceJson, marketplacePaths,
+  validateChannelVersion,
+} from './marketplace.mjs';
 import { USAGE } from './usage.mjs';
 import { ok, info, warn, heading, banner, box, c, progress } from './ui.mjs';
 
 export const EXIT_OK = 0;
 export const EXIT_REFUSED = 2;
 
+export async function resolveExactSuite(args, effects) {
+  const packages = {};
+  for (const key of ['mcp', 'claude-code', 'codex']) {
+    const version = await effects.resolvePackageVersion(`@ours.network/${key}`, args.channel);
+    const checked = validateChannelVersion(version, args.channel);
+    if (!checked.ok) return { ok: false, reason: `${key}: ${checked.reason}` };
+    packages[key] = checked.version;
+  }
+  const versions = new Set(Object.values(packages));
+  if (versions.size !== 1) {
+    return { ok: false, reason: `the ${args.channel} dist-tags are not lockstep (${Object.entries(packages).map(([k, v]) => `${k}=${v}`).join(', ')})` };
+  }
+  return { ok: true, channel: args.channel, version: versions.values().next().value, packages };
+}
+
 /**
  * A dry run prints what it WOULD do and performs no mutation. The prefix is the
  * existing installer's, kept so the two flows read the same.
@@ -66,6 +85,104 @@ async function perform(effects, dryRun, label, thunk) {
 
 const reason = (error) => (error instanceof Error ? error.message : String(error));
 
+function semverMajor(version) {
+  const match = /^(?:[~^<>= ]*)(\d+)\./.exec(String(version ?? '').trim());
+  return match ? Number(match[1]) : null;
+}
+
+function incompatibleUpgrade(target, cliDependencies) {
+  if (target.action !== 'update' || !target.daemonVersion) return null;
+  const runningMajor = semverMajor(target.daemonVersion);
+  const targetRange = cliDependencies?.['@ours.network/sdk'];
+  const targetMajor = semverMajor(targetRange);
+  if (runningMajor === null) {
+    return { unknown: true, runningMajor: null, runningVersion: target.daemonVersion };
+  }
+  if (targetMajor === null) {
+    return { unknown: true, runningMajor, runningVersion: target.daemonVersion };
+  }
+  return runningMajor !== targetMajor
+    ? { unknown: false, runningMajor, runningVersion: target.daemonVersion, targetMajor, targetRange }
+    : null;
+}
+
+async function prepareIncompatibleUpgrade(args, effects, target, cliPkg, mismatch) {
+  const dir = target.stateDir;
+  const configPath = join(dir, 'config.json');
+  if (mismatch.unknown) {
+    effects.out(warn(`ours: cannot verify whether ${cliPkg} can restore daemon v${mismatch.runningVersion}. Nothing was changed.`));
+    effects.out(info('Check npm registry access and re-run; compatibility checks fail closed.'));
+    return { refused: { reason: 'compatibility-unknown', exitCode: EXIT_REFUSED } };
+  }
+
+  effects.out(warn(
+    `ours: daemon v${mismatch.runningVersion} cannot be restored by the requested major v${mismatch.targetMajor}; major upgrades are intentionally incompatible.`,
+  ));
+  if (resolve(dir) === resolve(effects.home) || dirname(resolve(dir)) === resolve(dir)) {
+    effects.out(info(`Automatic purge is not available for the broad state path ${dir}. Back it up and remove it manually.`));
+    return { refused: { reason: 'incompatible-major-broad-path', exitCode: EXIT_REFUSED } };
+  }
+  // Backups live one directory below a non-daemon container. Putting a copied
+  // state beside ~/.ours under another `.ours*` name makes daemon discovery see
+  // the backup as a second live target on the next installer run.
+  const backupPath = join(
+    dirname(dir),
+    '.ours-backups',
+    `${basename(dir)}-before-v${mismatch.targetMajor}-${effects.now()}`,
+  );
+  if (args.dryRun) {
+    effects.out(info(`[dry-run] would ask to stop the old daemon, copy its complete state to ${backupPath}, remove its service/state, and initialize v${mismatch.targetMajor}.`));
+    return { refused: { reason: 'incompatible-major-dry-run', exitCode: EXIT_REFUSED } };
+  }
+  if (args.assumeYes) {
+    effects.out(info('This purge is never accepted through OURS_ASSUME_YES. Re-run interactively to confirm the backup and reset.'));
+    return { refused: { reason: 'incompatible-major-unattended', exitCode: EXIT_REFUSED } };
+  }
+  if (effects.readJson(join(dir, 'ours-cli-daemon.json')) === null) {
+    effects.out(info('The daemon is not CLI-managed. Stop its external launcher, back up and remove its state/service, then re-run the installer.'));
+    return { refused: { reason: 'incompatible-major-external', exitCode: EXIT_REFUSED } };
+  }
+  const confirmed = await effects.ask(
+    `Back up all daemon state to ${backupPath}, purge the incompatible daemon and service, and install v${mismatch.targetMajor}?`,
+    false,
+  );
+  if (!confirmed) {
+    effects.out(info(`Nothing was changed. Back up ${dir}, remove the old daemon service/state, and re-run when ready.`));
+    return { refused: { reason: 'incompatible-major-declined', exitCode: EXIT_REFUSED } };
+  }
+
+  await perform(effects, false, 'stop the incompatible daemon', () => effects.run(
+    'ours', ['daemon', 'stop', '--state-dir', dir, '--config', configPath], { stream: true },
+  ));
+  try {
+    await perform(effects, false, `back up complete daemon state to ${backupPath}`, () => effects.copyDir(dir, backupPath));
+  } catch (error) {
+    try {
+      await effects.run('ours', ['daemon', 'start', '--state-dir', dir, '--config', configPath], { stream: true });
+      effects.out(ok('backup failed, but the old daemon was started again'));
+    } catch {
+      effects.out(warn(`backup failed and the old daemon did not restart; its state is still untouched at ${dir}`));
+    }
+    throw error;
+  }
+  try {
+    await perform(effects, false, 'remove the incompatible daemon boot service', () => effects.run(
+      'ours', ['daemon', 'uninstall-service', '--yes', '--state-dir', dir, '--config', configPath], { stream: true },
+    ));
+  } catch (error) {
+    try {
+      await effects.run('ours', ['daemon', 'start', '--state-dir', dir, '--config', configPath], { stream: true });
+      effects.out(ok(`service removal failed, but the old daemon was started again; backup retained at ${backupPath}`));
+    } catch {
+      effects.out(warn(`service removal failed and the old daemon did not restart; state remains at ${dir} and the backup is at ${backupPath}`));
+    }
+    throw error;
+  }
+  await perform(effects, false, `remove incompatible state at ${dir}`, () => effects.removeDir(dir));
+  effects.out(ok(`backup retained at ${backupPath}`));
+  return { purged: true, backupPath };
+}
+
 /**
  * A step that is allowed to fail without ending the run.
  *
@@ -102,7 +219,7 @@ function pairFor(plan, target) {
 /**
  * Which daemon is this run for?
  *
- * Never asks for a PATH — spec §2 stands — but when several daemons are DETECTED
+ * Never asks for a path, but when several daemons are detected
  * it shows them and lets the operator pick, because choosing from what was found
  * is not prompting for a state directory.
  *
@@ -144,7 +261,7 @@ export async function runSelectionPhase(args, effects) {
   const chosen = resolveSelection(answer, plan);
   if (chosen.action === 'invalid') {
     // Refused rather than guessed. Interpreting an unrecognised answer as a path
-    // would be the "type a state directory" prompt spec §2 forbids, arriving
+    // would reintroduce the forbidden "type a state directory" prompt through the
     // through the back door.
     effects.out(warn(`ours: ${chosen.reason}. Nothing was changed.`));
     effects.out(info('Re-run and pick one of the numbers, or name a daemon directly with --state-dir.'));
@@ -158,10 +275,10 @@ export async function runSelectionPhase(args, effects) {
 }
 
 /**
- * The daemon half of a run: §§2-4. Returns the target decision plus the step
+ * Run the daemon half of an installation and return the target decision plus step
  * outcomes, or a refusal.
  */
-export async function runDaemonPhase(args, effects) {
+export async function runDaemonPhase(args, effects, exactSuite = null) {
   const target = await resolveTarget({
     stateDir: args.stateDir,
     port: args.port,
@@ -184,7 +301,7 @@ export async function runDaemonPhase(args, effects) {
   }
 
   const dir = target.stateDir;
-  const creating = target.action === 'create';
+  let creating = target.action === 'create';
   effects.out(heading(creating ? `target ${dir} — creating a daemon here` : `target ${dir} — daemon found on port ${target.port}`));
   if (target.stalePidRecord) {
     effects.out(info(`a PID record names port ${target.stalePidRecord} but nothing answers there; treating it as stale`));
@@ -203,8 +320,8 @@ export async function runDaemonPhase(args, effects) {
   // daemon's broker is its own record, and re-asking would invite an operator to
   // change it from a screen that is not about changing it. The broker question
   // stays in v3: it is orthogonal to --state-dir/--port, so it
-  // does not violate spec §2's "nothing about a state directory or a port
-  // appears in any prompt".
+  // does not violate the rule that state-directory and port values never appear
+  // in prompts.
   if (creating) args.brokerUrl = await askBroker(args, effects);
 
   const steps = [];
@@ -212,10 +329,26 @@ export async function runDaemonPhase(args, effects) {
   // The operator CLI owns the shared daemon; ours-mcp is the per-session stdio
   // adapter each harness spawns. Both are required, but only `ours daemon`
   // participates in lifecycle or service management.
-  const mcpPkg = componentSpec(componentByKey('mcp'), args.channel);
+  const mcpPkg = exactSuite?.packages?.mcp
+    ? `@ours.network/mcp@${exactSuite.packages.mcp}`
+    : componentSpec(componentByKey('mcp'), args.channel);
+  // The CLI intentionally publishes only `latest`; unlike the lockstep MCP and
+  // connector packages it has no nightly dist-tag. Keep this untagged on every
+  // installer channel, and inspect that package's SDK dependency for the gate.
+  const cliPkg = '@ours.network/cli';
+  if (!creating && target.daemonVersion) {
+    const mismatch = incompatibleUpgrade(target, effects.packageDependencies(cliPkg));
+    if (mismatch) {
+      const prepared = await prepareIncompatibleUpgrade(args, effects, target, cliPkg, mismatch);
+      if (prepared.refused) return { target, refused: prepared.refused, steps };
+      creating = prepared.purged === true;
+      target.backupPath = prepared.backupPath;
+      target.action = 'create';
+    }
+  }
   await perform(effects, args.dryRun, `MCP server installed (npm i -g ${mcpPkg})`, () => effects.run('npm', ['i', '-g', mcpPkg]));
   steps.push({ id: 'mcp-package', changed: true, packageRefresh: true });
-  await perform(effects, args.dryRun, 'ours CLI installed (npm i -g @ours.network/cli)', () => effects.run('npm', ['i', '-g', '@ours.network/cli']));
+  await perform(effects, args.dryRun, `ours CLI installed (npm i -g ${cliPkg})`, () => effects.run('npm', ['i', '-g', cliPkg]));
   steps.push({ id: 'cli', changed: true, packageRefresh: true });
 
   // The config file — merged, never rewritten, and untouched when it already
@@ -249,8 +382,11 @@ export async function runDaemonPhase(args, effects) {
 
   try {
     if (creating) {
-      await perform(effects, args.dryRun, `start the daemon on port ${target.port}`, () => effects.run('ours', ['daemon', 'start', '--config', configPath]));
+      await perform(effects, args.dryRun, `start the daemon on port ${target.port}`, () => effects.run('ours', ['daemon', 'start', '--config', configPath], { stream: true }));
       steps.push({ id: 'start', changed: true });
+    } else {
+      await perform(effects, args.dryRun, `restart the daemon on port ${target.port}`, () => effects.run('ours', ['daemon', 'restart', '--config', configPath], { stream: true }));
+      steps.push({ id: 'restart', changed: true });
     }
 
     const service = await runServicePhase(args, effects, dir, target.port);
@@ -343,7 +479,7 @@ function rollBack(effects, journal, args, why, { packagesInstalled = true, repla
 }
 
 /**
- * The boot service: §4 step 4, including the legacy-unit case.
+ * Install the boot service, including the legacy-unit case.
  *
  * A legacy ours-mcp unit is adopted SILENTLY, with one informational line naming
  * the file. `--force` is passed ONLY here, only for a unit
@@ -430,11 +566,11 @@ export async function askComponents(args, effects) {
 }
 
 /**
- * Components: §5. A component that fails is reported with its retry command and
+ * A component that fails is reported with its retry command and
  * the run CONTINUES — a failed component is never a reason to undo a successful
  * one, or to undo the daemon.
  */
-export async function runComponentPhase(args, effects, target) {
+export async function runComponentPhase(args, effects, target, exactSuite = null) {
   const dir = target.stateDir;
   const endpoint = `http://127.0.0.1:${target.port}`;
   const isDefaultStateDir = dir === join(effects.home, '.ours');
@@ -453,13 +589,15 @@ export async function runComponentPhase(args, effects, target) {
       continue;
     }
     try {
-      results.push(await attachComponent(component, { args, effects, dir, endpoint, isDefaultStateDir }));
+      results.push(await attachComponent(component, { args, effects, dir, endpoint, isDefaultStateDir, exactSuite }));
     } catch (error) {
       // Reported with its reason and the exact manual command; the run continues.
       // The retry carries the CHANNEL — a nightly run that hands the operator a
       // stable retry command sends them straight into the split-brain install
       // this phase exists to avoid.
-      const retry = `npm i -g ${componentSpec(component, args.channel)}`;
+      const retrySpec = component.key === 'mcp' && exactSuite?.packages?.mcp
+        ? `@ours.network/mcp@${exactSuite.packages.mcp}` : componentSpec(component, args.channel);
+      const retry = `npm i -g ${retrySpec}`;
       effects.out(warn(`${component.label} failed: ${error instanceof Error ? error.message : String(error)}`));
       effects.out(info(`retry manually: ${retry}`));
       results.push({ key: component.key, state: 'failed', reason: String(error?.message ?? error), retry });
@@ -468,10 +606,11 @@ export async function runComponentPhase(args, effects, target) {
   return summarizeComponentRun(results);
 }
 
-async function attachComponent(component, { args, effects, dir, endpoint, isDefaultStateDir }) {
+async function attachComponent(component, { args, effects, dir, endpoint, isDefaultStateDir, exactSuite }) {
   if (component.key === 'mcp') {
     const plan = planMcpAttachment({ stateDir: dir, isDefaultStateDir, channel: args.channel });
-    await perform(effects, args.dryRun, `install ${plan.install[3]}`, () => effects.run(plan.install[0], plan.install.slice(1)));
+    const exact = exactSuite?.packages?.mcp ? `@ours.network/mcp@${exactSuite.packages.mcp}` : plan.install[3];
+    await perform(effects, args.dryRun, `install ${exact}`, () => effects.run('npm', ['i', '-g', exact]));
     if (Object.keys(plan.harnessEnv).length > 0) {
       effects.out(info(`harness registration carries OURS_CONFIG=${plan.harnessEnv.OURS_CONFIG}`));
     }
@@ -502,14 +641,21 @@ async function attachComponent(component, { args, effects, dir, endpoint, isDefa
       }
     }
     await perform(effects, args.dryRun, `install ${plan.install[3]}`, () => effects.run(plan.install[0], plan.install.slice(1)));
+    const journal = configJournal(effects, { dryRun: args.dryRun });
     if (plan.changed) {
+      journal.snapshot(path);
       await perform(effects, args.dryRun, `write ${path}`, () => effects.writeJson(path, `${JSON.stringify(plan.config, null, 2)}\n`));
     } else {
       effects.out(ok(`${path} already points here — not touched`));
     }
-    effects.out(ok('Telegram connector installed and configured, but not started.'));
-    effects.out(info('After adding a bot, start it explicitly with: ours-tg-connector install-service'));
-    return { key: 'tg', state: 'installed', note: 'configured; stopped' };
+    try {
+      await perform(effects, args.dryRun, 'Telegram connector service installed', () => effects.run(plan.service[0], plan.service.slice(1)));
+    } catch (error) {
+      rollBack(effects, journal, args, 'the Telegram connector service did not come up — putting its daemon selection back');
+      throw error;
+    }
+    effects.out(ok('Telegram connector installed as a durable service on the shared daemon.'));
+    return { key: 'tg', state: 'installed', note: 'configured; service running' };
   }
 
   const path = coworkConfigPath(effects.home, effects.env);
@@ -665,7 +811,7 @@ export async function runIdentityPhase(args, effects, { target, mcpReady }) {
 }
 
 /**
- * The harness plugins (spec §5's other half).
+ * Install harness plugins after the daemon and components are ready.
  *
  * Two things this phase must never do, both inherited rules rather than new
  * ones. It never DRIVES a command it could not identify — an alias or a wrapper
@@ -675,7 +821,7 @@ export async function runIdentityPhase(args, effects, { target, mcpReady }) {
  * get the exact export line and no promise. Hermes' writer is ours, so its
  * invocation carries the whole pair and the claim is true.
  */
-export async function runHarnessPhase(args, effects, { target, isDefaultStateDir }) {
+export async function runHarnessPhase(args, effects, { target, isDefaultStateDir, exactSuite = null }) {
   effects.out(heading('Harness plugins'));
   const detected = await effects.detectHarnesses();
   for (const h of detected) {
@@ -700,6 +846,7 @@ export async function runHarnessPhase(args, effects, { target, isDefaultStateDir
   });
 
   const rows = [];
+  const markets = marketplacePaths(effects.home);
   for (const plan of plans) {
     const row = { key: plan.name, label: `${plan.label} plugin` };
     if (plan.action === 'skip') {
@@ -710,27 +857,65 @@ export async function runHarnessPhase(args, effects, { target, isDefaultStateDir
     if (plan.action === 'manual') {
       // NEVER a dead end: the plugin is still installable, by hand, and the run
       // says so instead of pretending the harness does not exist.
+      let manual = plan.manual;
+      if (exactSuite && (plan.name === 'claude-code' || plan.name === 'codex')) {
+        const isClaude = plan.name === 'claude-code';
+        const root = isClaude ? markets.claudeRoot : markets.codexRoot;
+        const manifest = isClaude ? markets.claudeManifest : markets.codexManifest;
+        const value = isClaude
+          ? buildClaudeMarketplace(exactSuite.packages['claude-code'], exactSuite.channel)
+          : buildCodexMarketplace(exactSuite.packages.codex, exactSuite.channel);
+        await perform(effects, args.dryRun, `write exact ${plan.name} marketplace ${manifest}`, () => effects.writeJson(manifest, marketplaceJson(value)));
+        manual = isClaude
+          ? [`/plugin marketplace add ${root}`, '/plugin install ours']
+          : [`codex plugin marketplace add ${root}`, 'codex plugin add ours@ours-codex-marketplace', `npm i -g @ours.network/codex@${exactSuite.packages.codex}`];
+      }
       effects.out(warn(`${plan.label} — ${plan.reason}; install it yourself with:`));
-      for (const step of plan.manual) effects.out(info(`  ${step}`));
+      for (const step of manual) effects.out(info(`  ${step}`));
       rows.push({ ...row, state: 'skipped', note: plan.reason });
       continue;
     }
 
+    let steps = plan.steps;
+    let manual = plan.manual;
+    if (exactSuite && (plan.name === 'claude-code' || plan.name === 'codex')) {
+      const isClaude = plan.name === 'claude-code';
+      const root = isClaude ? markets.claudeRoot : markets.codexRoot;
+      const manifest = isClaude ? markets.claudeManifest : markets.codexManifest;
+      const value = isClaude
+        ? buildClaudeMarketplace(exactSuite.packages['claude-code'], exactSuite.channel)
+        : buildCodexMarketplace(exactSuite.packages.codex, exactSuite.channel);
+      await perform(effects, args.dryRun, `write exact ${plan.name} marketplace ${manifest}`, () => effects.writeJson(manifest, marketplaceJson(value)));
+      if (!isClaude) {
+        const current = await effects.codexMarketplace();
+        const source = current?.marketplaceSource;
+        if (current && !(source?.sourceType === 'local' && source?.source === root)) {
+          await perform(effects, args.dryRun, 'remove moving Codex marketplace source', () => effects.run('codex', ['plugin', 'marketplace', 'remove', 'ours-codex-marketplace']));
+        }
+      }
+      steps = isClaude
+        ? [['claude', 'plugin', 'marketplace', 'add', root], ['claude', 'plugin', await effects.hasClaudePlugin() ? 'update' : 'install', 'ours@ours.network']]
+        : [['codex', 'plugin', 'marketplace', 'add', root], ['codex', 'plugin', 'add', 'ours@ours-codex-marketplace'], ['npm', 'i', '-g', `@ours.network/codex@${exactSuite.packages.codex}`]];
+      manual = isClaude
+        ? [`/plugin marketplace add ${root}`, '/plugin install ours']
+        : [`codex plugin marketplace add ${root}`, 'codex plugin add ours@ours-codex-marketplace', `npm i -g @ours.network/codex@${exactSuite.packages.codex}`];
+    }
+
     const env = pairFor(plan, target);
     let failed = null;
-    for (const step of plan.steps) {
+    for (const step of steps) {
       const outcome = await attempt(effects, args.dryRun, step.join(' '), () => effects.run(step[0], step.slice(1), env ? { env } : {}));
       if (!outcome.ok) { failed = outcome; break; }
     }
     if (failed) {
       effects.out(info(`${plan.label} can still be installed by hand:`));
-      for (const step of plan.manual) effects.out(info(`  ${step}`));
+      for (const step of manual) effects.out(info(`  ${step}`));
       rows.push({ ...row, state: 'failed', note: 'install step failed' });
       continue;
     }
     if (plan.envLine) {
-      // The honest line. §5's promise does NOT hold for this harness, and the
-      // screen says exactly what is true and exactly what to do about it.
+      // This harness cannot persist the selected daemon pair. Say exactly what is
+      // true and how the operator can configure it explicitly.
       effects.out(warn(`${plan.label}'s registration cannot carry a value, so it will attach to the DEFAULT daemon.`));
       effects.out(info(`Add this to your shell profile so it uses this one instead:  ${plan.envLine}`));
     }
@@ -823,13 +1008,9 @@ export async function endScreen(args, effects, { summary, target, isDefaultState
   }
 
   const has = (key) => summary.some((r) => r.key === key && (r.state === 'installed' || r.state === 'current'));
-  if (has('tg') || has('fleet')) {
+  if (has('fleet')) {
     effects.out('');
     effects.out(`  ${c.bold('Installed but intentionally stopped')}`);
-    if (has('tg')) {
-      effects.out(`  ${c.gray('• Telegram: add a bot/route first, then run')}`);
-      effects.out(`    ${c.cyan('ours-tg-connector install-service')}`);
-    }
     if (has('fleet')) {
       effects.out(`  ${c.gray('• Fleet: review the generated coordinator/watchdog config, then run')}`);
       effects.out(`    ${c.cyan('ours-fleet doctor && ours-fleet config && ours-fleet up')}`);
@@ -917,6 +1098,13 @@ export async function runInstall(argv, effects) {
   // that wrapped the old installer keeps its meaning.
   if (!runPreflight(effects).ok) return EXIT_OK;
 
+  const exactSuite = await resolveExactSuite(args, effects);
+  if (!exactSuite.ok) {
+    effects.out(warn(`Release suite could not be resolved safely: ${exactSuite.reason}. Nothing was changed.`));
+    return EXIT_REFUSED;
+  }
+  effects.out(ok(`Release channel: ${exactSuite.channel} → exact lockstep suite v${exactSuite.version}`));
+
   // Which daemon, before anything is decided about it. Only args.stateDir can
   // change here; every refusal downstream is unaffected.
   effects.out(progress(2, 8, 'Choose one daemon', 'Reuse the only detected daemon or create one coherent shared target.'));
@@ -924,7 +1112,7 @@ export async function runInstall(argv, effects) {
   if (selection.action === 'refuse') return EXIT_REFUSED;
 
   effects.out(progress(3, 8, 'Prepare the shared daemon', 'Install the CLI, write config, start it, and enable boot persistence.'));
-  const daemon = await runDaemonPhase(args, effects);
+  const daemon = await runDaemonPhase(args, effects, exactSuite);
   if (daemon.refused) return EXIT_REFUSED;
   const target = daemon.target;
   const isDefaultStateDir = target.stateDir === join(effects.home, '.ours');
@@ -946,8 +1134,8 @@ export async function runInstall(argv, effects) {
     });
   }
 
-  effects.out(progress(4, 8, 'Install the complete stack', 'Attach MCP, Telegram, and cowork to the same daemon; Telegram stays stopped.'));
-  const components = await runComponentPhase(args, effects, target);
+  effects.out(progress(4, 8, 'Install the complete stack', 'Attach MCP, Telegram, and cowork to the same daemon; run both shims as durable services.'));
+  const components = await runComponentPhase(args, effects, target, exactSuite);
   for (const component of COMPONENTS) {
     const state = components.installed.includes(component.key) ? 'installed'
       : components.failed.some((f) => f.key === component.key) ? 'failed' : 'skipped';
@@ -957,7 +1145,7 @@ export async function runInstall(argv, effects) {
       state,
       version: state === 'installed' && !args.dryRun ? (effects.installedVersion(component.pkg) ?? '') : '',
       note: components.failed.find((f) => f.key === component.key)?.reason
-        ?? (state === 'installed' && component.key === 'tg' ? 'configured; stopped'
+        ?? (state === 'installed' && component.key === 'tg' ? 'configured; service running'
           : state === 'installed' && component.key === 'cowork' ? 'configured; service running' : undefined),
     });
   }
@@ -966,7 +1154,7 @@ export async function runInstall(argv, effects) {
   effects.out(progress(5, 8, 'Create the Human identity', 'Create the daemon root identity once, or keep the existing one.'));
   summary.push(await runIdentityPhase(args, effects, { target, mcpReady }));
   effects.out(progress(6, 8, 'Wire detected harnesses', 'Install the ours plugin into each safe Claude Code, Codex, or Hermes installation.'));
-  summary.push(...await runHarnessPhase(args, effects, { target, isDefaultStateDir }));
+  summary.push(...await runHarnessPhase(args, effects, { target, isDefaultStateDir, exactSuite }));
   effects.out(progress(7, 8, 'Stage the fleet', 'Install Fleet and write a stopped coordinator + watchdog + health-loop starter config.'));
   summary.push(await runFleetPhase(args, effects, { target, isDefaultStateDir }));
   summary.push(await runVoicePhase(args, effects, { target, mcpReady }));

package/lib/plan.mjs

@@ -1,6 +1,6 @@
 // ours-install v3 — daemon creation and boot-service installation.
 //
-// Spec: installer-spec-v3 §§3-4. Pure, like lib/target.mjs: the orchestrator
+// Pure planning code, like lib/target.mjs: the orchestrator
 // injects file reads, and every function returns a PLAN the caller renders and
 // executes. Nothing here writes, spawns, or runs systemctl.
 
@@ -11,7 +11,7 @@ export const SYSTEMD_USER_DIR = ['.config', 'systemd', 'user'];
 export const DEFAULT_SYSTEMD_UNIT = 'ours.service';
 
 // -----------------------------------------------------------------------------
-// §4 — which unit file does this state directory own?
+// Which unit file does this state directory own?
 // -----------------------------------------------------------------------------
 
 // 1–32 chars, alphanumeric with interior hyphens/underscores, no dots.
@@ -59,7 +59,7 @@ export function unitPathForStateDir(stateDir, home) {
  *   legacy      — the unit published ours-mcp wrote: NO marker, ExecStart running
  *                 ours-mcp. This is the migration blocker. `ours daemon
  *                 install-service` refuses to overwrite an unmarked unit without
- *                 --force, so spec §4 step 4 fails for every existing Linux user.
+ *                 --force, so service installation fails for every existing Linux user.
  *   foreign     — unmarked and NOT recognisably ours-mcp's. Someone else's file.
  *
  * THE legacy/foreign SPLIT IS NOW THE ENTIRE SAFETY BOUNDARY. A `legacy` unit is
@@ -85,7 +85,7 @@ export function classifyUnit(text) {
 }
 
 /**
- * What this run should do about the boot service (spec §4 step 4).
+ * Decide what this run should do about the boot service.
  *
  * Returns one of:
  *   { action: 'install' }                        — call the CLI; it does the rest
@@ -202,9 +202,9 @@ export function legacyReplacedNotice(unitPath, stateDir) {
 
 /**
  * The CLI invocation that installs the boot service. The unit NAME is not passed:
- * ours-sdk #20 made the CLI derive it from --state-dir itself, which is why spec
- * §4's "the installer must either pass a per-instance unit name or write the unit
- * itself" no longer applies — neither, it selects the daemon and the CLI names
+ * ours-sdk #20 made the CLI derive it from --state-dir itself, so the installer
+ * neither passes a per-instance unit name nor writes the unit itself: it selects
+ * the daemon and the CLI names
  * the unit. One derivation, in one place.
  */
 export function serviceInstallCommand({ stateDir, adoptLegacyUnit = false }) {
@@ -221,7 +221,7 @@ export function serviceInstallCommand({ stateDir, adoptLegacyUnit = false }) {
 }
 
 // -----------------------------------------------------------------------------
-// §3(a) step 2 / §4 step 2 — the daemon config file
+// Daemon configuration file
 // -----------------------------------------------------------------------------
 
 /**
@@ -247,7 +247,7 @@ export function planDaemonConfig(existing, { port, stateDir, brokerUrl }) {
 }
 
 /**
- * The ordered, announced steps for the daemon half of a run (spec §4). Each is
+ * The ordered, announced steps for the daemon half of a run. Each is
  * idempotent, and an `update` skips creation entirely: it never moves a port and
  * never creates a second daemon.
  */

package/lib/rerun.mjs

@@ -1,14 +1,14 @@
 // ours-install v3 — re-running, and a second daemon alongside the first.
 //
-// Spec: installer-spec-v3 §§6-7. Pure, like the earlier stages.
+// Pure re-run and coexistence planning, like the earlier stages.
 //
 // Two properties this file exists to make checkable rather than hoped for:
 //
-//   IDEMPOTENCE (§6). Running the installer again with the same answers changes
+//   IDEMPOTENCE. Running the installer again with the same answers changes
 //   nothing except refreshed npm packages. Not "changes little" — nothing: no
 //   config written, no unit rewritten, no systemctl run, no daemon restarted.
 //
-//   COEXISTENCE (§7). Two daemons share no per-daemon artefact. Everything keyed
+//   COEXISTENCE. Two daemons share no per-daemon artefact. Everything keyed
 //   to a daemon is derived from its state directory, so two state directories
 //   produce two of everything.
 
@@ -16,8 +16,8 @@ import { join, resolve } from 'node:path';
 import { unitNameForStateDir } from './plan.mjs';
 
 /**
- * Everything that belongs to ONE daemon, derived from its state directory (spec
- * §7's table). Listing them in one place is what makes "these two daemons share
+ * Everything that belongs to one daemon is derived from its state directory.
+ * Listing the artifacts in one place makes "these two daemons share
  * nothing" a property a test can check instead of a claim in a document.
  *
  * `port` is included because it is per-daemon, but note it is NOT what identifies
@@ -55,7 +55,7 @@ export function daemonCollisions(a, b) {
 }
 
 /**
- * The per-component coexistence rule (spec §7), stated so the screen can never
+ * The per-component coexistence rule, stated so the screen can never
  * imply something the design does not do.
  *
  *   mcp    — coexists naturally. Each harness registration carries its own
@@ -107,7 +107,7 @@ export function summarizeRun(steps) {
 }
 
 /**
- * Did a re-run leave the daemon alone? Spec §3(a): update never deletes state,
+ * Did a re-run leave the daemon alone? An update never deletes state,
  * never moves a port, and never creates a second daemon.
  */
 export function assertUpdateLeftDaemonAlone({ before, after }) {