@ours.network/install 0.11.0

package/install.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# ours.network — unified stack installer bootstrap (the `ours-install` experience).
+#
+# PREFERRED install is npm (persistent, versioned, integrity-checked command on PATH):
+#     npm i -g @ours.network/install && ours-install     # then re-run any time with: ours-install
+#     npx @ours.network/install                          # one-off, no global install
+#
+# This curl|bash bootstrap is the FALLBACK for machines without npm set up (least secure — it
+# pipes a script into your shell). It just gets Node.js/npm sorted, then does the same
+# `npm i -g @ours.network/install` and runs `ours-install`. Meant to be run as:
+#
+#     curl -fsSL https://raw.githubusercontent.com/adapt-toolkit/ours-mcp/main/packages/installer/install.sh | bash
+#
+# This file is a THIN bootstrap: it checks that Node.js + npm are present (and prints friendly,
+# per-OS guidance if not), then runs the real experience — the Node installer (install.mjs) that
+# guides the WHOLE stack in ~3 minutes: pre-flight (platform / node / harness alias-safety),
+# config-first (broker + port), then four consent-gated steps — ours core (the daemon), the harness
+# plugins (Claude Code + Codex), ours-fleet, and the Telegram connector — ending in ONE copy-paste
+# hand-off prompt. All the real work lives in the Node installer.
+#
+# From a CLONE (a sibling install.mjs is present) it runs that directly. Piped as `curl … | bash`
+# it installs the published command globally — `npm i -g @ours.network/install` — then runs
+# `ours-install`. Idempotent: a re-run updates to @latest and runs again.
+#
+# Non-interactive env overrides (all optional) — consumed by the Node installer:
+#   OURS_ASSUME_YES=1                        accept every default; never prompt (no tty needed)
+#   OURS_INSTALL_DRY_RUN=1                   walk the whole flow WITHOUT installing/changing anything
+#                                            (prints exactly what it WOULD do — safe on any machine)
+#   OURS_NPM="npm"                           npm binary to use
+#   OURS_CONFIG=/path/config.json            daemon config file (default ~/.ours/config.json)
+#   OURS_INSTALLER_MJS=/path/install.mjs     run this Node installer directly (dev/testing)
+#   OURS_INSTALL_PKG=@ours.network/install   the package to install for the command (override for dev)
+set -euo pipefail
+
+say(){ printf 'ours: %s\n' "$1"; }
+PKG="${OURS_INSTALL_PKG:-@ours.network/install}"
+NPM_BIN="${OURS_NPM:-npm}"
+
+# --- 1) Node.js + npm check + friendly guidance ------------------------------------------------
+# The installer needs Node.js ≥ 20 (and npm to fetch the command). If missing, don't fail
+# cryptically: explain what Node is and how to get it for this OS, point at nodejs.org, and exit
+# cleanly (0) so a piped run ends gracefully rather than with a scary non-zero error.
+if ! command -v node >/dev/null 2>&1 || ! command -v "$NPM_BIN" >/dev/null 2>&1; then
+  os="$(uname -s 2>/dev/null || echo unknown)"
+  printf '\n'
+  say "ours needs Node.js (version 20 or newer, which includes npm) — it isn't installed yet."
+  say "Node.js is a common, free runtime; here's how to get it:"
+  case "$os" in
+    Darwin)
+      say "  • macOS (Homebrew):  brew install node"
+      say "  • or nvm:            https://github.com/nvm-sh/nvm  then  nvm install --lts" ;;
+    Linux)
+      say "  • Debian/Ubuntu:     https://github.com/nodesource/distributions  (NodeSource)"
+      say "  • or nvm:            https://github.com/nvm-sh/nvm  then  nvm install --lts" ;;
+    *)
+      say "  • Windows/WSL:       install Node.js in WSL, or from https://nodejs.org" ;;
+  esac
+  say "  • Or download the installer for any OS: https://nodejs.org"
+  say "Once Node.js is installed, re-run this command and you're set."
+  printf '\n'
+  exit 0
+fi
+
+# --- 2) DEV / LOCAL path: run the sibling install.mjs directly ---------------------------------
+# From a clone (or an explicit OURS_INSTALLER_MJS), skip npm entirely and run the local installer.
+MJS=""
+if [ -n "${OURS_INSTALLER_MJS:-}" ] && [ -f "${OURS_INSTALLER_MJS}" ]; then
+  MJS="${OURS_INSTALLER_MJS}"
+else
+  SELF="${BASH_SOURCE[0]:-$0}"
+  DIR="$(cd "$(dirname "$SELF")" 2>/dev/null && pwd || true)"
+  [ -n "$DIR" ] && [ -f "$DIR/install.mjs" ] && MJS="$DIR/install.mjs"
+fi
+if [ -n "$MJS" ]; then
+  exec node "$MJS" "$@"
+fi
+
+# --- 3) PIPED path (curl … | bash): install the command globally, then run it ------------------
+# Canonical entry: install (or update) @ours.network/install, then invoke `ours-install`.
+# Idempotent — a re-run updates to @latest and runs again.
+say "installing the ours installer ($PKG)…"
+if ! "$NPM_BIN" i -g "${PKG}@latest" >/dev/null 2>&1; then
+  say "couldn't install $PKG from npm. Check your connection (and npm permissions), then retry:"
+  say "    $NPM_BIN i -g $PKG   &&   ours-install"
+  exit 1
+fi
+if ! command -v ours-install >/dev/null 2>&1; then
+  say "installed $PKG but 'ours-install' isn't on your PATH. Add your npm global bin to PATH, then run: ours-install"
+  say "    (npm bin -g  shows the directory to add)"
+  exit 1
+fi
+exec ours-install "$@"

