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

package/lib/journal.mjs

@@ -0,0 +1,158 @@
+// ours-install v3 — the config journal.
+//
+// WHAT THIS IS FOR, IN ONE SENTENCE: v3 could write a config file describing a
+// daemon it then failed to bring up, print one warning line, and go on to say
+// "install complete".
+//
+// The nightly installer does not have that failure. It snapshots every config
+// file before touching it and restores the bytes when the plan does not complete
+// (lib/nightly-install.mjs `snap`/`rollbackSnapshots`), and it says precisely what
+// it could NOT undo. This is that behaviour, carried into v3's shape rather than
+// copied into it.
+//
+// THE LINE THIS DOES NOT CROSS. Package and plugin installs are NOT rolled back.
+// Not because it is hard, but because it is wrong: npm cannot be un-run
+// meaningfully, a newer package is not damage, and nightly draws the line in the
+// same place and says so. What gets restored is exactly the bytes of files this
+// installer rewrote. Everything else is REPORTED.
+//
+// SCOPE IS PER UNIT OF WORK, NOT PER RUN, and that is the one design decision
+// here worth reading twice. v3's rule is that a failed extra never undoes a
+// daemon that came up correctly (lib/orchestrate.mjs `attempt`), so a single
+// run-wide journal restored at the end would fight the architecture: a cowork
+// failure would roll back the daemon's own config. Instead each journal covers
+// ONE write and the step that makes its bytes true — write the connector config,
+// then install its service; if the service does not come up, the config goes
+// back. The pairing is the whole idea, and it is why `snapshot` and `restoreAll`
+// are on an object you hold for the length of one unit of work rather than
+// functions you call anywhere.
+
+import { ok, info, warn } from './ui.mjs';
+
+/**
+ * A journal for one unit of work.
+ *
+ * `effects.snapshot(path)` and `effects.restore(path, snapshot)` are the seam, so
+ * this is testable without a filesystem for the same reason everything else here
+ * is. On a dry run nothing was written, so nothing is snapshotted and nothing can
+ * be restored — the journal is inert rather than special-cased at each call site.
+ */
+export function configJournal(effects, { dryRun = false } = {}) {
+  const entries = [];
+  return {
+    get entries() { return entries.slice(); },
+
+    /**
+     * Record the current bytes of `path` BEFORE it is written. Idempotent per
+     * path: the FIRST snapshot is the one that survives, because that is the
+     * state the run started from. Snapshotting twice and keeping the second would
+     * "restore" to a value this run itself wrote.
+     */
+    snapshot(path) {
+      if (dryRun) return null;
+      if (entries.some((e) => e.path === path)) return entries.find((e) => e.path === path).snapshot;
+      const snapshot = effects.snapshot(path);
+      entries.push({ path, snapshot });
+      return snapshot;
+    },
+
+    /**
+     * Put every journalled file back, most recent first.
+     *
+     * A restore that itself fails is reported, never thrown: the caller is already
+     * on a failure path, and losing the original error to a second one would hide
+     * the thing that actually went wrong. The report says which files went back
+     * and which did not, so a partially recovered state is visible rather than
+     * implied.
+     */
+    restoreAll() {
+      const restored = [];
+      const failed = [];
+      for (const entry of entries.slice().reverse()) {
+        try {
+          effects.restore(entry.path, entry.snapshot);
+          // A write that RETURNED is not a file that HOLDS. Read the bytes back.
+          const mismatch = verifyRestored(effects, entry);
+          if (mismatch) failed.push({ path: entry.path, reason: mismatch });
+          else restored.push({ path: entry.path, existed: entry.snapshot?.exists !== false });
+        } catch (error) {
+          failed.push({ path: entry.path, reason: error instanceof Error ? error.message : String(error) });
+        }
+      }
+      entries.length = 0;
+      return { restored, failed };
+    },
+  };
+}
+
+/**
+ * Did the restore actually take? Returns null when it did, or the reason it did not.
+ *
+ * WHY THIS EXISTS. `restore` returning is evidence that a call completed, not that
+ * a file holds the bytes it was given. A full disk, a read-only mount, a rename
+ * that lands somewhere else, an editor holding the inode — each of those can let
+ * the write return and leave the old contents in place. Reporting on the call
+ * rather than on the state is how a rollback comes to LIE, and a rollback that
+ * lies is worse than one that admits it failed: the operator is told the machine
+ * is back where it was and stops looking.
+ *
+ * The read-back seam is `effects.snapshot`, the same one used to record the bytes
+ * in the first place — it already returns exactly the shape being compared, so
+ * this needs no second seam and no second notion of what a file's state is.
+ *
+ * Its own failure is a mismatch, not an exception: if the file cannot be read
+ * after being written, that is precisely the case this check exists to catch.
+ */
+function verifyRestored(effects, entry) {
+  const expected = entry.snapshot;
+  let actual;
+  try {
+    actual = effects.snapshot(entry.path);
+  } catch (error) {
+    return `restored, but the file could not be read back to confirm it (${error instanceof Error ? error.message : String(error)})`;
+  }
+  const shouldExist = expected?.exists !== false;
+  if (!shouldExist) {
+    return actual?.exists ? 'this run created it and the removal did not take — the file is still there' : null;
+  }
+  if (!actual?.exists) return 'the restore reported success but the file is not there';
+  if (actual.text !== expected.text) return 'the restore reported success but the bytes on disk are not the previous ones';
+  // Bytes first, permissions second: the contents are back either way, so this
+  // must not be reported as "could not restore the config".
+  if (expected.mode !== undefined && actual.mode !== undefined && actual.mode !== expected.mode) {
+    return `contents restored, but the permissions are ${fmtMode(actual.mode)} and were ${fmtMode(expected.mode)} — check them before re-running`;
+  }
+  return null;
+}
+
+const fmtMode = (mode) => `0${(mode & 0o777).toString(8).padStart(3, '0')}`;
+
+/**
+ * The report, and it is half the feature.
+ *
+ * A rollback nobody is told about is indistinguishable from a run that did
+ * nothing. Three separate facts, each stated plainly:
+ *
+ *   · which files were put back, and whether "back" meant deleting one this run
+ *     created — because "restored" and "removed the file we made" are different
+ *     things to read on a screen;
+ *   · which could not be put back, if any;
+ *   · that completed package installs were NOT rolled back. This last line is the
+ *     honest boundary, and it is nightly's wording rather than a new one.
+ */
+export function reportRollback(effects, outcome, { packagesInstalled = false } = {}) {
+  const { restored = [], failed = [] } = outcome ?? {};
+  if (restored.length === 0 && failed.length === 0) return false;
+  for (const item of restored) {
+    effects.out(item.existed
+      ? ok(`rolled back ${item.path} to its previous contents`)
+      : ok(`removed ${item.path} — this run created it and did not finish`));
+  }
+  for (const item of failed) {
+    effects.out(warn(`could NOT roll back ${item.path}: ${item.reason} — inspect it before re-running`));
+  }
+  if (packagesInstalled) {
+    effects.out(info('completed package installs were not rolled back — a newer package is not damage, and npm cannot be un-run'));
+  }
+  return true;
+}

