@mmmbuto/nexuscrew 0.8.7 → 0.8.10

package/README.md

@@ -16,7 +16,7 @@ panes, windows. tmux does the work; the browser is just a faithful client.
 
 ---
 
-## What it is (v0.8.7 "One-Link Pairing")
+## What it is (v0.8.10 "Hydra Federation")
 
 - Runs a small server on the host where your tmux sessions live.
 - Each attach spawns a real PTY running `tmux attach` and bridges its bytes over a WebSocket
@@ -24,16 +24,21 @@ panes, windows. tmux does the work; the browser is just a faithful client.
 - **Desktop grid** (≥1024px): drag sessions from the sidebar into a tiling column layout —
   live terminals side by side, draggable dividers, per-tile composer, layout remembered.
   Tiles attach with `ignore-size` so they never resize your real terminals.
-- **Multi-window decks**: named workspaces at `/deck/<name>` — one browser window per
-  monitor, each with its own remembered tile layout. The focused tile is the size owner;
-  everything else attaches with `ignore-size`.
+- **Ordered Fleet roster**: local and remote locations are independently collapsible and
+  filterable by all, pinned, active, or off. The desktop chrome stays fixed while the roster
+  scrolls; the mobile header stays visible above its own touch-scrolling list.
+- **Attached decks by default**: named workspaces switch as tabs inside the same PWA without
+  reloading terminals or losing a pending layout save. Use `↗` only when you want to detach a
+  deck into another browser window or monitor.
 - **Federated Hydra inventory**: connect existing NexusCrew installations through the SSH
   configuration you already control and see local, direct, and relayed tmux fleets in one UI.
   Route labels show where every session lives; creation, attach, files, lifecycle and Fleet
   management use the selected location through a scoped single-origin route.
 - **One-link node pairing**: paste a link or scan its QR in Settings → Nodes. A complete
   link tests SSH, exchanges the one-time invitation, confirms both directions and verifies
-  the peer automatically; failures identify the exact connection stage.
+  the peer automatically; failures identify the exact connection stage. A device already
+  connected to a hub creates invitations through that hub; a standalone hub asks only for
+  the SSH address by which the receiving device can reach it.
 - **Settings and wizard**: manage roles, nodes, token rotation, and service regeneration
   from the UI; the first-run wizard uses the same pairing flow as Settings.
 - **Cell lifecycle from the UI**: the primary `+` creates a managed Fleet cell at Local or
@@ -42,6 +47,9 @@ panes, windows. tmux does the work; the browser is just a faithful client.
 - **Legacy session adoption**: Settings → Fleet lists managed and unmanaged tmux sessions on
   every route. A live unmanaged session can be explicitly imported as a managed cell without
   inventing its engine, provider or model.
+- **Selective cell backup**: export chosen cells with their engine mapping and system prompt,
+  then select exactly which definitions to restore. Provider keys and runtime session state
+  are never exported; active cells that need a restart are reported explicitly.
 - **Rich cards**: last activity, current command, a sanitized one-line preview per session.
 - **Fleet control**: a built-in schema-driven fleet manager handles cells, engines, model
   selection, and boot persistence; an existing external `fleet` CLI can take ownership through
@@ -50,7 +58,14 @@ panes, windows. tmux does the work; the browser is just a faithful client.
 - **localhost-only**: the server binds `127.0.0.1` and refuses any non-loopback bind.
 - **Stateless**: tmux *is* the persistence. No database, no accounts.
 - **Mobile terminal controls**: long-press begins local text selection, drag extends it, and
-  the composer send button keeps the software keyboard open for the next message.
+  the composer sends long or multiline drafts through the terminal's real bracketed-paste
+  mode while keeping both failed drafts and the software keyboard ready.
+- **Desktop file paste/drop**: paste a clipboard image or drop files directly on the target
+  terminal. NexusCrew uploads them to that session's inbox—locally or through Hydra—and
+  inserts the saved paths without submitting Enter; ordinary text paste is unchanged.
+- **Safe npm auto-update**: global installs follow stable npm `latest` without downgrades,
+  serialize installation across processes, verify the restarted runtime and roll back once
+  to the exact previous version if the new server does not become healthy.
 - **Universal**: a PTY is a PTY — a coding agent, a REPL, a plain shell, anything tmux holds.
 
 ## Screenshots
@@ -63,7 +78,7 @@ The **Fleet Deck** desktop grid (≥1024px): drag sessions into a tiling layout
 terminals side by side, each a real PTY streamed to the browser.
 
 <p align="center">
-  <img src="docs/img/fleet-mobile.png" width="420" alt="NexusCrew mobile Fleet overview with managed AI cells and direct power controls">
+  <img src="docs/img/fleet-mobile.gif" width="420" alt="Animated NexusCrew mobile Fleet overview with managed AI cells and direct power controls">
 </p>
 
 The mobile Fleet overview keeps managed cells, current engines, activity and direct power
