Release v3.8.9

.agents/skills/deploy-vps-akamai-cc/SKILL.md

@@ -5,36 +5,102 @@ description: Deploy the latest OmniRoute code to the Akamai VPS (69.164.221.35)
 
 # Deploy to Akamai VPS Workflow
 
-Deploy OmniRoute to the Akamai VPS using `npm pack + scp` + PM2.
+Deploy OmniRoute to the Akamai VPS using a clean `build:release` + `rsync` + PM2 restart.
 
 **Akamai VPS:** `69.164.221.35`
 **Process manager:** PM2 (`omniroute`)
 **Port:** `20128`
+**Remote install dir:** `/usr/lib/node_modules/omniroute/app/` (VPS image dir — unchanged)
+
+> [!IMPORTANT]
+> **Build must run where `node_modules` is REAL.** A git worktree with symlinked
+> `node_modules` breaks the Next.js standalone assembly. Always build from the main
+> checkout (or an `npm ci`'d worktree), never from `OmniRoute-*` worktrees unless
+> you first ran `npm ci` inside them.
 
 ## Steps
 
-### 1. Build + pack locally
+### 1. Clean build + sentinel
+
+Run from a checkout with a **real** `node_modules`:
 
 // turbo
 
 ```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
+cd /home/diegosouzapw/dev/proxys/OmniRoute && npm run build:release
+```
+
+`build:release` does:
+1. Deletes `.build/` and `dist/` (clean rebuild — no stale cache)
+2. Runs `next build` → `.build/next/` (intermediates)
+3. Assembles the shippable bundle into `dist/` via `assembleStandalone`
+4. Writes `dist/BUILD_SHA` = `git rev-parse --short HEAD` (deploy sentinel)
+
+Verify the sentinel before shipping:
+
+```bash
+cat /home/diegosouzapw/dev/proxys/OmniRoute/dist/BUILD_SHA && git -C /home/diegosouzapw/dev/proxys/OmniRoute rev-parse --short HEAD
 ```
 
-### 2. Copy to Akamai VPS and install
+Both lines must match. If they differ, the build is stale — re-run `build:release`.
+
+### 2. Back up the running bundle on the VPS
+
+```bash
+OMNIROUTE_VERSION=$(node -p "require('/home/diegosouzapw/dev/proxys/OmniRoute/package.json').version")
+ssh root@69.164.221.35 "cp -a /usr/lib/node_modules/omniroute/app /usr/lib/node_modules/omniroute/app.bak-${OMNIROUTE_VERSION}"
+```
+
+### 3. Stop the process, then rsync `dist/` → remote `app/`
+
+The VPS image directory is still named `app/`; we ship the **contents** of our local `dist/`. **Stop the running process FIRST** so `rsync --delete` never removes chunk files out from under the live server — that race produces the transient `[Shutdown] Cannot find module ./chunks/NNNNN.js` seen mid-deploy:
 
 // turbo-all
 
 ```bash
-scp omniroute-*.tgz root@69.164.221.35:/tmp/
+ssh root@69.164.221.35 "pm2 stop omniroute"
+rsync -az --delete /home/diegosouzapw/dev/proxys/OmniRoute/dist/ root@69.164.221.35:/usr/lib/node_modules/omniroute/app/
 ```
 
+### 4. Start + health check
+
+`pm2 restart` on a stopped app starts it again with a clean module graph:
+
 ```bash
-ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
+ssh root@69.164.221.35 "pm2 restart omniroute --update-env && pm2 save"
 ```
 
-### 3. Verify the deployment
+```bash
+sleep 5 && curl -sf http://69.164.221.35:20128/api/monitoring/health | jq '{status:.status, version:.version}'
+```
+
+Expected: HTTP 200, `"status": "ok"` (or equivalent health payload).
+
+### 5. Verify the deployment
 
 ```bash
 curl -s -o /dev/null -w 'AKAMAI HTTP %{http_code}\n' http://69.164.221.35:20128/
 ```
+
+## Rollback
+
+If the health check fails, restore the backup:
+
+```bash
+OMNIROUTE_VERSION=$(node -p "require('/home/diegosouzapw/dev/proxys/OmniRoute/package.json').version")
+ssh root@69.164.221.35 "rm -rf /usr/lib/node_modules/omniroute/app && cp -a /usr/lib/node_modules/omniroute/app.bak-${OMNIROUTE_VERSION} /usr/lib/node_modules/omniroute/app && pm2 restart omniroute --update-env"
+```
+
+## Gotchas
+
+- **Never build in a worktree with symlinked `node_modules`** — the standalone copy step
+  follows symlinks and produces a broken bundle. Use the main checkout or run `npm ci`
+  inside the worktree first.
+- **`pm2 restart --update-env` does NOT re-read `ecosystem.config.cjs`** — if you changed
+  env vars in the ecosystem file, use `pm2 reload` or `pm2 delete + pm2 start` instead.
+- **Parallel dev + release builds**: to avoid clobbering the dev server's `.build/next`,
+  pass `NEXT_DIST_DIR=.build/next-release` to `build:release` in CI or concurrent deploys:
+  `NEXT_DIST_DIR=.build/next-release npm run build:release`
+  then adjust the rsync source to `dist-release/` (or whatever `build:release` assembles into).
+- **`dist/BUILD_SHA` must match the deployed HEAD** — always confirm before rsyncing.
+  A mismatch means the build ran from a dirty or incorrect commit.

.agents/skills/deploy-vps-both-cc/SKILL.md

@@ -5,46 +5,118 @@ description: Deploy the latest OmniRoute code to BOTH the Akamai VPS and the Loc
 
 # Deploy to VPS (Both) Workflow
 
-Deploy OmniRoute to the production VPSs using `npm pack + scp` + PM2.
+Deploy OmniRoute to both production VPSs using a clean `build:release` + `rsync` + PM2 restart.
 
 **Akamai VPS:** `69.164.221.35`
 **Local VPS:** `192.168.0.15`
 **Process manager:** PM2 (`omniroute`)
 **Port:** `20128`
-**PM2 entry:** `/usr/lib/node_modules/omniroute/app/server.js`
+**Remote install dir:** `/usr/lib/node_modules/omniroute/app/` (VPS image dir — unchanged)
 
 > [!IMPORTANT]
-> The npm registry rejects packages > 100MB, so deployment uses **npm pack + scp**.
+> **Build must run where `node_modules` is REAL.** A git worktree with symlinked
+> `node_modules` breaks the Next.js standalone assembly. Always build from the main
+> checkout (or an `npm ci`'d worktree), never from `OmniRoute-*` worktrees unless
+> you first ran `npm ci` inside them.
 
 ## Steps
 
-### 1. Build + pack locally
+### 1. Clean build + sentinel
+
+Build **once** locally — the same `dist/` is shipped to both VPSs:
 
 // turbo
 
 ```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
+cd /home/diegosouzapw/dev/proxys/OmniRoute && npm run build:release
 ```
 
-### 2. Copy to both VPS and install
+`build:release` does:
+1. Deletes `.build/` and `dist/` (clean rebuild — no stale cache)
+2. Runs `next build` → `.build/next/` (intermediates)
+3. Assembles the shippable bundle into `dist/` via `assembleStandalone`
+4. Writes `dist/BUILD_SHA` = `git rev-parse --short HEAD` (deploy sentinel)
+
+Verify the sentinel before shipping:
+
+```bash
+cat /home/diegosouzapw/dev/proxys/OmniRoute/dist/BUILD_SHA && git -C /home/diegosouzapw/dev/proxys/OmniRoute rev-parse --short HEAD
+```
+
+Both lines must match. If they differ, the build is stale — re-run `build:release`.
+
+### 2. Back up the running bundle on both VPSs
+
+```bash
+OMNIROUTE_VERSION=$(node -p "require('/home/diegosouzapw/dev/proxys/OmniRoute/package.json').version")
+ssh root@69.164.221.35 "cp -a /usr/lib/node_modules/omniroute/app /usr/lib/node_modules/omniroute/app.bak-${OMNIROUTE_VERSION}" &
+ssh root@192.168.0.15 "cp -a /usr/lib/node_modules/omniroute/app /usr/lib/node_modules/omniroute/app.bak-${OMNIROUTE_VERSION}" &
+wait
+```
+
+### 3. Stop the processes, then rsync `dist/` → remote `app/` on both VPSs
+
+The VPS image directory is still named `app/`; we ship the **contents** of our local `dist/`. **Stop both running processes FIRST** so `rsync --delete` never removes chunk files out from under a live server — that race produces the transient `[Shutdown] Cannot find module ./chunks/NNNNN.js` seen mid-deploy:
 
 // turbo-all
 
 ```bash
-scp omniroute-*.tgz root@69.164.221.35:/tmp/ && scp omniroute-*.tgz root@192.168.0.15:/tmp/
+ssh root@69.164.221.35 "pm2 stop omniroute" & ssh root@192.168.0.15 "pm2 stop omniroute" & wait
+rsync -az --delete /home/diegosouzapw/dev/proxys/OmniRoute/dist/ root@69.164.221.35:/usr/lib/node_modules/omniroute/app/ && rsync -az --delete /home/diegosouzapw/dev/proxys/OmniRoute/dist/ root@192.168.0.15:/usr/lib/node_modules/omniroute/app/
+```
+
+### 4. Start + health check on both VPSs
+
+`pm2 restart` on a stopped app starts it again with a clean module graph:
+
+```bash
+ssh root@69.164.221.35 "pm2 restart omniroute --update-env && pm2 save"
 ```
 
 ```bash
-ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
+ssh root@192.168.0.15 "pm2 restart omniroute --update-env && pm2 save"
 ```
 
 ```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+sleep 5
+curl -sf http://69.164.221.35:20128/api/monitoring/health | jq '{status:.status, version:.version}'
+curl -sf http://192.168.0.15:20128/api/monitoring/health | jq '{status:.status, version:.version}'
 ```
 
-### 3. Verify the deployment
+Expected: HTTP 200, `"status": "ok"` on both.
+
+### 5. Verify the deployment
 
 ```bash
 curl -s -o /dev/null -w 'AKAMAI HTTP %{http_code}\n' http://69.164.221.35:20128/
 curl -s -o /dev/null -w 'LOCAL HTTP %{http_code}\n' http://192.168.0.15:20128/
 ```
+
+## Rollback
+
+If either VPS fails its health check, restore from backup (adjust host as needed):
+
+```bash
+OMNIROUTE_VERSION=$(node -p "require('/home/diegosouzapw/dev/proxys/OmniRoute/package.json').version")
+# Akamai rollback:
+ssh root@69.164.221.35 "rm -rf /usr/lib/node_modules/omniroute/app && cp -a /usr/lib/node_modules/omniroute/app.bak-${OMNIROUTE_VERSION} /usr/lib/node_modules/omniroute/app && pm2 restart omniroute --update-env"
+# Local rollback:
+ssh root@192.168.0.15 "rm -rf /usr/lib/node_modules/omniroute/app && cp -a /usr/lib/node_modules/omniroute/app.bak-${OMNIROUTE_VERSION} /usr/lib/node_modules/omniroute/app && pm2 restart omniroute --update-env"
+```
+
+## Gotchas
+
+- **Never build in a worktree with symlinked `node_modules`** — the standalone copy step
+  follows symlinks and produces a broken bundle. Use the main checkout or run `npm ci`
+  inside the worktree first.
+- **`pm2 restart --update-env` does NOT re-read `ecosystem.config.cjs`** — if you changed
+  env vars in the ecosystem file, use `pm2 reload` or `pm2 delete + pm2 start` instead.
+- **Parallel dev + release builds**: to avoid clobbering the dev server's `.build/next`,
+  pass `NEXT_DIST_DIR=.build/next-release` to `build:release` in CI or concurrent deploys:
+  `NEXT_DIST_DIR=.build/next-release npm run build:release`
+  then adjust the rsync source to `dist-release/`.
+- **`dist/BUILD_SHA` must match the deployed HEAD** — always confirm before rsyncing.
+  A mismatch means the build ran from a dirty or incorrect commit.
+- **Build once, deploy to both** — never run two separate builds for the two VPSs.
+  The same `dist/` artifact (same `BUILD_SHA`) must land on both hosts to keep
+  versions in sync.

.agents/skills/deploy-vps-local-cc/SKILL.md

@@ -5,36 +5,102 @@ description: Deploy the latest OmniRoute code to the Local VPS (192.168.0.15)
 
 # Deploy to Local VPS Workflow
 
-Deploy OmniRoute to the Local VPS using `npm pack + scp` + PM2.
+Deploy OmniRoute to the Local VPS using a clean `build:release` + `rsync` + PM2 restart.
 
 **Local VPS:** `192.168.0.15`
 **Process manager:** PM2 (`omniroute`)
 **Port:** `20128`
+**Remote install dir:** `/usr/lib/node_modules/omniroute/app/` (VPS image dir — unchanged)
+
+> [!IMPORTANT]
+> **Build must run where `node_modules` is REAL.** A git worktree with symlinked
+> `node_modules` breaks the Next.js standalone assembly. Always build from the main
+> checkout (or an `npm ci`'d worktree), never from `OmniRoute-*` worktrees unless
+> you first ran `npm ci` inside them.
 
 ## Steps
 
-### 1. Build + pack locally
+### 1. Clean build + sentinel
+
+Run from a checkout with a **real** `node_modules`:
 
 // turbo
 
 ```bash
-cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
+cd /home/diegosouzapw/dev/proxys/OmniRoute && npm run build:release
+```
+
+`build:release` does:
+1. Deletes `.build/` and `dist/` (clean rebuild — no stale cache)
+2. Runs `next build` → `.build/next/` (intermediates)
+3. Assembles the shippable bundle into `dist/` via `assembleStandalone`
+4. Writes `dist/BUILD_SHA` = `git rev-parse --short HEAD` (deploy sentinel)
+
+Verify the sentinel before shipping:
+
+```bash
+cat /home/diegosouzapw/dev/proxys/OmniRoute/dist/BUILD_SHA && git -C /home/diegosouzapw/dev/proxys/OmniRoute rev-parse --short HEAD
 ```
 
-### 2. Copy to Local VPS and install
+Both lines must match. If they differ, the build is stale — re-run `build:release`.
+
+### 2. Back up the running bundle on the VPS
+
+```bash
+OMNIROUTE_VERSION=$(node -p "require('/home/diegosouzapw/dev/proxys/OmniRoute/package.json').version")
+ssh root@192.168.0.15 "cp -a /usr/lib/node_modules/omniroute/app /usr/lib/node_modules/omniroute/app.bak-${OMNIROUTE_VERSION}"
+```
+
+### 3. Stop the process, then rsync `dist/` → remote `app/`
+
+The VPS image directory is still named `app/`; we ship the **contents** of our local `dist/`. **Stop the running process FIRST** so `rsync --delete` never removes chunk files out from under the live server — that race produces the transient `[Shutdown] Cannot find module ./chunks/NNNNN.js` seen mid-deploy:
 
 // turbo-all
 
 ```bash
-scp omniroute-*.tgz root@192.168.0.15:/tmp/
+ssh root@192.168.0.15 "pm2 stop omniroute"
+rsync -az --delete /home/diegosouzapw/dev/proxys/OmniRoute/dist/ root@192.168.0.15:/usr/lib/node_modules/omniroute/app/
 ```
 
+### 4. Start + health check
+
+`pm2 restart` on a stopped app starts it again with a clean module graph:
+
 ```bash
-ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts --legacy-peer-deps && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && (pm2 delete omniroute 2>/dev/null || true) && pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
+ssh root@192.168.0.15 "pm2 restart omniroute --update-env && pm2 save"
 ```
 
-### 3. Verify the deployment
+```bash
+sleep 5 && curl -sf http://192.168.0.15:20128/api/monitoring/health | jq '{status:.status, version:.version}'
+```
+
+Expected: HTTP 200, `"status": "ok"` (or equivalent health payload).
+
+### 5. Verify the deployment
 
 ```bash
 curl -s -o /dev/null -w 'LOCAL HTTP %{http_code}\n' http://192.168.0.15:20128/
 ```
+
+## Rollback
+
+If the health check fails, restore the backup:
+
+```bash
+OMNIROUTE_VERSION=$(node -p "require('/home/diegosouzapw/dev/proxys/OmniRoute/package.json').version")
+ssh root@192.168.0.15 "rm -rf /usr/lib/node_modules/omniroute/app && cp -a /usr/lib/node_modules/omniroute/app.bak-${OMNIROUTE_VERSION} /usr/lib/node_modules/omniroute/app && pm2 restart omniroute --update-env"
+```
+
+## Gotchas
+
+- **Never build in a worktree with symlinked `node_modules`** — the standalone copy step
+  follows symlinks and produces a broken bundle. Use the main checkout or run `npm ci`
+  inside the worktree first.
+- **`pm2 restart --update-env` does NOT re-read `ecosystem.config.cjs`** — if you changed
+  env vars in the ecosystem file, use `pm2 reload` or `pm2 delete + pm2 start` instead.
+- **Parallel dev + release builds**: to avoid clobbering the dev server's `.build/next`,
+  pass `NEXT_DIST_DIR=.build/next-release` to `build:release` in CI or concurrent deploys:
+  `NEXT_DIST_DIR=.build/next-release npm run build:release`
+  then adjust the rsync source to `dist-release/` (or whatever `build:release` assembles into).
+- **`dist/BUILD_SHA` must match the deployed HEAD** — always confirm before rsyncing.
+  A mismatch means the build ran from a dirty or incorrect commit.

.dockerignore

@@ -9,6 +9,7 @@
 # Dependencies and build output
 node_modules
 .next
+.build
 out
 build
 dist

.env.example

@@ -1180,6 +1180,16 @@ APP_LOG_TO_FILE=true
 # Used by: open-sse/executors/cursor.ts.
 # CURSOR_STREAM_TIMEOUT_MS=300000
 
+# Cursor tool-commit directive toggle. Default-on: when a request declares
+# tools, a directive is prepended so composer-2.5 reliably issues tool calls
+# instead of narrating intent. Set to 0 to disable.
+# Used by: open-sse/executors/cursor.ts.
+# CURSOR_TOOL_DIRECTIVE=1
+
+# Per-image fetch timeout (ms) for remote image_url vision input. Default: 15000.
+# Used by: open-sse/utils/cursorImages.ts.
+# CURSOR_IMAGE_FETCH_TIMEOUT_MS=15000
+
 # Cursor state DB path override (for cursor version detection).
 # Used by: open-sse/utils/cursorVersionDetector.ts. Default: probed automatically.
 # CURSOR_STATE_DB_PATH=

.github/workflows/ci.yml

@@ -159,7 +159,11 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check:node-runtime
+      # build:cli runs a clean build into .build/next and assembles dist/
+      # For release builds prefer: npm run build:release (clean rebuild + HEAD sentinel)
       - run: npm run build:cli
+      - name: Assert dist/server.js exists
+        run: test -f dist/server.js || (echo "dist/server.js missing — build:cli did not assemble correctly" && exit 1)
       - run: npm run check:pack-artifact
 
   electron-package-smoke: