@akshar5/cohall 0.4.4 → 0.4.6

package/deploy/systemd/cohall-relay.service

@@ -1,7 +1,8 @@
 [Unit]
 Description=Cohall relay
-After=network-online.target
+After=network-online.target cohall-relay.socket
 Wants=network-online.target
+Requires=cohall-relay.socket
 
 [Service]
 Type=simple
@@ -9,6 +10,7 @@ User=cohall
 Group=cohall
 EnvironmentFile=/etc/cohall/relay.env
 ExecStart=/usr/local/bin/cohall relay
+Sockets=cohall-relay.socket
 Restart=on-failure
 RestartSec=3
 UMask=0077

package/deploy/systemd/cohall-relay.socket

@@ -0,0 +1,11 @@
+[Unit]
+Description=Cohall relay socket
+
+[Socket]
+ListenStream=127.0.0.1:8787
+NoDelay=true
+FileDescriptorName=cohall-relay
+Service=cohall-relay.service
+
+[Install]
+WantedBy=sockets.target

package/docs/install.md

@@ -71,9 +71,11 @@ Configuration locations:
 Use `COHALL_CONFIG` to override the path. On Unix, Cohall enforces directory
 mode `0700` and file mode `0600`.
 
-The relay must stay online so devices and clients can reach it. A target device
-must be online only while it is accepting or running work; queued tasks remain
-durable on the relay while it is offline.
+The relay must be reachable to submit new work or read its status. A target
+device only needs to be online while accepting or running work; accepted tasks
+wait durably on the relay while it is offline. Accepted tasks also survive a
+relay restart when its data directory is persistent. A client cannot submit a
+new task while the relay itself is offline.
 
 `--providers` is an optional comma-separated allowlist. It prevents an installed
 but unauthenticated provider executable from being advertised. Run `cohall
@@ -94,8 +96,9 @@ services. Active services restart even when the package files are already
 current, so a process left on old code by a direct package-manager update is
 replaced. If a service points to a different global installation, Cohall stops
 with its executable path instead of reporting a misleading successful restart.
-Run that executable's `upgrade` command or update the service definition. Choose an exact version with `cohall upgrade --to 1.2.3`. Use `--dry-run` to inspect the plan or
-`--no-restart` to leave active services pending a manual restart.
+Run that executable's `upgrade` command or update the service definition. Choose
+an exact version with `cohall upgrade --to 1.2.3`. Use `--dry-run` to inspect the
+plan or `--no-restart` to leave active services pending a manual restart.
 
 Back up the data directory before upgrading a production relay; SQLite schema
 migrations run in place. A system-level relay may require running the command

package/docs/integrations.md

@@ -87,6 +87,4 @@ owner or device token in an MCP client configuration.
 CLI and MCP are equivalent entry points. Use one per delegated task.
 Both expose redacted task tracing through `cohall trace <task-id>` and the
 `task_trace` MCP tool.
-Replace the `npx`, `-y`, `@akshar5/cohall` command prefix with `bunx`,
-`@akshar5/cohall` or `pnpm`, `dlx`, `@akshar5/cohall` when that better matches
-the host.
+Use `bunx @akshar5/cohall` with Bun. Use `pnpm dlx @akshar5/cohall` with pnpm.

package/docs/releasing.md

@@ -8,7 +8,6 @@ Before merging a release:
 ```bash
 bun install --frozen-lockfile
 bun run check
-bun run check
 npm pack --dry-run
 ```
 

package/docs/services.md

@@ -4,6 +4,19 @@ Interactive use should use `npx -y @akshar5/cohall`. Unattended services
 install the same npm package so the operating system has a stable executable
 path.
 
+## Startup behavior
+
+| Component      | Starts again                                                                     | Offline behavior                                                         |
+| -------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Linux relay    | At boot when its systemd socket and service are enabled                          | Cannot accept new tasks while down; persisted tasks resume after startup |
+| Linux device   | With the user's systemd manager; at boot without login when lingering is enabled | Accepted tasks wait on the relay and dispatch after reconnect            |
+| macOS device   | At user login through launchd                                                    | Accepted tasks wait while the Mac is off, asleep, or logged out          |
+| Windows device | At user logon through Task Scheduler                                             | Accepted tasks wait while the PC is off or logged out                    |
+
+The relay's data directory must be persistent. Cohall uses at-least-once delivery:
+work interrupted during execution can run again after recovery, so consequential
+tasks should be idempotent.
+
 ## Linux device daemon
 
 Install and pair as the user that will run the daemon:
@@ -25,7 +38,15 @@ journalctl --user -u cohall-device -f
 loginctl enable-linger "$USER"
 ```
 
-Linger is optional; it keeps the daemon running after logout.
+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:
+
+```bash
+systemctl --user is-enabled cohall-device
+systemctl --user is-active cohall-device
+loginctl show-user "$USER" -p Linger
+```
 
 ## Linux relay
 
@@ -41,16 +62,30 @@ COHALL_TOKEN=replace-with-a-random-owner-token
 COHALL_DATA_DIR=/var/lib/cohall
 ```
 
-Install `deploy/systemd/cohall-relay.service`, then:
+Install `deploy/systemd/cohall-relay.service` and
+`deploy/systemd/cohall-relay.socket`. The packaged socket listens on loopback;
+change `ListenStream` to the relay's private Tailscale address when devices
+connect directly over Tailscale. Then:
 
 ```bash
 systemctl daemon-reload
+systemctl enable --now cohall-relay.socket
 systemctl enable --now cohall-relay
 journalctl -u cohall-relay -f
 ```
 
+Verify both units are enabled and active:
+
+```bash
+systemctl is-enabled cohall-relay.socket cohall-relay.service
+systemctl is-active cohall-relay.socket cohall-relay.service
+```
+
 Expose the relay only through a private network such as Tailscale or an HTTPS
-reverse proxy. Device connections are outbound WebSockets.
+reverse proxy. Device connections are outbound WebSockets. The socket unit keeps
+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.
 
 ## macOS
 
@@ -69,6 +104,14 @@ launchctl bootstrap gui/"$(id -u)" ~/Library/LaunchAgents/com.cohall.device.plis
 launchctl kickstart -k gui/"$(id -u)"/com.cohall.device
 ```
 
+The packaged 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:
+
+```bash
+launchctl print gui/"$(id -u)"/com.cohall.device
+```
+
 The relay and device worker may run on the same machine. Configure the worker
 with the relay's private Tailscale URL and install both services independently.
 
@@ -82,14 +125,16 @@ powershell -ExecutionPolicy Bypass -File deploy\windows\install-device.ps1
 ```
 
 The script registers a per-user scheduled task that starts `cohall device` at
-logon and restarts it after failures.
+logon and restarts it after failures. It does not run before that user logs on.
 
 ## Upgrade running services
 
 Run `cohall upgrade` from a global npm, Bun, or pnpm installation. It updates
 that installation and restarts only active managed Cohall services, with relays
 restarted before device daemons. Active services restart even when the installed
-files already match the requested version. A delegated upgrade can finish after
+files already match the requested version. A systemd relay installed with the
+packaged socket unit keeps accepting new connections while its process restarts.
+A delegated upgrade can finish after
 restarting its own device daemon: a durable receipt records the restart attempt,
 and a delegated caller leaves that marker for the replacement task to consume
 after reconnecting, even when a service manager returns before ending the old process.

package/package.json

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