hermes-local-hands 0.1.0__tar.gz

hermes_local_hands-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Upgrade the environment installer
+        run: >-
+          python -m pip install --disable-pip-version-check --upgrade
+          'pip>=26.2' 'setuptools>=83'
+      - name: Install project
+        run: python -m pip install --disable-pip-version-check -e '.[dev]'
+      - name: Lint
+        run: ruff check .
+      - name: Check formatting
+        run: ruff format --check .
+      - name: Audit runtime dependencies
+        run: pip-audit --local --skip-editable --progress-spinner off
+      - name: Test
+        run: pytest --cov=hermes_local_hands --cov-report=term-missing
+      - name: Build distributions
+        run: python -m build
+      - name: Validate package metadata
+        run: python -m twine check dist/*
+      - name: Install built wheel in a clean environment
+        shell: bash
+        run: |
+          clean_venv="$(mktemp -d)/wheel-smoke"
+          python -m venv "$clean_venv"
+          "$clean_venv/bin/python" -m pip install --disable-pip-version-check dist/*.whl
+          "$clean_venv/bin/hermes-local-hands" --help

hermes_local_hands-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,38 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '23 4 * * 1'
+
+permissions:
+  contents: read
+  security-events: write
+
+concurrency:
+  group: codeql-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Python
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@f205ea1c3313d32999d8d6a48b4f6530d4437b38 # v4.37.4
+        with:
+          languages: python
+          build-mode: none
+          config: |
+            paths:
+              - src/hermes_local_hands
+      - name: Analyze
+        uses: github/codeql-action/analyze@f205ea1c3313d32999d8d6a48b4f6530d4437b38 # v4.37.4

hermes_local_hands-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,89 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+concurrency:
+  group: publish-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out the released tag
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Upgrade the environment installer
+        run: >-
+          python -m pip install --disable-pip-version-check --upgrade
+          'pip>=26.2' 'setuptools>=83'
+      - name: Verify release tag and package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(
+              Path("pyproject.toml").read_text(encoding="utf-8")
+          )["project"]["version"]
+          expected = f"v{version}"
+          if os.environ["RELEASE_TAG"] != expected:
+              raise SystemExit(
+                  f"release tag must be {expected!r}, got {os.environ['RELEASE_TAG']!r}"
+              )
+          PY
+      - name: Install release checks
+        run: python -m pip install --disable-pip-version-check -e '.[dev]'
+      - name: Validate source
+        run: |
+          ruff check .
+          ruff format --check .
+          pytest
+      - name: Build distributions
+        run: python -m build
+      - name: Validate package metadata
+        run: python -m twine check dist/*
+      - name: Store distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish distributions
+    if: vars.PYPI_PUBLISH == 'true'
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hermes-local-hands
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distributions with attestations
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        with:
+          attestations: true

hermes_local_hands-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.coverage.*
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+dist/
+build/
+*.log
+.DS_Store
+.env
+.env.*
+!.env.example
+hermes-local-hands-data/
+.local-hands/

hermes_local_hands-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## Unreleased
+
+- No stable protocol, production-security claim, hosted service, or compatibility
+  guarantee is made until a release explicitly says otherwise.
+
+## 0.1.0 - 2026-09-04
+
+Initial alpha release candidate:
+
+- loopback-only MCP companion with explicit trusted reverse-proxy host settings;
+- client-scoped workspace grants and narrow status/file-read tools;
+- pending, expiring patch/check requests with local-only approval and rejection;
+- snapshot-only patch/check execution, stale-request protection, and uncertain
+  recovery after interrupted execution;
+- anonymous archives, high-entropy staging, and atomic no-replace snapshot
+  publication on supported macOS and Linux hosts;
+- exact-ID snapshot cleanup with fd-bound deletion, retained completion markers,
+  and explicit incomplete-deletion visibility;
+- signed receipt chain and local verification command;
+- source/build/test/package validation automation.
+- one real two-machine alpha validation over tailnet HTTPS, covering remote
+  status/read, a pending patch, local approval, snapshot execution, a linked
+  check, and receipt verification.
+
+This version is not a sandbox. Approved checks run trusted repository code with
+the local user's normal host and network access and can cause host-side effects.
+Its post-check source observation covers Git-visible checkout status only. It
+has not established broad Hermes/tunnel compatibility or production readiness.

hermes_local_hands-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for helping test a safer local companion for Hermes. The project is
+alpha-stage; its protocol, state format, and CLI can change before a stable
+release.
+
+## Development setup and required checks
+
+```bash
+python3.11 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+
+ruff check .
+ruff format --check .
+pip-audit --local --skip-editable --progress-spinner off
+pytest --cov=hermes_local_hands --cov-report=term-missing
+python -m build
+python -m twine check dist/*
+```
+
+Run checks against the commit you propose. Do not claim a command passed on a
+platform where you did not run it. CI also installs the built wheel into a clean
+environment; that validates packaging, not a real tunnel or two-host Hermes
+deployment.
+
+## Security-sensitive changes
+
+Any change to authentication, client/workspace grants, paths, secret handling,
+patch parsing, approvals, request TTL/recovery, receipts, command execution,
+proxy trust, or state persistence requires all of the following:
+
+1. A focused test for success and fail-closed behavior.
+2. A [THREAT_MODEL.md](THREAT_MODEL.md) update when the trust boundary changes.
+3. A review of whether output, errors, logs, or receipts could leak local paths,
+   credentials, or source.
+4. A clear statement of what remains untrusted. In particular, fixed check
+   profiles execute repository code as the local user, are not a sandbox, and
+   can cause host-side effects. Git-status observation does not detect effects
+   outside the checkout's Git-visible state.
+
+Prefer a smaller denied surface over a convenient implicit fallback. Preserve
+the invariant that the remote protocol can neither approve/deny nor write the
+active checkout, merge, push, or expose a raw shell.
+
+## Pull requests
+
+Describe the user problem, scope, security impact, validation actually run, and
+known limitations. Keep changes narrow. Do not include automatic merge/push,
+credentials, private repositories, private state databases, bearer tokens, or
+real action receipts. Report security problems privately under
+[SECURITY.md](SECURITY.md).

hermes_local_hands-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maurice Mohr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_local_hands-0.1.0/PKG-INFO

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: hermes-local-hands
+Version: 0.1.0
+Summary: A consent-gated local companion for remote Hermes agents
+Project-URL: Homepage, https://github.com/mauricemohr88-debug/hermes-local-hands
+Project-URL: Documentation, https://github.com/mauricemohr88-debug/hermes-local-hands#readme
+Project-URL: Issues, https://github.com/mauricemohr88-debug/hermes-local-hands/issues
+Project-URL: Source, https://github.com/mauricemohr88-debug/hermes-local-hands
+Author: Maurice Mohr
+License: MIT License
+        
+        Copyright (c) 2026 Maurice Mohr
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,automation,git,hermes,mcp,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: cryptography<51,>=50
+Requires-Dist: mcp<3,>=2.1
+Requires-Dist: uvicorn<1,>=0.35
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: httpx<1,>=0.28; extra == 'dev'
+Requires-Dist: pip-audit<3,>=2.10; extra == 'dev'
+Requires-Dist: pytest-cov<7,>=6; extra == 'dev'
+Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.12; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Hermes Local Hands
+
+[![CI](https://github.com/mauricemohr88-debug/hermes-local-hands/actions/workflows/ci.yml/badge.svg)](https://github.com/mauricemohr88-debug/hermes-local-hands/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/mauricemohr88-debug/hermes-local-hands/actions/workflows/codeql.yml/badge.svg)](https://github.com/mauricemohr88-debug/hermes-local-hands/actions/workflows/codeql.yml)
+[![PyPI](https://img.shields.io/pypi/v/hermes-local-hands.svg)](https://pypi.org/project/hermes-local-hands/)
+
+Hermes Local Hands is an **alpha** local companion for a remote
+[Hermes](https://github.com/NousResearch/hermes-agent) agent. It gives that
+agent a deliberately narrow view of one registered repository, while the
+computer that owns the repository retains the final say over every change and
+check.
+
+It solves a concrete split-machine problem: Hermes can reason on a Mac Studio,
+server, or VM, while the developer's source code remains on a different local
+machine. The remote side can inspect approved files and create requests. It
+cannot run a shell, approve or deny a request, write the active checkout,
+merge, or push.
+
+> **Security boundary in v0.1.** `workspace_status` and `read_file` are remote
+> inspection tools. `propose_patch` and `request_check` only create a pending,
+> expiring request. Approval and rejection are local-operator actions. Local
+> Hands applies patches and launches checks from an isolated snapshot rather
+> than writing the registered checkout itself. Approved check code still has
+> the local user's normal host and network access and can deliberately modify
+> the registered checkout; this is **not** a sandbox.
+
+## Why this now
+
+The architecture follows real upstream demand for safer local execution and
+split-runtime workflows, rather than adding a second Hermes runtime. Useful
+primary context is the upstream discussions [#18715](https://github.com/NousResearch/hermes-agent/issues/18715),
+[#42807](https://github.com/NousResearch/hermes-agent/issues/42807), and
+[#16462](https://github.com/NousResearch/hermes-agent/issues/16462), plus the
+related implementation work in [#63966](https://github.com/NousResearch/hermes-agent/pull/63966)
+and [#43045](https://github.com/NousResearch/hermes-agent/pull/43045).
+
+## What it does — and does not do
+
+| Capability | Remote Hermes can do it | Local operator must do it |
+| --- | --- | --- |
+| See sanitised Git status | Yes, for a granted workspace | Register the workspace and grant the client |
+| Read a text file | Yes, only inside the explicit read allowlist | Define the allowlist |
+| Propose a textual patch | Create a pending request only | Review and approve it |
+| Request a fixed check profile | Create a pending request only | Review and approve it |
+| Apply or test | No | Local Hands launches it in a snapshot; approved code remains host-capable |
+| Reject, merge, push, use a shell | No | Reject is local; merge/push/shell are outside the protocol |
+
+Every request is tied to an authenticated client, an allowed workspace, the
+current Git `HEAD`, the workspace-policy hash, an idempotency key scoped to the
+client, and a short TTL. A changed policy or commit invalidates a request.
+Re-registering an existing workspace ID replaces its client grants with exactly
+the new `--client` list; old grants do not follow a changed root or policy.
+Interrupted execution is recorded as **uncertain**, not silently reported as a
+success. The local state store also writes a signed, append-only receipt chain
+for requests and operator decisions.
+
+## Install and local-only quickstart
+
+Requirements: Python 3.11+ and Git. Install the isolated command with
+[uv](https://docs.astral.sh/uv/) or pipx:
+
+```bash
+uv tool install hermes-local-hands
+# Alternative: pipx install hermes-local-hands
+```
+
+For development from a source checkout instead:
+
+```bash
+# Use a Python 3.11+ executable; macOS /usr/bin/python3 may still be too old.
+python3.11 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+```
+
+The example below uses `demo` and only exposes `src` and `tests`; replace the
+absolute path and allowlist with your own deliberate choices.
+
+```bash
+
+# Creates private local state and a bearer credential file (mode 0600).
+hermes-local-hands init --client-id hermes-mac-studio
+
+# Register one Git repository and fixed, named check profiles.
+hermes-local-hands workspace add \
+  --id demo \
+  --root /absolute/path/to/repository \
+  --read src \
+  --read tests \
+  --write src \
+  --check syntax=/usr/bin/python3,-m,compileall,-q,src \
+  --client hermes-mac-studio
+
+# Start the listener. It refuses non-loopback bind addresses.
+hermes-local-hands serve --host 127.0.0.1 --port 8741
+```
+
+`init` stores the token under the private state directory rather than printing
+it. On macOS/Linux the default is
+`~/.local/state/hermes-local-hands/clients/<client-id>.token`; set
+`XDG_STATE_HOME` first to choose another private state location. Read the file
+locally and export it only in the Hermes runtime's private environment:
+
+```bash
+export HERMES_LOCAL_HANDS_TOKEN="$(< "$HOME/.local/state/hermes-local-hands/clients/hermes-mac-studio.token")"
+```
+
+Do not put a real token in a repository, issue, screenshot, shell history, or
+public configuration file.
+
+### End-to-end workflow
+
+1. The local operator registers a workspace, its explicit read/write allowlist,
+   fixed check profiles, and the Hermes client grant.
+   `workspace grants <workspace-id>` lists current grants; `workspace revoke
+   <workspace-id> <client-id>` removes one and records the decision.
+2. The local operator starts `serve` on loopback only.
+3. A trusted reverse proxy/tunnel terminates HTTPS and forwards to that local
+   listener. Local Hands still accepts only the exact proxy host(s) named at
+   startup; it does not infer trust from arbitrary forwarded headers.
+4. Hermes calls `workspace_status` or `read_file`, or creates a pending patch
+   or check request.
+   Patch and check requests require a clean registered checkout both when they
+   are created and when they are approved; uncommitted changes are never copied
+   into the managed snapshot.
+5. The local operator inspects the request and chooses one of these local-only
+   commands:
+
+   ```bash
+   hermes-local-hands request list --state pending
+   # Default output is a multiline, control-escaped local review.
+   hermes-local-hands request show <request-id>
+   # Copy the approval_code shown above; it is intentionally request-specific.
+   hermes-local-hands request approve <request-id> --confirm <approval-code>
+   # or:
+   hermes-local-hands request deny <request-id> --reason "not approved"
+   ```
+
+   Use `request show <request-id> --json` only when escaped machine-readable
+   output is needed. The default review prefixes every untrusted patch line and
+   escapes terminal/bidirectional controls so a patch cannot visually imitate
+   the approval fields.
+
+6. An approved operation is revalidated against the recorded `HEAD` and policy,
+   then Local Hands applies or launches it from a managed snapshot. Approved
+   check code is still host-capable. Inspect the result with
+   `hermes-local-hands request status <request-id>` and verify the receipt chain
+   locally with `hermes-local-hands receipt-verify`.
+
+7. After reviewing a succeeded or failed snapshot, free its retention slot only
+   through the exact-ID local deletion gate:
+
+   ```bash
+   hermes-local-hands snapshot list
+   hermes-local-hands snapshot delete <request-id> --confirm <request-id>
+   ```
+
+   The command records deletion-requested and deletion-completed receipts. It
+   refuses pending, executing, missing, symlinked, or mismatched targets and
+   never deletes snapshots automatically. An `uncertain` snapshot can be
+   removed only after explicit local review and the same exact-ID confirmation.
+   A successful deletion empties the already-open request directory in place
+   and retains only a tiny completion marker instead of performing a final
+   path-based directory removal. Completed marker directories are omitted from
+   `snapshot list`; incomplete deletions remain visible there for local
+   investigation.
+
+For a check request linked to an approved patch, create it locally with the
+patch request ID. The check then uses that patch's approved snapshot rather
+than the mutable active checkout:
+
+```bash
+hermes-local-hands check add demo syntax check-after-patch-001 \
+  --client hermes-mac-studio \
+  --patch-request <approved-patch-request-id>
+```
+
+That approval creates a **fresh** snapshot at the recorded base commit and
+replays the exact stored patch bytes whose digest was reviewed; it does not
+reuse a mutable previous snapshot. A check result is evidence about that
+snapshot only; it is not a merge, deployment, or production safety claim.
+
+## Hermes MCP configuration
+
+Generate the configuration fragment rather than hand-copying names:
+
+```bash
+# Local same-machine use:
+hermes-local-hands hermes-config --port 8741
+
+# Remote use: pass the exact, already configured HTTPS tunnel endpoint.
+hermes-local-hands hermes-config \
+  --endpoint https://mac-studio.example.ts.net/mcp \
+  --token-env HERMES_LOCAL_HANDS_TOKEN
+```
+
+The generated YAML includes only these five tools:
+
+- `workspace_status`
+- `read_file`
+- `propose_patch`
+- `request_check`
+- `request_status`
+
+The two inspection tools advertise the MCP `readOnlyHint`. Hermes versions and
+clients may still apply their own approval or policy gate to those tools; the
+hint is useful metadata, not a compatibility guarantee or a bypass.
+
+Hermes releases affected by upstream issue
+[#88858](https://github.com/NousResearch/hermes-agent/issues/88858) may still
+prompt for every read-only call while `trust: untrusted` is configured. That is
+a fail-closed Hermes client behaviour, not additional Local Hands authority.
+The upstream fix is tracked in
+[#88372](https://github.com/NousResearch/hermes-agent/pull/88372). Keep the
+generated `untrusted` setting unless you have reviewed the implications of
+changing the client-side trust policy.
+
+For a reverse proxy, bind Local Hands only to loopback and name every permitted
+external Host exactly:
+
+```bash
+hermes-local-hands serve --host 127.0.0.1 --port 8741 \
+  --proxy-host mac-studio.example.ts.net
+```
+
+The endpoint generator accepts loopback `http://.../mcp` or an explicit
+non-loopback `https://.../mcp` URL. It rejects embedded credentials, query
+strings, and unsafe schemes. Configure the tunnel's own identity,
+authentication, and HTTPS separately; do not expose port 8741 directly to the
+public Internet.
+
+## Safety properties and limits
+
+- **Explicit scope:** a client must have a workspace grant; path reads and
+  patches must stay inside the workspace allowlist. Secret-looking and binary
+  material is not returned as normal text.
+- **No direct mutation:** no remote endpoint approves, denies, executes a
+  shell, writes the registered checkout, merges, or pushes.
+- **Snapshot working directory:** accepted patches and checks use a snapshot
+  rooted at the recorded commit and do not include uncommitted checkout
+  changes. This constrains Local Hands' own file operations, not what approved
+  check code can access on the host.
+- **Checks are not sandboxed:** fixed profiles limit what the protocol launches,
+  but the selected program still runs as the local user. It can access that
+  user's files, network, credentials, services, and can cause host-side
+  effects. Only approve profiles and repositories you trust.
+- **Checkout observation is limited:** after a check, Local Hands compares only
+  Git-visible checkout status before and after. `same` does not prove that no
+  non-Git file, service, network, credential, or other host-side effect
+  occurred.
+- **Audit evidence:** retained request/decision events form a signed receipt
+  chain. Verification detects edits and reordering within that retained chain;
+  without an externally anchored head it cannot detect deletion of a valid
+  tail or rollback to an earlier valid database. Receipts also do not prove a
+  host was not compromised.
+- **Bounded alpha retention:** v0.1 permits at most 32 open requests per client,
+  256 open requests globally, 512 retained requests per client, and 2,048
+  retained requests globally. Managed storage also permits at most 128 snapshot
+  deletion-marker directories. It never silently deletes requests, snapshots,
+  or markers.
+  Reviewed terminal snapshots can be removed one at a time through the local
+  exact-ID command above, but there is no request-record or marker-prune command
+  yet. Reaching a retained-request or deletion-marker cap is a deliberate
+  fail-closed stop that needs a later reviewed retention/migration release, not
+  a database or filesystem deletion workaround.
+- **Failed creation markers:** snapshot construction uses a private,
+  high-entropy `.creating-*` staging directory and atomic no-replace publication.
+  If construction fails, Local Hands clears only the directory bound to its open
+  descriptor and deliberately does not perform a race-prone path deletion. An
+  empty or partially cleared staging marker can therefore remain and counts
+  conservatively toward the 32-snapshot limit. v0.1 has no CLI prune operation
+  for these internal markers; repeated build failures require a reviewed
+  recovery/migration rather than manual deletion while evidence matters.
+
+Read [THREAT_MODEL.md](THREAT_MODEL.md) and [SECURITY.md](SECURITY.md) before
+using it with sensitive repositories.
+
+## Development validation
+
+```bash
+ruff check .
+ruff format --check .
+pip-audit --local --skip-editable --progress-spinner off
+pytest --cov=hermes_local_hands --cov-report=term-missing
+python -m build
+python -m twine check dist/*
+```
+
+CI additionally installs the built wheel into a clean environment. These are
+release checks for the package, not proof of a safe production rollout.
+
+On 2026-09-07 one real two-machine alpha flow was completed using Hermes on one
+Mac, this service on another Mac, and HTTPS over a private Tailscale network.
+The run covered unauthenticated rejection, status and file reads, a pending
+patch, local approval, snapshot application, a linked check, and receipt-chain
+verification. This is evidence for that exact environment only; it is not a
+general compatibility, availability, or production-security claim.
+
+For a durable local service setup, see [docs/SERVICE.md](docs/SERVICE.md).
+
+## Project direction
+
+The security core is intended to remain free and open source. There is no paid
+plan, hosted service, customer, or revenue today. Adoption and safety come
+before any optional convenience layer. See [ROADMAP.md](ROADMAP.md) for the
+public, evidence-gated direction.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development expectations and
+[SECURITY.md](SECURITY.md) for private vulnerability reporting. Never put
+credentials, private source, or real action receipts in a public issue or pull
+request.
+
+## License
+
+Released under the [MIT License](LICENSE).
+
+Hermes Local Hands is an independent community project and is not affiliated
+with or endorsed by Nous Research.