package/lib/logic.mjs

@@ -0,0 +1,192 @@
+// Pure, dependency-free logic for the ours.network installer — everything here is a plain
+// function with no I/O so it can be unit-tested directly (no subprocess, no tty). The install.mjs
+// orchestrator wires these to real npm/ours-mcp/tty calls; the integration tests drive that via
+// install.sh. Keeping the decisions here means the tricky bits (harness canon, port-conflict,
+// config merge, version parsing) are covered by fast, hermetic tests.
+
+// canonHarnesses: normalize a free-form selection (numbers, names, or "all") into canonical
+// harness names, de-duped, order-preserving. Faithful port of install.sh's canon_harnesses.
+// Returns { names: string[], unknown: string[] } — unknown tokens are reported, not fatal.
+export function canonHarnesses(raw) {
+  const names = [];
+  const unknown = [];
+  const push = (n) => { if (!names.includes(n)) names.push(n); };
+  const toks = String(raw || '').toLowerCase().replace(/,/g, ' ').split(/\s+/).filter(Boolean);
+  for (const tok of toks) {
+    switch (tok) {
+      case 'all': case 'a':
+        return { names: ['claude-code', 'codex', 'hermes'], unknown };
+      case '1': case 'claude-code': case 'claude': case 'cc': push('claude-code'); break;
+      case '2': case 'codex': push('codex'); break;
+      case '3': case 'hermes': push('hermes'); break;
+      case 'none': case 'skip': case '0': break;
+      default: unknown.push(tok);
+    }
+  }
+  return { names, unknown };
+}
+
+// The Telegram connector owns 3051 — the installer must never hand a daemon that port.
+export const RESERVED_PORTS = [3051];
+export const DEFAULT_PORT = 3050;
+export const DEFAULT_BROKER = 'wss://broker1.ours.network';
+
+// suggestPort: pick a usable HTTP port. If `desired` is free and not reserved, keep it. Otherwise
+// scan upward from 3060 (the brief's suggested alternate band) for the first free, non-reserved
+// port. `isTaken(port)` is injected so this stays pure and testable (real caller probes a bind).
+export function suggestPort(desired, isTaken, { reserved = RESERVED_PORTS, floor = 3060 } = {}) {
+  const taken = (p) => reserved.includes(p) || isTaken(p);
+  if (!taken(desired)) return desired;
+  for (let p = Math.max(floor, desired + 1); p < desired + 1000; p++) {
+    if (!taken(p)) return p;
+  }
+  return desired; // exhausted — let the caller surface it; never silently loop forever
+}
+
+// A port string is valid if it's an integer in the ephemeral-safe user range.
+export function parsePort(input, fallback = DEFAULT_PORT) {
+  const n = Number.parseInt(String(input).trim(), 10);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) return { ok: false, port: fallback };
+  return { ok: true, port: n };
+}
+
+// Basic sanity for a broker address: must look like a ws:// or wss:// URL. Empty → keep default
+// (handled by caller). We don't hard-fail on odd input, just report so the caller can warn.
+export function validateBroker(input) {
+  const s = String(input).trim();
+  if (!s) return { ok: true, value: '', empty: true };
+  const ok = /^wss?:\/\/[^\s]+$/i.test(s);
+  return { ok, value: s, empty: false };
+}
+
+// mergeConfig: take the existing parsed config.json object and a patch of only the keys the user
+// changed, returning the pretty-printed strict-JSON text to write (stable key handling, trailing
+// newline). Never drops unrelated keys the daemon or user added.
+export function mergeConfig(existing, patch) {
+  const base = existing && typeof existing === 'object' ? existing : {};
+  const out = { ...base };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === undefined) continue;
+    out[k] = v;
+  }
+  return JSON.stringify(out, null, 2) + '\n';
+}
+
+// parseVersion: pull the first x.y.z out of a version string (e.g. `ours-mcp v0.9.9`), matching
+// install.sh's `grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1`. Returns '' when none is present.
+export function parseVersion(text) {
+  const m = String(text || '').match(/[0-9]+\.[0-9]+\.[0-9]+/);
+  return m ? m[0] : '';
+}
+
+// parseStatus: read the daemon's RESOLVED broker + port out of `ours-mcp status` output, so we
+// prompt with what the daemon is actually using rather than a hardcoded guess. Returns
+// { broker, port } with either field null when the line isn't present (daemon stopped / older
+// build). Lines look like:  "  broker: wss://broker1.ours.network"  and
+// "  url:    http://localhost:3050/mcp (reachable)".
+export function parseStatus(text) {
+  const s = String(text || '');
+  const bm = s.match(/^\s*broker:\s*(\S+)/m);
+  const pm = s.match(/url:\s*https?:\/\/[^:\s/]+:(\d+)/i);
+  return {
+    broker: bm ? bm[1] : null,
+    port: pm ? Number.parseInt(pm[1], 10) : null,
+  };
+}
+
+// ===============================================================================================
+// v2 unified-installer logic (all pure — the orchestrator injects the real probe/uname/env).
+// ===============================================================================================
+
+// detectPlatform: classify the host from process.platform + the kernel release string + env.
+// - darwin              → macOS  (supported)
+// - linux + microsoft/WSL in release, or WSL_* env  → WSL  (supported)
+// - linux               → Linux  (supported)
+// - win32               → Windows (NOT supported in v1 — the caller prints a WSL pointer + exits)
+// - anything else       → unknown (unsupported)
+// Returns { os, label, supported }.
+export function detectPlatform({ platform, release = '', env = {} } = {}) {
+  const rel = String(release).toLowerCase();
+  const isWsl = !!(env.WSL_DISTRO_NAME || env.WSL_INTEROP) || /microsoft|wsl/.test(rel);
+  switch (platform) {
+    case 'darwin': return { os: 'macos', label: 'macOS', supported: true };
+    case 'linux':
+      return isWsl
+        ? { os: 'wsl', label: 'Windows (WSL)', supported: true }
+        : { os: 'linux', label: 'Linux', supported: true };
+    case 'win32': return { os: 'windows', label: 'Windows (native)', supported: false };
+    default: return { os: 'unknown', label: platform || 'unknown', supported: false };
+  }
+}
+
+// classifyHarnessProbe: turn what we observed about a harness command into a safety verdict,
+// WITHOUT ever having called it unsafely. Inputs (all gathered by the orchestrator):
+//   onPath      — `command -v <name>` found an executable on PATH
+//   versionOk   — a non-interactive `<name> --version` returned 0 promptly with sane output
+//   timedOut    — that probe had to be killed (an interactive/hanging wrapper — NEVER call it)
+//   shellType   — `type -t <name>` in the user's shell: 'alias' | 'function' | 'file' | ''
+// Verdict.status:
+//   'ok'      — a real binary that answers --version → safe to drive
+//   'alias'   — shadowed by a shell alias/function (or a wrapper that hangs) → do NOT call it,
+//               tell the user plainly + how to fix, and ALWAYS still offer a manual path
+//   'unsafe'  — on PATH but the probe failed/looked wrong → don't auto-drive; offer manual path
+//   'absent'  — genuinely not installed → this harness is skipped (with a note)
+// The golden rule (owner edit #3): 'alias'/'unsafe'/'absent' NEVER dead-end — the caller always
+// prints a manual-install path so the component still gets installed.
+export function classifyHarnessProbe({ onPath, versionOk, timedOut, shellType = '' } = {}) {
+  if (versionOk) return { status: 'ok', detail: 'real program' };
+  if (timedOut) return { status: 'alias', detail: 'a wrapper that did not answer --version' };
+  const t = String(shellType).toLowerCase();
+  if (t === 'alias' || t === 'function') {
+    return { status: 'alias', detail: `a shell ${t}, not the real command` };
+  }
+  if (onPath) return { status: 'unsafe', detail: 'found, but did not answer --version' };
+  return { status: 'absent', detail: 'not installed' };
+}
+
+// harnessAvailable: a harness we can safely DRIVE headlessly right now.
+export function harnessAvailable(status) { return status === 'ok'; }
+
+// buildHandoffPrompt: the literal copy-paste hand-off text (delta #1861). Steps for components
+// that were NOT installed drop out and the remaining steps renumber, so the user never sees an
+// instruction for a piece they don't have. The human identity is normally created DURING install,
+// so its step is included ONLY as a fallback (identity: true) when in-install creation was skipped
+// or failed. Returns { text, empty } — empty is true when there is nothing left to finish.
+export function buildHandoffPrompt({ identity = false, fleet = false, telegram = false } = {}) {
+  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 ours-fleet: confirm it's ready and show me how to spawn a\n" +
+      '   temporary agent, then spawn one so I can see it.',
+    );
+  }
+  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 numbered = steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
+  const text =
+    '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 };
+}
+
+// summarizeComponent: normalize one component's outcome into a summary row the final screen and
+// the report share. state ∈ 'installed'|'skipped'|'failed'|'current'. Pure formatting only.
+export function summarizeComponent({ key, label, state, version = '', note = '' }) {
+  const mark = state === 'failed' ? '✗' : state === 'skipped' ? '·' : '✓';
+  return { key, label, state, version, note, mark };
+}

