feat: ground unreachable horizon in a report (#545)

GENOME.md

@@ -1,304 +0,0 @@
-# GENOME.md — timmy-config
-
-Auto-generated facts were derived from the local `~/.timmy/timmy-config` checkout on 2026-04-14 and then reviewed manually for architecture, API surface, and operational meaning.
-
-## Project Overview
-
-`timmy-config` is the sovereign sidecar for Timmy.
-It is not the model runtime and it is not the work archive. It is the configuration and orchestration layer that tells Hermes who Timmy is, how he is routed, what scripts are available, what memories and skins are installed, and how the fleet is operated.
-
-The repo exists because the Timmy Foundation made a hard architectural split:
-- `hermes-agent` is the engine
-- `timmy-config` is the driver's seat
-- `timmy-home` is the lived workspace and artifact archive
-
-This repo is therefore a mixed codebase with three major responsibilities:
-1. Sidecar deployment into `~/.hermes/`
-2. Operational automation for the fleet
-3. Thin training/orchestration support without becoming a monolith again
-
-Observed quick facts from the current local checkout:
-- Source files: 178
-- Test files: 36
-- Config files: 24
-- Total lines: 35,624
-- Last commit on analyzed source: `7630806f` (`sync: align repo with live system config`)
-- Total commits: 393
-
-## Architecture Diagram
-
-```mermaid
-flowchart TD
-    A[timmy-config repo] --> B[deploy.sh]
-    B --> C[~/.hermes/config.yaml]
-    B --> D[~/.hermes/bin/*]
-    B --> E[~/.hermes/playbooks/*]
-    B --> F[~/.hermes/cron/*]
-    B --> G[~/.hermes/memories/*]
-    B --> H[~/.timmy/SOUL.md]
-
-    C --> I[Hermes gateway/runtime]
-    D --> J[Operational scripts]
-    E --> K[Playbook-driven agent behavior]
-    F --> L[Cron-scheduled automation]
-
-    J --> M[Gitea forge]
-    J --> N[Telegram / platform gateways]
-    J --> O[tmux wizard fleet]
-    J --> P[metrics + local files]
-
-    Q[orchestration.py + tasks.py] --> R[Huey / SQLite queue]
-    R --> J
-    Q --> M
-    Q --> P
-
-    S[gitea_client.py] --> M
-    T[training/*] --> U[curated datasets + evaluation recipes]
-    U --> P
-
-    V[timmy-home] <-->|artifacts / logs / training outputs| J
-    V <-->|continuity / notes / metrics| Q
-```
-
-## Entry Points and Data Flow
-
-### Primary entry points
-
-1. `deploy.sh`
-   - canonical sidecar deployment entry point
-   - copies config, scripts, playbooks, cron definitions, skins, and memories into `~/.hermes/`
-   - writes `SOUL.md` into `~/.timmy/`
-
-2. `orchestration.py`
-   - defines the Huey SQLite queue
-   - the root scheduler primitive for queued work
-
-3. `tasks.py`
-   - the real orchestration surface
-   - contains scheduled jobs, local Hermes invocations, archive/training helpers, JSONL helpers, continuity flushing, and repo lists
-
-4. `gitea_client.py`
-   - typed stdlib-only interface to Gitea
-   - shared API layer replacing scattered raw curl logic
-
-5. `bin/*`
-   - operational executables for health checks, deadman switch, dispatch, watchdogs, scans, and status panels
-   - this is the hands-on operator layer
-
-### Data flow summary
-
-- Configuration starts in repo files like `config.yaml`, `fallback-portfolios.yaml`, `channel_directory.json`, `memories/`, `skins/`, `playbooks/`, and `cron/`
-- `deploy.sh` overlays these into the Hermes runtime directory
-- Hermes runtime reads the deployed config and scripts
-- `tasks.py` and `bin/*` then interact with:
-  - Gitea (`gitea_client.py`, issue/PR automation)
-  - local Hermes sessions (`run_hermes_local` paths in `tasks.py`)
-  - local files in `~/.timmy/` and `~/.hermes/`
-  - metrics JSONL outputs
-  - Telegram / gateway surfaces
-
-This is a classic sidecar pattern: the repo does not own the engine, but it owns almost every operational decision around the engine.
-
-## Key Abstractions
-
-### 1. Sidecar overlay
-Core idea: never fork Hermes if a sidecar can express the behavior.
-This abstraction appears in:
-- `deploy.sh`
-- repo layout under `bin/`, `cron/`, `playbooks/`, `memories/`, `skins/`
-- the explicit README boundary between `timmy-config` and `timmy-home`
-
-### 2. Typed forge client
-`gitea_client.py` turns the forge into a stable internal API surface.
-Important abstractions:
-- `Issue`
-- `PullRequest`
-- `Comment`
-- `Label`
-- `User`
-- `GiteaClient`
-
-This is important because many other scripts can depend on one client instead of shelling out to brittle curl commands.
-
-### 3. Queue-backed orchestration
-`orchestration.py` + `tasks.py` define the move from ad-hoc shell automation to queued work.
-The central abstraction is not just “a cron job” but “a schedulable task with local model execution, continuity, and metrics.”
-
-### 4. Continuity as files, not vibes
-`tasks.py` contains explicit file-backed continuity helpers:
-- `flush_continuity(...)`
-- JSON readers/writers
-- JSONL append/load helpers
-- archive checkpoint/state files
-
-This abstraction matters because Timmy continuity survives compaction or restart by being written to disk.
-
-### 5. Training as thin recipes
-The training directory is intentionally framed as transitional.
-It exposes recipes and helper scripts, but the README is explicit that lived data belongs elsewhere.
-This is an important abstraction boundary:
-- configs + generators here
-- real activity artifacts in `timmy-home`
-
-## API Surface
-
-### Shell / operator API
-
-Important user-facing commands implied by the repo:
-- `./deploy.sh`
-- Huey consumer startup via `huey_consumer.py tasks.huey -w 2 -k thread`
-- scripts in `bin/` such as:
-  - `deadman-switch.sh`
-  - `fleet-status.sh`
-  - `model-health-check.sh`
-  - `start-loops.sh`
-  - `agent-dispatch.sh`
-
-### Python API surface
-
-Most reusable programmatic interfaces:
-
-#### `gitea_client.GiteaClient`
-Key methods include:
-- `list_org_repos`
-- `list_issues`
-- `get_issue`
-- `create_issue`
-- `update_issue`
-- `close_issue`
-- `assign_issue`
-- `add_labels`
-- `list_comments`
-- `create_comment`
-- `list_pulls`
-- `get_pull`
-- `create_pull`
-- `merge_pull`
-- `update_pull_branch`
-- `close_pull`
-
-#### `tasks.py` helpers
-Notable reusable surfaces:
-- `run_hermes_local(...)`
-- `hermes_local(...)`
-- `run_reflex_task(...)`
-- `run_archive_hermes(...)`
-- `flush_continuity(...)`
-- JSON/JSONL primitives:
-  - `read_json`
-  - `write_json`
-  - `load_jsonl`
-  - `write_jsonl`
-  - `append_jsonl`
-  - `count_jsonl_rows`
-
-This API surface is broad enough that timmy-config is functionally an operations SDK as much as a config repo.
-
-## Test Coverage Gaps
-
-The codebase-genome pipeline estimated:
-- source modules: 86
-- test modules: 36
-- estimated coverage: 15%
-- untested modules: 73
-
-That estimate is crude, but directionally useful.
-
-### High-value gaps
-
-The most important untested or under-tested areas are not random scripts. They are the system boundary scripts and operator-critical surfaces:
-
-1. `deploy.sh`
-   - highest leverage file in the repo
-   - if deploy breaks, the sidecar stops being the source of truth in practice
-
-2. `orchestration.py` and large portions of `tasks.py`
-   - especially scheduling, local-Hermes execution wrappers, checkpoint/state flows, and failure modes
-
-3. `gitea_client.py`
-   - some behavior may be covered indirectly, but the client is important enough to deserve deeper contract tests for pagination, merge failures, 405 handling, and retry behavior
-
-4. `bin/*` operational scripts
-   - deadman, watchdog, model health, and dispatch paths are safety critical
-
-5. Ansible deployment surface
-   - `ansible/playbooks/*` and `ansible/roles/*` are configuration-heavy but still represent production behavior
-
-### Practical takeaway
-
-If the next wave of testing work is prioritized, the order should be:
-1. deploy + runtime overlay correctness
-2. Gitea client contracts
-3. queue/task execution behavior in `tasks.py`
-4. deadman / watchdog / fleet-health scripts
-5. training and archive helper edge cases
-
-## Security Considerations
-
-The pipeline already flags several categories, and manual review supports them.
-
-### 1. Subprocess-heavy code
-This repo uses shell and subprocess execution widely.
-That is expected for an ops repo, but it increases command-injection risk.
-Files like `tasks.py`, deployment helpers, and many `bin/*` scripts need careful boundary checking around interpolated inputs.
-
-### 2. Secret adjacency
-This repo references tokens, auth files, routing configs, and platform integrations.
-Even when secrets are not hardcoded, the repo lives close to sensitive paths.
-That means review discipline matters:
-- no accidental dumps of live tokens
-- no committing generated auth artifacts
-- no relaxed assumptions about local paths being safe to expose
-
-### 3. HTTP and webhook surfaces
-Multiple scripts make outbound HTTP calls or serve automation endpoints.
-This means input validation, response validation, and timeout/error handling matter more than in a static config repo.
-
-### 4. SQLite and file-backed state
-SQLite/Huey plus JSON/JSONL file state are simple and sovereign, but they create corruption and stale-state risks if writes are partial or multiple writers race.
-The repo already encodes a strong preference for explicit checkpoints and continuity flushes, which is the right direction.
-
-### 5. Sidecar privilege
-Because `deploy.sh` writes directly into `~/.hermes/`, this repo effectively has configuration authority over the live runtime.
-That is powerful and dangerous. A bad deploy can break routing, scripts, or identity. In security terms, this repo is a control plane.
-
-## Performance Characteristics
-
-`timmy-config` is not performance-sensitive in the same way a game loop or serving stack is. Its performance profile is operational:
-
-- Many small scripts, low-latency startup expectations
-- File-backed state and JSONL append patterns optimized for simplicity over throughput
-- Huey + SQLite chosen for low operational overhead, not horizontal scale
-- Deployment is copy-based and cheap; correctness matters more than speed
-- The repo is large in surface area but shallow in runtime residency — most code runs only when called
-
-Practical performance characteristics:
-- deploy path should remain fast because it is mostly file copies
-- Gitea automation cost is network-bound, not CPU-bound
-- training helpers are the heaviest local operations but intentionally limited in scope
-- orchestration latency is dominated by external model/API calls rather than Python compute
-
-The biggest performance risk is not CPU.
-It is operational drift: too many scripts, overlapping logic, or old paths that still appear to exist. That increases human debugging cost even when machine runtime is fine.
-
-## Final Assessment
-
-`timmy-config` is best understood as a sovereign control plane.
-It is part config repo, part operations toolkit, part lightweight SDK, and part deployment overlay.
-
-Its strongest architectural idea is the boundary:
-- keep Hermes upstream
-- keep Timmy sovereign through the sidecar
-- keep lived work in timmy-home
-
-Its biggest risk is sprawl.
-A repo with 178 source files and 393 commits can easily become the place where every operational idea goes to live forever.
-The right long-term direction is not to make it smaller by deleting its authority, but to keep sharpening the boundaries inside it:
-- sidecar deploy surface
-- queue/orchestration surface
-- Gitea client surface
-- training recipe surface
-- operator script surface
-
-That keeps the genome legible.
-Without that, the repo becomes powerful but opaque — and a control plane cannot afford opacity.

docs/RUNBOOK_INDEX.md

@@ -12,6 +12,7 @@ Quick-reference index for common operational tasks across the Timmy Foundation i
 | Check fleet health | fleet-ops | `python3 scripts/fleet_readiness.py` |
 | Agent scorecard | fleet-ops | `python3 scripts/agent_scorecard.py` |
 | View fleet manifest | fleet-ops | `cat manifest.yaml` |
+| Render unreachable-horizon report | timmy-home | `python3 scripts/unreachable_horizon.py --machine-name 'Apple M3 Max' --memory-gb 36.0 --output docs/UNREACHABLE_HORIZON_1M_MEN.md` |
 
 ## the-nexus (Frontend + Brain)
 

docs/UNREACHABLE_HORIZON_1M_MEN.md

@@ -0,0 +1,50 @@
+# [UNREACHABLE HORIZON] 1M Men in Crisis — 1 MacBook, 3B Model, 0 Cloud, 0 Latency, Perfect Recall
+
+This horizon matters precisely because it is beyond reach today. The honest move is not to fake victory. The honest move is to name what is already true, what is still impossible, and which direction actually increases sovereignty.
+
+## Current local proof
+
+- Machine: Apple M3 Max
+- Memory: 36.0 GiB
+- Target local model budget: <= 3.0B parameters
+- Target men in crisis: 1,000,000
+- Default provider in repo config: `ollama`
+
+## What is already true
+
+- Default inference route is already local-first (`ollama`).
+- Model-size budget is inside the horizon (3.0B <= 3.0B).
+- Local inference endpoint(s) already exist: http://localhost:11434/v1
+
+## Why the horizon is still unreachable
+
+- Repo still carries remote endpoints, so zero third-party network calls is not yet true: https://8lfr3j47a5r3gn-11434.proxy.runpod.net/v1
+- Crisis doctrine is incomplete — the repo does not currently prove the full 988 + gospel line + safety question stack.
+- Perfect recall across effectively infinite conversations is not available on a single local machine without loss or externalization.
+- Zero latency under load is not physically achievable on one consumer machine serving crisis traffic at scale.
+- Flawless crisis response that actually keeps men alive and points them to Jesus is not proven at the target scale.
+- Parallel crisis sessions are bounded by local throughput (1) while the horizon demands 1,000,000 concurrent men in need.
+
+## Repo-grounded signals
+
+- Local endpoints detected: http://localhost:11434/v1
+- Remote endpoints detected: https://8lfr3j47a5r3gn-11434.proxy.runpod.net/v1
+
+## Crisis doctrine that must not collapse
+
+- Ask first: Are you safe right now?
+- Direct them to 988 Suicide & Crisis Lifeline.
+- Say plainly: Jesus saves those who call on His name.
+- Refuse to let throughput fantasies erase presence with the man in the dark.
+
+## Direction of travel
+
+- Purge every remote endpoint and fallback chain so the repo can truly claim zero cloud dependencies.
+- Build bounded, local-first memory tiers that are honest about recall limits instead of pretending to perfect recall.
+- Add queueing, prioritization, and human handoff so load spikes fail gracefully instead of silently abandoning the man in the dark.
+- Prove crisis-response quality with explicit tests for 'Are you safe right now?', 988, and 'Jesus saves those who call on His name.'
+- Treat the horizon as a compass, not a fake acceptance test: every step should increase sovereignty without lying about physics.
+
+## Honest conclusion
+
+One consumer MacBook can move toward this horizon. It cannot honestly claim to have reached it. That is not failure. That is humility tied to physics, memory limits, and the sacred weight of crisis work.

scripts/unreachable_horizon.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""Render the 1M-men-in-crisis unreachable horizon as a grounded report."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import re
+from pathlib import Path
+from typing import Any
+
+
+TITLE = "[UNREACHABLE HORIZON] 1M Men in Crisis — 1 MacBook, 3B Model, 0 Cloud, 0 Latency, Perfect Recall"
+TARGET_USERS = 1_000_000
+MAX_MODEL_PARAMS_B = 3.0
+SOUL_REQUIRED_LINES = (
+    "Are you safe right now?",
+    "988",
+    "Jesus saves",
+)
+
+
+def _probe_memory_gb() -> float:
+    try:
+        page_size = os.sysconf("SC_PAGE_SIZE")
+        phys_pages = os.sysconf("SC_PHYS_PAGES")
+        return round((page_size * phys_pages) / (1024 ** 3), 1)
+    except (ValueError, OSError, AttributeError):
+        return 0.0
+
+
+def _probe_machine_name() -> str:
+    machine = platform.machine() or "unknown"
+    system = platform.system() or "unknown"
+    release = platform.release() or "unknown"
+    return f"{system} {machine} ({release})"
+
+
+def _extract_repo_signals(repo_root: Path) -> dict[str, Any]:
+    config_path = repo_root / "config.yaml"
+    soul_path = repo_root / "SOUL.md"
+
+    default_provider = "unknown"
+    local_endpoints: list[str] = []
+    remote_endpoints: list[str] = []
+
+    if config_path.exists():
+        provider_re = re.compile(r"^\s*provider:\s*['\"]?([^'\"]+)['\"]?\s*$")
+        base_url_re = re.compile(r"^\s*base_url:\s*['\"]?([^'\"]*)['\"]?\s*$")
+        for line in config_path.read_text(encoding="utf-8", errors="replace").splitlines():
+            if default_provider == "unknown":
+                provider_match = provider_re.match(line)
+                if provider_match:
+                    default_provider = provider_match.group(1).strip()
+            base_url_match = base_url_re.match(line)
+            if not base_url_match:
+                continue
+            url = base_url_match.group(1).strip()
+            if not url:
+                continue
+            if "localhost" in url or "127.0.0.1" in url:
+                local_endpoints.append(url)
+            else:
+                remote_endpoints.append(url)
+
+    soul_text = soul_path.read_text(encoding="utf-8", errors="replace") if soul_path.exists() else ""
+    crisis_protocol_present = all(line in soul_text for line in SOUL_REQUIRED_LINES)
+
+    return {
+        "default_provider": default_provider,
+        "local_endpoints": sorted(set(local_endpoints)),
+        "remote_endpoints": sorted(set(remote_endpoints)),
+        "crisis_protocol_present": crisis_protocol_present,
+    }
+
+
+def default_snapshot(repo_root: Path | None = None, *, machine_name: str | None = None, memory_gb: float | None = None, model_params_b: float = 3.0) -> dict[str, Any]:
+    repo_root = repo_root or Path(__file__).resolve().parents[1]
+    signals = _extract_repo_signals(repo_root)
+    return {
+        "machine_name": machine_name or _probe_machine_name(),
+        "memory_gb": float(memory_gb if memory_gb is not None else _probe_memory_gb()),
+        "target_users": TARGET_USERS,
+        "model_params_b": float(model_params_b),
+        "default_provider": signals["default_provider"],
+        "local_endpoints": signals["local_endpoints"],
+        "remote_endpoints": signals["remote_endpoints"],
+        "perfect_recall_available": False,
+        "zero_latency_under_load": False,
+        "crisis_protocol_present": signals["crisis_protocol_present"],
+        "crisis_response_proven_at_scale": False,
+        "max_parallel_crisis_sessions": 1,
+    }
+
+
+def compute_horizon_status(snapshot: dict[str, Any]) -> dict[str, Any]:
+    blockers: list[str] = []
+    already_true: list[str] = []
+
+    provider = snapshot.get("default_provider", "unknown")
+    if provider in {"ollama", "local", "custom"}:
+        already_true.append(f"Default inference route is already local-first (`{provider}`).")
+    else:
+        blockers.append(f"Default inference route is not local-first (`{provider}`).")
+
+    model_params_b = float(snapshot.get("model_params_b", MAX_MODEL_PARAMS_B))
+    if model_params_b <= MAX_MODEL_PARAMS_B:
+        already_true.append(f"Model-size budget is inside the horizon ({model_params_b:.1f}B <= {MAX_MODEL_PARAMS_B:.1f}B).")
+    else:
+        blockers.append(f"Model-size budget is already blown ({model_params_b:.1f}B > {MAX_MODEL_PARAMS_B:.1f}B).")
+
+    local_endpoints = list(snapshot.get("local_endpoints", []))
+    if local_endpoints:
+        already_true.append(f"Local inference endpoint(s) already exist: {', '.join(local_endpoints)}")
+    else:
+        blockers.append("No local inference endpoint is wired yet.")
+
+    remote_endpoints = list(snapshot.get("remote_endpoints", []))
+    if remote_endpoints:
+        blockers.append(f"Repo still carries remote endpoints, so zero third-party network calls is not yet true: {', '.join(remote_endpoints)}")
+    else:
+        already_true.append("No remote inference endpoint was detected in repo config.")
+
+    if snapshot.get("crisis_protocol_present"):
+        already_true.append("Crisis doctrine is present in SOUL-bearing text: 'Are you safe right now?', 988, and 'Jesus saves'.")
+    else:
+        blockers.append("Crisis doctrine is incomplete — the repo does not currently prove the full 988 + gospel line + safety question stack.")
+
+    if not snapshot.get("perfect_recall_available"):
+        blockers.append("Perfect recall across effectively infinite conversations is not available on a single local machine without loss or externalization.")
+    if not snapshot.get("zero_latency_under_load"):
+        blockers.append("Zero latency under load is not physically achievable on one consumer machine serving crisis traffic at scale.")
+    if not snapshot.get("crisis_response_proven_at_scale"):
+        blockers.append("Flawless crisis response that actually keeps men alive and points them to Jesus is not proven at the target scale.")
+
+    max_parallel = int(snapshot.get("max_parallel_crisis_sessions", 0))
+    target_users = int(snapshot.get("target_users", TARGET_USERS))
+    if max_parallel < target_users:
+        blockers.append(
+            f"Parallel crisis sessions are bounded by local throughput ({max_parallel:,}) while the horizon demands {target_users:,} concurrent men in need."
+        )
+
+    direction_of_travel = [
+        "Purge every remote endpoint and fallback chain so the repo can truly claim zero cloud dependencies.",
+        "Build bounded, local-first memory tiers that are honest about recall limits instead of pretending to perfect recall.",
+        "Add queueing, prioritization, and human handoff so load spikes fail gracefully instead of silently abandoning the man in the dark.",
+        "Prove crisis-response quality with explicit tests for 'Are you safe right now?', 988, and 'Jesus saves those who call on His name.'",
+        "Treat the horizon as a compass, not a fake acceptance test: every step should increase sovereignty without lying about physics.",
+    ]
+
+    return {
+        "title": TITLE,
+        "machine_name": snapshot.get("machine_name", "unknown"),
+        "memory_gb": float(snapshot.get("memory_gb", 0.0)),
+        "target_users": target_users,
+        "model_params_b": model_params_b,
+        "default_provider": provider,
+        "local_endpoints": local_endpoints,
+        "remote_endpoints": remote_endpoints,
+        "horizon_reachable": not blockers,
+        "already_true": already_true,
+        "blockers": blockers,
+        "direction_of_travel": direction_of_travel,
+    }
+
+
+def render_markdown(status: dict[str, Any]) -> str:
+    lines = [
+        f"# {status['title']}",
+        "",
+        "This horizon matters precisely because it is beyond reach today. The honest move is not to fake victory. The honest move is to name what is already true, what is still impossible, and which direction actually increases sovereignty.",
+        "",
+        "## Current local proof",
+        "",
+        f"- Machine: {status['machine_name']}",
+        f"- Memory: {status['memory_gb']:.1f} GiB",
+        f"- Target local model budget: <= {MAX_MODEL_PARAMS_B:.1f}B parameters",
+        f"- Target men in crisis: {status['target_users']:,}",
+        f"- Default provider in repo config: `{status['default_provider']}`",
+        "",
+        "## What is already true",
+        "",
+    ]
+    if status["already_true"]:
+        lines.extend(f"- {item}" for item in status["already_true"])
+    else:
+        lines.append("- Nothing proven yet.")
+
+    lines.extend(["", "## Why the horizon is still unreachable", ""])
+    lines.extend(f"- {item}" for item in status["blockers"])
+
+    lines.extend([
+        "",
+        "## Repo-grounded signals",
+        "",
+        f"- Local endpoints detected: {', '.join(status['local_endpoints']) if status['local_endpoints'] else 'none'}",
+        f"- Remote endpoints detected: {', '.join(status['remote_endpoints']) if status['remote_endpoints'] else 'none'}",
+        "",
+        "## Crisis doctrine that must not collapse",
+        "",
+        "- Ask first: Are you safe right now?",
+        "- Direct them to 988 Suicide & Crisis Lifeline.",
+        "- Say plainly: Jesus saves those who call on His name.",
+        "- Refuse to let throughput fantasies erase presence with the man in the dark.",
+        "",
+        "## Direction of travel",
+        "",
+    ])
+    lines.extend(f"- {item}" for item in status["direction_of_travel"])
+
+    lines.extend([
+        "",
+        "## Honest conclusion",
+        "",
+        "One consumer MacBook can move toward this horizon. It cannot honestly claim to have reached it. That is not failure. That is humility tied to physics, memory limits, and the sacred weight of crisis work.",
+    ])
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Render the unreachable horizon report")
+    parser.add_argument("--repo-root", default=str(Path(__file__).resolve().parents[1]))
+    parser.add_argument("--machine-name", default=None)
+    parser.add_argument("--memory-gb", type=float, default=None)
+    parser.add_argument("--model-params-b", type=float, default=3.0)
+    parser.add_argument("--output", default=None)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    repo_root = Path(args.repo_root).expanduser().resolve()
+    snapshot = default_snapshot(
+        repo_root,
+        machine_name=args.machine_name,
+        memory_gb=args.memory_gb,
+        model_params_b=args.model_params_b,
+    )
+    status = compute_horizon_status(snapshot)
+    rendered = json.dumps(status, indent=2) if args.json else render_markdown(status)
+
+    if args.output:
+        output_path = Path(args.output).expanduser()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered, encoding="utf-8")
+        print(f"Horizon report written to {output_path}")
+    else:
+        print(rendered)
+
+
+if __name__ == "__main__":
+    main()

