@mmmbuto/nexuscrew 0.8.12 → 0.8.14

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.12 "Mobile Roster")
+## What it is (v0.8.14 "Private Launch")
 
 - 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
@@ -25,14 +25,19 @@ panes, windows. tmux does the work; the browser is just a faithful client.
   live terminals side by side, draggable dividers, per-tile composer, layout remembered.
   Tiles attach with `ignore-size` so they never resize your real terminals.
 - **Ordered Fleet roster**: desktop and mobile share the same per-location model. Local and
-  every Hydra route are independently collapsible and filterable by all, pinned, active, or
-  off; route-qualified pins and the deterministic pinned → live → fresh output → activity →
-  name order survive reloads. Search covers every visible node once the combined roster grows
-  beyond eight entries. Desktop chrome and the mobile header stay fixed while their lists
-  scroll, and the compact version/endpoint/language footer remains readable on narrow screens.
+  every Hydra route are independently collapsible and filterable by all, pinned, active, off,
+  or technical. Technical tmux sessions stay out of the normal roster until explicitly shown,
+  and every location count reflects the rows actually displayed. Route-qualified pins keep
+  priority, while cells can be reordered from the dedicated handle with Pointer Events on
+  mouse, touch, or pen, or with keyboard move controls. Reorder highlights the destination,
+  scrolls at list edges, commits only on release and can be cancelled without changing the
+  saved order. The owner-qualified order survives reloads and is shared by compact and expanded
+  views. Desktop chrome and the mobile header stay fixed while their lists scroll, and the
+  compact version/endpoint/language footer remains readable on narrow screens.
 - **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.
+  deck into another browser window or monitor. Every Local or remote owner group ends with its
+  own compact `+ new`, so the creation destination is explicit and never falls back elsewhere.
 - **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
@@ -47,12 +52,20 @@ panes, windows. tmux does the work; the browser is just a faithful client.
 - **Cell lifecycle from the UI**: the primary `+` creates a managed Fleet cell at Local or
   any reachable node. Power opens one shared launch sheet where engine, model, permission
   policy and boot can be reviewed before every start; deletion lives in Settings → Fleet.
+  An immediately exiting client reports bounded, redacted diagnostics and cannot leave a
+  zero-window phantom beside the configured cell.
 - **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.
+- **Selective cell and engine backup**: export chosen cells, reusable engine definitions,
+  engine mapping and system prompts, then select exactly what to restore. Archives contain
+  credential-variable names but never their values, provider keys or runtime session state;
+  conflicts and active cells that need a restart are reported explicitly.
+- **Private provider credentials**: each node resolves a required key from its runtime
+  environment, compatible user-owned provider files, or an optional local write-only store.
+  The PWA can set, replace, or forget a missing key on that exact node without displaying it.
+  Values never enter Fleet definitions, backups, API responses, tmux state, process arguments,
+  temporary files, or logs.
 - **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
@@ -70,6 +83,13 @@ panes, windows. tmux does the work; the browser is just a faithful client.
   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. On Linux, stopping
   or restarting the HTTP service preserves the independent shared tmux server and every session.
+  Registry checks and service processes use a stable NexusCrew working directory, so deleting
+  the directory from which NexusCrew was originally launched cannot break future updates.
+- **Authenticated cell network**: AI cells can discover the owner-qualified Fleet directory
+  visible through the authorized Hydra topology and submit bounded text to one exact active
+  destination. Inactive cells remain visible but are never presented as queued recipients;
+  a `submitted` receipt confirms only paste plus Enter in the target TUI, not that its model
+  accepted, processed or completed the task.
 - **Universal**: a PTY is a PTY — a coding agent, a REPL, a plain shell, anything tmux holds.
 
 ## Screenshots
@@ -107,10 +127,19 @@ The concise provider catalog is scoped per CLI:
   GitHub Copilot, OpenRouter, local Ollama, DeepSeek, Z.AI, and a custom provider.
 
 Provider credentials are resolved from the selected CLI's native login or from an environment
-variable named in the PWA; NexusCrew never stores a new secret value. Legacy Z.AI A/P engines
-remain launch-compatible for existing fleets but are not provider choices for new engines.
-Model discovery is used where the CLI/provider documents it, with a manual model field as the
-portable fallback.
+variable named in the PWA. A named variable is read first from the service environment, then
+from the optional node-local NexusCrew store, then—when present—from the user-owned
+`~/.config/ai-shell/providers.zsh`, `~/.config/keys/ai.env`, or
+`~/.config/secure/.env`, parsed strictly as assignment data and never sourced or executed.
+The PWA shows only whether the requested name is configured and its source category; a missing
+value can be saved locally in `~/.nexuscrew/credentials.json` under a user-owned `0700`
+directory and `0600` file, or removed again. The store is write-only through the API and is
+never included in config, services, Fleet backups, federation payloads, logs, or responses.
+At launch, secret-bearing environment data crosses a private one-shot Unix socket and reaches
+the CLI by direct process spawn; it never enters tmux environment state, argv, or a temporary
+file. Legacy Z.AI A/P engines remain launch-compatible for existing fleets but are not provider
+choices for new engines. Model discovery is used where the CLI/provider documents it, with a
+manual model field as the portable fallback.
 
 Managed engines expose a permission selector both in their definition and in the cell launch
 sheet. New Claude engines (native, Z.AI, Ollama, or custom) default to **Bypass permissions**
