feat: headroom integration + resource optimizations for container stability

.omo/run-continuation/ses_105eba89fffeuccNC88SJJBRTV.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_105eba89fffeuccNC88SJJBRTV",
+  "updatedAt": "2026-06-24T20:01:32.931Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-06-24T20:01:32.931Z"
+    }
+  }
+}

CLAUDE.md

@@ -221,7 +221,7 @@ connection continue serving other models.
 - **2 spaces**, semicolons, double quotes, 100 char width, es5 trailing commas (enforced by lint-staged via Prettier)
 - **Imports**: external → internal (`@/`, `@omniroute/open-sse`) → relative
 - **Naming**: files=camelCase/kebab, components=PascalCase, constants=UPPER_SNAKE
-- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = error everywhere; `no-explicit-any` = warn in `open-sse/` and `tests/`
+- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = error everywhere; `no-explicit-any` = **error** in `open-sse/` and `tests/` (since #6218 — pre-existing violations are frozen in `config/quality/eslint-suppressions.json`, new ones must be fixed; `npm run lint` applies the suppressions and is what CI runs)
 - **TypeScript**: `strict: false`, target ES2022, module esnext, resolution bundler. Prefer explicit types.
 
 ### Database
@@ -543,7 +543,7 @@ the stale-enforcement added in Fase 6A.3.
 21. **Release-freeze — the FROZEN release branch belongs to the release captain; development does NOT stop (parallel-cycle model, 2026-07-04).** `/generate-release` opens a marker issue labeled `release-freeze` at the start of reconciliation (Phase 0a), **immediately cuts the next cycle's branch `release/vX+1` from the frozen tip (Phase 0a.0b — bump + living release PR + re-home of open PRs)**, and closes the freeze once the release PR squash-merges to `main`. Before merging **any** PR, every campaign workflow (`/review-issues`, `/review-prs`, `/implement-features`, `/green-prs`, `/port-upstream-*`) **MUST** check `gh issue list --repo diegosouzapw/OmniRoute --label release-freeze --state open` — if a freeze is active: **NEVER merge into the frozen `release/vX.Y.Z` named in the freeze title**; instead resolve the ACTIVE development branch (the **highest** `release/v*` by semver — normally `release/vX+1`, announced in a freeze-issue comment) and **retarget the PR there** (`gh pr edit <N> --base release/vX+1`, then VERIFY with `gh pr view <N> --json baseRefName` — the edit fails silently) and merge normally. **HOLD only when the highest release/v\* branch IS the frozen one** (the short window before 0a.0b completes, or a pre-parallel-cycle release) — in that case leave the PR ready and open, tell the operator, and resume when the next branch appears or the freeze lifts. The just-shipped fixes reach `release/vX+1` via the Phase 5 sync-back (`scripts/release/sync-next-cycle.mjs`); do not try to sync mid-release. This is a **coordination signal, not a permission lock**: the release captain and the campaign sessions share the `diegosouzapw` identity, so a GitHub branch-protection lock cannot distinguish them — only this honored marker prevents the mid-release commit races that forced full CHANGELOG re-reconciliation in v3.8.40/v3.8.41 (a parallel campaign advanced `release/vX.Y.Z` by 34 commits mid-run). The release captain's own reconciliation/cycle-open pushes are exempt — they _are_ the release. Fixes that must land during a freeze (a homologation finding) follow the post-merge read-only rule: land on `main` first via `fix/release-vX.Y.Z-*`. **⛔ ONLY `/generate-release` may raise a release-freeze, and ONLY at its Phase 0a (start of generating a new version) — lifted at Phase 12c after the squash-merge to `main`.** No campaign, session, or agent may open a `release-freeze` marker at any other time — a freeze is **never** a mid-development coordination tool. If a session ever believes a freeze is genuinely, unavoidably necessary outside the `/generate-release` flow, it **MUST first ask the operator (`diegosouzapw`) in chat, explicitly alert "estou criando um freeze" and get an explicit yes** — never open, extend, or re-open a `release-freeze` autonomously. Conversely, do **not** close/lift an active `/generate-release` freeze to unblock campaign merges: it protects the captain's single clean CI run and auto-lifts at Phase 12c — closing it early re-triggers the exact commit race it prevents. Verify a freeze is legitimate before acting on it: an open `release-freeze` whose title/body references an **OPEN** release PR (`gh pr view <N> --json state`) is the authorized captain freeze — hold, don't touch.
 22. **Cross-session safety — this repo is worked by MANY parallel sessions/agents at once; never step on another's in-flight work.** Two absolute bans, both recurring incidents (this rule exists because they keep happening):
     - **(a) Never `git stash` / `git stash pop` — ANYWHERE in this repo, including inside an isolated worktree, and including inside any subagent you dispatch.** `git stash` operates on the **shared repository object store**, not the per-worktree working tree — so a stash pushed or popped in one session can silently clobber or resurrect another parallel session's uncommitted changes. This is not hypothetical: 2026-07-02 a `#5923` quotaCache change leaked into the unrelated `#2296` worktree via a global `stash pop`, and the same class reincided through a **subagent**. To compare working changes against a base ref **without** stashing, use `git show <ref>:<path>` or `git diff <ref> -- <path>`; to confirm a typecheck/lint error is pre-existing on the base, inspect the base ref directly (`git show origin/release/vX.Y.Z:<path>`) — never stash your tree away to "get it clean". **Put this ban verbatim in the prompt of every subagent that touches git** (agents don't inherit this file's context — the recurrence was a subagent).
-    - **(b) Never merge, push, rebase, or force-push a PR / branch / worktree that another session is actively working.** An open PR whose head is a live fix worktree in `.claude/worktrees/` you did **not** create (e.g. `fix-5852`/`fix-5923` carrying fresh commits, even when they share your `diegosouzapw` identity), or any branch another session owns, is **off-limits — HOLD**, and let the owning session merge it. **Before** merging or pushing to any PR you did not create *this* session, run `git worktree list` to check for a matching in-flight worktree and re-check `gh pr view <N> --json state,headRefOid`. Only the owning session merges its own in-flight PR; mid-flight merges race the owner and re-trigger the exact commit/CHANGELOG races Rule #19 and Rule #21 guard against. (Reinforces Rule #19.)
+    - **(b) Never merge, push, rebase, or force-push a PR / branch / worktree that another session is actively working.** An open PR whose head is a live fix worktree in `.claude/worktrees/` you did **not** create (e.g. `fix-5852`/`fix-5923` carrying fresh commits, even when they share your `diegosouzapw` identity), or any branch another session owns, is **off-limits — HOLD**, and let the owning session merge it. **Before** merging or pushing to any PR you did not create _this_ session, run `git worktree list` to check for a matching in-flight worktree and re-check `gh pr view <N> --json state,headRefOid`. Only the owning session merges its own in-flight PR; mid-flight merges race the owner and re-trigger the exact commit/CHANGELOG races Rule #19 and Rule #21 guard against. (Reinforces Rule #19.)
 
 ---
 

Dockerfile

@@ -70,6 +70,11 @@ RUN --mount=type=cache,id=npm-cache,target=/root/.npm \
 # See docs/ops/QUALITY_GATE_PLAYBOOK.md Parte 6.
 ENV OMNIROUTE_USE_TURBOPACK=1
 
+# Docker containers cannot run the MITM/Agent-Bridge stack (no host DNS/cert
+# access), so keep @/mitm/manager on the graceful stub (#3390). This flag is
+# Docker-only: npm/Electron/VPS builds must bundle the REAL manager (#6344).
+ENV OMNIROUTE_MITM_STUB=1
+
 # Raise the V8 heap ceiling for the build. The webpack production optimization
 # pass needs more than V8's default ceiling (~2 GB) for a codebase this size; a
 # memory-constrained Docker build otherwise dies with "FATAL ERROR: ... JavaScript
@@ -103,7 +108,7 @@ ENV NODE_OPTIONS="--max-old-space-size=${OMNIROUTE_MEMORY_MB}"
 
 # Data directory inside Docker — must match the volume mount in docker-compose.yml
 ENV DATA_DIR=/app/data
-RUN mkdir -p /app/data
+RUN mkdir -p /app/data && chown -R node:node /app
 
 # `npm run build` (build-next-isolated → assembleStandalone) bundles ALL runtime
 # files into .build/next/standalone/ — .next, node_modules, migrations, scripts,
@@ -113,23 +118,26 @@ RUN mkdir -p /app/data
 # The old per-module overrides were therefore pure duplication and were removed
 # (build-output-isolation cleanup). See scripts/build/assembleStandalone.mjs
 # (EXTRA_MODULE_ENTRIES) for the single source of truth.
-COPY --from=builder /app/.build/next/standalone ./
+COPY --chown=node:node --from=builder /app/.build/next/standalone ./
 # better-sqlite3 is the one exception still copied explicitly: assembleStandalone
 # only syncs its native build/ dir; the JS wrapper (lib/, package.json) is left to
 # Next.js tracing. bootstrap-env requires SQLite BEFORE the standalone server
 # starts, so guarantee the complete package independent of trace behaviour.
-COPY --from=builder /app/node_modules/better-sqlite3 ./node_modules/better-sqlite3
+COPY --chown=node:node --from=builder /app/node_modules/better-sqlite3 ./node_modules/better-sqlite3
 # migrations land at <standalone>/migrations via assembleStandalone; point the runtime at them.
 ENV OMNIROUTE_MIGRATIONS_DIR=/app/migrations
 
 # Docker healthcheck script — not traced by Next.js standalone output, so copy
 # it explicitly. The HEALTHCHECK CMD references it as `node healthcheck.mjs`.
-COPY --from=builder /app/scripts/dev/healthcheck.mjs ./healthcheck.mjs
-
-# Hand /app over to the baked-in `node` non-root user (UID/GID 1000) so the
-# runtime process never holds root privileges. The chown happens after all
-# COPYs so it covers files originally owned by root in the builder stage.
-RUN chown -R node:node /app
+COPY --chown=node:node --from=builder /app/scripts/dev/healthcheck.mjs ./healthcheck.mjs
+
+# Install Python + pipx for Headroom CLI (required for headroom proxy management)
+# Install as root, then ensure pipx binaries are accessible to node user
+ENV PIPX_BIN_DIR=/usr/local/bin
+ENV PIPX_HOME=/opt/pipx
+RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip python3-venv pipx \
+    && pipx install --global headroom-ai \
+    && rm -rf /var/lib/apt/lists/*
 
 EXPOSE 20128
 

bin/cli/commands/launch-codex.mjs

@@ -19,6 +19,16 @@ const STRIPPED_CODEX_ENV_KEYS = [
 /** Placeholder so codex's `env_key` is always satisfied when the backend is open. */
 const NO_AUTH_SENTINEL = "omniroute-no-auth";
 
+// On Windows the `codex` binary is an npm `.cmd` shim that `spawn` cannot resolve
+// without a shell (bare "codex" → ENOENT). Mirror the qodercli Windows fix (#6263):
+// spawn `codex.cmd` through a shell on win32, and the bare binary elsewhere.
+export function resolveCodexSpawn(platform) {
+  if (platform === "win32") {
+    return { command: "codex.cmd", shell: true };
+  }
+  return { command: "codex", shell: undefined };
+}
+
 function stripTrailingSlash(value) {
   let s = String(value);
   let end = s.length;
@@ -126,10 +136,10 @@ export async function runLaunchCodexCommand(opts = {}, codexArgs = []) {
 
   if (!(await healthCheck(baseUrl))) {
     console.error(
-      (t("launch.notRunning") || "OmniRoute is not reachable at {port}. Start it with 'omniroute serve'.").replace(
-        "{port}",
-        baseUrl
-      )
+      (
+        t("launch.notRunning") ||
+        "OmniRoute is not reachable at {port}. Start it with 'omniroute serve'."
+      ).replace("{port}", baseUrl)
     );
     return 1;
   }
@@ -142,7 +152,12 @@ export async function runLaunchCodexCommand(opts = {}, codexArgs = []) {
   const env = buildCodexEnv(process.env, authToken);
 
   return await new Promise((resolve) => {
-    const child = spawn("codex", extraArgs, { env, stdio: "inherit" });
+    const { command: codexLaunch, shell: shellValue } = resolveCodexSpawn(process.platform);
+    const child = spawn(codexLaunch, extraArgs, {
+      env,
+      stdio: "inherit",
+      shell: shellValue,
+    });
     child.on("error", (err) => {
       if (err?.code === "ENOENT") {
         console.error(
@@ -165,10 +180,16 @@ export function registerLaunchCodex(program) {
       t("launchCodex.description") || "Launch Codex CLI pointed at OmniRoute (local or remote VPS)"
     )
     .option("--port <port>", "Local OmniRoute port (ignored when --remote is set)", "20128")
-    .option("--remote <url>", "Remote OmniRoute base URL, e.g. http://192.168.0.15:20128 (overrides --port + context)")
+    .option(
+      "--remote <url>",
+      "Remote OmniRoute base URL, e.g. http://192.168.0.15:20128 (overrides --port + context)"
+    )
     .option("--profile <name>", "Codex profile to activate (passed as --profile <name>)")
     .option("-p, --p <name>", "Alias for --profile")
-    .option("--api-key <key>", "OmniRoute API key (overrides OMNIROUTE_API_KEY env var for this invocation)")
+    .option(
+      "--api-key <key>",
+      "OmniRoute API key (overrides OMNIROUTE_API_KEY env var for this invocation)"
+    )
     .allowUnknownOption(true)
     .allowExcessArguments(true)
     .argument("[codexArgs...]", "arguments passed through to the codex binary")

bin/omniroute.mjs

@@ -6,6 +6,7 @@
  * Special bypasses (handled before Commander):
  *   --mcp                     Start MCP server over stdio
  *   reset-encrypted-columns   Recovery tool for broken encrypted credentials
+ *   reset-password            Reset the admin/management password
  *
  * All other commands are routed through Commander (bin/cli/program.mjs).
  */
@@ -210,6 +211,15 @@ if (process.argv.includes("reset-encrypted-columns")) {
   process.exit(exitCode ?? 0);
 }
 
+if (process.argv.includes("reset-password")) {
+  // bin/reset-password.mjs self-executes its `main()` on import and calls
+  // process.exit() on completion/error. Await a never-resolving promise so
+  // control never falls through to Commander (which would then reject
+  // `reset-password` as an unknown command). See #6261.
+  await import(pathToFileURL(join(ROOT, "bin", "reset-password.mjs")).href);
+  await new Promise(() => {});
+}
+
 try {
   const { createProgram } = await import(
     pathToFileURL(join(ROOT, "bin", "cli", "program.mjs")).href

bin/reset-password.mjs

@@ -5,10 +5,15 @@
  *
  * Usage:
  *   node bin/reset-password.mjs
- *   npx omniroute reset-password
+ *   omniroute reset-password
+ *
+ * Non-interactive / scripted usage (piped stdin, e.g. CI or Docker):
+ *   printf 'NewPass123\nNewPass123\n' | omniroute reset-password
+ *   printf 'NewPass123' | omniroute reset-password --password-stdin
  *
  * Resets the admin password for OmniRoute.
- * Prompts for a new password and updates the database directly.
+ * Prompts for a new password (interactive TTY) or reads it from stdin
+ * (non-TTY) and updates the database directly.
  *
  * @module bin/reset-password
  */
@@ -21,19 +26,61 @@ import { readManagementPasswordState, resetManagementPassword } from "./cli/sqli
 const DATA_DIR = resolveDataDir();
 const DB_PATH = resolveStoragePath(DATA_DIR);
 
-const rl = createInterface({
-  input: process.stdin,
-  output: process.stdout,
-});
-
-function ask(question) {
-  return new Promise((resolve) => rl.question(question, resolve));
+const MIN_PASSWORD_LENGTH = 8;
+
+/** Read the entire stdin stream as a UTF-8 string (used for non-TTY input). */
+function readAllStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(data));
+    // Resuming is implied by attaching a 'data' listener, but be explicit so a
+    // paused stream (some spawn setups) still flows to EOF.
+    process.stdin.resume();
+  });
 }
 
-function exitWithError(message) {
-  console.error(message);
-  rl.close();
-  process.exit(1);
+/**
+ * Obtain the new password (and its confirmation).
+ *
+ * - `--password-stdin`: the ENTIRE stdin is the password, no confirmation.
+ * - non-TTY stdin (piped): read all of stdin once; first line is the password,
+ *   second line — when present — is the confirmation, else the first line is
+ *   reused (a single-line pipe means "no separate confirmation").
+ * - interactive TTY: two sequential prompts (unchanged behavior).
+ *
+ * The non-TTY path exists because two sequential `rl.question` promises never
+ * settle under a piped EOF — the second read blocks forever, so the reset was
+ * silently never applied (#6258).
+ */
+async function collectPassword() {
+  if (process.argv.includes("--password-stdin")) {
+    const raw = await readAllStdin();
+    const password = raw.replace(/[\r\n]+$/, "");
+    return { password, confirm: password };
+  }
+
+  if (!process.stdin.isTTY) {
+    const raw = await readAllStdin();
+    const lines = raw.split(/\r?\n/);
+    const password = lines[0] ?? "";
+    const confirm = lines[1] ? lines[1] : password;
+    return { password, confirm };
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const ask = (question) => new Promise((resolve) => rl.question(question, resolve));
+    const password = await ask("Enter new password (min 8 chars): ");
+    const confirm = await ask("Confirm new password: ");
+    return { password, confirm };
+  } finally {
+    rl.close();
+  }
 }
 
 console.log("\n🔑 OmniRoute — Password Reset\n");
@@ -54,27 +101,34 @@ async function main() {
     console.log("ℹ️  No password is currently set.");
   }
 
-  const password = await ask("Enter new password (min 8 chars): ");
+  const { password, confirm } = await collectPassword();
 
-  if (!password || password.length < 8) {
-    exitWithError("\n❌ Password must be at least 8 characters.\n");
+  if (!password || password.length < MIN_PASSWORD_LENGTH) {
+    console.error(`\n❌ Password must be at least ${MIN_PASSWORD_LENGTH} characters.\n`);
+    process.exit(1);
   }
 
-  const confirm = await ask("Confirm new password: ");
-
   if (password !== confirm) {
-    exitWithError("\n❌ Passwords do not match.\n");
+    console.error("\n❌ Passwords do not match.\n");
+    process.exit(1);
   }
 
   await resetManagementPassword(password, DB_PATH);
-  rl.close();
 
   console.log("\n✅ Password reset successfully!");
   console.log("   Restart OmniRoute for changes to take effect.\n");
 }
 
-main().catch((err) => {
-  console.error(`\n❌ Error: ${err.message}\n`);
-  rl.close();
-  process.exit(1);
-});
+main()
+  .then(() => {
+    // Explicit exit(0) so a caller that imports this module (bin/omniroute.mjs
+    // routes `omniroute reset-password` here) terminates cleanly instead of
+    // hanging / exiting with code 13 on an unsettled wrapper await. On POSIX,
+    // console.log to a pipe is synchronous, so the success line is already
+    // flushed by the time we exit.
+    process.exit(0);
+  })
+  .catch((err) => {
+    console.error(`\n❌ Error: ${err.message}\n`);
+    process.exit(1);
+  });