@ours.network/install 0.17.0 → 0.18.0-nightly.1

package/lib/effects.mjs

@@ -0,0 +1,349 @@
+// ours-install v3 — the real side effects.
+//
+// Every mutation the installer can perform lives here and nowhere else, behind
+// the same contract lib/orchestrate.mjs is tested against. Keeping them in one
+// small file is the point: it is the only place to audit for "does this touch
+// the machine", and it is what makes the fake used in the tests a faithful
+// stand-in rather than an approximation.
+//
+// NOTE: nothing here runs systemctl. systemd is reached ONLY through
+// `ours daemon install-service`, which owns the marker check, the baked
+// state-directory guard and the enable/reload. The installer never touches a
+// unit file or the service manager directly.
+
+import { spawnSync, execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, userInfo, platform as osPlatform, release as osRelease } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { atomicWriteConfig, snapshotConfig, restoreConfig } from './config.mjs';
+import { askYesNo, askLine as askLineOnTty } from './prompt.mjs';
+import { classifyHarnessProbe } from './logic.mjs';
+import { classifyStateDir } from './detect.mjs';
+
+/** GET http://127.0.0.1:<port>/state-dir — the unauthenticated identity probe. */
+async function probePort(port, { timeoutMs = 1500 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/state-dir`, { signal: controller.signal });
+    if (!res.ok) return { ok: false, reason: `HTTP ${res.status}` };
+    const body = await res.json();
+    if (typeof body?.stateDir !== 'string') return { ok: false, reason: 'no stateDir in reply' };
+    return { ok: true, stateDir: body.stateDir };
+  } catch (error) {
+    return { ok: false, reason: error?.name === 'AbortError' ? 'timed out' : String(error?.message ?? error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Is this port bound? Probed in a throwaway child so a bind attempt cannot leave
+ * a listener behind in this process — the same technique the existing installer
+ * uses (install.mjs portTakenSync).
+ */
+function portTakenSync(port) {
+  const src = `const net=require('net');const s=net.createServer();s.once('error',e=>{process.exit(e.code==='EADDRINUSE'?3:0)});s.listen(${port},'127.0.0.1',()=>{s.close(()=>process.exit(0))});`;
+  return spawnSync(process.execPath, ['-e', src], { stdio: 'ignore' }).status === 3;
+}
+
+function readJsonFile(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function readTextFile(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function installedVersionOf(pkg) {
+  try {
+    const out = execFileSync('npm', ['ls', '-g', '--depth', '0', '--json', pkg], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return JSON.parse(out)?.dependencies?.[pkg]?.version ?? null;
+  } catch {
+    // Unreadable is NOT "new enough": the cowork gate fails closed on null.
+    return null;
+  }
+}
+
+/**
+ * A read-only command probe that NEVER throws and NEVER inherits stdio.
+ *
+ * Separate from `run` on purpose. `run` is for mutations and throws on a
+ * non-zero exit, because a failed mutation is news. Detection is the opposite:
+ * a non-zero exit IS the answer, and a hung wrapper must be killed rather than
+ * waited on. Mixing the two would mean either detection crashes a run or a
+ * failed install passes silently.
+ */
+function capture(cmd, args, { timeout, env = process.env } = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'], env });
+  const timedOut = !!(r.error && (r.error.code === 'ETIMEDOUT' || r.signal === 'SIGTERM'));
+  return {
+    ok: !r.error && r.status === 0,
+    code: r.status ?? -1,
+    stdout: r.stdout ?? '',
+    stderr: r.stderr ?? '',
+    timedOut,
+  };
+}
+
+// The two harnesses that are DRIVEN CLIs. The `name` is the one lib/extras.mjs
+// plans against; the `command` is what actually lives on PATH.
+export const DRIVEN_HARNESSES = [
+  { name: 'claude-code', command: 'claude', label: 'Claude Code' },
+  { name: 'codex', command: 'codex', label: 'Codex' },
+];
+
+/**
+ * Alias-safety, unchanged from v2: three read-only observations, then the pure
+ * classifier decides. The harness is NEVER called in a way that can hang —
+ * `--version` is spawned directly (no shell, so a real PATH binary) under a hard
+ * timeout, and the shell `type` lookup is timeout-guarded too.
+ */
+function detectDrivenHarness({ name, command, label }, env) {
+  const onPath = capture('bash', ['-c', `command -v ${command}`], { env }).ok;
+  const probe = capture(command, ['--version'], { timeout: 6000, env });
+  const versionOk = probe.ok && /\d+\.\d+/.test(probe.stdout);
+  const shell = env.SHELL || '/bin/bash';
+  const typeProbe = capture(shell, ['-ic', `type -t ${command} 2>/dev/null`], { timeout: 4000, env });
+  const verdict = classifyHarnessProbe({
+    onPath, versionOk, timedOut: probe.timedOut, shellType: (typeProbe.stdout || '').trim(),
+  });
+  return { name, command, label, ...verdict };
+}
+
+/**
+ * Hermes is detected DIFFERENTLY, and it is not an inconsistency. Its ours
+ * plugin never calls a `hermes` binary — `ours-hermes-install` writes
+ * ~/.hermes/config.yaml and the skills — so "can we drive it?" is the wrong
+ * question. Per the plugin's own prerequisites, presence IS the config
+ * directory. The CLI probe still runs, purely to enrich detection.
+ */
+function detectHermesHarness(env, home) {
+  const dir = env.HERMES_DIR || join(home, '.hermes');
+  const dirPresent = existsSync(dir);
+  const cli = detectDrivenHarness({ name: 'hermes', command: 'hermes', label: 'Hermes' }, env);
+  return {
+    name: 'hermes',
+    command: 'hermes',
+    label: 'Hermes',
+    status: dirPresent || cli.status === 'ok' ? 'ok' : 'absent',
+    detail: dirPresent ? `config dir ${dir} present` : cli.detail,
+  };
+}
+
+/**
+ * Best-effort clipboard copy (pbcopy / wl-copy / xclip / clip.exe). The hard
+ * timeout is load-bearing: xclip holds the selection and would otherwise keep
+ * the installer alive after its own summary.
+ */
+function copyToClipboard(text) {
+  const tools = [['pbcopy', []], ['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['clip.exe', []]];
+  for (const [bin, args] of tools) {
+    try {
+      const r = spawnSync(bin, args, { input: text, timeout: 2000 });
+      if (!r.error && (r.status === 0 || r.status == null)) return true;
+    } catch { /* try the next one */ }
+  }
+  return false;
+}
+
+/**
+ * Every DAEMON state directory on this machine.
+ *
+ * ONE DEFINITION OF WHAT A DAEMON IS, and this function is why that matters.
+ *
+ * It used to count any `~/.ours*` directory containing a config.json. Two of those
+ * are not daemons on a perfectly normal machine: `~/.ours-telegram/config.json` is
+ * the Telegram connector's and `~/.ours-cowork/config.json` is cowork's. So the
+ * uninstaller reported "@ours.network/cli kept — still used by the daemon at
+ * ~/.ours-telegram", and two things followed silently:
+ *
+ *   · planGlobalPackages kept cli, mcp and the plugin packages FOREVER on any
+ *     machine with the connector installed, naming a connector's config directory
+ *     as a daemon;
+ *   · worse, planPluginRemoval's `lastDaemon` went false, so the whole harness
+ *     plugin phase was skipped — with a reason that was not true. A plain
+ *     interactive `ours-uninstall` on a machine with the connector removed no
+ *     plugins at all.
+ *
+ * The selection screen had already closed exactly this: config.json is the one
+ * piece of evidence that is AMBIGUOUS, so it cannot be the test. That predicate
+ * lives in lib/detect.mjs and this now calls it rather than keeping a second,
+ * naive copy that drifted. A daemon is identified by an artefact only a daemon
+ * writes, or by a config whose SHAPE is a daemon's.
+ *
+ * Still deliberately conservative about WHERE it looks: only `~/.ours` and its
+ * `~/.ours*` siblings. A state directory somewhere else is not found, and an
+ * unreadable home means "there might be others", not "there are none" — because
+ * the caller uses this to decide whether a GLOBAL package is still needed, and
+ * being wrong the optimistic way uninstalls the CLI out from under a running
+ * daemon.
+ */
+function knownStateDirsIn(home) {
+  const found = [];
+  const io = { exists: existsSync, readJson: readJsonFile };
+  const consider = (dir) => { if (classifyStateDir(dir, io).isDaemon) found.push(dir); };
+  consider(join(home, '.ours'));
+  try {
+    for (const entry of readdirSync(home, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !entry.name.startsWith('.ours') || entry.name === '.ours') continue;
+      consider(join(home, entry.name));
+    }
+  } catch { /* an unreadable home is not evidence that there are no others */ }
+  return found;
+}
+
+/**
+ * Build the real effects. `write` and `ttyFd` come from the caller's UI layer so
+ * the orchestrator never reaches for a terminal itself.
+ */
+export function realEffects({ write, ttyFd, env = process.env, home = homedir(), out, version = null } = {}) {
+  return {
+    home,
+    env,
+    version,
+    // Preflight reads the machine rather than asking the orchestrator to.
+    platform: { platform: osPlatform(), release: osRelease() },
+    nodeVersion: process.versions.node,
+    exists: (path) => existsSync(path),
+    knownStateDirs: () => knownStateDirsIn(home),
+    // The only irreversible effect in this package, and the reason it takes no
+    // pattern and no parent: the caller passes ONE resolved directory that the
+    // pure planner already gated four ways, and this deletes exactly that.
+    removeDir: (path) => { rmSync(resolve(path), { recursive: true, force: true }); },
+    removeFile: (path) => { rmSync(resolve(path), { force: true }); },
+    // Rewrites a config file we do NOT own, so it keeps the file's own mode
+    // rather than imposing 0600: tightening the permissions of somebody else's
+    // ~/.codex/config.toml is a side effect nobody asked this to have.
+    //
+    // DO NOT "IMPROVE" THIS TO 0600. It looks like a security improvement, which
+    // is exactly why someone will try — but this file is the operator's, not
+    // ours, and the only thing we were invited to do to it is remove our own
+    // block. Changing its mode on the way past is an uninvited change to a file
+    // we happened to be holding, and a tool that does that once is a tool you
+    // cannot let near your configs.
+    writeText: (path, text) => {
+      const mode = (() => { try { return statSync(path).mode & 0o777; } catch { return 0o644; } })();
+      const temp = `${path}.tmp-${process.pid}`;
+      writeFileSync(temp, text, { encoding: 'utf8', mode });
+      renameSync(temp, path);
+    },
+    username: () => { try { return userInfo().username || 'me'; } catch { return 'me'; } },
+    detectHarnesses: () => [
+      ...DRIVEN_HARNESSES.map((h) => detectDrivenHarness(h, env)),
+      detectHermesHarness(env, home),
+    ],
+    clipboard: (text) => copyToClipboard(text),
+    brokerUrl: env.OURS_BROKER_URL ?? 'wss://broker1.ours.network',
+    now: () => Date.now(),
+    probe: (port) => probePort(port),
+    isTaken: (port) => portTakenSync(port),
+    readJson: readJsonFile,
+    readText: readTextFile,
+    writeJson: (path, text) => {
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      atomicWriteConfig(path, text);
+    },
+    // The two halves of a config rollback (lib/journal.mjs). Deliberately the
+    // SAME pair the nightly installer uses, from lib/config.mjs, rather than a
+    // second implementation: `snapshot` records bytes and mode, and `restore`
+    // either writes those bytes back at their original mode or DELETES a file
+    // that did not exist before this run. Both are ordinary reads and writes of a
+    // file this installer was already writing — no new class of side effect
+    // enters the package here.
+    snapshot: (path) => snapshotConfig(path),
+    restore: (path, snapshot) => restoreConfig(path, snapshot),
+    // `extraEnv` is the daemon pair (see daemonEnv). It is applied to THIS
+    // invocation only and never to the installer's own process: a state
+    // directory selected by one run must not leak into anything the operator
+    // starts afterwards.
+    run: async (cmd, args, { env: extraEnv = null } = {}) => {
+      // Always built from this layer's OWN env rather than left to spawnSync's
+      // implicit inheritance, so what a child receives is a property of the
+      // effects object a caller constructed and not of whatever ambient shell
+      // the installer happened to start in.
+      const childEnv = { ...env, ...(extraEnv ?? {}) };
+      const r = spawnSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: childEnv });
+      if (r.status !== 0) {
+        const detail = (r.stderr || r.stdout || '').trim().split('\n').slice(-3).join('; ');
+        throw new Error(`${cmd} ${args.join(' ')} exited ${r.status}${detail ? `: ${detail}` : ''}`);
+      }
+      return { ok: true, code: r.status, stdout: r.stdout ?? '' };
+    },
+    // The ONE invocation that must keep the user's terminal: `ours-mcp
+    // voice-setup` is an interactive command with its own masked prompts, and
+    // piping its stdio would hang it forever waiting on input nobody can type.
+    // It is otherwise the same contract as `run` — including the environment,
+    // so an interactive command reaches the same daemon a piped one would.
+    runInteractive: async (cmd, args, { env: extraEnv = null } = {}) => {
+      const r = spawnSync(cmd, args, { stdio: 'inherit', env: { ...env, ...(extraEnv ?? {}) } });
+      return { ok: !r.error && r.status === 0, code: r.status ?? -1 };
+    },
+    installedVersion: installedVersionOf,
+    out: out ?? ((line) => process.stdout.write(`${line}\n`)),
+    // Never called when assumeYes: the orchestrator takes the default itself.
+    ask: async (prompt, def = false) => (ttyFd == null ? def : askYesNo(write, ttyFd, `  ${prompt}  `, def)),
+    askLine: async (prompt, def = '') => (ttyFd == null ? def : askLineOnTty(write, ttyFd, `  ${prompt}  `, def)),
+  };
+}
+
+export const __testables = { probePort, portTakenSync, readJsonFile, readTextFile, installedVersionOf, knownStateDirsIn };
+
+// -----------------------------------------------------------------------------
+// THE PAIR
+// -----------------------------------------------------------------------------
+
+/**
+ * The environment that names ONE daemon, for a single child invocation.
+ *
+ * Spec §2's rule is that a state directory and an endpoint always travel
+ * together; "endpoint selected, state directory defaulted" must be unreachable.
+ * Every consumer downstream — ours-mcp's proxy, ours-fleet's per-role resolver,
+ * ours-hermes-install — reads these three names and falls back to `~/.ours` for
+ * whichever one is missing. So a HALF pair does not fail: it silently attaches
+ * to the default daemon while the operator was told a different one was chosen.
+ *
+ * That is why this is a function and not three assignments at the call sites.
+ * There is exactly one place a daemon environment can be built, it takes both
+ * halves as arguments, and it refuses rather than emit a partial one.
+ *
+ * The three names, not two, are deliberate: OURS_CONFIG alone would leave the
+ * port to whatever config.json happens to say, which is exactly the stale-file
+ * divergence lib/target.mjs's second lookup exists to survive.
+ */
+export const DAEMON_ENV_KEYS = ['OURS_CONFIG', 'OURS_STATE_DIR', 'OURS_PORT'];
+
+export function daemonEnv(stateDir, port) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (!dir) throw new Error('daemonEnv requires a state directory: refusing to build half of the daemon pair');
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('daemonEnv requires a port between 1 and 65535: refusing to build half of the daemon pair');
+  }
+  const resolved = resolve(dir);
+  return {
+    OURS_CONFIG: join(resolved, 'config.json'),
+    OURS_STATE_DIR: resolved,
+    OURS_PORT: String(port),
+  };
+}
+
+/** Is this environment a whole pair (or nothing at all)? Never one half. */
+export function isWholeDaemonEnv(env) {
+  if (env == null) return true;
+  const present = DAEMON_ENV_KEYS.filter((k) => typeof env[k] === 'string' && env[k] !== '');
+  if (present.length === 0) return true;
+  if (present.length !== DAEMON_ENV_KEYS.length) return false;
+  return env.OURS_CONFIG === join(resolve(env.OURS_STATE_DIR), 'config.json');
+}
+
+/** The state directory a default run targets, for callers that need it early. */
+export const defaultStateDir = (home = homedir()) => join(home, '.ours');

