deepdebug-local-agent 1.0.23 → 1.1.0

package/src/utils/exec-utils.js

@@ -5,12 +5,12 @@ import stripAnsi from 'strip-ansi';
 const execAsync = promisify(exec);
 
 /**
- * Executa um comando e retorna o resultado
+ * Runs a command and returns the result
  *
- * @param {string} cmd - Comando a executar
- * @param {string[]} args - Argumentos
- * @param {string} cwd - Diretório de trabalho
- * @param {number} timeoutMs - Timeout em ms (default: 10 min)
+ * @param {string} cmd - Command to run
+ * @param {string[]} args - Arguments
+ * @param {string} cwd - Working directory
+ * @param {number} timeoutMs - Timeout in ms (default: 10 min)
  * @returns {Promise<CommandResult>}
  */
 export function run(cmd, args = [], cwd = process.cwd(), timeoutMs = 10 * 60 * 1000) {
@@ -65,11 +65,11 @@ export function run(cmd, args = [], cwd = process.cwd(), timeoutMs = 10 * 60 * 1
 }
 
 /**
- * Executa comando com streaming de output
+ * Runs a command with output streaming
  *
- * @param {string} cmd - Comando
- * @param {string[]} args - Argumentos
- * @param {string} cwd - Diretório de trabalho
+ * @param {string} cmd - Command
+ * @param {string[]} args - Arguments
+ * @param {string} cwd - Working directory
  * @param {object} callbacks - { onStdout, onStderr, onClose }
  * @returns {ChildProcess}
  */
@@ -106,10 +106,10 @@ export function runStreaming(cmd, args = [], cwd = process.cwd(), callbacks = {}
 }
 
 /**
- * Executa comando simples e retorna output
+ * Runs a simple command and returns its output
  *
- * @param {string} command - Comando completo
- * @param {string} cwd - Diretório de trabalho
+ * @param {string} command - Full command
+ * @param {string} cwd - Working directory
  * @returns {Promise<string>}
  */
 export async function execSimple(command, cwd = process.cwd()) {
@@ -122,9 +122,9 @@ export async function execSimple(command, cwd = process.cwd()) {
 }
 
 /**
- * Verifica se um comando está disponível no sistema
+ * Checks whether a command is available on the system
  *
- * @param {string} cmd - Nome do comando
+ * @param {string} cmd - Command name
  * @returns {Promise<boolean>}
  */
 export async function commandExists(cmd) {
@@ -140,7 +140,7 @@ export async function commandExists(cmd) {
 }
 
 /**
- * Executa compile e test para um projeto
+ * Runs compile and test for a project
  *
  * @param {object} options - { language, buildTool, cwd }
  * @returns {Promise<CompileTestResult>}

package/src/utils/file-count.js

@@ -0,0 +1,46 @@
+// file-count.js — ENG-1 empty-clone detection.
+//
+// Counts the files under a workspace root, EXCLUDING the `.git` directory
+// and the agent's own `.vh-workspace.json` registration sidecar.
+// A freshly-cloned repo that yields 0 files (excl. .git) is an EMPTY clone:
+// the remote repo is empty, the requested branch is wrong/empty, or the path
+// is bad. Callers use this to HARD-STOP structurally instead of silently
+// proceeding with an empty workspace (which dies later as "NEEDS_REVIEW,
+// 0 files read" — a false, un-actionable terminal state).
+
+import fs from "fs";
+import path from "path";
+import { WORKSPACE_SIDECAR } from "./open-gate.js";
+
+/**
+ * Count regular files under `rootDir`, skipping any `.git` directory at any
+ * depth. Never throws — unreadable dirs are skipped and counted as 0.
+ *
+ * @param {string} rootDir absolute path to the workspace/clone root
+ * @returns {number} number of non-.git files found under rootDir
+ */
+export function countFilesExcludingGit(rootDir) {
+    let count = 0;
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch (_) {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === ".git") continue;
+            // The registration sidecar is agent metadata, not repo content:
+            // an empty clone must still count as 0.
+            if (entry.name === WORKSPACE_SIDECAR && !entry.isDirectory()) continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            } else {
+                count++;
+            }
+        }
+    }
+    try { walk(rootDir); } catch (_) {}
+    return count;
+}

