deepdebug-local-agent 1.0.23 → 1.1.0

package/src/server.js

@@ -5,13 +5,35 @@ import path from "path";
 import os from "os";
 import fs from "fs";
 const fsPromises = fs.promises;
-import { exec, spawn } from "child_process";
+import { exec, execFile, spawn } from "child_process";
 import { promisify } from "util";
 import { EventEmitter } from "events";
 import { exists, listRecursive, readFile, writeFile } from "./fs-utils.js";
 import { detectProject, readText } from "./detectors.js";
+import { detectBuildTool } from "./detectors/build-tool-detector.js";
+import { validateFiles } from "./validators/syntax-validator.js";
 import { detectPort } from "./ports.js";
 import { compileAndTest, run } from "./exec-utils.js";
+import { confineToRoot, checkArgsWithinRoot, scanRawCommand, SandboxViolation } from "./utils/sandbox.js";
+import { getSigningConfig, createSignatureMiddleware, captureRawBody, describeSigningConfig, verifyWsEnvelope, internalSignatureHeaders } from "./utils/request-signing.js";
+import { decideExec, rejectionBody, resolveExecPolicyConfig } from "./utils/exec-policy.js";
+import { resolveEffectiveHeaderRoot } from "./utils/root-recovery.js";
+import { classifyGrepFailure, partialSearchBody } from "./utils/search-outcome.js";
+import { classifyOpenDestination, extractOpenTenantId, isSafeToRemove } from "./utils/open-gate.js";
+import { fetchRequestedRef } from "./utils/branch-refspec.js";
+import { sliceFileContent } from "./utils/ranged-read.js";
+import { countFilesExcludingGit } from "./utils/file-count.js";
+import { hydrateRepos, multiRepoAllowPartial, planRepos } from "./utils/multi-repo-open.js";
+import {
+    multiRepoPrEnabled,
+    isMultiRepoRoot,
+    listRepoSubdirs,
+    parseAuthedRemote,
+    stripRemoteCreds,
+    buildCompareUrl,
+    buildCrossLinkNote,
+    buildMultiRepoPrBody,
+} from "./git/multi-repo-pr.js";
 import { applyUnifiedDiff } from "./patch.js";
 import { WorkspaceScanner } from "./workspace/scanner.js";
 import { FileReader } from "./workspace/file-reader.js";
@@ -25,14 +47,49 @@ import { ConfigAnalyzer } from "./analyzers/config-analyzer.js";
 import { WorkspaceManager } from "./workspace-manager.js";
 import { startMCPHttpServer } from "./mcp-http-server.js";
 import { registerVercelRoutes } from "./vercel-proxy.js";
+import { registerObservabilityRoutes } from "./observability/routes.js";
+import { resolveAuthConfig, allowedOrigins, corsOriginCallback, createAuthMiddleware, internalAuthHeaders, describeAuthMode } from "./utils/agent-auth.js";
+import { isSafeBranchName } from "./utils/branch-refspec.js";
+import { resolveBindHost } from "./utils/bind-host.js";
+import { sanitizedChildEnv } from "./utils/child-env.js";
+import { validateHeaderRoot } from "./utils/workspace-root.js";
+import { buildGrepArgs, buildTarArgs, parseAuthCommand } from "./utils/safe-exec-args.js";
+import { validateLocalTestUrl, buildLocalTestUrl, isSafeTenantId, validateGitUrl, isSafeToolName } from "./utils/request-guards.js";
 import { loadAdapters, stopAll } from "./adapters/index.js";
 
 const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+
