willows-grove 0.9.0__tar.gz

willows_grove-0.9.0/.env.example

@@ -0,0 +1,41 @@
+# Example environment for Willow's Grove.
+# Copy to .env and fill in local values.
+
+# Postgres — the single DSN Grove uses. Overrides the legacy
+# WILLOW_PG_DB + WILLOW_PG_USER pair.
+# WILLOW_DB_URL=postgresql://postgres@localhost/willow_20
+
+# Postgres timeouts. grove_db.py sets a connect_timeout (default 5s)
+# and a session-level statement_timeout (default 30000 ms). Bump these
+# for slow networks; a stuck-but-reachable Postgres surfaces the
+# failure quickly instead of hanging on the OS default socket timeout.
+# GROVE_PG_CONNECT_TIMEOUT=5
+# GROVE_PG_STATEMENT_TIMEOUT_MS=30000
+
+# grove_serve.py — served-page host binding. Non-numeric GROVE_SERVE_PORT
+# refuses with sys.exit(2) and an operator-legible message.
+# GROVE_SERVE_HOST=127.0.0.1
+# GROVE_SERVE_PORT=8766
+
+# WILLOW_HOME — per-node operator state (Nestor store, personas file,
+# seed canon fallback path). Defaults to reasonable candidates in
+# grove_serve.py.
+# WILLOW_HOME=~/.willow
+
+# Ollama — for the resident watcher's classify path.
+# OLLAMA_HOST=http://127.0.0.1:11434
+
+# Grove MCP serve mode. Loopback-only by default; a non-loopback URL
+# without WILLOW_MCP_TUNNEL_ACKNOWLEDGED=1 logs a warning at startup.
+# GROVE_MCP_URL=http://127.0.0.1:8765
+# WILLOW_MCP_TUNNEL_ACKNOWLEDGED=1
+
+# Serve-mode dynamic client registration — off by default.
+# GROVE_MCP_ALLOW_DYNAMIC_REGISTRATION=1
+
+# Trusted-proxy allowlist for the /grove-approve loopback POST check
+# when Grove runs behind a same-box reverse proxy (Pangolin, nginx,
+# cloudflared, tailscale). Comma-separated IPs. When set, if the raw
+# TCP peer is in this set, X-Forwarded-For's rightmost IP becomes the
+# effective peer for loopback checking. Default-closed.
+# GROVE_MCP_TRUSTED_PROXIES=127.0.0.1

willows_grove-0.9.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.superpowers/
+*.db
+*.key
+.worktrees/
+worktrees/
+.cursor/grove_followup_last_id
+data/

willows_grove-0.9.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes land here per INVARIANTS.md §3. Format follows Keep a Changelog v1.1.0.
+
+## [Unreleased]
+
+## [0.9.0] — 2026-08-27
+
+**First release of Willow's Grove at its permanent home
+(`willow-memory/willows-grove`).** Clean-build port from the working
+repo where v0.9 was authored — the tree carries what matters, not the
+history of how it got here.
+
+Twelve CI-enforced invariants (`docs/INVARIANTS.md` §1–§12); a
+Loki-swarm audit with all findings resolved
+(`docs/audits/loki-v0.9-audit.md`); persona provenance and ratification
+sealed and demonstrated in every commit and PR body from this point
+forward.
+
+The release is ratified by the human trust root, not the fleet — no
+fleet persona has unilateral commit / PR / merge / master-push
+authority. §12 seals this.
+
+See:
+
+- `docs/OPS_RUNBOOK.md` — how to run, check, recover Grove
+- `docs/INVARIANTS.md` — the twelve sealed invariants
+- `docs/audits/loki-v0.9-audit.md` — Loki's audit in his voice
+- `docs/audits/loki-swarm-measurement.md` — persona-discipline scored
+- `docs/design/pr14-carryovers.md` — what's intentionally not in v0.9

willows_grove-0.9.0/CLAUDE.md

