@primusclaw/connector 0.1.4 → 0.1.6

package/README.md

@@ -41,8 +41,12 @@ If npm answers `EACCES`, point its global prefix at a directory you own (`npm co
 ```sh
 claw-connector init      # writes agents.toml and prints where: ~/.config/claw-connector/agents.toml unless XDG_CONFIG_HOME or CLAW_CONNECTOR_HOME is set
 claw-connector status    # after you edit it: prints a "problem:" line if the file is wrong
+claw-connector doctor    # checks the machine (step 5), then starts each agent's adapter, opens a session (no prompt) and checks the modes it offers
 ```
 
+`init` runs the adapter check of `doctor` at the end. `doctor` says `ok` for an agent whose phone sessions will open, and otherwise a
+`problem:` line with the fix, for example an agent whose sessions would be refused with `mode_unavailable`.
+
 By default every agent asks before it writes a file or runs a command, and your phone answers each question. To let phone sessions run
 like your terminal instead, run `claw-connector init --approval never` (or set `approval = "never"` on an agent later); see
 [Running without per-step approval](#running-without-per-step-approval).
@@ -80,15 +84,36 @@ claw-connector service status
 
 This starts the connector now and keeps it up: at login and after a reboot, and again 5 seconds after it dies for any reason, except
 one that only you can fix (the connector was revoked, or Claw refused the sign-in), which leaves it stopped until you run `login` again.
+Only `claw-connector stop` (or stopping the service) stops it for good: a `kill` of the connector's process from anywhere else ends it
+with exit 75, and it is started again.
 It uses `systemd --user` on Linux and launchd on macOS. On Linux, run `loginctl enable-linger $USER` once (`service install` says so
 when it is needed) so it also runs while you are logged out. In a container without systemd, `service install` starts a small
-supervisor and writes `keepalive.sh`; have the container's startup command and a 5-minute cron job run that script (it does nothing
-when the supervisor is up) so a restarted container comes back by itself. See [Keeping it running](#keeping-it-running).
+supervisor, writes `keepalive.sh` and adds it to your crontab when a cron daemon runs; when none does it says so, and the container's
+startup command must run that script (it does nothing when the supervisor is up) for a restarted container to come back. Keys the
+agents read from your shell (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`...) are kept for the service in a 0600 file, never in the unit.
+See [Keeping it running](#keeping-it-running).
 
 To try it in the foreground instead, `claw-connector run` prints `connecting claude to https://claw.example.com/claw-api as
 "<machine name>"` and stays up until Ctrl-C, which stops it and every agent it started.
 
-**5. See it in Clawy**
+**5. Check the machine**
+
+```sh
+claw-connector doctor
+```
+
+`doctor` checks what makes a first phone session fail far from the machine that caused it, and prints one fix per problem:
+Node.js 22 or newer; each agent's program on `PATH` (and on the `PATH` the installed service starts it with, which is not your
+shell's); whether Claude Code and Codex are signed in (`claude auth status`, `codex login status`, or the model provider's key
+variable in `~/.codex/config.toml`); the `roots` writable; `HTTPS_PROXY` and `https_proxy` not set to different values; a service
+installed (and, for `keepalive.sh`, something calling it); and Claw answering, including whether Node.js trusts its certificate
+(Node does not read the system's CA store by default: behind a company CA set `NODE_USE_SYSTEM_CA=1` or `NODE_EXTRA_CA_CERTS`). Then it
+runs the adapter check of step 2. It exits 1 when something will stop sessions (`--json`: `ok` is the adapters' verdict,
+`machine_ok` and `environment` the machine's). The
+running connector repeats the machine checks with its own environment (in a child process, so a stalled disk cannot stall
+it) every 15 minutes, and at once when `doctor` runs (it signals the connector), and Clawy's `/agents` card shows what it found under the machine ("Codex is not signed in: run `codex login` on that machine").
+
+**6. See it in Clawy**
 
 In Clawy (or any chat client built on Claw), send `/agents`. The agents of this machine are listed, online while `run` is up.
 A session started there runs on this machine, inside one of your `roots`, and each permission request comes back as a card in the chat.
@@ -116,7 +141,9 @@ id = "codex"
 preset = "codex"
 roots = ["~/work/repo-a", "~/work/repo-b"]
 [agents.env]                       # passed to the adapter; the model settings live here, never in Claw
-OPENAI_API_KEY = "..."             # or leave your own environment / CODEX_HOME to supply it
+OPENAI_API_KEY = "..."             # or leave your own environment / CODEX_HOME to supply it; with only a key, the
+                                   # connector signs Codex in with it (Codex keeps it in its auth.json, like
+                                   # "codex login --with-api-key")
 
 [[agents]]
 id = "mine"
@@ -136,10 +163,23 @@ Presets and the adapter versions they pin (override `command` and `args` to move
 | `codex` | `npx @agentclientprotocol/codex-acp@2.3.0` | `read-only` | `read-only` | `agent-full-access` |
 | `cursor` | `agent acp` (the Cursor CLI) | `ask` | `ask`, `plan` | `agent`, started as `agent --force acp` |
 
+The pinned adapters (the `npx -y <package>@<version>` presets above) are installed once into the connector's state
+directory (`adapters/<package>@<version>`), by `init`, by `service install` and in the background when `run` starts, and are
+then started from there with the connector's own Node.js: a session does not wait for npx to look the package up in a
+registry (about 70 seconds when the registry cannot be reached) or download it (Claude's adapter takes about 350 MB on
+disk with its dependencies), and a repository's own `.npmrc` cannot pick the registry. The install uses `npm install` with your npm
+settings (`~/.npmrc`, `npm_config_*`, an `npm_config_registry` in the agent's `env`). A session that opens while its
+adapter is still being installed waits for it; if the install failed, the agent's npx command runs as before, in the
+connector's state directory, and the install is tried again in the background ten minutes later. An agent with its own
+`command` or `args` is started exactly as written.
+
 `claude-attach` does not start new conversations: it takes over Claude Code conversations that already exist on this
 machine (see [Taking over an existing conversation](#taking-over-an-existing-conversation)).
 
-An agent with no `roots` is never offered. A configuration problem is reported at start-up, not skipped.
+An agent with no `roots` is never offered. A configuration problem is reported at start-up, not skipped. A root that does
+not exist, or whose disk does not answer (a network mount that is down or not mounted yet), is not a configuration problem:
+`run` warns about it and keeps going, and that root's sessions are refused (`cwd_not_found`, `root_unavailable`) until it is
+back. Reading `agents.toml` never touches a root.
 
 ## Running without per-step approval
 
@@ -165,23 +205,20 @@ unattended while Cursor keeps asking. For that agent the connector then:
   `mode_update` carry `unattended`, so a client can always show whether a session asks. `status` and the line `run` prints
   at start-up name the agents without per-step approval.
 
-**Before the first phone session, check which way your Claude settings go.** When `permissions.defaultMode` is
-`bypassPermissions` in your user `settings.json` (`$CLAUDE_CONFIG_DIR`, else `~/.claude`) or in Claude's managed settings,
-every session of a `claude` agent without `approval = "never"` is closed with `mode_not_enforced` (a `claude-attach`
-agent accepts the warning while it takes a conversation over, so it is not affected).
-`claw-connector status` and the start-up line of `run` say so for each such agent:
-
-```
-warning:    claude: sessions will be refused (mode_not_enforced): Claude defaults to bypassPermissions here (permissions.defaultMode in /home/me/.claude/settings.json); set approval = "never" on this agent or change defaultMode
-```
-
-Choose one: `approval = "never"` on that agent (knowing the risk below), or another `defaultMode` in that file. The check
-reads the two files from which the Claude adapter takes `bypassPermissions` (it ignores that value in a repository's
-`.claude/settings.json` and `.claude/settings.local.json`), and only the exact spelling counts, as for the adapter; root
-without `IS_SANDBOX` cannot use bypass, and `permissions.disableBypassPermissionsMode = "disable"` turns it off. It applies
-to every agent that runs `claude-agent-acp` except `claude-attach`. Codex and Cursor have no equivalent: their own
+**Your own Claude settings may default to `bypassPermissions`** (`permissions.defaultMode` in your user `settings.json`,
+`$CLAUDE_CONFIG_DIR` or `~/.claude`, or in Claude's managed settings). For a `claude` agent that asks (no
+`approval = "never"`), the connector tells the adapter to leave that mode out (`allowDangerouslySkipPermissions: false`),
+so its sessions start in `default` and ask; before 0.1.5 each of them was closed with `mode_not_enforced`. An agent with
+`approval = "never"` runs in `bypassPermissions` either way. A `claude-attach` agent takes over a conversation in the mode
+its terminal chose and accepts the adapter's warning while it starts. Codex and Cursor have no equivalent: their own
 settings are replaced by the mode the connector sets and reads back.
 
+**Root.** Claude Code offers `bypassPermissions` to root only when `IS_SANDBOX` is set. For an agent that runs
+`claude-agent-acp` with `approval = "never"` (or `allow_unsafe_modes = true`), the connector sets `IS_SANDBOX=1` in that
+agent's adapter environment when it runs as root, and `run` prints a `note:` line saying so; nothing else gets it. Without
+that, every phone session of such an agent was refused with `mode_unavailable`. To keep it off, set `IS_SANDBOX` yourself
+in the agent's `[agents.env]` (an empty value is kept as it is; `status` then warns that sessions will be refused).
+
 **The risk, in one sentence:** an agent without per-step approval acts on whatever it is told, including text it read in
 a file or a web page, with everything your account can do inside its roots (and `--force` or full access reach outside the
 sandbox the adapter would otherwise keep), and nobody is asked first.
@@ -209,7 +246,24 @@ All of these run on your machine and fail closed.
 
 - **Directories.** A session's working directory is resolved (symlinks included) and must be inside one of the agent's
   `roots`; otherwise no process is started and the session is closed with `cwd_outside_roots`. The agent runs in the
-  resolved path.
+  resolved path. A folder can be given the way people type it: `~` and `~/x` are the agent's home directory (its
+  `[agents.env]` `HOME`, else the connector's), and a relative name (`repo`, `repo/sub`) is looked up under each root and
+  taken when exactly one has it (`cwd_ambiguous` when several do); a root's own last segment names that root. A relative
+  name never climbs out (`..`). Every look at the disk on the way to opening a session is asynchronous with a 10-second
+  limit, so a root on a stalled network mount refuses its own sessions (`root_unavailable`), never those under a healthy
+  root, and never freezes the connector or its heartbeat. A restored session whose root does not answer is kept: its
+  commands are rejected `root_unavailable` until it does, and `close` still closes it.
+- **Signed in before ready.** A new session of an agent that reports its sign-in (Claude Code does) and reports none is
+  refused at once with `agent_auth_required`, instead of opening and failing at its first message; a session that
+  already exists is kept and its prompts say why. A prompt refused for the same reason later
+  (an expired login) ends its turn with `error: "agent_auth_required"` and the fix, and the next prompt starts the agent
+  afresh, so a sign-in done on the machine meanwhile is picked up. An adapter that needs a sign-in and offers an
+  `api-key` method (Codex) is told to `authenticate` with it when its environment has `OPENAI_API_KEY` or `CODEX_API_KEY`;
+  the key itself is never sent, the adapter reads its own environment.
+- **Why, in one sentence.** Every refusal (`session_closed`, `command_rejected`, and a `turn_end` that failed for a known
+  reason) carries its stable `reason` code and a `hint`: one English sentence of what to do about it (sign in with which
+  command, which folder to pick, `claw-connector doctor`), with no path and nothing secret, for a client to show beside
+  its own translation of the code.
 - **Ask mode, read back.** After the adapter creates a session, the connector sets the agent's ask mode and reads the
   mode back from the adapter. Your own agent settings may start an adapter in a mode that never asks (bypass, full
   access); an adapter that does not confirm the ask mode, or that warns it will not invoke its permission callback, is
@@ -229,6 +283,9 @@ All of these run on your machine and fail closed.
   which cannot write. `approval = "never"` selects `agent` and starts `agent --force acp` (`--force` is a root flag of the
   Cursor CLI, "force allow commands unless explicitly denied"; it is accepted before or after `acp`). Cursor
   has no `session/resume`; the connector uses `session/load` and marks the replayed history `replay: true`.
+  A Cursor agent that asks therefore answers and plans but changes no file: its capabilities say `edits: false` with an
+  `edits_hint`, `read_only_modes` lists `ask` and `plan` (each such mode in `session_started` carries `read_only: true`),
+  `run` prints a note, and the sample `agents.toml` says so above the Cursor block.
 - **Permissions.** Each permission request becomes a card with the options **the adapter offered**, passed through with
   their own ids and kinds (`allow_once`, `allow_always`, `reject_once`). An answer must be one of those ids; any other is refused
   and the request stays open. An unanswered request is answered `cancelled` after 10 minutes, and a cancel,
@@ -258,6 +315,17 @@ reference, title, directory, last activity, and whether anything holds it open),
 chat client can offer a choice; `session.new` then names the chosen one (`resume_ref`). Claw and the chat client know no
 product: the agent's `kind` is the label `attach`.
 
+**You do not have to add this agent.** Every agent made from the `claude` preset brings one with the same roots, adapter,
+approval and environment, named `<id>-sessions`, so the conversations already on the machine show up on the phone by
+themselves. `existing_sessions = false` on the `claude` agent turns that off; an explicit `claude-attach` agent reading the same
+Claude config directory replaces it.
+
+Each entry also says, for a conversation a terminal holds open, what Claude Code says that terminal is doing (`activity`:
+`working`, `waiting` for the person at it, or `idle`; with `waiting`, `waiting_for` in its words, such as "input needed"). The
+connector looks at Claude Code's session registry and projects directory every 10 seconds (file names and times only; nothing
+is started) and reports a change at once instead of at the next heartbeat, so a conversation a terminal has just opened, or one
+that starts waiting, reaches the phone within seconds.
+
 ```toml
 [[agents]]
 id = "claude-attach"
@@ -319,6 +387,18 @@ A transcript written within the last 10 seconds is refused too (a terminal that
 `session_live`, `recently_written` and `twin_check_failed`; the agent that this connector itself started for the conversation
 is not mistaken for a twin.
 
+A conversation that a terminal has open when the phone asks for it is not refused but watched, read-only. Nothing is
+started: the connector reads the transcript the terminal writes, from its end (opened read-only; nothing is ever written to it),
+and sends each new line as the update an adapter would have sent (the user's words, the agent's words, the steps it starts
+and how they end; thinking and sub-agents are left out), scrubbed for credentials like every event and marked `read_only`.
+The last twenty updates already there are sent first, marked `replay`. `session_started` says `read_only: true` and
+`read_only_reason: "session_live"`. A prompt, a mode change or a decision sent to it is refused with
+`read_only_live_session` and reaches nothing that could write to the transcript; the server refuses them too
+(`session_read_only`). The heartbeat still reports the conversation as `live`, and an attach agent's capabilities say `watch_live: true`, so a
+client offers the watch only where the connector can do it. When the terminal no longer has it open the
+watch ends (`session_closed`, reason `terminal_closed`), and taking it over is then a new session, through every check
+above. A watched session stays read-only across a restart of the connector.
+
 The ask mode still applies: a conversation keeps the mode it was left in, often one that never asks (`bypassPermissions`),
 and the adapter says so while it sets the session up. That warning describes the mode that is about to be replaced, so it is
 set aside until the ask mode (`default`) is locked and read back from the adapter; a warning that comes after that, or a mode
@@ -335,6 +415,7 @@ session stops the agent process; it never deletes the conversation.
 | `run [--supervised]` | Connect and serve. Exit code 78 means starting it again will not help: the connector was revoked, Claw or the identity service refused the sign-in (at start, or for two minutes in a row while running), or there is no usable `agents.toml` or sign-in; the reason is kept in `needs-login.json`, and until `login` removes it `run` exits 78 at once without contacting Claw. `--supervised` marks a run the service started. Any other non-zero exit is worth a restart. A unit written by hand for 0.1.2 and older (`RestartPreventExitStatus=3`): replace it with `claw-connector service install`, which writes the same file. |
 | `service install\|uninstall\|status [--supervisor systemd\|launchd\|script] [--env NAME ...]` | Keep `run` up (see [Keeping it running](#keeping-it-running)). `install` stops a `run` started by hand so the service takes over; `status` also lists the last five disconnects and why. |
 | `status [--json]` | Running or not, paused, signed in, agents, adapter processes, the last disconnect and its reason (`last down:`), a `problem:` line when a new sign-in is needed, and a `warning:` line for each agent whose sessions will be refused because Claude's own settings default to `bypassPermissions` (see [Running without per-step approval](#running-without-per-step-approval)). |
+| `doctor [--agent ID] [--json]` | Check this machine and print one fix per problem (see step 5 of the quick start), then each agent's adapter (step 2); exit 1 when something stops sessions. The report is kept in `doctor.json`; a running connector is signalled to check again and sends what it finds to Claw (each agent's `capabilities.health`). |
 | `pause` / `resume` | Stop every agent within a second and stay offline, or undo that. |
 | `stop` | Stop the running connector and every agent it started. |
 | `logout` | Stop, revoke this machine's connector at Claw (with a key, `DELETE /v1/remote-agents/connectors/:cid`; with a device sign-in, the connector-side `POST .../connectors/:cid/revoke`), ask the identity service to revoke the sign-in, and delete it from this machine. The next sign-in registers a new connector. When Claw cannot be reached or refuses (a Claw from before the connector-side route refuses a device sign-in), the sign-in is still deleted, but `logout` says the connector was not revoked, prints the `curl` that revokes it with a Claw API key of yours, keeps its id (so a later sign-in reuses it), and exits 1. |
@@ -347,12 +428,12 @@ the connector sees it within a heartbeat, stops every agent and exits without re
 
 ## Files
 
-`~/.config/claw-connector/` (or `$XDG_CONFIG_HOME/claw-connector/`): `agents.toml`, `credentials.json` (0600; a file other users can read is
-refused). `~/.local/state/claw-connector/` (or `$XDG_STATE_HOME/claw-connector/`): `connector.json` (the connector's identity and the
+`~/.config/claw-connector/` (or `$XDG_CONFIG_HOME/claw-connector/`, or `$CLAW_CONNECTOR_CONFIG_DIR`): `agents.toml`, `credentials.json`
+(0600; a file other users can read is refused), and `service-env.json` (0600, the agents' sign-in variables `service install` kept). `~/.local/state/claw-connector/` (or `$XDG_STATE_HOME/claw-connector/`): `connector.json` (the connector's identity and the
 commands handled), `sessions.json`, `outbox/` (events not yet acknowledged by Claw), `audit.jsonl` (spawn, directory
 decisions, every command received, every permission request and answer, every automatic approval, mode changes),
-`logs/`, `children.json`, `connector.pid`, `disconnects.jsonl`, `needs-login.json` (only after a run that needs a new sign-in), and with
-the script supervisor `supervisor.pid`, `keepalive.sh` and `run.log`. `CLAW_CONNECTOR_HOME=/some/dir` keeps all of it under one directory.
+`logs/`, `children.json`, `connector.pid`, `disconnects.jsonl`, `needs-login.json` (only after a run that needs a new sign-in), `doctor.json`
+(the last `doctor` report), and with the script supervisor `supervisor.pid`, `keepalive.sh`, `keepalive-last` (when it last ran) and `run.log`. `CLAW_CONNECTOR_HOME=/some/dir` keeps all of it under one directory.
 
 ## Keeping it running
 
@@ -365,32 +446,68 @@ the script supervisor `supervisor.pid`, `keepalive.sh` and `run.log`. `CLAW_CONN
   Log: `run.log` in the state directory.
 - **script** (a container without systemd; an `systemctl` that answers "Running in chroot" counts as none): `claw-connector supervise`
   runs in the background and restarts the connector 5 seconds after it dies; `keepalive.sh` in the state directory starts that
-  supervisor unless it is alive (recorded pid and start time) or a sign-in is needed. Nothing restarts the supervisor after the container
-  restarts, so call `keepalive.sh` from the container's startup command and from a 5-minute cron job. Log: `run.log`.
+  supervisor unless it is alive (recorded pid and start time) or a sign-in is needed. Where a cron daemon runs, `install` adds an
+  `@reboot` and a 5-minute line that call `keepalive.sh` to your crontab (once; `uninstall` removes them). Where none runs (most
+  containers), `install` says so: nothing brings the connector back after a restart until the container's startup command (or
+  `~/.bashrc`) runs `sh keepalive.sh`. Log: `run.log`.
+
+**A container whose home directory does not outlive it** (a dev pod): when `agents.toml` and the sign-in sit on the container's own
+file system (overlay, tmpfs), `init` and `service install` say so. Keep them on storage that survives the container with
+`CLAW_CONNECTOR_CONFIG_DIR=/mnt/<your persistent volume>/claw-connector` (only the configuration and sign-in move; pid files, the outbox
+and logs stay on the local disk), set in your shell profile and in the container's startup command, which then runs
+`claw-connector service ensure` (after installing the package again, if it lived on the container's file system too).
 
 A successful `login` starts an installed service again, so after a revocation or a refused key signing in is the whole fix.
 `keepalive.sh` and the script supervisor start nothing while only a person can help (no `agents.toml`, not signed in,
 `needs-login.json`); under launchd every exit 78 is turned into a clean exit, which launchd does not restart. The service
 installed for a state directory is recorded in its `service.json`.
 
-The unit carries `PATH` (so the agents are found), `CLAW_CONNECTOR_HOME`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `CLAUDE_CONFIG_DIR`,
-`CODEX_HOME`, the CA and proxy variables and `LANG` from the shell that ran `install` (a proxy URL with a password in it only when named with `--env`, e.g. `--env HTTPS_PROXY`); `--env NAME` adds another, except a name that looks
-like a credential (`KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`), which is never written into a unit. Run `install` again after
-changing any of them, or after moving Node. With a service installed, `claw-connector stop` stops the connector until the next login,
+The unit carries `PATH` (so the agents are found), `CLAW_CONNECTOR_HOME`, `CLAW_CONNECTOR_CONFIG_DIR`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`,
+`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, the CA and proxy variables (with `NODE_USE_SYSTEM_CA` and `NODE_USE_ENV_PROXY`), `LANG`, `IS_SANDBOX`, the npm registry and proxy settings, and every
+plain setting of the agents (`ANTHROPIC_*`, `CLAUDE_CODE_*`, `OPENAI_*`, `CODEX_*`, `CURSOR_*` that is not named like a credential:
+`ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`, `CLAUDE_CODE_USE_BEDROCK`...) from the shell that ran `install` (a proxy URL with a password in
+it only when named with `--env`, e.g. `--env HTTPS_PROXY`); `--env NAME` adds another.
+
+The agents' own sign-in variables are never written into a unit. When the shell that runs `install` has `ANTHROPIC_API_KEY`,
+`ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_CUSTOM_HEADERS`, `OPENAI_API_KEY`, `CODEX_API_KEY`, `CURSOR_API_KEY`, the
+AWS keys, a variable Codex's `config.toml` names as a provider's `env_key`, or an `--env` name that looks like a credential (`KEY`,
+`TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`), they are kept in `service-env.json` beside `credentials.json` (mode 0600) and every `run`
+gives them to the agents that do not set them in `[agents.env]` (a configuration directory its group or others may write is first made 0700; one owned by another account is refused). `install` prints their names, never their values; `service status`
+lists them; `uninstall` deletes the file. Without this a connector that works in a terminal loses its agents' sign-in as a service,
+and each session fails at its first message. `CLAW_CONNECTOR_KEY` is never copied. Run `install` again after changing any of them, or
+after moving Node. With a service installed, `claw-connector stop` stops the connector until the next login,
 boot or keep-alive check; to stay offline use `pause`, or `service uninstall`.
 
 **Why it went down.** Every disconnect is appended to `disconnects.jsonl` in the state directory: `server_closed` (a Claw release or
 restart, `superseded` by another run, `token_expired`; reconnected at once), `stream_lost` (the network, with the error), `stopped`,
-`revoked`, `auth_failed`, `failed`, and `process_died` (the previous run never shut down: killed, crashed or the machine restarted;
-dated by its last heartbeat). `status` shows the latest, `service status` the last five.
+`revoked`, `auth_failed`, `failed`, `process_died` (the previous run never shut down: killed, crashed or the machine restarted;
+dated by its last heartbeat), and `connector_limit_reached` (Claw already holds the most connectors one person may have: remove a
+machine you no longer use, in the chat with `/agents` or with `claw-connector logout` on it; the run stays up and tries again every 10
+minutes instead of being restarted every 5 seconds). `status` shows the latest, `service status` the last five.
 
 ## Restarts and crashes
 
-A prompt counts as handled only when it reaches the agent (or is dropped by a cancel, a close or a stop), so a connector that
-dies with a prompt still queued is sent that prompt again by Claw instead of losing it. A permission request waiting
-for an answer lives in the adapter, which dies with the connector: the next run closes such a card (`cancelled`, by
-`connector_restart`), so a phone is not left with a button that does nothing. Session state, unacknowledged events and
-their sequence numbers are on disk; a session resumes in a fresh adapter on its next prompt.
+A prompt counts as handled only when it reaches the agent (or is dropped by a cancel or a close), so a connector that
+dies, or is stopped or restarted by its supervisor, with a prompt still queued is sent that prompt again by Claw instead of
+losing it. A permission request waiting for an answer lives in the adapter, which dies with the connector: the next run
+closes such a card (`cancelled`, by `connector_restart`), so a phone is not left with a button that does nothing. Session
+state, unacknowledged events and their sequence numbers are on disk; a session resumes in a fresh adapter on its next prompt
+(Claude Code's `session/resume`, the conversation intact).
+
+The turn an agent is running is on disk too, from the moment its prompt reaches the agent until its `turn_end`. The next run
+(after a crash, a kill, a pod restart, `stop`, or an upgrade) finds it and:
+
+- carries it on when the agent was waiting for a person's permission for a tool call (not a plan or a question card), the agent
+  always asks (no `approval = "never"`, no `allow_unsafe_modes`) and its session was in a mode that asks, the connector is not
+  paused, and it was away no longer than a card lives (10 minutes): the agent is told the connector restarted and to go on, so
+  it asks again and a new card comes; the prompt's own `turn_end` still ends it. It only asks, so nothing runs that nobody
+  approved. Nothing is carried on before the run has signed in (a revoked connector carries on nothing);
+- otherwise ends it with `turn_end` `{"stopReason": "error", "error": "connector_restarted"}`, naming its prompt (`cmd_id`,
+  `cmd_seq`), so a phone stops waiting for it. The agent is not re-run by itself; the next message resumes the conversation.
+
+Every session used in the last 4 hours, and every one with a turn found this way, then gets one `session_recovered` event
+(`interrupted`: a turn was cut off; `continuing`: it is being carried on; `cmd_id` and `cmd_seq` of that turn), which a chat
+shows as "recovered". A stop by the kill switch (`pause`, a revocation) still ends every turn and drops the queue.
 
 Known limit: the working-directory check resolves the path and starts the adapter in the resolved path, but another process of
 the same user that can rewrite a directory in that path could swap a symlink between the check and the start. The