ltcai 11.5.2 → 11.7.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.2 Living Brain walkthrough](output/release/v11.5.2/gifs/v11.5.2-living-brain-walkthrough.gif)
+![v11.7.0 Living Brain walkthrough](output/release/v11.7.0/gifs/v11.7.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.2/screenshots/13-chronicle.png) | **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v11.5.2/screenshots/04-brain-chat-home.png) |
-| **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v11.5.2/screenshots/05-memory-graph.png) | **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v11.5.2/screenshots/06-capture.png) |
-| **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v11.5.2/screenshots/12-review-center.png) | **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v11.5.2/screenshots/02-recommended-models.png) |
-| **Watch a file become memory** — three named steps, not a pipeline diagram ![Material to memory](output/release/v11.5.2/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.2/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.7.0/screenshots/13-chronicle.png) | **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v11.7.0/screenshots/04-brain-chat-home.png) |
+| **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v11.7.0/screenshots/05-memory-graph.png) | **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v11.7.0/screenshots/06-capture.png) |
+| **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v11.7.0/screenshots/12-review-center.png) | **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v11.7.0/screenshots/02-recommended-models.png) |
+| **Watch a file become memory** — three named steps, not a pipeline diagram ![Material to memory](output/release/v11.7.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.7.0/screenshots/08-system.png) |
 
 ## Why Lattice AI
 
@@ -58,103 +58,81 @@ First-run flow — wake the Brain, pick the owner, load a recommended model:
 
 | | | |
 | --- | --- | --- |
-| ![Login](output/release/v11.5.2/screenshots/01-login.png) | ![Model install](output/release/v11.5.2/screenshots/03-install-load-progress.png) | ![Model library](output/release/v11.5.2/screenshots/07-model-library.png) |
+| ![Login](output/release/v11.7.0/screenshots/01-login.png) | ![Model install](output/release/v11.7.0/screenshots/03-install-load-progress.png) | ![Model library](output/release/v11.7.0/screenshots/07-model-library.png) |
 
 Screenshot index and capture notes:
-[output/release/v11.5.2/SCREENSHOT_INDEX.md](output/release/v11.5.2/SCREENSHOT_INDEX.md)
+[output/release/v11.7.0/SCREENSHOT_INDEX.md](output/release/v11.7.0/SCREENSHOT_INDEX.md)
 
 ## Current Release
 
