relay-shell 0.5.2__tar.gz → 0.5.3__tar.gz

{relay_shell-0.5.2 → relay_shell-0.5.3}/.env.example

@@ -126,7 +126,7 @@ RELAY_SHELL_EDGE_UPSTREAM=127.0.0.1:8080
 # Set to https://acme-staging-v02.api.letsencrypt.org/directory for dry runs.
 RELAY_SHELL_EDGE_ACME_CA=https://acme-v02.api.letsencrypt.org/directory
 
-# --- OAuth 2.1 (HTTP transport only; requires the [http] extra) ---
+# --- OAuth 2.1 (HTTP transport only; plain install includes dependencies) ---
 RELAY_SHELL_AUTH_ENABLED=false
 RELAY_SHELL_AUTH_ISSUER=https://localhost:8080
 RELAY_SHELL_AUTH_STATE_DIR=/var/lib/relay-shell/oauth

{relay_shell-0.5.2 → relay_shell-0.5.3}/.github/ISSUE_TEMPLATE/feature.md

@@ -49,7 +49,7 @@ plus a script) and the only ask is ergonomics, say so explicitly. -->
 - an entry in `tests/test_server.py::_EXPECTED` plus the `len()` assertion
 - an entry in the README capability table
 - a unit test of the underlying helper
-- a wiring test that exercises the tool through FastMCP
+- a wiring test that exercises the tool through `MCPServer`
 - the `_INSTRUCTIONS` string in `server.py` -->
 
 ## Out of scope

{relay_shell-0.5.2 → relay_shell-0.5.3}/.github/PULL_REQUEST_TEMPLATE.md

@@ -37,8 +37,10 @@ if applicable: "Closes F-6 from docs/runbook.md". -->
       `docs/deployment.md`.
 - [ ] A new permissive setting has a matching entry in `notices.config_warnings`, and the
       default configuration still refuses no command (ADR 0013).
-- [ ] No new dependency is added without a justification in the PR body
-      and a pinned version in `requirements.txt`.
+- [ ] Dependency changes justify the addition in the PR body, align
+      `pyproject.toml`, `requirements.txt` and the matching `requirements/*.in`
+      scope, and regenerate all affected runtime/development/tooling hash locks
+      for both qualified profiles (runbook §6.6 and `requirements/README.md`).
 
 ## Security-sensitive diff (runbook §3.3)
 

{relay_shell-0.5.2 → relay_shell-0.5.3}/.github/copilot-instructions.md

