feat: certified local mode — managed on-device model with verified setup and egress guard

[anandgupta42]

Issue for this PR

Closes #1162

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Adds altimate local — a managed local-model mode. One command detects hardware, downloads a SHA-256-pinned GGUF + llama.cpp runtime, starts a loopback-only server, runs certification probes (tool-call round trip, reasoning render, 8K prefill), and only then wires a local provider into the user config. Subcommands: models, status, stop, doctor, update.

Design decisions worth knowing when reviewing:

• Egress guard (wire.ts): wiring adds ask rules for websearch/webfetch/codesearch. This works because user config merges after agent rulesets and permission evaluation is last-match-wins, so a config-level ask overrides the agents' built-in allow. Rules are only added where the user has no existing key; --no-egress-guard removes only rules a prior guarded wiring actually set (ownership recorded in local mode's own environment.json, not the user config — kept out of the config schema on purpose).
• small_model pinned to local when unset so title generation never silently calls a cloud model. Compaction already follows the session model, so it needs no pin.
• Model registry, not a single model: recipes.json is a models[] registry with per-tier recipes; --model <id> selects, firstModel is only the default. Adding future models is a data change.
• Skill-listing diet (system.ts, gated on the existing ALTIMATE_TOOL_RETRIEVAL env): descriptions compact to their first sentence in the system prompt. Behavior with the flag unset is byte-identical to today. Measured on an M4 Max: first-turn input 33.4K → 28.0K tokens, wall 4:48 → 3:39.
• Session/tool fixes that local models need ride along: turn-boundary-aware fitHead, uncountedTail overflow estimation (with the fitHead 0.8 margin), tool-callid sanitization, shared truncate-core, and honest run accounting (run-accounting.ts) including an idempotent client messageID on run retries (server upserts by id, so an ambiguous network failure can't double-execute a turn).
• TUI: seventh first-run picker row ("Local model") opens an interstitial that explains hardware/download expectations and hands the user the one command; funnel telemetry (local_model_info_shown/local_model_choice) is threaded through the tui-union / Telemetry.Event / onboarding-extract / compile-time parity test — those four must stay in sync.
• Docs: nav entry, Providers section, quickstart picker + air-gapped tip, security-FAQ offline answer, network note, permissions callout, CLI table, platform status/roadmap table, README feature block.

Provenance: this is a content-only re-port of the earlier local-mode work (originally developed on a branch that could not be pushed) with three review rounds applied on top — 16 confirmed findings fixed, including a lock that could loop forever on fresh installs, certification durations measured before the await, docker daemon errors read as "container absent", and a disk-space discount that keyed on any cached .gguf instead of the target artifact.

How did you verify your code works?

• Real end-to-end on an M4 Max (48GB): full altimate local setup ran green after every fix — detect → SHA-verify → serve → certify (3/3 probes) → wire. status/doctor/stop/restart cycle exercised. Real agent turns answered by the local model through altimate run, including after the messageID retry change.
• Egress guard verified live, not just in unit tests: a real session attempting webfetch produced permission requested: webfetch (…); auto-rejecting, and a bash curl attempt was likewise gated. In the interactive TUI the same event renders as an approval prompt.
• ~660 tests green across test/local/ (lock, runtime, hardware, preflight, docker, server, certify, wire, recipes, fetch), session compaction/uncounted-tail, truncate-core, run-accounting, onboarding telemetry, and the TUI welcome-dialog tests. Typecheck clean in packages/opencode and packages/tui. bun run script/upstream/analyze.ts --markers --base main --strict green. mkdocs build --strict green.
• Not verified (stated plainly): native Windows (runtime is pinned and labeled experimental; no GPU probe yet, never certified on real hardware), the DGX Spark docker-sglang tier on real hardware (covered by injectable-exec unit tests only), Linux AMD/Intel GPU auto-detection (known gap — runtime works via Vulkan, docs say exactly that), and the TUI picker row was verified by component tests, not visually in a live terminal.

Screenshots / recordings

Terminal transcript of the real setup run (M4 Max):

◇ Detected: Apple M4 Max (48GB unified memory)
◇ ✓ disk space: 240GB free vs ~4GB needed (artifacts already cached)
◇ Recommended: Qwen3.8-27B UD-Q4_K_M · 131072 context/slot · tool-slim · MTP speculative
◇ Model verified · Runtime installed · Local server healthy: http://127.0.0.1:42625/v1
✓ tool call round trip · ✓ reasoning render · ✓ prompt prefill 8k
✓ Ready. Configured local/qwen3.8-27b in ~/.config/altimate-code/config.json

Live egress-guard probe (headless run auto-rejects; TUI shows an approval prompt):

! permission requested: webfetch (https://github.com/dbt-labs/dbt-core/releases); auto-rejecting
✗ webfetch failed

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

🤖 Generated with Claude Code

https://claude.ai/code/session_019zce4wWoFV7SNti1nfhq5q

---

Note

High Risk
Adds managed downloads, Docker GPU containers, and config/permission wiring plus changed run exit semantics and retries—areas that affect security posture and CI automation.

Overview
Introduces altimate local — a new CLI surface that detects hardware, runs preflight, downloads SHA-256–pinned model/runtime artifacts (llama.cpp or DGX Spark SGLang in Docker), starts a 127.0.0.1-only server, certifies it (tool-call, reasoning, 8K prefill) before touching config, then wires a local provider (with optional egress guard ask rules for web tools). Subcommands cover models, status, stop, doctor, and update; startup calls applyLocalEnvironment() so later commands pick up persisted local defaults.

Headless run harness gets a dedicated run-accounting module: compaction steps no longer count toward --max-turns, termination is split into why_model_stopped / why_harness_stopped, session errors serialize cleanly, prompt enqueue uses bounded retries with a stable messageID, the event subscription is abortable on fatal failure, and process.exitCode = 1 on budget exhaustion or unrecovered errors.

Onboarding telemetry adds local as a curated provider, local_model_* events, and local_model_back on the model picker; compaction_head_truncated is a new event type. Docs/README/quickstart/security/network/permissions expand around Local Mode; the builder prompt adds a mandatory finish protocol (re-read contract, run final build/tests). .gitignore adds docs/site/.

^{Reviewed by Cursor Bugbot for commit ba3ee0e. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Adds altimate local — detects hardware, downloads SHA-256-pinned GGUF and llama.cpp artifacts, certifies a loopback-only server, and wires a local provider into user config only after setup passes. Closes #1162.

Egress guard and config wiring

• Wiring adds ask rules for websearch, webfetch, codesearch; user config merges last, so the guard overrides agent built-in allow rules, and the key-absent check evaluates the effective permission across config files in precedence order.
• Pre-existing provider.local blocks are deep-merged rather than replaced, so custom options and extra models survive re-wiring; --no-egress-guard removes exactly the keys a prior wiring added, tracked per-key in environment.json and carried across re-runs.
• small_model pins to local when unset, so title generation never calls a cloud model; compaction already follows the session model.
• Setup validates everything before stopping a working server; broken runtimes are replaced, checksum-failed artifacts redownloaded once, containers are label-stamped and reaped on interruption with a second signal exiting immediately, stale locks are reclaimed atomically with post-rename ownership re-verification, the RAM-as-accelerator fallback is gated to unified-memory macOS so CPU-only Linux fails fast, remote recipes can't advance the pinned runtime ref, truncated cached artifacts don't earn disk discount, and invalid resume ranges restart the download.

Session and tool fixes riding along

• Fixes local models exposed: turn-boundary-aware fitHead (empties head when context ≤ headroom), uncountedTail overflow estimation, deterministic tool-call-id sanitization, shared truncate-core, SGLang overflow detection.
• Skill listings under ALTIMATE_TOOL_RETRIEVAL compact descriptions to their first sentence; byte-identical without the flag.
• Run retries carry an idempotent messageID; re-delivery returns the existing message, unrecovered mid-stream or terminal overflow errors exit nonzero, and only a trailing explicit DONE counts as termination.
• Tool-output truncation defaults to middle (head+tail) rather than head-only; laptop tier runs at certified 65536 context, 131072 on the 64GB tier.
• First-run picker gains a Local model row with funnel telemetry; native Windows resolves process identity via PowerShell CIM.

^{Written for commit ba3ee0e. Summary will update on new commits.}

Summary by CodeRabbit

• New Features
  • Added altimate local for certified, API-key-free local model setup and inference.
  • Added hardware detection, verified downloads, model server management, diagnostics, and optional approval controls for web access.
  • Added a Local model option to first-run setup.
• Bug Fixes
  • Improved context-overflow recovery, tool-call compatibility, truncation, retry handling, duplicate message prevention, and fatal-run exit reporting.
• Documentation
  • Added comprehensive Local Mode setup, security, networking, platform, and troubleshooting guidance.