theus-cli 0.2.59 → 0.2.63

package/README.md

@@ -31,7 +31,7 @@ curl -fsSL https://theus.pe/install.sh | bash
 theus --version
 ```
 
-El instalador detecta tu plataforma (macOS/Linux, x64/arm64), descarga el tarball del último release (primario desde `theus.pe/dl`, con GitHub Releases como respaldo — el repo es privado), lo instala en `~/.theus/app` y enlaza `theus` en tu PATH. Es idempotente: para actualizar, vuelve a ejecutarlo.
+El instalador detecta tu plataforma (macOS/Linux, x64/arm64), descarga el tarball del último release (primario desde `theus.pe/dl`, con GitHub Releases como respaldo — el repo es privado), lo instala en `~/.theus/app` y enlaza `theus` en tu PATH. Es idempotente: para actualizar, vuelve a ejecutarlo. En **Windows** usa el instalador nativo (instala también Ñaupa): `powershell -c "irm https://theus.pe/install.ps1 | iex"`.
 
 **Alternativa vía npm** (también requiere Bun):
 
@@ -89,9 +89,53 @@ O define proveedores en `~/.theus/providers.json`:
 | `THEUS_NO_PROJECT_INTELLIGENCE=1` | no levanta índice/API/dashboard |
 | `THEUS_NO_OPEN_DASHBOARD=1` | levanta la API sin abrir el navegador |
 | `PROJECT_API_PORT` / `INDEX_MAX_FILES` | puerto local / límite de archivos indexados |
+| `THEUS_TITAN_CONTROL_PLANE_URL` / `THEUS_TITAN_CONTROL_PLANE_API_KEY` | activa el ledger de orquestación TITAN; ambos son obligatorios |
+| `THEUS_TITAN_CONTROL_PLANE_TIMEOUT_MS` | timeout total de reportes y reintentos idempotentes |
+| `THEUS_TITAN_TASK_TIMEOUT_SECONDS` | deadline real de tarea, verificación e integración |
+| `THEUS_TITAN_FLEET_URL` / `THEUS_TITAN_FLEET_REGISTRATION_TOKEN` | habilita únicamente el comando explícito `fleet-worker`; no afecta el arranque normal |
 
 ---
 
+### Orquestación TITAN y worktrees
+
+El control-plane de programación es opt-in y no es necesario para usar Theus
+localmente. Las URLs remotas deben usar HTTPS; sólo los loopbacks aceptan HTTP.
+Con TITAN activo, un worktree se integra al padre después de
+`integration.started` y sólo bajo `acceptEdits` o `bypassPermissions`. Conflicto,
+dirty solapado, cancelación o timeout fallan cerrados, conservan el worktree y
+no sobrescriben cambios del usuario. La referencia operativa, variables, retry,
+rollback y smoke están en [THEUS.md](./THEUS.md#control-plane-de-orquestación-titan-opt-in).
+
+### Worker distribuido TITAN Fleet
+
+`theus fleet-worker` conecta una máquina a la cola durable compartida por CLI,
+Chat y Enterprise. Es headless y opt-in: rota su token de worker, reclama jobs
+por lease cercado, mantiene heartbeats independientes y ejecuta el runtime
+agentic real de Theus dentro del workspace o un worktree. `SIGINT`/`SIGTERM`
+activa draining, libera jobs todavía no iniciados y espera las ejecuciones en
+curso dentro de un grace period.
+
+```bash
+export THEUS_TITAN_FLEET_URL="https://theus.pe"
+export THEUS_TITAN_FLEET_REGISTRATION_TOKEN="..." # nunca usar un argumento CLI
+export THEUS_TITAN_FLEET_WORKSPACE="/ruta/al/proyecto"
+theus fleet-worker --queues default --max-concurrency 2
+```
+
+Las credenciales rotadas se guardan atómicamente en
+`~/.theus/titan/fleet-worker.json` con modo `0600`. Un `409 stale_lease`
+descarta el resultado y nunca lo publica como propio. La referencia completa de
+variables, seguridad y operación está en
+[THEUS.md](./THEUS.md#worker-distribuido-titan-fleet-opt-in).
+Antes de integrar un worktree o enviar `complete`/`fail`, el worker persiste un
+outbox terminal atómico `0600`. Un ACK perdido conserva el mismo payload,
+fencing token y `completion_key`; al reiniciar se reproduce antes de aceptar
+otro claim. Sólo un rechazo `stale_lease` definitivo autoriza rollback.
+Los workers `platform` son sólo lectura por defecto; cualquier capacidad
+privilegiada requiere HTTPS y una allowlist explícita de queues, sin comodines.
+Los jobs con capacidad de escritura siempre se ejecutan en worktree; nunca
+mutan directamente el workspace.
+
 ## 📊 Dashboard e inteligencia local
 
 Al iniciar dentro de un proyecto, el servicio de inteligencia local indexa archivos, extrae símbolos, construye el grafo, detecta esquemas SQL/Prisma, guarda índice y memoria en `~/.theus/knowledge/` y expone un dashboard en `127.0.0.1`:
@@ -107,10 +151,12 @@ Al iniciar dentro de un proyecto, el servicio de inteligencia local indexa archi
 Si el binario [`naupa`](https://theus.pe/naupa/) está instalado, Theus lo monta **automáticamente** como servidor MCP (`theus-naupa`) en cada sesión: grafo de conocimiento AST del proyecto (tree-sitter, 158 lenguajes), cadenas de llamadas, consultas Cypher y análisis de impacto en <1 ms — el agente consulta la estructura antes de recurrir a grep/read.
 
 ```bash