package/src/utils/fs-utils.js

@@ -15,7 +15,7 @@ export const access = promisify(fs.access);
 export const rename = promisify(fs.rename);
 
 /**
- * Verifica se um arquivo/diretório existe
+ * Checks whether a file/directory exists
  */
 export async function exists(p) {
     try {
@@ -27,7 +27,7 @@ export async function exists(p) {
 }
 
 /**
- * Cria diretório recursivamente se não existir
+ * Creates a directory recursively if it does not exist
  */
 export async function ensureDir(dir) {
     if (!(await exists(dir))) {
@@ -36,7 +36,7 @@ export async function ensureDir(dir) {
 }
 
 /**
- * Lista arquivos recursivamente
+ * Lists files recursively
  */
 export async function listRecursive(root, options = {}) {
     const {
@@ -89,7 +89,7 @@ export async function listRecursive(root, options = {}) {
 }
 
 /**
- * Copia diretório recursivamente
+ * Copies a directory recursively
  */
 export async function copyDir(src, dest) {
     await ensureDir(dest);
@@ -108,7 +108,7 @@ export async function copyDir(src, dest) {
 }
 
 /**
- * Remove diretório recursivamente
+ * Removes a directory recursively
  */
 export async function removeDir(dir) {
     if (!(await exists(dir))) return;
@@ -129,7 +129,7 @@ export async function removeDir(dir) {
 }
 
 /**
- * Calcula tamanho total de um diretório
+ * Calculates the total size of a directory
  */
 export async function dirSize(dir) {
     let totalSize = 0;
@@ -158,7 +158,7 @@ export async function dirSize(dir) {
 }
 
 /**
- * Lê arquivo JSON
+ * Reads a JSON file
  */
 export async function readJson(filePath) {
     const content = await readFile(filePath, 'utf8');
@@ -166,7 +166,7 @@ export async function readJson(filePath) {
 }
 
 /**
- * Escreve arquivo JSON
+ * Writes a JSON file
  */
 export async function writeJson(filePath, data, pretty = true) {
     const content = pretty
@@ -176,14 +176,14 @@ export async function writeJson(filePath, data, pretty = true) {
 }
 
 /**
- * Obtém extensão do arquivo normalizada
+ * Gets the normalized file extension
  */
 export function getExtension(filePath) {
     return path.extname(filePath).toLowerCase();
 }
 
 /**
- * Verifica se é arquivo de código
+ * Checks whether it is a code file
  */
 export function isCodeFile(filePath) {
     const codeExtensions = [

package/src/utils/multi-repo-open.js

@@ -0,0 +1,132 @@
+/**
+ * MULTI-REPO OPEN - partial-tolerant hydration of N repos under ONE workspace dir.
+ *
+ * Problem (proven in QA, 2026-09-22): POST /workspace/open with repos[] ran a
+ * sequential loop inside ONE try/catch. The first failed `git clone` (a repo
+ * the token could not see: "Repository not found") aborted the loop and the
+ * handler answered 500 - discarding the 9 repos that had already been cloned.
+ * Every scan then repeated all 10 clones just to die on the same one.
+ *
+ * Rules:
+ *  - every repo entry is validated BEFORE anything is cloned (bad entry -> 400,
+ *    nothing touched);
+ *  - each repo is cloned inside its OWN try/catch; a failure is recorded in
+ *    `failed[]` ({dir, repoUrl, error} - both URL and message MASKED) and the
+ *    loop moves on;
+ *  - with `allowPartial: false` (env MULTI_REPO_ALLOW_PARTIAL=false) the first
+ *    failure rethrows the raw git error - the pre-fix fail-all behavior;
+ *  - the caller decides the HTTP outcome: >=1 cloned -> 200 (partial when
+ *    failed.length > 0); 0 cloned -> 500 (or 400/404 for a tagged
+ *    BRANCH_NOT_FOUND / INVALID_BRANCH on the first error).
+ *
+ * Kept pure/dependency-injected so guard tests can pin every decision without
+ * a running server or git (same style as utils/open-gate.js).
+ */
+
+const SAFE_DIR = /^[A-Za-z0-9._-]+$/;
+
+/** MULTI_REPO_ALLOW_PARTIAL: default ON; only the literal "false" turns it off. */
+export function multiRepoAllowPartial(env = process.env) {
+    const raw = env && env.MULTI_REPO_ALLOW_PARTIAL;
+    if (typeof raw !== "string") return true;
+    return raw.trim().toLowerCase() !== "false";
+}
+
+/** Derive a stable on-disk dir name for a repo URL: org_repo. */
+export function repoDirName(repoUrl) {
+    let name = String(repoUrl).split('/').pop().replace(/\.git$/, '');
+    const parts = String(repoUrl).replace(/\.git$/, '').split('/');
+    if (parts.length >= 2) name = `${parts[parts.length - 2]}_${name}`;
+    return name;
+}
+
+function badRequest(message) {
+    const err = new Error(message);
+    err.code = "BAD_REQUEST";
+    err.httpStatus = 400;
+    return err;
+}
+
+/**
+ * Validate every repo entry up-front and resolve its per-repo dir.
+ * Throws a tagged BAD_REQUEST (httpStatus 400) on the first invalid entry,
+ * BEFORE any filesystem or git work happens.
+ *
+ * @returns {Array<{repo:object, dir:string, destDir:string}>}
+ */
+export function planRepos(repos, { workspaceDir, confineToRoot }) {
+    const plan = [];
+    for (const r of Array.isArray(repos) ? repos : []) {
+        if (!r || !r.repoUrl) throw badRequest("each repo needs a repoUrl");
+        const dir = (r.dir && SAFE_DIR.test(r.dir)) ? r.dir : repoDirName(r.repoUrl);
+        // Defense in depth: the per-repo dir must stay inside the workspace dir.
+        let destDir;
+        try {
+            destDir = confineToRoot(workspaceDir, dir);
+        } catch {
+            throw badRequest(`invalid repo dir: ${dir}`);
+        }
+        plan.push({ repo: r, dir, destDir });
+    }
+    return plan;
+}
+
+/**
+ * Clone/update every planned repo, tolerating individual failures.
+ *
+ * @param {Array<{repo:object, dir:string, destDir:string}>} plan  from planRepos()
+ * @param {object} deps
+ * @param {(args:{repoUrl:string,token?:string,branch?:string,destDir:string})=>Promise<void>} deps.cloneRepo
+ * @param {(dir:string)=>Promise<object>} deps.detectProject
+ * @param {(dir:string)=>Promise<void>} deps.mkdir
+ * @param {(s:string)=>string} deps.maskUrlCreds
+ * @param {string|undefined} deps.token   workspace-level token fallback
+ * @param {string} deps.branch            workspace-level branch fallback
+ * @param {boolean} deps.allowPartial
+ * @param {(destDir:string)=>Promise<void>} [deps.cleanupFailed] best-effort removal of
+ *        the per-repo dir a failed clone left behind (never throws through)
+ * @param {string} deps.wsId              for log lines only
+ * @param {{log:Function,warn:Function}} [deps.logger]
+ * @returns {Promise<{cloned:Array, failed:Array, firstError:Error|null}>}
+ *          `failed` entries are fully masked (safe to log/return);
+ *          `firstError` is the RAW first failure (for tagged-code handling
+ *          when nothing cloned) - never put it in a response unmasked.
+ */
+export async function hydrateRepos(plan, deps) {
+    const {
+        cloneRepo, detectProject, mkdir, maskUrlCreds,
+        token, branch, allowPartial = true, wsId = "?",
+        cleanupFailed = null, logger = console
+    } = deps;
+    const mask = typeof maskUrlCreds === "function" ? maskUrlCreds : (s) => s;
+    const cloned = [];
+    const failed = [];
+    let firstError = null;
+
+    for (const { repo: r, dir, destDir } of plan) {
+        const maskedUrl = mask(r.repoUrl);
+        try {
+            await mkdir(destDir);
+            logger.log(`[multi-repo] cloning ${maskedUrl} → ${wsId}/${dir}`);
+            await cloneRepo({ repoUrl: r.repoUrl, token: r.token ?? token, branch: r.branch ?? branch, destDir });
+            const meta = await detectProject(destDir);
+            cloned.push({ dir, path: destDir, repoUrl: maskedUrl, meta });
+        } catch (gitErr) {
+            const reason = mask((gitErr && gitErr.message) || String(gitErr));
+            logger.warn(`[multi-repo] clone FAILED ${maskedUrl} → ${wsId}/${dir}: ${reason}`);
+            if (typeof cleanupFailed === "function") {
+                try { await cleanupFailed(destDir); } catch { /* best-effort */ }
+            }
+            if (!allowPartial) throw gitErr;
+            if (!firstError) firstError = gitErr;
+            failed.push({ dir, repoUrl: maskedUrl, error: reason });
+        }
+    }
+
+    if (failed.length > 0) {
+        const kind = cloned.length > 0 ? "partial" : "all failed";
+        logger.warn(`[multi-repo] ${kind}: ${cloned.length} cloned, ${failed.length} failed - `
+            + failed.map((f) => `${f.dir} (${f.error})`).join("; "));
+    }
+    return { cloned, failed, firstError };
+}

package/src/utils/open-gate.js

@@ -0,0 +1,183 @@
+import path from "path";
+import fs from "fs";
+
+/**
+ * OPEN GATE - ownership classification for /workspace/open clone destinations.
+ *
+ * Problem (proven in QA, 2026-07-20 00:17Z, agent rev 00020-px6): a
+ * POST /workspace/open with repoUrl found a STALE clone dir on disk
+ * ("/tmp/workspaces/VISIONHAMMER_vh-e2e-sap-abap", left by a previous
+ * revision; the in-memory workspace registry was lost on restart). The
+ * handler blindly took the "alreadyCloned" reuse path and died on
+ * `git reset --hard origin/main` ("ambiguous argument 'origin/main'"),
+ * returning HTTP 500 - instead of treating the request as what it is:
+ * a HYDRATION request that should clone fresh.
+ *
+ * Rules (additive, fail-safe):
+ *  - destination does not exist            -> "fresh"          (clone, unchanged)
+ *  - destination exists, NOT registered    -> "clean_and_fresh" (orphan: remove stale
+ *                                             dir, clone fresh, register with tenant)
+ *  - registered for ANOTHER tenant (BOTH tenants known and different)
+ *                                          -> "deny"           (clear 409, dir untouched)
+ *  - registered otherwise (same tenant, or tenant unknown on either side)
+ *                                          -> "reuse"          (current refresh path,
+ *                                             byte-identical behavior)
+ * A registered directory is NEVER removed by this gate; only orphans
+ * (no registry entry at all) can be cleaned. The ROOT-RECOVERY tenant
+ * gate (utils/root-recovery.js) stays intact for dead-root RESOLUTION -
+ * this module only governs the open/clone hydration path.
+ *
+ * SIDECAR (QA 2026-09-22): the registry is an in-memory Map, so every Cloud
+ * Run cold start / new revision / second instance forgets EVERY registration
+ * and each existing clone dir becomes an "orphan" -> rm -rf + re-clone of all
+ * N repos on every scan. WorkspaceManager.open() now also writes a small
+ * JSON sidecar `<root>/.vh-workspace.json` {id, tenantId, root, openedAt}
+ * (NEVER tokens). When the registry has no entry, a VALID sidecar (its
+ * `root` resolves to the dir it lives in) counts as the registration and the
+ * SAME rules above apply to it: same/unknown tenant -> reuse, another tenant
+ * (both known) -> deny. A sidecar therefore never widens what an open may
+ * touch - it only stops a registered dir from being mistaken for an orphan.
+ *
+ * Kept pure/dependency-injected so guard tests can pin every decision
+ * without a running server (same style as utils/root-recovery.js).
+ */
+
+/**
+ * Tenant id carried by an /workspace/open request: body.tenantId wins,
+ * X-Tenant-ID header is the fallback (CORS already allows it). Blank/absent
+ * stays null (= unknown; the gate then never denies and never cleans a
+ * registered dir - pre-fix behavior).
+ */
+export function extractOpenTenantId(body, headers) {
+    const fromBody = body && typeof body.tenantId === "string" && body.tenantId.trim()
+        ? body.tenantId.trim() : null;
+    if (fromBody) return fromBody;
+    const raw = headers ? (headers["x-tenant-id"] || headers["X-Tenant-ID"]) : null;
+    return (typeof raw === "string" && raw.trim()) ? raw.trim() : null;
+}
+
+/** File name of the per-workspace registration sidecar. */
+export const WORKSPACE_SIDECAR = ".vh-workspace.json";
+
+/**
+ * Read + validate the registration sidecar of ONE directory. Returns a
+ * registry-shaped entry {id, root, tenantId, openedAt, source:"sidecar"} or
+ * null. Valid means: parseable JSON object, non-empty string `id`, and
+ * `root` resolving to the directory the file lives in (a copied/moved dir
+ * never carries its old registration along). Never throws.
+ */
+export function readWorkspaceSidecar(dir, opts = {}) {
+    const readFileSync = opts.readFileSync || fs.readFileSync;
+    try {
+        const abs = path.resolve(String(dir || "").trim() || "/");
+        if (abs === "/") return null;
+        const raw = readFileSync(path.join(abs, WORKSPACE_SIDECAR), "utf8");
+        const data = JSON.parse(raw);
+        if (!data || typeof data !== "object") return null;
+        if (typeof data.id !== "string" || !data.id.trim()) return null;
+        if (typeof data.root !== "string" || path.resolve(data.root) !== abs) return null;
+        const tenantId = (typeof data.tenantId === "string" && data.tenantId.trim())
+            ? data.tenantId.trim() : null;
+        return {
+            id: data.id.trim(),
+            root: abs,
+            tenantId,
+            openedAt: typeof data.openedAt === "string" ? data.openedAt : null,
+            source: "sidecar"
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Find the registry entry that OWNS a destination dir: exact root match, or
+ * a registered root that is an ANCESTOR of the destination (multi-repo
+ * layout registers the parent workspace dir; its per-repo sub-dirs belong
+ * to that registration). Returns the entry or null (= orphan).
+ *
+ * Fallback (opts.readSidecar, default readWorkspaceSidecar): when the
+ * in-memory registry knows nothing, a valid sidecar in the destination dir
+ * or its parent (multi-repo sub-dir -> parent workspace dir) is the
+ * registration. Pass `readSidecar: null` to disable (pure registry lookup).
+ */
+export function findRegistrationForDir(destDir, registry, opts = {}) {
+    const dest = path.resolve(String(destDir || "").trim() || "/");
+    for (const w of Array.isArray(registry) ? registry : []) {
+        if (!w || !w.root) continue;
+        let root;
+        try { root = path.resolve(String(w.root)); } catch { continue; }
+        if (root === dest) return w;
+        if (dest.startsWith(root + path.sep)) return w;
+    }
+    const readSidecar = opts.readSidecar === undefined ? readWorkspaceSidecar : opts.readSidecar;
+    if (typeof readSidecar !== "function" || dest === "/") return null;
+    for (const candidate of [dest, path.dirname(dest)]) {
+        if (candidate === "/") break;
+        const entry = readSidecar(candidate);
+        if (entry) return entry;
+    }
+    return null;
+}
+
+/**
+ * Classify what /workspace/open may do with its clone destination.
+ *
+ * @param {string} destDir  the computed clone destination
+ * @param {object} opts
+ * @param {Array<{id:string,root:string,tenantId?:string|null}>} opts.registry
+ *                          live workspaces (wsManager.list())
+ * @param {string|null} opts.requestTenantId tenant of THIS open request (null = unknown)
+ * @param {(p:string)=>boolean} [opts.existsSync] injectable for tests
+ * @param {((dir:string)=>object|null)|null} [opts.readSidecar] injectable for tests
+ *                          (null disables the sidecar fallback)
+ * @returns {{action:"fresh"|"clean_and_fresh"|"reuse"|"deny", reason:string,
+ *            ownerWorkspaceId?:string, ownerTenantId?:string|null,
+ *            registration?:object}}  `registration` is the owning entry
+ *            (registry or sidecar; `source:"sidecar"` when rehydrated from disk)
+ */
+export function classifyOpenDestination(destDir, opts = {}) {
+    const existsSync = opts.existsSync || fs.existsSync;
+    let onDisk = false;
+    try { onDisk = existsSync(String(destDir || "")); } catch { onDisk = false; }
+    if (!onDisk) return { action: "fresh", reason: "destination_missing" };
+
+    const reg = findRegistrationForDir(destDir, opts.registry, { readSidecar: opts.readSidecar });
+    if (!reg) return { action: "clean_and_fresh", reason: "orphan_dir_no_registration" };
+
+    const ownerTenant = reg.tenantId || null;
+    const reqTenant = opts.requestTenantId || null;
+    if (ownerTenant && reqTenant && ownerTenant !== reqTenant) {
+        return {
+            action: "deny",
+            reason: "owned_by_another_tenant",
+            ownerWorkspaceId: reg.id,
+            ownerTenantId: ownerTenant,
+            registration: reg
+        };
+    }
+    return {
+        action: "reuse",
+        reason: ownerTenant ? "registered_same_or_unknown_tenant" : "registered_tenant_unknown",
+        ownerWorkspaceId: reg.id,
+        ownerTenantId: ownerTenant,
+        registration: reg
+    };
+}
+
+/**
+ * Removal guard for orphan cleanup: the dir must be STRICTLY inside the
+ * cache/mount base (never the base itself, never "/", never a traversal
+ * escape). Pure + total: any weird input -> false (nothing is removed).
+ */
+export function isSafeToRemove(baseDir, dir) {
+    try {
+        const base = path.resolve(String(baseDir || "").trim());
+        const target = path.resolve(String(dir || "").trim());
+        if (!base || base === "/" || !target || target === "/") return false;
+        if (target === base) return false;
+        return target.startsWith(base + path.sep);
+    } catch {
+        return false;
+    }
+}

package/src/utils/ranged-read.js

@@ -0,0 +1,65 @@
+/**
+ * RANGED READS (Claude Code model) - pure slicing logic for
+ * GET /workspace/file-content. Huge files used to be returned whole,
+ * blowing the AI's context budget; the model then burned its iteration
+ * budget extracting chunks via `sed` in run_command.
+ *
+ * Contract:
+ *  - explicit startLine (1-based) -> that slice (endLine clamped to EOF;
+ *    absent endLine = one cap-sized page from startLine)
+ *  - no range and file within cap -> null (caller returns the original
+ *    response byte-identical to before)
+ *  - no range and file over cap -> first page + truncated:true + an
+ *    actionable pagination hint the model can follow in ONE step
+ *
+ * Pure and dependency-free so guard tests pin it without a server.
+ */
+export function sliceFileContent(file, { startLine, endLine, lineCap = 2000 } = {}) {
+    const allLines = String(file.content ?? "").split("\n");
+    const totalLines = allLines.length;
+    const cap = Number.isFinite(lineCap) && lineCap >= 1 ? Math.floor(lineCap) : 2000;
+
+    const start = Number.isFinite(startLine) ? Math.floor(startLine) : NaN;
+    const end = Number.isFinite(endLine) ? Math.floor(endLine) : NaN;
+
+    if (Number.isFinite(start) && start >= 1) {
+        const from = Math.min(start, totalLines);
+        const to = Number.isFinite(end) && end >= from
+            ? Math.min(end, totalLines)
+            : Math.min(from + cap - 1, totalLines);
+        const slice = allLines.slice(from - 1, to).join("\n");
+        return {
+            path: file.path,
+            content: slice,
+            lines: to - from + 1,
+            startLine: from,
+            endLine: to,
+            totalLines,
+            size: byteLen(slice)
+        };
+    }
+
+    if (totalLines > cap) {
+        const slice = allLines.slice(0, cap).join("\n");
+        return {
+            path: file.path,
+            content: slice,
+            lines: cap,
+            startLine: 1,
+            endLine: cap,
+            totalLines,
+            truncated: true,
+            hint: "File has " + totalLines + " lines; showing 1-" + cap + ". "
+                + "Request the rest with ?startLine=&endLine= (e.g. startLine="
+                + (cap + 1) + "&endLine=" + Math.min(cap * 2, totalLines) + ").",
+            size: byteLen(slice)
+        };
+    }
+
+    // Within cap, no range: caller keeps the original response unchanged.
+    return null;
+}
+
+function byteLen(s) {
+    return typeof Buffer !== "undefined" ? Buffer.byteLength(s, "utf8") : s.length;
+}

package/src/utils/request-guards.js

@@ -0,0 +1,77 @@
+/**
+ * request-guards.js — input validation for request fields that reach the
+ * network or a shell. Pure functions, unit-tested in test/request-guards.test.js.
+ */
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/**
+ * The agent's own listeners. A "test the customer's local service" request
+ * must never be pointed back at the agent itself (that would turn an SSRF
+ * into an auth bypass of the loopback perimeter).
+ */
+export function agentOwnPorts(env = process.env) {
+    const ports = [env.PORT, env.LOCAL_AGENT_PORT, env.MCP_PORT, 5055, 5056]
+        .map(p => parseInt(p, 10)).filter(p => Number.isInteger(p) && p > 0);
+    return new Set(ports);
+}
+
+/**
+ * Accepts only http://localhost|127.0.0.1|[::1]:<port>/<path>, with no
+ * userinfo, and not addressed to the agent's own ports.
+ * Returns { ok: true, url } or { ok: false, reason }.
+ *
+ * The previous check was `url.startsWith('http://localhost')`, which accepted
+ * http://localhost.attacker.tld/ and http://localhost@10.0.0.5/ — SSRF into
+ * the customer network.
+ */
+export function validateLocalTestUrl(raw, ownPorts = agentOwnPorts()) {
+    if (typeof raw !== "string" || !raw) return { ok: false, reason: "url is required" };
+    let u;
+    try { u = new URL(raw); } catch { return { ok: false, reason: "invalid url" }; }
+    if (u.protocol !== "http:" && u.protocol !== "https:") return { ok: false, reason: "only http(s) allowed" };
+    if (u.username || u.password) return { ok: false, reason: "credentials in url not allowed" };
+    if (!LOOPBACK_HOSTS.has(u.hostname)) return { ok: false, reason: "only localhost URLs allowed" };
+    const port = u.port ? parseInt(u.port, 10) : (u.protocol === "https:" ? 443 : 80);
+    if (ownPorts.has(port)) return { ok: false, reason: "the agent's own ports are not testable targets" };
+    return { ok: true, url: u.toString() };
+}
+
+/** Builds a loopback URL from a port + path supplied by the caller. */
+export function buildLocalTestUrl(port, reqPath, ownPorts = agentOwnPorts()) {
+    if (!/^\d{1,5}$/.test(String(port))) return { ok: false, reason: "invalid port" };
+    const p = parseInt(port, 10);
+    if (!Number.isInteger(p) || p < 1 || p > 65535) return { ok: false, reason: "invalid port" };
+    if (typeof reqPath !== "string" || !reqPath.startsWith("/") || reqPath.startsWith("//")) {
+        return { ok: false, reason: "path must start with a single '/'" };
+    }
+    if (/[\s\\]/.test(reqPath)) return { ok: false, reason: "invalid characters in path" };
+    return validateLocalTestUrl(`http://localhost:${p}${reqPath}`, ownPorts);
+}
+
+/** Tenant ids become path segments under /mnt/workspaces. */
+export function isSafeTenantId(tenantId) {
+    return typeof tenantId === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(tenantId);
+}
+
+/**
+ * Remote git URLs the agent may clone. https:// or scp-style git@host:path.
+ * Rejects file://, ext::, local paths, option injection (leading '-') and
+ * shell metacharacters.
+ */
+export function validateGitUrl(raw) {
+    if (typeof raw !== "string" || !raw.trim()) return { ok: false, reason: "gitUrl is required" };
+    const s = raw.trim();
+    if (s.startsWith("-")) return { ok: false, reason: "invalid gitUrl" };
+    if (/[\s"'`$;&|<>\\]/.test(s)) return { ok: false, reason: "invalid characters in gitUrl" };
+    if (/^git@[A-Za-z0-9.-]+:[A-Za-z0-9._\/-]+$/.test(s)) return { ok: true };
+    let u;
+    try { u = new URL(s); } catch { return { ok: false, reason: "invalid gitUrl" }; }
+    if (u.protocol !== "https:" && u.protocol !== "ssh:") return { ok: false, reason: "only https:// or ssh git URLs allowed" };
+    return { ok: true };
+}
+
+/** CLI tool names interpolated into `which`/`brew install`. */
+export function isSafeToolName(name) {
+    return typeof name === "string" && /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/.test(name);
+}