ltcai 11.5.1 → 11.6.0

package/README.md

@@ -11,7 +11,7 @@
 [![CI Status](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-![v11.5.1 Living Brain walkthrough](output/release/v11.5.1/gifs/v11.5.1-living-brain-walkthrough.gif)
+![v11.6.0 Living Brain walkthrough](output/release/v11.6.0/gifs/v11.6.0-living-brain-walkthrough.gif)
 
 Chat, files, folders, notes, and web pages all flow into one durable knowledge
 graph on your computer. Any model — local MLX or cloud — can speak with that
@@ -24,10 +24,10 @@ memory. Nothing leaves your machine without explicit consent.
 
 | | |
 | --- | --- |
-| **See your Brain's story in time** — a growth curve, an activity heatmap, and each day's story, rewindable to any past moment ![Brain Chronicle](output/release/v11.5.1/screenshots/13-chronicle.png) | **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v11.5.1/screenshots/04-brain-chat-home.png) |
-| **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v11.5.1/screenshots/05-memory-graph.png) | **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v11.5.1/screenshots/06-capture.png) |
-| **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v11.5.1/screenshots/12-review-center.png) | **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v11.5.1/screenshots/02-recommended-models.png) |
-| **Watch a file become memory** — three named steps, not a pipeline diagram ![Material to memory](output/release/v11.5.1/screenshots/11-knowledge-journey.png) | **Say how much it may do alone** — one dial in plain words; dangerous actions stay blocked either way ![Settings](output/release/v11.5.1/screenshots/08-system.png) |
+| **See your Brain's story in time** — a growth curve, an activity heatmap, and each day's story, rewindable to any past moment ![Brain Chronicle](output/release/v11.6.0/screenshots/13-chronicle.png) | **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v11.6.0/screenshots/04-brain-chat-home.png) |
+| **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v11.6.0/screenshots/05-memory-graph.png) | **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v11.6.0/screenshots/06-capture.png) |
+| **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v11.6.0/screenshots/12-review-center.png) | **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v11.6.0/screenshots/02-recommended-models.png) |
+| **Watch a file become memory** — three named steps, not a pipeline diagram ![Material to memory](output/release/v11.6.0/screenshots/11-knowledge-journey.png) | **Say how much it may do alone** — one dial in plain words; dangerous actions stay blocked either way ![Settings](output/release/v11.6.0/screenshots/08-system.png) |
 
 ## Why Lattice AI
 
@@ -58,72 +58,81 @@ First-run flow — wake the Brain, pick the owner, load a recommended model:
 
 | | | |
 | --- | --- | --- |
-| ![Login](output/release/v11.5.1/screenshots/01-login.png) | ![Model install](output/release/v11.5.1/screenshots/03-install-load-progress.png) | ![Model library](output/release/v11.5.1/screenshots/07-model-library.png) |
+| ![Login](output/release/v11.6.0/screenshots/01-login.png) | ![Model install](output/release/v11.6.0/screenshots/03-install-load-progress.png) | ![Model library](output/release/v11.6.0/screenshots/07-model-library.png) |
 
 Screenshot index and capture notes:
-[output/release/v11.5.1/SCREENSHOT_INDEX.md](output/release/v11.5.1/SCREENSHOT_INDEX.md)
+[output/release/v11.6.0/SCREENSHOT_INDEX.md](output/release/v11.6.0/SCREENSHOT_INDEX.md)
 
 ## Current Release
 
