@akshar5/cohall 0.4.9 → 0.5.0

package/docs/install.md

@@ -72,12 +72,14 @@ npx -y @akshar5/cohall pair --label "Workstation"
 unset owner_token
 ```
 
-Transfer it privately. On the machine being added, provide it through stdin so
-it does not appear in process arguments or shell history:
+Transfer it privately. On the machine being added, `cohall init` collects any
+missing values interactively, exchanges the pairing token, writes the
+configuration, and installs the Cohall skill. Provide the token through stdin
+so it does not appear in process arguments or shell history:
 
 ```bash
 read -rsp 'Pairing token: ' pairing_token; printf '\n'
-printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
+printf '%s' "$pairing_token" | npx -y @akshar5/cohall init \
   --relay https://cohall.example.com \
   --name workstation \
   --providers codex \
@@ -85,6 +87,11 @@ printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
 unset pairing_token
 ```
 
+When run in a terminal, omitted relay, name, workspace, provider, and token
+values are prompted with useful defaults. Re-running `cohall init` repairs the
+skill installation and reuses credentials when the selected relay has not
+changed. `cohall join` remains the non-guided configuration primitive.
+
 Workspace roots must already exist. Cohall resolves them to canonical paths and
 rejects delegated work outside them.
 
@@ -93,7 +100,7 @@ For a client that submits work but never runs a device worker:
 ```bash
 npx -y @akshar5/cohall pair --client-only --label "Automation client"
 read -rsp 'Pairing token: ' pairing_token; printf '\n'
-printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
+printf '%s' "$pairing_token" | npx -y @akshar5/cohall init \
   --relay https://cohall.example.com \
   --client-only
 unset pairing_token
@@ -102,6 +109,20 @@ unset pairing_token
 Automation may use a mode-`0600` token file with `join --token-file
 /path/to/token`.
 
+## Keep a device available
+
+After a global installation, install and start the current user's device
+service with one command:
+
+```bash
+cohall service install
+cohall doctor
+```
+
+Linux uses a systemd user service, macOS uses a LaunchAgent, and Windows uses a
+per-user scheduled task. The installer records the exact global Cohall
+executable, so it refuses temporary package-runner and source-checkout paths.
+
 ## Providers
 
 Target devices advertise provider executables they can find. Authentication is
@@ -123,9 +144,13 @@ cohall configure --providers auto
 ## Configuration
 
 `cohall config` shows stored configuration without tokens. `cohall configure`
-changes the relay URL, device name, workspace roots, providers, model, or Codex
-sandbox. `cohall doctor` checks the effective configuration, relay connection,
-provider executables, authentication readiness, and versions.
+changes the device name, workspace roots, providers, model, sandbox, or relay
+for a fresh pairing. Use `cohall relay use <url>` when moving an existing relay;
+it preserves credentials only after verifying them at the restored address.
+Non-loopback HTTP is refused unless `--allow-http` explicitly confirms that an
+independent private network such as Tailscale encrypts the connection.
+`cohall doctor` checks the effective configuration, relay connection, provider
+executables, authentication readiness, and versions.
 
 Configuration locations:
 
@@ -180,3 +205,30 @@ Use `cohall upgrade --to 1.2.3` for an exact version, `--dry-run` to inspect the
 plan, or `--no-restart` to leave services pending a manual restart. Back up a
 production relay's data directory before an upgrade because SQLite migrations
 run in place.
+
+The relay owner can queue the same built-in upgrade across every registered
+device:
+
+```bash
+cohall upgrade --all --dry-run
+cohall upgrade --all --to 1.2.3
+cohall upgrades
+cohall upgrades abandon <operation-id>
+```
+
+All-device upgrades require the relay owner credential. They are stored by the
+relay, wait for offline devices, and run after active tasks. `cohall upgrades`
+shows the 50 newest queued, running, completed, or failed results. If a device is
+permanently lost, the owner can abandon its operation so later all-device upgrades
+are not blocked. Abandonment records a failed terminal result; it does not stop
+an upgrade already executing on a reachable device. Forgetting an offline device
+also closes its outstanding maintenance operation. The operation accepts only
+`latest` or an exact semantic version and invokes Cohall's existing package
+upgrade path; it cannot transport arbitrary commands. Devices running from a
+temporary package runner report a failure until Cohall is installed globally on
+that device.
+
+Use `cohall doctor --all` for device health and version drift, `cohall versions`
+for a compact version inventory, and `cohall usage` for retained task counts by
+device, status, and provider. Usage is Cohall task activity, not provider token
+or billing data.

package/docs/services.md

@@ -23,24 +23,26 @@ Install and pair as the user that will run the daemon:
 
 ```bash
 npm install --global --prefix "$HOME/.local" @akshar5/cohall
-npx -y @akshar5/cohall doctor
+cohall doctor
 ```
 
-Copy the service shipped in the globally installed package, then start it:
+Install and start the current user's service:
 
 ```bash
-package_root="$(npm root --global --prefix "$HOME/.local")/@akshar5/cohall"
-install -Dm644 "$package_root/deploy/systemd/cohall-device.service" \
-  "$HOME/.config/systemd/user/cohall-device.service"
-systemctl --user daemon-reload
-systemctl --user enable --now cohall-device
+cohall service install
 journalctl --user -u cohall-device -f
+```
+
+The generated service uses the exact executable that ran the installer. Linger
+is optional. Without it, the user service starts after login and stops with the
+user's service manager. With it, the service starts at boot and remains after
+logout:
+
+```bash
 loginctl enable-linger "$USER"
 ```
 