package/lib/extras.mjs

@@ -0,0 +1,320 @@
+// ours-install v3 — the four retained extras, re-pointed at the v3 arrangement.
+//
+// The v3 installer keeps harness plugins, ours-fleet, voice setup and the
+// copy-paste hand-off prompt; spec v3's silence about them was an oversight.
+//
+// The shared daemon belongs to the operator CLI. ours-mcp is only a per-session
+// stdio adapter with no unit, and these extra phases preserve that boundary.
+//
+// Pure, like target.mjs / plan.mjs / components.mjs: no I/O, no subprocess, no
+// terminal. Every function takes what was observed and returns a plan; the
+// orchestrator (a later PR) is what performs it.
+
+import { join, resolve } from 'node:path';
+import { pkgSpec } from './logic.mjs';
+
+const cfgPath = (stateDir) => join(resolve(stateDir), 'config.json');
+
+// -----------------------------------------------------------------------------
+// §5 — harness plugins
+// -----------------------------------------------------------------------------
+
+export const CLAUDE_MARKET = 'adapt-toolkit/ours-claude-marketplace';
+export const CODEX_MARKET = 'adapt-toolkit/ours-codex-marketplace';
+
+export const HARNESSES = [
+  { name: 'claude-code', label: 'Claude Code' },
+  { name: 'codex', label: 'Codex' },
+  { name: 'hermes', label: 'Hermes' },
+];
+
+/**
+ * SPEC §5 PROMISES SOMETHING TWO OF THE THREE REGISTRATIONS CANNOT DO.
+ *
+ * §5: "For any other state directory the installer registers the harness MCP
+ * entry with OURS_CONFIG=<state-dir>/config.json in its environment, so the pair
+ * travels together." planMcpAttachment already returns exactly that harnessEnv —
+ * and the orchestrator only PRINTS it. That is not an oversight to be fixed by
+ * wiring it up harder; none of the three registrations can carry a value:
+ *
+ *   Claude Code  the marketplace plugin's mcpServers.ours is command+args, with
+ *                no env key, and `claude plugin install` injects nothing per
+ *                install.
+ *   Codex        .mcp.json's env_vars is an allowlist of NAMES, not a value map
+ *                (pinned by packages/codex/test/plugin-package.test.mjs). The
+ *                value must already be in the ambient environment.
+ *   Hermes       renderConfigBlock is OUR writer, and now emits an `env:` block
+ *                carrying OURS_CONFIG — so for Hermes the pair is real.
+ *
+ * So §5's guarantee is ALREADY unmet today for every non-default state
+ * directory, silently: the harness attaches to ~/.ours while the operator was
+ * told the run targeted somewhere else. The shape is:
+ *
+ *   default state directory   today's behaviour, byte for byte.
+ *   Hermes, non-default       real: the pair is handed to ours-hermes-install's
+ *                             invocation and written into ~/.hermes/config.yaml
+ *                             as the ours server's own env block.
+ *   Claude / Codex, non-def   install the plugin (it is still the right plugin)
+ *                             and PRINT the exact line the operator must add.
+ *                             Never claim §5's guarantee in the screen text.
+ *
+ * Deliberately NOT done: registering a second, user-scoped `ours` MCP server via
+ * `claude mcp add --env`. Two `ours` servers in front of one harness, and which
+ * wins is not something anyone here has verified.
+ */
+export const HARNESS_ENV_SUPPORT = {
+  // 'applied' — the pair is genuinely carried into the registration.
+  // 'printed' — the operator is told the exact line and nothing is claimed.
+  'claude-code': 'printed',
+  codex: 'printed',
+  hermes: 'applied',
+};
+
+const manualSteps = {
+  'claude-code': (channel) => [
+    `/plugin marketplace add ${CLAUDE_MARKET}`,
+    '/plugin install ours',
+  ],
+  codex: (channel) => [
+    `codex plugin marketplace add ${CODEX_MARKET}`,
+    'codex plugin add ours@ours-codex-marketplace',
+    `npm i -g ${pkgSpec('codex', channel)}`,
+  ],
+  hermes: (channel) => [
+    `npm i -g ${pkgSpec('hermes', channel)}`,
+    'ours-hermes-install',
+  ],
+};
+
+const driveSteps = {
+  'claude-code': (channel) => [
+    ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKET],
+    ['claude', 'plugin', 'install', 'ours@ours.network'],
+  ],
+  codex: (channel) => [
+    ['codex', 'plugin', 'marketplace', 'add', CODEX_MARKET],
+    ['codex', 'plugin', 'add', 'ours@ours-codex-marketplace'],
+    // Owner-mandated in v2 and kept: choosing the Codex plugin also installs the
+    // ours-codex live launcher, in the same step.
+    ['npm', 'i', '-g', pkgSpec('codex', channel)],
+  ],
+  // Hermes has no driven CLI: nothing here ever calls a `hermes` binary. Its
+  // plugin install is npm + ours-hermes-install, which writes ~/.hermes.
+  // --skip-daemon because in v3 the daemon is emphatically not ours-mcp's.
+  hermes: (channel) => [
+    ['npm', 'i', '-g', pkgSpec('hermes', channel)],
+    ['ours-hermes-install', '--skip-daemon'],
+  ],
+};
+
+/**
+ * One plan per harness the caller observed.
+ *
+ * `harnesses` is [{ name, status }] where status is classifyHarnessProbe's
+ * verdict ('ok' | 'alias' | 'unsafe' | 'absent'). Hermes is detected by its
+ * config directory rather than a CLI, which is the caller's business; this only
+ * consumes the verdict.
+ *
+ * The v2 golden rule is kept intact: 'alias' / 'unsafe' NEVER dead-end. A
+ * harness we cannot safely drive still gets its manual steps printed, so the
+ * plugin is still installable.
+ *
+ * `env` is what an invocation must carry, and it is EMPTY unless the harness can
+ * genuinely apply it. `envLine` is what the operator is told. `claimsPair` is
+ * false whenever the pair is only printed — the screen text renderer reads it so
+ * §5's guarantee cannot be claimed where it does not hold.
+ */
+export function planHarnessPlugins({
+  harnesses = [],
+  stateDir,
+  isDefaultStateDir,
+  channel = 'latest',
+  assumeYes = false,
+  answers = {},
+} = {}) {
+  const config = stateDir ? cfgPath(stateDir) : null;
+  return harnesses.map((h) => {
+    const name = String(h?.name ?? '');
+    const known = HARNESSES.find((k) => k.name === name);
+    const label = known?.label ?? name;
+    const status = String(h?.status ?? 'absent');
+    const support = HARNESS_ENV_SUPPORT[name] ?? 'printed';
+    const applies = !isDefaultStateDir && support === 'applied';
+
+    const base = {
+      name,
+      label,
+      status,
+      // Default state directory → today's behaviour, byte for byte: no env
+      // anywhere, nothing extra printed, nothing claimed.
+      envSupport: isDefaultStateDir ? 'none' : support,
+      env: applies ? { OURS_CONFIG: config } : {},
+      envLine: isDefaultStateDir || applies ? null : `export OURS_CONFIG=${config}`,
+      claimsPair: isDefaultStateDir ? true : applies,
+      manual: manualSteps[name] ? manualSteps[name](channel) : [],
+    };
+
+    if (!known) return { ...base, action: 'skip', reason: 'unknown harness' };
+    if (status === 'absent') return { ...base, action: 'skip', reason: 'not installed' };
+
+    const wanted = assumeYes ? true : answers[name] !== false;
+    if (!wanted) return { ...base, action: 'skip', reason: 'declined', offerOnRerun: true };
+
+    if (status === 'ok') return { ...base, action: 'drive', steps: driveSteps[name](channel) };
+    return {
+      ...base,
+      action: 'manual',
+      reason: status === 'alias' ? 'installed as an alias, not the real command' : 'found, but did not answer --version',
+    };
+  });
+}
+
+// -----------------------------------------------------------------------------
+// §5 — what the operator has to do BEFORE any of this works
+// -----------------------------------------------------------------------------
+
+/**
+ * The restart each harness needs before its new plugin is live.
+ *
+ * A CORRECTNESS PROBLEM WEARING A COSMETIC COSTUME. The ours MCP server is spawned
+ * BY the harness, once per session (`ours-mcp proxy` over stdio), so a harness that
+ * was already running when its plugin was installed has no ours tools and will not
+ * get them until it restarts. v3 said nothing at all about this: the screen read
+ * "Everything installed cleanly", the user went back to a running Claude Code,
+ * found no ours tools, and concluded the install had failed. The nightly installer
+ * prints these hints and v3 dropped them.
+ *
+ * Derived from what THIS RUN installed rather than from a registry — v3 already
+ * knows, and its own summary is a better source than a persisted file that can go
+ * stale against reality.
+ *
+ * The connectors are deliberately absent. The installer runs their
+ * `install-service` itself, so their new configuration is already applied; telling
+ * someone to restart something that was just restarted for them is noise, and noise
+ * in this list is what stops the real lines being read.
+ */
+export const HARNESS_RESTART = {
+  'claude-code': 'restart Claude Code',
+  codex: 'start a new Codex session (or `ours-codex`)',
+  hermes: 'run /reload-mcp in Hermes',
+};
+
+export function restartHints(summary = []) {
+  const live = (row) => row && (row.state === 'installed' || row.state === 'current');
+  const hints = [];
+  for (const [name, action] of Object.entries(HARNESS_RESTART)) {
+    const row = summary.find((r) => r.key === name);
+    if (live(row)) hints.push({ key: name, action });
+  }
+  // Nothing to restart if no harness got a plugin this run. The MCP server on its
+  // own changes nothing a running harness can see, so an "install the MCP server
+  // and restart everything" line would be advice with no reason behind it.
+  return hints;
+}
+
+// -----------------------------------------------------------------------------
+// ours-fleet — the one that needs zero code
+// -----------------------------------------------------------------------------
+
+/**
+ * ours-fleet needs NO change in either repo, and the installer configures
+ * nothing in it.
+ *
+ * `ours-fleet init` takes no daemon argument of any kind and never reads a
+ * daemon config: it makes its directories, installs its own units and prints a
+ * next step. Fleet resolves the ours daemon the same way the MCP client does —
+ * OURS_CONFIG ?? ~/.ours/config.json, then OURS_PORT / OURS_STATE_DIR /
+ * OURS_API_TOKEN — and it does so PER ROLE, through
+ * resolveEndpoint({ ...process.env, ...role.env }). Different roles can already
+ * target different daemons. Temp supervisors inherit the same four names.
+ *
+ * So for a non-default state directory the installer's ONLY job is to say the
+ * one fleet.yaml line that points a role at the daemon this run created. Saying
+ * it is the whole feature; anything more would be configuring a tool that is
+ * already correct.
+ */
+export function planFleet({ stateDir, isDefaultStateDir, wanted = true, channel = 'latest' } = {}) {
+  const config = stateDir ? cfgPath(stateDir) : null;
+  const plan = {
+    key: 'fleet',
+    label: 'ours-fleet',
+    // FOLLOWS THE CHANNEL, and the correction matters more than it looks.
+    //
+    // This comment used to say the opposite — that ours-fleet lives in its own
+    // repo and publishes no nightly tag, so pkgSpec pinned it to @latest. That
+    // was true when v3 was written against `main` and it is FALSE here: fleet
+    // does publish a nightly dist-tag, and the nightly stack needs the fleet
+    // build carrying the SDK integration. A nightly installer that quietly
+    // installs stable fleet is precisely the split-brain deployment the channel
+    // exists to prevent — the same architecture boundary that made a mixed
+    // tg-connector fatal. lib/logic.mjs is the single source of that mapping and
+    // this defers to it rather than restating it.
+    install: ['npm', 'i', '-g', pkgSpec('fleet', channel)],
+    init: ['ours-fleet', 'init'],
+    // Stated as data so a test can pin it: this feature writes no fleet config.
+    writes: [],
+    roleEnv: isDefaultStateDir ? {} : { OURS_CONFIG: config },
+    instruction: isDefaultStateDir
+      ? null
+      : `fleet roles that should use this daemon need one line in fleet.yaml:\n    env: { OURS_CONFIG: ${config} }`,
+  };
+  return wanted ? { ...plan, action: 'install' } : { ...plan, action: 'skip', offerOnRerun: true };
+}
+
+// -----------------------------------------------------------------------------
+// the copy-paste hand-off prompt
+// -----------------------------------------------------------------------------
+
+/**
+ * buildHandoffPrompt is already pure, already renumbers and already drops steps
+ * for components that were not installed. Re-pointing it is one preamble.
+ *
+ * DEFAULT STATE DIRECTORY → THE TEXT IS UNCHANGED, BYTE FOR BYTE. That is the
+ * overwhelming majority case and it is pinned by a test, because the agent on
+ * the other end of this prompt configures fleet roles and harness environments,
+ * and a stray line about a state directory the user never chose is a worse
+ * outcome than no line at all.
+ */
+export function buildHandoffPromptV3({
+  identity = false,
+  fleet = false,
+  telegram = false,
+  stateDir = null,
+  isDefaultStateDir = true,
+} = {}) {
+  const steps = [];
+  if (identity) {
+    steps.push(
+      'Create my Ours human identity — this is me, the human; my agents act on\n'
+      + '   my behalf. Ask me what name others should see, then create it.',
+    );
+  }
+  if (fleet) {
+    steps.push(
+      'Set up my ours-fleet: ask me what agents I want in my fleet for\n'
+      + '   PERMANENT use (a name + role/purpose for each), then create and\n'
+      + '   configure those permanent fleet agents for me.',
+    );
+  }
+  if (telegram) {
+    steps.push(
+      'Set up my Telegram bot: ask me for my bot\'s name and its token from\n'
+      + '   @BotFather, register the bot, create a chat↔agent connection, and\n'
+      + '   give me the invite link to send.',
+    );
+  }
+  if (steps.length === 0) return { text: '', empty: true };
+
+  const preamble = isDefaultStateDir || !stateDir
+    ? ''
+    : `My ours daemon uses the state directory ${resolve(stateDir)} (config\n${cfgPath(stateDir)}). When you configure anything for me — fleet roles,\nharness environments — set OURS_CONFIG to that path.\n\n`;
+
+  const numbered = steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
+  const text = preamble
+    + 'I just installed the ours.network stack. Please help me finish setup, one\n'
+    + 'step at a time, explaining as you go:\n\n'
+    + numbered + '\n\n'
+    + 'Do these in order, wait for my answers, and tell me if you need anything\n'
+    + "from me. Don't assume — ask.";
+  return { text, empty: false };
+}