+/**
+ * Resolve a repo's real default branch by asking the remote directly.
+ *
+ * `git symbolic-ref refs/remotes/origin/HEAD` is unreliable: a `--single-branch`
+ * clone (our fallback when the requested branch is absent) never creates the
+ * origin/HEAD ref, so on the next update the lookup returns nothing and we wrongly
+ * keep assuming 'main'. `git ls-remote --symref origin HEAD` queries the remote and
+ * always reports the true default (master/main/anything), independent of how the
+ * local clone was made.
+ *
+ * @returns {Promise<string|null>} branch name (e.g. "master") or null if undeterminable.
+ */
+async function resolveDefaultBranch(cwd) {
+    try {
+        const { stdout } = await execAsync(`git ls-remote --symref origin HEAD`, { cwd, timeout: 30000 });
+        // First line looks like: "ref: refs/heads/master\tHEAD"
+        const m = /ref:\s+refs\/heads\/(\S+)\s+HEAD/.exec(stdout || "");
+        if (m) return m[1];
+    } catch {
+        // Network/token failure — fall through to the local symbolic-ref probe.
+    }
+    const head = await execAsync(`git symbolic-ref refs/remotes/origin/HEAD --short`, { cwd })
+        .catch(() => null);
+    return head && head.stdout ? head.stdout.trim().replace(/^origin\//, "") : null;
+}
 
 // ============================================
 //  AI VIBE CODING ENGINE
-// Sistema universal de auto-healing que usa AI
-// para resolver QUALQUER erro automaticamente
+// Universal auto-healing system that uses AI
+// to resolve ANY error automatically
 // ============================================
 
 class AIVibeCodingEngine extends EventEmitter {
@@ -96,7 +153,7 @@ class AIVibeCodingEngine extends EventEmitter {
             /datasource.*failed/i
         ];
 
-        // Excluir falsos positivos (linhas normais que contm palavras de erro)
+        // Exclude false positives (normal lines that contain error words)
         const falsePositives = [
             /hikaripool.*start/i,      // "HikariPool-1 - Starting..."  normal
             /hikaripool.*completed/i,  // "HikariPool-1 - Start completed"  normal
@@ -106,7 +163,7 @@ class AIVibeCodingEngine extends EventEmitter {
             /tomcat started/i          // "Tomcat started on port"  sucesso!
         ];
 
-        // Se match com falso positivo, no  erro
+        // If it matches a false positive, it is not an error
         if (falsePositives.some(p => p.test(message))) {
             return false;
         }
@@ -293,7 +350,7 @@ class AIVibeCodingEngine extends EventEmitter {
                 clearTimeout(timeout);
             };
 
-            // Detectar sucesso do Spring Boot nos logs
+            // Detect Spring Boot success in the logs
             const isStartupSuccess = (message) => {
                 if (!message) return false;
                 return /started.*in.*seconds/i.test(message) ||
@@ -305,7 +362,7 @@ class AIVibeCodingEngine extends EventEmitter {
                 if (serviceId === 'test-local' && message) {
                     logs.push(message);
 
-                    // Detectar sucesso nos logs do Spring Boot
+                    // Detect success in the Spring Boot logs
                     if (isStartupSuccess(message) && !resolved) {
                         console.log(`[AI-Engine] Detected startup success: ${message.substring(0, 80)}...`);
                         resolved = true;
@@ -551,59 +608,37 @@ const app = express();
 //  FIXED: Support Cloud Run PORT environment variable (GCP uses PORT)
 const PORT = process.env.PORT || process.env.LOCAL_AGENT_PORT || 5055;
 
-// CORS - Allow from Cloud Run, local dev, and Lovable frontend domains
+// SECURITY (audit 2026-09): CORS is an exact allowlist (no wildcard shared-
+// hosting domains such as *.vercel.app / *.run.app, no allow-all in non-prod)
+// and every non-public route goes through the auth perimeter in
+// utils/agent-auth.js. No browser page calls the agent directly.
+const AGENT_AUTH = resolveAuthConfig();
+const AGENT_ORIGINS = allowedOrigins();
 app.use(cors({
-    origin: function(origin, callback) {
-        // Allow requests with no origin (curl, mobile apps, server-to-server)
-        if (!origin) return callback(null, true);
-
-        const allowed = [
-            // Local development
-            "http://localhost:3010",
-            "http://localhost:3000",
-            "http://localhost:8085",
-            "http://127.0.0.1:3010",
-            "http://127.0.0.1:3000",
-            "http://127.0.0.1:8085",
-        ];
-
-        const allowedPatterns = [
-            /https:\/\/.*\.run\.app$/,          // Cloud Run
-            /https:\/\/.*\.web\.app$/,           // Firebase hosting
-            /https:\/\/.*\.lovable\.app$/,       // Lovable preview
-            /https:\/\/.*\.lovableproject\.com$/, // Lovable project domains
-            /https:\/\/.*\.netlify\.app$/,       // Netlify
-            /https:\/\/.*\.vercel\.app$/,        // Vercel
-            /https:\/\/deepdebug\.ai$/,           // Production
-            /https:\/\/.*\.deepdebug\.ai$/,      // Production subdomains
-        ];
-
-        if (allowed.includes(origin) || allowedPatterns.some(p => p.test(origin))) {
-            return callback(null, true);
-        }
-
-        // In development/QA, log and allow unknown origins instead of blocking
-        const env = process.env.NODE_ENV || 'development';
-        if (env !== 'production') {
-            console.warn(`CORS: allowing unknown origin in non-prod: ${origin}`);
-            return callback(null, true);
-        }
-
-        console.warn(`CORS: blocked origin: ${origin}`);
-        return callback(new Error(`CORS: origin ${origin} not allowed`));
-    },
+    origin: corsOriginCallback(AGENT_ORIGINS),
     methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
-    allowedHeaders: ["Content-Type", "Authorization", "X-Tenant-ID", "X-User-ID"],
+    allowedHeaders: ["Content-Type", "Authorization", "X-Tenant-ID", "X-User-ID", "X-Agent-Token", "X-Workspace-Id", "X-Workspace-Root"],
     credentials: true
 }));
-
-//  Handle preflight requests explicitly
-app.options('*', cors());
-
-app.use(bodyParser.json({ limit: "50mb" }));
-
-//  DEFAULT WORKSPACE - Define o workspace padro
-// Pode ser sobrescrito via varivel de ambiente ou POST /workspace/open
+app.options('*', cors({ origin: corsOriginCallback(AGENT_ORIGINS) }));
+app.use(createAuthMiddleware(AGENT_AUTH, AGENT_ORIGINS));
+(AGENT_AUTH.mode === 'token' || AGENT_AUTH.mode === 'loopback' ? console.log : console.warn)(`[agent-auth] mode: ${describeAuthMode(AGENT_AUTH)}`);
+
+// captureRawBody keeps the exact bytes the platform signed (X-VH-Signature).
+app.use(bodyParser.json({ limit: "50mb", verify: captureRawBody }));
+
+// SIGNED COMMANDS (utils/request-signing.js): every platform request carries an
+// Ed25519 signature over method/path/body/tenant/workspace/timestamp/nonce.
+// LOCAL_AGENT_SIGNATURE_MODE=off|warn|enforce (default enforce since 1.1.0; warn = verify + log only).
+// X-Agent-Token (agent-auth above) stays as the second factor.
+const SIGNING = getSigningConfig();
+const EXEC_POLICY = resolveExecPolicyConfig();
+app.use(createSignatureMiddleware(SIGNING));
+(SIGNING.mode === "enforce" ? console.log : console.warn)(`[agent-sig] ${describeSigningConfig(SIGNING)}`);
+console.log(`[exec-policy] mode=${EXEC_POLICY.mode} (allowlist; LOCAL_AGENT_EXEC_POLICY_MODE=off|warn|enforce)`);
+
+//  DEFAULT WORKSPACE - Sets the default workspace
+// Can be overridden via an environment variable or POST /workspace/open
 const DEFAULT_WORKSPACE = process.env.WORKSPACE_ROOT
     || process.env.DEFAULT_WORKSPACE
     || '/Users/macintosh/IdeaProjects/pure-core-ms';
@@ -617,6 +652,24 @@ let DETECTED_SERVICES = [];
 const processManager = new ProcessManager();
 const wsManager = new WorkspaceManager();
 
+// SEG-1: strip credentials from any URL before it reaches a log line or an
+// error returned to the caller. Masks the userinfo segment of every http(s)
+// URL in the string (user:pass, x-token-auth:token, oauth2:token,
+// x-access-token:token) regardless of token format, so a client access token
+// never appears in Cloud Logging. Token-agnostic (unlike a literal token
+// replace, which misses repeated occurrences and breaks on regex chars) and
+// never throws. Returns non-strings coerced to string; null/undefined pass
+// through unchanged.
+function maskUrlCreds(input) {
+    if (input === null || input === undefined) return input;
+    const s = typeof input === "string" ? input : String(input);
+    // Mask the entire userinfo (everything from "://" up to the delimiting "@").
+    // [^\s@]+ allows ":" and "/" so tokens that embed a slash (base64, some
+    // PATs) or carry no colon ("https://<token>@host") are fully masked, not
+    // just up to the first slash.
+    return s.replace(/(https?:\/\/)[^\s@]+@/gi, "$1***@");
+}
+
 function resolveWorkspaceRoot(req) {
     // TENANT ISOLATION: stateless, never mutates global state.
     // Returns the workspace path for THIS specific request only.
@@ -632,7 +685,46 @@ function resolveWorkspaceRoot(req) {
     // 1. Tenant-isolated NFS path from Gateway
     const secureRoot = req.headers['x-workspace-root'];
     if (secureRoot && secureRoot.trim()) {
-        return secureRoot.trim();
+        // SECURITY (2026-10-11): the header is not covered by the request
+        // signature, so it is validated against the workspace bases / the
+        // registry (and the signed tenant) before it becomes the sandbox root.
+        const check = validateHeaderRoot(secureRoot, {
+            registry: wsManager.list(),
+            tenantId: req.vhSignature && req.vhSignature.verified ? (req.vhSignature.tenantId || null) : undefined,
+        });
+        if (!check.ok) {
+            console.warn(`[workspace-root] REJECTED X-Workspace-Root '${secureRoot.trim().slice(0, 200)}': ${check.reason}`);
+            return null;
+        }
+        // ROOT-RECOVERY (transversal, 2026-07-19): on a stateless agent the
+        // header often carries a DEAD persisted path ("/mnt/workspaces/...")
+        // while the real clone this agent made lives under WORKSPACE_MOUNT
+        // ("/tmp/workspaces/<owner>_<repo>"). If the header root exists on
+        // disk it is returned UNCHANGED (byte-identical for every working
+        // caller); only a dead root triggers conservative recovery via the
+        // workspace registry + clone-mount scan. Fixes the v1/v2/indexer
+        // split-brain (prepare clones to one path, reads hit another) at the
+        // single point every caller already goes through.
+        const wsIdHint = req.headers['x-workspace-id']
+            || (req.body && req.body.workspaceId)
+            || (req.query && req.query.workspaceId)
+            || null;
+        // TENANT GATE: tenant of the dead root is derived from the
+        // "/mnt/workspaces/<tenant>/..." path inside the recovery module;
+        // the request payload tenantId is only a fallback hint.
+        const tenantHint = (req.body && req.body.tenantId)
+            || (req.query && req.query.tenantId)
+            || null;
+        const eff = resolveEffectiveHeaderRoot(secureRoot, {
+            wsIdHint,
+            tenantHint,
+            registry: wsManager.list(),
+            mountDir: process.env.WORKSPACE_MOUNT || process.env.WORKSPACES_MOUNT || "/tmp/workspaces"
+        });
+        if (eff.recovered) {
+            console.log(`[ROOT-RECOVERY] dead root '${secureRoot.trim()}' -> live root '${eff.root}'`);
+        }
+        return eff.root;
     }
 
     // 2. WorkspaceId (dev/local mode only)
@@ -660,6 +752,17 @@ try {
         .filter(Boolean);
     if (stacks.length > 0) {
         _legacyAdapters = loadAdapters({ legacyStacks: stacks });
+        // Wire the adapter consumer (sibling module): forward each adapter's 6-key
+        // 'error' event to the gateway incident endpoint. Attached here in the
+        // existing boot loop; the forwarder buffers until it is configured with the
+        // gateway credentials from the app.listen callback below.
+        import('./siblings/incident-forwarder.js')
+            .then(({ incidentForwarder }) => {
+                for (const a of _legacyAdapters) {
+                    a.on('error', (evt) => incidentForwarder.handleAdapterEvent(evt, a?.constructor?.name));
+                }
+            })
+            .catch((err) => process.stderr.write(`adapter-consumer wiring failed: ${err.message}\n`));
         for (const a of _legacyAdapters) {
             // Start failures are surfaced via the adapter's 'error' event; do not crash boot.
             Promise.resolve()
@@ -752,6 +855,24 @@ function loadBackupIndex() {
 // Load backups on startup
 loadBackupIndex();
 
+// ============================================
+//  TEST LOCAL STATE (EARLY INITIALIZATION)
+// Must be initialized BEFORE event listeners that call addServerLog()
+// ============================================
+// Single source of truth for test-local state. Declared early (before the
+// ProcessManager event listeners that call addServerLog) and reused by the
+// test-local endpoints below. Full shape so every field the endpoints read
+// (status/config/testResults/endpoints/...) exists from the start.
+const TEST_LOCAL_STATE = {
+    status: "idle", // idle, compiling, compiled, starting, running, stopped, error
+    compilationResult: null,
+    serverProcess: null,
+    endpoints: [],
+    config: null,
+    testResults: [],
+    serverLogs: [] // circular buffer of server logs (last 1000)
+};
+
 // Event listeners do ProcessManager
 processManager.on("started", ({ serviceId }) => {
     console.log(`Service ${serviceId} started successfully`);
@@ -814,14 +935,246 @@ app.get("/health", (req, res) => {
 });
 
 /** Define/abre o workspace local */
+/**
+ * Clone or update ONE repo into `destDir`. Extracted so both the single-repo
+ * and multi-repo branches share identical auth/checkout/reset semantics.
+ */
+async function cloneOrUpdateRepo({ repoUrl, token, branch = "main", destDir }) {
+    let authUrl;
+    if (token) {
+        const cleanUrl = repoUrl.replace(/https:\/\/[^@]+@/, 'https://');
+        authUrl = token.includes(':')
+            ? cleanUrl.replace('https://', `https://${token}@`)
+            : cleanUrl.replace('https://', `https://x-access-token:${token}@`);
+    } else {
+        authUrl = repoUrl;
+    }
+    const alreadyCloned = await exists(path.join(destDir, '.git'));
+    if (alreadyCloned) {
+        await execAsync(`git remote set-url origin "${authUrl}"`, { cwd: destDir }).catch(() => {});
+        await execAsync(`git fetch origin`, { cwd: destDir, timeout: 120000 });
+        // REFSPEC FIX (QA 2026-07-20) composed with main's default-branch
+        // fallback (PR #4): the original clone was --single-branch, so the
+        // `git fetch origin` above only refreshes THAT one branch. Fetch the
+        // REQUESTED ref explicitly so branches created after the clone (e.g.
+        // a PR branch minutes old) exist before checkout/reset. If the branch
+        // does not exist on the remote (caller assumed main, repo uses
+        // master), fall back to the repo's real default branch. Shell-unsafe
+        // branch names still throw tagged INVALID_BRANCH -> clear response.
+        let effBranch = branch;
+        try {
+            await fetchRequestedRef(execAsync, branch, destDir);
+        } catch (refErr) {
+            if (refErr && refErr.code === 'BRANCH_NOT_FOUND') {
+                const defBranch = await resolveDefaultBranch(destDir);
+                if (defBranch) {
+                    console.warn(`[cloud] Branch '${branch}' not on remote — using default '${defBranch}'`);
+                    effBranch = defBranch;
+                } else {
+                    throw refErr;
+                }
+            } else {
+                throw refErr;
+            }
+        }
+        await execAsync(`git checkout ${effBranch} 2>/dev/null || git checkout -b ${effBranch} origin/${effBranch}`, { cwd: destDir }).catch(() => {});
+        await execAsync(`git reset --hard origin/${effBranch}`, { cwd: destDir });
+    } else {
+        try {
+            await execAsync(
+                `git clone --branch ${branch} --single-branch --depth 50 "${authUrl}" "${destDir}"`,
+                { timeout: 300000 }
+            );
+        } catch (cloneErr) {
+            // Requested branch absent (e.g. repo uses master). Git phrases this as
+            // "Remote branch <x> not found in upstream origin" or "could not find
+            // remote branch" — match both, then clone the repo's default branch.
+            if (/(remote branch .* not found|could not find remote branch)/i.test(cloneErr.message || '')) {
+                console.warn(`[cloud] Branch '${branch}' not found — falling back to the repo default branch`);
+                await execAsync(`rm -rf "${destDir}"`).catch(() => {});
+                await execAsync(
+                    `git clone --single-branch --depth 50 "${authUrl}" "${destDir}"`,
+                    { timeout: 300000 }
+                );
+            } else {
+                throw cloneErr;
+            }
+        }
+        await execAsync(`git config user.email "deepdebug-ai@deepdebug.ai"`, { cwd: destDir });
+        await execAsync(`git config user.name "DeepDebug AI"`, { cwd: destDir });
+    }
+}
+
 app.post("/workspace/open", async (req, res) => {
-    const { root, workspaceId, repoUrl, token, branch = "main" } = req.body || {};
+    const { root, workspaceId, repoUrl, token, branch = "main", repos } = req.body || {};
+    // TENANT GATE (ROOT-RECOVERY): remember which tenant this clone is
+    // hydrated for. Best-effort and additive - null means unknown, and
+    // unknown NEVER cross-recovers by basename/scan (fail-closed).
+    // OPEN GATE (2026-07-20): body.tenantId wins, X-Tenant-ID header is the
+    // fallback, so EVERY branch below registers the tenant when the caller
+    // sends it in either place.
+    const openTenantId = extractOpenTenantId(req.body, req.headers);
+
+    // ==========================================
+    // MULTI-REPO CLOUD MODE (SEG-3 + FEATURE):
+    // Gateway sends repos:[{repoUrl,token?,branch?,dir?}] for a workspace.
+    // All N repos are cloned UNDER ONE per-workspace dir, and that dir — the
+    // PARENT of the repos — becomes the sandbox root. The agent's confineToRoot
+    // then allows every repo of THIS workspace and denies anything outside it
+    // (another workspace of the same tenant lives under a different <wsId> dir).
+    // ==========================================
+    if (Array.isArray(repos) && repos.length > 0) {
+        const wsId = (workspaceId && workspaceId.trim()) ? workspaceId.trim() : null;
+        if (!wsId) return res.status(400).json({ ok: false, error: "workspaceId is required for multi-repo open" });
+        // Reject a workspaceId that would escape the cache dir (e.g. "../x").
+        if (!/^[A-Za-z0-9._-]+$/.test(wsId)) {
+            return res.status(400).json({ ok: false, error: "invalid workspaceId" });
+        }
+        // PATH CONVENTION (Phase C, reconciled 2026-09): multi-repo and single-repo
+        // BOTH root under the same WORKSPACE_CACHE base (the NFS mount
+        // /mnt/workspaces in QA/PROD; /tmp/workspaces only as the local-dev
+        // fallback). Single-repo keys by <org_repo>; multi-repo keys by <wsId>
+        // (a globally-unique workspace UUID) because it needs ONE parent dir to
+        // hold N sibling repos. Keying by wsId - not tenantId/repoName - is the
+        // isolation boundary the rest of this handler already enforces:
+        // classifyOpenDestination() denies a dir REGISTERED to another tenant
+        // (requestTenantId gate), and confineToRoot() below keeps every repo
+        // inside this wsId dir, so a second workspace of the same tenant lives
+        // under a different <wsId> and can never be reached. Nesting under
+        // tenantId would add nothing (the UUID is already unique + tenant-gated)
+        // while breaking isSafeToRemove()'s cacheDir/workspaceDir depth check.
+        const cacheDir = process.env.WORKSPACE_CACHE || '/tmp/workspaces';
+        const workspaceDir = path.join(cacheDir, wsId);
+
+        // OPEN GATE (2026-07-20): an open with repos[] is a HYDRATION request.
+        // Never die on a stale dir a previous revision left behind (in-memory
+        // registry lost on restart => orphan): remove the orphan and clone
+        // fresh. A dir REGISTERED for another tenant is never touched - the
+        // caller gets a clear 409 instead of a generic 500.
+        const multiGate = classifyOpenDestination(workspaceDir, {
+            registry: wsManager.list(),
+            requestTenantId: openTenantId
+        });
+        if (multiGate.action === "deny") {
+            console.warn(`[open-gate] DENY multi-repo open: ${workspaceDir} is registered for another tenant (ws '${multiGate.ownerWorkspaceId}') - request tenant '${openTenantId}'`);
+            return res.status(409).json({
+                ok: false,
+                error: "workspace_dir_owned_by_another_tenant",
+                hint: "The clone destination on this agent is registered for a different tenant. Use a distinct workspaceId."
+            });
+        }
+        if (multiGate.action === "clean_and_fresh" && isSafeToRemove(cacheDir, workspaceDir)) {
+            console.warn(`[open-gate] ORPHAN dir at ${workspaceDir} (no registered workspace) - removing stale clone and hydrating fresh`);
+            await fsPromises.rm(workspaceDir, { recursive: true, force: true });
+        }
+        if (multiGate.action === "reuse" && multiGate.registration && multiGate.registration.source === "sidecar") {
+            console.log(`[open-gate] REHYDRATED registration for ${workspaceDir} from sidecar (ws '${multiGate.ownerWorkspaceId}', tenant '${multiGate.ownerTenantId || "unknown"}') - reusing existing clones`);
+        }
+
+        // Validate EVERY repo entry before touching the filesystem (400, nothing cloned).
+        let plan;
+        try {
+            plan = planRepos(repos, { workspaceDir, confineToRoot });
+        } catch (planErr) {
+            return res.status(planErr.httpStatus || 400).json({ ok: false, error: planErr.message });
+        }
+
+        await fsPromises.mkdir(workspaceDir, { recursive: true });
+
+        // REGISTRATION-FIRST (QA 2026-09-22): register the workspace dir (and
+        // write its sidecar) BEFORE cloning. Previously registration happened
+        // only after a fully successful loop, so any failed hydration left an
+        // UNREGISTERED dir on disk; the next open classified it as an orphan,
+        // rm -rf'd the N repos already cloned and re-cloned everything just to
+        // fail on the same repo again (self-perpetuating, 10 clones per scan).
+        try { await wsManager.open(wsId, workspaceDir, { tenantId: openTenantId }); } catch (err) {
+            console.warn(`WorkspaceManager.open failed (non-fatal): ${err.message}`);
+        }
+
+        // PARTIAL TOLERANCE (QA 2026-09-22): one repo the token cannot see
+        // ("Repository not found") must not discard the other N-1 clones.
+        // MULTI_REPO_ALLOW_PARTIAL=false restores the pre-fix fail-all loop.
+        const allowPartial = multiRepoAllowPartial(process.env);
+        let cloned, failed, firstError;
+        try {
+            ({ cloned, failed, firstError } = await hydrateRepos(plan, {
+                cloneRepo: cloneOrUpdateRepo,
+                detectProject,
+                mkdir: (d) => fsPromises.mkdir(d, { recursive: true }),
+                // a failed clone must not leave an empty per-repo dir behind
+                // (an existing clone that failed to REFRESH keeps its .git).
+                cleanupFailed: async (d) => {
+                    if (!(await exists(path.join(d, '.git')))) await fsPromises.rm(d, { recursive: true, force: true });
+                },
+                maskUrlCreds,
+                token, branch, allowPartial, wsId
+            }));
+        } catch (gitErr) {
+            // allowPartial=false: first failure aborts the loop (old behavior).
+            cloned = []; failed = []; firstError = gitErr;
+        }
+
+        if (cloned.length === 0) {
+            const gitErr = firstError || new Error("no repo could be cloned");
+            console.error(`[multi-repo] clone failed (0 of ${plan.length} cloned):`, maskUrlCreds(gitErr.message));
+            // Nothing usable was hydrated. If THIS open created the dir
+            // (fresh / cleaned orphan): unregister + remove it so it is neither
+            // a registered-but-empty workspace nor an orphan on disk. On a
+            // REUSE all-fail (e.g. transient network during refresh) the
+            // previously hydrated clones stay registered and are retried next open.
+            if (multiGate.action !== "reuse") {
+                wsManager.close(wsId);
+                if (isSafeToRemove(cacheDir, workspaceDir)) {
+                    await fsPromises.rm(workspaceDir, { recursive: true, force: true }).catch(() => {});
+                }
+            }
+            // REFSPEC FIX: a missing/invalid REQUESTED branch is a clear client
+            // error, not a generic 500 (fetchRequestedRef tags it).
+            if (gitErr && (gitErr.code === "BRANCH_NOT_FOUND" || gitErr.code === "INVALID_BRANCH")) {
+                return res.status(gitErr.httpStatus || 500).json({ ok: false, error: gitErr.message, ...(failed.length ? { failed } : {}) });
+            }
+            // SEG-1: the message embeds the authenticated clone URL — mask the
+            // credential before it reaches the response body.
+            return res.status(500).json({
+                ok: false,
+                error: maskUrlCreds(gitErr.message),
+                hint: "Clone failed. Check repo URLs and tokens.",
+                ...(failed.length ? { failed } : {})
+            });
+        }
+
+        // ENG-1: total files across ALL cloned repo dirs (excl. .git). 0 => every
+        // repo of this workspace cloned empty => structural empty clone. We keep
+        // ok:true and surface fileCount/empty so the GATEWAY hard-stops the run
+        // (single decision point) instead of silently proceeding with 0 files.
+        let fileCount = 0;
+        try {
+            for (const c of cloned) fileCount += countFilesExcludingGit(c.path);
+        } catch (err) {
+            console.warn(`countFilesExcludingGit failed (non-fatal): ${err.message}`);
+        }
+        if (fileCount === 0) {
+            console.error(`[multi-repo] EMPTY CLONE: 0 files across ${cloned.length} repo(s) under ${wsId}`);
+        }
+        return res.json({
+            ok: true,
+            root: workspaceDir,      // the sandbox root = the workspace dir (parent of the repos)
+            workspaceId: wsId,
+            mode: "cloud-multi-clone",
+            repos: cloned,
+            partial: failed.length > 0,
+            failed,                  // [{dir, repoUrl (masked), error (masked)}]
+            port: null,
+            fileCount,
+            ...(fileCount === 0 ? { empty: true } : {})
+        });
+    }
 
     // ==========================================
     // CLOUD MODE: Git clone (when Gateway sends repoUrl)
     // ==========================================
     if (repoUrl) {
-        console.log(`[/workspace/open] CLOUD MODE  cloning ${repoUrl} (branch: ${branch})`);
+        console.log(`[/workspace/open] CLOUD MODE  cloning ${maskUrlCreds(repoUrl)} (branch: ${branch})`);
 
         try {
             // Extract repo name: https://github.com/org/repo  org_repo
@@ -838,6 +1191,32 @@ app.post("/workspace/open", async (req, res) => {
             // Ensure cache directory exists
             await fsPromises.mkdir(cacheDir, { recursive: true });
 
+            // OPEN GATE (2026-07-20, QA-proven): an open with repoUrl is a
+            // HYDRATION request - it must never 500 on a stale clone dir left
+            // by a previous revision (registry lost on restart => the dir is
+            // an ORPHAN; its git state may be broken, e.g. "ambiguous
+            // argument 'origin/main'" on the reuse path). Orphans are removed
+            // and the repo is cloned fresh, then registered with the request
+            // tenant. A dir REGISTERED for ANOTHER tenant is never touched:
+            // clear 409 instead of a generic 500. Registered same/unknown
+            // tenant keeps the byte-identical reuse/refresh path below.
+            const openGate = classifyOpenDestination(clonePath, {
+                registry: wsManager.list(),
+                requestTenantId: openTenantId
+            });
+            if (openGate.action === "deny") {
+                console.warn(`[open-gate] DENY open: ${clonePath} is registered for another tenant (ws '${openGate.ownerWorkspaceId}') - request tenant '${openTenantId}'`);
+                return res.status(409).json({
+                    ok: false,
+                    error: "workspace_dir_owned_by_another_tenant",
+                    hint: "The clone destination on this agent is registered for a different tenant. Use a distinct workspaceId."
+                });
+            }
+            if (openGate.action === "clean_and_fresh" && isSafeToRemove(cacheDir, clonePath)) {
+                console.warn(`[open-gate] ORPHAN dir at ${clonePath} (no registered workspace) - removing stale clone and cloning fresh`);
+                await fsPromises.rm(clonePath, { recursive: true, force: true });
+            }
+
             // Build authenticated URL
             // Token formats:
             //   GitHub:    TOKEN (uses x-access-token:TOKEN@)
@@ -866,16 +1245,57 @@ app.post("/workspace/open", async (req, res) => {
                 // Update remote URL with fresh token
                 await execAsync(`git remote set-url origin "${authUrl}"`, { cwd: clonePath }).catch(() => {});
                 await execAsync(`git fetch origin`, { cwd: clonePath, timeout: 120000 });
+                // REFSPEC FIX (QA 2026-07-20, PR #13 review FAILED) composed
+                // with main's default-branch fallback (PR #4): the clone below
+                // is --single-branch, so on reuse `git fetch origin` never
+                // brings branches born AFTER the clone; the checkout error was
+                // swallowed and `git reset --hard origin/<branch>` died with
+                // "ambiguous argument ... unknown revision" -> 500. Fetch the
+                // requested ref explicitly first; if the branch is absent on
+                // the remote, fall back to the repo's real default branch.
+                let effBranch = branch;
+                try {
+                    await fetchRequestedRef(execAsync, branch, clonePath);
+                } catch (refErr) {
+                    if (refErr && refErr.code === 'BRANCH_NOT_FOUND') {
+                        const defBranch = await resolveDefaultBranch(clonePath);
+                        if (defBranch) {
+                            console.warn(`[cloud] Branch '${branch}' not on remote — using default '${defBranch}'`);
+                            effBranch = defBranch;
+                        } else {
+                            throw refErr;
+                        }
+                    } else {
+                        throw refErr;
+                    }
+                }
                 // Checkout correct branch and reset to remote (discard previous patches)
-                await execAsync(`git checkout ${branch} 2>/dev/null || git checkout -b ${branch} origin/${branch}`, { cwd: clonePath }).catch(() => {});
-                await execAsync(`git reset --hard origin/${branch}`, { cwd: clonePath });
-                console.log(`[cloud] Updated to latest ${branch}`);
+                await execAsync(`git checkout ${effBranch} 2>/dev/null || git checkout -b ${effBranch} origin/${effBranch}`, { cwd: clonePath }).catch(() => {});
+                await execAsync(`git reset --hard origin/${effBranch}`, { cwd: clonePath });
+                console.log(`[cloud] Updated to latest ${effBranch}`);
             } else {
-                console.log(`[cloud] Cloning ${repoUrl} (branch: ${branch})...`);
-                await execAsync(
-                    `git clone --branch ${branch} --single-branch --depth 50 "${authUrl}" "${clonePath}"`,
-                    { timeout: 300000 }
-                );
+                console.log(`[cloud] Cloning ${maskUrlCreds(repoUrl)} (branch: ${branch})...`);
+                try {
+                    await execAsync(
+                        `git clone --branch ${branch} --single-branch --depth 50 "${authUrl}" "${clonePath}"`,
+                        { timeout: 300000 }
+                    );
+                } catch (cloneErr) {
+                    // Requested branch may not exist (e.g. repo uses master, caller assumed main).
+                    // Git phrases this as "Remote branch <x> not found in upstream origin" or
+                    // "could not find remote branch" depending on version — match both.
+                    // Fall back to the repo's default branch instead of failing the session.
+                    if (/(remote branch .* not found|could not find remote branch)/i.test(cloneErr.message || '')) {
+                        console.warn(`[cloud] Branch '${branch}' not found — falling back to the repo default branch`);
+                        await execAsync(`rm -rf "${clonePath}"`).catch(() => {});
+                        await execAsync(
+                            `git clone --single-branch --depth 50 "${authUrl}" "${clonePath}"`,
+                            { timeout: 300000 }
+                        );
+                    } else {
+                        throw cloneErr;
+                    }
+                }
                 // Configure git user for future commits
                 await execAsync(`git config user.email "deepdebug-ai@deepdebug.ai"`, { cwd: clonePath });
                 await execAsync(`git config user.name "DeepDebug AI"`, { cwd: clonePath });
@@ -888,30 +1308,46 @@ app.post("/workspace/open", async (req, res) => {
                 WORKSPACE_ROOT = clonePath;
             }
             const wsId = workspaceId || "default";
-            try { await wsManager.open(wsId, clonePath); } catch (err) {
+            try { await wsManager.open(wsId, clonePath, { tenantId: openTenantId }); } catch (err) {
                 console.warn(`WorkspaceManager.open failed (non-fatal): ${err.message}`);
             }
 
             const meta = await detectProject(clonePath);
             const port = await detectPort(clonePath);
 
+            // ENG-1: files under the clone (excl. .git). 0 => empty repo / wrong
+            // branch. Keep ok:true and report fileCount/empty; the GATEWAY makes
+            // the hard-stop decision (avoids silent "NEEDS_REVIEW, 0 files read").
+            const fileCount = countFilesExcludingGit(clonePath);
+            if (fileCount === 0) {
+                console.error(`[cloud] EMPTY CLONE: 0 files at ${clonePath} for ${maskUrlCreds(repoUrl)} (branch ${branch})`);
+            }
+
             return res.json({
                 ok: true,
                 root: clonePath,
                 workspaceId: wsId,
                 mode: "cloud-clone",
                 meta,
-                port
+                port,
+                fileCount,
+                ...(fileCount === 0 ? { empty: true } : {})
             });
 
         } catch (gitErr) {
-            console.error(`[cloud] Git clone failed:`, gitErr.message);
+            console.error(`[cloud] Git clone failed:`, maskUrlCreds(gitErr.message));
+            // REFSPEC FIX: a missing/invalid REQUESTED branch is a clear client
+            // error, not a generic 500 (fetchRequestedRef tags it).
+            if (gitErr && (gitErr.code === "BRANCH_NOT_FOUND" || gitErr.code === "INVALID_BRANCH")) {
+                return res.status(gitErr.httpStatus || 500).json({ ok: false, error: gitErr.message });
+            }
             const hint = gitErr.message.includes('Authentication') || gitErr.message.includes('could not read')
                 ? "Authentication failed. Check token and repo URL."
                 : gitErr.message.includes('not found') || gitErr.message.includes('does not exist')
                     ? "Repository not found. Check the URL."
                     : "Clone failed. Ensure the URL is accessible.";
-            return res.status(500).json({ ok: false, error: gitErr.message, hint });
+            // SEG-1: mask the authenticated clone URL in the response body too.
+            return res.status(500).json({ ok: false, error: maskUrlCreds(gitErr.message), hint });
         }
     }
 
@@ -930,7 +1366,7 @@ app.post("/workspace/open", async (req, res) => {
         WORKSPACE_ROOT = abs;
     }
     try {
-        await wsManager.open(wsId, abs);
+        await wsManager.open(wsId, abs, { tenantId: openTenantId });
     } catch (err) {
         console.warn(`WorkspaceManager open failed (non-fatal): ${err.message}`);
     }
@@ -961,8 +1397,20 @@ app.post("/workspace/clone", async (req, res) => {
 
     if (!gitUrl) return res.status(400).json({ ok: false, error: "gitUrl is required" });
 
+    // SECURITY: gitUrl/branch were interpolated into a shell string (command
+    // injection via "$(...)" or ";"), tenantId into a filesystem path (../
+    // traversal), and file:// / local paths were clonable (reads arbitrary
+    // host repos). Validate, then run git via execFile (no shell).
+    const gitUrlCheck = validateGitUrl(gitUrl);
+    if (!gitUrlCheck.ok) return res.status(400).json({ ok: false, error: gitUrlCheck.reason });
+    if (branch && !isSafeBranchName(branch)) return res.status(400).json({ ok: false, error: "invalid branch name" });
+    if (tenantId && !isSafeTenantId(tenantId)) return res.status(400).json({ ok: false, error: "invalid tenantId" });
+
     // Strip ALL trailing .git suffixes (handles accidental double .git.git from frontend)
     const repoName = gitUrl.split('/').pop().replace(/\.git$/i, '').replace(/\.git$/i, '');
+    if (!repoName || repoName === '.' || repoName === '..' || /[\\/]/.test(repoName)) {
+        return res.status(400).json({ ok: false, error: "cannot derive repository name from gitUrl" });
+    }
 
     const NFS_MOUNT = '/mnt/workspaces';
     let absTarget;
@@ -992,7 +1440,7 @@ app.post("/workspace/clone", async (req, res) => {
             authenticatedUrl = cleanGitUrl.replace('https://', `https://x-access-token:${gitToken}@`);
         }
     }
-    console.log(`Clone request: ${cleanGitUrl} -> ${absTarget}`);
+    console.log(`Clone request: ${maskUrlCreds(cleanGitUrl)} -> ${absTarget}`);
 
     try {
         // Ensure parent directory exists
@@ -1008,18 +1456,18 @@ app.post("/workspace/clone", async (req, res) => {
             console.log(`Repo already exists at ${absTarget}, updating branch: ${targetBranch}...`);
             await execAsync('git fetch --all', { cwd: absTarget, timeout: 60000 });
             try {
-                await execAsync(`git checkout ${targetBranch}`, { cwd: absTarget, timeout: 30000 });
-                const { stdout } = await execAsync(`git pull origin ${targetBranch}`, { cwd: absTarget, timeout: 120000 });
+                await execFileAsync('git', ['checkout', targetBranch], { cwd: absTarget, timeout: 30000 });
+                const { stdout } = await execFileAsync('git', ['pull', 'origin', targetBranch], { cwd: absTarget, timeout: 120000 });
                 console.log(`git pull: ${stdout.trim()}`);
             } catch (checkoutErr) {
                 console.warn(`Checkout ${targetBranch} failed, staying on current branch: ${checkoutErr.message}`);
             }
         } else {
             const safeLog = authenticatedUrl.replace(/x-token-auth:[^@]+@/g, 'x-token-auth:***@').replace(/oauth2:[^@]+@/g, 'oauth2:***@').replace(/x-access-token:[^@]+@/g, 'x-access-token:***@');
-            const cloneCmd = branch ? `git clone -b ${branch} "${authenticatedUrl}" "${absTarget}"` : `git clone "${authenticatedUrl}" "${absTarget}"`;
+            const cloneArgs = branch ? ['clone', '-b', branch, '--', authenticatedUrl, absTarget] : ['clone', '--', authenticatedUrl, absTarget];
             console.log(`Running: git clone${branch ? ' -b ' + branch : ''} "${safeLog}" "${absTarget}"`);
             const cloneEnvWorkspace = { ...process.env, GIT_TERMINAL_PROMPT: "0", HOME: process.env.HOME || "/tmp" };
-            await execAsync(cloneCmd, { timeout: 300000, env: cloneEnvWorkspace });
+            await execFileAsync('git', cloneArgs, { timeout: 300000, env: cloneEnvWorkspace });
             console.log(`Clone complete: ${absTarget}`);
         }
 
@@ -1029,7 +1477,9 @@ app.post("/workspace/clone", async (req, res) => {
             WORKSPACE_ROOT = absTarget;
         }
         try {
-            await wsManager.open(wsId, absTarget);
+            // TENANT GATE (ROOT-RECOVERY): register the tenant this clone is
+            // hydrated for so recovery can refuse cross-tenant basename hits.
+            await wsManager.open(wsId, absTarget, { tenantId: tenantId || null });
         } catch (err) {
             console.warn(`WorkspaceManager.open failed (non-fatal): ${err.message}`);
         }
@@ -1047,17 +1497,17 @@ app.post("/workspace/clone", async (req, res) => {
         });
 
     } catch (err) {
-        console.error(`Clone failed: ${err.message}`);
+        console.error(`Clone failed: ${maskUrlCreds(err.message)}`);
         const hint = err.message.includes('Authentication') || err.message.includes('could not read')
             ? "Authentication failed. Ensure the repo is public or GitHub integration is configured."
             : err.message.includes('not found') || err.message.includes('does not exist')
                 ? "Repository not found. Check the URL is correct."
                 : "Clone failed. Ensure git is installed and the URL is accessible.";
-        res.status(500).json({ ok: false, error: err.message, hint });
+        res.status(500).json({ ok: false, error: maskUrlCreds(err.message), hint });
     }
 });
 
-/** Info do workspace */
+/** Workspace info */
 app.get("/workspace/info", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
@@ -1066,7 +1516,7 @@ app.get("/workspace/info", async (req, res) => {
     res.json({ root: wsRoot, meta, port });
 });
 
-/** Scan completo do workspace */
+/** Full workspace scan */
 app.get("/workspace/scan", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
@@ -1112,17 +1562,42 @@ app.get("/workspace/analyze", async (req, res) => {
     }
 });
 
-/** L contedo de arquivo especfico */
+/** Reads the content of a specific file */
 app.get("/workspace/file-content", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
 
+    // ROOT-RECOVERY fail-fast: the effective root does not exist on this agent
+    // at all (dead persisted path, no live clone to recover). Tell the caller
+    // EXACTLY what to do instead of a generic 404 the AI retries forever.
+    if (!fs.existsSync(wsRoot)) {
+        return res.status(404).json({
+            error: "workspace_root_not_hydrated",
+            root: wsRoot,
+            hint: "This agent has no clone at that path. Run git_prepare_workspace "
+                + "(POST /workspace/clone) for this workspace first, then retry."
+        });
+    }
+
     const { path: relativePath } = req.query;
     if (!relativePath) return res.status(400).json({ error: "path query param required" });
 
     try {
         const reader = new FileReader(wsRoot);
         const file = await reader.read(relativePath);
+        // RANGED READS (Claude Code model, 2026-07-19): huge files (this repo's
+        // own server.js is 7500+ lines) used to be returned WHOLE, blowing the
+        // AI's context/tool-result budget - the model then burned its whole
+        // iteration budget extracting chunks via `sed` in run_command. Pure
+        // slicing logic in utils/ranged-read.js (guard-tested); small files
+        // without a range keep the byte-identical original response.
+        const sliced = sliceFileContent(file, {
+            startLine: parseInt(req.query.startLine, 10),
+            endLine: parseInt(req.query.endLine, 10),
+            lineCap: parseInt(process.env.FILE_CONTENT_LINE_CAP || "2000", 10)
+        });
+        if (sliced) return res.json(sliced);
+
         res.json(file);
     } catch (err) {
         res.status(404).json({ error: "file not found", details: err.message });
@@ -1152,6 +1627,10 @@ app.post("/workspace/build-push", async (req, res) => {
     };
 
     try {
+        if (!isSafeTenantId(workspaceId)) {
+            emit("error", { error: "invalid workspaceId" });
+            return res.end();
+        }
         const nfsBase = process.env.WORKSPACES_MOUNT || "/mnt/workspaces";
         const wsPath = path.join(nfsBase, workspaceId);
 
@@ -1199,15 +1678,11 @@ app.post("/workspace/build-push", async (req, res) => {
 
         // Step 2: Compress workspace to tar.gz
         emit("progress", "Compressing source code...");
-        const { execSync } = await import("child_process");
+        const { execFileSync } = await import("child_process");
         const tarPath = `/tmp/source-${workspaceId}-${Date.now()}.tar.gz`;
         try {
-            execSync(
-                `tar -czf "${tarPath}" --exclude=".git" --exclude="node_modules" ` +
-                `--exclude="target" --exclude="*.class" --exclude=".gradle" ` +
-                `-C "${wsPath}" . 2>&1`,
-                { stdio: "pipe", timeout: 120000 }
-            );
+            // No shell: workspaceId is validated above and paths are argv entries.
+            execFileSync("tar", buildTarArgs({ tarPath, wsPath }), { stdio: "pipe", timeout: 120000 });
             const sizeKB = Math.round(fs.statSync(tarPath).size / 1024);
             emit("progress", `Source compressed: ${sizeKB}KB`);
         } catch (e) {
@@ -1338,6 +1813,12 @@ app.post("/workspace/setup", async (req, res) => {
     if (!workspaceId || !repoUrl) {
         return res.status(400).json({ error: "workspaceId and repoUrl required" });
     }
+    // SECURITY (2026-10-11): workspaceId became a path segment under the NFS
+    // base (../ traversal + rmSync of the escaped dir) and repoUrl was
+    // interpolated into a shell string. Validate, then run git via execFile.
+    if (!isSafeTenantId(workspaceId)) return res.status(400).json({ error: "invalid workspaceId" });
+    const repoUrlCheck = validateGitUrl(repoUrl);
+    if (!repoUrlCheck.ok) return res.status(400).json({ error: repoUrlCheck.reason });
 
     res.setHeader("Content-Type", "text/event-stream");
     res.setHeader("Cache-Control", "no-cache");
@@ -1375,30 +1856,33 @@ app.post("/workspace/setup", async (req, res) => {
                 authUrl = urlObj.toString();
                 emit("progress", `Using authenticated clone for ${urlObj.hostname} (auth=${authUser})`);
             } catch {
-                authUrl = repoUrl.replace("https://", `https://${authUser}:${gitToken}@`);
-                emit("progress", `Using authenticated clone (fallback, auth=${authUser})`);
+                emit("error", "repoUrl must be an https URL when a gitToken is supplied");
+                return res.end();
             }
         }
 
-        const { execSync } = await import("child_process");
+        const { execFileSync } = await import("child_process");
         const cloneEnv = { ...process.env, GIT_TERMINAL_PROMPT: "0", HOME: process.env.HOME || "/tmp" };
         const execOpts = { stdio: "pipe", timeout: 300000, encoding: "utf8", env: cloneEnv };
+        // No shell: arguments are passed as an argv array.
+        const execSync = (argv, o = execOpts) => execFileSync("git", argv, o);
         let cloneBranch = "main";
 
         // Configure safe directory
-        try { execSync(`git config --global --add safe.directory "${wsPath}"`, execOpts); } catch {}
+        try { execSync(["config", "--global", "--add", "safe.directory", wsPath]); } catch {}
 
         if (fs.existsSync(path.join(wsPath, ".git"))) {
             emit("progress", "Workspace exists, updating...");
             try {
                 if (gitToken && gitToken.length > 5) {
-                    execSync(`git remote set-url origin "${authUrl}"`, { ...execOpts, cwd: wsPath });
+                    execSync(["remote", "set-url", "origin", authUrl], { ...execOpts, cwd: wsPath });
                 }
-                execSync("git fetch origin", { ...execOpts, cwd: wsPath });
-                cloneBranch = execSync("git branch --show-current", { ...execOpts, cwd: wsPath }).trim() || "main";
-                execSync(`git reset --hard origin/${cloneBranch}`, { ...execOpts, cwd: wsPath });
+                execSync(["fetch", "origin"], { ...execOpts, cwd: wsPath });
+                cloneBranch = execSync(["branch", "--show-current"], { ...execOpts, cwd: wsPath }).trim() || "main";
+                if (!isSafeBranchName(cloneBranch)) throw new Error("unsafe current branch name");
+                execSync(["reset", "--hard", `origin/${cloneBranch}`], { ...execOpts, cwd: wsPath });
             } catch (e) {
-                const safeMsg = gitToken ? e.message.replace(gitToken, "***") : e.message;
+                const safeMsg = maskUrlCreds(e.message);
                 emit("progress", `Update failed (${safeMsg.substring(0, 100)}), re-cloning...`);
                 fs.rmSync(wsPath, { recursive: true, force: true });
             }
@@ -1414,13 +1898,16 @@ app.post("/workspace/setup", async (req, res) => {
             for (const b of ["main", "master", "develop"]) {
                 try {
                     emit("progress", `Trying branch: ${b}...`);
-                    execSync(`git clone --depth=1 --branch ${b} "${authUrl}" "${wsPath}"`, execOpts);
+                    execSync(["clone", "--depth=1", "--branch", b, "--", authUrl, wsPath]);
                     cloneBranch = b;
                     emit("progress", `Cloned on branch: ${b}`);
                     break;
                 } catch (e) {
                     const stderr = (e.stderr || e.stdout || e.message || "").toString();
-                    const safeMsg = gitToken ? stderr.replace(new RegExp(gitToken, 'g'), "***") : stderr;
+                    // maskUrlCreds is token-agnostic and cannot throw; the previous
+                    // new RegExp(gitToken) both missed non-URL repeats and could throw
+                    // on regex-special chars in the token.
+                    const safeMsg = maskUrlCreds(stderr);
                     console.warn(`[Clone] Branch ${b} failed: ${safeMsg.substring(0, 500)}`);
                     emit("progress", `Branch ${b} failed: ${safeMsg.substring(0, 200)}`);
                     // Clean up partial clone
@@ -1432,12 +1919,15 @@ app.post("/workspace/setup", async (req, res) => {
             if (!fs.existsSync(path.join(wsPath, ".git"))) {
                 try {
                     emit("progress", "Trying default branch...");
-                    execSync(`git clone --depth=1 "${authUrl}" "${wsPath}" 2>&1`, execOpts);
-                    cloneBranch = execSync("git branch --show-current", { ...execOpts, cwd: wsPath }).trim() || "main";
+                    execSync(["clone", "--depth=1", "--", authUrl, wsPath]);
+                    cloneBranch = execSync(["branch", "--show-current"], { ...execOpts, cwd: wsPath }).trim() || "main";
                     emit("progress", `Cloned on default branch: ${cloneBranch}`);
                 } catch (e) {
                     const stderr = (e.stderr || e.stdout || e.message || "").toString();
-                    const safeMsg = gitToken ? stderr.replace(new RegExp(gitToken, 'g'), "***") : stderr;
+                    // maskUrlCreds is token-agnostic and cannot throw; the previous
+                    // new RegExp(gitToken) both missed non-URL repeats and could throw
+                    // on regex-special chars in the token.
+                    const safeMsg = maskUrlCreds(stderr);
                     console.error(`[Clone] Default branch failed: ${safeMsg.substring(0, 500)}`);
                     emit("progress", `Default branch failed: ${safeMsg.substring(0, 200)}`);
                     if (fs.existsSync(wsPath)) fs.rmSync(wsPath, { recursive: true, force: true });
@@ -1521,7 +2011,7 @@ app.post("/workspace/detect", async (req, res) => {
     }
 });
 
-/** Escreve/salva conteudo de arquivo no workspace */
+/** Writes/saves file content to the workspace */
 app.post("/workspace/write-file", async (req, res) => {
     const workspaceRoot = resolveWorkspaceRoot(req);
     if (!workspaceRoot) return res.status(400).json({ error: "workspace not set" });
@@ -1531,11 +2021,17 @@ app.post("/workspace/write-file", async (req, res) => {
     if (fileContent === undefined || fileContent === null) return res.status(400).json({ error: "content is required" });
 
     const pathMod = await import('path');
-    const fullPath = pathMod.default.resolve(workspaceRoot, relativePath);
-
-    // Security: prevent path traversal outside workspace root
-    if (!fullPath.startsWith(workspaceRoot)) {
-        return res.status(403).json({ error: "Path traversal not allowed" });
+    // SEG-3: realpath + separator-aware containment (the old `startsWith(root)`
+    // let siblings like `<root>-2` and `..`-traversal through).
+    let fullPath;
+    try {
+        fullPath = confineToRoot(workspaceRoot, relativePath);
+    } catch (e) {
+        if (e instanceof SandboxViolation) {
+            console.warn(`[WRITE-FILE] SANDBOX DENIED: ${relativePath} (${e.details?.resolved})`);
+            return res.status(403).json({ error: "path escapes the workspace sandbox" });
+        }
+        throw e;
     }
 
     try {
@@ -1550,7 +2046,7 @@ app.post("/workspace/write-file", async (req, res) => {
 
 
 
-/** L mltiplos arquivos */
+/** Reads multiple files */
 app.post("/workspace/batch-read", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
@@ -1589,7 +2085,7 @@ app.get("/workspace/file-exists", async (req, res) => {
     }
 
     try {
-        const fullPath = path.join(wsRoot, relativePath);
+        const fullPath = confineToRoot(wsRoot, relativePath); // SEG-3
         const fileExists = await exists(fullPath);
 
         console.log(`[file-exists] ${relativePath} -> ${fileExists ? 'EXISTS' : 'NOT FOUND'}`);
@@ -1602,6 +2098,9 @@ app.get("/workspace/file-exists", async (req, res) => {
         });
     } catch (err) {
         console.error(`[file-exists] Error:`, err.message);
+        if (err instanceof SandboxViolation) {
+            return res.status(403).json({ ok: false, error: "path escapes the workspace sandbox" });
+        }
         res.status(500).json({ ok: false, error: err.message });
     }
 });
@@ -1624,7 +2123,7 @@ app.post("/workspace/validate-paths", async (req, res) => {
     try {
         const results = await Promise.all(
             pathList.map(async (relativePath) => {
-                const fullPath = path.join(wsRoot, relativePath);
+                const fullPath = confineToRoot(wsRoot, relativePath); // SEG-3
                 const fileExists = await exists(fullPath);
                 return { path: relativePath, exists: fileExists };
             })
@@ -1648,6 +2147,50 @@ app.post("/workspace/validate-paths", async (req, res) => {
     }
 });
 
+/**
+ * GET /workspace/detect-stack
+ * PASSO 0 of the fix validation ladder: resolve {stack, tier, language,
+ * buildTool} for this workspace so the engine can pick validators without
+ * any language logic of its own.
+ */
+app.get("/workspace/detect-stack", async (req, res) => {
+    const wsRoot = resolveWorkspaceRoot(req);
+    if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
+    try {
+        const result = await detectBuildTool(wsRoot);
+        console.log(`[detect-stack] ${wsRoot} -> stack=${result.stack} tier=${result.tier}`);
+        res.json({ ok: true, ...result });
+    } catch (err) {
+        console.error("[detect-stack] Error:", err.message);
+        res.status(500).json({ ok: false, error: err.message });
+    }
+});
+
+/**
+ * POST /workspace/validate  { paths: [relativePath...] }
+ * Camada 2 (SyntaxValidator) of the fix validation ladder: parse-only
+ * validation of the given files. Per-extension resolution (typescript for
+ * JS/TS, tree-sitter for Swift); files without a validator come back as
+ * {validator:"none", ok:true} — the tier degrades, it never blocks.
+ */
+app.post("/workspace/validate", async (req, res) => {
+    const wsRoot = resolveWorkspaceRoot(req);
+    if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
+    const { paths: pathList } = req.body || {};
+    if (!pathList || !Array.isArray(pathList)) {
+        return res.status(400).json({ error: "paths array required in body" });
+    }
+    try {
+        const results = await validateFiles(wsRoot, pathList.slice(0, 50));
+        const failed = results.filter(r => !r.ok);
+        console.log(`[validate] ${results.length} file(s), ${failed.length} with syntax problems`);
+        res.json({ ok: true, allValid: failed.length === 0, results });
+    } catch (err) {
+        console.error("[validate] Error:", err.message);
+        res.status(500).json({ ok: false, error: err.message });
+    }
+});
+
 /**
  * POST /workspace/search-file
  * Searches for a file by name in the workspace
@@ -1772,7 +2315,7 @@ app.post("/workspace/search-by-content", async (req, res) => {
             if (results.length >= maxResults * 2) break;
 
             try {
-                const fullPath = path.join(wsRoot, filePath);
+                const fullPath = confineToRoot(wsRoot, filePath); // SEG-3
                 const content = await readFile(fullPath, 'utf8');
                 const lines = content.split('\n');
 
@@ -1868,7 +2411,7 @@ app.post("/workspace/find-field-definition", async (req, res) => {
 
         for (const filePath of targetFiles) {
             try {
-                const fullPath = path.join(wsRoot, filePath);
+                const fullPath = confineToRoot(wsRoot, filePath); // SEG-3
                 const content = await readFile(fullPath, 'utf8');
                 const lines = content.split('\n');
 
@@ -1940,7 +2483,7 @@ app.post("/workspace/find-field-definition", async (req, res) => {
 //  RUNTIME MANAGEMENT ENDPOINTS
 // ============================================
 
-/** Detecta servios no workspace */
+/** Detects services in the workspace */
 app.get("/workspace/services/detect", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
@@ -1977,12 +2520,12 @@ app.get("/workspace/services/detect", async (req, res) => {
     }
 });
 
-/** Lista todos os servios */
+/** Lists all services */
 app.get("/workspace/services", (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
 
-    // Atualizar status dos servios com info do ProcessManager
+    // Update the service statuses with info from the ProcessManager
     const servicesWithStatus = DETECTED_SERVICES.map(service => {
         const status = processManager.getStatus(service.id);
         return {
@@ -1994,7 +2537,7 @@ app.get("/workspace/services", (req, res) => {
     res.json({ services: servicesWithStatus });
 });
 
-/** Inicia um servio */
+/** Starts a service */
 app.post("/workspace/services/:serviceId/start", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
@@ -2021,7 +2564,7 @@ app.post("/workspace/services/:serviceId/start", async (req, res) => {
     }
 });
 
-/** Para um servio */
+/** Stops a service */
 app.post("/workspace/services/:serviceId/stop", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
@@ -2036,7 +2579,7 @@ app.post("/workspace/services/:serviceId/stop", async (req, res) => {
     }
 });
 
-/** Retorna status de um servio */
+/** Returns the status of a service */
 app.get("/workspace/services/:serviceId/status", (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
@@ -2047,7 +2590,7 @@ app.get("/workspace/services/:serviceId/status", (req, res) => {
     res.json({ serviceId, ...status });
 });
 
-/** Retorna logs de um servio */
+/** Returns the logs of a service */
 app.get("/workspace/services/:serviceId/logs", (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
@@ -2075,7 +2618,7 @@ app.get("/workspace/services/:serviceId/logs/stream", (req, res) => {
     res.setHeader("Cache-Control", "no-cache");
     res.setHeader("Connection", "keep-alive");
 
-    // Enviar logs existentes
+    // Send existing logs
     const existingLogs = processManager.getLogs(serviceId);
     existingLogs.forEach(log => {
         res.write(`data: ${JSON.stringify(log)}\n\n`);
@@ -2090,7 +2633,7 @@ app.get("/workspace/services/:serviceId/logs/stream", (req, res) => {
 
     processManager.on("log", logHandler);
 
-    // Cleanup ao fechar conexo
+    // Cleanup when the connection closes
     req.on("close", () => {
         processManager.off("log", logHandler);
     });
@@ -2103,9 +2646,28 @@ app.get("/workspace/services/:serviceId/logs/stream", (req, res) => {
 app.get("/workspace/files", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
-    const { max = 5000 } = req.query;
-    const tree = await listRecursive(wsRoot, { maxFiles: Number(max) });
-    res.json({ root: wsRoot, count: tree.length, tree });
+    // CRASH-LOOP FIX (2026-07-20): this handler awaited listRecursive with NO
+    // try/catch. A dead root (indexer sending the NFS-era /mnt path) made the
+    // scandir ENOENT an UNHANDLED promise rejection - Node 20 kills the whole
+    // process, Cloud Run restarts it, the indexer retries, and the single QA
+    // agent instance crash-looped 503s for every tenant. Fail fast with the
+    // structured hint instead; and any other walk error answers 500 JSON -
+    // never a dead process.
+    if (!fs.existsSync(wsRoot)) {
+        return res.status(404).json({
+            error: "workspace_root_not_hydrated",
+            root: wsRoot,
+            hint: "This agent has no clone at that path. Run git_prepare_workspace "
+                + "(POST /workspace/clone) for this workspace first, then retry."
+        });
+    }
+    try {
+        const { max = 5000 } = req.query;
+        const tree = await listRecursive(wsRoot, { maxFiles: Number(max) });
+        res.json({ root: wsRoot, count: tree.length, tree });
+    } catch (err) {
+        res.status(500).json({ error: "workspace walk failed", details: String(err && err.message) });
+    }
 });
 
 app.get("/workspace/file", async (req, res) => {
@@ -2127,7 +2689,7 @@ app.post("/workspace/write", async (req, res) => {
     const { path: rel, content } = req.body || {};
     if (!rel) return res.status(400).json({ error: "path is required" });
     try {
-        const fullPath = path.join(wsRoot, rel);
+        const fullPath = confineToRoot(wsRoot, rel); // SEG-3
         await fsPromises.mkdir(path.dirname(fullPath), { recursive: true });
         await writeFile(fullPath, content ?? "", "utf8");
         res.json({ ok: true, path: rel, bytes: Buffer.byteLength(content ?? "", "utf8") });
@@ -2188,11 +2750,64 @@ app.post("/workspace/test", async (req, res) => {
     res.json({ root: wsRoot, meta, result });
 });
 
+/**
+ * POST /workspace/compile  (v2 — added 2026-06-03 for BYOC Phase 7.5+8)
+ *
+ * Compile-only path. Sibling of /workspace/test but with skipTests=true so
+ * the BYOC gateway can validate the build without paying the test runtime.
+ *
+ * The gateway's LocalAgentClient.compileAt + the operator-side compile path
+ * both target this endpoint. local-agent-full:v1 did NOT expose it, so
+ * 75-04 added an adapter that routed compile -> /workspace/test instead;
+ * once :v2 ships everywhere we can flip compileAt back to this URL.
+ *
+ * Response shape matches /workspace/test:
+ *   { root, meta, result: { code, stdout, stderr, duration } }
+ * plus top-level { ok, message, output, durationMs } convenience fields
+ * for callers that consume the simple shape.
+ */
+app.post("/workspace/compile", async (req, res) => {
+    const wsRoot = resolveWorkspaceRoot(req);
+    if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
+    const meta = await detectProject(wsRoot);
+    const result = await compileAndTest({
+        language: meta.language,
+        buildTool: meta.buildTool,
+        cwd: wsRoot,
+        skipTests: true,
+    });
+    const ok = result?.code === 0;
+    res.json({
+        ok,
+        message: ok ? "compile succeeded" : "compile failed",
+        output: result?.stdout || result?.stderr || "",
+        durationMs: result?.duration || 0,
+        root: wsRoot,
+        meta,
+        result,
+    });
+});
+
 app.post("/workspace/run", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
     if (!wsRoot) return res.status(400).json({ error: "workspace not set" });
     const { cmd, args = [] } = req.body || {};
     if (!cmd) return res.status(400).json({ error: "cmd is required" });
+    // SEG-3: cwd is pinned to the workspace root; reject any path argument that
+    // resolves outside it (e.g. `cat ../<other-workspace>/x`).
+    const argCheck = checkArgsWithinRoot(wsRoot, [cmd, ...args]);
+    if (!argCheck.ok) {
+        console.warn(`[workspace/run] SANDBOX DENIED arg: ${argCheck.arg} (${argCheck.resolved})`);
+        return res.status(403).json({ error: "command argument escapes the workspace sandbox", arg: argCheck.arg });
+    }
+    const runDecision = decideExec({
+        argv: [cmd, ...args].map(String), root: wsRoot, headers: req.headers, body: req.body || {},
+        vhSignature: req.vhSignature, signingCfg: SIGNING,
+    }, EXEC_POLICY);
+    if (!runDecision.allow) {
+        console.warn(`[workspace/run] POLICY DENIED: ${runDecision.reason}`);
+        return res.status(runDecision.status || 403).json(rejectionBody(runDecision));
+    }
     const out = await run(cmd, args, wsRoot, 5 * 60 * 1000);
     res.json(out);
 });
@@ -2201,16 +2816,9 @@ app.post("/workspace/run", async (req, res) => {
 //  TEST LOCAL ENDPOINTS
 // ============================================
 
-/** Store test local state */
-let TEST_LOCAL_STATE = {
-    status: "idle", // idle, compiling, compiled, starting, running, stopped, error
-    compilationResult: null,
-    serverProcess: null,
-    endpoints: [],
-    config: null,
-    testResults: [],
-    serverLogs: [] // Buffer circular de logs do servidor (ltimos 1000)
-};
+// TEST_LOCAL_STATE is declared once, early (see above) - it must exist before
+// the ProcessManager event listeners run. The endpoints below mutate that same
+// single object.
 
 // ============================================
 //  TEST LOCAL STATE ENDPOINTS (ADDED)
@@ -2269,19 +2877,19 @@ app.post("/workspace/git/prepare", async (req, res) => {
     console.log(`[git-prepare] Starting workspace preparation: wsRoot=${wsRoot} repoUrl=${repoUrl || 'none'}`);
 
     try {
-        const { execSync } = await import("child_process");
+        const { execFileSync } = await import("child_process");
         const execOpts = { encoding: "utf8", timeout: 120000, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } };
-        const execGit = (cmd) => {
+        // No shell: `cmd` is an argv array (git is the executable).
+        const execSync = (argv, o = execOpts) => execFileSync("git", argv, o);
+        const execGit = (argv) => {
             try {
-                return { ok: true, output: execSync(cmd, {
-                    cwd: wsRoot, ...execOpts
-                }).trim() };
+                return { ok: true, output: execSync(argv, { cwd: wsRoot, ...execOpts }).trim() };
             } catch (err) {
                 return { ok: false, output: (err.stderr || err.stdout || err.message || "unknown").toString().trim() };
             }
         };
 
-        execGit(`git config --global --add safe.directory "${wsRoot}"`);
+        execGit(["config", "--global", "--add", "safe.directory", wsRoot]);
 
         // If workspace is empty (no .git), clone first before attempting fetch/reset
         const gitDir = path.join(wsRoot, ".git");
@@ -2289,9 +2897,13 @@ app.post("/workspace/git/prepare", async (req, res) => {
             if (!repoUrl) {
                 return res.json({ ok: false, error: "Workspace is empty and no repoUrl provided for clone" });
             }
-            console.log(`[git-prepare] No .git found at ${wsRoot}, cloning from ${repoUrl}`);
+            console.log(`[git-prepare] No .git found at ${wsRoot}, cloning from ${maskUrlCreds(repoUrl)}`);
             fs.mkdirSync(wsRoot, { recursive: true });
 
+            // SECURITY (2026-10-11): repoUrl/branch reached a shell string.
+            const prepUrlCheck = validateGitUrl(repoUrl);
+            if (!prepUrlCheck.ok) return res.status(400).json({ ok: false, error: prepUrlCheck.reason });
+            if (reqBranch && !isSafeBranchName(reqBranch)) return res.status(400).json({ ok: false, error: "invalid branch name" });
             // Build authenticated URL
             let authUrl = repoUrl;
             if (gitToken) {
@@ -2313,24 +2925,24 @@ app.post("/workspace/git/prepare", async (req, res) => {
                 try {
                     fs.rmSync(wsRoot, { recursive: true, force: true });
                     fs.mkdirSync(wsRoot, { recursive: true });
-                    execSync(`git clone --depth 50 --branch "${b}" "${authUrl}" "${wsRoot}"`, execOpts);
+                    execSync(["clone", "--depth", "50", "--branch", b, "--", authUrl, wsRoot]);
                     clonedBranch = b;
                     cloned = true;
                     console.log(`[git-prepare] Cloned branch ${b} successfully`);
                     break;
                 } catch (cloneErr) {
-                    console.warn(`[git-prepare] Clone branch ${b} failed: ${(cloneErr.message || "").slice(0, 100)}`);
+                    console.warn(`[git-prepare] Clone branch ${b} failed: ${maskUrlCreds(cloneErr.message || "").slice(0, 100)}`);
                 }
             }
             if (!cloned) {
                 try {
                     fs.rmSync(wsRoot, { recursive: true, force: true });
                     fs.mkdirSync(wsRoot, { recursive: true });
-                    execSync(`git clone --depth 50 "${authUrl}" "${wsRoot}"`, execOpts);
+                    execSync(["clone", "--depth", "50", "--", authUrl, wsRoot]);
                     cloned = true;
                     clonedBranch = "default";
                 } catch (e) {
-                    return res.json({ ok: false, error: "Clone failed: " + (e.message || "").slice(0, 200) });
+                    return res.json({ ok: false, error: "Clone failed: " + maskUrlCreds(e.message || "").slice(0, 200) });
                 }
             }
 
@@ -2338,9 +2950,17 @@ app.post("/workspace/git/prepare", async (req, res) => {
             WORKSPACE_ROOT = wsRoot;
             try { await wsManager.open(workspaceId || path.basename(wsRoot), wsRoot); } catch (_) {}
 
-            const commit = execGit("git rev-parse --short HEAD");
-            let fileCount = 0;
-            try { function walk(d) { for (const e of fs.readdirSync(d, {withFileTypes:true})) { if (e.name==='.git') continue; if (e.isDirectory()) walk(path.join(d,e.name)); else fileCount++; } } walk(wsRoot); } catch (_) {}
+            const commit = execGit(["rev-parse", "--short", "HEAD"]);
+            const fileCount = countFilesExcludingGit(wsRoot);
+            // ENG-1 HARD-STOP: a clone that yields 0 files (excl. .git) is a
+            // structural failure (empty repo, wrong/empty branch, bad path).
+            // Fail closed instead of returning ok:true — the previous behaviour
+            // let the run continue and die later as "NEEDS_REVIEW, 0 files read".
+            if (fileCount === 0) {
+                console.error(`[git-prepare] EMPTY CLONE: 0 files after cloning branch ${clonedBranch} from ${maskUrlCreds(repoUrl)}`);
+                return res.json({ ok: false, empty: true, fileCount: 0, reason: "empty_clone",
+                    error: "Cloned repository has no files (empty repo or wrong branch)" });
+            }
             return res.json({ ok: true, cloned: true, mainBranch: clonedBranch,
                 currentCommit: commit.ok ? commit.output : "unknown", fileCount,
                 message: `Repository cloned: ${clonedBranch} (${fileCount} files)` });
@@ -2356,48 +2976,56 @@ app.post("/workspace/git/prepare", async (req, res) => {
             } else {
                 authUrl = repoUrl.replace(/https:\/\/([^@]*@)?/, `https://x-access-token:${gitToken}@`);
             }
-            execGit(`git remote set-url origin "${authUrl}"`);
+            execGit(["remote", "set-url", "origin", authUrl]);
         }
 
         console.log("[git-prepare] Fetching origin...");
-        execGit("git fetch origin --prune");
+        execGit(["fetch", "origin", "--prune"]);
 
         let mainBranch = null;
         for (const branch of ["main", "master", "develop", "dev"]) {
-            if (execGit(`git rev-parse --verify origin/${branch}`).ok) {
+            if (execGit(["rev-parse", "--verify", `origin/${branch}`]).ok) {
                 mainBranch = branch;
                 break;
             }
         }
         if (!mainBranch) {
-            const cur = execGit("git rev-parse --abbrev-ref HEAD");
-            mainBranch = cur.ok ? cur.output : "main";
+            const cur = execGit(["rev-parse", "--abbrev-ref", "HEAD"]);
+            mainBranch = cur.ok && isSafeBranchName(cur.output) ? cur.output : "main";
         }
 
-        const prevBranch = (execGit("git rev-parse --abbrev-ref HEAD").output || "unknown");
-        const prevCommit = (execGit("git rev-parse --short HEAD").output || "unknown");
+        const prevBranch = (execGit(["rev-parse", "--abbrev-ref", "HEAD"]).output || "unknown");
+        const prevCommit = (execGit(["rev-parse", "--short", "HEAD"]).output || "unknown");
 
         console.log(`[git-prepare] ${prevBranch}@${prevCommit} -> ${mainBranch}`);
 
-        let checkout = execGit(`git checkout ${mainBranch}`);
-        if (!checkout.ok) checkout = execGit(`git checkout -f ${mainBranch}`);
+        let checkout = execGit(["checkout", mainBranch]);
+        if (!checkout.ok) checkout = execGit(["checkout", "-f", mainBranch]);
         if (!checkout.ok) {
             return res.json({ ok: false, error: `Could not checkout ${mainBranch}: ${checkout.output}`,
                 mainBranch, previousBranch: prevBranch, previousCommit: prevCommit });
         }
 
-        execGit(`git reset --hard origin/${mainBranch}`);
-        execGit('git clean -fd --exclude="*.env" --exclude=".env*"');
+        execGit(["reset", "--hard", `origin/${mainBranch}`]);
+        execGit(["clean", "-fd", "--exclude=*.env", "--exclude=.env*"]);
 
-        const newCommit = (execGit("git rev-parse --short HEAD").output || "unknown");
-        console.log(`[git-prepare] Ready: ${mainBranch}@${newCommit}`);
+        const newCommit = (execGit(["rev-parse", "--short", "HEAD"]).output || "unknown");
+        // ENG-1 HARD-STOP: same structural check on the fetch/reset path — an
+        // already-cloned workspace that holds 0 files (excl. .git) is empty.
+        const fileCount = countFilesExcludingGit(wsRoot);
+        if (fileCount === 0) {
+            console.error(`[git-prepare] EMPTY WORKSPACE: 0 files after prepare on ${mainBranch}@${newCommit}`);
+            return res.json({ ok: false, empty: true, fileCount: 0, reason: "empty_clone",
+                error: "Prepared workspace has no files (empty repo or wrong branch)" });
+        }
+        console.log(`[git-prepare] Ready: ${mainBranch}@${newCommit} (${fileCount} files)`);
 
-        res.json({ ok: true, mainBranch, currentCommit: newCommit,
+        res.json({ ok: true, mainBranch, currentCommit: newCommit, fileCount,
             previousBranch: prevBranch, previousCommit: prevCommit,
             message: `Workspace prepared: on ${mainBranch} at ${newCommit}` });
     } catch (err) {
-        console.error("[git-prepare] Error:", err.message);
-        res.status(500).json({ ok: false, error: err.message });
+        console.error("[git-prepare] Error:", maskUrlCreds(err.message));
+        res.status(500).json({ ok: false, error: maskUrlCreds(err.message) });
     }
 });
 
@@ -2505,7 +3133,7 @@ app.post("/workspace/test-local/start", async (req, res) => {
         // Detect port if not provided
         let serverPort = port || 8080;
 
-        // Para Java, encontrar o JAR e correr directamente
+        // For Java, find the JAR and run it directly
         if (meta.language === 'java') {
             const targetDir = path.join(wsRoot, 'target');
 
@@ -2527,19 +3155,19 @@ app.post("/workspace/test-local/start", async (req, res) => {
 
             const jarPath = path.join(targetDir, jarFiles[0]);
 
-            // Comando EXACTO como no terminal (sem profiles!)
+            // EXACT command as in the terminal (no profiles!)
             const command = 'java';
             const args = ['-jar', jarPath, `--server.port=${serverPort}`];
 
             console.log(`Command: ${command} ${args.join(' ')}`);
 
-            // Env LIMPO - remover TODAS as variveis Spring que podem interferir
+            // CLEAN env - remove ALL Spring variables that could interfere
             const cleanEnv = { ...process.env };
             delete cleanEnv.SPRING_PROFILES_ACTIVE;
             delete cleanEnv.SPRING_DATASOURCE_URL;
             delete cleanEnv.SPRING_DATASOURCE_USERNAME;
             delete cleanEnv.SPRING_DATASOURCE_PASSWORD;
-            // Remover qualquer varivel que comece com SPRING_
+            // Remove any variable that starts with SPRING_
             Object.keys(cleanEnv).forEach(key => {
                 if (key.startsWith('SPRING_')) {
                     delete cleanEnv[key];
@@ -2698,7 +3326,13 @@ app.post("/workspace/test-local/execute", async (req, res) => {
 
     try {
         const serverPort = port || TEST_LOCAL_STATE.config?.server?.port || 8080;
-        const url = `http://localhost:${serverPort}${reqPath}`;
+        // Security: `${port}${path}` concatenation let path "@host/x" retarget the
+        // request to any host (SSRF). Build + validate a loopback URL instead.
+        const built = buildLocalTestUrl(serverPort, reqPath);
+        if (!built.ok) {
+            return res.status(400).json({ ok: false, error: built.reason });
+        }
+        const url = built.url;
 
         console.log(`[TEST-LOCAL] Executing: ${method} ${url}`);
 
@@ -2716,7 +3350,7 @@ app.post("/workspace/test-local/execute", async (req, res) => {
             fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
         }
 
-        const response = await fetch(url, fetchOptions);
+        const response = await fetch(url, { ...fetchOptions, redirect: "manual" });
         const duration = Date.now() - startTime;
 
         let responseBody;
@@ -2983,7 +3617,7 @@ app.post("/workspace/safe-patch", async (req, res) => {
         const backupFiles = [];
 
         for (const relPath of targetFiles) {
-            const fullPath = path.join(wsRoot, relPath);
+            const fullPath = confineToRoot(wsRoot, relPath); // SEG-3
             if (await exists(fullPath)) {
                 const content = await readFile(fullPath, 'utf8');
                 backupFiles.push({ path: relPath, content });
@@ -3038,7 +3672,7 @@ app.post("/workspace/safe-patch", async (req, res) => {
             console.error(`Patch failed, rolling back: ${patchError.message}`);
 
             for (const file of backupFiles) {
-                const fullPath = path.join(wsRoot, file.path);
+                const fullPath = confineToRoot(wsRoot, file.path); // SEG-3
                 await writeFile(fullPath, file.content, 'utf8');
             }
 
@@ -3095,7 +3729,7 @@ app.post("/workspace/patch/dry-run", async (req, res) => {
         // 3. Check if files exist
         const fileChecks = await Promise.all(
             targetFiles.map(async (relPath) => {
-                const fullPath = path.join(wsRoot, relPath);
+                const fullPath = confineToRoot(wsRoot, relPath); // SEG-3
                 const fileExists = await exists(fullPath);
                 let currentContent = null;
                 let lineCount = 0;
@@ -3184,7 +3818,7 @@ app.post("/workspace/backup", async (req, res) => {
         const backupFiles = [];
 
         for (const relPath of files) {
-            const fullPath = path.join(wsRoot, relPath);
+            const fullPath = confineToRoot(wsRoot, relPath); // SEG-3
             if (await exists(fullPath)) {
                 const content = await readFile(fullPath, 'utf8');
                 backupFiles.push({ path: relPath, content });
@@ -3249,7 +3883,7 @@ app.post("/workspace/rollback", async (req, res) => {
         console.log(`Rolling back to backup: ${backupId}`);
 
         for (const file of backup.files) {
-            const fullPath = path.join(wsRoot, file.path);
+            const fullPath = confineToRoot(wsRoot, file.path); // SEG-3
             await writeFile(fullPath, file.content, 'utf8');
         }
 
@@ -3376,7 +4010,7 @@ app.get("/workspace/diff/by-incident/:incidentId", async (req, res) => {
     try {
         const diffs = [];
         for (const file of matchedBackup.files) {
-            const fullPath = path.join(wsRoot, file.path);
+            const fullPath = confineToRoot(wsRoot, file.path); // SEG-3
             let currentContent = '';
             try {
                 currentContent = await readFile(fullPath, 'utf8');
@@ -3455,7 +4089,7 @@ app.get("/workspace/diff/:backupId", async (req, res) => {
         const diffs = [];
 
         for (const file of backup.files) {
-            const fullPath = path.join(wsRoot, file.path);
+            const fullPath = confineToRoot(wsRoot, file.path); // SEG-3
             let currentContent = '';
 
             try {
@@ -3523,7 +4157,7 @@ app.get("/workspace/detect-port", async (req, res) => {
     const { servicePath = '', language, framework } = req.query;
 
     try {
-        const fullPath = path.join(wsRoot, servicePath);
+        const fullPath = confineToRoot(wsRoot, servicePath); // SEG-3
         console.log(`Detecting port for service at: ${fullPath}`);
 
         let port = null;
@@ -4028,17 +4662,20 @@ app.get("/workspace/test-local/logs/stream", async (req, res) => {
 
 // ============================================
 //  AUTO-TRAINING ENDPOINTS
-// Escanear e ler arquivos para treinamento AI
+// Scan and read files for AI training
 // ============================================
 
 /**
  * POST /workspace/scan-files
- * Escaneia todos os arquivos do workspace para auto-training
+ * Scans all workspace files for auto-training
  */
 app.post("/workspace/scan-files", async (req, res) => {
     const { root, excludePatterns = [], includeExtensions = [], maxDepth = 10, maxFiles = 1000 } = req.body;
 
-    const workspaceRoot = root || WORKSPACE_ROOT;
+    // SEG-3: when the gateway sets the tenant-isolated root (header), it wins and
+    // a body `root` can never override it. Body root is honoured only in dev
+    // (no header present).
+    const workspaceRoot = resolveWorkspaceRoot(req) || root || WORKSPACE_ROOT;
     if (!workspaceRoot) {
         return res.status(400).json({
             error: "workspace not set",
@@ -4055,7 +4692,7 @@ app.post("/workspace/scan-files", async (req, res) => {
         const fs = await import("fs/promises");
         const pathModule = await import("path");
 
-        // Padres padro para excluir
+        // Default patterns to exclude
         const defaultExcludes = [
             "node_modules", "target", "build", "dist", ".git", ".idea",
             ".vscode", "__pycache__", ".gradle", "bin", "obj",
@@ -4063,7 +4700,7 @@ app.post("/workspace/scan-files", async (req, res) => {
         ];
         const allExcludes = [...defaultExcludes, ...excludePatterns];
 
-        // Funo recursiva para escanear
+        // Recursive function to scan
         async function scanDir(dir, depth = 0) {
             if (depth > maxDepth || files.length >= maxFiles) return;
 
@@ -4076,7 +4713,7 @@ app.post("/workspace/scan-files", async (req, res) => {
                     const fullPath = pathModule.join(dir, entry.name);
                     const relativePath = pathModule.relative(workspaceRoot, fullPath);
 
-                    // Verificar se deve excluir
+                    // Check whether it should be excluded
                     const shouldExclude = allExcludes.some(pattern => {
                         if (pattern.includes("*")) {
                             const regex = new RegExp(pattern.replace(/\*/g, ".*"));
@@ -4090,7 +4727,7 @@ app.post("/workspace/scan-files", async (req, res) => {
                     if (entry.isDirectory()) {
                         await scanDir(fullPath, depth + 1);
                     } else if (entry.isFile()) {
-                        // Verificar extenso
+                        // Check the extension
                         const ext = pathModule.extname(entry.name).toLowerCase();
                         if (includeExtensions.length === 0 || includeExtensions.includes(ext)) {
                             files.push(relativePath);
@@ -4125,12 +4762,14 @@ app.post("/workspace/scan-files", async (req, res) => {
 
 /**
  * POST /workspace/read-file
- * L contedo de um arquivo especfico
+ * Reads the content of a specific file
  */
 app.post("/workspace/read-file", async (req, res) => {
-    const { root, filePath } = req.body;
+    const { filePath } = req.body;
 
-    const workspaceRoot = root || WORKSPACE_ROOT;
+    // SEG-3: the root comes ONLY from the tenant-isolated request context,
+    // never from the body (a body `root` could point at another workspace).
+    const workspaceRoot = resolveWorkspaceRoot(req);
     if (!workspaceRoot) {
         return res.status(400).json({
             error: "workspace not set"
@@ -4147,11 +4786,19 @@ app.post("/workspace/read-file", async (req, res) => {
 
     try {
         const fs = await import("fs/promises");
-        const pathModule = await import("path");
 
-        const fullPath = pathModule.join(workspaceRoot, filePath);
+        let fullPath;
+        try {
+            fullPath = confineToRoot(workspaceRoot, filePath);
+        } catch (e) {
+            if (e instanceof SandboxViolation) {
+                console.warn(`[READ-FILE] SANDBOX DENIED: ${filePath} (${e.details?.resolved})`);
+                return res.status(403).json({ success: false, error: "path escapes the workspace sandbox", filePath });
+            }
+            throw e;
+        }
 
-        // Verificar se arquivo existe
+        // Check whether the file exists
         const stats = await fs.stat(fullPath);
 
         // Limitar tamanho (100KB)
@@ -4185,12 +4832,13 @@ app.post("/workspace/read-file", async (req, res) => {
 
 /**
  * POST /workspace/read-files
- * L mltiplos arquivos de uma vez (batch)
+ * Reads multiple files at once (batch)
  */
 app.post("/workspace/read-files", async (req, res) => {
-    const { root, filePaths } = req.body;
+    const { filePaths } = req.body;
 
-    const workspaceRoot = root || WORKSPACE_ROOT;
+    // SEG-3: root only from the tenant-isolated request context.
+    const workspaceRoot = resolveWorkspaceRoot(req);
     if (!workspaceRoot) {
         return res.status(400).json({
             error: "workspace not set"
@@ -4207,17 +4855,25 @@ app.post("/workspace/read-files", async (req, res) => {
 
     try {
         const fs = await import("fs/promises");
-        const pathModule = await import("path");
 
         const files = {};
         const errors = [];
 
         for (const filePath of filePaths) {
             try {
-                const fullPath = pathModule.join(workspaceRoot, filePath);
+                let fullPath;
+                try {
+                    fullPath = confineToRoot(workspaceRoot, filePath);
+                } catch (e) {
+                    if (e instanceof SandboxViolation) {
+                        errors.push({ filePath, error: "path escapes the workspace sandbox" });
+                        continue;
+                    }
+                    throw e;
+                }
                 const stats = await fs.stat(fullPath);
 
-                // Pular arquivos muito grandes
+                // Skip files that are too large
                 if (stats.size > 100 * 1024) {
                     errors.push({ filePath, error: "File too large" });
                     continue;
@@ -4255,7 +4911,7 @@ app.post("/workspace/read-files", async (req, res) => {
 
 /**
  * GET /system/folder-picker
- * Abre o file picker nativo do sistema operacional
+ * Opens the native operating system file picker
  */
 app.get("/system/folder-picker", async (req, res) => {
     console.log(`[FOLDER-PICKER] Opening native folder picker...`);
@@ -4271,7 +4927,7 @@ app.get("/system/folder-picker", async (req, res) => {
                 const { stdout } = await execAsync(script);
                 selectedPath = stdout.trim();
             } catch (error) {
-                // Usurio cancelou
+                // User cancelled
                 if (error.code === 1) {
                     return res.json({
                         success: true,
@@ -4300,7 +4956,7 @@ app.get("/system/folder-picker", async (req, res) => {
             }
 
         } else if (platform === "linux") {
-            // Linux - tentar zenity, kdialog ou yad
+            // Linux - try zenity, kdialog or yad
             const commands = [
                 `zenity --file-selection --directory --title="Select your project folder"`,
                 `kdialog --getexistingdirectory ~ --title "Select your project folder"`,
@@ -4336,7 +4992,7 @@ app.get("/system/folder-picker", async (req, res) => {
             });
         }
 
-        // Remover trailing slash se houver
+        // Remove trailing slash if present
         if (selectedPath && selectedPath.endsWith("/")) {
             selectedPath = selectedPath.slice(0, -1);
         }
@@ -4362,7 +5018,7 @@ app.get("/system/folder-picker", async (req, res) => {
 
 /**
  * GET /system/info
- * Retorna informaes do sistema
+ * Returns system information
  */
 app.get("/system/info", (req, res) => {
     res.json({
@@ -4376,12 +5032,12 @@ app.get("/system/info", (req, res) => {
 
 // ============================================
 //  API DOCS ENDPOINT
-// Retorna endpoints detectados das controllers
+// Returns endpoints detected from the controllers
 // ============================================
 
 /**
  * GET /workspace/api-docs
- * Analisa controllers e retorna todos os endpoints da API
+ * Analyzes controllers and returns all API endpoints
  */
 app.get("/workspace/api-docs", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
@@ -4395,7 +5051,7 @@ app.get("/workspace/api-docs", async (req, res) => {
     console.log(`[API-DOCS] Analyzing controllers in ${wsRoot}`);
 
     try {
-        // Primeiro, escanear arquivos do workspace
+        // First, scan the workspace files
         const fs = await import("fs/promises");
         const pathModule = await import("path");
 
@@ -4433,7 +5089,7 @@ app.get("/workspace/api-docs", async (req, res) => {
 
         console.log(`[API-DOCS] Found ${files.length} Java files`);
 
-        // Agora analisar os controllers
+        // Now analyze the controllers
         const controllerAnalyzer = new ControllerAnalyzer(wsRoot);
         const apiDocs = await controllerAnalyzer.generateApiDocs(files);
 
@@ -4464,7 +5120,7 @@ app.get("/workspace/api-docs", async (req, res) => {
 
 /**
  * GET /workspace/api-docs/:controller
- * Retorna endpoints de uma controller especfica
+ * Returns the endpoints of a specific controller
  */
 app.get("/workspace/api-docs/:controller", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
@@ -4479,7 +5135,7 @@ app.get("/workspace/api-docs/:controller", async (req, res) => {
     console.log(`[API-DOCS] Getting endpoints for controller: ${controller}`);
 
     try {
-        // Primeiro, escanear arquivos do workspace
+        // First, scan the workspace files
         const fs = await import("fs/promises");
         const pathModule = await import("path");
 
@@ -4514,7 +5170,7 @@ app.get("/workspace/api-docs/:controller", async (req, res) => {
 
         await scanDir(wsRoot);
 
-        // Analisar os controllers
+        // Analyze the controllers
         const controllerAnalyzer = new ControllerAnalyzer(wsRoot);
         const apiDocs = await controllerAnalyzer.generateApiDocs(files);
 
@@ -4565,7 +5221,7 @@ app.get("/workspace/api-docs/:controller", async (req, res) => {
 
 /**
  * GET /ai-engine/status
- * Retorna estado do AI Vibe Coding Engine
+ * Returns the state of the AI Vibe Coding Engine
  */
 app.get("/ai-engine/status", (req, res) => {
     res.json(aiEngine ? aiEngine.getStatus() : { active: false, error: 'AI Engine not initialized' });
@@ -4600,7 +5256,7 @@ app.post("/ai-engine/clear-history", (req, res) => {
 
 /**
  * GET /ai-engine/errors
- * Retorna histrico de erros
+ * Returns the error history
  */
 app.get("/ai-engine/errors", (req, res) => {
     const { limit = 50 } = req.query;
@@ -4617,7 +5273,7 @@ app.get("/ai-engine/errors", (req, res) => {
 
 /**
  * GET /ai-engine/fixes
- * Retorna histrico de fixes
+ * Returns the fix history
  */
 app.get("/ai-engine/fixes", (req, res) => {
     if (aiEngine) {
@@ -4633,7 +5289,7 @@ app.get("/ai-engine/fixes", (req, res) => {
 
 /**
  * GET /workspace/smart-config
- * Recolhe ficheiros de configurao para anlise AI
+ * Collects configuration files for AI analysis
  */
 app.get("/workspace/smart-config", async (req, res) => {
     const wsRoot = resolveWorkspaceRoot(req);
@@ -4682,7 +5338,7 @@ app.get("/workspace/smart-config", async (req, res) => {
             }
         }
 
-        // Detectar profiles disponveis
+        // Detect available profiles
         const availableProfiles = [];
         const resourcesDir = path.join(wsRoot, 'src/main/resources');
         if (fs.existsSync(resourcesDir)) {
@@ -4797,40 +5453,40 @@ app.post("/workspace/search", async (req, res) => {
         return res.status(400).json({ ok: false, error: "pattern is required" });
     }
 
+    // ROOT-RECOVERY fail-fast: dead root with no recoverable clone - answer
+    // with an actionable error instead of an empty result set the AI cannot
+    // distinguish from "no matches".
+    if (!fs.existsSync(wsRoot)) {
+        return res.status(200).json({
+            ok: false,
+            error: "workspace_root_not_hydrated",
+            root: wsRoot,
+            hint: "This agent has no clone at that path. Run git_prepare_workspace "
+                + "(POST /workspace/clone) for this workspace first, then retry."
+        });
+    }
+
     console.log(`[workspace/search] pattern="${pattern}" filter="${fileFilter || '*'}"`);
 
     try {
-        const { execSync } = await import('child_process');
+        const { execFileSync } = await import('child_process');
 
-        // Build grep command with safety limits
-        let cmd = `grep -rn `;
-
-        // Apply file filter if provided
-        if (fileFilter && fileFilter.trim()) {
-            cmd += `--include="${fileFilter}" `;
-        }
-
-        // Exclude common non-source directories
-        cmd += `--exclude-dir=node_modules --exclude-dir=.git --exclude-dir=target `;
-        cmd += `--exclude-dir=build --exclude-dir=dist --exclude-dir=.idea `;
-        cmd += `--exclude-dir=__pycache__ --exclude-dir=.next --exclude-dir=vendor `;
-        cmd += `--exclude-dir=bin --exclude-dir=obj --exclude-dir=.gradle `;
-        cmd += `--exclude-dir=.mvn --exclude-dir=.venv --exclude-dir=coverage `;
-
-        // Escape pattern for shell safety and limit results
-        const safePattern = pattern.replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
-        cmd += `"${safePattern}" "${wsRoot}" | head -100`;
+        // No shell: pattern and fileFilter are argv entries (H4), never interpolated.
+        const grepArgs = buildGrepArgs({ pattern: String(pattern), fileFilter, root: wsRoot });
 
+        const relativize = (line) => line.replace(wsRoot + '/', '');
+        const SEARCH_TIMEOUT_MS = parseInt(process.env.WORKSPACE_SEARCH_TIMEOUT_MS || "15000", 10);
         let stdout = '';
         try {
-            stdout = execSync(cmd, {
+            stdout = execFileSync('grep', grepArgs, {
                 encoding: 'utf8',
-                timeout: 15000,
+                timeout: SEARCH_TIMEOUT_MS,
                 maxBuffer: 1024 * 1024
-            });
+            }).split('\n').slice(0, 100).join('\n');
         } catch (grepErr) {
+            const outcome = classifyGrepFailure(grepErr, { timeoutMs: SEARCH_TIMEOUT_MS });
             // grep returns exit code 1 when no matches found
-            if (grepErr.status === 1) {
+            if (outcome.kind === 'no_match') {
                 return res.json({
                     ok: true,
                     results: `No matches found for: ${pattern}`,
@@ -4838,12 +5494,18 @@ app.post("/workspace/search", async (req, res) => {
                 });
             }
             // Exit code 2 = error in grep
-            if (grepErr.status === 2) {
+            if (outcome.kind === 'bad_pattern') {
                 return res.status(400).json({
                     ok: false,
-                    error: "Invalid search pattern: " + grepErr.message
+                    error: "Invalid search pattern: " + outcome.message
                 });
             }
+            // Timeout / output cap: a 15 s grep over a multi-repo parent used to end
+            // here as HTTP 500 (QA incident b83215a8). Answer with what grep found.
+            if (outcome.kind === 'partial') {
+                console.warn(`[workspace/search] ${outcome.reason} pattern="${pattern}" root=${wsRoot}`);
+                return res.status(200).json(partialSearchBody(pattern, outcome, relativize));
+            }
             throw grepErr;
         }
 
@@ -4851,7 +5513,7 @@ app.post("/workspace/search", async (req, res) => {
         const results = stdout
             .split('\n')
             .filter(line => line.trim())
-            .map(line => line.replace(wsRoot + '/', ''))
+            .map(relativize)
             .join('\n');
 
         const count = results.split('\n').filter(l => l.trim()).length;
@@ -4895,19 +5557,26 @@ app.post("/workspace/exec", async (req, res) => {
         return res.status(400).json({ ok: false, error: "command is required" });
     }
 
-    // Security: block dangerous commands
-    const dangerous = [
-        'rm -rf /', 'rm -rf /*', 'mkfs', 'dd if=', 'shutdown', 'reboot',
-        'init 0', '> /dev/', 'chmod -R 777 /', 'curl | sh', 'wget | sh',
-        'curl | bash', 'wget | bash', 'format c:', 'del /f /s /q'
-    ];
-    const lowerCmd = command.toLowerCase().trim();
-    if (dangerous.some(d => lowerCmd.includes(d))) {
-        console.warn(`[workspace/exec] BLOCKED dangerous command: ${command}`);
-        return res.status(403).json({
-            ok: false,
-            error: "Command blocked for security reasons"
-        });
+    // Security: ALLOWLIST (utils/exec-policy.js) instead of the old substring
+    // blocklist. Outside the allowlist a command needs a PolicyGate human
+    // approval token, or must be a signed platform-authored tool command.
+    const execDecision = decideExec({
+        command, root: wsRoot, headers: req.headers, body: req.body || {},
+        vhSignature: req.vhSignature, signingCfg: SIGNING,
+    }, EXEC_POLICY);
+    if (!execDecision.allow) {
+        console.warn(`[workspace/exec] POLICY DENIED: ${execDecision.reason}`);
+        return res.status(execDecision.status || 403).json(rejectionBody(execDecision));
+    }
+
+    // SEG-3: cwd is pinned to the workspace root below; additionally scan the
+    // raw command for out-of-root escapes (`..` traversal, absolute paths into
+    // other workspaces / sensitive dirs). Best-effort — full shell containment
+    // needs OS namespaces — but it blocks the obvious `cat ../neighbor/x` case.
+    const rawScan = scanRawCommand(wsRoot, command);
+    if (!rawScan.ok) {
+        console.warn(`[workspace/exec] SANDBOX DENIED: ${rawScan.reason} (${rawScan.token})`);
+        return res.status(403).json({ ok: false, error: "command escapes the workspace sandbox", detail: rawScan.reason });
     }
 
     console.log(`[workspace/exec] Running: ${command.substring(0, 120)}...`);
@@ -4921,7 +5590,9 @@ app.post("/workspace/exec", async (req, res) => {
             cwd: wsRoot,
             timeout: 60000,
             maxBuffer: 5 * 1024 * 1024,
-            env: { ...process.env, FORCE_COLOR: '0' }
+            // SECURITY (2026-10-11): never hand the agent's own credentials to
+            // a model-authored command (`env`, /proc/self/environ).
+            env: sanitizedChildEnv(process.env, { FORCE_COLOR: '0' })
         });
 
         console.log(`Command completed (stdout: ${result.stdout.length} chars)`);
@@ -4961,9 +5632,10 @@ app.post("/workspace/test-endpoint", async (req, res) => {
         return res.status(400).json({ error: "url is required" });
     }
 
-    // Security: only localhost
-    if (!url.startsWith('http://localhost') && !url.startsWith('http://127.0.0.1')) {
-        return res.status(403).json({ error: "Only localhost URLs allowed for security" });
+    // Security: only loopback, parsed (not prefix-matched), never the agent's own ports.
+    const urlCheck = validateLocalTestUrl(url);
+    if (!urlCheck.ok) {
+        return res.status(403).json({ error: `Only localhost URLs allowed for security: ${urlCheck.reason}` });
     }
 
     console.log(`Testing: ${method} ${url} (${testName || 'unnamed'})`);
@@ -4984,7 +5656,7 @@ app.post("/workspace/test-endpoint", async (req, res) => {
             fetchOptions.body = reqBody;
         }
 
-        const response = await fetch(url, fetchOptions);
+        const response = await fetch(urlCheck.url, { ...fetchOptions, redirect: 'manual' });
         const durationMs = Date.now() - startTime;
 
         // Capture response
@@ -5042,6 +5714,198 @@ app.post("/workspace/test-endpoint", async (req, res) => {
 // Create branch, commit, push for auto-fix PRs
 // ============================================
 
+/**
+ * Coordinated multi-repo branch + PR (Workbench Option B).
+ *
+ * wsRoot is the per-workspace PARENT dir; each immediate git sub-repo that has
+ * uncommitted changes gets the SAME `branchName`, a commit, a push, and ONE PR.
+ * After all PRs exist, each PR body is updated (two-pass) to cross-link the
+ * sibling PRs. Returns a LIST of per-repo PR results; single-repo callers never
+ * reach here (server routes only when isMultiRepoRoot()).
+ *
+ * PR creation currently uses the GitHub REST API (primary provider). Non-GitHub
+ * sub-repos still get branch+commit+push and a "compare/new MR" URL, but no API
+ * PR/cross-link (tracked as follow-up).
+ */
+async function createMultiRepoFixBranch({ wsRoot, branchName, commitMessage, gitToken, files }) {
+    if (!isSafeBranchName(branchName)) {
+        const err = new Error("invalid branch name"); err.httpStatus = 400; throw err;
+    }
+    const { execSync, execFileSync } = await import('child_process');
+    const gitEnv = {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_ASKPASS: 'echo',
+        GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o ConnectTimeout=5',
+    };
+    const repos = listRepoSubdirs(wsRoot);
+    const prs = [];
+    let totalFiles = 0;
+
+    for (const repo of repos) {
+        const opts = { cwd: repo.path, encoding: 'utf8', timeout: 60000, env: gitEnv };
+        const runQuiet = (cmd, o = {}) => {
+            try { return execSync(cmd, { ...opts, ...o }).toString().trim(); }
+            catch { return ''; }
+        };
+        // No shell for anything that carries caller-supplied text (branch,
+        // commit message, file names): argv array via execFile.
+        const git = (args, o = {}) => execFileSync('git', args, { ...opts, ...o }).toString().trim();
+        const gitQuiet = (args, o = {}) => { try { return git(args, o); } catch { return ''; } };
+
+        // Only repos with actual changes get a PR (one-PR-per-CHANGED-repo).
+        let status = '';
+        try { status = execSync('git status --porcelain', opts).toString().trim(); }
+        catch { status = ''; }
+        if (!status) {
+            prs.push({ dir: repo.dir, changed: false, prCreated: false, prUrl: '' });
+            continue;
+        }
+        const filesChanged = status.split('\n').filter(Boolean).length;
+        totalFiles += filesChanged;
+
+        // git identity (Cloud Run has none by default).
+        runQuiet('git config user.email "ai@deepdebug.ai"');
+        runQuiet('git config user.name "DeepDebug AI"');
+
+        // Shared branch across every repo. Reuse if it already exists in this repo.
+        try { git(['checkout', '-b', branchName]); }
+        catch { gitQuiet(['checkout', branchName]); }
+
+        // Stage + commit.
+        if (Array.isArray(files) && files.length > 0) {
+            for (const f of files) gitQuiet(['add', '--', String(f)]);
+        } else {
+            runQuiet('git add -A');
+        }
+        try { git(['commit', '-m', String(commitMessage)]); }
+        catch (e) { /* nothing staged after all */ }
+        const commitSha = runQuiet('git rev-parse HEAD');
+
+        // Resolve authed remote for push + API.
+        const remoteRaw = runQuiet('git remote get-url origin 2>/dev/null');
+        const parsed = parseAuthedRemote(remoteRaw);
+        const cleanBase = stripRemoteCreds(remoteRaw);
+
+        // Determine PR base: repo default branch (origin/HEAD) else main.
+        let targetBranch = 'main';
+        const head = runQuiet('git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null');
+        if (head) {
+            const parts = head.split('/');
+            if (parts.length) targetBranch = parts[parts.length - 1];
+        }
+
+        // Push the shared branch (origin already carries the per-repo token from clone).
+        let pushed = false;
+        try {
+            git(['push', '-u', 'origin', branchName], { timeout: 120000 });
+            pushed = true;
+        } catch (e) {
+            console.warn(`[multi-repo-pr] push failed for ${repo.dir}: ${maskUrlCreds(e.message || '')}`);
+        }
+
+        const entry = {
+            dir: repo.dir,
+            changed: true,
+            filesChanged,
+            commitSha,
+            branch: branchName,
+            targetBranch,
+            pushed,
+            repoUrl: cleanBase,
+            provider: parsed ? parsed.provider : 'generic',
+            prCreated: false,
+            prUrl: '',
+            prNumber: null,
+        };
+
+        // Open the PR (GitHub API). Others: fall back to a compare/new-MR URL.
+        if (pushed && parsed && parsed.provider === 'github' && parsed.apiToken) {
+            const body = buildMultiRepoPrBody({
+                dir: repo.dir, branch: branchName, commitMessage, filesChanged, commitSha,
+            });
+            try {
+                const resp = await fetch(`https://api.github.com/repos/${parsed.ownerRepo}/pulls`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${parsed.apiToken}`,
+                        'Accept': 'application/vnd.github+json',
+                        'Content-Type': 'application/json',
+                        'X-GitHub-Api-Version': '2022-11-28',
+                        'User-Agent': 'DeepDebug-AI',
+                    },
+                    body: JSON.stringify({ title: commitMessage, head: branchName, base: targetBranch, body }),
+                });
+                if (resp.ok) {
+                    const data = await resp.json();
+                    entry.prUrl = data.html_url;
+                    entry.prNumber = data.number;
+                    entry.prCreated = true;
+                    console.log(`[multi-repo-pr] GitHub PR created for ${repo.dir}: ${entry.prUrl}`);
+                } else {
+                    const errText = (await resp.text()).substring(0, 200);
+                    console.warn(`[multi-repo-pr] GitHub PR failed (${resp.status}) for ${repo.dir}: ${errText}`);
+                    entry.prUrl = buildCompareUrl(cleanBase, 'github', branchName, targetBranch);
+                }
+            } catch (e) {
+                console.warn(`[multi-repo-pr] GitHub PR error for ${repo.dir}: ${e.message}`);
+                entry.prUrl = buildCompareUrl(cleanBase, 'github', branchName, targetBranch);
+            }
+        } else if (pushed) {
+            entry.prUrl = buildCompareUrl(cleanBase, entry.provider, branchName, targetBranch);
+        }
+        prs.push(entry);
+    }
+
+    // Second pass: cross-link sibling PRs in each real GitHub PR body.
+    const realPrs = prs.filter((p) => p.prCreated && p.prNumber != null);
+    if (realPrs.length > 1) {
+        for (const p of realPrs) {
+            const note = buildCrossLinkNote(p.dir, realPrs);
+            if (!note) continue;
+            const repo = repos.find((r) => r.dir === p.dir);
+            const remoteRaw = execSync('git remote get-url origin 2>/dev/null',
+                { cwd: repo.path, encoding: 'utf8', env: gitEnv }).toString().trim();
+            const parsed = parseAuthedRemote(remoteRaw);
+            if (!parsed || parsed.provider !== 'github' || !parsed.apiToken) continue;
+            const baseBody = buildMultiRepoPrBody({
+                dir: p.dir, branch: branchName, commitMessage,
+                filesChanged: p.filesChanged, commitSha: p.commitSha,
+            });
+            try {
+                await fetch(`https://api.github.com/repos/${parsed.ownerRepo}/pulls/${p.prNumber}`, {
+                    method: 'PATCH',
+                    headers: {
+                        'Authorization': `Bearer ${parsed.apiToken}`,
+                        'Accept': 'application/vnd.github+json',
+                        'Content-Type': 'application/json',
+                        'X-GitHub-Api-Version': '2022-11-28',
+                        'User-Agent': 'DeepDebug-AI',
+                    },
+                    body: JSON.stringify({ body: baseBody + note }),
+                });
+            } catch (e) {
+                console.warn(`[multi-repo-pr] cross-link update failed for ${p.dir}: ${e.message}`);
+            }
+        }
+    }
+
+    const changedPrs = prs.filter((p) => p.changed);
+    const firstUrl = (changedPrs.find((p) => p.prUrl) || {}).prUrl || '';
+    return {
+        ok: true,
+        multiRepo: true,
+        branch: branchName,
+        prs,
+        prUrls: changedPrs.filter((p) => p.prUrl).map((p) => p.prUrl),
+        mrUrl: firstUrl,
+        prCreated: changedPrs.some((p) => p.prCreated),
+        filesChanged: totalFiles,
+        reposChanged: changedPrs.length,
+        reposTotal: repos.length,
+    };
+}
+
 /**
  * POST /workspace/git/create-fix-branch
  * Creates a branch, commits changes, and pushes to remote.
@@ -5058,9 +5922,33 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
     if (!branchName || !commitMessage) {
         return res.status(400).json({ error: "branchName and commitMessage required" });
     }
+    // SECURITY (2026-10-11): branchName / commitMessage / files were interpolated
+    // into shell strings (`git commit -m "${msg}"` only escaped quotes, so
+    // backticks and $() ran). Validate the branch, run git via execFile below.
+    if (!isSafeBranchName(branchName)) return res.status(400).json({ error: "invalid branch name" });
+    if (files !== undefined && (!Array.isArray(files) || files.some(f => typeof f !== "string" || !f || f.startsWith("-")))) {
+        return res.status(400).json({ error: "files must be an array of relative paths" });
+    }
+
+    // MULTI-REPO (Workbench Option B): when the session root is a per-workspace
+    // PARENT dir with N git sub-repos (cloud-multi-clone), open ONE PR per CHANGED
+    // repo on the SAME shared branch and cross-link the siblings. Single-repo
+    // roots (root itself is a git repo) fall through to the legacy path below,
+    // unchanged. Gated by MULTI_REPO_PR_ENABLED (default on).
+    if (multiRepoPrEnabled() && isMultiRepoRoot(wsRoot)) {
+        try {
+            const result = await createMultiRepoFixBranch({
+                wsRoot, branchName, commitMessage, gitToken, files,
+            });
+            return res.json(result);
+        } catch (err) {
+            console.error(`[multi-repo-pr] failed: ${maskUrlCreds(err.message)}`);
+            return res.status(500).json({ ok: false, error: maskUrlCreds(err.message) });
+        }
+    }
 
     try {
-        const { execSync } = await import('child_process');
+        const { execSync, execFileSync } = await import('child_process');
         const opts = {
             cwd: wsRoot,
             encoding: 'utf8',
@@ -5069,9 +5957,11 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
                 ...process.env,
                 GIT_TERMINAL_PROMPT: '0',      // Never prompt for credentials
                 GIT_ASKPASS: 'echo',            // Return empty if asked
-                GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o StrictHostKeyChecking=no -o ConnectTimeout=5'
+                GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o ConnectTimeout=5'
             }
         };
+        // argv form (no shell) for every call that carries request data.
+        const git = (args, o = {}) => execFileSync('git', args, { ...opts, ...o }).toString();
 
         // 1. Check if git repo
         try {
@@ -5098,12 +5988,12 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
         // 4. Create and checkout new branch (with unique name if exists)
         let finalBranchName = branchName;
         try {
-            execSync(`git checkout -b ${finalBranchName}`, opts);
+            git(['checkout', '-b', finalBranchName]);
         } catch (e) {
             // Branch already exists  add timestamp suffix
             finalBranchName = `${branchName}-${Date.now() % 100000}`;
             try {
-                execSync(`git checkout -b ${finalBranchName}`, opts);
+                git(['checkout', '-b', finalBranchName]);
             } catch (e2) {
                 // Restore stash and bail
                 if (hadStash) try { execSync('git stash pop', opts); } catch {}
@@ -5124,7 +6014,7 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
         // 6. Stage changes
         if (files && files.length > 0) {
             for (const file of files) {
-                execSync(`git add "${file}"`, opts);
+                git(['add', '--', file]);
             }
         } else {
             execSync('git add -A', opts);
@@ -5133,7 +6023,7 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
         // 7. Check for changes
         const status = execSync('git status --porcelain', opts).trim();
         if (!status) {
-            try { execSync(`git checkout ${currentBranch}`, opts); } catch {}
+            try { git(['checkout', currentBranch]); } catch {}
             return res.json({ ok: false, error: "No changes to commit" });
         }
 
@@ -5145,8 +6035,7 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
         } catch (e) {
             console.warn('Could not set git config:', e.message);
         }
-        const safeMsg = commitMessage.replace(/"/g, '\\"').replace(/\n/g, '\\n');
-        execSync(`git commit -m "${safeMsg}"`, opts);
+        git(['commit', '-m', String(commitMessage)]);
 
         // 9. Push (use token if available for authentication)
         let pushResult = '';
@@ -5164,11 +6053,11 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
                     // No remote configured  use repoUrl from integration if available
                     if (repoUrl) {
                         remoteUrlRaw = repoUrl;
-                        console.log(`No git remote, using repoUrl from integration: ${repoUrl}`);
+                        console.log(`No git remote, using repoUrl from integration: ${maskUrlCreds(repoUrl)}`);
                     }
                 }
 
-                console.log(`Remote URL: ${remoteUrlRaw.replace(gitToken, '***')}`);
+                console.log(`Remote URL: ${maskUrlCreds(remoteUrlRaw)}`);
                 let authenticatedUrl = '';
 
                 if (remoteUrlRaw.includes('github.com')) {
@@ -5192,7 +6081,7 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
                         .replace(/^git@bitbucket\.org:/, '')
                         .replace(/\.git$/, '');
                     //  FIXED: Bitbucket App Password auth  token j est no formato "username:appPassword"
-                    // x-token-auth no funciona; Basic Auth via URL  o mtodo correcto
+                    // x-token-auth does not work; Basic Auth via URL is the correct method
                     authenticatedUrl = `https://${gitToken}@bitbucket.org/${repoPath}.git`;
                 } else if (remoteUrlRaw) {
                     // Unknown provider  try generic https with token
@@ -5206,42 +6095,46 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
                     console.log(`Pushing ${finalBranchName} with token auth...`);
                     try {
                         // Don't use 2>&1  let execSync capture stderr separately
-                        pushResult = execSync(`git push ${authenticatedUrl} ${finalBranchName}`, {
-                            ...opts,
+                        pushResult = git(['push', authenticatedUrl, finalBranchName], {
                             timeout: 60000,  // 60s for slow connections
                             stdio: ['pipe', 'pipe', 'pipe']  // capture stdin, stdout, stderr separately
-                        }).toString();
+                        });
                         pushed = true;
                         console.log(`Pushed with token authentication`);
                     } catch (innerErr) {
-                        // Mask token in error messages before logging
-                        const maskToken = (str) => str ? str.replace(gitToken, '***TOKEN***') : '';
-                        const errMsg = maskToken(innerErr.stderr?.toString() || innerErr.stdout?.toString() || innerErr.message || '');
+                        // Mask token in error messages before logging. maskUrlCreds
+                        // strips URL userinfo (all occurrences, token-agnostic); the
+                        // literal maskToken is kept as a second layer for any bare
+                        // token echo outside a URL.
+                        const maskToken = (str) => str ? str.split(gitToken).join('***TOKEN***') : '';
+                        const errMsg = maskUrlCreds(maskToken(innerErr.stderr?.toString() || innerErr.stdout?.toString() || innerErr.message || ''));
                         console.warn(`Authenticated push failed: ${errMsg}`);
                         pushResult = errMsg;
                     }
                 } else {
-                    console.warn(`Could not construct authenticated URL from: ${remoteUrlRaw}`);
+                    console.warn(`Could not construct authenticated URL from: ${maskUrlCreds(remoteUrlRaw)}`);
                 }
             } catch (pushErr) {
-                const maskToken = (str) => str ? str.replace(gitToken, '***TOKEN***') : '';
-                console.warn(`Git auth setup failed: ${maskToken(pushErr.message)}`);
-                pushResult = maskToken(pushErr.message) || 'Push setup failed';
+                const maskToken = (str) => str ? str.split(gitToken).join('***TOKEN***') : '';
+                const safe = maskUrlCreds(maskToken(pushErr.message));
+                console.warn(`Git auth setup failed: ${safe}`);
+                pushResult = safe || 'Push setup failed';
             }
         }
 
         // Fallback: try push without token (uses local git credentials)
         if (!pushed) {
             try {
-                pushResult = execSync(`git push -u origin ${finalBranchName} 2>&1`, opts).toString();
+                pushResult = git(['push', '-u', 'origin', finalBranchName], { stdio: ['pipe', 'pipe', 'pipe'] });
                 pushed = true;
             } catch (pushErr) {
                 try {
-                    pushResult = execSync(`git push origin ${finalBranchName} 2>&1`, opts).toString();
+                    pushResult = git(['push', 'origin', finalBranchName], { stdio: ['pipe', 'pipe', 'pipe'] });
                     pushed = true;
                 } catch (pushErr2) {
-                    console.warn(`Git push failed: ${pushErr2.message}`);
-                    pushResult = pushErr2.message || 'Push failed  no remote configured or auth required';
+                    const safe = maskUrlCreds(pushErr2.message);
+                    console.warn(`Git push failed: ${safe}`);
+                    pushResult = safe || 'Push failed  no remote configured or auth required';
                 }
             }
         }
@@ -5304,11 +6197,11 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
 
         // 10. Switch back to original branch and merge fix to keep changes on disk
         try {
-            execSync(`git checkout ${currentBranch}`, opts);
+            git(['checkout', currentBranch]);
             // Merge the fix branch so the working directory has the patched files
             // This keeps the diff viewer working (disk has patched version)
             try {
-                execSync(`git merge ${finalBranchName} --no-edit`, opts);
+                git(['merge', finalBranchName, '--no-edit']);
                 console.log(`Merged ${finalBranchName} into ${currentBranch}`);
             } catch (mergeErr) {
                 // If merge fails (conflicts), just cherry-pick the changes without committing
@@ -5320,7 +6213,7 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
                     const changedFiles = status.split('\n').map(l => l.trim().split(/\s+/).pop()).filter(Boolean);
                     for (const f of changedFiles) {
                         try {
-                            execSync(`git checkout ${finalBranchName} -- ${f}`, opts);
+                            git(['checkout', finalBranchName, '--', f]);
                         } catch {}
                     }
                     console.log(`Cherry-picked ${changedFiles.length} file(s) from ${finalBranchName}`);
@@ -5329,17 +6222,17 @@ app.post("/workspace/git/create-fix-branch", async (req, res) => {
         } catch {}
 
         // 11. Auto-create Pull Request if pushed and token available
-        //  FIXED: suporta GitHub, GitLab e Bitbucket; branding Insptech AI
+        //  FIXED: suporta GitHub, GitLab e Bitbucket; branding VisionHammer
         let prUrl = '';
         const prBodyText =
-            `##  Auto-fix by Insptech AI\n\n` +
+            `##  Auto-fix by VisionHammer\n\n` +
             `**Branch:** \`${finalBranchName}\`\n` +
             `**Files changed:** ${status.split('\n').length}\n` +
             `**Commit:** ${commitSha.substring(0, 8)}\n\n` +
-            `This pull request was automatically created by Insptech AI after detecting and fixing a production error.\n\n` +
+            `This pull request was automatically created by VisionHammer after detecting and fixing a production error.\n\n` +
             `### Changes\n` +
             status.split('\n').map(l => `- \`${l.trim()}\``).join('\n') + '\n\n' +
-            `---\n*Generated by [Insptech AI](https://app.insptech.pt)  Autonomous Debugging Platform*`;
+            `---\n*Generated by [VisionHammer](https://visionhammer.io)  Autonomous Debugging Platform*`;
 
         if (pushed && gitToken && remoteUrl) {
 
@@ -5901,7 +6794,7 @@ async function _getGitProvider() {
         const providerId = registry.detectProviderFromUrl(remoteUrl);
 
         if (!providerId) {
-            console.warn(`Unknown git provider for URL: ${remoteUrl}`);
+            console.warn(`Unknown git provider for URL: ${maskUrlCreds(remoteUrl)}`);
             return null;
         }
 
@@ -5944,7 +6837,7 @@ async function _getGitProvider() {
 //  MULTI-WORKSPACE ENDPOINTS
 // ============================================
 
-/** Lista todos os workspaces abertos */
+/** Lists all open workspaces */
 app.get("/workspaces", (req, res) => {
     res.json({
         workspaces: wsManager.list(),
@@ -5978,7 +6871,7 @@ app.post("/workspace/:workspaceId/open", async (req, res) => {
     }
 });
 
-/** Aplica patch num workspace especfico */
+/** Applies a patch to a specific workspace */
 app.post("/workspace/:workspaceId/patch", async (req, res) => {
     const { workspaceId } = req.params;
     const { diff } = req.body || {};
@@ -5992,7 +6885,7 @@ app.post("/workspace/:workspaceId/patch", async (req, res) => {
     }
 });
 
-/** Compila e testa num workspace especfico */
+/** Compiles and tests a specific workspace */
 app.post("/workspace/:workspaceId/test", async (req, res) => {
     const { workspaceId } = req.params;
     try {
@@ -6005,13 +6898,19 @@ app.post("/workspace/:workspaceId/test", async (req, res) => {
     }
 });
 
-/** Executa comando num workspace especfico */
+/** Runs a command in a specific workspace */
 app.post("/workspace/:workspaceId/run", async (req, res) => {
     const { workspaceId } = req.params;
     const { cmd, args = [] } = req.body || {};
     if (!cmd) return res.status(400).json({ error: "cmd is required" });
     try {
         const root = wsManager.resolveRoot(workspaceId);
+        // SEG-3: reject path arguments that resolve outside this workspace root.
+        const argCheck = checkArgsWithinRoot(root, [cmd, ...args]);
+        if (!argCheck.ok) {
+            console.warn(`[workspace/:id/run] SANDBOX DENIED arg: ${argCheck.arg}`);
+            return res.status(403).json({ error: "command argument escapes the workspace sandbox", arg: argCheck.arg });
+        }
         const out = await run(cmd, args, root, 5 * 60 * 1000);
         res.json({ workspaceId, ...out });
     } catch (e) {
@@ -6024,14 +6923,32 @@ app.post("/workspace/:workspaceId/run", async (req, res) => {
 //  WEBSOCKET REVERSE TUNNEL
 // Connects Local Agent to Gateway  no public URL needed
 // ============================================
-async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
+async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId) {
     if (!gatewayUrl || !tenantId) {
         console.log('WebSocket tunnel skipped: missing gatewayUrl or tenantId');
         return;
     }
 
     const wsUrl = gatewayUrl.replace(/^https:\/\//, 'wss://').replace(/^http:\/\//, 'ws://');
-    const fullUrl = `${wsUrl}/api/v1/agent/ws?tenantId=${encodeURIComponent(tenantId)}${apiKey ? '&apiKey=' + encodeURIComponent(apiKey) : ''}`;
+    // SECURITY: the tunnel carries the machine credential and receives commands
+    // the agent executes; never run it in cleartext to a remote host (MITM =
+    // command injection into the customer network). Loopback ws:// stays for dev.
+    try {
+        const u = new URL(wsUrl);
+        const loop = ['localhost', '127.0.0.1', '[::1]', '::1'].includes(u.hostname);
+        if (u.protocol !== 'wss:' && !(u.protocol === 'ws:' && loop)) {
+            console.error(`WebSocket tunnel refused: gateway URL must be https:// (got ${u.protocol}//${u.hostname})`);
+            return;
+        }
+    } catch {
+        console.error('WebSocket tunnel refused: invalid gateway URL');
+        return;
+    }
+    // Credential (the per-machine authorizationToken) goes in the Authorization
+    // header, NOT the URL query (query strings leak to access logs / proxies /
+    // referrers — issue #207). tenantId is not a secret and stays in the query.
+    const fullUrl = `${wsUrl}/api/v1/agent/ws?tenantId=${encodeURIComponent(tenantId)}`;
+    const wsHeaders = authToken ? { Authorization: `Bearer ${authToken}` } : {};
 
     let reconnectDelay = 2000;
     let isShuttingDown = false;
@@ -6041,7 +6958,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
         if (isShuttingDown) return;
         try {
             const { default: WebSocket } = await import('ws');
-            ws = new WebSocket(fullUrl);
+            ws = new WebSocket(fullUrl, { headers: wsHeaders });
 
             ws.on('open', () => {
                 console.log(`WebSocket tunnel connected to Gateway`);
@@ -6058,11 +6975,18 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 if (text === 'pong') return;
                 let request;
                 try { request = JSON.parse(text); } catch { return; }
-                const { requestId, command, params } = request;
+                const { requestId, command } = request;
                 if (!requestId || !command) return;
                 console.log(`WS command: ${command}`);
+                // Signed envelope (utils/request-signing.js): a verified command runs
+                // with the signed paramsRaw, never the unsigned params copy.
+                const envelope = verifyWsEnvelope(request, SIGNING);
+                if (!envelope.ok) {
+                    ws.send(JSON.stringify({ requestId, command, ok: false, error: "invalid command signature", reason: envelope.reason }));
+                    return;
+                }
                 let result;
-                try { result = await handleWsCommand(command, params || {}); }
+                try { result = await handleWsCommand(command, envelope.params || {}, envelope); }
                 catch (err) { result = { error: err.message }; }
                 ws.send(JSON.stringify({ requestId, command, ...result }));
             });
@@ -6088,8 +7012,18 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
         }
     }
 
-    async function handleWsCommand(command, params) {
+    async function handleWsCommand(command, params, sigCtx = {}) {
         const localBase = `http://localhost:${port}`;
+        // In-process hop to the HTTP API: X-Agent-Token plus, when the envelope
+        // verified, the per-process internal marker carrying the signed identity.
+        const hopHeaders = () => ({
+            ...internalAuthHeaders(AGENT_AUTH),
+            ...(sigCtx.verified ? {
+                ...internalSignatureHeaders(),
+                'X-VH-Tenant-Id': sigCtx.tenantId || '',
+                'X-VH-Workspace-Id': sigCtx.workspaceId || '',
+            } : {}),
+        });
         switch (command) {
             case 'health':
                 return { status: 'ok', workspace: WORKSPACE_ROOT, openWorkspaces: wsManager ? wsManager.list().length : 0 };
@@ -6103,10 +7037,23 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
             }
 
             case 'workspace.file-content': {
-                const { path: filePath } = params;
+                const { path: filePath, workspacePath: wsRootParam } = params;
                 if (!filePath) return { error: 'path is required' };
-                if (!WORKSPACE_ROOT) return { error: 'No workspace open' };
-                const absPath = path.isAbsolute(filePath) ? filePath : path.join(WORKSPACE_ROOT, filePath);
+                // SEG-3: confine to the tenant root the gateway sent (params.workspacePath),
+                // never to the shared mutable WORKSPACE_ROOT global. Absolute paths are
+                // treated as workspace-relative and denied if they escape.
+                const wsRoot = (wsRootParam && wsRootParam.trim()) ? wsRootParam.trim() : WORKSPACE_ROOT;
+                if (!wsRoot) return { error: 'No workspace open' };
+                let absPath;
+                try {
+                    absPath = confineToRoot(wsRoot, filePath);
+                } catch (e) {
+                    if (e instanceof SandboxViolation) {
+                        console.warn(`[ws:file-content] SANDBOX DENIED: ${filePath}`);
+                        return { content: null, found: false, error: 'path escapes the workspace sandbox' };
+                    }
+                    throw e;
+                }
                 try {
                     const content = await fsPromises.readFile(absPath, 'utf-8');
                     return { content, path: filePath, found: true };
@@ -6131,7 +7078,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 const method = command === 'workspace.backups' ? 'GET' : 'POST';
                 const res = await fetch(`${localBase}${endpoint}`, {
                     method,
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     ...(method === 'POST' ? { body: JSON.stringify(params) } : {})
                 });
                 return await res.json();
@@ -6155,7 +7102,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 console.log(`WS workspace.diff  ${endpoint}`);
                 const res = await fetch(`${localBase}${endpoint}`, {
                     method: 'GET',
-                    headers: { 'Content-Type': 'application/json' }
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() }
                 });
                 return await res.json();
             }
@@ -6167,7 +7114,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 const mcpBase = `http://localhost:5056`;
                 const res = await fetch(`${mcpBase}/mcp/read-file`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     body: JSON.stringify({
                         workspaceId: params.workspaceId || 'default',
                         path: params.path
@@ -6180,7 +7127,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 const mcpBase = `http://localhost:5056`;
                 const res = await fetch(`${mcpBase}/mcp/read-files`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     body: JSON.stringify({
                         workspaceId: params.workspaceId || 'default',
                         paths: params.paths
@@ -6193,7 +7140,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 const mcpBase = `http://localhost:5056`;
                 const res = await fetch(`${mcpBase}/mcp/list-directory`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     body: JSON.stringify({
                         workspaceId: params.workspaceId || 'default',
                         path: params.path || '.',
@@ -6207,7 +7154,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 const mcpBase = `http://localhost:5056`;
                 const res = await fetch(`${mcpBase}/mcp/search-code`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     body: JSON.stringify({
                         workspaceId: params.workspaceId || 'default',
                         query: params.query,
@@ -6222,11 +7169,14 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 const mcpBase = `http://localhost:5056`;
                 const res = await fetch(`${mcpBase}/mcp/execute-command`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     body: JSON.stringify({
                         workspaceId: params.workspaceId || 'default',
                         command: params.command,
-                        timeoutMs: params.timeoutMs || 120000
+                        timeoutMs: params.timeoutMs || 120000,
+                        // exec-policy inputs (allowlist exceptions) travel with the command
+                        ...(params.approvalToken ? { approvalToken: params.approvalToken } : {}),
+                        ...(params.commandOrigin ? { commandOrigin: params.commandOrigin, tool: params.tool } : {}),
                     })
                 });
                 return await res.json();
@@ -6236,7 +7186,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 const mcpBase = `http://localhost:5056`;
                 const res = await fetch(`${mcpBase}/mcp/project-info`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     body: JSON.stringify({
                         workspaceId: params.workspaceId || 'default'
                     })
@@ -6248,7 +7198,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 const mcpBase = `http://localhost:5056`;
                 const res = await fetch(`${mcpBase}/mcp/apply-patch`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     body: JSON.stringify({
                         workspaceId: params.workspaceId || 'default',
                         diff: params.diff
@@ -6266,7 +7216,7 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
                 }
                 const res = await fetch(`${mcpBase}/mcp/open`, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: { 'Content-Type': 'application/json', ...hopHeaders() },
                     body: JSON.stringify({
                         workspaceId: params.workspaceId || 'default',
                         root: params.root
@@ -6308,13 +7258,27 @@ async function startWebSocketTunnel(port, gatewayUrl, apiKey, tenantId) {
  * POST /setup/run-command
  * Run any shell command on the user's machine.
  */
+// SECURITY: /setup/run-command, /setup/install-tool and /setup/run-auth-command
+// run arbitrary host commands outside any workspace sandbox (the denylist is
+// trivially bypassable). No platform component calls them today, so they are
+// disabled unless the operator explicitly opts in.
+function setupCommandsEnabled(res) {
+    if (process.env.LOCAL_AGENT_ENABLE_SETUP_COMMANDS === 'true') return true;
+    res.status(403).json({ ok: false, error: "setup commands are disabled on this agent (set LOCAL_AGENT_ENABLE_SETUP_COMMANDS=true to enable)" });
+    return false;
+}
+
 app.post("/setup/run-command", async (req, res) => {
+    if (!setupCommandsEnabled(res)) return;
     const { command, description, workingDir } = req.body || {};
     if (!command) return res.status(400).json({ ok: false, error: "command is required" });
 
-    const dangerous = ['rm -rf /', 'mkfs', 'dd if=', 'shutdown', 'reboot', 'format c:', 'del /f /s /q'];
-    if (dangerous.some(d => command.toLowerCase().includes(d))) {
-        return res.status(403).json({ ok: false, error: "Command blocked for safety" });
+    const setupDecision = decideExec({
+        command, root: workingDir || WORKSPACE_ROOT || process.cwd(), headers: req.headers, body: req.body || {},
+        vhSignature: req.vhSignature, signingCfg: SIGNING,
+    }, EXEC_POLICY);
+    if (!setupDecision.allow) {
+        return res.status(setupDecision.status || 403).json(rejectionBody(setupDecision));
     }
 
     console.log(`[SetupAgent] Running: ${command.substring(0, 100)}`);
@@ -6326,7 +7290,7 @@ app.post("/setup/run-command", async (req, res) => {
         const cwd = workingDir || WORKSPACE_ROOT || process.env.HOME || process.cwd();
         const result = await execAsync(command, {
             cwd, timeout: 60000, maxBuffer: 2 * 1024 * 1024,
-            env: { ...process.env, FORCE_COLOR: '0' }, shell: true
+            env: sanitizedChildEnv(process.env, { FORCE_COLOR: '0' }), shell: true
         });
         res.json({ ok: true, stdout: result.stdout, stderr: result.stderr, exitCode: 0, command });
     } catch (err) {
@@ -6362,6 +7326,8 @@ app.post("/setup/check-ports", async (req, res) => {
 app.get("/setup/check-tool", async (req, res) => {
     const { name } = req.query;
     if (!name) return res.status(400).json({ error: "name is required" });
+    // SECURITY: name is interpolated into a shell command.
+    if (!isSafeToolName(name)) return res.status(400).json({ error: "invalid tool name" });
 
     const { exec: execCb } = await import('child_process');
     const { promisify } = await import('util');
@@ -6384,8 +7350,10 @@ app.get("/setup/check-tool", async (req, res) => {
  * Auto-install a CLI tool using the available package manager.
  */
 app.post("/setup/install-tool", async (req, res) => {
+    if (!setupCommandsEnabled(res)) return;
     const { tool } = req.body || {};
     if (!tool) return res.status(400).json({ error: "tool is required" });
+    if (!isSafeToolName(tool)) return res.status(400).json({ error: "invalid tool name" });
 
     const { exec: execCb } = await import('child_process');
     const { promisify } = await import('util');
@@ -6410,16 +7378,23 @@ app.post("/setup/install-tool", async (req, res) => {
  * Run an auth command (gcloud, az login, gh auth) opening browser on user's machine.
  */
 app.post("/setup/run-auth-command", async (req, res) => {
+    if (!setupCommandsEnabled(res)) return;
     const { command, session_id } = req.body || {};
     if (!command) return res.status(400).json({ error: "command is required" });
+    // H4: allowlisted interactive logins only, spawned without a shell.
+    const parsed = parseAuthCommand(command);
+    if (!parsed.ok) return res.status(400).json({ ok: false, error: parsed.reason });
 
-    const { exec: execCb } = await import('child_process');
-    const bgCmd = process.platform === 'win32' ? `start cmd /c "${command}"` : `${command} &`;
-    console.log(`[SetupAgent] Starting auth: ${command.substring(0, 80)}`);
-
-    execCb(bgCmd, { shell: true }, (err) => {
-        if (err) console.warn(`Auth command warning: ${err.message}`);
-    });
+    console.log(`[SetupAgent] Starting auth: ${parsed.argv.slice(0, 3).join(" ")}`);
+    try {
+        const child = spawn(parsed.argv[0], parsed.argv.slice(1), {
+            detached: true, stdio: "ignore", env: sanitizedChildEnv(process.env),
+        });
+        child.on("error", (err) => console.warn(`Auth command warning: ${err.message}`));
+        child.unref();
+    } catch (err) {
+        console.warn(`Auth command warning: ${err.message}`);
+    }
 
     res.json({ ok: true, status: "started", session_id, message: "Auth command started, browser should open" });
 });
@@ -6899,6 +7874,14 @@ app.delete("/workspace/vibe/tunnel/:sessionId", async (req, res) => {
 // ============================================
 registerVercelRoutes(app);
 
+// ============================================
+// OBSERVABILITY PROVISIONING ROUTES
+// (zero-observability detection -> deploy the client observability bundle).
+// Registered after createAuthMiddleware, so they need the agent token like every
+// other route; provisioning runs docker compose on the host.
+// ============================================
+registerObservabilityRoutes(app);
+
 // ============================================
 // LIVE PREVIEW — iOS / Android / Web
 // ============================================
@@ -7083,8 +8066,27 @@ function buildPhoneFrame(body, platform) {
 // START SERVER
 
 // ============================================
-app.listen(PORT, '0.0.0.0', async () => {
-    console.log(`\n DeepDebug Local Agent listening on port ${PORT}`);
+// ============================================
+// PROCESS SAFETY NET (2026-07-20)
+// A multi-tenant agent must NEVER die because one handler leaked a promise
+// rejection (Node 20 default = kill the process). The 2026-07-20 QA
+// crash-loop was exactly that: an unhandled scandir ENOENT in
+// /workspace/files killed the single instance on every indexer retry,
+// 503-ing every tenant. Log loudly, keep serving. Per-handler try/catch
+// remains the first line of defense - this is the last one.
+// ============================================
+process.on("unhandledRejection", (reason) => {
+    const msg = reason && reason.stack ? reason.stack : String(reason);
+    console.error(`[SAFETY-NET] Unhandled promise rejection (process kept alive): ${msg}`);
+});
+process.on("uncaughtException", (err) => {
+    const msg = err && err.stack ? err.stack : String(err);
+    console.error(`[SAFETY-NET] Uncaught exception (process kept alive): ${msg}`);
+});
+
+const BIND_HOST = resolveBindHost(process.env, AGENT_AUTH);
+app.listen(PORT, BIND_HOST, async () => {
+    console.log(`\n DeepDebug Local Agent listening on ${BIND_HOST}:${PORT}`);
     console.log(`Environment: ${process.env.NODE_ENV || 'development'}`);
     console.log(`Process Manager initialized`);
     console.log(`Backup system ready (max: ${MAX_BACKUPS} backups)`);
@@ -7103,6 +8105,13 @@ app.listen(PORT, '0.0.0.0', async () => {
 
     const gwUrl = cfg.gatewayUrl || process.env.GATEWAY_URL;
     const apiKey = cfg.apiKey || process.env.DEEPDEBUG_API_KEY;
+    // The WS tunnel credential is the per-machine authorizationToken minted by
+    // /api/v1/agent/authorize (install.js saves it to config.json and passes it
+    // to the container as AUTH_TOKEN). The gateway authenticates the handshake
+    // with findByAuthorizationToken — NOT the user apiKey. Sending apiKey (the
+    // old behaviour) was rejected 100% of the time (0 connects / 1000+ rejections
+    // in QA). Fall back to apiKey only if no authorizationToken is present.
+    const wsToken = cfg.authorizationToken || process.env.AUTH_TOKEN || apiKey;
     let tenantId = cfg.tenantId || process.env.TENANT_ID;
     if (!tenantId && apiKey) {
         try {
@@ -7112,8 +8121,32 @@ app.listen(PORT, '0.0.0.0', async () => {
     }
 
     if (process.env.DISABLE_WS_TUNNEL !== 'true') {
-        startWebSocketTunnel(PORT, gwUrl, apiKey, tenantId);
+        startWebSocketTunnel(PORT, gwUrl, wsToken, tenantId);
     }
+
+    // Sibling plane (started here so the frozen monolith is untouched): metrics
+    // on 5055, the adapter->incident forwarder configured with gateway creds +
+    // metrics, and the capability preflight (logs mode, serves /capabilities).
+    (async () => {
+        try {
+            const [{ startMetrics }, { incidentForwarder }, { startCapabilityPreflight }] = await Promise.all([
+                import('./siblings/metrics.js'),
+                import('./siblings/incident-forwarder.js'),
+                import('./siblings/capabilities.js'),
+            ]);
+            const metrics = startMetrics(app);
+            incidentForwarder.configure({ gatewayUrl: gwUrl, apiKey, tenantId, metrics });
+            // One-shot contract preflight (must not block/prevent startup).
+            incidentForwarder.contractPreflight().catch(() => {});
+            // authToken = the agent API key: unlocks the full inventory on
+            // /capabilities. Unauthenticated callers get health-only.
+            await startCapabilityPreflight(app, {
+                metrics, workspaceRoot: WORKSPACE_ROOT, gatewayUrl: gwUrl, authToken: apiKey,
+            });
+        } catch (err) {
+            console.warn(`[siblings] startup failed: ${err.message}`);
+        }
+    })();
 });
 
 // Start MCP HTTP Bridge em paralelo (port 5056)