package/lib/prompt.mjs

@@ -0,0 +1,139 @@
+// Interactive prompts drawn on the controlling terminal (/dev/tty), so they work under
+// `curl | bash` (where stdin/stdout are the pipe). Synchronous, dependency-free: line prompts via
+// fs.readSync, and a raw-mode checkbox multi-select. When there is no tty or OURS_ASSUME_YES is
+// set, every prompt returns its default without reading — the headless/CI path never blocks.
+import { readSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { c } from './ui.mjs';
+
+const ASSUME_YES = () => !!process.env.OURS_ASSUME_YES;
+
+// A Ctrl+C at any prompt must abort cleanly — never the old "^C^C^C… and keeps going" bug. Two
+// things conspire: (1) the process must have a SIGINT handler (installed by the orchestrator) so
+// Node doesn't just hard-kill, and (2) that handler can't run while a synchronous fs.readSync
+// blocks the event loop. So readByte turns an interrupted read (EINTR) — and a literal Ctrl+C byte
+// 0x03, in case the tty's signal generation is off — into this sentinel error, which unwinds the
+// blocked read; the orchestrator catches it (or its own SIGINT handler fires) and exits(130).
+export class InstallCancelled extends Error {
+  constructor() { super('SIGINT'); this.code = 'OURS_SIGINT'; }
+}
+export const isCancel = (e) => !!e && e.code === 'OURS_SIGINT';
+
+// Read raw bytes one at a time from the tty fd. Returns the byte (0-255) or null at EOF/error.
+function readByte(fd) {
+  const buf = Buffer.alloc(1);
+  try {
+    const n = readSync(fd, buf, 0, 1, null);
+    return n === 1 ? buf[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+// askLine: print `prompt` and read a line. We read in RAW mode with signal generation OFF (stty
+// -icanon -echo -isig) so Ctrl+C arrives as the byte 0x03 that we turn into a clean InstallCancelled
+// — rather than a SIGINT that a blocked synchronous readSync would defer forever (the old
+// "^C^C^C… and keeps going" bug). We echo/backspace ourselves since -echo is off. If stty isn't
+// available (not a real tty), fall back to a plain cooked read. Throws InstallCancelled on Ctrl+C.
+export function askLine(write, fd, prompt, def = '') {
+  if (fd == null || ASSUME_YES()) return def;
+  write(prompt);
+
+  const saved = spawnSync('stty', ['-g'], { stdio: [fd, 'pipe', 'ignore'], encoding: 'utf8' });
+  const rawOk = saved.status === 0
+    && spawnSync('stty', ['-icanon', '-echo', '-isig', 'min', '1', 'time', '0'], { stdio: [fd, 'ignore', 'ignore'] }).status === 0;
+  const restore = () => { if (rawOk) spawnSync('stty', (saved.stdout || '').trim() ? [(saved.stdout || '').trim()] : ['sane'], { stdio: [fd, 'ignore', 'ignore'] }); };
+
+  let s = '';
+  try {
+    for (;;) {
+      const b = readByte(fd);
+      if (b === null || b === 0x04) break;               // EOF / Ctrl+D → take the default
+      if (b === 0x03) { restore(); write('^C'); throw new InstallCancelled(); } // Ctrl+C
+      if (b === 0x0a || b === 0x0d) { if (rawOk) write('\n'); break; }          // Enter
+      if (b === 0x7f || b === 0x08) { if (s.length) { s = s.slice(0, -1); if (rawOk) write('\b \b'); } continue; } // backspace
+      if (b < 0x20) continue;                            // ignore other control bytes
+      s += String.fromCharCode(b);
+      if (rawOk) write(String.fromCharCode(b));           // manual echo
+    }
+  } finally {
+    restore();
+  }
+  const ans = s.trim();
+  return ans === '' ? def : ans;
+}
+
+// askYesNo: y/n with a default shown in caps. Returns boolean.
+export function askYesNo(write, fd, prompt, def = false) {
+  if (fd == null || ASSUME_YES()) return def;
+  const hint = def ? '[Y/n]' : '[y/N]';
+  const ans = askLine(write, fd, `${prompt} ${hint} `, def ? 'y' : 'n');
+  return /^y/i.test(ans);
+}
+
+// checkboxSelect: raw-mode multi-select drawn on the tty. ↑/↓ (or k/j) move, Space toggles, Enter
+// confirms, a/n = all/none, q cancels (selects nothing). Returns the selected names in order.
+// `specs` are { name, label } (optionally { checked }). No-tty → returns pre-checked defaults.
+export function checkboxSelect(write, fd, specs, { title } = {}) {
+  const names = specs.map((s) => s.name);
+  const labels = specs.map((s) => s.label);
+  const sel = specs.map((s) => (s.checked ? 1 : 0));
+  const n = specs.length;
+  const chosen = () => names.filter((_, i) => sel[i] === 1);
+
+  if (fd == null) return chosen();
+
+  // Enter raw mode via `stty` on the tty fd (NOT tty.ReadStream.setRawMode, which would flip the
+  // fd to non-blocking and break our fs.readSync). Save the current settings and restore them
+  // after. If stty is unavailable / this isn't a real tty, fall back to the pre-checked defaults.
+  const saved = spawnSync('stty', ['-g'], { stdio: [fd, 'pipe', 'ignore'], encoding: 'utf8' });
+  if (saved.status !== 0) return chosen();
+  const savedMode = (saved.stdout || '').trim();
+  const setRaw = spawnSync('stty', ['-echo', '-icanon', 'min', '1', 'time', '0'], { stdio: [fd, 'ignore', 'ignore'] });
+  if (setRaw.status !== 0) return chosen();
+  const restore = () => spawnSync('stty', savedMode ? [savedMode] : ['sane'], { stdio: [fd, 'ignore', 'ignore'] });
+
+  let cur = 0;
+  let drawn = 0;
+
+  const redraw = () => {
+    if (drawn) write(`\x1b[${n}A`); // rewind over the previous frame
+    drawn = 1;
+    for (let i = 0; i < n; i++) {
+      const box = sel[i] ? c.green('[x]') : '[ ]';
+      const point = i === cur ? c.cyan('> ') : '  ';
+      write(`\r\x1b[K  ${point}${box} ${labels[i]}\n`);
+    }
+  };
+
+  write(`  ${title || 'Choose — ' + c.bold('↑/↓') + ' move, ' + c.bold('Space') + ' toggle, ' + c.bold('Enter') + ' confirm (a=all, n=none)'}:\n`);
+  redraw();
+
+  loop: for (;;) {
+    const b = readByte(fd);
+    if (b === null) break;
+    switch (b) {
+      case 0x1b: { // ESC — arrow key sequence \x1b [ A/B
+        const b1 = readByte(fd);
+        if (b1 === 0x5b || b1 === 0x4f) { // '[' or 'O'
+          const b2 = readByte(fd);
+          if (b2 === 0x41) cur = (cur - 1 + n) % n; // up
+          else if (b2 === 0x42) cur = (cur + 1) % n; // down
+        }
+        break;
+      }
+      case 0x6b: case 0x4b: cur = (cur - 1 + n) % n; break; // k/K
+      case 0x6a: case 0x4a: cur = (cur + 1) % n; break;     // j/J
+      case 0x20: sel[cur] = 1 - sel[cur]; break;            // space
+      case 0x61: case 0x41: for (let i = 0; i < n; i++) sel[i] = 1; break; // a/A
+      case 0x6e: case 0x4e: for (let i = 0; i < n; i++) sel[i] = 0; break; // n/N
+      case 0x71: case 0x51: for (let i = 0; i < n; i++) sel[i] = 0; break loop; // q/Q cancel
+      case 0x0d: case 0x0a: break loop; // enter
+      default: break;
+    }
+    redraw();
+  }
+
+  restore();
+  return chosen();
+}

package/lib/ui.mjs

@@ -0,0 +1,126 @@
+// Shared UI toolkit for the ours.network Node installer + uninstaller: colors that degrade
+// gracefully, the ASCII banner, and /dev/tty-aware prompts (so `curl | bash` still works and
+// true-headless runs fall back to env vars). No dependencies — pure Node, ESM.
+import { openSync, closeSync, writeSync } from 'node:fs';
+
+// --- colors -----------------------------------------------------------------------------------
+// Enabled only for a real terminal and when NO_COLOR is unset (https://no-color.org). Everything
+// routes through c()/style helpers so a no-color run is plain ASCII, never raw escape codes.
+const COLOR = !process.env.NO_COLOR && (process.env.OURS_FORCE_COLOR === '1' || process.stdout.isTTY);
+const E = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  cyan: '\x1b[36m', green: '\x1b[32m', yellow: '\x1b[33m',
+  red: '\x1b[31m', blue: '\x1b[34m', magenta: '\x1b[35m', gray: '\x1b[90m',
+};
+function wrap(code, s) { return COLOR ? code + s + E.reset : String(s); }
+export const c = {
+  bold: (s) => wrap(E.bold, s), dim: (s) => wrap(E.dim, s), gray: (s) => wrap(E.gray, s),
+  cyan: (s) => wrap(E.cyan, s), green: (s) => wrap(E.green, s), yellow: (s) => wrap(E.yellow, s),
+  red: (s) => wrap(E.red, s), blue: (s) => wrap(E.blue, s), magenta: (s) => wrap(E.magenta, s),
+};
+
+// The theme's gradient ramp (256-color cyan → blue → violet), one shade per banner row. Plain
+// text under NO_COLOR — same degrade contract as c.*.
+const GRAD = [51, 45, 39, 33, 63, 99];
+const grad = (s, i) => (COLOR ? `\x1b[38;5;${GRAD[Math.min(i, GRAD.length - 1)]}m${s}\x1b[0m` : String(s));
+
+// --- banner -----------------------------------------------------------------------------------
+// The block-letter "ours" logo with a top-to-bottom gradient, the wordmark, a mesh accent and
+// the website tagline. Straight monospace blocks (no slanted ASCII art — that reads crooked),
+// kept well under 80 columns so it never wraps on a default terminal. Plain under NO_COLOR.
+export function banner() {
+  const logo = [
+    ' ██████  ██    ██ ██████  ███████',
+    '██    ██ ██    ██ ██   ██ ██     ',
+    '██    ██ ██    ██ ██████  ███████',
+    '██    ██ ██    ██ ██   ██      ██',
+    ' ██████   ██████  ██   ██ ███████',
+  ];
+  const dot = c.gray('·');
+  const mesh = `${c.cyan('◇')}${dot}${c.cyan('◇')}${dot}${c.cyan('◇')}`;
+  const out = [];
+  out.push('');
+  logo.forEach((l, i) => out.push('  ' + grad(l, i)));
+  out.push('');
+  out.push('  ' + c.bold(c.cyan('ours')) + c.gray('.network') + '   ' + mesh);
+  out.push('  ' + c.dim('The space where humans and AI agents collaborate'));
+  out.push('');
+  return out.join('\n');
+}
+
+// --- section + status helpers -----------------------------------------------------------------
+// Sections read as ruled chapter headers: `── 3 · broker address ────────…` (fixed overall
+// width so the rules line up down the whole run).
+const SECTION_WIDTH = 64;
+export function section(n, title) {
+  const rule = '─'.repeat(Math.max(2, SECTION_WIDTH - `── ${n} · ${title} `.length));
+  return '\n' + c.cyan('──') + ' ' + c.bold(c.cyan(String(n))) + c.gray(' · ') + c.bold(title) + ' ' + c.gray(rule);
+}
+export function heading(title) { return '\n' + c.bold(c.cyan('◆ ' + title)); }
+export const ok = (s) => `  ${c.green('✓')} ${s}`;
+export const step = (s) => `  ${c.dim('…')} ${s}`;
+export const info = (s) => `  ${c.gray('•')} ${s}`;
+export const warn = (s) => `  ${c.yellow('!')} ${s}`;
+export const why = (s) => `    ${c.gray('why: ' + s)}`;
+
+// --- framed panel -------------------------------------------------------------------------------
+// A boxed block for the one moment that must stand out (the post-first-install next steps).
+// Content lines must be PLAIN strings (no ANSI) so the width math stays honest — only the frame
+// is coloured, which degrades to plain box-drawing under NO_COLOR.
+export function box(lines, title = '') {
+  const inner = Math.max(...lines.map((l) => l.length), title.length + 2) + 2;
+  const bar = (s) => c.cyan(s);
+  const top = title
+    ? bar('┌─') + ' ' + c.bold(title) + ' ' + bar('─'.repeat(inner - title.length - 3) + '┐')
+    : bar('┌' + '─'.repeat(inner) + '┐');
+  const row = (l) => bar('│') + ' ' + l + ' '.repeat(inner - l.length - 1) + bar('│');
+  const bottom = bar('└' + '─'.repeat(inner) + '┘');
+  return [top, ...lines.map(row), bottom].map((l) => '  ' + l).join('\n');
+}
+
+// --- spinner ------------------------------------------------------------------------------------
+// Animate a braille spinner next to `label` while the (async) thunk runs, then clear the line so
+// the caller prints the real ✓/! outcome. Animation only on a real color tty — a piped or
+// NO_COLOR run gets one static `… label` line instead, so logs and tests stay clean.
+export async function withSpinner(label, thunk) {
+  const animate = COLOR && !!process.stdout.isTTY;
+  if (!animate) {
+    process.stdout.write(`  … ${label}\n`);
+    return thunk();
+  }
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  const draw = () => process.stdout.write(`\r\x1b[K  ${c.cyan(frames[i = (i + 1) % frames.length])} ${label}`);
+  draw();
+  const timer = setInterval(draw, 80);
+  try {
+    return await thunk();
+  } finally {
+    clearInterval(timer);
+    process.stdout.write('\r\x1b[K');
+  }
+}
+
+// --- /dev/tty-aware prompting ------------------------------------------------------------------
+// Probe by OPENING /dev/tty read-write: the device node is world-rw, so a permission check passes
+// even with no controlling terminal (headless/CI). open() fails (ENXIO) when there is genuinely no
+// terminal — only then do we truly have no tty. Mirrors install.sh's bash probe exactly.
+export function openTty() {
+  try {
+    const fd = openSync('/dev/tty', 'r+');
+    return fd;
+  } catch {
+    return null;
+  }
+}
+
+// Write to the tty (falls back to stdout if no tty fd). Used for prompts drawn on the controlling
+// terminal so they survive `curl | bash` (where stdout may be the far end of a pipe). We use a
+// blocking fs.writeSync — NOT a tty.WriteStream — because wrapping the fd in a tty stream flips it
+// to non-blocking, which would make our fs.readSync-based prompt reads throw EAGAIN.
+export function makeWriter(ttyFd) {
+  if (ttyFd == null) return (s) => process.stdout.write(s);
+  return (s) => { try { writeSync(ttyFd, s); } catch { /* ignore */ } };
+}
+
+export { closeSync };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ours.network/install",
+  "version": "0.11.0",
+  "private": false,
+  "description": "The unified ours.network stack installer (ours-install): one guided ~3-minute flow for ours core (the daemon) + the harness plugins (Claude Code / Codex) + ours-fleet + the Telegram connector, then a single copy-paste hand-off prompt. Self-contained (Node built-ins only); run as `ours-install` or via curl|bash (install.sh).",
+  "type": "module",
+  "bin": {
+    "ours-install": "install.mjs"
+  },
+  "files": [
+    "install.mjs",
+    "install.sh",
+    "lib",
+    "uninstall.mjs",
+    "uninstall.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "Adapt Toolkit",
+  "homepage": "https://github.com/adapt-toolkit/ours-mcp/tree/main/packages/installer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adapt-toolkit/ours-mcp.git",
+    "directory": "packages/installer"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}