@@ -104,6 +119,12 @@ auto-compaction window variables, including one-million-token profiles where dec
 Custom argv-based engines remain supported. Their command, environment, cwd, and prompt are
 validated against a strict trust boundary and launched without a shell.
 
+Settings → Fleet also provides a selective **Cells backup** flow. The JSON file contains only
+portable cell definitions (cwd, engine choice, model mapping, boot flag and system prompt),
+never provider credentials, PWA tokens or live tmux identifiers. During restore you choose the
+destination engine for each cell and confirm overwrites; running cells are left untouched and
+listed as needing a restart.
+
 ### External fleet manager
 
 NexusCrew can instead act as a control panel for a *fleet manager* you already have: any
@@ -136,6 +157,9 @@ entirely.
 - **Node.js ≥ 18**
 - **tmux** on the host (3.4+; the non-destructive `ignore-size` attach is honored on 3.4 and
   later)
+- **OpenSSH client (`ssh`)** for Hydra nodes and a clean `nexuscrew doctor`. A local-only tmux
+  session does not invoke it, but the installation is reported degraded until it is present.
+  `autossh` is detected by doctor but is not required.
 - A PTY backend is resolved automatically per platform: Darwin ARM64/x64 and Linux ARM64/x64
   scriptless prebuilds, including the native Android ARM64 provider on Termux.
 
@@ -151,7 +175,7 @@ ssh -L 41820:127.0.0.1:41820 user@your-host
 # then run `nexuscrew show` on the machine where the browser is available
 ```
 
-autossh reverse tunnels or a VPN work the same way. A local **authentication token** (0600 file,
+A user-managed autossh tunnel or a VPN works the same way. A local **authentication token** (0600 file,
 auto-generated and passed directly to the browser by `nexuscrew show`) is a second factor on top of your SSH/VPN gate. The
 token travels in the URL **fragment** (`#token=…`), so it never reaches the server logs.
 
@@ -163,9 +187,10 @@ token travels in the URL **fragment** (`#token=…`), so it never reaches the se
 Every installation is always the local node and can join other NexusCrew nodes. The normal
 flow stays entirely in the PWA:
 
-1. On the installation being shared, open **Settings → Nodes → Invite a node**. Enter the
-   OpenSSH target or Host alias that the *other device* uses to reach this installation, then
-   create the ten-minute link/QR.
+1. On the installation being shared, open **Settings → Nodes → Invite a node** and create the
+   ten-minute link/QR. A device already connected to a hub uses that hub automatically.
+   A standalone hub needs one value: the OpenSSH target or Host alias that the *other device*
+   uses to reach it. This is not `127.0.0.1` and not a NexusCrew HTTP URL.
 2. On the other device, open its own NexusCrew PWA (`nexuscrew show`), go to
    **Settings → Nodes**, and use the first card, **Connect with one link**. Paste the complete
    link in the prominent field or scan the QR. Do not navigate to the loopback address in the
@@ -178,12 +203,21 @@ flow stays entirely in the PWA:
 
 The link never contains an SSH key, identity file, API key or PWA token. Its only credential is
 the random, one-time pairing invite; SSH routing fields are non-secret configuration. A
-successful pairing creates a reciprocal loopback-only link and both sides exchange a redacted
-topology automatically.
+successful pairing creates one supervised SSH connection to the hub. Its normal `-L` channel
+is private and provides access to the hub. The optional `-R` channel is added to that same SSH
+process only when the user enables **Share this node**, after which the hub verifies it before
+advertising the device. Both sides exchange only redacted topology.
+
+A newly paired phone or laptop is private by default: the hub keeps it in Settings without
+probing it as a server or showing a false red error. Enabling Share makes it routable and turns
+authenticated reverse-channel health into a real requirement; a shared node that stops
+responding, or a live endpoint that rejects authentication, remains a real health error.
 
 NexusCrew does not create SSH keys or edit `authorized_keys`. OpenSSH remains authoritative for
 identity files, agents, host keys, ports, ProxyJump and forwarding policy. NexusCrew uses
-`autossh` when available and otherwise its supervised `ssh`; configured links return at boot.
+one built-in retry supervisor around `ssh`; it never nests `autossh`. `nexuscrew doctor` reports
+whether both binaries are installed and states that OpenSSH is the transport actually used.
+Missing `ssh` is a blocking error; `autossh` is optional. Configured links return at boot.
 Pair credentials are random, per-peer and scoped only to the federated session/file surface—the
 PWA token never crosses a peer link.
 
@@ -198,7 +232,7 @@ transitive nodes remain listed as offline with their last-seen time while a rela
 ### Linux
 
 ```bash
-# Install Node.js 18+ and tmux 3.4+ with your distribution package manager first.
+# Install Node.js 18+, tmux 3.4+ and OpenSSH with your package manager first.
 npm install -g @mmmbuto/nexuscrew
 nexuscrew
 ```
