@akshar5/cohall 0.8.0 → 0.10.0

package/deploy/windows/install-device.ps1

@@ -1,7 +1,12 @@
 param(
   [Parameter(Mandatory = $true)][string]$NodeExecutable,
   [Parameter(Mandatory = $true)][string]$Entrypoint,
-  [Parameter(Mandatory = $true)][string]$ConfigurationPath
+  [Parameter(Mandatory = $true)][string]$ConfigurationPath,
+  [string]$PnpmHome,
+  [string]$PnpmExecutable,
+  [string]$PnpmStoreDir,
+  [string]$PnpmGlobalDir,
+  [string]$PnpmGlobalBinDir
 )
 
 $ErrorActionPreference = "Stop"
@@ -10,10 +15,28 @@ function Quote-Literal([string]$Value) {
   return "'" + $Value.Replace("'", "''") + "'"
 }
 
+$pnpmEnvironment = if ($PnpmHome) {
+  "`$env:PNPM_HOME = $(Quote-Literal $PnpmHome)`r`n`$env:PATH = $(Quote-Literal ((Join-Path $PnpmHome 'bin') + ';' + $PnpmHome)) + ';' + `$env:PATH`r`n"
+} else { "" }
+
+if ($PnpmExecutable) {
+  $pnpmEnvironment += "`$env:COHALL_PNPM_EXECUTABLE = $(Quote-Literal $PnpmExecutable)`r`n"
+}
+
+if ($PnpmStoreDir) {
+  $pnpmEnvironment += "`$env:COHALL_PNPM_STORE_DIR = $(Quote-Literal $PnpmStoreDir)`r`n"
+}
+if ($PnpmGlobalDir) {
+  $pnpmEnvironment += "`$env:COHALL_PNPM_GLOBAL_DIR = $(Quote-Literal $PnpmGlobalDir)`r`n"
+}
+if ($PnpmGlobalBinDir) {
+  $pnpmEnvironment += "`$env:COHALL_PNPM_GLOBAL_BIN_DIR = $(Quote-Literal $PnpmGlobalBinDir)`r`n`$env:PATH = $(Quote-Literal $PnpmGlobalBinDir) + ';' + `$env:PATH`r`n"
+}
+
 $bootstrap = @"
 `$ErrorActionPreference = 'Stop'
 `$env:COHALL_CONFIG = $(Quote-Literal $ConfigurationPath)
-`$env:PATH = $(Quote-Literal (Split-Path -Parent $NodeExecutable)) + ';' + `$env:PATH
+${pnpmEnvironment}`$env:PATH = $(Quote-Literal (Split-Path -Parent $NodeExecutable)) + ';' + `$env:PATH
 & $(Quote-Literal $NodeExecutable) $(Quote-Literal $Entrypoint) device
 exit `$LASTEXITCODE
 "@

package/docs/grok-bot.md

@@ -164,6 +164,13 @@ See [Bot replies and cancellation](../README.md#talk-to-your-grok-bots) for
 how Cohall records the answer. The local gateway is experimental and may change
 with Grok Bot updates.
 
+Bots must preserve the task and `--run-id` in their supplied callback command.
+Use `--question 'Your question'` for essential missing information, then end the
+turn. The requester answers with `cohall answer`; Cohall sends a resumed handoff
+with the answer and a new callback. Questions submitted while the worker is
+disconnected reach the requester's inbox when it reconnects. Paused tasks can be cancelled. See
+[clarification and resume](integrations.md#clarification-and-resume).
+
 ## Give the setup to a Bot
 
 Once you have added the Tailscale policy, you can send this to a Bot on the

package/docs/install.md

@@ -90,7 +90,9 @@ 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.
+changed. Keeping the default workspace retains all configured roots;
+`init --client-only` also retains the worker's provider selection unless
+`--providers` overrides it. `cohall join` remains the non-guided configuration primitive.
 
 Workspace roots must be existing directories. Cohall resolves them to canonical paths and
 rejects delegated work outside them.
@@ -148,6 +150,10 @@ cohall configure --providers codex,claude-code
 cohall configure --providers auto
 ```
 