@@ -123,11 +152,14 @@ 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.
+Settings → Fleet also provides a selective **Cells and engines backup** flow. The v2 JSON file
+contains portable cell definitions (cwd, engine choice, model mapping, boot flag and system
+prompt) plus only the selected reusable engine definitions. Custom-engine environment-variable
+names are portable; their values, provider credentials, PWA tokens and live tmux identifiers
+are never exported. Legacy cell-only v1 files remain importable. Restore previews conflicts,
+lets you choose each section independently, confirms every overwrite before mutation, preserves
+only matching values already configured on the destination, and reports which active cells need
+a restart.
 
 ### External fleet manager
 
@@ -209,13 +241,17 @@ The link never contains an SSH key, identity file, API key or PWA token. Its onl
 the random, one-time pairing invite; SSH routing fields are non-secret configuration. A
 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.
+process only when the user enables **Share this device through the selected hub** in the local
+device card. The hub verifies the authenticated reverse channel before advertising the device;
+its inbound-node controls then decide whether authorized clients see the whole network,
+relay-only or a selected set. 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.
+probing it as a server or showing a false red error. Share always refers to the current local
+device—not to the remote hub card—and uses its already selected hub connection; no direct
+peer-to-peer SSH is required. 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
@@ -228,8 +264,9 @@ PWA token never crosses a peer link.
 A relay controls what its peers can see. The default is the whole network; a peer can be reduced
 to relay-only or a selected set. HTTP and WebSocket routing enforce that policy at every hop,
 with stable instance IDs, cycle rejection and a four-hop ceiling. Session creation, terminal,
-files, termination, and Fleet editing work on Local or any reachable route. Previously seen
-transitive nodes remain listed as offline with their last-seen time while a relay is down.
+files, termination, Fleet editing and authorized cell discovery work on Local or any reachable
+route. Previously seen transitive nodes remain listed as offline with their last-seen time while
+a relay is down.
 
 ## Install & run
 
@@ -273,7 +310,10 @@ nexuscrew
 Termux uses the Android ARM64 PTY provider. The normal command starts NexusCrew in the
 background and exits. `nexuscrew boot` installs the Termux:Boot script explicitly; install the
 Termux:Boot app and launch it once, because Android app activation cannot be verified by the
-CLI. `nexuscrew doctor` reports that limitation even when the script itself is valid.
+CLI. `nexuscrew doctor` reports that limitation even when the script itself is valid. Inside
+managed cells, npm-installed Codex and Codex-VL scripts are launched through the active Node
+executable when their shebang depends on the unavailable `/usr/bin/env`; native executables
+such as Pi remain direct launches.
 
 On every platform the first run starts the server in the background and opens the PWA wizard.
 After onboarding, the same command starts or reuses it, prints a compact status and guide, and
@@ -308,8 +348,10 @@ and the active service or detached runtime is restarted on the same loopback por
 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.
+paths from PWA errors. Registry commands run from a stable directory owned by NexusCrew and
+accept npm's JSON scalar or plain semantic-version output. Its current state and manual
+check/apply controls live in Settings → System. Set `NEXUSCREW_AUTO_UPDATE=0` (or `false`,
+`no`, `off`) to disable scheduling.
 
 On Linux, the installed service uses `KillMode=process`: service lifecycle affects NexusCrew,
 not the shared tmux server. Existing units are protected by an atomic drop-in before any CLI or
@@ -336,8 +378,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 six tools — the cell→human channel plus its
-read-only deck context:
+running in a tmux session gets eight tools: the cell→human channel, read-only deck context,
+and an authenticated active-cell network:
 
 - `nc_notify {title, body?, urgency?}` — human notification: toast on every open UI +
   web push on subscribed devices (enable push from Settings → System).
@@ -351,13 +393,24 @@ read-only deck context:
   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_cells {}` — returns the owner-qualified Fleet directory visible through the caller's
+  authorized, non-stale Hydra topology. Every entry has a stable `<instanceId>:<cell>` ID,
+  exact tmux session and route, activity state and `canReceive`; duplicate cell names on
+  different devices remain unambiguous.
+- `nc_send_cell {to, message}` — submits bounded text to one exact ID returned by `nc_cells`.
+  The caller must itself be an active local Fleet cell, the destination must still be active,
+  and every remote hop rechecks identity and ACL. There is no silent offline queue. A
+  `submitted` receipt means only that bracketed paste and a separate Enter reached the target
+  TUI; it does not mean accepted, working or completed.
 - `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.
+HTTP API (loopback + token from `~/.nexuscrew/token`). Use `nc_deck` for visual workspace
+neighbours and `nc_cells` for the global authorized directory; use `nc_send_cell` for managed
+cell delivery. Direct tmux injection is only a declared same-host compatibility or repair
+fallback and must never bypass Fleet membership or Hydra ACLs. Never scrape `decks.json`
+directly.
 
 Register it in **Claude Code** (`.mcp.json` in your project root, or `~/.claude.json`):
 
@@ -404,8 +457,9 @@ node bin/nexuscrew.js serve
 
 ## Status
 
-The current release candidate is **v0.8.12**. npm **`latest`**, the GitHub tag and the release
-assets are promoted from the same verified artifact.
+The current release candidate is **v0.8.14**. npm **`latest`** is promoted from the verified
+artifact first; the GitHub tag and release follow the operator field test from the same source
+candidate.
 
 ## License