session-peer 0.6.2__tar.gz → 0.7.0__tar.gz

{session_peer-0.6.2 → session_peer-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: session-peer
-Version: 0.6.2
+Version: 0.7.0
 Summary: Message coding agent sessions locally and over SSH
 Project-URL: Homepage, https://github.com/abruption/session-peer
 Project-URL: Repository, https://github.com/abruption/session-peer
@@ -150,6 +150,9 @@ session-peer list                                  # Claude sessions on this mac
 session-peer list --host web-01                    # Claude sessions over there
 session-peer list --host web-01 --all              # Claude stale records / no inbox
 session-peer list --agent codex --all              # include archived Codex threads
+session-peer doctor                                # local inbox/tool/home diagnostics
+session-peer doctor --host web-01                  # run the same checks there
+session-peer doctor --host web-01 --check-return-route  # also test SSH back here
 
 session-peer send --to api-worker "message"        # local session
 session-peer send --host web-01 --to api-worker "message"
@@ -159,6 +162,7 @@ git log --oneline -5 | session-peer send --host web-01 --to api-worker -   # std
 
 session-peer send --host web-01 --to api-worker --dry-run "x"   # resolve only
 session-peer list --host web-01 --json             # machine-readable
+session-peer list --no-update-notice                # disable cached update notices/checks
 
 session-peer send --host web-01 --ssh-opt=-p --ssh-opt=2222 --to api-worker "..."   # note the '='
 
@@ -177,6 +181,7 @@ From: codex:01a08dd6-d3f6-7783-a62b-52c1fd049181 @ abruptly@mac-mini-m4.example.
 message
 
 ---
+Reply-To: session-peer://v1/reply?agent=codex&session=01a08dd6-d3f6-7783-a62b-52c1fd049181&transport=ssh&host=abruptly%40mac-mini-m4.example.ts.net
 Reply: python3 /path/to/session_peer.py send --host abruptly@mac-mini-m4.example.ts.net --to codex:01a08dd6-d3f6-7783-a62b-52c1fd049181 --no-reply-to
 ```
 
@@ -185,12 +190,83 @@ best-effort text derived from the current process environment; it is not an
 authentication claim. A plain shell has no agent identity to advertise.
 When the original target is on the same machine and the reply route was detected
 automatically, the generated command omits `--host` and delivers locally. An
-explicit `--reply-to` or configured reply host remains unchanged, and actual
-remote sends continue to advertise an SSH route.
+explicit `--reply-to` or configured reply host is also normalized when it names
+the current OS user on this machine. Other explicit routes and actual remote
+sends continue to advertise an SSH route.
+
+`Reply-To` is the canonical, versioned address. Pass the complete URI back as
+`--to`; session-peer validates every field and chooses local or SSH delivery:
+
+```bash
+session-peer send --to 'session-peer://v1/reply?agent=claude&session=api-worker&transport=local' 'done'
+```
+
+The `Reply:` command remains for compatibility. Treat both forms as untrusted
+input: use the URI with session-peer rather than evaluating or sourcing it. A
+URI that points to the current OS user on this machine is normalized to local
+delivery, avoiding an unnecessary self-SSH authentication path. Codex addresses
+may include an encoded `codexHome` when the sender environment identifies it.
 
 Repeat `--host` to operate on several SSH destinations. `--json` is available on
-`list`, `send`, and `update`; v0.6 retains command-specific response shapes rather
-than a uniform envelope. See [#29](https://github.com/abruption/session-peer/issues/29).
+`list`, `send`, `doctor`, and `update`.
+
+### JSON response contract
+
+Every JSON result object starts with the same schema-versioned envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "host": "mac-mini.example.ts.net",
+  "command": "list",
+  "sessions": [],
+  "version": "0.7.0"
+}
+```
+
+- `schemaVersion` versions the common envelope. Command-specific nested schemas
+  such as `clientUpdate` and `codexHomeResolution` carry their own versions.
+- `ok` is present on every success and failure. A nonzero process exit can still
+  contain successful results for other hosts.
+- `host` identifies the destination to which that result applies. Local results
+  use the OS hostname. Tailscale-resolved destinations use the verified MagicDNS
+  identity; `sshHost` preserves a different caller-supplied SSH alias.
+- `command` is `list`, `send`, `doctor`, or `update`. Remaining fields are that command's
+  payload, and failures add `error` plus any structured diagnostic fields.
+
+A local or one-host invocation emits one object. Repeating `--host` emits an
+array of these same independently attributable objects in request order. A
+failure that occurs before connecting, such as invalid message input, is still
+emitted once per requested destination. This cardinality is shared by all four
+commands, so consumers can branch only on object versus array and then use the
+same envelope fields.
+
+Normal commands read a dedicated 24-hour update cache. A missing, expired, or
+invalid cache starts one detached best-effort GitHub refresh and never delays or
+changes the requested command. When a fresh cache proves that the invoking CLI is
+behind a stable release, JSON results add `clientUpdate`:
+
+```json
+{
+  "clientUpdate": {
+    "schemaVersion": 1,
+    "status": "available",
+    "current": "0.7.0",
+    "latest": "0.7.1",
+    "checkedAt": "2026-09-16T10:00:00Z",
+    "source": "github_release_cache",
+    "command": "session-peer update"
+  }
+}
+```
+
+Human output gets the same short guidance on stderr. The field is omitted when
+the client is current, the cache is unavailable or stale, the host is offline,
+or notices are disabled, so absence alone does not prove the client is current.
+For multi-host commands the fact remains scoped to the one invoking CLI and is
+copied into each result object; destination `remoteVersion` fields keep
+their separate meaning. Remote subprocesses do not perform their own refresh.
 
 When local `tailscale status --json` identifies a `--host` by device hostname,
 short MagicDNS name, full MagicDNS name, or Tailscale IP, session-peer verifies and
@@ -239,8 +315,10 @@ pipx upgrade session-peer
 # or, in its virtual environment: python -m pip install --upgrade session-peer
 ```
 
-For these installs, local `session-peer update` (including `--check`) prints
-package-manager guidance without checking GitHub or replacing the package's files.
+For these installs, local `session-peer update` prints package-manager guidance
+without replacing package-owned files. `session-peer update --check` checks the
+latest stable GitHub release, refreshes the shared cache, and reports the exact
+upgrade command, but still does not replace those files.
 
 For standalone programs:
 
@@ -261,6 +339,8 @@ package-managed remote CLI, upgrade it with its own manager on that host instead
 
 Neither local nor remote `update` refreshes the Claude skill. Re-run `install.sh`
 from the desired release checkout to refresh both standalone program and skill.
+Local `session-peer update --check` and `session-peer update` also populate the
+same cache used by automatic notices.
 
 ### Environment variables
 
@@ -272,6 +352,8 @@ from the desired release checkout to refresh both standalone program and skill.
 | `ANTHROPIC_CONFIG_DIR` | Fallback if `CLAUDE_CONFIG_DIR` is unset. |
 | `CODEX_HOME` | Codex discovery/queue home (default `~/.codex`); overridden by `--codex-home`. |
 | `SESSION_PEER_CODEX_HOMES` | Additional destination homes to check for duplicate thread UUIDs and stable live writers before an implicit send/dry-run. JSON array of absolute paths (or `~/…`), not a shell command or a path-separated list. It does not merge listings; an unambiguous active writer may change the implicit send home. |
+| `SESSION_PEER_NO_UPDATE_NOTICE` | Set to `1`, `true`, `yes`, or `on` to disable automatic cached update notices and background refreshes. The per-command equivalent is `--no-update-notice`. Explicit `session-peer update --check` still checks. |
+| `XDG_CACHE_HOME` | Base directory for the update cache; otherwise `~/.cache/session-peer/update.json` is used. |
 
 With `--host`, discovery uses the destination's environment; local environment
 variables are not automatically forwarded. `--codex-home` and `--codex-bin`
@@ -356,7 +438,8 @@ environment inspection, and process arguments are not exposed. Activity
 inspection runs on the destination machine, including over SSH. Platforms
 without POSIX `flock` or `lsof` cannot automatically resolve competing homes and
 must use `--codex-home`. Unconfigured/custom layouts and copies created after the
-check can still be missed. Further diagnostics belong to [#45](https://github.com/abruption/session-peer/issues/45).
+check can still be missed. Use `session-peer doctor` to inspect the selected home,
+bounded candidates, executable, and supported state DB schema without submitting.
 
 ### Submission and JSON results
 
@@ -373,15 +456,17 @@ session-peer portability policy rather than a measured Codex server limit. NUL
 characters cannot be passed as CLI arguments. `--dry-run` verifies the executable
 and saved target without queueing but cannot guarantee a later submission will succeed.
 
-Local Codex list JSON retains `sessions` and `version`, and adds the resolved
-absolute `codexHome` at the top level. Each entry has
+Local Codex list JSON uses the common response envelope and includes `sessions`,
+`version`, and the resolved absolute `codexHome`. Each session entry has
 `agent`, `id`, `name` (first line, at most 120 characters), `cwd`, `updatedAt`
-(Unix seconds), and `archived`. Remote list JSON is an array of per-host results,
-even for one host; each successful result includes `host`, `sessions`, `version`, `codexHome`
-and an optional `remoteVersion` for an installed standalone copy.
+(Unix seconds), and `archived`. Each successful remote result includes
+`sessions`, `version`, `codexHome`, and an optional `remoteVersion` for an
+installed standalone copy. One remote host returns an object; repeated hosts
+return an array.
 
-Codex send JSON retains `target: {agent, id}`, `status: queued` (or `validated`
-under dry-run), `ok`, `chars`, `dryRun`, and optional `queueId`. It adds:
+Within the common envelope, Codex send JSON includes `target: {agent, id}`,
+`status: queued` (or `validated` under dry-run), `chars`, `dryRun`, and optional
+`queueId`. It also includes:
 
 - `codexHome`: the resolved absolute destination home, not a sender-side guess.
 - `codexHomeResolution`: schema-versioned `status`, `selected`, `reason`, and
@@ -391,21 +476,40 @@ under dry-run), `ok`, `chars`, `dryRun`, and optional `queueId`. It adds:
 - `submitted`: `true` only after successful queue CLI completion, `false` for dry-run.
 - `consumptionConfirmed`: always `false`; neither queued nor validated establishes consumption.
 
-Errors keep the existing `{ok: false, error}` fields (plus host on remote results)
-and add `codexHomeResolution` when home evidence caused the failure.
+Errors set the common envelope's `ok` to `false`, add `error`, and include
+`codexHomeResolution` when home evidence caused the failure.
 A timeout has an unknown submission outcome; missing `submitted` on an error
 must not be interpreted as proof that nothing was queued. Listing results do
-not describe a submission and have no submission/consumption fields. The changes
-are additive, not the cross-command envelope redesign tracked in [#29](https://github.com/abruption/session-peer/issues/29).
+not describe a submission and have no submission/consumption fields.
 
-A remote send to one host returns a flat object with `host`; multiple hosts return an array.
-Claude output stays compatible. When `CODEX_THREAD_ID` (or the compatibility
+For every command, one remote host returns a flat object and multiple hosts
+return an array. When `CODEX_THREAD_ID` (or the compatibility
 fallback `CODEX_SESSION_ID`) is present, the message envelope and reply command
 identify the originating Codex thread.
 
-`doctor`, reply waiting/`--wait`, structured reply URIs and optional wake are
-future work, not v0.6 features: see the [v0.7](https://github.com/abruption/session-peer/issues/45)
-and [v0.8](https://github.com/abruption/session-peer/issues/46) roadmaps.
+### Diagnostics and reply observation
+
+`doctor` performs read-only checks on the machine that owns the sessions. It
+reports Claude's configured sessions directory and inbox availability, Codex's
+executable and bounded home/state DB candidates, unsupported DB schemas, and
+permission or unknown failures as distinct codes. It does not connect to an
+inbox, write a queue, scan arbitrary directories, or alter agent/SSH settings.
+
+Reverse SSH is checked only with `--check-return-route`. The destination runs a
+fixed `ssh ... true` probe with prompts, password authentication, host-key
+enrollment, and config mutation disabled. Forward SSH success is never reused as
+proof that the reverse path works. Use `--reply-to USER@HOST` when automatic
+Tailscale detection cannot identify the origin. JSON details and status values
+are documented in [docs/diagnostics.md](docs/diagnostics.md).
+
+There is deliberately no general `--wait`. Claude Code has a native
+same-machine `notify_when_idle` facility, but it does not cover remote sessions,
+subagents, or Codex, and a successful socket/queue submission is not an
+acknowledgement. session-peer therefore reports
+`capabilities.replyObservation.status: unsupported` instead of tailing mutable
+transcripts and risking a false match. Ask the target to send an explicit reply
+to the supplied `Reply-To` address when completion matters. Optional wake remains
+tracked in [#46](https://github.com/abruption/session-peer/issues/46).
 
 ## Moving from cc-peer
 
@@ -508,9 +612,10 @@ not as the user typing approval.
   Outside that context, it may omit it. This is not an authenticated identity
   protocol; environment variables and session registries are local hints.
 - **Advertised replies need a working return path.** When an agent sender and
-  reply host can be determined, a `Reply:` line supplies an SSH return command.
-  Forward SSH success does not prove reverse SSH access. v0.6 does not verify
-  that route, correlate a reply, or wait for one; the address grants no access.
+  reply host can be determined, `Reply-To` and a compatibility `Reply:` line
+  describe a return route. Forward SSH success does not prove reverse SSH
+  access; use the opt-in doctor check. The address grants no access and
+  session-peer does not correlate or wait for a reply.
 - **Tailscale status is a local routing hint.** A known online peer is addressed
   by its current MagicDNS name and a known offline peer is rejected before SSH.
   An unknown destination remains ordinary SSH; session-peer does not claim that
@@ -525,7 +630,8 @@ not as the user typing approval.
 - **Windows support.** Claude's named pipe transport is supported.
   `install.sh` and the standalone remote installer/updater use POSIX shell;
   use a Python package manager on native Windows. Live Codex verification
-  for v0.6 was on macOS, not Windows.
+  remains macOS-only; the Codex home, Reply-To, doctor, and JSON fixtures run in
+  Windows CI.
 
 ## Tests
 
@@ -533,7 +639,7 @@ not as the user typing approval.
 python3 -m unittest discover -s tests -v
 ```
 
-The suite needs no live agent, SSH server or network. It includes legacy
+The default suite needs no live agent, SSH server or network. It includes legacy
 compatibility tests, shared CLI helpers, fixture-based Codex discovery and queue
 subprocess tests, and isolated standalone installation/coexistence checks.
 Codex coverage includes argv/payload handling, destination home selection,
@@ -544,6 +650,9 @@ homes, unique/multiple/changing writer evidence, fail-closed inventory errors,
 explicit selection, alias deduplication, single-home compatibility and structured
 home/submission metadata. They never infer a live writer from a saved row or
 submit messages to real sessions.
+Update-notice coverage checks freshness and expiry, strict stable versions,
+atomic private writes, single-flight background refresh, opt-out behavior,
+package-manager guidance, multi-host scope, and failure isolation.
 
 CI runs tests on Ubuntu/macOS with Python 3.9 and 3.13, and Windows with Python
 3.13 (POSIX installer tests are skipped there). Separate jobs check shell syntax
@@ -554,6 +663,20 @@ tests remain tracked in [#28](https://github.com/abruption/session-peer/issues/2
 
 ## Verified
 
+### session-peer v0.7.0 (2026-09-16)
+
+- 240 local tests passed for cached update notices, the shared JSON envelope,
+  read-only diagnostics, structured Reply-To parsing/routing, same-machine
+  normalization, and opt-in reverse-route classification.
+- CI covers Ubuntu and macOS with Python 3.9/3.13, Windows with Python 3.13,
+  package build and isolated installs, standalone install smoke tests, shellcheck,
+  and secret scanning.
+- Wheel and sdist contents were inspected and installed independently. Both
+  artifacts report v0.7.0 and exclude the frozen legacy `cc_peer.py`.
+- A real SSH doctor run found Claude inboxes and bounded default/Orca Codex homes.
+  Its opt-in reverse probe reported authentication failure independently of the
+  successful forward connection. No live message was submitted.
+
 ### session-peer v0.6.2 (2026-09-15)
 
 - 198 local tests and the release build checks passed for UUID-specific Codex

{session_peer-0.6.2 → session_peer-0.7.0}/README.md

@@ -121,6 +121,9 @@ session-peer list                                  # Claude sessions on this mac
 session-peer list --host web-01                    # Claude sessions over there
 session-peer list --host web-01 --all              # Claude stale records / no inbox
 session-peer list --agent codex --all              # include archived Codex threads
+session-peer doctor                                # local inbox/tool/home diagnostics
+session-peer doctor --host web-01                  # run the same checks there
+session-peer doctor --host web-01 --check-return-route  # also test SSH back here
 
 session-peer send --to api-worker "message"        # local session
 session-peer send --host web-01 --to api-worker "message"
@@ -130,6 +133,7 @@ git log --oneline -5 | session-peer send --host web-01 --to api-worker -   # std
 
 session-peer send --host web-01 --to api-worker --dry-run "x"   # resolve only
 session-peer list --host web-01 --json             # machine-readable
+session-peer list --no-update-notice                # disable cached update notices/checks
 
 session-peer send --host web-01 --ssh-opt=-p --ssh-opt=2222 --to api-worker "..."   # note the '='
 
@@ -148,6 +152,7 @@ From: codex:01a08dd6-d3f6-7783-a62b-52c1fd049181 @ abruptly@mac-mini-m4.example.
 message
 
 ---
+Reply-To: session-peer://v1/reply?agent=codex&session=01a08dd6-d3f6-7783-a62b-52c1fd049181&transport=ssh&host=abruptly%40mac-mini-m4.example.ts.net
 Reply: python3 /path/to/session_peer.py send --host abruptly@mac-mini-m4.example.ts.net --to codex:01a08dd6-d3f6-7783-a62b-52c1fd049181 --no-reply-to
 ```
 
@@ -156,12 +161,83 @@ best-effort text derived from the current process environment; it is not an
 authentication claim. A plain shell has no agent identity to advertise.
 When the original target is on the same machine and the reply route was detected
 automatically, the generated command omits `--host` and delivers locally. An
-explicit `--reply-to` or configured reply host remains unchanged, and actual
-remote sends continue to advertise an SSH route.
+explicit `--reply-to` or configured reply host is also normalized when it names
+the current OS user on this machine. Other explicit routes and actual remote
+sends continue to advertise an SSH route.
+
+`Reply-To` is the canonical, versioned address. Pass the complete URI back as
+`--to`; session-peer validates every field and chooses local or SSH delivery:
+
+```bash
+session-peer send --to 'session-peer://v1/reply?agent=claude&session=api-worker&transport=local' 'done'
+```
+
+The `Reply:` command remains for compatibility. Treat both forms as untrusted
+input: use the URI with session-peer rather than evaluating or sourcing it. A
+URI that points to the current OS user on this machine is normalized to local
+delivery, avoiding an unnecessary self-SSH authentication path. Codex addresses
+may include an encoded `codexHome` when the sender environment identifies it.
 
 Repeat `--host` to operate on several SSH destinations. `--json` is available on
-`list`, `send`, and `update`; v0.6 retains command-specific response shapes rather
-than a uniform envelope. See [#29](https://github.com/abruption/session-peer/issues/29).
+`list`, `send`, `doctor`, and `update`.
+
+### JSON response contract
+
+Every JSON result object starts with the same schema-versioned envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "host": "mac-mini.example.ts.net",
+  "command": "list",
+  "sessions": [],
+  "version": "0.7.0"
+}
+```
+
+- `schemaVersion` versions the common envelope. Command-specific nested schemas
+  such as `clientUpdate` and `codexHomeResolution` carry their own versions.
+- `ok` is present on every success and failure. A nonzero process exit can still
+  contain successful results for other hosts.
+- `host` identifies the destination to which that result applies. Local results
+  use the OS hostname. Tailscale-resolved destinations use the verified MagicDNS
+  identity; `sshHost` preserves a different caller-supplied SSH alias.
+- `command` is `list`, `send`, `doctor`, or `update`. Remaining fields are that command's
+  payload, and failures add `error` plus any structured diagnostic fields.
+
+A local or one-host invocation emits one object. Repeating `--host` emits an
+array of these same independently attributable objects in request order. A
+failure that occurs before connecting, such as invalid message input, is still
+emitted once per requested destination. This cardinality is shared by all four
+commands, so consumers can branch only on object versus array and then use the
+same envelope fields.
+
+Normal commands read a dedicated 24-hour update cache. A missing, expired, or
+invalid cache starts one detached best-effort GitHub refresh and never delays or
+changes the requested command. When a fresh cache proves that the invoking CLI is
+behind a stable release, JSON results add `clientUpdate`:
+
+```json
+{
+  "clientUpdate": {
+    "schemaVersion": 1,
+    "status": "available",
+    "current": "0.7.0",
+    "latest": "0.7.1",
+    "checkedAt": "2026-09-16T10:00:00Z",
+    "source": "github_release_cache",
+    "command": "session-peer update"
+  }
+}
+```
+
+Human output gets the same short guidance on stderr. The field is omitted when
+the client is current, the cache is unavailable or stale, the host is offline,
+or notices are disabled, so absence alone does not prove the client is current.
+For multi-host commands the fact remains scoped to the one invoking CLI and is
+copied into each result object; destination `remoteVersion` fields keep
+their separate meaning. Remote subprocesses do not perform their own refresh.
 
 When local `tailscale status --json` identifies a `--host` by device hostname,
 short MagicDNS name, full MagicDNS name, or Tailscale IP, session-peer verifies and
@@ -210,8 +286,10 @@ pipx upgrade session-peer
 # or, in its virtual environment: python -m pip install --upgrade session-peer
 ```
 
-For these installs, local `session-peer update` (including `--check`) prints
-package-manager guidance without checking GitHub or replacing the package's files.
+For these installs, local `session-peer update` prints package-manager guidance
+without replacing package-owned files. `session-peer update --check` checks the
+latest stable GitHub release, refreshes the shared cache, and reports the exact
+upgrade command, but still does not replace those files.
 
 For standalone programs:
 
@@ -232,6 +310,8 @@ package-managed remote CLI, upgrade it with its own manager on that host instead
 
 Neither local nor remote `update` refreshes the Claude skill. Re-run `install.sh`
 from the desired release checkout to refresh both standalone program and skill.
+Local `session-peer update --check` and `session-peer update` also populate the
+same cache used by automatic notices.
 
 ### Environment variables
 
@@ -243,6 +323,8 @@ from the desired release checkout to refresh both standalone program and skill.
 | `ANTHROPIC_CONFIG_DIR` | Fallback if `CLAUDE_CONFIG_DIR` is unset. |
 | `CODEX_HOME` | Codex discovery/queue home (default `~/.codex`); overridden by `--codex-home`. |
 | `SESSION_PEER_CODEX_HOMES` | Additional destination homes to check for duplicate thread UUIDs and stable live writers before an implicit send/dry-run. JSON array of absolute paths (or `~/…`), not a shell command or a path-separated list. It does not merge listings; an unambiguous active writer may change the implicit send home. |
+| `SESSION_PEER_NO_UPDATE_NOTICE` | Set to `1`, `true`, `yes`, or `on` to disable automatic cached update notices and background refreshes. The per-command equivalent is `--no-update-notice`. Explicit `session-peer update --check` still checks. |
+| `XDG_CACHE_HOME` | Base directory for the update cache; otherwise `~/.cache/session-peer/update.json` is used. |
 
 With `--host`, discovery uses the destination's environment; local environment
 variables are not automatically forwarded. `--codex-home` and `--codex-bin`
@@ -327,7 +409,8 @@ environment inspection, and process arguments are not exposed. Activity
 inspection runs on the destination machine, including over SSH. Platforms
 without POSIX `flock` or `lsof` cannot automatically resolve competing homes and
 must use `--codex-home`. Unconfigured/custom layouts and copies created after the
-check can still be missed. Further diagnostics belong to [#45](https://github.com/abruption/session-peer/issues/45).
+check can still be missed. Use `session-peer doctor` to inspect the selected home,
+bounded candidates, executable, and supported state DB schema without submitting.
 
 ### Submission and JSON results
 
@@ -344,15 +427,17 @@ session-peer portability policy rather than a measured Codex server limit. NUL
 characters cannot be passed as CLI arguments. `--dry-run` verifies the executable
 and saved target without queueing but cannot guarantee a later submission will succeed.
 
-Local Codex list JSON retains `sessions` and `version`, and adds the resolved
-absolute `codexHome` at the top level. Each entry has
+Local Codex list JSON uses the common response envelope and includes `sessions`,
+`version`, and the resolved absolute `codexHome`. Each session entry has
 `agent`, `id`, `name` (first line, at most 120 characters), `cwd`, `updatedAt`
-(Unix seconds), and `archived`. Remote list JSON is an array of per-host results,
-even for one host; each successful result includes `host`, `sessions`, `version`, `codexHome`
-and an optional `remoteVersion` for an installed standalone copy.
+(Unix seconds), and `archived`. Each successful remote result includes
+`sessions`, `version`, `codexHome`, and an optional `remoteVersion` for an
+installed standalone copy. One remote host returns an object; repeated hosts
+return an array.
 
-Codex send JSON retains `target: {agent, id}`, `status: queued` (or `validated`
-under dry-run), `ok`, `chars`, `dryRun`, and optional `queueId`. It adds:
+Within the common envelope, Codex send JSON includes `target: {agent, id}`,
+`status: queued` (or `validated` under dry-run), `chars`, `dryRun`, and optional
+`queueId`. It also includes:
 
 - `codexHome`: the resolved absolute destination home, not a sender-side guess.
 - `codexHomeResolution`: schema-versioned `status`, `selected`, `reason`, and
@@ -362,21 +447,40 @@ under dry-run), `ok`, `chars`, `dryRun`, and optional `queueId`. It adds:
 - `submitted`: `true` only after successful queue CLI completion, `false` for dry-run.
 - `consumptionConfirmed`: always `false`; neither queued nor validated establishes consumption.
 
-Errors keep the existing `{ok: false, error}` fields (plus host on remote results)
-and add `codexHomeResolution` when home evidence caused the failure.
+Errors set the common envelope's `ok` to `false`, add `error`, and include
+`codexHomeResolution` when home evidence caused the failure.
 A timeout has an unknown submission outcome; missing `submitted` on an error
 must not be interpreted as proof that nothing was queued. Listing results do
-not describe a submission and have no submission/consumption fields. The changes
-are additive, not the cross-command envelope redesign tracked in [#29](https://github.com/abruption/session-peer/issues/29).
+not describe a submission and have no submission/consumption fields.
 
-A remote send to one host returns a flat object with `host`; multiple hosts return an array.
-Claude output stays compatible. When `CODEX_THREAD_ID` (or the compatibility
+For every command, one remote host returns a flat object and multiple hosts
+return an array. When `CODEX_THREAD_ID` (or the compatibility
 fallback `CODEX_SESSION_ID`) is present, the message envelope and reply command
 identify the originating Codex thread.
 
-`doctor`, reply waiting/`--wait`, structured reply URIs and optional wake are
-future work, not v0.6 features: see the [v0.7](https://github.com/abruption/session-peer/issues/45)
-and [v0.8](https://github.com/abruption/session-peer/issues/46) roadmaps.
+### Diagnostics and reply observation
+
+`doctor` performs read-only checks on the machine that owns the sessions. It
+reports Claude's configured sessions directory and inbox availability, Codex's
+executable and bounded home/state DB candidates, unsupported DB schemas, and
+permission or unknown failures as distinct codes. It does not connect to an
+inbox, write a queue, scan arbitrary directories, or alter agent/SSH settings.
+
+Reverse SSH is checked only with `--check-return-route`. The destination runs a
+fixed `ssh ... true` probe with prompts, password authentication, host-key
+enrollment, and config mutation disabled. Forward SSH success is never reused as
+proof that the reverse path works. Use `--reply-to USER@HOST` when automatic
+Tailscale detection cannot identify the origin. JSON details and status values
+are documented in [docs/diagnostics.md](docs/diagnostics.md).
+
+There is deliberately no general `--wait`. Claude Code has a native
+same-machine `notify_when_idle` facility, but it does not cover remote sessions,
+subagents, or Codex, and a successful socket/queue submission is not an
+acknowledgement. session-peer therefore reports
+`capabilities.replyObservation.status: unsupported` instead of tailing mutable
+transcripts and risking a false match. Ask the target to send an explicit reply
+to the supplied `Reply-To` address when completion matters. Optional wake remains
+tracked in [#46](https://github.com/abruption/session-peer/issues/46).
 
 ## Moving from cc-peer
 
@@ -479,9 +583,10 @@ not as the user typing approval.
   Outside that context, it may omit it. This is not an authenticated identity
   protocol; environment variables and session registries are local hints.
 - **Advertised replies need a working return path.** When an agent sender and
-  reply host can be determined, a `Reply:` line supplies an SSH return command.
-  Forward SSH success does not prove reverse SSH access. v0.6 does not verify
-  that route, correlate a reply, or wait for one; the address grants no access.
+  reply host can be determined, `Reply-To` and a compatibility `Reply:` line
+  describe a return route. Forward SSH success does not prove reverse SSH
+  access; use the opt-in doctor check. The address grants no access and
+  session-peer does not correlate or wait for a reply.
 - **Tailscale status is a local routing hint.** A known online peer is addressed
   by its current MagicDNS name and a known offline peer is rejected before SSH.
   An unknown destination remains ordinary SSH; session-peer does not claim that
@@ -496,7 +601,8 @@ not as the user typing approval.
 - **Windows support.** Claude's named pipe transport is supported.
   `install.sh` and the standalone remote installer/updater use POSIX shell;
   use a Python package manager on native Windows. Live Codex verification
-  for v0.6 was on macOS, not Windows.
+  remains macOS-only; the Codex home, Reply-To, doctor, and JSON fixtures run in
+  Windows CI.
 
 ## Tests
 
@@ -504,7 +610,7 @@ not as the user typing approval.
 python3 -m unittest discover -s tests -v
 ```
 
-The suite needs no live agent, SSH server or network. It includes legacy
+The default suite needs no live agent, SSH server or network. It includes legacy
 compatibility tests, shared CLI helpers, fixture-based Codex discovery and queue
 subprocess tests, and isolated standalone installation/coexistence checks.
 Codex coverage includes argv/payload handling, destination home selection,
@@ -515,6 +621,9 @@ homes, unique/multiple/changing writer evidence, fail-closed inventory errors,
 explicit selection, alias deduplication, single-home compatibility and structured
 home/submission metadata. They never infer a live writer from a saved row or
 submit messages to real sessions.
+Update-notice coverage checks freshness and expiry, strict stable versions,
+atomic private writes, single-flight background refresh, opt-out behavior,
+package-manager guidance, multi-host scope, and failure isolation.
 
 CI runs tests on Ubuntu/macOS with Python 3.9 and 3.13, and Windows with Python
 3.13 (POSIX installer tests are skipped there). Separate jobs check shell syntax
@@ -525,6 +634,20 @@ tests remain tracked in [#28](https://github.com/abruption/session-peer/issues/2
 
 ## Verified
 
+### session-peer v0.7.0 (2026-09-16)
+
+- 240 local tests passed for cached update notices, the shared JSON envelope,
+  read-only diagnostics, structured Reply-To parsing/routing, same-machine
+  normalization, and opt-in reverse-route classification.
+- CI covers Ubuntu and macOS with Python 3.9/3.13, Windows with Python 3.13,
+  package build and isolated installs, standalone install smoke tests, shellcheck,
+  and secret scanning.
+- Wheel and sdist contents were inspected and installed independently. Both
+  artifacts report v0.7.0 and exclude the frozen legacy `cc_peer.py`.
+- A real SSH doctor run found Claude inboxes and bounded default/Orca Codex homes.
+  Its opt-in reverse probe reported authentication failure independently of the
+  successful forward connection. No live message was submitted.
+
 ### session-peer v0.6.2 (2026-09-15)
 
 - 198 local tests and the release build checks passed for UUID-specific Codex