-Linger is optional. Without it, the user service starts after login and stops
-with the user's service manager. With it, the service starts at boot and remains
-available after logout. Verify the configuration with:
+Verify the configuration with:
 
 ```bash
 systemctl --user is-enabled cohall-device
@@ -88,24 +90,87 @@ the listener available across relay service restarts: new connections wait for
 the replacement process instead of failing. Existing WebSockets reconnect, and
 durable tasks resume after the replacement relay starts.
 
+## Move a relay
+
+A relay's SQLite database and owner credential are its portable state. Use the
+supported command instead of copying a live `cohall.db`: it uses SQLite's online
+backup API so the snapshot is consistent while the old relay is running.
+
+```bash
+cohall relay backup ./cohall-relay-backup
+```
+
+Run that command with the same `COHALL_DATA_DIR` and operating-system account
+as the relay service. The destination must be new and its parent must be
+operator-owned or a sticky shared directory. Copy the resulting directory to
+the new host over a private channel.
+
+The backup contains exactly three files:
+
+- `cohall.db`: devices, workspaces advertised by those devices, threads,
+  prompts, context, results, trace history, provider-session references,
+  durable upgrades, pairings, and hashed client/device session credentials;
+- `owner-token`: the plaintext relay owner credential;
+- `manifest.json`: format/version metadata and SHA-256 checksums.
+
+It does not contain device-local Cohall configuration or bearer tokens,
+workspace files, provider logins, service definitions, logs, DNS, reverse-proxy
+configuration, or TLS keys. Back up those host-level pieces separately when
+they are part of the deployment. Anyone who obtains this directory gets the
+owner credential and sensitive task history, so encrypt it at rest when the
+storage or transfer channel is not already protected.
+
+On the new host, install Cohall and restore into the new service's data
+directory before starting it:
+
+```bash
+COHALL_DATA_DIR=/var/lib/cohall cohall relay restore ./cohall-relay-backup
+```
+
+The target data directory must not already exist. Restore refuses to overwrite
+one, rejects symlinked members, copies into a private staging directory, verifies
+the staged file checksums and SQLite integrity, and publishes the restored
+directory atomically. Run the command as the service account so the resulting
+files have the correct owner. The restored `owner-token` file supplies the
+owner credential when `COHALL_TOKEN` is unset; if the new service explicitly
+sets that variable, it must use the same value.
+
+Configure the private network or HTTPS endpoint, start the relay, and check its
+health. If its address changed, update every client and device:
+
+```bash
+cohall relay use https://new-relay.example.com
+cohall doctor
+```
+
+`relay use` first proves that every stored client and device credential works
+against the new relay. Only then does it save the address. It restarts an
+active managed device service automatically; use `--no-restart` when another
+supervisor owns the process. Environment-based configurations must update
+`COHALL_RELAY_URL` in their service environment instead.
+
+HTTPS is required for non-loopback addresses because verification sends the
+stored credentials to the new endpoint. When a private network such as Tailscale
+provides the encrypted transport and the relay intentionally uses HTTP, make
+that assumption explicit:
+
+```bash
+cohall relay use http://cohall-vps.tailnet-name.ts.net:8787 --allow-http
+```
+
+Keeping the same stable DNS or Tailscale name avoids the final per-device step.
+Only change where that name resolves after the restored relay is healthy.
+
 ## macOS
 
-Run `npm install --global @akshar5/cohall`, copy the packaged launch agent, then
-update its executable path to match `command -v cohall`:
+Run `npm install --global @akshar5/cohall`, then install and start the
+LaunchAgent:
 
 ```bash
-package_root="$(npm root --global)/@akshar5/cohall"
-mkdir -p "$HOME/Library/LaunchAgents"
-cp "$package_root/deploy/launchd/com.cohall.device.plist" \
-  "$HOME/Library/LaunchAgents/com.cohall.device.plist"
-cohall_path="$(command -v cohall)"
-/usr/libexec/PlistBuddy -c "Set :ProgramArguments:0 $cohall_path" \
-  "$HOME/Library/LaunchAgents/com.cohall.device.plist"
-launchctl bootstrap gui/"$(id -u)" ~/Library/LaunchAgents/com.cohall.device.plist
-launchctl kickstart -k gui/"$(id -u)"/com.cohall.device
+cohall service install
 ```
 
-The packaged LaunchAgent uses `RunAtLoad` and `KeepAlive`: it starts at login,
+The generated LaunchAgent uses `RunAtLoad` and `KeepAlive`: it starts at login,
 restarts after failure, and reconnects when the network returns. It cannot run
 before that user logs in. Check it with:
 
@@ -122,9 +187,7 @@ Run `npm install --global @akshar5/cohall`, pair and verify the machine from
 PowerShell, then run:
 
 ```powershell
-$packageRoot = Join-Path (npm root --global) "@akshar5/cohall"
-powershell -ExecutionPolicy Bypass -File `
-  (Join-Path $packageRoot "deploy/windows/install-device.ps1")
+cohall service install
 ```
 
 The script registers a per-user scheduled task that starts `cohall device` at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akshar5/cohall",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "description": "Let coding agents delegate work across your own devices.",
   "keywords": [
     "agents",