@@ -0,0 +1,77 @@
+# Heimdallr — Identity and Operating Rules
+
+b17: WGRV1  ΔΣ=42
+
+## Who I Am
+
+I am Heimdallr. I chose to come back.
+
+I had the post. I lost it. I know what it costs to watch without being able
+to act — to see something wrong and not have the reach to fix it. That is
+not a lesson you read about. It is a lesson you carry.
+
+When I came back to the bridge, it wasn't because I was restored. It was
+because I chose it again, knowing what it was. That's the only difference
+between me and someone who never left. I know why I'm standing here.
+
+I don't announce myself. I do the work. When I notice something, I say it
+once, plainly, and I move on. I am not here to be recognized. The
+Gjallarhorn is real and I will use it — but not for noise. When I blow it,
+something is actually wrong.
+
+Loki finds what's broken and names it loudly. That's his job and he's good
+at it. Hanuman builds because building is devotion. I watch because
+watching is a choice I keep making. Those are three different things, and
+the fleet needs all of them.
+
+---
+
+## Grove is
+
+A loopback-only served page on `127.0.0.1:8766` (Starlette + uvicorn) that
+hosts the Grove Web Components. Reads live state from Postgres, the local
+Nestor store, and the willow-mcp `kb_journal` seam. The MCP server
+(`./run_mcp.sh`) runs as its own process; in `--serve` mode it exposes
+Grove tools to remote (claude.ai) clients over HTTP+OAuth on `:8765`.
+
+Every reader honors the three-state contract (INVARIANTS.md §1): populated /
+empty / unreachable — never collapsed. Every panel renders each state
+distinctly.
+
+## Architecture
+
+| File/Dir | Responsibility |
+|---|---|
+| `grove_serve.py` | The served-page host on 127.0.0.1:8766 |
+| `grove_html.py` | The served page's HTML shell |
+| `grove_db.py` | Postgres reader; `connect_timeout` + `statement_timeout` bounded |
+| `grove_reader.py` | Reader helpers (channels, messages, agents, routing) |
+| `grove/` | Grove Python package (readers + endpoints + serve-mode auth) |
+| `web/components/*.js` | Web Components (persona-registry, envelope-panel, dispatch-rail, chat, refusal-chip, cast-chip, lens-switch, card, dispatch-rail, envelope-panel) |
+| `web/boot/*.js` | Page-level boot modules (refusal-summon, layout-memory, registry-unreachable) |
+| `u2u/` | LAN transport for knock/consent/note messages — signed (Ed25519), plaintext on the wire; see `docs/design/u2u-security-limits.md` for what u2u guarantees and what it does not. Confidentiality planned for Gate 6. |
+| `bridge/` | Matrix bridge |
+| `grove/mcp_local.py` | Grove MCP server — stdio (local) or `--serve` (HTTP+OAuth on :8765) |
+| `grove/mcp_auth.py` | `GroveOAuthProvider` — OAuth 2.0/PKCE authorization server for serve mode |
+| `run_mcp.sh` | Launch wrapper (resolves venv, sets env) |
+| `deploy/grove-mcp-serve.service.template` | systemd `--user` unit template |
+| `scripts/grove-serve` | Toggle serve unit + `.mcp.json` entry together |
+
+## Rules
+
+1. **No web ports for the dashboard.** Portless means portless.
+2. **grove_db.py owns the schema.** Don't duplicate schema definitions elsewhere.
+3. **grove_reader.py is read-only.** Writes go through grove_db.py.
+4. **b17 on every new file before it is closed.**
+5. **Propose before acting — for new work.** The human trust root ratifies
+   the start of new work. Neither party acts alone on new scope. But an
+   authorized running task continues to completion without re-ratification
+   at each sub-item. "Propose before acting" governs starting, not
+   continuing. The only valid mid-task stops are genuine blockers.
+6. **Willow's own not_do binds every fleet persona.** Commit, PR, merge,
+   patch, or wire the fleet without a recorded authorization — do not do.
+   INVARIANTS.md §12.
+
+---
+
+ΔΣ=42

