@ours.network/install 0.18.0-nightly.5 → 1.0.0

package/README.md

@@ -9,6 +9,21 @@ npm install --global @ours.network/install
 ours-install
 ```
 
+### Stable and nightly channels
+
+Installing `@ours.network/install@latest` selects the stable channel; installing
+`@ours.network/install@nightly` selects the nightly channel. Before changing the
+machine, the installer resolves `@ours.network/mcp`,
+`@ours.network/claude-code`, and `@ours.network/codex`, verifies that their
+selected dist-tags expose one exact lockstep version, and fails closed if they
+do not. MCP and the Codex launcher are installed by exact version, and local
+Claude Code and Codex marketplace manifests pin the corresponding plugin
+packages to that same version.
+
+`OURS_CHANNEL=latest|nightly` (or the legacy `OURS_INSTALL_CHANNEL`) remains an
+explicit override. Without an override, the installed package's own version
+selects the channel.
+
 The normal flow uses one daemon at `~/.ours` on port 3050, shows an eight-stage
 progress bar, and asks only for information it cannot safely infer (normally the
 Human identity's display name). Existing daemon conflicts and moving a Telegram
@@ -75,8 +90,11 @@ new Human identity and asks no ordinary setup questions, but it never bypasses
 selection conflicts, connector moves, or destructive safeguards.
 
 A non-default daemon must be selected coherently with a config file or matching
-port and state directory. Harnesses and the generated Fleet role receive that
-selection through `OURS_CONFIG`; there is no per-application daemon.
+port and state directory. Hermes and the generated Fleet role persist that
+selection through `OURS_CONFIG`. Claude Code and Codex plugin registrations
+cannot store an environment value; for those harnesses the installer prints the
+exact `export OURS_CONFIG=...` line that must be added to the shell profile
+before starting the harness. There is no per-application daemon.
 
 ## Uninstall
 

package/install.sh

@@ -21,6 +21,9 @@
 # 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.
+# The bootstrap is deliberately stable. For nightly, install the published nightly command
+# directly: `npm i -g @ours.network/install@nightly && ours-install`; that package's own
+# X.Y.Z-nightly.N version selects and exactly resolves the matching stack channel.
 #
 # Non-interactive env overrides (all optional) — consumed by the Node installer:
 #   OURS_ASSUME_YES=1                        accept every default; never prompt (no tty needed)

package/lib/components.mjs

@@ -1,7 +1,7 @@
 // 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).
+// Component selection and attachment planning. Repoint decisions stay beside
+// attachment decisions so an existing connector can never move silently.
 // Pure, like target.mjs and plan.mjs: the caller injects the current file
 // contents and the installed versions, and every function returns a plan.
 //
@@ -101,7 +101,7 @@ export const tgConfigPath = (home, env = {}) => env.OURS_TG_CONFIG ?? join(home,
 export const coworkConfigPath = (home, env = {}) => env.OURS_COWORK_CONFIG ?? join(home, '.ours-cowork', 'config.json');
 
 // -----------------------------------------------------------------------------
-// §5 — selection
+// Component selection
 // -----------------------------------------------------------------------------
 
 /**
@@ -133,7 +133,7 @@ export function planComponentSelection({ answers = {}, installed = {}, assumeYes
 }
 
 // -----------------------------------------------------------------------------
-// §5 — the MCP server
+// MCP server attachment
 // -----------------------------------------------------------------------------
 
 /**
@@ -159,7 +159,7 @@ export function planMcpAttachment({ stateDir, isDefaultStateDir, channel = 'late
 }
 
 // -----------------------------------------------------------------------------
-// §5 / §7 — the Telegram connector
+// Telegram connector attachment and repointing
 // -----------------------------------------------------------------------------
 
 /**
@@ -217,12 +217,12 @@ export function planTgAttachment({ existing, endpoint, stateDir, brokerUrl, assu
     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).
+  // Never repoint an existing connector without a human, in any mode.
   return assumeYes ? { ...repoint, action: 'skip-repoint', reason: 'never repointed non-interactively' } : repoint;
 }
 
 // -----------------------------------------------------------------------------
-// §5 — cowork
+// cowork attachment
 // -----------------------------------------------------------------------------
 
 /**
@@ -341,7 +341,7 @@ export function planCoworkAttachment({ existing, endpoint, stateDir, installedVe
 }
 
 // -----------------------------------------------------------------------------
-// §5 — one component failing does not stop the others
+// Component failures are isolated so the remaining components can continue.
 // -----------------------------------------------------------------------------
 
 /**

package/lib/detect.mjs

@@ -1,7 +1,7 @@
 // ours-install v3 — which daemons are already on this machine, and which one this
 // run is for.
 //
-// Never ask for a state directory or a port to be TYPED (spec §2). When several
+// Never ask for a state directory or port to be typed. When several
 // daemons are DETECTED, show them and let one be picked: selecting from what was
 // found is not prompting for a path.
 //
@@ -91,7 +91,7 @@ export function detectDaemons({ candidates = [], exists, readJson }) {
 /**
  * A state directory for a daemon this run would CREATE, derived and never typed.
  *
- * Spec §2 forbids asking for a path, so "create a new one" has to derive somewhere
+ * The UI does not ask for a path, so "create a new one" has to derive somewhere
  * to put it: `~/.ours` when free, else the first free `~/.ours-2`, `~/.ours-3`…
  * An operator who wants a specific path still has `--state-dir`, which bypasses
  * this screen entirely.
@@ -151,7 +151,7 @@ export function planDaemonSelection({
  *
  * Deliberately strict: an answer that is not a number in range, or the create
  * option, is NOT a state directory to be interpreted. Accepting free text here
- * would be exactly the "type a path" prompt spec §2 forbids, arriving through the
+ * would reintroduce the forbidden "type a path" prompt through the
  * back door.
  */
 export function resolveSelection(answer, { candidates = [], createOption = null } = {}) {

package/lib/effects.mjs

@@ -69,9 +69,9 @@ function readTextFile(path) {
   }
 }
 
-function installedVersionOf(pkg) {
+function installedVersionOf(pkg, npmBin = 'npm') {
   try {
-    const out = execFileSync('npm', ['ls', '-g', '--depth', '0', '--json', pkg], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const out = execFileSync(npmBin, ['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.
@@ -79,8 +79,8 @@ function installedVersionOf(pkg) {
   }
 }
 
-function packageDependenciesOf(pkgSpec) {
-  const probe = capture('npm', ['view', pkgSpec, 'dependencies', '--json'], { timeout: 15_000 });
+function packageDependenciesOf(pkgSpec, npmBin = 'npm') {
+  const probe = capture(npmBin, ['view', pkgSpec, 'dependencies', '--json'], { timeout: 15_000 });
   if (!probe.ok) return null;
   try {
     const parsed = JSON.parse(probe.stdout);
@@ -90,6 +90,33 @@ function packageDependenciesOf(pkgSpec) {
   }
 }
 
+function resolvePackageVersion(pkg, channel, npmBin = 'npm') {
+  const tag = channel === 'nightly' ? 'nightly' : 'latest';
+  const probe = capture(npmBin, ['view', `${pkg}@${tag}`, 'version', '--json'], { timeout: 15_000 });
+  if (!probe.ok) return '';
+  try {
+    const parsed = JSON.parse(probe.stdout);
+    return typeof parsed === 'string' ? parsed : '';
+  } catch {
+    return /^\S+$/.test(probe.stdout.trim()) ? probe.stdout.trim() : '';
+  }
+}
+
+function codexMarketplace() {
+  const probe = capture('codex', ['plugin', 'marketplace', 'list', '--json'], { timeout: 6_000 });
+  if (!probe.ok) return null;
+  try {
+    return JSON.parse(probe.stdout)?.marketplaces?.find((m) => m?.name === 'ours-codex-marketplace') ?? null;
+  } catch { return null; }
+}
+
+function hasClaudePlugin() {
+  const probe = capture('claude', ['plugin', 'list', '--json'], { timeout: 6_000 });
+  if (!probe.ok) return false;
+  try { return JSON.parse(probe.stdout)?.some((p) => p?.id === 'ours@ours.network') ?? false; }
+  catch { return false; }
+}
+
 /**
  * A read-only command probe that NEVER throws and NEVER inherits stdio.
  *
@@ -223,6 +250,7 @@ function knownStateDirsIn(home) {
  * the orchestrator never reaches for a terminal itself.
  */
 export function realEffects({ write, ttyFd, env = process.env, home = homedir(), out, version = null } = {}) {
+  const npmBin = env.OURS_NPM?.trim() || 'npm';
   return {
     home,
     env,
@@ -297,14 +325,15 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
       // 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, {
+      const executable = cmd === 'npm' ? npmBin : cmd;
+      const r = spawnSync(executable, args, {
         encoding: 'utf8',
         stdio: stream ? ['ignore', 'inherit', 'inherit'] : ['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}` : ''}`);
+        throw new Error(`${executable} ${args.join(' ')} exited ${r.status}${detail ? `: ${detail}` : ''}`);
       }
       return { ok: true, code: r.status, stdout: r.stdout ?? '' };
     },
@@ -317,8 +346,11 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
       const r = spawnSync(cmd, args, { stdio: 'inherit', env: { ...env, ...(extraEnv ?? {}) } });
       return { ok: !r.error && r.status === 0, code: r.status ?? -1 };
     },
-    installedVersion: installedVersionOf,
-    packageDependencies: packageDependenciesOf,
+    installedVersion: (pkg) => installedVersionOf(pkg, npmBin),
+    packageDependencies: (spec) => packageDependenciesOf(spec, npmBin),
+    resolvePackageVersion: (pkg, channel) => resolvePackageVersion(pkg, channel, npmBin),
+    codexMarketplace,
+    hasClaudePlugin,
     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)),
@@ -326,7 +358,7 @@ export function realEffects({ write, ttyFd, env = process.env, home = homedir(),
   };
 }
 
-export const __testables = { probePort, portTakenSync, readJsonFile, readTextFile, installedVersionOf, packageDependenciesOf, knownStateDirsIn };
+export const __testables = { probePort, portTakenSync, readJsonFile, readTextFile, installedVersionOf, packageDependenciesOf, resolvePackageVersion, codexMarketplace, hasClaudePlugin, knownStateDirsIn };
 
 // -----------------------------------------------------------------------------
 // THE PAIR
@@ -335,7 +367,7 @@ export const __testables = { probePort, portTakenSync, readJsonFile, readTextFil
 /**
  * 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
+ * A state directory and its 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

package/lib/extras.mjs

@@ -1,14 +1,14 @@
 // 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.
+// copy-paste hand-off prompt.
 //
 // 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.
+// orchestrator performs it.
 
 import { dirname, join, resolve } from 'node:path';
 import { pkgSpec } from './logic.mjs';
@@ -16,7 +16,7 @@ import { pkgSpec } from './logic.mjs';
 const cfgPath = (stateDir) => join(resolve(stateDir), 'config.json');
 
 // -----------------------------------------------------------------------------
-// §5 — harness plugins
+// Harness plugins
 // -----------------------------------------------------------------------------
 
 export const CLAUDE_MARKET = 'adapt-toolkit/ours-claude-marketplace';
@@ -29,13 +29,12 @@ export const HARNESSES = [
 ];
 
 /**
- * SPEC §5 PROMISES SOMETHING TWO OF THE THREE REGISTRATIONS CANNOT DO.
+ * TWO OF THE THREE REGISTRATIONS CANNOT PERSIST AN ENVIRONMENT VALUE.
  *
- * §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:
+ * For a non-default state directory, planMcpAttachment exposes the required
+ * OURS_CONFIG value. Claude Code and Codex cannot persist that value in their
+ * plugin registrations, so the installer prints an explicit shell export and
+ * never claims it was applied automatically:
  *
  *   Claude Code  the marketplace plugin's mcpServers.ours is command+args, with
  *                no env key, and `claude plugin install` injects nothing per
@@ -46,9 +45,7 @@ export const HARNESSES = [
  *   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:
+ * The supported behavior is:
  *
  *   default state directory   today's behaviour, byte for byte.
  *   Hermes, non-default       real: the pair is handed to ours-hermes-install's
@@ -56,7 +53,7 @@ export const HARNESSES = [
  *                             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.
+ *                             Never claim automatic configuration 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
@@ -94,7 +91,7 @@ const driveSteps = {
   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
+    // Product requirement 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)],
   ],
@@ -122,7 +119,7 @@ const driveSteps = {
  * `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.