package/lib/logic.mjs

@@ -26,37 +26,98 @@ export function canonHarnesses(raw) {
   return { names, unknown };
 }
 
-// ── Release CHANNEL / npm dist-tag selection (owner 2026-07-17) ─────────────────
+// ── Release CHANNEL / npm dist-tag selection ───────────────────────────────────
 // The installer normally installs everything at @latest (stable). Setting
-// OURS_CHANNEL=nightly (or OURS_INSTALL_CHANNEL) makes it install the NIGHTLY tag
-// for the packages that HAVE a nightly (mcp, tg-connector, and the harness-plugin
-// launchers claude-code/codex/hermes — all lockstep-published to the `nightly` tag),
-// but keep @ours.network/fleet at @latest ALWAYS: ours-fleet lives in its own repo
-// and publishes NO nightly tag, so `@nightly` there would 404 the whole install.
+// OURS_CHANNEL=nightly (or OURS_INSTALL_CHANNEL) makes it install each package's
+// PRERELEASE dist-tag instead — for the packages that publish one.
+//
+// The prerelease tag is NOT the same string everywhere, which is why this is a
+// per-package map rather than one global tag:
+//   · mcp, tg-connector, claude-code, codex, hermes  → `nightly` (lockstep-published
+//     from this repo by .github/workflows/scripts/bump-versions.sh)
+//   · fleet                                          → `nightly` (its own repo,
+//     adapt-toolkit/ours-fleet, publishes a nightly dist-tag of its own)
+//   · cowork (rooms)                                 → `nightly` (cowork aligns
+//     with every other service rather than keeping its
+//     historical `next` tag)
+//
+// WHY FLEET FOLLOWS THE CHANNEL NOW. It used to be pinned to @latest with the note
+// "ours-fleet publishes no nightly tag". It does publish one, and the nightly stack
+// needs the fleet build carrying the SDK integration — the same architecture
+// boundary that made a mixed tg-connector fatal applies here. A nightly installer
+// that silently installs stable fleet is exactly the split-brain deployment the
+// channel exists to prevent.
+//
+// WHY COWORK STILL NEEDS ITS OWN ENTRY. It historically published its prerelease
+// line as `next`; the decision is that it aligns with every
+// other service and publishes `nightly` instead. The entry stays because the map,
+// not a hardcoded string, is what makes such a change one line — and because an
+// UNMAPPED package deliberately falls back to `latest` rather than a guessed tag.
+//
+// The nightly channel MUST reach cowork's prerelease line: the external-daemon
+// mode the Rooms step configures ships there (cowork PR #9), so a nightly
+// installer taking `latest` would pair a config carrying a `daemon` block with a
+// build that predates it — the same architecture-boundary mismatch this whole
+// mechanism exists to prevent, pointed at Rooms instead of Telegram.
+//
+// SEQUENCING — load-bearing, and not yet satisfied. cowork
+// publishes NO `nightly` dist-tag at all (its tags are latest=0.4.0 and
+// next=0.3.7-nightly.20260815.80ea770). `npm i -g @ours.network/cowork@nightly`
+// therefore 404s today, and a 404 fails the WHOLE install. So the nightly
+// installer must not be published until cowork's release flow has actually
+// published a `nightly` artifact carrying PR #9. Verify the tag exists AND that
+// the tarball contains the implementation — never trust the tag alone. See
+// coworkSupportsExternalDaemon for the guard that keeps a build without the mode
+// from ever being handed a daemon block.
 export const DEFAULT_CHANNEL = 'latest';
 