-curl -fsSL https://theus.pe/naupa.sh | bash   # instalar Ñaupa
+curl -fsSL https://theus.pe/naupa.sh | bash   # instalar Ñaupa (macOS/Linux)
 THEUS_NO_NAUPA=1 theus                        # kill-switch por sesión
 ```
 
+En Windows no hace falta comando aparte: el instalador oficial (`powershell -c "irm https://theus.pe/install.ps1 | iex"`) instala también Ñaupa con la UI 3D. (En PowerShell `curl` es un alias de `Invoke-WebRequest`; los comandos `curl … | bash` son solo para macOS/Linux.)
+
 Las tools de lectura (`search_graph`, `trace_path`, `query_graph`, `get_architecture`, …) van pre-permitidas; las que escriben (`index_repository`, `delete_project`, …) pasan por el flujo de permisos normal. Caché en `~/.theus/naupa/`. Código: `services/mcpNaupa/`. Docs: [theus.pe/docs/naupa](https://theus.pe/docs/naupa).
 
 ---
@@ -197,10 +243,37 @@ Este CLI es una reconstrucción de un agente upstream: varios invariantes de bui
 
 ```bash
 bun run scripts/release.ts --tag vX.Y.Z    # genera dist/release/* + SHA256SUMS
+bun run release:native --tag vX.Y.Z        # candidatos nativos + manifiesto
+bun run release:msix -- --help              # paquete Windows para Partner Center
 ```
 
 Luego: sube `dist/release/*` a `/var/www/theus.pe/dl/` (y `/dl/vX.Y.Z/`), crea el release en GitHub (`MarketrixPE/theuscode`), y publica en npm (`theus-cli`; requiere OTP salvo con token de automatización). El paquete npm contiene el bundle compilado, el launcher, el logo oficial requerido por el dashboard y el README: **no expone la fuente privada**.
 
+El release canónico sigue siendo el bundle firmado por checksum que usa el
+instalador oficial. `release:native` produce ejecutables autónomos para macOS
+ARM64/x64, Linux ARM64/x64 y Windows x64, valida su formato y genera
+`SHA256SUMS` + `RELEASE-MANIFEST.json`. Esos binarios nacen con
+`publishable:false`: antes de publicarlos deben completarse sus gates de
+distribución. macOS se firma/notariza y repite los smokes en runners nativos.
+Windows repite los smokes sobre el PE real y se empaqueta como MSIX; Microsoft
+Store firma ese paquete durante la certificación. El `.exe` sin firma no se
+publica como descarga estable.
+
+El workflow de release prepara `theus-cli-vX.Y.Z.tar.gz`,
+`theus-cli.tar.gz`, los cuatro tarballs Unix y un MSIX Windows privado para
+Partner Center. GitHub queda en borrador hasta que Microsoft certifique/firme
+el MSIX; sólo entonces se coordinan GitHub, npm y `theus.pe/dl`. Si falta una
+firma, notarización, identidad Store o smoke nativo, no crea una publicación
+pública.
+
+La suite completa, el typecheck y el bundle portable se validan una vez en el
+gate canónico de Linux. Los cuatro targets Unix compilan y ejecutan su binario
+en el runner nativo. Windows x64 baseline se compila con el mismo Bun fijado
+desde Linux y el PE resultante se transfiere al runner Windows, donde ejecuta
+`--version`, `--help` y `fleet-worker --help` antes de empaquetarse como MSIX.
+Así no se omite ninguna prueba y tampoco se fuerzan sobre Windows pruebas
+internas que validan permisos POSIX o scripts de shell.
+
 ---
 
 ## 📖 Docs adicionales del subproyecto