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

package/README.md

@@ -43,37 +43,154 @@ dependency on the things it installs): an ASCII banner, tasteful colour (degrade
    answers `--version` promptly. A shell alias / hanging wrapper is **never called** (that would
    hang the run) — it's reported plainly with a fix, and a manual-install path is always offered.
    If neither harness exists it says so and exits.
-2. **Config-first** (first install only) — the daemon's two base settings, up front:
-   the **broker** (end-to-end encrypted; the broker never sees message content — almost everyone
-   just presses Enter) and the **port** (probes `3050`; only asks if it's busy; never hands out
-   `3051`, reserved for the Telegram connector). Applied once, then the stack is built with it.
-3. **Four consent gates**, each paced with a clean `✓ … No problems.` line + an explicit
+2. **Five consent gates**, each paced with a clean `✓ … No problems.` line + an explicit
    **Continue?** — never a start-twice-then-ask, never a silent failure:
-   - **1/4 ours core (the daemon)** — write config → optional voice setup → install/start ONCE
-     → boot service. On a re-run it reuses the running config (no re-ask) and only updates when
-     you say yes. Complete voice setup is kept without prompting. Missing/incomplete setup is
-     offered before the first start or pending update restart, then delegated to the canonical
-     `ours-mcp voice-setup` provider selector and hidden API-key prompt. Accepted setup owns the
-     one restart/readiness transaction; declining or already-ready setup preserves the normal
-     core lifecycle. The secret is written atomically to mode-`0600` config; a failed daemon
-     reload rolls back.
-   - **2/4 harness plugins** — the installer **drives the plugin CLIs itself**
+   - **1/5 the shared ours daemon** — its own step, before every consumer, and it owns its own
+     configuration: the **broker** (end-to-end encrypted; the broker never sees message content —
+     almost everyone just presses Enter) and the **listen port**, which is now an explicit
+     question rather than one you only hear about when `3050` is busy. The default is still
+     `3050` (the next free port when that is taken), so **Enter and every non-interactive run
+     land exactly where they always did**. The answer is validated (a real port, not reserved by
+     another component, not already in use, not already claimed by another daemon in this run),
+     persisted to `~/.ours/config.json`, and it is the endpoint everything below is wired to.
+     Then: write config → optional voice setup → install/start ONCE → boot service. On a re-run
+     it reuses the running config (no re-ask) and only updates when you say yes. Complete voice
+     setup is kept without prompting. Missing/incomplete setup is offered before the first start
+     or pending update restart, then delegated to the canonical `ours-mcp voice-setup` provider
+     selector and hidden API-key prompt. Accepted setup owns the one restart/readiness
+     transaction; declining or already-ready setup preserves the normal core lifecycle. The
+     secret is written atomically to mode-`0600` config; a failed daemon reload rolls back.
+   - **2/5 harness plugins** — the installer **drives the plugin CLIs itself**
      (`claude plugin marketplace add …` + `claude plugin install ours@ours.network`;
      `codex plugin marketplace add …` + `codex plugin add ours@ours-codex-marketplace`). Choosing
      Codex also installs the `ours-codex` live launcher in the same step. Any failure / alias
      prints the exact manual commands and continues — it **never dead-ends**.
-   - **3/4 ours-fleet** — makes your harnesses persistent, always-online agent teams that survive
+   - **3/5 ours-fleet** — makes your harnesses persistent, always-online agent teams that survive
      a reboot; runs `ours-fleet init`. Default **Yes**.
-   - **4/4 Telegram connector** — install-only (no bot tokens here), then optionally as a
-     boot service.
-4. **Summary + hand-off** — a recap (skipped/failed rows call out the fix), then a **literal
-   copy-paste prompt** (root identity + fleet + Telegram) with the steps for any skipped/failed
-   component dropped out. Copied to the clipboard where supported.
+   - **4/5 Telegram connector** — install-only (no bot tokens here), then a question asked
+     **independently of every other consumer**: use the shared daemon from step 1, or run against
+     its **own dedicated daemon**? Default (and Enter, and non-interactive) is the shared one.
+     A dedicated daemon is provisioned with its own port, its own state directory
+     (`~/.ours-tg`) and its own boot unit (`ours-tg.service`), and the connector is wired to
+     that endpoint. Then optionally installed as a boot service itself.
+   - **5/5 Rooms (ours-cowork)** — durable mission rooms. Default **No**. Configures its own
+     surface (the deployment's broker, its state directory `~/.ours-cowork`, and its loopback
+     **console port** — default `3052`, validated the same way), then asks the same
+     shared-vs-dedicated daemon question, defaulting to shared. A dedicated Rooms daemon gets
+     `~/.ours-rooms` and `ours-rooms.service`. Then `ours-cowork install-service`. See
+     **Daemon topology** for when the question is asked at all.
+3. **Summary + hand-off** — a recap (skipped/failed rows call out the fix), then a **literal
+   copy-paste prompt** (human identity + fleet + Telegram + Rooms) with the steps for any
+   skipped/failed component dropped out. Copied to the clipboard where supported.
 
 The human identity is created idempotently after the daemon becomes reachable. Because
 `curl … | bash` gives the script its input over the pipe, every prompt is read from the
 controlling terminal (`/dev/tty`), so the flow still works piped.
 
+## Daemon topology
+
+A clean deployment installs, configures and starts **one shared** ours daemon first, then wires
+every client to that same daemon. That is the default and the backward-compatible answer.
+
+**Optional isolation.** The Telegram connector and Rooms may each instead be given their own
+daemon, chosen independently of one another. Isolation is only real when all three of these are
+separate, which is what the installer provisions:
+
+| | shared | dedicated (Telegram) | dedicated (Rooms) |
+|---|---|---|---|
+| listen port | your step-1 answer | its own, validated against every other daemon in the run | likewise |
+| state directory | `~/.ours` | `~/.ours-tg` — the daemon's API token lives here | `~/.ours-rooms` |
+| boot unit | `ours.service` | `ours-tg.service` (via `OURS_SERVICE_NAME`) | `ours-rooms.service` |
+| config file | `~/.ours/config.json` | `~/.ours-tg/config.json` | `~/.ours-rooms/config.json` |
+
+Without a distinct service name, `ours-mcp install-service` would write the **same** unit for
+both and the second daemon would silently overwrite the first's port and state directory. See
+`packages/core/src/service-instance.ts`; a daemon with no instance name keeps exactly the
+historical `ours.service` / `solutions.adaptframework.ours`.
+
+**Rooms has a third answer.** `ours-cowork` used to host its own daemon, always. It now also
+supports an **external** one, so Rooms answers the same shared-vs-dedicated question — plus
+`embedded`, cowork's own, which is what every install predating that support runs.
+
+Its config carries an optional `daemon` block. Absent means embedded; external is
+`{ mode: 'external', endpoint, stateDir }` and **requires both halves**, because cowork stores no
+token and its SDK reads `<stateDir>/daemon-token`. Env equivalents are `OURS_COWORK_DAEMON_MODE`
+/ `_ENDPOINT` / `_STATE_DIR`, and the service unit carries only those — never a token.
+
+Two things follow from cowork's boot being **fail-closed** (an unreachable endpoint, a non-ours
+daemon, or a mismatched state directory aborts startup, with no embedded fallback):
+
+- A build that **predates** the external mode is never handed a block. The check is on the
+  **installed version**, not the channel: `COWORK_EXTERNAL_MIN_VERSION` in `lib/logic.mjs` is
+  pinned to `0.4.1-nightly.20260816.4aaf940`, the first published cowork that implements it
+  (verified against the registry *and* the tarball's contents). A channel-only gate would have
+  accepted an earlier nightly of the same core version. `cowork@latest` (0.4.0) predates the
+  mode, so the stable installer keeps Rooms embedded, names the build it found and the version it
+  needed, and points at `OURS_CHANNEL=nightly`. An unreadable version keeps Rooms embedded too —
+  it never guesses.
+- An install **already running embedded** is never migrated behind the user's back — headless
+  runs leave it exactly as it is, and interactive runs ask first.
+
+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. Confusing them fails closed at boot.
+
+What wiring a client to a daemon takes differs per client:
+
+- **The harness plugins** need nothing extra: each is `ours-mcp proxy`, which reads the daemon's
+  own config (`OURS_CONFIG`, else `~/.ours/config.json`). `autoStart` is off by default, so a proxy
+  whose daemon is down reports it rather than quietly starting a second one.
+- **The Telegram connector keeps its own config file** and never inherits the daemon's, so the
+  installer writes `~/.ours-telegram/config.json` (honouring `OURS_TG_CONFIG`) **before** the
+  connector is started or installed as a service — `install-service` bakes whatever it resolves
+  into the service unit as environment variables, and those outrank the file from then on.
+  Three keys are written, so whichever connector generation is installed finds what it reads:
+  - `daemonUrl` + `daemonStateDir` — for `>=0.3.3-nightly.1`, which attaches to the running daemon
+    over `/api/v1`. **Both** are required: with neither, its SDK never reads `~/.ours/config.json`
+    and falls back to the built-in `127.0.0.1:3050`, missing a daemon on any other port; with the
+    endpoint alone it refuses outright (`INCOHERENT_SELECTION` — the daemon's API token belongs to
+    a state directory, so selecting an endpoint without one would disclose that token).
+  - `brokerUrl` — for `<=0.3.2`, which hosts its own ADAPT wrapper and meets the daemon at a broker
+    instead. It must match the daemon's or the two can never see each other.
+
+  A re-run that changes nothing rewrites nothing, and keys the installer does not own are preserved.
+
+If `ours-mcp install-service` fails (no systemd user bus, no linger, a container, WSL without
+systemd) it has already **stopped** the daemon it was about to supervise. The installer restarts it
+and says plainly that the boot service is missing — a clean deployment never ends with no daemon
+while the summary claims success.
+
+## Release channel
+
+`OURS_CHANNEL=nightly` (or `OURS_INSTALL_CHANNEL`) installs each package's **own** prerelease
+dist-tag. The tag is not the same string everywhere, so the mapping is per package:
+
+| package | stable channel | nightly channel |
+|---|---|---|
+| `mcp`, `tg-connector`, `claude-code`, `codex`, `hermes` | `latest` | `nightly` |
+| `fleet` | `latest` | `nightly` |
+| `cowork` (Rooms) | `latest` | `nightly` |
+
+`fleet` follows the channel: it publishes its own `nightly` dist-tag, and the nightly stack needs
+the fleet build carrying the SDK integration. A nightly installer that quietly installed stable
+fleet is the same split-brain deployment the channel exists to prevent.
+
+`cowork` publishes `nightly` alongside every other service (it previously used `next`). The
+nightly channel must reach that line, because the external-daemon mode the Rooms step configures
+ships there; taking `latest` would pair a config carrying a `daemon` block with a build that
+predates it.
+
+A package with no mapping for the selected channel installs `@latest` rather than a guessed tag,
+because a 404 fails the *whole* install — which is also why the nightly installer must not be
+published before every package it names actually has the tag it will ask for.
+
+**With no explicit selection the installer follows its own version.** A published nightly build
+carries the `-nightly.N` suffix the release bump stamps, so `npm i -g @ours.network/install@nightly`
+builds a nightly stack, and a stable installer can never consume a nightly. This is load-bearing
+rather than cosmetic: across `tg-connector` 0.3.2 → 0.3.3-nightly.1 the connector stopped hosting
+its own ADAPT wrapper and became a client of the shared daemon, so mixing tags across that boundary
+pairs a connector that needs `/api/v1` with a daemon that does not serve it. `OURS_CHANNEL` still
+overrides in both directions.
+
 ## Non-interactive / CI / safe dry-run
 
 ```sh
@@ -96,6 +213,15 @@ is reported and left unchanged.
 | `OURS_INSTALL_DRY_RUN` | walk the flow without installing or changing anything |
 | `OURS_NPM` | npm binary to use (default `npm`) |
 | `OURS_CONFIG` | daemon config file location (default `~/.ours/config.json`) |
+| `OURS_STATE_DIR` | daemon state directory (default `~/.ours`) — also what the Telegram connector is told to expect |
+| `OURS_TG_CONFIG` | Telegram connector config file location (default `~/.ours-telegram/config.json`) |
+| `OURS_COWORK_CONFIG` | Rooms config file location (default `~/.ours-cowork/config.json`) |
+| `OURS_COWORK_DAEMON_MODE` / `_ENDPOINT` / `_STATE_DIR` | cowork's own env equivalents of its `daemon` block (read by cowork, not set by the installer) |
+| `OURS_CHANNEL` | `nightly` or `latest`; unset follows the installer's own version |
+
+A non-interactive run takes the shared daemon on its existing default port and installs no
+dedicated daemon and no Rooms — the topology is unchanged from before this flow existed. It also
+never converts an existing embedded Rooms install to an external daemon.
 
 ## Uninstall
 
@@ -138,9 +264,11 @@ OURS_UNINSTALL_DAEMON=yes \
 - This package is **not published to npm** (`private: true`); it ships as the hosted
   `install.sh` bootstrap plus the `install.mjs` Node installer (and its `lib/`), and exposes the
   `ours-install` bin. The pieces it installs — the daemon (`@ours.network/mcp`), the harness
-  plugins via each marketplace, `@ours.network/fleet`, and `@ours.network/tg-connector` — are the
-  published components.
+  plugins via each marketplace, `@ours.network/fleet`, `@ours.network/tg-connector`, and
+  `@ours.network/cowork` — are the published components.
 - **Idempotent + safe to re-run.** A re-run adds a skipped piece, re-points the plugins, or (only
   when you say yes) updates a component; an already-current daemon is left untouched, its running
-  port and complete voice setup are reused everywhere. Bot tokens and fleet roles remain in the
-  copy-paste hand-off; provider keys never enter that prompt or agent chat.
+  port and complete voice setup are reused everywhere — and the Telegram connector's daemon
+  selection, a dedicated daemon's config, and the Rooms config are each rewritten only if they
+  actually changed. Bot tokens and fleet roles remain in the copy-paste hand-off; provider keys
+  never enter that prompt or agent chat.