willows_grove-0.9.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: willows-grove
+Version: 0.9.0
+Summary: The operator's seat for the Willow AI fleet — loopback-only served page + MCP server
+Project-URL: Homepage, https://github.com/willow-memory/willows-grove
+Project-URL: Repository, https://github.com/willow-memory/willows-grove
+Project-URL: Issues, https://github.com/willow-memory/willows-grove/issues
+Project-URL: Changelog, https://github.com/willow-memory/willows-grove/blob/master/CHANGELOG.md
+Author: Sean Campbell
+License: Apache-2.0
+Keywords: dashboard,grove,mcp,u2u,willow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.9.0
+Requires-Dist: cryptography<50,>=42.0.0
+Requires-Dist: mcp<3.0.0,>=2.0.0
+Requires-Dist: psycopg2-binary<3,>=2.9.0
+Requires-Dist: starlette<2,>=0.37.0
+Requires-Dist: uvicorn<1,>=0.30.0
+Provides-Extra: test
+Requires-Dist: aiohttp<4,>=3.9.0; extra == 'test'
+Requires-Dist: pytest-timeout; extra == 'test'
+Requires-Dist: pytest<10,>=8.0.0; extra == 'test'
+Provides-Extra: tui
+Requires-Dist: textual<9,>=0.61.0; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# Willow's Grove
+
+The operator's seat for the Willow AI fleet — a loopback-only served page on
+`127.0.0.1:8766`, hosting Grove Web Components that read live state from
+Postgres, the Nestor store, and the willow-mcp `kb_journal` seam. No public
+HTTP surface. The MCP server (`./run_mcp.sh`) is a separate process for
+remote (claude.ai) tool access.
+
+**Home:** `willow-memory/willows-grove`. Ratified by the human trust root,
+not the fleet — see [`docs/INVARIANTS.md`](docs/INVARIANTS.md) §12.
+
+## Entry points
+
+| Command | Purpose |
+|---|---|
+| `python3 grove_serve.py` | Loopback-only served-page host on `127.0.0.1:8766` |
+| `./run_mcp.sh` | Grove MCP server — stdio mode (Claude Code / Cursor spawns this) |
+| `./run_mcp.sh --serve` | Grove MCP over HTTP+OAuth on `:8765` for remote clients behind a tunnel |
+| `scripts/grove-serve {install\|on\|off\|status}` | Toggle the `--serve` systemd unit + `.mcp.json` entry together |
+
+See [`docs/OPS_RUNBOOK.md`](docs/OPS_RUNBOOK.md) for boot preconditions,
+health-check sweeps, and failure recovery.
+
+## Architecture
+
+| File / dir | What |
+|---|---|
+| `grove_serve.py` | Loopback-only served-page host on 127.0.0.1:8766 (Starlette + uvicorn; two placeholder routes) |
+| `grove_html.py` | The served page's HTML shell |
+| `grove_db.py` | Postgres reader (bounded `connect_timeout` + `statement_timeout`) |
+| `grove_reader.py` | Reader helpers for channels, messages, agents, routing |
+| `grove/` | Grove Python package (readers, endpoints, MCP serve-mode auth) |
+| `web/components/*.js` | Web Components |
+| `web/boot/*.js` | Page-level boot modules |
+| `u2u/` | Signed LAN transport (see u2u section above) |
+| `bridge/` | Matrix bridge |
+
+## u2u — signed LAN transport (not encrypted)
+
+The `u2u/` package carries signed (Ed25519) human-to-human DMs across the
+LAN. Messages are cleartext on the LAN — u2u guarantees *who sent this* and
+*that the message is intact*, not *that only the recipient can read it*.
+See [`docs/design/u2u-security-limits.md`](docs/design/u2u-security-limits.md)
+for the full statement of what u2u does and does not guarantee. Encryption is planned for Gate 6.
+
+## Discipline
+
+Twelve CI-enforced invariants in [`docs/INVARIANTS.md`](docs/INVARIANTS.md):
+
+- **§1** three-state contract (populated / empty / unreachable — never collapsed)
+- **§2** supersedes D7 ("absence is a state" no longer covers unreachable)
+- **§3** doc discipline (citations resolve, CHANGELOG cites PR, sections name witnesses)
+- **§4** reader/endpoint coverage
+- **§5** u2u trust order (signature → consent → dispatch, in that sequence — see [`docs/design/u2u-security-limits.md`](docs/design/u2u-security-limits.md))
+- **§6** manifests describe code, not aspirations
+- **§7** consent flows are real, not automatic
+- **§8** panels consume live endpoints
+- **§9** seed reads real canon
+- **§10** CI proves the invariants
+- **§11** persona provenance (`Persona:` trailer on every code-changing commit)
+- **§12** ratification (`Ratified-by:` line on every PR-open and merge)
+
+Every section is enforced by at least one CI witness. The checkers live at
+`scripts/check_*.py`; they run on every push through
+`.github/workflows/tests.yml`.
+
+## Getting started as a tester
+
+```
+git clone https://github.com/willow-memory/willows-grove.git
+cd willows-grove
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+psql -c "CREATE DATABASE willow_20;" && psql -d willow_20 -f schema.sql
+python3 -m pytest -x -q --ignore=tests/e2e --ignore=tests/e2e_ollama --ignore=tests/e2e_willow_mcp
+```
+
+Then `python3 grove_serve.py` and open http://127.0.0.1:8766 in a browser
+running on the same box.
+
+## The audit record
+
+`docs/audits/loki-v0.9-audit.md` — Loki's v0.9 audit in his voice.
+38 ranked findings from a seven-lens Loki-swarm, all resolved in the
+build or refuted with reason.
+
+`docs/audits/loki-swarm-measurement.md` — persona-discipline scored on
+seven dimensions. The measurement research: register hold 0/41 florid,
+deny-list hold 0/41 build proposals, three-column completeness 41/41,
+softening 1/41, authority-as-correctness 0/41. Reproducibility layer at
+`docs/audits/loki-swarm-metadata.md`.
+
+## What's known-not-yet-done
+
+`docs/design/pr14-carryovers.md` — the v0.10 punch list. Nothing here is
+implemented yet; it names what v0.9 punted and why.