-// Packages that follow the selected channel (nightly ⇒ @nightly). Short keys map to
-// the @ours.network/<key> npm name. NOTE fleet is deliberately ABSENT — it is pinned.
-const CHANNEL_TRACKING_PKGS = new Set(['mcp', 'tg-connector', 'claude-code', 'codex', 'hermes']);
-// Packages ALWAYS pinned to @latest regardless of channel (no nightly tag exists).
-const STABLE_ONLY_PKGS = new Set(['fleet']);
+// Per-package dist-tag by channel. A package absent from this map, or missing a
+// key for the selected channel, installs @latest — this never guesses a tag that
+// might not exist, because a 404 fails the WHOLE install.
+const PKG_CHANNEL_TAGS = {
+  mcp: { nightly: 'nightly' },
+  'tg-connector': { nightly: 'nightly' },
+  'claude-code': { nightly: 'nightly' },
+  codex: { nightly: 'nightly' },
+  hermes: { nightly: 'nightly' },
+  fleet: { nightly: 'nightly' },
+  cowork: { nightly: 'nightly' }, // aligned with every other service
+};
 
 // Normalize a raw channel selection to 'latest' | 'nightly'. Anything unrecognized
-// (incl. undefined/'') falls back to the safe default 'latest' — never guesses a tag.
-export function resolveChannel(raw) {
+// (incl. undefined/'') falls back to the installer's OWN channel — never guesses a tag.
+//
+// WHY THE INSTALLER'S OWN VERSION IS A CHANNEL SIGNAL. `@ours.network/install` is
+// published on both dist-tags from the same lockstep bump (.github/workflows/scripts/
+// bump-versions.sh), so a nightly build carries a `-nightly.N` version and a stable
+// build does not. Without this, `npm i -g @ours.network/install@nightly && ours-install`
+// installed the nightly INSTALLER but @latest for everything it installs — which since
+// tg-connector 0.3.3-nightly.1 is not merely older but a DIFFERENT ARCHITECTURE (0.3.2
+// hosts its own ADAPT wrapper; the nightly attaches to the shared daemon over /api/v1,
+// which only the SDK-based daemon serves). Mixing the two tags across that boundary is
+// exactly the split-brain deployment this must not produce. A stable installer stays on
+// @latest and can never consume a nightly; an explicit OURS_CHANNEL always wins over both.
+export function resolveChannel(raw, selfVersion = '') {
   const v = String(raw || '').trim().toLowerCase();
   if (v === 'nightly' || v === 'prerelease' || v === 'next') return 'nightly';
-  return DEFAULT_CHANNEL; // 'latest' and everything else
+  if (v === 'latest' || v === 'stable') return DEFAULT_CHANNEL;
+  if (v) return DEFAULT_CHANNEL; // unrecognized: never guess, never inherit
+  return isNightlyVersion(selfVersion) ? 'nightly' : DEFAULT_CHANNEL;
 }
 
-// The npm dist-tag to install for one package key under a channel. fleet is ALWAYS
-// 'latest'; channel-tracking packages take the channel; anything else defaults to 'latest'.
+// A published nightly carries the `-nightly.N` prerelease suffix the bump script writes.
+export function isNightlyVersion(version) {
+  return /-nightly\.\d+/.test(String(version || ''));
+}
+
+// The npm dist-tag to install for one package key under a channel. Looks the key
+// up in PKG_CHANNEL_TAGS; anything unmapped — including an unknown package —
+// falls back to 'latest' rather than inventing a tag that would 404.
 export function pkgTag(pkgKey, channel = DEFAULT_CHANNEL) {
   const key = String(pkgKey || '').replace(/^@ours\.network\//, '');
-  if (STABLE_ONLY_PKGS.has(key)) return 'latest';
   const ch = resolveChannel(channel);
-  if (ch === 'nightly' && CHANNEL_TRACKING_PKGS.has(key)) return 'nightly';
-  return 'latest';
+  if (ch === DEFAULT_CHANNEL) return 'latest';
+  return PKG_CHANNEL_TAGS[key]?.[ch] ?? 'latest';
 }
 
 // Full `@ours.network/<key>@<tag>` spec for `npm i -g`, honoring the channel.
@@ -65,11 +126,266 @@ export function pkgSpec(pkgKey, channel = DEFAULT_CHANNEL) {
   return `@ours.network/${key}@${pkgTag(key, channel)}`;
 }
 
-// The Telegram connector owns 3051 — the installer must never hand a daemon that port.
-export const RESERVED_PORTS = [3051];
+// Ports other components in the stack own, which the installer must never hand a
+// daemon: 3051 is the Telegram connector's, 3052 is ours-cowork's loopback console
+// (its config default; see COWORK_DEFAULT_PORT).
+export const RESERVED_PORTS = [3051, 3052];
 export const DEFAULT_PORT = 3050;
 export const DEFAULT_BROKER = 'wss://broker1.ours.network';
 
+// ── Handing the Telegram connector the ONE shared daemon ───────────────────────
+// The connector has its OWN config file and never inherits the daemon's. Two
+// generations of it are in the wild and the installer must satisfy BOTH, because
+// which one gets installed is a channel decision (see pkgTag):
+//
+//   @nightly (>=0.3.3-nightly.1) — SDK-based. It ATTACHES to an already-running
+//     ours daemon over /api/v1 and has NO broker at all. It selects the daemon
+//     through @ours.network/sdk's resolveDaemonConfig, whose behaviour we verified
+//     against the published SDK 0.1.2 (the version the nightly pins):
+//       · with no overrides it reports configPath: null — the daemon's
+//         ~/.ours/config.json is NEVER read implicitly, so a daemon on any port
+//         other than the built-in 3050 is simply MISSED.
+//       · pointing OURS_CONFIG at that file, or passing an endpoint alone, throws
+//         INCOHERENT_SELECTION: "the endpoint was selected … but the state
+//         directory is the built-in default" — a deliberate credential-disclosure
+//         guard that refuses BEFORE any token is read.
+//       · endpoint AND state dir together resolve cleanly.
+//     So the ONLY correct contract is to give it BOTH daemonUrl and daemonStateDir.
+//
+//   @latest (<=0.3.2) — the older self-hosting ADAPT wrapper. It ignores
+//     daemonUrl/daemonStateDir and meets the daemon at a BROKER instead, so its
+//     brokerUrl must match the daemon's or the two can never see each other.
+//
+// Writing all three keys satisfies whichever generation is installed: each reads
+// only the keys it understands and ignores the rest. This matters at INSTALL time
+// specifically, because `ours-tg-connector install-service` BAKES its resolved
+// values into the service unit as environment variables, and env outranks the
+// config file forever after — a divergence created here can never be repaired by
+// editing that file.
+
+// The daemon's loopback endpoint. The daemon always binds 127.0.0.1 (never a
+// hostname), so this is the address the connector must be given.
+export function daemonEndpoint(port) {
+  return `http://127.0.0.1:${port}`;
+}
+
+// The broker the whole deployment shares, for a <=0.3.2 connector.
+// Precedence: what the user chose in THIS run > what the running daemon actually
+// resolved (`ours daemon status`, which accounts for the selected config) > what
+// the daemon's config file says > the built-in default (identical to the daemon's
+// DEFAULT_CONFIG.brokerUrl, so "no answer anywhere" still agrees).
+export function resolveSharedBroker({ chosenBroker, statusBroker, configBroker } = {}) {
+  for (const candidate of [chosenBroker, statusBroker, configBroker]) {
+    const v = validateBroker(candidate ?? '');
+    if (!v.empty && v.ok) return v.value;
+  }
+  return DEFAULT_BROKER;
+}
+
+// The Telegram connector's own config file (mirrors its src/config.ts: OURS_TG_CONFIG,
+// else <home>/.ours-telegram/config.json — a FIXED location, independent of its stateDir).
+export function tgConfigPath(env = {}, home = '') {
+  return env.OURS_TG_CONFIG || `${home}/.ours-telegram/config.json`;
+}
+
+// Decide whether the connector's config needs a write, and what to write. Returns
+// { changed, text, previous } — `changed` is false when the file already names this
+// exact daemon and broker, so an idempotent re-run touches nothing. Unrelated keys
+// the user or the connector added (bot tokens, STT settings) are preserved.
+export function planTgDaemonConfig(existing, { daemonUrl, daemonStateDir, brokerUrl } = {}) {
+  const base = existing && typeof existing === 'object' ? existing : {};
+  const str = (v) => (typeof v === 'string' ? v : '');
+  const previous = {
+    daemonUrl: str(base.daemonUrl),
+    daemonStateDir: str(base.daemonStateDir),
+    brokerUrl: str(base.brokerUrl),
+  };
+  const next = { daemonUrl, daemonStateDir, brokerUrl };
+  const changed = Object.entries(next).some(([k, v]) => v !== undefined && previous[k] !== v);
+  if (!changed) return { changed: false, text: '', previous };
+  return { changed: true, text: mergeConfig(base, next), previous };
+}
+
+// ── 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:
+//
+//   ~/.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
+//               running that way).
+//     present ⇒ { mode: 'external', endpoint: 'http://127.0.0.1:<port>',
+//                 stateDir: '<absolute ours-daemon state dir>' }
+//   External REQUIRES both endpoint and stateDir. cowork never stores or asks for
+//   a token — its SDK reads <stateDir>/daemon-token, which is why the state
+//   directory is part of the selection rather than derivable from the endpoint.
+//   Env equivalents: OURS_COWORK_DAEMON_MODE / _ENDPOINT / _STATE_DIR, and the
+//   service unit carries only those — never a token.
+//   Boot is FAIL-CLOSED: an unavailable endpoint, a non-ours daemon, or a
+//   stateDir that does not match it aborts startup. There is no embedded
+//   fallback, so writing this block is a real commitment and must never be done
+//   to an install that did not ask for it.
+//
+// NOTE the two different `stateDir` keys. The TOP-LEVEL one is cowork's own
+// private state. `daemon.stateDir` is the OURS daemon's state directory, where
+// that daemon's API token lives. Confusing them fails closed at boot.
+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
+// 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.
+export const COWORK_EXTERNAL_MIN_VERSION = '0.4.1-nightly.20260816.4aaf940';
+
+// Does the cowork build actually on this machine support an external daemon?
+//
+// This is deliberately a VERSION check and not a channel check. A channel gate
+// would answer "yes" for any nightly install, including one made before this
+// version was published — and a `daemon` block handed to a build without the mode
+// meets a strict config and a fail-closed boot, i.e. Rooms that will not start.
+// The version is read after the install, so it describes what is really there.
+// An unreadable version yields -1 below and therefore "no", which keeps Rooms
+// embedded rather than guessing.
+export function coworkSupportsExternalDaemon(installedVersion = '', minVersion = COWORK_EXTERNAL_MIN_VERSION) {
+  if (!minVersion) return false;   // no published build supports it yet
+  return compareVersions(String(installedVersion || ''), minVersion) >= 0;
+}
+
+// Semver precedence, enough for a published-release floor: x.y.z numerically,
+// then prerelease rules — a release outranks a prerelease of the same core
+// version, and two prereleases compare identifier by identifier (numeric parts
+// numerically, so nightly.20260815 < nightly.20260816). Returns -1 / 0 / 1, and
+// -1 for anything unparseable, so garbage NEVER claims to be new enough.
+export function compareVersions(a, b) {
+  const split = (v) => {
+    const m = String(v ?? '').match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+    return m ? { core: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null } : null;
+  };
+  const x = split(a);
+  const y = split(b);
+  if (!x || !y) return -1;
+  for (let i = 0; i < 3; i++) {
+    if (x.core[i] !== y.core[i]) return x.core[i] > y.core[i] ? 1 : -1;
+  }
+  if (x.pre === null && y.pre === null) return 0;
+  if (x.pre === null) return 1;   // 1.0.0 outranks 1.0.0-nightly.1
+  if (y.pre === null) return -1;
+  const xs = x.pre.split('.');
+  const ys = y.pre.split('.');
+  for (let i = 0; i < Math.max(xs.length, ys.length); i++) {
+    const xi = xs[i];
+    const yi = ys[i];
+    if (xi === undefined) return -1;         // a shorter identifier set is lower
+    if (yi === undefined) return 1;
+    const xn = /^\d+$/.test(xi);
+    const yn = /^\d+$/.test(yi);
+    if (xn && yn) {
+      if (Number(xi) !== Number(yi)) return Number(xi) > Number(yi) ? 1 : -1;
+    } else if (xn !== yn) {
+      return xn ? -1 : 1;                    // numeric identifiers rank below alphanumeric
+    } else if (xi !== yi) {
+      return xi > yi ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
+// Which daemon an existing cowork config is set up for. No block ⇒ embedded.
+export function coworkDaemonMode(existing) {
+  const block = existing && typeof existing === 'object' ? existing.daemon : null;
+  if (!block || typeof block !== 'object') return 'embedded';
+  return block.mode === 'external' ? 'external' : 'embedded';
+}
+
+// Build the external `daemon` block. Returns { ok, block, reason } — external is
+// refused without BOTH halves rather than written half-formed, because a partial
+// block fails closed at cowork's boot and the user would only find out then.
+export function coworkDaemonBlock({ endpoint, stateDir } = {}) {
+  const e = String(endpoint || '').trim();
+  const s = String(stateDir || '').trim();
+  if (!e || !s) {
+    return { ok: false, block: null, reason: 'an external daemon needs BOTH an endpoint and its state directory' };
+  }
+  return { ok: true, block: { mode: 'external', endpoint: e, stateDir: s }, reason: '' };
+}
+
+// The cowork config file (mirrors its docs/03-configuration.md: OURS_COWORK_CONFIG,
+// else <home>/.ours-cowork/config.json).
+export function coworkConfigPath(env = {}, home = '') {
+  return env.OURS_COWORK_CONFIG || `${home}/.ours-cowork/config.json`;
+}
+
+// Decide whether cowork's config needs a write, and what to write. Same contract
+// as planTgDaemonConfig: { changed, text, previous }, unchanged ⇒ nothing written,
+// so a re-run is a no-op. Its `rest` block is merged rather than replaced, so an
+// operator's explicit `rest.enabled: false` survives a port update.
+// `daemon` is three-valued on purpose:
+//   undefined — do not touch the daemon selection at all (an existing embedded
+//               install this run was not asked to migrate)
+//   null      — EMBEDDED: remove any block, cowork hosts its own daemon again
+//   {endpoint, stateDir} — EXTERNAL: point it at that ours daemon
+export function planCoworkConfig(existing, { brokerUrl, stateDir, restPort, daemon } = {}) {
+  const base = existing && typeof existing === 'object' ? existing : {};
+  const baseRest = base.rest && typeof base.rest === 'object' ? base.rest : {};
+  const previous = {
+    brokerUrl: typeof base.brokerUrl === 'string' ? base.brokerUrl : '',
+    stateDir: typeof base.stateDir === 'string' ? base.stateDir : '',
+    restPort: Number.isInteger(baseRest.port) ? baseRest.port : null,
+    daemonMode: coworkDaemonMode(base),
+    daemonEndpoint: base.daemon?.endpoint ?? '',
+    daemonStateDir: base.daemon?.stateDir ?? '',
+  };
+
+  let nextDaemon;                       // undefined ⇒ leave the block alone
+  let daemonChanged = false;
+  if (daemon === null) {
+    nextDaemon = null;
+    daemonChanged = previous.daemonMode !== 'embedded';
+  } else if (daemon !== undefined) {
+    const built = coworkDaemonBlock(daemon);
+    if (!built.ok) return { changed: false, text: '', previous, error: built.reason };
+    nextDaemon = built.block;
+    daemonChanged = previous.daemonMode !== 'external'
+      || previous.daemonEndpoint !== built.block.endpoint
+      || previous.daemonStateDir !== built.block.stateDir;
+  }
+
+  const changed = daemonChanged
+    || (brokerUrl !== undefined && previous.brokerUrl !== brokerUrl)
+    || (stateDir !== undefined && previous.stateDir !== stateDir)
+    || (restPort !== undefined && previous.restPort !== restPort);
+  if (!changed) return { changed: false, text: '', previous };
+
+  const patch = { version: 1 };
+  if (brokerUrl !== undefined) patch.brokerUrl = brokerUrl;
+  if (stateDir !== undefined) patch.stateDir = stateDir;
+  if (restPort !== undefined) patch.rest = { ...baseRest, enabled: baseRest.enabled ?? true, port: restPort };
+  if (nextDaemon !== undefined) patch.daemon = nextDaemon;
+  const merged = mergeConfig(base, patch);
+  // mergeConfig keeps every key it is handed; an EMBEDDED selection has to drop
+  // the block outright, since `daemon: null` is not the same as no block.
+  if (nextDaemon === null) {
+    const obj = JSON.parse(merged);
+    delete obj.daemon;
+    return { changed: true, text: JSON.stringify(obj, null, 2) + '\n', previous };
+  }
+  return { changed: true, text: merged, previous };
+}
+
 // 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).
@@ -201,7 +517,7 @@ export function parseVersion(text) {
   return m ? m[0] : '';
 }
 
-// parseStatus: read the daemon's RESOLVED broker + port out of `ours-mcp status` output, so we
+// parseStatus: read the daemon's RESOLVED broker + port out of `ours daemon 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
@@ -209,7 +525,10 @@ export function parseVersion(text) {
 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);
+  // `api:` is the current line and `url:` the historical one. Both are matched
+  // because a newly installed CLI can be asked to report on an older running
+  // daemon, and a parser that knows only today's wording reads that as "no port".
+  const pm = s.match(/(?:api|url):\s*https?:\/\/[^:\s/]+:(\d+)/i);
   return {
     broker: bm ? bm[1] : null,
     port: pm ? Number.parseInt(pm[1], 10) : null,
@@ -253,7 +572,7 @@ export function detectPlatform({ platform, release = '', env = {} } = {}) {
 //               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
+// The golden rule: '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' };
@@ -274,7 +593,7 @@ export function harnessAvailable(status) { return status === 'ok'; }
 // 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 } = {}) {
+export function buildHandoffPrompt({ identity = false, fleet = false, telegram = false, rooms = false } = {}) {
   const steps = [];
   if (identity) {
     steps.push(
@@ -296,6 +615,13 @@ export function buildHandoffPrompt({ identity = false, fleet = false, telegram =
       '   give me the invite link to send.',
     );
   }
+  if (rooms) {
+    steps.push(
+      'Set up my first Rooms mission room: ask me what the room is for and what\n' +
+      '   to call it, create it, then walk me through inviting the people and\n' +
+      '   agents who should have a seat.',
+    );
+  }
   if (steps.length === 0) return { text: '', empty: true };
   const numbered = steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
   const text =