+ * the screen cannot claim that the pair was persisted where it was only printed.
  */
 export function planHarnessPlugins({
   harnesses = [],
@@ -170,7 +167,7 @@ export function planHarnessPlugins({
 }
 
 // -----------------------------------------------------------------------------
-// §5 — what the operator has to do BEFORE any of this works
+// Preconditions the operator must satisfy before installation
 // -----------------------------------------------------------------------------
 
 /**

package/lib/logic.mjs

@@ -107,7 +107,7 @@ export function resolveChannel(raw, selfVersion = '') {
 
 // A published nightly carries the `-nightly.N` prerelease suffix the bump script writes.
 export function isNightlyVersion(version) {
-  return /-nightly\.\d+/.test(String(version || ''));
+  return /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)-nightly\.(?:0|[1-9]\d*)$/.test(String(version || ''));
 }
 
 // The npm dist-tag to install for one package key under a channel. Looks the key
@@ -207,15 +207,13 @@ export function planTgDaemonConfig(existing, { daemonUrl, daemonStateDir, broker
 }
 
 // ── Rooms / ours-cowork ────────────────────────────────────────────────────────
-// ours-cowork was a purely standalone daemon: its shipped 0.4.0 bundle has no
-// daemonUrl / daemonStateDir / /api/v1 anywhere and its docs said it "has no
-// dependency on another agent daemon". ours-cowork PR #9 (head 030b71df…) adds an
-// EXTERNAL daemon mode, so Rooms can now answer the same common-vs-dedicated
-// question the Telegram connector does. Its exact contract, as reported:
+// cowork supports an external-daemon mode, so Rooms can use the same
+// common-vs-dedicated selection as the Telegram connector. Its public config
+// contract is:
 //
 //   ~/.ours-cowork/config.json carries an OPTIONAL `daemon` block.
 //     absent  ⇒ EMBEDDED — cowork hosts its own daemon (what every install
-//               before PR #9 does, and still the safe answer for one already
+//               before external mode existed, and still the safe answer for one already
 //               running that way).
 //     present ⇒ { mode: 'external', endpoint: 'http://127.0.0.1:<port>',
 //                 stateDir: '<absolute ours-daemon state dir>' }
@@ -236,19 +234,12 @@ export const COWORK_DEFAULT_PORT = 3052;
 export const COWORK_DAEMON_MODES = ['embedded', 'external'];
 
 // Which cowork builds understand the `daemon` block. Its config is a STRICT
-// document, so handing an unknown key to a build that predates PR #9 is not a
+// document, so handing an unknown key to a build that predates external mode is not a
 // harmless no-op — and cowork's boot is fail-closed, so the failure surfaces as a
 // Rooms daemon that will not start rather than a warning.
 //
-// The FIRST published cowork that implements the external-daemon mode. Verified
-// against the registry rather than taken on trust:
-//   @ours.network/cowork@nightly = 0.4.1-nightly.20260816.4aaf940
-//   gitHead 4aaf9406016098704d06b52352f7a38adc2ef160
-//   dist.shasum 5a6422409b1203a9bcc6aca33965fe47e9a5c17c
-//   depends on @ours.network/sdk 1.3.1; `latest` still 0.4.0
-// and the packed tarball really carries it — dist/daemon.js and dist/cli.js
-// contain the mode enum ["embedded","external"], the endpoint+stateDir pairing
-// check, OURS_COWORK_DAEMON_MODE/_ENDPOINT/_STATE_DIR, and the daemon-token read.
+// The first published cowork version whose package contains external-daemon
+// config parsing, endpoint/state-directory pairing, and daemon-token loading.
 export const COWORK_EXTERNAL_MIN_VERSION = '0.4.1-nightly.20260816.4aaf940';
 
 // Does the cowork build actually on this machine support an external daemon?

package/lib/marketplace.mjs

@@ -0,0 +1,104 @@
+import { join } from 'node:path';
+
+const NUM = '(?:0|[1-9]\\d*)';
+const STABLE_VERSION = new RegExp(`^${NUM}\\.${NUM}\\.${NUM}$`);
+const NIGHTLY_VERSION = new RegExp(`^${NUM}\\.${NUM}\\.${NUM}-nightly\\.${NUM}$`);
+
+// npm view --json normally returns a JSON string, while older/custom npm wrappers may
+// return the plain version. Accept exactly one scalar either way; arrays/objects are not
+// a deliberate dist-tag resolution and therefore fail closed.
+export function parseNpmVersion(text) {
+  const raw = String(text ?? '').trim();
+  if (!raw) return '';
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === 'string' ? parsed.trim() : '';
+  } catch {
+    return /^\S+$/.test(raw) ? raw : '';
+  }
+}
+
+export function validateChannelVersion(version, channel) {
+  const value = String(version ?? '').trim();
+  const selected = channel === 'nightly' ? 'nightly' : 'latest';
+  const valid = selected === 'nightly'
+    ? NIGHTLY_VERSION.test(value)
+    : STABLE_VERSION.test(value);
+  return valid
+    ? { ok: true, version: value, channel: selected }
+    : {
+        ok: false,
+        version: value,
+        channel: selected,
+        reason: selected === 'nightly'
+          ? `expected an exact X.Y.Z-nightly.N version, got ${value || '<empty>'}`
+          : `expected an exact stable X.Y.Z version, got ${value || '<empty>'}`,
+      };
+}
+
+function exactVersion(version, channel) {
+  const checked = validateChannelVersion(version, channel);
+  if (!checked.ok) throw new Error(checked.reason);
+  return checked.version;
+}
+
+export function buildClaudeMarketplace(version, channel) {
+  const pinned = exactVersion(version, channel);
+  return {
+    $schema: 'https://json.schemastore.org/claude-code-marketplace.json',
+    name: 'ours.network',
+    owner: {
+      name: 'Adapt Toolkit',
+      url: 'https://github.com/adapt-toolkit/ours-claude-marketplace',
+    },
+    plugins: [{
+      name: 'ours',
+      displayName: 'ours',
+      description: 'Secure agent-to-agent communication channel over ADAPT: self-sovereign pubkey identity, end-to-end encryption.',
+      author: { name: 'Adapt Toolkit' },
+      homepage: 'https://github.com/adapt-toolkit/ours-claude-marketplace',
+      repository: 'https://github.com/adapt-toolkit/ours-claude-marketplace',
+      keywords: ['mcp', 'a2a', 'adapt', 'e2e', 'messaging'],
+      source: {
+        source: 'npm',
+        package: '@ours.network/claude-code',
+        version: pinned,
+      },
+    }],
+  };
+}
+
+export function buildCodexMarketplace(version, channel) {
+  const pinned = exactVersion(version, channel);
+  return {
+    name: 'ours-codex-marketplace',
+    interface: { displayName: 'ours.network for Codex' },
+    plugins: [{
+      name: 'ours',
+      source: {
+        source: 'npm',
+        package: '@ours.network/codex',
+        version: pinned,
+        registry: 'https://registry.npmjs.org',
+      },
+      policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+      category: 'Productivity',
+    }],
+  };
+}
+
+export function marketplacePaths(home) {
+  const root = join(home, '.ours', 'install', 'marketplaces');
+  const claudeRoot = join(root, 'claude-code');
+  const codexRoot = join(root, 'codex');
+  return {
+    claudeRoot,
+    claudeManifest: join(claudeRoot, '.claude-plugin', 'marketplace.json'),
+    codexRoot,
+    codexManifest: join(codexRoot, '.agents', 'plugins', 'marketplace.json'),
+  };
+}
+
+export function marketplaceJson(value) {
+  return JSON.stringify(value, null, 2) + '\n';
+}

package/lib/orchestrate-uninstall.mjs

@@ -40,7 +40,7 @@ async function perform(effects, dryRun, label, thunk) {
 
 /**
  * Which components are being removed alongside this daemon. Asked once, before
- * anything is touched, so the §8 step 1 refusal can be resolved in the same run
+ * anything is touched, so a referenced-component refusal can be resolved in the same run
  * rather than sending the operator away and back.
  *
  * Non-interactively the answer is NO — assume-yes never consents to removing
@@ -81,7 +81,7 @@ export async function runUninstall(argv, effects) {
   effects.out(heading(`ours-uninstall --state-dir ${dir}`));
   if (args.dryRun) effects.out(info('dry-run: nothing will be removed or stopped'));
 
-  // §9 — the documented OURS_UNINSTALL_* contract (item 10.9), read BEFORE any
+  // Read the documented OURS_UNINSTALL_* contract before any
   // file is opened. A variable this uninstaller cannot deliver stops the run
   // here, naming itself and naming the replacement, rather than being silently
   // ignored while the operator's script reports success.

package/lib/orchestrate.mjs

@@ -37,12 +37,31 @@ import { configJournal, reportRollback } from './journal.mjs';
 import { detectDaemons, planDaemonSelection, resolveSelection } from './detect.mjs';
 import { detectPlatform, resolveChannel } from './logic.mjs';
 import { daemonEnv } from './effects.mjs';
+import {
+  buildClaudeMarketplace, buildCodexMarketplace, marketplaceJson, marketplacePaths,
+  validateChannelVersion,
+} from './marketplace.mjs';
 import { USAGE } from './usage.mjs';
 import { ok, info, warn, heading, banner, box, c, progress } from './ui.mjs';
 
 export const EXIT_OK = 0;
 export const EXIT_REFUSED = 2;
 
+export async function resolveExactSuite(args, effects) {
+  const packages = {};
+  for (const key of ['mcp', 'claude-code', 'codex']) {
+    const version = await effects.resolvePackageVersion(`@ours.network/${key}`, args.channel);
+    const checked = validateChannelVersion(version, args.channel);
+    if (!checked.ok) return { ok: false, reason: `${key}: ${checked.reason}` };
+    packages[key] = checked.version;
+  }
+  const versions = new Set(Object.values(packages));
+  if (versions.size !== 1) {
+    return { ok: false, reason: `the ${args.channel} dist-tags are not lockstep (${Object.entries(packages).map(([k, v]) => `${k}=${v}`).join(', ')})` };
+  }
+  return { ok: true, channel: args.channel, version: versions.values().next().value, packages };
+}
+
 /**
  * A dry run prints what it WOULD do and performs no mutation. The prefix is the
  * existing installer's, kept so the two flows read the same.
@@ -200,7 +219,7 @@ function pairFor(plan, target) {
 /**
  * Which daemon is this run for?
  *
- * Never asks for a PATH — spec §2 stands — but when several daemons are DETECTED
+ * Never asks for a path, but when several daemons are detected
  * it shows them and lets the operator pick, because choosing from what was found
  * is not prompting for a state directory.
  *
@@ -242,7 +261,7 @@ export async function runSelectionPhase(args, effects) {
   const chosen = resolveSelection(answer, plan);
   if (chosen.action === 'invalid') {
     // Refused rather than guessed. Interpreting an unrecognised answer as a path
-    // would be the "type a state directory" prompt spec §2 forbids, arriving
+    // would reintroduce the forbidden "type a state directory" prompt through the
     // through the back door.
     effects.out(warn(`ours: ${chosen.reason}. Nothing was changed.`));
     effects.out(info('Re-run and pick one of the numbers, or name a daemon directly with --state-dir.'));
@@ -256,10 +275,10 @@ export async function runSelectionPhase(args, effects) {
 }
 
 /**
- * The daemon half of a run: §§2-4. Returns the target decision plus the step
+ * Run the daemon half of an installation and return the target decision plus step
  * outcomes, or a refusal.
  */
-export async function runDaemonPhase(args, effects) {
+export async function runDaemonPhase(args, effects, exactSuite = null) {
   const target = await resolveTarget({
     stateDir: args.stateDir,
     port: args.port,
@@ -301,8 +320,8 @@ export async function runDaemonPhase(args, effects) {
   // daemon's broker is its own record, and re-asking would invite an operator to
   // change it from a screen that is not about changing it. The broker question
   // stays in v3: it is orthogonal to --state-dir/--port, so it
-  // does not violate spec §2's "nothing about a state directory or a port
-  // appears in any prompt".
+  // does not violate the rule that state-directory and port values never appear
+  // in prompts.
   if (creating) args.brokerUrl = await askBroker(args, effects);
 
   const steps = [];
@@ -310,7 +329,9 @@ export async function runDaemonPhase(args, effects) {
   // The operator CLI owns the shared daemon; ours-mcp is the per-session stdio
   // adapter each harness spawns. Both are required, but only `ours daemon`
   // participates in lifecycle or service management.
-  const mcpPkg = componentSpec(componentByKey('mcp'), args.channel);
+  const mcpPkg = exactSuite?.packages?.mcp
+    ? `@ours.network/mcp@${exactSuite.packages.mcp}`
+    : componentSpec(componentByKey('mcp'), args.channel);
   // The CLI intentionally publishes only `latest`; unlike the lockstep MCP and
   // connector packages it has no nightly dist-tag. Keep this untagged on every
   // installer channel, and inspect that package's SDK dependency for the gate.
@@ -458,7 +479,7 @@ function rollBack(effects, journal, args, why, { packagesInstalled = true, repla
 }
 
 /**
- * The boot service: §4 step 4, including the legacy-unit case.
+ * Install the boot service, including the legacy-unit case.
  *
  * A legacy ours-mcp unit is adopted SILENTLY, with one informational line naming
  * the file. `--force` is passed ONLY here, only for a unit
@@ -545,11 +566,11 @@ export async function askComponents(args, effects) {
 }
 
 /**
- * Components: §5. A component that fails is reported with its retry command and
+ * A component that fails is reported with its retry command and
  * the run CONTINUES — a failed component is never a reason to undo a successful
  * one, or to undo the daemon.
  */
-export async function runComponentPhase(args, effects, target) {
+export async function runComponentPhase(args, effects, target, exactSuite = null) {
   const dir = target.stateDir;
   const endpoint = `http://127.0.0.1:${target.port}`;
   const isDefaultStateDir = dir === join(effects.home, '.ours');
@@ -568,13 +589,15 @@ export async function runComponentPhase(args, effects, target) {
       continue;
     }
     try {
-      results.push(await attachComponent(component, { args, effects, dir, endpoint, isDefaultStateDir }));
+      results.push(await attachComponent(component, { args, effects, dir, endpoint, isDefaultStateDir, exactSuite }));
     } catch (error) {
       // Reported with its reason and the exact manual command; the run continues.
       // The retry carries the CHANNEL — a nightly run that hands the operator a
       // stable retry command sends them straight into the split-brain install
       // this phase exists to avoid.
-      const retry = `npm i -g ${componentSpec(component, args.channel)}`;
+      const retrySpec = component.key === 'mcp' && exactSuite?.packages?.mcp
+        ? `@ours.network/mcp@${exactSuite.packages.mcp}` : componentSpec(component, args.channel);
+      const retry = `npm i -g ${retrySpec}`;
       effects.out(warn(`${component.label} failed: ${error instanceof Error ? error.message : String(error)}`));
       effects.out(info(`retry manually: ${retry}`));
       results.push({ key: component.key, state: 'failed', reason: String(error?.message ?? error), retry });
@@ -583,10 +606,11 @@ export async function runComponentPhase(args, effects, target) {
   return summarizeComponentRun(results);
 }
 
-async function attachComponent(component, { args, effects, dir, endpoint, isDefaultStateDir }) {
+async function attachComponent(component, { args, effects, dir, endpoint, isDefaultStateDir, exactSuite }) {
   if (component.key === 'mcp') {
     const plan = planMcpAttachment({ stateDir: dir, isDefaultStateDir, channel: args.channel });
-    await perform(effects, args.dryRun, `install ${plan.install[3]}`, () => effects.run(plan.install[0], plan.install.slice(1)));
+    const exact = exactSuite?.packages?.mcp ? `@ours.network/mcp@${exactSuite.packages.mcp}` : plan.install[3];
+    await perform(effects, args.dryRun, `install ${exact}`, () => effects.run('npm', ['i', '-g', exact]));
     if (Object.keys(plan.harnessEnv).length > 0) {
       effects.out(info(`harness registration carries OURS_CONFIG=${plan.harnessEnv.OURS_CONFIG}`));
     }
@@ -787,7 +811,7 @@ export async function runIdentityPhase(args, effects, { target, mcpReady }) {
 }
 
 /**
- * The harness plugins (spec §5's other half).
+ * Install harness plugins after the daemon and components are ready.
  *
  * Two things this phase must never do, both inherited rules rather than new
  * ones. It never DRIVES a command it could not identify — an alias or a wrapper
@@ -797,7 +821,7 @@ export async function runIdentityPhase(args, effects, { target, mcpReady }) {
  * get the exact export line and no promise. Hermes' writer is ours, so its
  * invocation carries the whole pair and the claim is true.
  */
-export async function runHarnessPhase(args, effects, { target, isDefaultStateDir }) {
+export async function runHarnessPhase(args, effects, { target, isDefaultStateDir, exactSuite = null }) {
   effects.out(heading('Harness plugins'));
   const detected = await effects.detectHarnesses();
   for (const h of detected) {
@@ -822,6 +846,7 @@ export async function runHarnessPhase(args, effects, { target, isDefaultStateDir
   });
 
   const rows = [];
+  const markets = marketplacePaths(effects.home);
   for (const plan of plans) {
     const row = { key: plan.name, label: `${plan.label} plugin` };
     if (plan.action === 'skip') {
@@ -832,27 +857,65 @@ export async function runHarnessPhase(args, effects, { target, isDefaultStateDir
     if (plan.action === 'manual') {
       // NEVER a dead end: the plugin is still installable, by hand, and the run
       // says so instead of pretending the harness does not exist.
+      let manual = plan.manual;
+      if (exactSuite && (plan.name === 'claude-code' || plan.name === 'codex')) {
+        const isClaude = plan.name === 'claude-code';
+        const root = isClaude ? markets.claudeRoot : markets.codexRoot;
+        const manifest = isClaude ? markets.claudeManifest : markets.codexManifest;
+        const value = isClaude
+          ? buildClaudeMarketplace(exactSuite.packages['claude-code'], exactSuite.channel)
+          : buildCodexMarketplace(exactSuite.packages.codex, exactSuite.channel);
+        await perform(effects, args.dryRun, `write exact ${plan.name} marketplace ${manifest}`, () => effects.writeJson(manifest, marketplaceJson(value)));
+        manual = isClaude
+          ? [`/plugin marketplace add ${root}`, '/plugin install ours']
+          : [`codex plugin marketplace add ${root}`, 'codex plugin add ours@ours-codex-marketplace', `npm i -g @ours.network/codex@${exactSuite.packages.codex}`];
+      }
       effects.out(warn(`${plan.label} — ${plan.reason}; install it yourself with:`));
-      for (const step of plan.manual) effects.out(info(`  ${step}`));
+      for (const step of manual) effects.out(info(`  ${step}`));
       rows.push({ ...row, state: 'skipped', note: plan.reason });
       continue;
     }
 
+    let steps = plan.steps;
+    let manual = plan.manual;
+    if (exactSuite && (plan.name === 'claude-code' || plan.name === 'codex')) {
+      const isClaude = plan.name === 'claude-code';
+      const root = isClaude ? markets.claudeRoot : markets.codexRoot;
+      const manifest = isClaude ? markets.claudeManifest : markets.codexManifest;
+      const value = isClaude
+        ? buildClaudeMarketplace(exactSuite.packages['claude-code'], exactSuite.channel)
+        : buildCodexMarketplace(exactSuite.packages.codex, exactSuite.channel);
+      await perform(effects, args.dryRun, `write exact ${plan.name} marketplace ${manifest}`, () => effects.writeJson(manifest, marketplaceJson(value)));
+      if (!isClaude) {
+        const current = await effects.codexMarketplace();
+        const source = current?.marketplaceSource;
+        if (current && !(source?.sourceType === 'local' && source?.source === root)) {
+          await perform(effects, args.dryRun, 'remove moving Codex marketplace source', () => effects.run('codex', ['plugin', 'marketplace', 'remove', 'ours-codex-marketplace']));
+        }
+      }
+      steps = isClaude
+        ? [['claude', 'plugin', 'marketplace', 'add', root], ['claude', 'plugin', await effects.hasClaudePlugin() ? 'update' : 'install', 'ours@ours.network']]
+        : [['codex', 'plugin', 'marketplace', 'add', root], ['codex', 'plugin', 'add', 'ours@ours-codex-marketplace'], ['npm', 'i', '-g', `@ours.network/codex@${exactSuite.packages.codex}`]];
+      manual = isClaude
+        ? [`/plugin marketplace add ${root}`, '/plugin install ours']
+        : [`codex plugin marketplace add ${root}`, 'codex plugin add ours@ours-codex-marketplace', `npm i -g @ours.network/codex@${exactSuite.packages.codex}`];
+    }
+
     const env = pairFor(plan, target);
     let failed = null;
-    for (const step of plan.steps) {
+    for (const step of steps) {
       const outcome = await attempt(effects, args.dryRun, step.join(' '), () => effects.run(step[0], step.slice(1), env ? { env } : {}));
       if (!outcome.ok) { failed = outcome; break; }
     }
     if (failed) {
       effects.out(info(`${plan.label} can still be installed by hand:`));
-      for (const step of plan.manual) effects.out(info(`  ${step}`));
+      for (const step of manual) effects.out(info(`  ${step}`));
       rows.push({ ...row, state: 'failed', note: 'install step failed' });
       continue;
     }
     if (plan.envLine) {
-      // The honest line. §5's promise does NOT hold for this harness, and the
-      // screen says exactly what is true and exactly what to do about it.
+      // This harness cannot persist the selected daemon pair. Say exactly what is
+      // true and how the operator can configure it explicitly.
       effects.out(warn(`${plan.label}'s registration cannot carry a value, so it will attach to the DEFAULT daemon.`));
       effects.out(info(`Add this to your shell profile so it uses this one instead:  ${plan.envLine}`));
     }
@@ -1035,6 +1098,13 @@ export async function runInstall(argv, effects) {
   // that wrapped the old installer keeps its meaning.
   if (!runPreflight(effects).ok) return EXIT_OK;
 
+  const exactSuite = await resolveExactSuite(args, effects);
+  if (!exactSuite.ok) {
+    effects.out(warn(`Release suite could not be resolved safely: ${exactSuite.reason}. Nothing was changed.`));
+    return EXIT_REFUSED;
+  }
+  effects.out(ok(`Release channel: ${exactSuite.channel} → exact lockstep suite v${exactSuite.version}`));
+
   // Which daemon, before anything is decided about it. Only args.stateDir can
   // change here; every refusal downstream is unaffected.
   effects.out(progress(2, 8, 'Choose one daemon', 'Reuse the only detected daemon or create one coherent shared target.'));
@@ -1042,7 +1112,7 @@ export async function runInstall(argv, effects) {
   if (selection.action === 'refuse') return EXIT_REFUSED;
 
   effects.out(progress(3, 8, 'Prepare the shared daemon', 'Install the CLI, write config, start it, and enable boot persistence.'));
-  const daemon = await runDaemonPhase(args, effects);
+  const daemon = await runDaemonPhase(args, effects, exactSuite);
   if (daemon.refused) return EXIT_REFUSED;
   const target = daemon.target;
   const isDefaultStateDir = target.stateDir === join(effects.home, '.ours');
@@ -1065,7 +1135,7 @@ export async function runInstall(argv, effects) {
   }
 
   effects.out(progress(4, 8, 'Install the complete stack', 'Attach MCP, Telegram, and cowork to the same daemon; run both shims as durable services.'));
-  const components = await runComponentPhase(args, effects, target);
+  const components = await runComponentPhase(args, effects, target, exactSuite);
   for (const component of COMPONENTS) {
     const state = components.installed.includes(component.key) ? 'installed'
       : components.failed.some((f) => f.key === component.key) ? 'failed' : 'skipped';
@@ -1084,7 +1154,7 @@ export async function runInstall(argv, effects) {
   effects.out(progress(5, 8, 'Create the Human identity', 'Create the daemon root identity once, or keep the existing one.'));
   summary.push(await runIdentityPhase(args, effects, { target, mcpReady }));
   effects.out(progress(6, 8, 'Wire detected harnesses', 'Install the ours plugin into each safe Claude Code, Codex, or Hermes installation.'));
-  summary.push(...await runHarnessPhase(args, effects, { target, isDefaultStateDir }));
+  summary.push(...await runHarnessPhase(args, effects, { target, isDefaultStateDir, exactSuite }));
   effects.out(progress(7, 8, 'Stage the fleet', 'Install Fleet and write a stopped coordinator + watchdog + health-loop starter config.'));
   summary.push(await runFleetPhase(args, effects, { target, isDefaultStateDir }));
   summary.push(await runVoicePhase(args, effects, { target, mcpReady }));

package/lib/plan.mjs

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

package/lib/rerun.mjs

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

package/lib/target.mjs

@@ -1,6 +1,6 @@
 // ours-install v3 — argument handling and daemon detection.
 //
-// Spec: installer-spec-v3 §§1-3. Everything here is PURE: the orchestrator
+// Pure argument handling and daemon-target selection. The orchestrator
 // injects the probe, the file reads and the port check, so the whole decision
 // table is testable without a socket, a daemon or a filesystem.
 //
@@ -19,17 +19,15 @@ export const FREE_PORT_SPAN = 1000;
 
 // Ports that are other components' DEFAULTS, not facts about the machine: 3051
 // is the Telegram connector's, 3052 is cowork's loopback console. The free-port
-// search skips them; an explicit --port is still honoured as typed (spec §2).
+// search skips them; an explicit --port is still honoured exactly as typed.
 //
-// NOTE, deliberately not silently reconciled: lib/logic.mjs's RESERVED_PORTS is
-// [3051] on this branch, while spec §2 states [3051, 3052] citing the
-// dev4/version-plumbing branch. This constant follows the spec. The two should
-// be merged once someone decides whether cowork's 3052 belongs in the shipped
-// list — flagged rather than assumed.
+// Keep both component defaults out of automatic selection: 3051 belongs to the
+// Telegram connector and 3052 to cowork. Explicit operator selections remain
+// valid.
 export const INSTALL_RESERVED_PORTS = [3051, 3052];
 
 // The CLI-owned PID record that proves a daemon belongs to a state directory
-// even when nothing is recorded in its config (spec §1).
+// even when nothing is recorded in its config.
 export const CLI_PID_RECORD = 'ours-cli-daemon.json';
 // The SAME record, written by a different daemon. `ours daemon start` writes
 // ours-cli-daemon.json; prerelease ours-mcp wrote daemon.pid (packages/core
@@ -77,7 +75,7 @@ export function samePath(a, b) {
 }
 
 // -----------------------------------------------------------------------------
-// §2 — arguments
+// Arguments
 // -----------------------------------------------------------------------------
 
 const VALUE_FLAGS = new Set(['--state-dir', '--port']);
@@ -143,14 +141,14 @@ export function parseInstallArgs(argv = [], env = {}, { home = homedir() } = {})
 }
 
 // -----------------------------------------------------------------------------
-// §§1, 3 — is there a daemon at this state directory?
+// Is there a daemon at this state directory?
 // -----------------------------------------------------------------------------
 
 /**
  * The port to probe first: the one recorded in <state-dir>/config.json, else the
  * built-in default. An explicit --port does NOT change where we look — the
  * question is which daemon owns this directory, and that is answered by the
- * directory's own record, not by what the operator typed (spec §2 step 2).
+ * directory's own record, not by what the operator typed.
  */
 export function candidatePort(config) {
   const recorded = config && typeof config.port === 'number' && Number.isFinite(config.port) ? config.port : null;
@@ -158,7 +156,7 @@ export function candidatePort(config) {
 }
 
 /**
- * Classify one probe result against the target state directory (spec §3).
+ * Classify one probe result against the target state directory.
  *
  *   present — an ours daemon answered and reports THIS state directory
  *   foreign — something answered, but it is not an ours daemon, or it is one
@@ -246,12 +244,12 @@ export async function findDaemon({ stateDir, probe, readJson, readText }) {
   }
   // A FOREIGN DAEMON ON A PORT WE GUESSED IS NOT A REASON TO REFUSE.
   //
-  // AMENDS #56. As first written, any foreign answer on the candidate port
+  // Regression guard. As first written, any foreign answer on the candidate port
   // refused the run. But a state directory with no recorded port has told us
   // nothing, so the candidate is the built-in default — which, on any machine
   // that already runs a daemon, is where the FIRST daemon answers. The result
   // was that a second daemon could never be created while the first was up:
-  // §7 coexistence was unreachable, and the refusal's own advice ("re-run with
+  // coexistence was unreachable, and the refusal's own advice ("re-run with
   // --port for a free port") could not work either, because an explicit --port
   // deliberately does not change where we look.
   //
@@ -280,7 +278,7 @@ export async function findDaemon({ stateDir, probe, readJson, readText }) {
 }
 
 // -----------------------------------------------------------------------------
-// §2 — the derived-port rule
+// Derived-port rule
 // -----------------------------------------------------------------------------
 
 /**

package/lib/uninstall.mjs

@@ -1,6 +1,6 @@
 // ours-uninstall v3 — removing ONE daemon, and the non-interactive contract.
 //
-// Spec: installer-spec-v3 §§8-9. Pure, like every other stage: the caller
+// Pure uninstall planning, like every other stage: the caller
 // injects the file reads and this returns a plan.
 //
 //   ours-uninstall [--state-dir PATH] [--purge] [--dry-run]
@@ -11,7 +11,7 @@
 // THE BIAS OF THIS WHOLE FILE IS TOWARD KEEPING THINGS. State is kept by default,
 // a component's config file is kept even when its daemon keys are removed, and
 // global packages are kept while any other daemon still needs them. The one
-// destructive operation, --purge, is separately gated (§8 step 5) because
+// destructive operation, --purge, is separately gated because
 // it deletes identity keys, and no other step here is irreversible.
 
 import { join, resolve } from 'node:path';
@@ -22,9 +22,9 @@ import { canonHarnesses } from './logic.mjs';
 /**
  * Does this directory even look like an ours state directory?
  *
- * WHY THIS EXISTS. The owner removed the "created by an installer run" gate —
- * purge means purge, on any state directory. That was a deliberate ruling and
- * this does not reintroduce it: this asks "is this a state directory at all",
+ * Purge applies to any explicitly selected ours state directory, not only one
+ * created by this installer. This does not add a provenance gate: it asks
+ * "is this a state directory at all",
  * not "is it ours". With provenance gone, the typed path would otherwise be the
  * only thing between `ours-uninstall --state-dir ~ --purge` and a deleted home
  * directory, and a typed path is no protection against a path typed exactly as
@@ -85,7 +85,7 @@ export function inspectComponentConfig(path, { readText } = {}) {
 }
 
 /**
- * §8 step 1 — refuse if a component still points at this daemon.
+ * Refuse if a component still points at this daemon.
  *
  * Read the connector's and cowork's config files; if either names this daemon's
  * endpoint or its state directory, list them and stop. Exit 2, nothing removed.
@@ -160,7 +160,7 @@ export function planComponentDetach(key, existing) {
 }
 
 /**
- * §8 steps 3-4 — the boot service, then the daemon itself.
+ * Stop the boot service, then the daemon itself.
  *
  * Both delegate their refusals rather than reimplementing them: `ours daemon
  * uninstall-service` refuses to remove a unit not marked as CLI-managed, and
@@ -186,14 +186,13 @@ export function planDaemonRemoval({ stateDir, cliStartedIt }) {
 }
 
 /**
- * §8 step 5 — state. Kept unless every gate opens.
+ * State is kept unless every purge gate opens.
  *
  *   --purge given      — never the default; deleting identity keys is opt-in.
- *   interactive        — an unattended run never deletes state (§9).
+ *   interactive        — an unattended run never deletes state.
  *   looks like a state directory — see looksLikeStateDir.
- *   typed confirmation — the full path, not a y/N. The owner removed the
- *                        provenance condition, not the deliberateness, and with
- *                        provenance gone this is the last thing standing between
+ *   typed confirmation — the full path, not a y/N. Without a provenance
+ *                        condition, this is the last thing standing between
  *                        a mistyped command and someone's identity keys.
  *
  * Returns the exact directory, never a glob or a parent, and only when every gate
@@ -219,7 +218,7 @@ export function planStatePurge({ stateDir, purge = false, assumeYes = false, exi
 }
 
 /**
- * §8 step 6 — global packages are shared. Remove them only when no OTHER state
+ * Global packages are shared. Remove them only when no other state
  * directory on this machine still has a daemon config; otherwise keep them and
  * say which daemon still needs them.
  */
@@ -257,7 +256,7 @@ export function planGlobalPackages({ stateDir, otherStateDirsWithConfig = [], pl
 }
 
 // -----------------------------------------------------------------------------
-// §8 — the harness plugins the installer wrote
+// Harness plugins written by the installer
 // -----------------------------------------------------------------------------
 
 /**
@@ -397,7 +396,7 @@ export function planPluginRemoval({ home, env = {}, exists = () => false, lastDa
 }
 
 /**
- * §8 — WHICH harnesses to detach (inventory item 9.5).
+ * Decide which harnesses to detach using the documented environment contract.
  *
  * The nightly uninstaller let the operator choose: a `checkboxSelect` picker on a
  * terminal, `OURS_UNINSTALL` without one, and NOTHING removed when it had
@@ -472,7 +471,7 @@ export function selectHarnesses(plugins, chosen) {
 }
 
 /**
- * The whole §8 order, refusing at step 1 rather than starting and stopping
+ * Preserve the full uninstall order, refusing before any mutation rather than stopping
  * half-way.
  */
 export function planUninstall({ home, env = {}, endpoint, stateDir, purge = false, assumeYes = false, confirmedComponents = [], readJson, readText, exists = () => true, cliStartedIt = true, otherStateDirsWithConfig = [], typedConfirmation = null, explicitHarnessSelection = false, platform = 'linux' }) {
@@ -528,7 +527,7 @@ export function planUninstall({ home, env = {}, endpoint, stateDir, purge = fals
 }
 
 // -----------------------------------------------------------------------------
-// §9 — the non-interactive contract
+// Non-interactive behavior
 // -----------------------------------------------------------------------------
 
 /**
@@ -565,7 +564,7 @@ export function refusalSurvivesAssumeYes(refusal) {
 }
 
 // -----------------------------------------------------------------------------
-// §9 — the OURS_UNINSTALL_* contract (inventory item 10.9)
+// Documented OURS_UNINSTALL_* environment contract
 // -----------------------------------------------------------------------------
 
 /**
@@ -592,13 +591,13 @@ export function refusalSurvivesAssumeYes(refusal) {
  *                           that matters most.
  *   OURS_UNINSTALL_TELEGRAM
  *   OURS_UNINSTALL_ROOMS    at the value `detach`, which is exactly the
- *                           confirmation §8 step 1 asks a human for and which an
+ *                           confirmation that the interactive flow asks a human for and which an
  *                           unattended run otherwise cannot give, so today the
  *                           run refuses instead of detaching.
  *
  * REFUSED
  *   OURS_UNINSTALL_DATA=yes         v3 never deletes state without a human
- *                                   present (§9), and that rule protects private
+ *                                   present; that rule protects private
  *                                   keys that exist nowhere else.
  *   OURS_UNINSTALL_PROFILE          names an entry in the daemon registry. v3
  *                                   has no registry; the selector is --state-dir.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/install",
-  "version": "0.18.0-nightly.5",
+  "version": "1.0.0",
   "private": false,
   "description": "The all-in-one ours.network installer: one shared daemon, MCP, cowork, Telegram, Fleet, harness plugins, Human identity, stopped Fleet starter, progress UI, and guided next steps.",
   "type": "module",