@@ -225,7 +259,7 @@ distribution, so it does not require Developer ID signing.
 
 ```bash
 pkg update
-pkg install nodejs-lts tmux
+pkg install nodejs-lts tmux openssh
 npm install -g @mmmbuto/nexuscrew
 nexuscrew
 ```
@@ -241,6 +275,9 @@ exits:
 nexuscrew                 # background start; opens only on first run
 nexuscrew show            # background start when needed + open the authenticated PWA
 nexuscrew show token      # print the clickable authenticated URL; do not open a browser
+nexuscrew status          # compact service, port and hub-connection state
+nexuscrew stop            # stop server and every NexusCrew-managed SSH supervisor
+nexuscrew restart         # restart server; restore only autostart-enabled hub links
 nexuscrew boot            # opt in to startup persistence
 nexuscrew boot off        # disable startup persistence, keep the current run alive
 ```
@@ -251,8 +288,20 @@ the same authenticated NexusCrew instance, it is reused.
 
 Env knobs: `NEXUSCREW_PORT` (default 41820), `NEXUSCREW_CONFIG_FILE`,
 `NEXUSCREW_TOKEN_FILE`, `NEXUSCREW_FILES_ROOT`, `NEXUSCREW_TMUX`,
-`NEXUSCREW_FLEET=0`, and `NEXUSCREW_READONLY=1`. Set `NEXUSCREW_DEBUG=1` to log the
-resolved PTY provider at startup.
+`NEXUSCREW_FLEET=0`, `NEXUSCREW_READONLY=1`, and `NEXUSCREW_AUTO_UPDATE=0` to disable
+automatic stable npm updates. Set `NEXUSCREW_DEBUG=1` to log the resolved PTY provider at
+startup.
+
+### Automatic updates
+
+A global npm installation checks `@mmmbuto/nexuscrew@latest` shortly after startup and then
+periodically. A newer stable version is installed exactly once, preflighted through the CLI,
+and the active service or detached runtime is restarted on the same loopback port. If the new
+runtime fails its bounded health check, NexusCrew reinstalls the exact previous version and
+restarts once; that failed version is then blocked from automatic retry. The updater never
+accepts a prerelease from `latest`, never downgrades, and redacts registry credentials and local
+paths from PWA errors. Its current state and manual check/apply controls live in Settings →
+System. Set `NEXUSCREW_AUTO_UPDATE=0` (or `false`, `no`, `off`) to disable scheduling.
 
 ## CLI
 
@@ -274,7 +323,8 @@ by normal startup, help, doctor, or service output.
 
 `nexuscrew mcp` runs a minimal **stdio MCP server** (JSON-RPC 2.0, one JSON message per
 line, zero SDK dependencies) that brings NexusCrew *inside* your AI sessions. An agent
-running in a tmux session gets five tools — the cell→human channel:
+running in a tmux session gets six tools — the cell→human channel plus its
+read-only deck context:
 
 - `nc_notify {title, body?, urgency?}` — human notification: toast on every open UI +
   web push on subscribed devices (enable push from Settings → System).
@@ -284,11 +334,17 @@ running in a tmux session gets five tools — the cell→human channel:
   `NEXUSCREW_REPLY_LABEL`; bracketed paste, never submits).
 - `nc_send_file {path, caption?}` — copies a file (absolute path under HOME) into the
   session outbox: badge + notification, downloadable from the Files panel.
+- `nc_deck {}` — identifies the caller's tmux session and node, then returns every local or
+  authorized shared-owner deck that contains it. Deck identity is owner-qualified; members
+  include stable owner ID, Fleet cell name (when managed), exact tmux session and the Hydra
+  route valid from the caller. Unavailable members remain visible with `cell: null`.
 - `nc_status {}` / `nc_inbox {}` — read-only: live sessions + fleet cells / inbox files.
 
 The caller's identity is the tmux session name (`$TMUX` → `tmux display-message`), with
 `NEXUSCREW_MCP_SESSION` as fallback for non-tmux contexts. The bridge talks to the local
 HTTP API (loopback + token from `~/.nexuscrew/token`); the cell↔cell bus stays out of scope.
+`nc_deck` is discovery only: use the AI client's verified tmux-messaging workflow to contact
+another member, and never scrape `decks.json` directly.
 
 Register it in **Claude Code** (`.mcp.json` in your project root, or `~/.claude.json`):
 
@@ -335,7 +391,8 @@ node bin/nexuscrew.js serve
 
 ## Status
 
-The current stable release is **v0.8.7**, published on npm under the **`latest`** dist-tag.
+The current stable release is **v0.8.10**. npm **`latest`**, the GitHub tag and the release
+assets are promoted from the same verified artifact.
 
 ## License