-The current release is **11.5.2 — Tight Ship**:
-
-A cleanup-and-correctness release built from three audits of the settled
-11.5.1 tree — a Rust↔Python duplication map, an arc-level dead-code and
-test audit, and a live front-door parity sweep across 192 endpoints
-(gateway vs. direct worker). The duplication map's verdict was that the
-boundary itself is sound: **zero cross-boundary deletions**, because every
-twin is either the live Python-direct surface or a copy pinned by a parity
-golden. The real duplication was inside each language, and that is what
-this release removes.
-
-- **About 1,100 lines gone.** Six moved-module shims, a multimodal
-  streaming seam that was never wired, roughly 27 zero-caller symbols
-  whose only callers were their own tests, an interface method
-  (`metadata_for`) no consumer ever called, a dead measurement script,
-  and the **legacy Electron shell** — superseded by Tauri, yet still
-  shipping inside the npm tarball. Every deletion came with per-assertion
-  test surgery so the 100% line **and** branch floor never moved, and a
-  new guard forbids the `sys.modules[__name__]` shim pattern from coming
-  back. The 183 coverage work-package test files were all verified
-  load-bearing (ten of them are the sole owners of 79 branch arcs); seven
-  coverage-redundant feature tests were deliberately kept for their
-  regression value.
-- **One home per thing.** The byte-identical embedder pair is
-  single-sourced on the golden-pinned copy — silent vector drift between
-  two write paths was the failure mode. The workspace selector's four
-  verbatim re-derivations now use the canonical rule, an intended
-  behaviour change: chat, agent, upload, computer-use and admin **403 on
-  disagreement** where the copies silently preferred the header. sha256,
-  SSE frame builders, the data-dir default, the mode services and the
-  module-importability probe each collapsed to one implementation, and
-  seven byte-identical Rust copies were consolidated (including a
-  wholesale duplicate of `clock.rs`).
-- **The front door, fixed with live before/after proof.** Proxied
-  redirects now pass through with `Set-Cookie` and `Location` intact —
-  the invite gate was a hard dead-end, SSO login silently never
-  authenticated, and twelve deep links lost their fragment. Absolute
-  `Location` values naming the internal worker are rewritten to the
-  gateway origin. The native `/rust/*` and `/host/status|jobs` lanes are
-  **posture-gated fail-closed**: they used to serve the whole graph
-  unauthenticated while the worker required auth. `X-Forwarded-For/Proto/
-  Host` cross the hop and are honoured only from a loopback or listed
-  trusted-proxy peer, which fixes `--no-spawn` CSRF refusals and the
-  invite links, notifications and SSO URLs that named the internal worker
-  port. The supervisor injects CORS origins alongside the CSRF ones,
-  stale `ws://` CSP entries are gone, and the Tauri shell no longer
-  navigates to a dead origin when the gateway fails to bind.
-- **What the audits surfaced.** `POST /api/search/graph` was allow-listed
-  but unreachable until now; `GET /api/ingestion/multimodal` was
-  documented but unwired. Two golden families were added: a `recent_chat`
-  family pinning the `build_recent_chat_context` the live `/chat` path
-  actually calls — it caught a real divergence, where Python's `limit=0`
-  tail slice keeps everything and Rust returned empty (**Python is the
-  reference; Rust was fixed**) — plus `document_targets` and
-  `agent_profiles` helper goldens, 97 rows. The corpus stands at **251
-  golden files**.
-- **The boundaries, stated plainly.** The native lanes are an
-  open-posture, single-local-owner surface (a closed or unknown posture
-  answers 401). The recent-chat context seam is still owned by the ad-hoc
-  prepends in `/chat` rather than the assembler — wiring it changes the
-  shape of a live prompt, which is a minor-release item, not something to
-  ship quietly here. `workspace_scope_from_request` itself remains
-  lenient for its two remaining callers. And the proxy hop deliberately
-  carries no request timeout: a blanket timeout would kill long-lived SSE.
-
-The floor holds: **7,022 Python tests (11 skipped) at 100.00% statement
-and branch coverage — 40,307 statements, 10,970 branches, `fail_under=100`
-with the pragma budget untouched — 1,761 frontend tests across 101 files
-at 100% on all four metrics, and 760 Rust workspace tests**, with the
-OpenAPI schema regenerated at 421 paths and the whole suite re-verified in
-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.2 release must use exact filenames:
-
-- `dist/ltcai-11.5.2-py3-none-any.whl`
-- `dist/ltcai-11.5.2.tar.gz`
-- `ltcai-11.5.2.tgz`
-- `dist/ltcai-11.5.2.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_11.5.2_aarch64.dmg`
+The current release is **11.7.0 — Clean Sweep**:
+
+11.6.0 left a disclosed backlog and a visual language that still used
+glass. This release closes that backlog, fixes regressions One Door did
+not know it had shipped, and restyles every captured surface on an
+elevation ladder — ink night, paper day, no glass. The door is unchanged:
+`lattice-host` still serves **420 operations across 41 route families**,
+and the Python package is still a **28-route AI worker** (LLM, embed,
+extract, parse, four renderers, ASR, multimodal, catalog, `sysinfo`,
+`/health`). The allowlist still includes `/worker/parse` and
+`/worker/render/*`; nothing product-shaped moved back into Python.
+
+- **The three oracle bugs 11.6.0 ported as-is are fixed.** Command-search
+  knowledge now reads `matches` and returns nodes. Review snooze accepts
+  offset-aware datetimes (unparseable `until` → 422). Double-reject is
+  409, byte-identical to its dismiss sibling. Fixture bodies that pinned
+  the old faults were updated and marked as divergences from the oracle.
+- **The §5.3 holes are closed.** Binary uploads go through `/worker/parse`.
+  Per-chunk supplied vectors land at the four ingest doors. User hooks
+  fire on native tools (`HooksStore` → `HookSink`) and write the same run
+  log the HTTP route writes. `sanitize_write_content` runs on the loop
+  path and on `POST /tools/write_file`. Every mutating review route records
+  `review_item_created` / `review_item_updated`. `workspace_os.json` has
+  one writer (`WorkspaceOsStore` + registry + ports).
+- **Regressions One Door did not know it had.** Self-Model writes were
+  100% dead (five routes posted into the retired `/worker/graph/mutate`;
+  `resolve_contradiction` claimed "applied" while writing nothing) —
+  restored natively, nine recorded bodies byte-identical. The security
+  xlsx export 502'd because it posted to a product route; it now uses
+  `/worker/render/xlsx`. Chat `ingest_generated` was a schema 400 even
+  against a live 11.5.2 worker. Vault-watch had fixtures and no poller —
+  it is a real native ingest loop now. A decoy-proven static gate keeps
+  this class from shipping again.
+- **Time bombs defused.** Chronicle `@today`, briefing freshness, and the
+  insights/garden/proactive/health/quality cutoffs now take a frozen
+  clock. Falsifier tests fail on the next run if a fuse is re-armed.
+- **The UI is one language.** Token-native elevation and gradients replace
+  backdrop-filter. Cytoscape reads theme tokens (comma-form `hsl()`).
+  Layout and a11y contracts stay; the first-paint bundle is still ~103 KiB
+  gzip.
+
+What this release still carries openly — `open_keys` pending-only, no
+extraction refiner, `delete_node` leaving `PART_OF`, review events silent
+without an owner, text-only KG-api ingest, two store cycles per review
+mutation, raw-English snooze 422 — is listed in
+[RELEASE_NOTES_v11.7.0.md](RELEASE_NOTES_v11.7.0.md).
+
+Expected artifacts for 11.7.0 release must use exact filenames:
+
+- `dist/ltcai-11.7.0-py3-none-any.whl`
+- `dist/ltcai-11.7.0.tar.gz`
+- `ltcai-11.7.0.tgz`
+- `dist/ltcai-11.7.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_11.7.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
@@ -164,22 +142,38 @@ 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).
+- Pointer-control tools still execute in the worker. Remaining honest gaps
+  (`open_keys` pending-only, no Self-Model refiner, `PART_OF` left on
+  delete, review events silent without an owner, KG-api ingest text-only,
+  two store cycles per review mutation) are listed with their reasons in
+  [RELEASE_NOTES_v11.7.0.md](RELEASE_NOTES_v11.7.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.7.0 | Clean Sweep |
+| 11.6.0 | One Door |
 | 11.5.2 | Tight Ship |
 | 11.5.1 | Rust Full Loop |
 | 11.5.0 | Rust Complete |
@@ -189,54 +183,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);