-The current release is **11.5.1 — Rust Full Loop**:
-
-The two explicitly-remaining items are done: the agent loop orchestrator
-now runs in Rust — proven by replaying the real Python runtime on scripted
-LLM transcripts (**10 trajectories, byte-identical**) and by a live smoke
-against the real worker — and the document-generation context builder is
-native (53 new goldens, 247 total). Every Rust box in the target diagram
-is implemented; Python remains exactly the AI Worker that diagram draws:
-LLM inference, tool-handler execution, and all graph writes behind three
-new fully-covered worker seams with server-side circuit breakers intact.
-
-- **The desktop's front door is now the Rust gateway.** The Tauri shell
-  boots the supervisor + gateway topology by default and the webview
-  lives at the gateway origin. The one real blocker — a CSRF policy
-  bound to the worker's own port — is dissolved by environment
-  injection, proven live against the real Python worker (trusted
-  origins 200, foreign origins 403). Three escape hatches preserve the
-  previous topologies.
-- **The native surface grew fourfold.** `lattice-retrieval` now serves
-  the three-channel service search, graph reads (search /
-  relationships / traverse), the full history read family, and the
-  chat context assembler — **191/191 exact-parity goldens, zero
-  epsilon**. `lattice-ingest` carries the typed chunker (332 golden
-  chunks, and a 26/26 mutation-test pass proving every constant
-  load-bearing) plus the polling folder watcher; writes stay delegated
-  to the worker, the single writer. `lattice-agent` carries the
-  permission kernel — **2,452 exact decision-table verdicts** — and
-  natively executes only validated read-only commands in a replaced
-  environment. `lattice-jobs` closes a documented gap: the durable
-  embed queue now has a scheduler (60s ticks, honest backoff,
-  `/host/jobs` status) driving a new fully-covered drain endpoint.
-- **The honest boundary, stated.** The Python worker keeps the document
-  parser matrix, embedding production, LLM inference, mutating tool
-  execution, and all graph writes. The agent loop orchestration port
-  remains for a future release, for reasons written down in the plan.
-
-All of it lands with the floor intact: **6,861 Python + 1,761 frontend
-tests at 100.00% statement and branch coverage — now 7,006 Python +
-1,761 frontend — and 739 Rust workspace tests**, four bidirectional golden families, mypy/ruff/clippy clean,
-verified on macOS 3.14 and a fresh-resolve python 3.11 environment.
-
-Release notes: [RELEASE.md](RELEASE.md) · Full history: [docs/CHANGELOG.md](docs/CHANGELOG.md)
-
-Expected artifacts for 11.5.1 release must use exact filenames:
-
-- `dist/ltcai-11.5.1-py3-none-any.whl`
-- `dist/ltcai-11.5.1.tar.gz`
-- `ltcai-11.5.1.tgz`
-- `dist/ltcai-11.5.1.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_11.5.1_aarch64.dmg`
+The current release is **11.6.0 — One Door**:
+
+The product now has one front door, and it is Rust. `lattice-host` serves
+**420 operations across 41 route families** at the paths they always had,
+and the Python package is no longer a web application at all — it is a
+pure-compute **AI worker** with **28 routes**: LLM inference and streaming,
+embedding, extraction, parsing, four document renderers, speech-to-text,
+multimodal description, the model and engine catalog, `sysinfo`, and
+`/health`. Nine crates hold the product; the door forwards exactly the 28
+and answers `404 {"detail":"Not Found"}` for anything else, from a
+committed allowlist that a drift gate regenerates and compares.
+
+- **Every write is native.** The knowledge-graph write engine moved into
+  `lattice-core`: ingest, curation, provenance, taxonomy and the vector
+  queue. It is held to Python's bytes by a **32-step row-parity battery**
+  that dumps every table after every step with zero tolerated differences,
+  and by a schema comparison over all **67 objects** in `sqlite_master`
+  (indexes and FTS shadow tables included). Seventeen graph tables changed
+  owner from the worker to Rust, and the single-writer invariant is now a
+  test rather than a convention.
+- **The surface is replayed, not re-described.** **1,487 recorded HTTP
+  cases** across twelve committed fixture files — captured from the real
+  Python app while it still served them — are replayed against the native
+  routes, status line and body compared. The retrieval, chunking, agent
+  kernel and agent-loop golden families are unchanged and still green.
+- **298 Python files and 73,617 lines were deleted.** What remains is 127
+  files and about 20,900 lines, all of it compute, at **100.00% statement
+  and branch coverage** with `fail_under=100` and no new pragmas.
+- **What the port found.** The Python oracle's own bugs are documented
+  rather than smoothed over: four graph-write divergences (a `kgv2_*` view
+  that updates `type` on conflict where `nodes` does not; two writers that
+  serialise without `sort_keys`; a hash computed from CPython's default
+  JSON separators), a documented redaction rule that never fired, and a
+  change-proposal kind whitelist that could never approve a folder
+  reorganization. Three known-wrong behaviours were ported **as they are**
+  so the surface does not change under users mid-release — they are listed
+  in [RELEASE_NOTES_v11.6.0.md](RELEASE_NOTES_v11.6.0.md).
+- **What was removed, and why.** The **Telegram bridge** is gone: it lived
+  in the platform code that became the worker, and a bridge with no product
+  server to bridge to is not a feature. **SSO/OIDC login and callback
+  flows** are gone with it — the configuration surface remains, and
+  password login is native. Both are consequences of the worker boundary,
+  not decisions taken on their own merits.
+
+Full disclosure of gaps, ported bugs and removed surfaces:
+[RELEASE_NOTES_v11.6.0.md](RELEASE_NOTES_v11.6.0.md)
+
+Expected artifacts for 11.6.0 release must use exact filenames:
+
+- `dist/ltcai-11.6.0-py3-none-any.whl`
+- `dist/ltcai-11.6.0.tar.gz`
+- `ltcai-11.6.0.tgz`
+- `dist/ltcai-11.6.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_11.6.0_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 
+Release notes: [RELEASE.md](RELEASE.md) · Full history: [docs/CHANGELOG.md](docs/CHANGELOG.md)
+
 ## Architecture At A Glance
 
-FastAPI on localhost is the source of truth; the React/Vite frontend and the
-Tauri desktop shell sit on top; the independent `lattice_brain` package owns
-the graph, memory, ingestion, and portability. Local-first by default — cloud
-calls, downloads, Telegram, and update checks are opt-in.
+One Rust server on localhost is the source of truth: `lattice-host` answers
+every product route, owns every write to the Brain, and supervises a Python
+**AI worker** it reaches over loopback for the things a model does — inference,
+embedding, extraction, parsing, rendering, speech-to-text. The React/Vite
+frontend and the Tauri desktop shell sit on top of that one door. Local-first
+by default — cloud model calls, downloads, Brain Network, and update checks are
+opt-in.
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the developer workflow
@@ -133,22 +142,37 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
 ## Known Limitations
 
 - External package registries are owner-published and can lag behind GitHub.
-- PostgreSQL/pgvector is optional scale/migration tooling. SQLite remains the
-  live local Brain store in 10.3.0.
-- Docker, model downloads, cloud model calls, Telegram, Brain Network, and
-  update checks require explicit user action.
+- SQLite is the live local Brain store. The optional PostgreSQL/pgvector
+  migration tooling is not part of the 11.6.0 worker.
+- Docker, model downloads, cloud model calls, Brain Network, and update checks
+  require explicit user action.
+- **The Telegram bridge was removed in 11.6.0** — it lived in the platform code
+  that became the AI worker. **SSO/OIDC login and callback flows were removed
+  with it**; the configuration surface remains and password login is native.
 - Conversation does not fabricate answers when no model is loaded. Agent and
   workflow simulation without a loaded LLM is deterministic and LLM-free (it
   does not call a model) — labeled as such, never presented as autonomous
   model success.
-- Some backend-generated messages (for example the Postgres DSN notice) are
-  produced server-side in English and are shown as-is; server-side i18n is not
-  part of 10.3.0.
+- `POST /worker/render/pdf` ships working out of the box: `reportlab` is a
+  required dependency as of 11.6.0 (it used to be an undeclared lazy import
+  that raised a 500; `ltcai[pdf]` remains as an empty alias for older
+  install instructions).
+- Known gaps carried openly into this release — upload extraction enrichment is
+  UTF-8-text only, supplied vectors cover the primary ingest node, and the
+  pointer-control tools still execute in the worker — are listed with their
+  reasons in [RELEASE_NOTES_v11.6.0.md](RELEASE_NOTES_v11.6.0.md).
 
 ## Release History
 
+Public history starts at 11.0.0. 11.6.0 rebuilt the product server in Rust and
+reduced the Python package to an AI worker, so a 10.x or 9.x install is a
+different program; `SECURITY.md` supports only 11.x, and this table states the
+same boundary. Earlier notes stay in the tree as `RELEASE_NOTES_v*.md` files.
+
 | Version | Theme |
 | --- | --- |
+| 11.6.0 | One Door |
+| 11.5.2 | Tight Ship |
 | 11.5.1 | Rust Full Loop |
 | 11.5.0 | Rust Complete |
 | 11.4.0 | Rust Foundation |
@@ -157,54 +181,5 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
 | 11.1.0 | Product Intelligence |
 | 11.0.1 | Both Branches |
 | 11.0.0 | Full Measure |
-| 10.10.0 | Quiet Station |
-| 10.9.0 | Never Blocks |
-| 10.8.0 | Within Reach |
-| 10.7.0 | Plain Surface |
-| 10.6.4 | Loud Limits |
-| 10.6.3 | Loud Limits |
-| 10.6.2 | Ask First |
-| 10.6.1 | First Things |
-| 10.6.0 | Promoted Panels |
-| 10.5.0 | Everyday Words |
-| 10.4.0 | Named Ground |
-| 10.3.0 | Measured Ground |
-| 10.2.0 | Load-Bearing Fixes |
-| 10.1.1 | Reachable Boundary |
-| 10.1.0 | Hybrid Brain |
-| 10.0.1 | One Source of Truth |
-| 10.0.0 | Plain Language |
-| 9.9.9 | Lean Shell |
-| 9.9.8 | Autonomy Dial |
-| 9.9.7 | No Gaps Left |
-| 9.9.6 | Same Brain Everywhere |
-| 9.9.5 | Closed Gaps |
-| 9.9.4 | Durable Loops |
-| 9.9.3 | Closed Loops |
-| 9.9.2 | Artifact Trust |
-| 9.9.1 | Clean Foundations |
-| 9.9.0 | Fail-Closed Trust |
-| 9.8.0 | Honest Knowledge Pipeline |
-| 9.7.0 | Proactive Hybrid Brain |
-| 9.6.0 | Trusted Agent Loop |
-| 9.5.0 | Command Center |
-| 9.4.0 | Question-Driven Everyday Automation |
-| 9.3.0 | Proactive Brain Intelligence |
-| 9.2.0 | Model-Agnostic File Generation |
-| 9.1.0 | Code Review Completion & Fail-Closed Runtime |
-| 9.0.0 | Code Review Closure & Runtime Cleanup |
 
 Per-release details: [RELEASE_NOTES.md](RELEASE_NOTES.md)
-
-## Documentation
-
-- [docs/WHY_LATTICE.md](docs/WHY_LATTICE.md) — product philosophy
-- [docs/TRUST_MODEL.md](docs/TRUST_MODEL.md) — local-first trust model
-- [PRIVACY.md](PRIVACY.md) — privacy and external communication policy
-- [FEATURE_STATUS.md](FEATURE_STATUS.md) — feature status and limitations
-- [SECURITY.md](SECURITY.md) — security posture
-- [RELEASE.md](RELEASE.md) — release guide and notes
-
-## License
-
-MIT. See [LICENSE](LICENSE).

package/bin/ltcai.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
-const { spawn } = require("node:child_process");
-const { spawnSync } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
@@ -11,6 +10,34 @@ const managedVenv = process.env.LTCAI_NPM_VENV || path.join(os.homedir(), ".ltca
 const managedPython = process.platform === "win32"
   ? path.join(managedVenv, "Scripts", "python.exe")
   : path.join(managedVenv, "bin", "python");
+const hostName = process.platform === "win32" ? "lattice-host.exe" : "lattice-host";
+const WORKER_MODULE = "latticeai.worker_app";
+// Mirrors rust/lattice-host/src/supervisor/command.rs::WORKER_FACTORY — the
+// supervisor appends `--host`/`--port` itself, so this is the whole of what a
+// launcher can name.
+const WORKER_FACTORY = `-m uvicorn ${WORKER_MODULE}:create_worker_app --factory`;
+
+const USAGE = `\
+ltcai — Lattice AI front door (lattice-host)
+
+USAGE:
+    ltcai [OPTIONS]
+    ltcai doctor
+
+OPTIONS:
+    --host <HOST>          Bind hint (sets LATTICEAI_HOST). lattice-host listens on 127.0.0.1
+    --port <PORT>          Gateway port (default: LATTICEAI_PORT, then 4825)
+    --worker-port <PORT>   Pin the worker port instead of scanning
+    --no-spawn             Do not start a worker; front an existing one
+    --no-jobs              Mount /host/jobs but never run the timer
+    -h, --help             Print this help
+    -V, --version          Print the version
+
+lattice-host is the only front door. It supervises the Python AI worker
+(\`python ${WORKER_FACTORY}\`, with the port it chose).
+LATTICEAI_* environment variables are passed through. Pin the host binary with
+LATTICEAI_HOST_BIN or LTCAI_HOST, and the worker interpreter with LTCAI_PYTHON.
+`;
 
 function loadDotEnv(file) {
   if (!fs.existsSync(file)) return;
@@ -61,7 +88,7 @@ function ensureManagedPython() {
   if (!canImport(managedPython, "fastapi")) {
     const requirements = path.join(root, "requirements.txt");
     if (!fs.existsSync(requirements)) {
-      console.error(`[LTCAI] Missing ${requirements}. The npm package is incomplete and cannot start the Python server.`);
+      console.error(`[LTCAI] Missing ${requirements}. The npm package is incomplete and cannot start the Python worker.`);
       process.exit(1);
     }
     console.log("[LTCAI] Installing Python dependencies. This can take a few minutes on first run.");
@@ -72,34 +99,217 @@ function ensureManagedPython() {
   return managedPython;
 }
 
-const bootstrappedPython = ensureManagedPython();
-const candidates = [
-  process.env.LTCAI_PYTHON,
-  bootstrappedPython,
-  path.join(root, ".venv", "bin", "python"),
-  path.join(root, "venv", "bin", "python"),
-  process.env.PYTHON,
-  "python3",
-  "python",
-].filter(Boolean);
-
-function run(index) {
-  const python = candidates[index];
-  if (!python) {
-    console.error("Could not find Python. Install Python 3.11+ and try again.");
+function pythonCandidates(includeManaged) {
+  return [
+    process.env.LTCAI_PYTHON,
+    includeManaged ? ensureManagedPython() : managedPython,
+    path.join(root, ".venv", "bin", "python"),
+    path.join(root, "venv", "bin", "python"),
+    process.platform === "win32" ? path.join(root, ".venv", "Scripts", "python.exe") : null,
+    process.env.PYTHON,
+    "python3",
+    "python",
+  ].filter(Boolean);
+}
+
+function resolveWorkerPython(bootstrap) {
+  for (const python of pythonCandidates(bootstrap)) {
+    if (canImport(python, WORKER_MODULE)) return python;
+  }
+  return pythonCandidates(bootstrap)[0] || "python3";
+}
+
+function whichHost() {
+  const tool = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(tool, ["lattice-host"], { encoding: "utf8" });
+  if (result.status !== 0) return null;
+  const found = String(result.stdout || "").split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+  return found && fs.existsSync(found) ? found : null;
+}
+
+function existingHostBinary() {
+  const pinned = process.env.LATTICEAI_HOST_BIN || process.env.LTCAI_HOST;
+  if (pinned && fs.existsSync(pinned)) return pinned;
+  const candidates = [
+    path.join(root, "rust", "target", "release", hostName),
+    path.join(root, "rust", "target", "debug", hostName),
+    path.join(root, "src-tauri", "target", "release", hostName),
+    path.join(root, "src-tauri", "target", "debug", hostName),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return whichHost();
+}
+
+function ensureHostBinary() {
+  const existing = existingHostBinary();
+  if (existing) return existing;
+  if (process.env.LTCAI_SKIP_HOST_BUILD === "1") {
+    console.error("[LTCAI] lattice-host binary not found and LTCAI_SKIP_HOST_BUILD=1.");
+    process.exit(1);
+  }
+  const manifest = path.join(root, "rust", "Cargo.toml");
+  if (!fs.existsSync(manifest)) {
+    console.error("[LTCAI] lattice-host binary not found and rust/ workspace is missing.");
+    process.exit(1);
+  }
+  console.log("[LTCAI] Building lattice-host (cargo build -p lattice-host)...");
+  if (!runSync("cargo", ["build", "-p", "lattice-host"], { cwd: path.join(root, "rust") })) {
+    console.error("[LTCAI] cargo build -p lattice-host failed.");
+    process.exit(1);
+  }
+  const built = path.join(root, "rust", "target", "debug", hostName);
+  if (!fs.existsSync(built)) {
+    console.error(`[LTCAI] build succeeded but ${built} is missing.`);
     process.exit(1);
   }
+  return built;
+}
 
-  const child = spawn(python, ["-m", "latticeai.cli.entrypoint", ...process.argv.slice(2)], {
-    cwd: root,
-    stdio: "inherit",
-  });
+function parseArgs(argv) {
+  const parsed = {
+    help: false,
+    version: false,
+    doctor: false,
+    host: null,
+    port: null,
+    hostArgs: [],
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "doctor") {
+      parsed.doctor = true;
+      continue;
+    }
+    if (arg === "-h" || arg === "--help") {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === "-V" || arg === "--version") {
+      parsed.version = true;
+      continue;
+    }
+    if (arg === "--host" || arg.startsWith("--host=")) {
+      parsed.host = arg === "--host" ? argv[++i] : arg.slice("--host=".length);
+      continue;
+    }
+    if (arg === "--port" || arg.startsWith("--port=")) {
+      parsed.port = arg === "--port" ? argv[++i] : arg.slice("--port=".length);
+      if (parsed.port) parsed.hostArgs.push("--port", parsed.port);
+      continue;
+    }
+    if (arg === "--reload" || arg === "--tunnel") {
+      console.error(`[LTCAI] ${arg} is not supported on the lattice-host front door.`);
+      continue;
+    }
+    parsed.hostArgs.push(arg);
+  }
+  return parsed;
+}
+
+/**
+ * The interpreter, as an absolute path.
+ *
+ * `lattice-host` spawns the worker with `PATH` prefixed by
+ * `/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin`
+ * (supervisor/worker_env.rs — GUI processes inherit a minimal PATH), so a bare
+ * `python3` is looked up against a different PATH than the one this launcher
+ * validated it on and can land on an interpreter with none of the deps.
+ * `sys.executable` is what keeps it the same interpreter on both sides.
+ */
+function absoluteInterpreter(python) {
+  const probe = spawnSync(python, ["-c", "import sys; print(sys.executable)"], { encoding: "utf8" });
+  const resolved = probe.status === 0 ? String(probe.stdout || "").trim() : "";
+  return resolved && fs.existsSync(resolved) ? resolved : python;
+}
+
+/**
+ * Tell the supervisor *which interpreter*, and let it build the command.
+ *
+ * This used to pin `LATTICEAI_DESKTOP_BACKEND_CMD = "<python> -m
+ * latticeai.worker_app"`, and that command serves nothing: `worker_app` exports
+ * `main()` but has no `if __name__ == "__main__"` guard, so the module form
+ * imports and exits 0 without binding a port — the supervisor restarts it,
+ * forever, and the front door answers 502 on every proxied route.
+ *
+ * The fix is not to pin the uvicorn string instead. `LATTICEAI_DESKTOP_BACKEND_CMD`
+ * is the supervisor's rule 1, whose args are passed **verbatim**; `--host` and
+ * `--port` are appended only by the module rules (`command.rs::module_args`),
+ * and the worker port is chosen at runtime by a free-port scan. A statically
+ * pinned `-m uvicorn … --factory` would therefore bind uvicorn's default 8000
+ * while the supervisor health-probes the port it actually picked.
+ *
+ * So pin the input the launcher genuinely knows — the interpreter — and let
+ * rule 2 produce its own canonical command (`command.rs::WORKER_FACTORY`):
+ * `<python> -m uvicorn latticeai.worker_app:create_worker_app --factory --host
+ * 127.0.0.1 --port <chosen>`. An explicit `LATTICEAI_DESKTOP_BACKEND_CMD` from
+ * the caller still wins, untouched.
+ */
+function pinWorkerInterpreter() {
+  if (process.env.LATTICEAI_DESKTOP_BACKEND_CMD) return;
+  process.env.LTCAI_PYTHON = absoluteInterpreter(resolveWorkerPython(true));
+}
+
+function doctor() {
+  let ok = true;
+  const host = existingHostBinary();
+  if (host) {
+    console.log(`[OK] lattice-host: ${host}`);
+  } else {
+    console.log("[MISS] lattice-host: not built (run without doctor to cargo-build it)");
+    ok = false;
+  }
+  const python = absoluteInterpreter(resolveWorkerPython(false));
+  if (canImport(python, WORKER_MODULE)) {
+    console.log(`[OK] worker: ${python} ${WORKER_FACTORY}`);
+  } else {
+    console.log(`[MISS] worker: cannot import ${WORKER_MODULE} (${python})`);
+    ok = false;
+  }
+  process.exit(ok ? 0 : 1);
+}
 
-  child.on("error", () => run(index + 1));
+function launchHost(bin, args) {
+  const child = spawn(bin, args, { cwd: root, stdio: "inherit" });
+  child.on("error", (err) => {
+    console.error(`[LTCAI] failed to launch lattice-host (${bin}): ${err.message}`);
+    process.exit(1);
+  });
   child.on("exit", (code, signal) => {
     if (signal) process.kill(process.pid, signal);
     process.exit(code ?? 0);
   });
 }
 
-run(0);
+const parsed = parseArgs(process.argv.slice(2));
+
+if (parsed.help) {
+  process.stdout.write(USAGE);
+  const host = existingHostBinary();
+  if (host) {
+    process.stdout.write("\n");
+    spawnSync(host, ["--help"], { stdio: "inherit" });
+  }
+  process.exit(0);
+}
+
+if (parsed.version) {
+  const host = existingHostBinary();
+  if (host) {
+    spawnSync(host, ["--version"], { stdio: "inherit" });
+  } else {
+    console.log("ltcai (lattice-host front door)");
+  }
+  process.exit(0);
+}
+
+if (parsed.doctor) {
+  doctor();
+}
+
+if (parsed.host) process.env.LATTICEAI_HOST = parsed.host;
+if (parsed.port) process.env.LATTICEAI_PORT = parsed.port;
+
+pinWorkerInterpreter();
+launchHost(ensureHostBinary(), parsed.hostArgs);