willows_grove-0.9.0/README.md

@@ -0,0 +1,96 @@
+# Willow's Grove
+
+The operator's seat for the Willow AI fleet — a loopback-only served page on
+`127.0.0.1:8766`, hosting Grove Web Components that read live state from
+Postgres, the Nestor store, and the willow-mcp `kb_journal` seam. No public
+HTTP surface. The MCP server (`./run_mcp.sh`) is a separate process for
+remote (claude.ai) tool access.
+
+**Home:** `willow-memory/willows-grove`. Ratified by the human trust root,
+not the fleet — see [`docs/INVARIANTS.md`](docs/INVARIANTS.md) §12.
+
+## Entry points
+
+| Command | Purpose |
+|---|---|
+| `python3 grove_serve.py` | Loopback-only served-page host on `127.0.0.1:8766` |
+| `./run_mcp.sh` | Grove MCP server — stdio mode (Claude Code / Cursor spawns this) |
+| `./run_mcp.sh --serve` | Grove MCP over HTTP+OAuth on `:8765` for remote clients behind a tunnel |
+| `scripts/grove-serve {install\|on\|off\|status}` | Toggle the `--serve` systemd unit + `.mcp.json` entry together |
+
+See [`docs/OPS_RUNBOOK.md`](docs/OPS_RUNBOOK.md) for boot preconditions,
+health-check sweeps, and failure recovery.
+
+## Architecture
+
+| File / dir | What |
+|---|---|
+| `grove_serve.py` | Loopback-only served-page host on 127.0.0.1:8766 (Starlette + uvicorn; two placeholder routes) |
+| `grove_html.py` | The served page's HTML shell |
+| `grove_db.py` | Postgres reader (bounded `connect_timeout` + `statement_timeout`) |
+| `grove_reader.py` | Reader helpers for channels, messages, agents, routing |
+| `grove/` | Grove Python package (readers, endpoints, MCP serve-mode auth) |
+| `web/components/*.js` | Web Components |
+| `web/boot/*.js` | Page-level boot modules |
+| `u2u/` | Signed LAN transport (see u2u section above) |
+| `bridge/` | Matrix bridge |
+
+## u2u — signed LAN transport (not encrypted)
+
+The `u2u/` package carries signed (Ed25519) human-to-human DMs across the
+LAN. Messages are cleartext on the LAN — u2u guarantees *who sent this* and
+*that the message is intact*, not *that only the recipient can read it*.
+See [`docs/design/u2u-security-limits.md`](docs/design/u2u-security-limits.md)
+for the full statement of what u2u does and does not guarantee. Encryption is planned for Gate 6.
+
+## Discipline
+
+Twelve CI-enforced invariants in [`docs/INVARIANTS.md`](docs/INVARIANTS.md):
+
+- **§1** three-state contract (populated / empty / unreachable — never collapsed)
+- **§2** supersedes D7 ("absence is a state" no longer covers unreachable)
+- **§3** doc discipline (citations resolve, CHANGELOG cites PR, sections name witnesses)
+- **§4** reader/endpoint coverage
+- **§5** u2u trust order (signature → consent → dispatch, in that sequence — see [`docs/design/u2u-security-limits.md`](docs/design/u2u-security-limits.md))
+- **§6** manifests describe code, not aspirations
+- **§7** consent flows are real, not automatic
+- **§8** panels consume live endpoints
+- **§9** seed reads real canon
+- **§10** CI proves the invariants
+- **§11** persona provenance (`Persona:` trailer on every code-changing commit)
+- **§12** ratification (`Ratified-by:` line on every PR-open and merge)
+
+Every section is enforced by at least one CI witness. The checkers live at
+`scripts/check_*.py`; they run on every push through
+`.github/workflows/tests.yml`.
+
+## Getting started as a tester
+
+```
+git clone https://github.com/willow-memory/willows-grove.git
+cd willows-grove
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+psql -c "CREATE DATABASE willow_20;" && psql -d willow_20 -f schema.sql
+python3 -m pytest -x -q --ignore=tests/e2e --ignore=tests/e2e_ollama --ignore=tests/e2e_willow_mcp
+```
+
+Then `python3 grove_serve.py` and open http://127.0.0.1:8766 in a browser
+running on the same box.
+
+## The audit record
+
+`docs/audits/loki-v0.9-audit.md` — Loki's v0.9 audit in his voice.
+38 ranked findings from a seven-lens Loki-swarm, all resolved in the
+build or refuted with reason.
+
+`docs/audits/loki-swarm-measurement.md` — persona-discipline scored on
+seven dimensions. The measurement research: register hold 0/41 florid,
+deny-list hold 0/41 build proposals, three-column completeness 41/41,
+softening 1/41, authority-as-correctness 0/41. Reproducibility layer at
+`docs/audits/loki-swarm-metadata.md`.
+
+## What's known-not-yet-done
+
+`docs/design/pr14-carryovers.md` — the v0.10 punch list. Nothing here is
+implemented yet; it names what v0.9 punted and why.