+Restart the worker after changing its provider selection. Queued work for a
+disabled provider fails with an error instead of starting that provider.
+`auto` enables all detected providers.
+
 ## Configuration
 
 `cohall config` shows stored configuration without tokens. `cohall configure`
@@ -212,15 +218,34 @@ the new version, and restarts only active Cohall services. If a service points
 to another global installation, Cohall stops and reports the correct executable
 instead of restarting the wrong job.
 
-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
+Upgrades and device service installation require a verified global installation.
+Project dependencies and package-runner caches are rejected before making changes.
+For npm, the global `cohall` command must still point to this installation.
+For Bun, Cohall checks the selected Bun executable's configured global directory,
+including custom `install.globalDir` or `BUN_INSTALL_GLOBAL_DIR` settings, and pins
+installation to that directory. Use the same Bun configuration when invoking
+Cohall; a different global directory is rejected.
+
+The default target, `latest`, is resolved through that package manager using its
+registry and network settings, then pinned before installation. Bun installations
+require Bun 1.2.15 or newer for this lookup; older Bun versions can still use an
+exact `--to` version. If `latest` is older than the running or installed version,
+Cohall leaves the installation and services untouched. Version ordering includes
+prereleases and ignores build metadata. A failed or invalid lookup, or unreadable
+installed package metadata, stops the upgrade before installation. Use an exact
+`--to` version to repair damaged metadata.
+
+Use `cohall upgrade --to 1.2.3` for an exact version, including an intentional
+rollback. Use `--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.
 
 An exact version already installed on disk skips package installation and still
 restarts active services. Dry runs and failed installations preserve restart
 recovery state. A new explicit version takes precedence over an older recovery
-record.
+record, while retaining unfinished restarts for the new version. `--no-restart`
+also preserves pending restarts for a later retry.
 
 Upgrade tools use the first PATH candidate that passes ownership and permission
 checks. Unsafe candidates are skipped; an explicit executable path must pass
@@ -240,7 +265,9 @@ 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. Upgrade devices
+shows the 50 newest queued, running, completed, or failed results. A `latest`
+operation applies the same downgrade check on each device when it executes;
+upgrade older daemons individually once to gain this protection. Upgrade devices
 older than Cohall 0.5.0 individually once before using all-device upgrades; the
 relay rejects work that their daemons cannot understand. If a device is permanently
 lost, the owner can abandon its operation so later all-device upgrades are not

package/docs/integrations.md

@@ -4,12 +4,159 @@ CLI plus skill is the recommended integration. MCP is available for harnesses
 that prefer native tool discovery. Both create the same relay tasks; use one
 entry point per task.
 
-For queued work, `cohall inbox` or the MCP `completion_inbox` tool lists results
-the sending client has not handled. Fetch a full result with `cohall status
-<task-id>` or `task_status`, then use `cohall inbox ack <task-id>` or
-`acknowledge_completion` to remove it from the inbox. A synchronous `delegate`
+For queued work, `cohall inbox` or the MCP `completion_inbox` tool lists questions
+awaiting answers and results the sending client has not handled. Fetch a full
+result with `cohall status <task-id>` or `task_status`, then use
+`cohall inbox ack <task-id>` or `acknowledge_completion` to remove it from the inbox. A synchronous `delegate`
 call acknowledges its result automatically.
 
+Cancelling an MCP `delegate` or `wait_task` request stops its wait and polling.
+Accepted work continues. To stop coding work, use `cancel_task` or a task deadline.
+Later completions stay in the inbox.
+
+## Retrying submissions
+
+Generate and save a UUID v4 before submitting work. Pass it as `--request-id`
+on `send` or `delegate`, or as `request_id` on the MCP `delegate` tool:
+
+```bash
+cohall delegate --target @<device-id> \
+  --request-id 11111111-1111-4111-8111-111111111111 \
+  --prompt 'Inspect deployment 184.' --no-wait
+```
+
+After a lost response, repeat the submission with the same ID, input, and client
+credential. The relay returns the original task's current state, including
+after a relay restart. Retries create no second task or thread message. Worker
+execution remains at least once: a run interrupted by a disconnect can restart.
+If the worker is still running that turn, it confirms the active run after
+reconnecting so progress and clarification continue without starting it again.
+The task keeps its original start time; its trace records the new acknowledgment.
+Requests without an ID continue to create a new task each time.
+
+Use a device UUID or `@device-uuid/bot-id` from `cohall bots` for retries. These
+targets bypass live name discovery when a request ID is supplied, so the original
+task can still be recovered after its target is forgotten or stops advertising
+the provider. Names need discovery on each call. With a request ID, a thread
+follow-up must select a target or provider explicitly. Select the Bot explicitly
+for a Bot follow-up. Cohall does not retry submissions automatically.
+
+IDs belong to the original requester credential. Another pairing or the relay
+owner has a separate ID namespace. Keep all task input unchanged, including
+context, thread and parent IDs, workspace, target, provider, deadline, and attachment
+names and bytes. Reusing an ID with changed input returns HTTP 409. Default Codex and
+an empty attachment list normalize to their omitted forms.
+
+Used IDs and input hashes remain in the relay database and its backups after
+terminal task history is pruned. They have no expiry. The retained record has no
+prompt, context, or attachment content. If the original task was pruned, retrying
+returns HTTP 410 and the ID stays consumed. Check whether that work completed
+before deciding to submit new work with a new ID. Upgrade older relays before
+using request IDs; clients reject unsupported relays before submission.
+
+## Clarification and resume
+
+A worker missing essential information can ask the sender, then end its current
+turn immediately:
+
+```bash
+cohall request-input --question 'Which branch should I use?'
+```
+
+The task and current turn IDs are inherited during delegated coding work.
+Outside that environment, supply `<task-id>` explicitly. `--run-id <run-id>`
+selects a specific worker turn; otherwise Cohall reads the task's current turn.
+MCP provides `task_request_input` with `question`, optional `task_id`, and optional
+`run_id`. Grok Bots use the callback command supplied in their handoff with
+`--question` and its `--run-id`.
+
+After the worker ends its turn, the task becomes `needs_input` and frees its
+worker slot. `delegate`, `send`, and `wait` return at this state as well as at a
+terminal result. Read `input_request.id` and `input_request.question` in their
+JSON or `status`; inbox entries use `inputRequest` instead. Questions cannot be
+acknowledged as completions.
+
+The original requester credential or relay owner answers the current question:
+
+```bash
+cohall answer <task-id> --request-id <question-id> --message 'Use main.'
+cohall wait <task-id> --timeout 1800
+```
+
+Answers also support `--message-file <path>` or `--message -` for stdin. MCP
+provides `task_answer` with `task_id`, `request_id`, and `answer`, followed by
+`wait_task`. A stale question ID or duplicate answer is rejected. Use known
+facts from the conversation; ask the user when the answer is missing.
+
+The same task and thread resume on their original target, using the saved
+provider session when available. Answered questions are included in the resumed
+prompt, including after a restart. An offline target waits in the queue. Each
+task permits ten questions; each question and answer must be nonblank and at most
+4096 UTF-8 bytes. Cancel a paused task with `cohall cancel <task-id>`.
+Tasks awaiting their first dispatch cancel immediately. Coding tasks that may
+have reached a worker stay `cancelling` until it confirms termination, including
+tasks requeued after a disconnect and paused tasks. An offline worker acknowledges
+the cancellation after reconnecting.
+
+The assigned task, including its prompt, context, and clarification history,
+must fit the 1 MiB transfer limit. Oversized assignments fail with an explicit
+error; retry with a shorter prompt or context.
+
+Each task supports up to ten clarification questions. If a Bot ends its turn
+with another question after that limit, the task fails with a visible error
+and releases the Bot for subsequent work.
+
+Upgrade the relay, requester, and worker before using clarification. Resumed
+tasks and Bot turns using a run ID remain queued while the worker lacks
+clarification support. Inbox checks
+and waits poll the relay; Cohall does not wake a requester to deliver a question.
+
+## Task deadlines
+
+`--timeout` and MCP `timeout_seconds` limit how long the requester waits.
+The limit covers task-status lookup and polling, including slow responses.
+Timing out stops the wait; accepted work continues and later completions stay in the inbox.
+To stop coding work at a fixed time, give `delegate` a future UTC timestamp:
+
+```bash
+cohall delegate --target @linux --no-wait \
+  --deadline 2030-01-01T18:00:00Z \
+  --prompt 'Run the test suite and report failures.'
+```
+
+MCP `delegate` accepts `deadline` in the same format. HTTP `POST /api/tasks`
+accepts `expiresAt`. Task results return `expires_at`; relay task records and
+traces use `expiresAt`. Omit the field for work without a deadline.
+
+The deadline covers queueing, execution, and time awaiting clarification.
+Restarting or resuming a task keeps its original deadline. An expired task
+fails with `Task deadline exceeded`. Tasks awaiting their first dispatch fail
+without contacting the worker. Tasks that may have reached a worker stay
+`cancelling` until it confirms termination. An offline worker
+acknowledges after reconnecting; its local timer stops active coding work even
+while disconnected. A manual cancellation requested before the deadline still
+finishes as `cancelled`.
+
+Upgrade the requester, relay, and target worker before using deadlines. Cohall
+rejects older relays and targets that do not advertise deadline support. Saved
+deadline tasks stay queued if their worker is downgraded, and still expire.
+Deadlines apply to coding providers only. The Grok Bot gateway cannot safely
+stop a specific turn, so Bot deadline requests are rejected.
+
+## Worker progress
+
+Workers can report a brief milestone with `cohall progress --message "Running
+tests"` or MCP `task_progress`. Both inherit the task ID during delegated work;
+otherwise supply the task ID explicitly. Notes must be nonblank and at most
+1024 UTF-8 bytes. Only the task's target device or relay owner may update a
+running task. Use milestones, never logs or secrets.
+
+`cohall status <task-id>`, `cohall trace <task-id> --follow`, and MCP `task_status`
+and `task_trace` include the latest note and timestamp. Notes replace one another
+and clear when work is requeued, pauses for input, or finishes.
+Reporting progress requires an updated relay; it does not change task status
+or acknowledge a completion.
+
 ## CLI plus skill
 
 ```bash
@@ -27,6 +174,27 @@ With a client credential, `doctor` starts Cohall's MCP server and verifies that
 it lists tools. This checks the local server; the agent host still needs a
 working MCP configuration to load it.
 
+A running MCP server checks its launched executable at most once per minute
+when returning tool results. If that file changes to a different Cohall version,
+the next checked result includes a notice to restart the Cohall MCP connection
+in your agent host. Each detected version produces one notice; the tool's
+normal result is preserved. The server does not restart an active session.
+Version probes time out after two seconds and failed probes retry on a later
+tool call. This detects changes to the launched file, including a replaced
+symlink target. It does not check the npm registry or other installations. An
+`npx` session using an unchanged cache path must be restarted to load a newer
+package.
+
+`doctor` also checks the client credential with an authenticated relay request.
+The `client_authentication` result separates rejected credentials and relay
+request failures from an offline device. `client_credential` reports only
+whether a credential is configured. The authentication check is skipped when
+the relay is unreachable or no client credential is configured.
+
+`doctor` warns when a configured Grok Bot gateway is unavailable in automatic
+provider mode or when `grok-bot` is explicitly selected. An explicit provider
+list that excludes `grok-bot` skips this warning.
+
 Any other harness with shell access can invoke the CLI directly. No Cohall UI
 extension is required.
 
@@ -36,6 +204,15 @@ infers `grok-bot` from a Bot target. See [Grok Bot setup](../README.md#talk-to-y
 for messaging details, and [computer setup](grok-bot.md) for Tailscale, pairing,
 and the local gateway.
 
+Device discovery uses `GET /api/devices/page`, returning `devices` and an
+optional `nextCursor`. Pass that cursor as `after` on the next request; an absent
+cursor ends the list. Pages contain up to 16 devices and at most 3 MiB of JSON.
+They follow device UUID order; clients sort the complete list by name.
+`GET /api/devices` still returns the full array for older clients.
+Updated clients fall back to that array on older relays, retaining its 2 MiB
+response limit. Upgrade both the relay and client for large device or Bot
+inventories.
+
 When delegating from a conversation, the sending agent must distill why the user
 is asking, relevant facts and prior findings, constraints, and the intended
 decision into Cohall's `context` field. Cohall cannot read the harness transcript
@@ -95,11 +272,15 @@ Add to `opencode.json`:
 
 ## Isolated environments
 
+For a hosted Muse sandbox, see [Muse requester setup](muse.md) for client-only
+pairing, proxy access, and collecting delegated results.
+
 The MCP subprocess reads the current user's Cohall configuration. If a harness
 uses an isolated environment, pass `COHALL_CONFIG` with an absolute path to that
 configuration file. Alternatively pass `COHALL_RELAY_URL` and
 `COHALL_CLIENT_TOKEN` directly.
 
-Never place an owner or device token in an MCP configuration. Both integrations
-provide redacted task tracing through `cohall trace <task-id>` or the
-`task_trace` MCP tool.
+Never place an owner or device token in an MCP configuration. Task tracing through
+`cohall trace <task-id>` or `task_trace` omits prompts, final results, credentials,
+and provider session IDs. It includes worker progress and clarification text;
+inspect those fields before sharing a trace.

package/docs/muse.md

@@ -0,0 +1,162 @@
+# Muse requester setup
+
+Muse can submit tasks to Cohall from a sandbox with shell access, Node.js 24 or
+newer, and an approved network route to your relay. Pair it as a client-only
+requester. Your existing Cohall device workers run the delegated work.
+
+The requester commands have been verified through an authenticated proxy.
+The hosted Muse integration has not been tested end to end.
+
+Cohall has no Muse worker adapter or Muse wake integration. This setup does not
+make Muse a target in `cohall devices` or start a new Muse turn when work arrives.
+
+## Relay access
+
+Use an HTTPS relay address reachable from the sandbox. A private relay requires
+an approved private network route or tunnel proxy provided by the sandbox host.
+Tailscale access on your computer does not give the sandbox the same access.
+Keep the relay address stable. If the relay moves with its existing data, switch
+the stored address after the new endpoint is reachable:
+
+```bash
+unset COHALL_RELAY_URL
+npx -y @akshar5/cohall relay use https://new-relay.example.com
+```
+
+This verifies and preserves the stored credential. Changing only
+`COHALL_RELAY_URL` does not reuse a credential bound to the old address.
+See [relay migration](../README.md#move-a-relay) for moving the relay data.
+
+Cohall's requester uses Node's `fetch`. In a proxy-only environment, enable
+Node's use of the proxy settings before starting Cohall:
+
+```bash
+export NODE_USE_ENV_PROXY=1
+```
+
+Preserve the host's `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, and
+`NODE_EXTRA_CA_CERTS` settings. If the regular egress proxy cannot reach the
+private relay, obtain the correct route from the host operator. Do not guess
+proxy endpoints or copy proxy credentials into chat, command arguments, or
+checked-in files. A relay listed in `NO_PROXY` bypasses the proxy, which fails
+when the sandbox has no direct route to it.
+
+`NODE_USE_ENV_PROXY=1` is supported for `fetch` starting with Node.js 24.0.0,
+as documented in [Node's 24.0.0 command-line API](https://nodejs.org/download/release/v24.0.0/docs/api/cli.html#node_use_env_proxy1).
+The separate `--use-env-proxy` flag and `http`/`https` agent support need 24.5.0;
+this guide uses the environment variable with `fetch`.
+See [Node's proxy and certificate guidance](https://nodejs.org/en/learn/http/enterprise-network-configuration).
+Keep certificate verification enabled; use the host-provided CA bundle when
+its proxy or relay requires one.
+
+## Pair the requester
+
+On an owner-authenticated machine, create a single-use client pairing token
+valid for ten minutes:
+
+```bash
+npx -y @akshar5/cohall pair --client-only --label "Muse"
+```
+
+Transfer that token privately to a mode-`0600` file in the sandbox. Keep the
+owner and device credentials on their own machines. Choose a private writable
+configuration path, outside shared repositories and artifacts:
+
+```bash
+export COHALL_CONFIG=/absolute/private/path/cohall/config.json
+
+npx -y @akshar5/cohall join \
+  --relay https://cohall.example.com \
+  --client-only \
+  --name Muse \
+  --token-file /absolute/private/path/cohall-pairing-token
+
+npx -y @akshar5/cohall doctor
+npx -y @akshar5/cohall devices
+```
+
+`join` stores the client credential at `COHALL_CONFIG`; it does not install a
+worker service. No workspace or coding provider is required for this requester.
+`doctor` should report a reachable relay and `client_authentication.status` of
+`ok`. Its MCP check verifies the local Cohall server, not Muse's tool loading.
+
+Use the same `COHALL_CONFIG` and network environment for later commands. If the
+sandbox is replaced, retain the configuration through the host's private
+persistent storage or issue a new pairing token. Cohall cannot preserve a file
+the host discards.
+
+Client credentials expire 90 days after pairing. Before expiry, collect and
+acknowledge completed work and record any outstanding task IDs. Have the relay
+owner create a new client-only pairing token, repeat `join` with that new token
+file, and run `doctor` again. Each pairing has a separate completion inbox;
+results from earlier pairings remain accessible through `status <task-id>` while
+the relay retains those tasks. Preserving the configuration does not extend the
+credential's expiry. Clarification answers require the original requester
+credential or relay owner; ask the owner to answer outstanding questions from
+an expired pairing.
+
+## Delegate and collect results
+
+For work that may exceed the host's command timeout, enqueue it and keep the
+returned task ID:
+
+```bash
+npx -y @akshar5/cohall delegate \
+  --target @workstation \
+  --prompt-file /absolute/path/task.txt \
+  --context-file /absolute/path/context.txt \
+  --no-wait
+
+npx -y @akshar5/cohall status <task-id>
+npx -y @akshar5/cohall inbox
+npx -y @akshar5/cohall inbox ack <task-id>
+```
+
+Replace `@workstation` with a name or ID from `devices`. Send the question,
+relevant facts, prior findings, and constraints in the prompt and context files.
+Cohall cannot read the Muse conversation automatically.
+
+Fetch the full result with `status` and acknowledge it after handling it. If
+`status`, `wait`, or `delegate` returns `needs_input`, read `input_request` and
+answer its question using known conversation facts:
+
+```bash
+npx -y @akshar5/cohall answer <task-id> \
+  --request-id <input-request-id> --message-file /absolute/path/answer.txt
+npx -y @akshar5/cohall wait <task-id> --timeout 900
+```
+
+The same task resumes on its worker. Questions appear in `inbox` as
+`inputRequest`; answer or cancel them instead of acknowledging them. Upgrade
+the requester, relay, and worker first; see
+[clarification and resume](integrations.md#clarification-and-resume).
+
+`wait <task-id> --timeout <seconds>` polls a specific task; it does not listen
+for incoming requests or wake Muse. A wait timeout leaves the task running.
+If the host ends long commands or does not deliver background output, check
+`status` or `inbox` during subsequent turns. Scheduling and background command
+notifications depend on the host.
+
+When coding work must stop by a fixed time, add
+`--deadline <future-UTC-ISO-timestamp>` to `delegate`. The deadline includes time
+waiting for clarification and survives restarts. Upgrade the requester, relay,
+and worker first. See [task deadlines](integrations.md#task-deadlines) for
+cancellation states and offline behavior.
+
+## Optional MCP
+
+If your Muse host supports local stdio MCP subprocesses, configure it to launch:
+
+```bash
+npx -y @akshar5/cohall mcp
+```
+
+Pass the same `COHALL_CONFIG`, `NODE_USE_ENV_PROXY=1`, and applicable proxy and CA
+settings into that subprocess through the host's secure environment mechanism.
+Use only the client credential. Cohall's MCP transport is stdio; the relay URL
+is not a remote MCP endpoint.
+
+For queued work, call `delegate` with `wait: false`, then `task_status` or
+`completion_inbox`. Answer `needs_input` with `task_answer`, then `wait_task`.
+Use `acknowledge_completion` after handling a completed result.
+See [agent integrations](integrations.md) for the common CLI and MCP behavior.

package/docs/releasing.md

@@ -12,8 +12,8 @@ npm pack --dry-run
 ```
 
 The Check workflow runs when manually dispatched or when a non-draft pull
-request is opened or marked ready for review. Synchronizing later commits does
-not start another run automatically.
+request is opened, reopened, updated, or marked ready for review. New commits
+cancel an earlier run for the same pull request and start a fresh check.
 
 After releasable conventional commits reach `main`, Release Please opens or
 updates one release pull request. Merging it creates the version tag and GitHub

package/docs/services.md

@@ -17,6 +17,18 @@ The relay's data directory must be persistent. Cohall uses at-least-once deliver
 work interrupted during execution can run again after recovery, so consequential
 tasks should be idempotent.
 
+Device workers retry the connection after two seconds if the relay does not
+accept it within ten seconds. Once connected, workers reconnect if no relay ping
+arrives for 45 seconds. The relay sends a ping every 30 seconds. This also recovers
+connections that go silent without closing the socket. Active work continues
+during a disconnect, and pending results are sent after reconnecting.
+
+On macOS and Linux, `cohall device` handles SIGINT and SIGTERM by stopping active
+coding providers and waiting for their process cleanup. It starts no queued work
+during shutdown. Forced termination, including SIGKILL, cannot run that cleanup;
+a custom supervisor must stop the worker's entire process tree. The Linux
+systemd service does this through its default control-group termination.
+
 ## Linux device daemon
 
 Install and pair as the user that will run the daemon:
@@ -33,11 +45,22 @@ cohall service install
 journalctl --user -u cohall-device -f
 ```
 
+The user unit is written under `$XDG_CONFIG_HOME/systemd/user` when that variable
+is an absolute path, or `$HOME/.config/systemd/user` otherwise.
+
 The generated service uses the exact Cohall executable and puts the current
-Node.js directory first on `PATH`. It records the resolved configuration file,
-including `COHALL_CONFIG` or `XDG_CONFIG_HOME` overrides. Reinstall the service
-after moving that file or replacing a Node.js installation at a different path.
-Reinstalling restarts an existing worker to apply the changes.
+Node.js directory first on `PATH`. Linux and macOS services include the configured
+pnpm home and its `bin` subdirectory. For pnpm installations, services also save
+the selected pnpm executable, global package directory, global bin directory, and
+store directory.
+This preserves custom paths supplied through shell configuration and prevents a
+Corepack shim on the service PATH from redirecting upgrades. Global pnpm operations
+ignore the current project’s Corepack manager specification.
+
+The service records the resolved configuration file, including `COHALL_CONFIG` or
+`XDG_CONFIG_HOME` overrides. Reinstall it after moving that file or replacing a
+Node.js or pnpm executable at a different path. Reinstalling restarts an existing
+worker to apply the changes.
 
 Some Grok Bot cloud computers have no systemd user manager. On those hosts,
 follow [Grok Bot computer setup](grok-bot.md) for a supported supervisor or
@@ -157,8 +180,11 @@ 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
+active managed device service automatically and leaves stopped workers stopped.
+Repeat the command to retry a failed restart or apply a previously saved address;
+credentials are verified again, and an unchanged address is not rewritten.
+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
@@ -212,16 +238,43 @@ change. 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
+Run `cohall upgrade` from a verified global npm, Bun, or pnpm installation.
+Project-local dependencies and package-runner caches cannot upgrade or install a
+device service; use the global `cohall` command. pnpm shared-store entrypoints
+must be reached through their stable global package link. It updates
 that installation and restarts only active managed Cohall services, with relays
 restarted before device workers. Active services restart even when the installed
 files already match the requested version. Socket-activated relays keep accepting
 new connections while their process is replaced, and delegated upgrades finish
 through durable restart recovery.
 
-Before changing files, Cohall verifies that active systemd and launchd jobs use
-the same global installation as the invoked CLI. If they differ, use the
-executable named in the error or update the service definition.
+Bun upgrades verify and retain the selected manager's configured global directory.
+If that directory is set only by shell environment variables, set
+`BUN_INSTALL_GLOBAL_DIR` in the service environment too; shell overrides are not
+copied when installing a service. A mismatched Bun global directory stops the
+upgrade before installation.
+
+If a restart fails, inactive or missing services remain listed in
+`services_pending_restart` and their recovery state is preserved. Repair or start
+the affected service, then rerun the same upgrade command. Recovery verifies each
+active service's installation before restarting it. Changing the target version
+retains unfinished restarts under the new version, including with `--no-restart`.
+
+Before changing files, Cohall verifies that active systemd jobs, launchd jobs,
+and Windows scheduled tasks use the same global installation as the invoked
+CLI. If they differ, use the executable named in the error or reinstall the
+device service with `cohall service install`. Windows tasks with unrecognized or
+multiple actions must also be reinstalled before upgrading.
+
+pnpm device services use the stable global package link so replacing or removing
+an old package directory does not leave the worker on the old version. Services
+installed by older Cohall versions may be pinned to a version-specific directory.
+After updating the global CLI, run `cohall service install` through pnpm's
+global `cohall` command once to replace the saved executable. Cohall rejects
+pinned active services before changing
+packages. This applies to systemd, launchd, and Windows scheduled tasks. For a
+manually configured pnpm relay, change its service executable to the stable
+package path named in the error.
 
 Direct `npm install --global`, `bun add --global`, or `pnpm add --global`
 replaces files on disk but cannot replace code already loaded by a running Node
@@ -234,14 +287,17 @@ Start with `cohall doctor`. It reports relay reachability, device connectivity,
 provider selection, executable discovery, and version information without
 printing credentials.
 
-Inspect a task's redacted lifecycle, including dispatches, reconnect-driven
-requeues, execution, cancellation, and completion:
+Inspect a task's lifecycle, including dispatches, reconnect-driven requeues,
+execution, clarification, cancellation, and completion:
 
 ```bash
 cohall trace <task-id>
 cohall trace <task-id> --follow
 ```
 
+Traces omit prompts, final results, credentials, and provider session IDs. They
+include progress and clarification text; inspect those fields before sharing.
+
 Use `journalctl --user -u cohall-device -f` for a Linux device and
 `journalctl -u cohall-relay -f` for a system relay. The trace is durable and
 portable; service logs remain machine-local.