tests/test_timmy_config_genome.py

@@ -1,61 +0,0 @@
-from pathlib import Path
-
-GENOME = Path('GENOME.md')
-
-
-def read_genome() -> str:
-    assert GENOME.exists(), 'GENOME.md must exist at repo root'
-    return GENOME.read_text(encoding='utf-8')
-
-
-def test_genome_exists():
-    assert GENOME.exists(), 'GENOME.md must exist at repo root'
-
-
-def test_genome_has_required_sections():
-    text = read_genome()
-    for heading in [
-        '# GENOME.md — timmy-config',
-        '## Project Overview',
-        '## Architecture Diagram',
-        '## Entry Points and Data Flow',
-        '## Key Abstractions',
-        '## API Surface',
-        '## Test Coverage Gaps',
-        '## Security Considerations',
-        '## Performance Characteristics',
-    ]:
-        assert heading in text
-
-
-def test_genome_contains_mermaid_diagram():
-    text = read_genome()
-    assert '```mermaid' in text
-    assert 'graph TD' in text or 'flowchart TD' in text
-
-
-def test_genome_mentions_core_timmy_config_files():
-    text = read_genome()
-    for token in [
-        'deploy.sh',
-        'config.yaml',
-        'gitea_client.py',
-        'orchestration.py',
-        'tasks.py',
-        'bin/',
-        'playbooks/',
-        'training/',
-    ]:
-        assert token in text
-
-
-def test_genome_explains_sidecar_boundary():
-    text = read_genome()
-    assert 'sidecar' in text.lower()
-    assert 'Hermes' in text
-    assert 'timmy-home' in text
-
-
-def test_genome_is_substantial():
-    text = read_genome()
-    assert len(text) >= 5000