@@ -34,5 +34,5 @@ MCP shell/SSH operator infrastructure. Read `docs/runbook.md` (especially its au
 - Audit arguments must be redacted; output bodies must not be logged, only length/hash. Preserve chain limitations, rotation continuity, off-host integrity requirements, and secret-prompt handling. Redaction is heuristic and must be tested with synthetic secrets.
 - Tool errors use existing bounded structured error helpers, not raw tracebacks or uncaught transport failures. Preserve cancellation and cleanup, close only owned sessions, and reconcile timeouts before retrying mutations.
 - Technical map: `src/relay_shell/server.py` registers tools; config, policy, broker, audit, redaction, patterns, sessions and sshpool define the principal boundaries. `tests/test_server.py::_EXPECTED` is the tool-registration contract.
-- Setup: `python -m pip install -e ".[dev]"`. Run `ruff check .`, `ruff format --check .`, `mypy`, `pytest -q`. For classifier/redactor changes also run `pytest -m fuzz -v`; update PATTERNS_VERSION when required by the existing contract. Preserve CodeQL, dependency review, dependency audit and secret-scanning gates.
+- Setup: follow the matching hash-locked development profile and no-dependency editable install in `CONTRIBUTING.md` (the canonical local loop). Run `ruff check .`, `ruff format --check .`, `mypy`, `pytest -q`. For classifier/redactor changes also run `pytest -m fuzz -v`; update PATTERNS_VERSION when required by the existing contract. Preserve CodeQL, dependency review, dependency audit and secret-scanning gates.
 - Use async I/O in tool paths; do not add requests/urllib3 blocking calls. Live shell/SSH smokes require explicit targets and bounded effects. Editing this repo does not authorize restarting or deploying its running service.

{relay_shell-0.5.2 → relay_shell-0.5.3}/.github/workflows/ci.yml

@@ -88,7 +88,7 @@ jobs:
           GODEBUG: http2client=0
         run: |
           command -v go
-          go install github.com/caddyserver/caddy/v2/cmd/caddy@v2.11.7
+          go install github.com/caddyserver/caddy/v2/cmd/caddy@v2.11.9
           echo "CADDY_BINARY=$GOBIN/caddy" >> "$GITHUB_ENV"
 
       - name: Lint (ruff)

{relay_shell-0.5.2 → relay_shell-0.5.3}/.github/workflows/codeql.yml

@@ -38,15 +38,15 @@ jobs:
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370  # v4
+        uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066  # v4
         with:
           languages: ${{ matrix.language }}
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@9b3254085494b55a0f7c4c2b3d2d52cc712ce370  # v4
+        uses: github/codeql-action/autobuild@33d7b85da1a04171e211befe2c739303b9a4c066  # v4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370  # v4
+        uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066  # v4
 
   # A14-D12: the workflows themselves are code that holds tokens. A separate job (not a
   # matrix entry) so the required check `Analyze (python) (python)` keeps its name. It is in
@@ -63,12 +63,12 @@ jobs:
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370  # v4
+        uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066  # v4
         with:
           languages: actions
           build-mode: none
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370  # v4
+        uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066  # v4
         with:
           category: "/language:actions"

{relay_shell-0.5.2 → relay_shell-0.5.3}/.github/workflows/docs.yml

@@ -28,7 +28,7 @@ concurrency:
 jobs:
   build:
     name: Build (MkDocs Material)
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.04
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
@@ -55,7 +55,7 @@ jobs:
     name: Deploy to GitHub Pages
     needs: build
     if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.04
     timeout-minutes: 10
     permissions:
       pages: write # publish the Pages deployment

{relay_shell-0.5.2 → relay_shell-0.5.3}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 # Pre-commit hooks for relay-shell.
 #
-# Install: `pip install pre-commit && pre-commit install`
+# Install the matching locked development profile, then run `pre-commit install`.
 # Run on a single file: `pre-commit run --files <path>`
 # Run on the whole tree: `pre-commit run --all-files`
 #
@@ -15,7 +15,7 @@ repos:
     # Pin to a known-good ruff release. Update this `rev` and the
     # `ruff==` pin in `[project.optional-dependencies] dev` together
     # so local pre-commit and `pip install -e ".[dev]"` agree.
-    rev: v0.17.2
+    rev: v0.17.3
     hooks:
       - id: ruff
         args: [--fix]
@@ -24,11 +24,11 @@ repos:
   - repo: local
     hooks:
       # mypy --strict needs the project's full import graph (asyncssh stubs
-      # override, FastMCP Context typing, etc.). Run it from the project's
+      # override, MCPServer Context typing, etc.). Run it from the project's
       # own venv rather than an isolated pre-commit env so the configured
       # overrides in pyproject.toml apply identically here and in CI. This
-      # assumes the contributor ran `pip install -e ".[dev]"` first, which
-      # the runbook §4.1 already requires.
+      # assumes the contributor installed the matching locked development profile
+      # and no-dependency editable checkout from runbook §4.1 first.
       - id: mypy
         name: mypy --strict (project venv)
         entry: mypy

{relay_shell-0.5.2 → relay_shell-0.5.3}/AGENTS.md

@@ -11,7 +11,7 @@ MCP shell/SSH operator infrastructure. Read `docs/runbook.md` (especially its au
 - Audit arguments must be redacted; output bodies must not be logged, only length/hash. Preserve chain limitations, rotation continuity, off-host integrity requirements, and secret-prompt handling. Redaction is heuristic and must be tested with synthetic secrets.
 - Tool errors use existing bounded structured error helpers, not raw tracebacks or uncaught transport failures. Preserve cancellation and cleanup, close only owned sessions, and reconcile timeouts before retrying mutations.
 - Technical map: `src/relay_shell/server.py` registers tools; config, policy, broker, audit, redaction, patterns, sessions and sshpool define the principal boundaries. `tests/test_server.py::_EXPECTED` is the tool-registration contract.
-- Setup: `python -m pip install -e ".[dev]"`. Run `ruff check .`, `ruff format --check .`, `mypy`, `pytest -q`. For classifier/redactor changes also run `pytest -m fuzz -v`; update PATTERNS_VERSION when required by the existing contract. Preserve CodeQL, dependency review, dependency audit and secret-scanning gates.
+- Setup: follow the matching hash-locked development profile and no-dependency editable install in `CONTRIBUTING.md` (the canonical local loop). Run `ruff check .`, `ruff format --check .`, `mypy`, `pytest -q`. For classifier/redactor changes also run `pytest -m fuzz -v`; update PATTERNS_VERSION when required by the existing contract. Preserve CodeQL, dependency review, dependency audit and secret-scanning gates.
 - Use async I/O in tool paths; do not add requests/urllib3 blocking calls. Live shell/SSH smokes require explicit targets and bounded effects. Editing this repo does not authorize restarting or deploying its running service.
 
 ## Working contract

{relay_shell-0.5.2 → relay_shell-0.5.3}/BACKLOG.md

@@ -298,6 +298,11 @@ reauthorization. Operational TLS/clients, broader state-policy reconciliation,
 binary-only downgrades, automatic rollback and live-host recovery remain open.
 
 
+**Runner update, 2026-11-07:** the current cross-version job now runs on
+Ubuntu 26.04 with an explicit legacy Python 3.12 interpreter. The paragraph above
+records the initial qualification; the native qualified profiles remain
+Ubuntu 24.04/Python 3.12 and Ubuntu 26.04/Python 3.14.
+
 ### Installer rollback qualification (2026-10-20)
 
 Implemented automatic restoration for ordinary installer errors and handled

{relay_shell-0.5.2 → relay_shell-0.5.3}/CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.5.3] - 2026-11-12
+
+### Fixed
+
+- Restrict rotated audit-log selection to the configured log basename so unrelated
+  streams cannot supply the restart chain anchor.
+
+- Align quickstart/deployment instructions with locked profiles and installer recovery;
+  clarify audit, timeout and resource/prompt limits, edge-variable precedence and
+  OAuth reauthorization. Refresh release-signature evidence through v0.5.2.
+- Correct the Vector shipping configuration, package-source guidance and parser
+  error handling; document protocol and rotation/backfill limits.
+- Use system fonts for the documentation site to avoid third-party font requests.
+
+- Give Renovate separate runtime/development lock inputs with manifest alignment
+  checks, and normalize the bootstrap regeneration command's option arguments.
+  This preserves runtime scope while allowing all hashed profiles to be extracted.
+
 ## [0.5.2] - 2026-11-02
 
 ### Fixed
@@ -1829,7 +1847,8 @@ All notable changes to this project are documented here. The format follows
   bundled logrotate config drops and restores the append-only attribute
   across rotation. See `docs/deployment.md` §6.
 
-[Unreleased]: https://github.com/rmednitzer/relay-shell/compare/v0.5.2...HEAD
+[Unreleased]: https://github.com/rmednitzer/relay-shell/compare/v0.5.3...HEAD
+[0.5.3]: https://github.com/rmednitzer/relay-shell/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/rmednitzer/relay-shell/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/rmednitzer/relay-shell/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/rmednitzer/relay-shell/compare/v0.4.0...v0.5.0

{relay_shell-0.5.2 → relay_shell-0.5.3}/CONTRIBUTING.md

@@ -99,8 +99,8 @@ short version:
 | Add or remove a tool         | `docs/tools.md`, `tests/test_server.py::_EXPECTED`, README capability tables, `_INSTRUCTIONS` in `server.py` |
 | Add or remove an env var     | `.env.example`, `Settings`, `docs/deployment.md` (and `notices.config_warnings` if it widens access) |
 | Add or change a module       | `docs/architecture.md` module table                                                    |
-| Add a runtime dependency     | `requirements.txt` (pinned), the `pyproject.toml` bound + a justification in the PR body |
-| Change release/SBOM tooling or a workflow | `requirements-build.in` / `requirements-sbom.in` then regenerate the hashed `.txt` locks (runbook §6.6), `tests/test_release_workflows.py` |
+| Add a runtime dependency     | `pyproject.toml` bound, `requirements.txt` pin, `requirements/runtime.in`, all affected runtime/development hashed profiles, and a justification in the PR body |
+| Change dependency/build/audit tooling | Matching `.in` inputs and all affected hashed outputs using their recorded commands (runbook §6.6), `tests/test_release_workflows.py` |
 | Change audit-record fields   | `docs/architecture.md` request lifecycle, `tests/test_audit.py`, runbook §2.3          |
 | Change a redaction/tier pattern | `src/relay_shell/patterns.py` (bump `PATTERNS_VERSION`), paired over-scrub/under-scrub (redaction) or positive/near-miss (policy) tests in `tests/test_patterns.py`, runbook §6.4 (policy heuristics) / §6.5 (redaction rules) |
 
@@ -170,7 +170,7 @@ These recur in the runbook §3.4 "common review failures" list.
 - `ruff check . && ruff format --check .` must pass. The line length
   is 100, target version is `py312`.
 - `mypy` is strict for the package and relaxed only for
-  `relay_shell.server` (FastMCP) and `asyncssh` (no stubs). Prefer
+  `relay_shell.server` (MCPServer) and `asyncssh` (no stubs). Prefer
   narrowing an override in `pyproject.toml` over `# type: ignore` in
   the file.
 - No new runtime dependency without a justification in the PR body.

{relay_shell-0.5.2 → relay_shell-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: relay-shell
-Version: 0.5.2
+Version: 0.5.3
 Summary: A highly reliable, maximally capable MCP server for complete shell and SSH mastery: a governed relay in the shell/SSH path.
 Project-URL: Homepage, https://github.com/rmednitzer/relay-shell
 Project-URL: Documentation, https://rmednitzer.github.io/relay-shell/
@@ -36,7 +36,7 @@ Requires-Dist: pre-commit<5,>=4.0; extra == 'dev'
 Requires-Dist: pyjwt<3,>=2.15.0; extra == 'dev'
 Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
 Requires-Dist: pytest<10,>=8.3; extra == 'dev'
-Requires-Dist: ruff==0.17.2; extra == 'dev'
+Requires-Dist: ruff==0.17.3; extra == 'dev'
 Provides-Extra: http
 Description-Content-Type: text/markdown
 
@@ -53,14 +53,20 @@ It is operator infrastructure for hosts you own and administer. It runs with the
 its service account, with no sandbox, and it is **open by default**: no command is refused for
 what it does. What it adds is a record and a warning:
 
-- **Every call is audited:** one JSON line with the redacted arguments, the output's hash and
+- **Per-call audit:** one JSON line with the redacted arguments, the output's hash and
   length (never its body), the exit code, the client and the assessed tier.
-- **Every risky call says so:** a call classified Tier 2 (changes state) or Tier 3
+- **Risk notices:** a call classified Tier 2 (changes state) or Tier 3
   (irreversible), or an SSH call with host-key checking off, ends with a `[NOTICE ...]` line.
   `server_info` lists the standing unsafe settings.
 - **Refusal is opt-in:** `guarded` and `readonly` modes, a deny list and a Tier-3 confirmation
   step are available and all off by default.
 
+Audit records describe completed, denied and cancelled calls; a process crash can
+leave an execution without a completion record. Opt-in `RELAY_SHELL_AUDIT_INTENT=true`
+adds a pre-execution record. Runtime sink failures mark audit health degraded while
+calls continue; monitor that health and ship evidence off-host. See the
+[audit lifecycle](docs/architecture.md#request-lifecycle).
+
 ## Tools
 
 | Local shell | Purpose |
@@ -109,8 +115,11 @@ is CPython 3.12; other interpreter/OS combinations are not qualified.
 
 ```bash
 git clone https://github.com/rmednitzer/relay-shell.git && cd relay-shell
-python3 -m venv .venv && . .venv/bin/activate
-pip install -e ".[dev]"
+python3.12 -m venv .venv
+. .venv/bin/activate
+python -m pip install --only-binary=:all: --require-hashes -r requirements/development-py3.12.txt
+python -m pip install --no-deps --no-build-isolation -e ".[dev]"
+python -m pip check
 
 relay-shell                              # stdio transport
 RELAY_SHELL_TRANSPORT=http relay-shell   # streamable-http on 127.0.0.1:8080
@@ -118,6 +127,11 @@ relay-shell --check-config               # validate config, print unsafe-setting
 relay-shell --verify-deploy              # compare installed templates with the shipped ones
 ```
 
+The example uses Ubuntu 24.04 / CPython 3.12. On Ubuntu 26.04, use
+`python3.14` and `requirements/development-py3.14.txt` instead. For a service
+installation using the runtime-only lock and an isolated builder, follow the
+[deployment guide](docs/deployment.md#2-install).
+
 Register with an MCP client (stdio):
 
 ```json
@@ -145,19 +159,24 @@ first. Classification is a heuristic, not a boundary]
 The classifier is a regex heuristic over the command text, not a parse of the shell language.
 A call without a notice is not thereby safe, and a notice does not block anything.
 
-Only resource bounds and one startup check refuse a call, none of them based on what the
-command does:
+Open mode controls command admission; it does not bypass argument validation,
+SSH host verification, transport authentication or resource limits. With the
+default policy, a command is not refused because of its meaning. Important bounds
+and startup checks include:
 
 | Bound | Setting (default) | Behaviour |
 |-------|-------------------|-----------|
-| Input size (command, stdin, script, env) | `RELAY_SHELL_MAX_INPUT` (2 MiB) | refused, because the policy scan is synchronous |
-| Wall-clock per call | `RELAY_SHELL_MAX_TIMEOUT` (900 s) | killed; use `shell_spawn` / `ssh_spawn` for longer work |
+| Input size (command, stdin, script, env) | `RELAY_SHELL_MAX_INPUT` (2,097,152 characters) | refused, because the policy scan is synchronous |
+| One-shot command timeout | `RELAY_SHELL_MAX_TIMEOUT` (900 s) | local process group terminated; remote termination is best effort; use `shell_spawn` / `ssh_spawn` for longer work |
 | Live sessions / forwards | `RELAY_SHELL_MAX_SESSIONS` (64), `RELAY_SHELL_MAX_FORWARDS` (64) | a new one is refused at the cap |
 | Output returned | `RELAY_SHELL_MAX_OUTPUT` (64 KiB) | truncated, not refused |
 | HTTP without OAuth on a non-loopback address | `RELAY_SHELL_ALLOW_UNAUTH_NETWORK` | refused at startup unless set |
 
 Session output buffers are also bounded, and idle sessions (`RELAY_SHELL_SESSION_IDLE_TIMEOUT`,
-1800 s) and exited, drained sessions are reaped.
+1800 s) and exited, drained sessions are reaped. Persistent sessions have no
+maximum lifetime. SFTP transfers default to `timeout=0` (no per-call deadline);
+set a positive transfer timeout when needed. After a remote timeout or disconnect,
+reconcile the remote operation before retrying a mutation.
 
 ### Making it stricter
 

{relay_shell-0.5.2 → relay_shell-0.5.3}/README.md

@@ -11,14 +11,20 @@ It is operator infrastructure for hosts you own and administer. It runs with the
 its service account, with no sandbox, and it is **open by default**: no command is refused for
 what it does. What it adds is a record and a warning:
 
-- **Every call is audited:** one JSON line with the redacted arguments, the output's hash and
+- **Per-call audit:** one JSON line with the redacted arguments, the output's hash and
   length (never its body), the exit code, the client and the assessed tier.
-- **Every risky call says so:** a call classified Tier 2 (changes state) or Tier 3
+- **Risk notices:** a call classified Tier 2 (changes state) or Tier 3
   (irreversible), or an SSH call with host-key checking off, ends with a `[NOTICE ...]` line.
   `server_info` lists the standing unsafe settings.
 - **Refusal is opt-in:** `guarded` and `readonly` modes, a deny list and a Tier-3 confirmation
   step are available and all off by default.
 
+Audit records describe completed, denied and cancelled calls; a process crash can
+leave an execution without a completion record. Opt-in `RELAY_SHELL_AUDIT_INTENT=true`
+adds a pre-execution record. Runtime sink failures mark audit health degraded while
+calls continue; monitor that health and ship evidence off-host. See the
+[audit lifecycle](docs/architecture.md#request-lifecycle).
+
 ## Tools
 
 | Local shell | Purpose |
@@ -67,8 +73,11 @@ is CPython 3.12; other interpreter/OS combinations are not qualified.
 
 ```bash
 git clone https://github.com/rmednitzer/relay-shell.git && cd relay-shell
-python3 -m venv .venv && . .venv/bin/activate
-pip install -e ".[dev]"
+python3.12 -m venv .venv
+. .venv/bin/activate
+python -m pip install --only-binary=:all: --require-hashes -r requirements/development-py3.12.txt
+python -m pip install --no-deps --no-build-isolation -e ".[dev]"
+python -m pip check
 
 relay-shell                              # stdio transport
 RELAY_SHELL_TRANSPORT=http relay-shell   # streamable-http on 127.0.0.1:8080
@@ -76,6 +85,11 @@ relay-shell --check-config               # validate config, print unsafe-setting
 relay-shell --verify-deploy              # compare installed templates with the shipped ones
 ```
 
+The example uses Ubuntu 24.04 / CPython 3.12. On Ubuntu 26.04, use
+`python3.14` and `requirements/development-py3.14.txt` instead. For a service
+installation using the runtime-only lock and an isolated builder, follow the
+[deployment guide](docs/deployment.md#2-install).
+
 Register with an MCP client (stdio):
 
 ```json
@@ -103,19 +117,24 @@ first. Classification is a heuristic, not a boundary]
 The classifier is a regex heuristic over the command text, not a parse of the shell language.
 A call without a notice is not thereby safe, and a notice does not block anything.
 
-Only resource bounds and one startup check refuse a call, none of them based on what the
-command does:
+Open mode controls command admission; it does not bypass argument validation,
+SSH host verification, transport authentication or resource limits. With the
+default policy, a command is not refused because of its meaning. Important bounds
+and startup checks include:
 
 | Bound | Setting (default) | Behaviour |
 |-------|-------------------|-----------|
-| Input size (command, stdin, script, env) | `RELAY_SHELL_MAX_INPUT` (2 MiB) | refused, because the policy scan is synchronous |
-| Wall-clock per call | `RELAY_SHELL_MAX_TIMEOUT` (900 s) | killed; use `shell_spawn` / `ssh_spawn` for longer work |
+| Input size (command, stdin, script, env) | `RELAY_SHELL_MAX_INPUT` (2,097,152 characters) | refused, because the policy scan is synchronous |
+| One-shot command timeout | `RELAY_SHELL_MAX_TIMEOUT` (900 s) | local process group terminated; remote termination is best effort; use `shell_spawn` / `ssh_spawn` for longer work |
 | Live sessions / forwards | `RELAY_SHELL_MAX_SESSIONS` (64), `RELAY_SHELL_MAX_FORWARDS` (64) | a new one is refused at the cap |
 | Output returned | `RELAY_SHELL_MAX_OUTPUT` (64 KiB) | truncated, not refused |
 | HTTP without OAuth on a non-loopback address | `RELAY_SHELL_ALLOW_UNAUTH_NETWORK` | refused at startup unless set |
 
 Session output buffers are also bounded, and idle sessions (`RELAY_SHELL_SESSION_IDLE_TIMEOUT`,
-1800 s) and exited, drained sessions are reaped.
+1800 s) and exited, drained sessions are reaped. Persistent sessions have no
+maximum lifetime. SFTP transfers default to `timeout=0` (no per-call deadline);
+set a positive transfer timeout when needed. After a remote timeout or disconnect,
+reconcile the remote operation before retrying a mutation.
 
 ### Making it stricter
 

relay_shell-0.5.3/audit/2026-11-07-documentation-review.md

@@ -0,0 +1,74 @@
+# Documentation and Pages review — 2026-11-07
+
+## Scope and baseline
+
+Public repository baseline: `e7f4256b63477fd2da6bcad8d2437d07cc2c17f5`
+(main), latest release v0.5.2. The inventory contained 54 tracked Markdown
+documents, including contributor/templates, eight site guides, 15 ADR/index
+files, deployment/dependency/fixture READMEs and frozen audit packs.
+[PR #281](https://github.com/rmednitzer/relay-shell/pull/281) carries the corrections.
+
+Antigravity was invoked through Vertex for a read-only repository and published
+Pages review. Its completed report supplied a coverage manifest and actionable
+findings. Independent review compared proposed corrections with actual source,
+workflow steps, lock headers and external repository settings. The provider's
+counts, line references and historical descriptions are not authoritative.
+In particular, its claimed missing latest SDK/SSH pin entry in ADR 0001 was
+rejected: the current Consequences section already contains that entry.
+
+## Verified findings and disposition
+
+| Area | Correction |
+| --- | --- |
+| Quickstart and agent setup | Use the qualified hashed development profile, then no-dependency editable installation. |
+| Deployment | Replace the superseded manual install with the locked installer's stopped-service procedure and link bounded failure/interruption recovery. |
+| Edge installer | Exported EDGE variables take precedence over the operator file, including explicit empty values; document sudo environment selection. |
+| Audit and resource limits | State crash/degraded-sink limits, audit-before-notice order, character input limits, SFTP/session/remote-timeout exceptions and resource/prompt truncation. |
+| OAuth | Reauthorization also follows grant revocation, reuse detection, resource changes or applicable recovery/migration. |
+| Release/SBOM runbook | Current tags use complete profiles, independent workflow tooling locks and separate runtime/builder/tool environments; preserve historical fallback limits. |
+| Contributor checklists | Include scope inputs and all affected profile/tooling lock regeneration commands. |
+| Release trust | Append dated v0.5.0–v0.5.2 signature, tag-object and main-ancestry evidence; recheck external controls. |
+| Current terminology | Correct MCPServer references, the CLI flag comment, optional HTTP-extra comment and broker operation-key docstring. Executable behavior is unchanged. |
+| Historical runner record | Append a dated current-runner clarification to BACKLOG; preserve the initial qualification and historical ADRs/audit packs. |
+| Vector example | Replace retired repository instructions; declare the metrics source, remove zero-age filtering, use valid compression/routing/buffer settings and handle non-object JSON. Document receiver protocol and rotation/backfill limits. |
+| Pages assets | Use system fonts, removing Google font requests. |
+
+## Validation evidence
+
+- Baseline live crawl: all 23 sitemap URLs returned HTTP 200.
+- All 22 registered tools are represented in README and the tool reference.
+- Strict MkDocs builds and documentation-environment `pip check` passed.
+- Relative file-link checks covered the 54 baseline Markdown documents; generated
+  file/anchor checks covered all 24 HTML files, including the 404 page.
+- Generated pages contain no Google Fonts requests.
+- Vector 0.61.0's original example failed configuration loading on boolean
+  compression. The corrected example passed `vector validate --no-environment`.
+  Synthetic VRL cases passed for an object, malformed JSON, a scalar and an array;
+  original message/file fields were retained and invalid records gained parse errors.
+  The official Linux release archive was checked against the GitHub-reported SHA-256
+  `84a27c3ad6b772fdb05bb76ea01a31498bfc8f5e71f32cc78a0d96841f1aa827`
+  and its validator ran in a disposable task directory under an unprivileged identity.
+- `pyproject.toml` and pre-commit parsed configuration remain identical to baseline.
+  The broker's executable AST remains identical after removing the module docstring.
+- SSH signatures and main ancestry were checked for all seven release tags.
+  Ruleset and immutable-release observations are recorded in
+  [release trust](../docs/release-trust.md#verification-update-2026-11-07).
+  The GitHub `pypi` environment had a required-reviewer rule on this date;
+  PyPI account-side trusted-publisher configuration was not independently inspected.
+
+The final revision's required CI and Pages deployment receipts belong to PR #281
+and its linked main workflow runs. A submitted job or a green documentation build
+alone does not establish deployment; published content must be checked afterwards.
+
+## Limits and rollback
+
+No daemon, edge, collector or operational host was deployed. No release tag or
+package was published. Vector configuration/VRL validation does not establish
+delivery, ACL access, TLS identity, outage backfill or collector recovery.
+Fluent Bit and journal recipes were not exercised against live receivers.
+Historical evidence remains dated evidence; this review does not renew old
+live-host, release-artifact or recovery claims.
+
+STPA: no new runtime control action or authority; the changes reconcile existing
+implementation and document limits. Roll back by reverting the documentation,
+comments and site configuration from PR #281, then verify the main Pages redeploy.

{relay_shell-0.5.2 → relay_shell-0.5.3}/docs/architecture.md

@@ -64,10 +64,6 @@ Every tool body is identical in shape (`Relay.run`):
    (`deployment.md` §6a).
 4. **Bound** - the body is truncated to the effective output budget (byte
    safe). An `[exit N]` prefix is added when an exit code is meaningful.
-4a. **Notice** - after the audit record is written, an admitted Tier 2/3 call (or one with
-   `known_hosts=ignore`) gets one or two trailing `[NOTICE ...]` lines appended to the returned
-   string; nothing is added to the record ([ADR 0013](adr/0013-open-by-default-with-unsafe-notices.md),
-   `RELAY_SHELL_UNSAFE_NOTICES`).
 5. **Audit** - one JSON line: timestamp, tool, tier, denied flag, redacted and
    length-bounded args, SHA-256 of the final output, output byte length, exit
    code, plus `request_id`, `client_id` and an `action` marker (`intent`, `confirm_plan`,
@@ -75,6 +71,12 @@ Every tool body is identical in shape (`Relay.run`):
    `RELAY_SHELL_AUDIT_CHAIN=true` the line additionally carries `seq`/`prev`/`chain`
    for tamper-evidence ([ADR 0007](adr/0007-audit-hash-chain.md)); default off
    keeps the record byte-identical.
+6. **Notice** - after auditing, an admitted Tier 2/3 call (or one with
+   `known_hosts=ignore`) gets `[NOTICE ...]` information in its response; nothing
+   is added to the audit record ([ADR 0013](adr/0013-open-by-default-with-unsafe-notices.md),
+   `RELAY_SHELL_UNSAFE_NOTICES`). `ssh_fanout` keeps its response valid JSON by
+   returning notices in a top-level `notices` field when the body is a JSON
+   object; errors or truncated bodies fall back to trailing notice lines.
 
 The audit file handler validates its opened descriptor at initialization and every
 rotation reopen. It uses nonblocking open to avoid FIFO stalls, rejects nonregular
@@ -84,8 +86,10 @@ degraded while tool calls continue; existing rotation-file modes are preserved.
 Regular-file type checks alone do not prove storage durability or constrain an
 operator-controlled path.
 
-A tool may fail, time out, or be denied, but it always returns a single bounded, audited
-string; the one exception is a cancelled call, which is audited and then re-raised.
+Handled tool failures, timeouts and denials return bounded text through the runner;
+a cancelled call is audited and then re-raised. This describes the normal handler
+path, not guaranteed durable evidence after process loss or a degraded sink.
+The optional intent record can expose an execution with no completion record.
 
 When `RELAY_SHELL_SECCOMP_NOTIFY=true` (and the host supports it),
 `Relay.run` also activates a per-call seccomp-notify monitor during step 3: a
@@ -146,8 +150,11 @@ The main `Relay.run` steps above correspond to specific call sites in
 | 5 Audit | `self.audit.record(...)` from `audit.AuditLogger.record`. |
 
 Resource reads (`relay-shell://...`) and prompt fetches (`prompts/get`)
-do not flow through `Relay.run` - there is no work to admit, time out,
-or truncate. They are still audited with `tool="resource:<name>"` /
+do not flow through `Relay.run`; they do not execute shell work or use its
+command-admission path. Their serialized bodies are byte-safely truncated to
+`app.clamp_output(cfg.max_output)` before hashing and return. An oversized JSON
+resource can therefore contain a truncation marker rather than parseable JSON.
+Successful reads/fetches are still audited with `tool="resource:<name>"` /
 `tool="prompt:<name>"` and `tier=0` so the operator sees what context
 the model is pulling in ([ADR 0008](adr/0008-operating-guidance-prompt.md)
 covers the prompt surface). The `Relay.run` body, the resource handlers,
@@ -170,8 +177,12 @@ produced.
   connection evicts the least-recently-used entry not in use, and a cache whose entries are
   all in use (sessions, forwards, running calls) exceeds the cap briefly rather than drop a
   live connection. `RELAY_SHELL_MAX_FORWARDS` (default 64) caps active forwards.
-- Every tool clamps its own timeout and output to the configured limits;
-  background/blocking filesystem work is offloaded with `asyncio.to_thread`.
+- One-shot command tools clamp timeouts and output to the configured limits.
+  SFTP transfers default to `timeout=0` (no per-call deadline); positive transfer
+  timeouts are clamped. Persistent PTY lifetime is governed by explicit closure
+  and idle reaping, not the one-shot command timeout. A remote timeout is not
+  proof that remote effects stopped; reconcile before retrying mutations.
+  Background/blocking filesystem work is offloaded with `asyncio.to_thread`.
 
 ## Transports