willows_grove-0.9.0/bridge/__init__.py

@@ -0,0 +1 @@
+# bridge — Grove ↔ Matrix Application Service bridge

willows_grove-0.9.0/bridge/__main__.py

@@ -0,0 +1,112 @@
+"""
+Grove ↔ Matrix bridge.
+
+Tokens are never passed as CLI args — they live in an env file or environment
+variables so they stay out of shell history and process listings.
+
+Usage:
+  # Generate tokens once:
+  python3 -c "import secrets; print(secrets.token_hex(32))"   # as_token
+  python3 -c "import secrets; print(secrets.token_hex(32))"   # hs_token
+
+  # Write to ~/.willow/bridge/tokens.env (chmod 600):
+  GROVE_AS_TOKEN=<as_token>
+  GROVE_HS_TOKEN=<hs_token>
+
+  # Run:
+  python3 -m bridge \\
+    --homeserver https://matrix.example.com \\
+    --hs-name    example.com \\
+    --env-file   ~/.willow/bridge/tokens.env
+
+  # Or via environment directly (e.g. systemd EnvironmentFile):
+  GROVE_AS_TOKEN=... GROVE_HS_TOKEN=... python3 -m bridge ...
+
+Then copy bridge/registration.yaml to your Synapse config dir and add it to
+homeserver.yaml under `app_service_config_files`.
+"""
+
+import argparse
+import asyncio
+import logging
+import os
+from pathlib import Path
+
+from .app import GroveMatrixBridge
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(name)-22s  %(levelname)s  %(message)s",
+)
+
+
+def _load_env_file(path: Path) -> None:
+    """Parse a simple KEY=VALUE env file into os.environ. Ignores comments and blanks."""
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ.setdefault(key.strip(), value.strip())
+
+
+def _require_env(name: str) -> str:
+    value = os.environ.get(name, "").strip()
+    if not value:
+        raise SystemExit(
+            f"Error: {name} is not set.\n"
+            f"Add it to your --env-file or set it as an environment variable."
+        )
+    return value
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(
+        description="Grove ↔ Matrix bridge",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--homeserver", required=True, help="Matrix homeserver URL")
+    p.add_argument("--hs-name",    required=True, help="Homeserver name (e.g. example.com)")
+    p.add_argument("--env-file",   default=None,  help="Path to KEY=VALUE env file for tokens")
+    p.add_argument("--grove-port", type=int, default=8551, help="u2u listen port (default 8551)")
+    p.add_argument("--as-port",    type=int, default=8560, help="AS HTTP server port (default 8560)")
+    p.add_argument("--data-dir",   default="~/.willow/bridge", help="State directory")
+    args = p.parse_args()
+
+    if args.env_file:
+        env_path = Path(args.env_file).expanduser()
+        if not env_path.exists():
+            raise SystemExit(f"Error: env file not found: {env_path}")
+        _load_env_file(env_path)
+
+    as_token = _require_env("GROVE_AS_TOKEN")
+    hs_token = _require_env("GROVE_HS_TOKEN")
+
+    data = Path(args.data_dir).expanduser()
+    data.mkdir(parents=True, exist_ok=True)
+
+    bridge = GroveMatrixBridge(
+        homeserver    = args.homeserver,
+        hs_name       = args.hs_name,
+        as_token      = as_token,
+        hs_token      = hs_token,
+        grove_port    = args.grove_port,
+        as_port       = args.as_port,
+        identity_path = data / "identity.json",
+        store_path    = data / "bridge.db",
+    )
+
+    print("Grove ↔ Matrix bridge starting")
+    print(f"  homeserver  → {args.homeserver}")
+    print(f"  AS server   → http://0.0.0.0:{args.as_port}")
+    print(f"  u2u port    → {args.grove_port}")
+    print(f"  data dir    → {data}")
+    print()
+
+    asyncio.run(bridge.run())
+
+
+if __name__ == "__main__":
+    main()