@ours.network/install 0.17.0-nightly.7 → 0.17.0-nightly.8

package/lib/components.mjs

@@ -0,0 +1,300 @@
+// ours-install v3 — component selection and attachment.
+//
+// Spec: installer-spec-v3 §5 (and the repoint half of §7, which cannot be
+// separated from attaching the connector without making a silent move possible).
+// Pure, like target.mjs and plan.mjs: the caller injects the current file
+// contents and the installed versions, and every function returns a plan.
+//
+// The three components are the MCP server, the Telegram connector and cowork.
+// None of them IS the daemon; all three attach to one. The messenger is out of
+// scope by the owner's instruction, and ours-fleet sits on top and is not
+// installed here.
+
+import { join, resolve } from 'node:path';
+import { pkgSpec, resolveChannel } from './logic.mjs';
+
+// `pkg` is the package's IDENTITY — bare, no dist-tag — because that is what
+// `npm ls -g --json <pkg>` needs to read an installed version back, and what a
+// component is keyed by in every summary. `specKey` is the same package's name
+// in lib/logic.mjs's channel map, and `componentSpec` below is the only thing
+// that turns the two into an `npm i -g` argument.
+//
+// THE TWO MUST STAY SEPARATE. Putting the tag in `pkg` would make
+// effects.installedVersion('@ours.network/mcp@nightly') return null forever,
+// which fails the cowork version floor CLOSED and blanks the version column —
+// a silent regression that looks like "cowork is too old".
+export const COMPONENTS = [
+  { key: 'mcp', label: 'MCP server', pkg: '@ours.network/mcp', specKey: 'mcp', default: true },
+  { key: 'tg', label: 'Telegram connector', pkg: '@ours.network/tg-connector', specKey: 'tg-connector', default: false },
+  { key: 'cowork', label: 'cowork', pkg: '@ours.network/cowork', specKey: 'cowork', default: false },
+];
+
+/**
+ * The `npm i -g` argument for one component on one channel.
+ *
+ * WHY THIS EXISTS AT ALL. `args.channel` was resolved in the orchestrator and
+ * then reached only lib/extras.mjs's two planners, while these three packages
+ * were installed by their bare names. So `CHANNEL=nightly` installed the NIGHTLY
+ * Codex/Hermes plugins and NIGHTLY ours-fleet beside a STABLE MCP server — the
+ * split-brain deployment the channel exists to prevent, and the same class of
+ * bug the extras.mjs channel-map correction fixed for ours-fleet one package
+ * over. Every install path for these three now goes through here.
+ *
+ * All three publish a real `nightly` dist-tag (verified against the registry,
+ * 2026-08-17), so none of these pins can 404. `pkgSpec` falls back to `latest`
+ * for anything unmapped rather than inventing a tag, so an unknown component
+ * degrades to today's behaviour instead of failing.
+ *
+ * ON THE STABLE CHANNEL THIS RETURNS THE BARE NAME, byte for byte what shipped
+ * before. `npm i -g pkg` and `npm i -g pkg@latest` are the same install, so
+ * appending the tag would have bought nothing and changed every stable screen
+ * line and assertion. The nightly channel is the case that was broken; it is the
+ * only case that changes.
+ */
+export const componentByKey = (key) => COMPONENTS.find((c) => c.key === key);
+
+export function componentSpec(component, channel = 'latest') {
+  const key = typeof component === 'string' ? component : component?.specKey ?? component?.key;
+  const name = typeof component === 'string' ? null : component?.pkg ?? null;
+  if (resolveChannel(channel) === 'latest') return name ?? `@ours.network/${String(key).replace(/^@ours\.network\//, '')}`;
+  return pkgSpec(key, channel);
+}
+
+// cowork must be at least this build to understand an external-daemon block.
+export const COWORK_DAEMON_FLOOR = '0.4.1-nightly.20260816.4aaf940';
+
+// -----------------------------------------------------------------------------
+// THE REGISTRY THAT IS NOT OURS TO TOUCH
+// -----------------------------------------------------------------------------
+
+/**
+ * The Telegram connector keeps its OWN registry of routes, and the installer must
+ * never write into it.
+ *
+ *   ~/.ours-telegram/bots.json        the bot registry
+ *   ~/.ours-telegram/<route>/         one directory per route, each holding
+ *                                     identity.key, state_data.bin, connection.json
+ *
+ * (tg-connector `src/connector.ts:35-42,170-173`, `src/config.ts:39`.)
+ *
+ * WHY THIS IS STATED AS A CONSTANT AND ASSERTED BY A TEST. The connector
+ * distinguishes its identities by walking its own state directory, NOT by asking
+ * the daemon: a daemon's identity list is FLAT and carries no attribution to the
+ * app that created it. So there is no way to reconstruct this registry from the
+ * daemon side, and anything the installer clears here is gone. The installer's
+ * entire business with the connector is three keys in one config file.
+ *
+ * This also keeps the door open for the route migration the owner is considering
+ * — moving each route's packet into the shared daemon. That migration has to read
+ * this registry to know which daemon identity corresponds to which route; an
+ * installer that had trampled it would have destroyed the mapping.
+ */
+export const TG_STATE_DIR_NAME = '.ours-telegram';
+export const TG_REGISTRY_FILES = ['bots.json'];
+export const TG_ROUTE_FILES = ['identity.key', 'state_data.bin', 'connection.json'];
+
+export const tgConfigPath = (home, env = {}) => env.OURS_TG_CONFIG ?? join(home, TG_STATE_DIR_NAME, 'config.json');
+export const coworkConfigPath = (home, env = {}) => env.OURS_COWORK_CONFIG ?? join(home, '.ours-cowork', 'config.json');
+
+// -----------------------------------------------------------------------------
+// §5 — selection
+// -----------------------------------------------------------------------------
+
+/**
+ * Which components this run installs. Defaults are MCP server yes, connector no,
+ * cowork no — the same answers a non-interactive run takes, so
+ * `OURS_ASSUME_YES=1 ours-install` produces a daemon plus the MCP server and
+ * nothing else (spec §9).
+ *
+ * `installed` marks a component already present so the question reads "keep it?"
+ * — and DECLINING AN ALREADY-INSTALLED COMPONENT NEVER UNINSTALLS IT. Removal is
+ * `ours-uninstall`. A "no" here means "do not add", never "take it away".
+ */
+export function planComponentSelection({ answers = {}, installed = {}, assumeYes = false } = {}) {
+  return COMPONENTS.map((component) => {
+    const already = installed[component.key] === true;
+    const answer = assumeYes ? component.default : answers[component.key];
+    const wanted = answer === undefined ? (already || component.default) : answer === true;
+    return {
+      ...component,
+      already,
+      action: already ? (wanted ? 'keep' : 'leave-alone') : (wanted ? 'install' : 'skip'),
+    };
+  });
+}
+
+// -----------------------------------------------------------------------------
+// §5 — the MCP server
+// -----------------------------------------------------------------------------
+
+/**
+ * The MCP server runs per session, not as a daemon: the harness spawns
+ * `ours-mcp proxy` over stdio. No systemd unit is installed for it, and the only
+ * thing written to disk is the harness's MCP registration.
+ *
+ * For a non-default state directory the registration carries
+ * `OURS_CONFIG=<state-dir>/config.json`, so the endpoint and the state directory
+ * travel together — which is what keeps "endpoint given, state directory
+ * defaulted" unreachable. Several harnesses can each point at a different daemon
+ * precisely because the pair lives in each registration.
+ */
+export function planMcpAttachment({ stateDir, isDefaultStateDir, channel = 'latest' }) {
+  const dir = resolve(stateDir);
+  return {
+    key: 'mcp',
+    install: ['npm', 'i', '-g', componentSpec(componentByKey('mcp'), channel)],
+    service: null, // deliberate: per-session stdio proxy, never a unit
+    harnessEnv: isDefaultStateDir ? {} : { OURS_CONFIG: join(dir, 'config.json') },
+    writes: ['the harness MCP registration'],
+  };
+}
+
+// -----------------------------------------------------------------------------
+// §5 / §7 — the Telegram connector
+// -----------------------------------------------------------------------------
+
+/**
+ * Attach the connector to this daemon by setting exactly three keys in its config
+ * file, preserving every other key in it — the file also holds the operator's bot
+ * token and STT settings. If all three already match, the file is not touched.
+ *
+ * Both daemon keys are ALWAYS written together. A half-formed pair is what makes
+ * "endpoint selected, state directory defaulted" reachable downstream, and the
+ * SDK refuses that before it opens a socket.
+ *
+ * Returns `action: 'confirm-repoint'` when the connector is currently attached to
+ * a DIFFERENT daemon. There is exactly one `daemonUrl`/`daemonStateDir` pair and
+ * one unit, so pointing it elsewhere MOVES the connector; it does not add a
+ * second one. That is not something to do silently, and unlike the legacy-unit
+ * case it is not recoverable by re-running: the operator's routes would be
+ * talking to a daemon they did not choose.
+ */
+export function planTgAttachment({ existing, endpoint, stateDir, brokerUrl, assumeYes = false, channel = 'latest' }) {
+  const dir = resolve(stateDir);
+  const base = existing && typeof existing === 'object' && !Array.isArray(existing) ? existing : {};
+  const desired = { daemonUrl: endpoint, daemonStateDir: dir, brokerUrl };
+
+  const current = typeof base.daemonUrl === 'string' || typeof base.daemonStateDir === 'string'
+    ? { daemonUrl: base.daemonUrl ?? null, daemonStateDir: base.daemonStateDir ?? null }
+    : null;
+  const pointsElsewhere = current !== null
+    && (current.daemonStateDir === null || resolve(current.daemonStateDir) !== dir);
+
+  const merged = { ...base };
+  const changes = [];
+  for (const [key, value] of Object.entries(desired)) {
+    if (value === undefined || value === null) continue;
+    if (merged[key] === value) continue;
+    changes.push(key);
+    merged[key] = value;
+  }
+  const plan = {
+    key: 'tg',
+    install: ['npm', 'i', '-g', componentSpec(componentByKey('tg'), channel)],
+    changed: changes.length > 0,
+    changes,
+    config: merged,
+    // Written BEFORE the service: `ours-tg-connector install-service` bakes the
+    // resolved values into the unit as environment, and environment outranks the
+    // config file afterwards.
+    service: ['ours-tg-connector', 'install-service'],
+    untouched: [...TG_REGISTRY_FILES, ...TG_ROUTE_FILES],
+  };
+  if (!pointsElsewhere) return { ...plan, action: plan.changed ? 'attach' : 'unchanged' };
+  const repoint = {
+    ...plan,
+    action: 'confirm-repoint',
+    from: current,
+    to: { daemonUrl: endpoint, daemonStateDir: dir },
+    prompt: `The Telegram connector currently uses ${current.daemonUrl ?? 'an unrecorded daemon'} (${current.daemonStateDir ?? 'unrecorded state directory'}).\nPoint it at ${endpoint} (${dir}) instead? This MOVES the connector; it does not add a second one.`,
+  };
+  // Never repointed without a human, in any mode (spec §9).
+  return assumeYes ? { ...repoint, action: 'skip-repoint', reason: 'never repointed non-interactively' } : repoint;
+}
+
+// -----------------------------------------------------------------------------
+// §5 — cowork
+// -----------------------------------------------------------------------------
+
+/**
+ * Compare an installed version against a floor. Prerelease-aware and CONSERVATIVE
+ * by design: anything unparseable is "too old", because the failure it guards is
+ * handing a daemon block to a build whose config is strict and whose boot is
+ * fail-closed. Being wrong in the cautious direction leaves cowork embedded;
+ * being wrong the other way stops it starting.
+ */
+export function atLeastVersion(actual, floor) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(String(v ?? '').trim());
+    return m ? { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null } : null;
+  };
+  const a = parse(actual);
+  const b = parse(floor);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (a.nums[i] !== b.nums[i]) return a.nums[i] > b.nums[i];
+  }
+  if (a.pre === b.pre) return true;
+  if (a.pre === null) return true; // a release outranks any prerelease of the same version
+  if (b.pre === null) return false;
+  return a.pre >= b.pre;
+}
+
+/**
+ * cowork's external-daemon block. Both halves are required: a half-formed block
+ * is REFUSED rather than written, because cowork's boot is fail-closed.
+ *
+ * The top-level `stateDir` in that file is cowork's OWN private state and is left
+ * alone; only `daemon.stateDir` is the ours daemon's. Confusing the two fails
+ * closed at boot, which is why they are never touched in the same write.
+ */
+export function planCoworkAttachment({ existing, endpoint, stateDir, installedVersion, channel = 'latest' }) {
+  const dir = resolve(stateDir);
+  if (!endpoint || !stateDir) {
+    return { key: 'cowork', action: 'refuse', reason: 'half-formed-block', message: 'a cowork daemon block needs both an endpoint and a state directory; refusing to write half of one' };
+  }
+  if (!atLeastVersion(installedVersion, COWORK_DAEMON_FLOOR)) {
+    return {
+      key: 'cowork',
+      action: 'leave-embedded',
+      reason: 'version-floor',
+      installedVersion: installedVersion ?? null,
+      message: `the installed cowork (${installedVersion ?? 'version unreadable'}) predates ${COWORK_DAEMON_FLOOR}, which is the first build that understands an external-daemon block; leaving cowork embedded`,
+    };
+  }
+  const base = existing && typeof existing === 'object' && !Array.isArray(existing) ? existing : {};
+  const daemon = { mode: 'external', endpoint, stateDir: dir };
+  const unchanged = base.daemon
+    && base.daemon.mode === 'external'
+    && base.daemon.endpoint === endpoint
+    && typeof base.daemon.stateDir === 'string'
+    && resolve(base.daemon.stateDir) === dir;
+  return {
+    key: 'cowork',
+    action: unchanged ? 'unchanged' : 'attach',
+    install: ['npm', 'i', '-g', componentSpec(componentByKey('cowork'), channel)],
+    changed: !unchanged,
+    // The top-level stateDir is cowork's own; it is copied through untouched.
+    config: { ...base, daemon },
+    service: ['ours-cowork', 'install-service'],
+  };
+}
+
+// -----------------------------------------------------------------------------
+// §5 — one component failing does not stop the others
+// -----------------------------------------------------------------------------
+
+/**
+ * A component that fails is reported with its reason and the exact manual
+ * command, and the run continues to the next. The daemon and the
+ * already-installed components stay as they are — a failed component is never a
+ * reason to undo a successful one.
+ */
+export function summarizeComponentRun(results) {
+  return {
+    installed: results.filter((r) => r.state === 'installed').map((r) => r.key),
+    failed: results.filter((r) => r.state === 'failed').map((r) => ({ key: r.key, reason: r.reason, retry: r.retry ?? null })),
+    skipped: results.filter((r) => r.state === 'skipped').map((r) => r.key),
+    continued: true,
+  };
+}

package/lib/effects.mjs

@@ -0,0 +1,331 @@
+// 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';
+
+/** 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 state directory on this machine that still has a daemon config.
+ *
+ * `ours-uninstall` asks this exactly once, to answer one question: are the
+ * GLOBAL packages still needed by somebody else? Getting it wrong the optimistic
+ * way (reporting none) uninstalls the CLI out from under a second daemon that is
+ * still running, so the search is deliberately conservative — it looks only where
+ * a state directory can actually be, and an unreadable home means "there might be
+ * others", not "there are none".
+ *
+ * Where they can be: the default `~/.ours`, plus any `~/.ours*` sibling, which is
+ * the shape every other part of this installer uses for a second daemon. A state
+ * directory somewhere else entirely will not be found, and that is a KNOWN limit
+ * rather than a claim — the failure is keeping a global package that could have
+ * been removed, which is the harmless direction.
+ */
+function knownStateDirsIn(home) {
+  const found = [];
+  const consider = (dir) => { if (existsSync(join(dir, 'config.json'))) 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 };
+
+// -----------------------------------------------------------------------------
+// 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');