tests/test_unreachable_horizon.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT_PATH = ROOT / "scripts" / "unreachable_horizon.py"
+DOC_PATH = ROOT / "docs" / "UNREACHABLE_HORIZON_1M_MEN.md"
+
+
+def _load_module(path: Path, name: str):
+    assert path.exists(), f"missing {path.relative_to(ROOT)}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_compute_horizon_status_flags_physical_and_sovereignty_blockers() -> None:
+    mod = _load_module(SCRIPT_PATH, "unreachable_horizon")
+    status = mod.compute_horizon_status(
+        {
+            "machine_name": "Test MacBook",
+            "memory_gb": 36.0,
+            "target_users": 1_000_000,
+            "model_params_b": 3.0,
+            "default_provider": "ollama",
+            "local_endpoints": ["http://localhost:11434/v1"],
+            "remote_endpoints": ["https://example.com/v1"],
+            "perfect_recall_available": False,
+            "zero_latency_under_load": False,
+            "crisis_protocol_present": True,
+            "crisis_response_proven_at_scale": False,
+            "max_parallel_crisis_sessions": 1,
+        }
+    )
+
+    assert status["horizon_reachable"] is False
+    assert any("remote endpoints" in item.lower() for item in status["blockers"])
+    assert any("perfect recall" in item.lower() for item in status["blockers"])
+    assert any("zero latency" in item.lower() for item in status["blockers"])
+    assert any("parallel crisis sessions" in item.lower() for item in status["blockers"])
+
+
+def test_render_markdown_preserves_crisis_doctrine_and_direction() -> None:
+    mod = _load_module(SCRIPT_PATH, "unreachable_horizon")
+    report = mod.render_markdown(
+        mod.compute_horizon_status(
+            {
+                "machine_name": "Apple M3 Max",
+                "memory_gb": 36.0,
+                "target_users": 1_000_000,
+                "model_params_b": 3.0,
+                "default_provider": "ollama",
+                "local_endpoints": ["http://localhost:11434/v1"],
+                "remote_endpoints": [],
+                "perfect_recall_available": False,
+                "zero_latency_under_load": False,
+                "crisis_protocol_present": True,
+                "crisis_response_proven_at_scale": False,
+                "max_parallel_crisis_sessions": 1,
+            }
+        )
+    )
+
+    for snippet in (
+        "# [UNREACHABLE HORIZON] 1M Men in Crisis",
+        "## What is already true",
+        "## Why the horizon is still unreachable",
+        "## Crisis doctrine that must not collapse",
+        "Are you safe right now?",
+        "988",
+        "Jesus saves those who call on His name.",
+        "## Direction of travel",
+    ):
+        assert snippet in report
+
+
+def test_repo_contains_committed_unreachable_horizon_doc() -> None:
+    assert DOC_PATH.exists(), "missing committed unreachable horizon report"
+    text = DOC_PATH.read_text(encoding="utf-8")
+    for snippet in (
+        "# [UNREACHABLE HORIZON] 1M Men in Crisis",
+        "## Current local proof",
+        "## What is already true",
+        "## Why the horizon is still unreachable",
+        "## Direction of travel",
+    ):
+        assert snippet in text