deepdebug-local-agent 1.0.23 → 1.2.0

package/src/utils/request-signing.js

@@ -0,0 +1,342 @@
+/**
+ * request-signing.js — Ed25519 verification of commands sent by the platform.
+ *
+ * WHY. X-Agent-Token proves "someone holding the per-workspace secret"; it does
+ * not prove the request came from the VisionHammer platform, is fresh, or was
+ * aimed at THIS tenant's agent. Every command the gateway / agents send is now
+ * signed with the platform private key (Secret Manager `local-agent-signing-key`)
+ * and the agent verifies it with the trusted public key(s) it was provisioned
+ * with. X-Agent-Token stays in place as a second factor (agent-auth.js).
+ *
+ * PROTOCOL v1 (HTTP). Headers:
+ *   X-VH-Key-Id        id of the signing key (selects the trusted public key)
+ *   X-VH-Timestamp     unix epoch SECONDS
+ *   X-VH-Nonce         16..128 chars [A-Za-z0-9_-], unique per request
+ *   X-VH-Tenant-Id     tenant the platform acts for ('' when unknown)
+ *   X-VH-Workspace-Id  workspace the platform acts for ('' when unknown)
+ *   X-VH-Signature     base64 Ed25519 signature over the canonical string:
+ *
+ *     VH-AGENT-SIG-V1\n<METHOD>\n<raw path?query>\n<sha256hex(body bytes)>\n
+ *     <tenantId>\n<workspaceId>\n<timestamp>\n<nonce>
+ *
+ * WS tunnel envelope: { requestId, command, params, paramsRaw, sig: { keyId,
+ * timestamp, nonce, tenantId, workspaceId, signature } } with METHOD = "WS",
+ * path = command and body = the exact UTF-8 bytes of `paramsRaw`. A verified
+ * envelope executes JSON.parse(paramsRaw) — never the unsigned `params` copy.
+ *
+ * REJECT: unknown key id, bad signature, |now - timestamp| > 60s, a nonce seen
+ * before (in-memory LRU, TTL 2x skew), tenant / workspace different from the
+ * agent's configured identity.
+ *
+ * MODES (LOCAL_AGENT_SIGNATURE_MODE): off | warn | enforce (default; an unset
+ * or unrecognised value is enforce, so a typo never fails open).
+ *   warn     verify + log, never reject — explicit opt-out for agents whose
+ *            platform side does not sign yet.
+ *   enforce  reject (401) anything that does not verify.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SIG_PREFIX = "VH-AGENT-SIG-V1";
+export const HEADERS = Object.freeze({
+    keyId: "x-vh-key-id",
+    timestamp: "x-vh-timestamp",
+    nonce: "x-vh-nonce",
+    tenantId: "x-vh-tenant-id",
+    workspaceId: "x-vh-workspace-id",
+    signature: "x-vh-signature",
+    internal: "x-vh-internal",
+});
+export const MAX_SKEW_SECONDS = 60;
+const NONCE_RE = /^[A-Za-z0-9_-]{16,128}$/;
+const PUBLIC_PATHS = new Set(["/health", "/metrics"]);
+// SPKI DER prefix of an Ed25519 public key (RFC 8410): a raw 32-byte key is
+// accepted too and wrapped with it.
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export const MODES = Object.freeze(["off", "warn", "enforce"]);
+
+export function resolveMode(raw, fallback = "enforce") {
+    const m = String(raw || "").trim().toLowerCase();
+    return MODES.includes(m) ? m : fallback;
+}
+
+export function sha256Hex(buf) {
+    return crypto.createHash("sha256").update(buf ?? Buffer.alloc(0)).digest("hex");
+}
+
+export function canonicalString({ method, pathAndQuery, bodySha256, tenantId, workspaceId, timestamp, nonce }) {
+    return [SIG_PREFIX, String(method || "").toUpperCase(), pathAndQuery || "/", bodySha256,
+        tenantId || "", workspaceId || "", String(timestamp), nonce].join("\n");
+}
+
+/**
+ * Parses one public key: PEM (SPKI), base64 SPKI DER (44 bytes) or base64 /
+ * base64url raw 32-byte key. Returns a KeyObject or throws.
+ */
+export function parsePublicKey(material) {
+    const s = String(material || "").trim();
+    if (!s) throw new Error("empty public key");
+    if (s.includes("BEGIN PUBLIC KEY")) {
+        const k = crypto.createPublicKey(s);
+        if (k.asymmetricKeyType !== "ed25519") throw new Error("public key is not Ed25519");
+        return k;
+    }
+    const der = Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+    const spki = der.length === 32 ? Buffer.concat([ED25519_SPKI_PREFIX, der]) : der;
+    const k = crypto.createPublicKey({ key: spki, format: "der", type: "spki" });
+    if (k.asymmetricKeyType !== "ed25519") throw new Error("public key is not Ed25519");
+    return k;
+}
+
+/**
+ * Trusted keys: LOCAL_AGENT_SIGNING_PUBLIC_KEYS="kid1=<b64>,kid2=<b64>" (the
+ * BYOC provisioning env) plus the image default file (JSON
+ * [{ "keyId": "...", "publicKey": "..." }]) at LOCAL_AGENT_SIGNING_KEYS_FILE or
+ * src/config/trusted-signing-keys.json. Several keys = rotation window.
+ * Returns { keys: Map<kid, KeyObject>, errors: string[] }.
+ */
+export function loadTrustedKeys(env = process.env, { defaultFile = defaultKeysFile() } = {}) {
+    const keys = new Map();
+    const errors = [];
+    const add = (kid, material, src) => {
+        const id = String(kid || "").trim();
+        if (!/^[A-Za-z0-9._:-]{1,64}$/.test(id)) { errors.push(`${src}: invalid key id`); return; }
+        try { keys.set(id, parsePublicKey(material)); }
+        catch (e) { errors.push(`${src}: key ${id}: ${e.message}`); }
+    };
+    const file = env.LOCAL_AGENT_SIGNING_KEYS_FILE || defaultFile;
+    if (file) {
+        try {
+            if (fs.existsSync(file)) {
+                const list = JSON.parse(fs.readFileSync(file, "utf-8"));
+                for (const e of Array.isArray(list) ? list : (list.keys || [])) add(e.keyId, e.publicKey, path.basename(file));
+            }
+        } catch (e) { errors.push(`${path.basename(file)}: ${e.message}`); }
+    }
+    for (const entry of String(env.LOCAL_AGENT_SIGNING_PUBLIC_KEYS || "").split(/[,\s]+/).filter(Boolean)) {
+        const i = entry.indexOf("=");
+        if (i <= 0) { errors.push("LOCAL_AGENT_SIGNING_PUBLIC_KEYS: entries must be keyId=publicKey"); continue; }
+        add(entry.slice(0, i), entry.slice(i + 1), "LOCAL_AGENT_SIGNING_PUBLIC_KEYS");
+    }
+    return { keys, errors };
+}
+
+function defaultKeysFile() {
+    try {
+        return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "config", "trusted-signing-keys.json");
+    } catch {
+        return null; // bundled (cjs) build: env only
+    }
+}
+
+/** Nonce replay cache: Map in insertion order = LRU by first sight, bounded. */
+export class NonceCache {
+    constructor({ ttlMs = 2 * MAX_SKEW_SECONDS * 1000, max = 100_000, now = () => Date.now() } = {}) {
+        this.ttlMs = ttlMs;
+        this.max = max;
+        this.now = now;
+        this.map = new Map();
+    }
+    /** true when first seen (and records it); false on replay. */
+    checkAndRemember(nonce) {
+        const t = this.now();
+        this.#sweep(t);
+        const exp = this.map.get(nonce);
+        if (exp !== undefined && exp > t) return false;
+        this.map.delete(nonce);
+        this.map.set(nonce, t + this.ttlMs);
+        while (this.map.size > this.max) this.map.delete(this.map.keys().next().value);
+        return true;
+    }
+    #sweep(t) {
+        for (const [k, exp] of this.map) {
+            if (exp > t) break; // insertion order ~ expiry order
+            this.map.delete(k);
+        }
+    }
+    get size() { return this.map.size; }
+}
+
+/** Identity this agent serves; blank = shared operator agent (any tenant). */
+export function resolveIdentity(env = process.env, fileCfg = {}) {
+    return {
+        tenantId: String(env.LOCAL_AGENT_TENANT_ID || env.TENANT_ID || fileCfg.tenantId || "").trim(),
+        workspaceId: String(env.LOCAL_AGENT_WORKSPACE_ID || env.WORKSPACE_ID || "").trim(),
+        requireWorkspace: String(env.LOCAL_AGENT_REQUIRE_WORKSPACE || "").toLowerCase() === "true",
+    };
+}
+
+export function resolveSigningConfig(env = process.env, opts = {}) {
+    const { keys, errors } = loadTrustedKeys(env, opts);
+    return {
+        mode: resolveMode(env.LOCAL_AGENT_SIGNATURE_MODE),
+        keys,
+        keyErrors: errors,
+        identity: resolveIdentity(env, opts.fileCfg || {}),
+        maxSkewSeconds: MAX_SKEW_SECONDS,
+        nonces: opts.nonces || new NonceCache(),
+        now: opts.now || (() => Date.now()),
+    };
+}
+
+/**
+ * Pure verification. `sig` = { keyId, timestamp, nonce, tenantId, workspaceId,
+ * signature }. Returns { ok: true, tenantId, workspaceId, keyId } or
+ * { ok: false, reason }. The nonce is only consumed when everything else passed.
+ */
+export function verifySignature({ method, pathAndQuery, body, sig }, cfg) {
+    if (!sig || !sig.signature) return { ok: false, reason: "unsigned request" };
+    const { keyId, nonce } = sig;
+    const tenantId = sig.tenantId || "";
+    const workspaceId = sig.workspaceId || "";
+    if (!cfg.keys || cfg.keys.size === 0) return { ok: false, reason: "no trusted signing keys configured" };
+    const key = cfg.keys.get(String(keyId || ""));
+    if (!key) return { ok: false, reason: `unknown signing key id '${String(keyId || "").slice(0, 64)}'` };
+    const ts = Number(sig.timestamp);
+    if (!/^\d{9,11}$/.test(String(sig.timestamp || "")) || !Number.isFinite(ts)) return { ok: false, reason: "invalid timestamp" };
+    const skew = Math.abs(Math.floor(cfg.now() / 1000) - ts);
+    if (skew > cfg.maxSkewSeconds) return { ok: false, reason: `timestamp skew ${skew}s exceeds ${cfg.maxSkewSeconds}s` };
+    if (!NONCE_RE.test(String(nonce || ""))) return { ok: false, reason: "invalid nonce" };
+    const data = Buffer.from(canonicalString({
+        method, pathAndQuery, bodySha256: sha256Hex(body), tenantId, workspaceId, timestamp: sig.timestamp, nonce,
+    }), "utf-8");
+    let good = false;
+    try {
+        good = crypto.verify(null, data, key, Buffer.from(String(sig.signature), "base64"));
+    } catch { good = false; }
+    if (!good) return { ok: false, reason: "bad signature" };
+    const id = cfg.identity || {};
+    if (id.tenantId && tenantId !== id.tenantId) return { ok: false, reason: "tenant mismatch with the agent's configured identity" };
+    if (id.workspaceId && (workspaceId || id.requireWorkspace) && workspaceId !== id.workspaceId) {
+        return { ok: false, reason: "workspace mismatch with the agent's configured identity" };
+    }
+    if (!cfg.nonces.checkAndRemember(`${keyId}:${nonce}`)) return { ok: false, reason: "replayed nonce" };
+    return { ok: true, tenantId, workspaceId, keyId };
+}
+
+export function sigFromHeaders(headers = {}) {
+    if (!headers[HEADERS.signature]) return null;
+    return {
+        keyId: headers[HEADERS.keyId],
+        timestamp: headers[HEADERS.timestamp],
+        nonce: headers[HEADERS.nonce],
+        tenantId: headers[HEADERS.tenantId] || "",
+        workspaceId: headers[HEADERS.workspaceId] || "",
+        signature: headers[HEADERS.signature],
+    };
+}
+
+/** Per-process secret for the agent's own loopback calls (WS tunnel -> HTTP). */
+const INTERNAL_TOKEN = crypto.randomBytes(32).toString("base64url");
+export function internalSignatureHeaders() {
+    return { "X-VH-Internal": INTERNAL_TOKEN };
+}
+function isInternal(headers, remoteAddress) {
+    const v = headers[HEADERS.internal];
+    if (typeof v !== "string" || v.length !== INTERNAL_TOKEN.length) return false;
+    const a = String(remoteAddress || "").replace(/^::ffff:/, "");
+    if (!(a === "::1" || /^127\./.test(a))) return false;
+    return crypto.timingSafeEqual(Buffer.from(v), Buffer.from(INTERNAL_TOKEN));
+}
+
+/** Rate-limited warn log: one line per (reason, path) per minute. */
+const lastLog = new Map();
+export function logDecision(level, key, msg, now = Date.now()) {
+    const last = lastLog.get(key) || 0;
+    if (now - last < 60_000) return;
+    lastLog.set(key, now);
+    if (lastLog.size > 1000) lastLog.clear();
+    (level === "error" ? console.error : console.warn)(msg);
+}
+
+export const stats = { verified: 0, failed: 0, rejected: 0, unsigned: 0 };
+
+/**
+ * Express middleware. Mount AFTER the JSON body parser (which must keep the
+ * raw bytes in req.rawBody via `verify`). Sets req.vhSignature = { verified,
+ * tenantId, workspaceId, reason }.
+ */
+export function createSignatureMiddleware(cfg = resolveSigningConfig()) {
+    return function agentSignature(req, res, next) {
+        const method = (req.method || "GET").toUpperCase();
+        if (method === "OPTIONS" || ((method === "GET" || method === "HEAD") && PUBLIC_PATHS.has(req.path))) return next();
+        if (cfg.mode === "off") { req.vhSignature = { verified: false, reason: "signature mode off" }; return next(); }
+        if (isInternal(req.headers, req.socket?.remoteAddress)) {
+            req.vhSignature = { verified: true, internal: true, tenantId: req.headers[HEADERS.tenantId] || "", workspaceId: req.headers[HEADERS.workspaceId] || "" };
+            return next();
+        }
+        const sig = sigFromHeaders(req.headers);
+        const out = verifySignature({ method, pathAndQuery: req.originalUrl || req.url, body: req.rawBody, sig }, cfg);
+        if (out.ok) {
+            stats.verified++;
+            req.vhSignature = { verified: true, tenantId: out.tenantId, workspaceId: out.workspaceId, keyId: out.keyId };
+            return next();
+        }
+        if (!sig) stats.unsigned++; else stats.failed++;
+        req.vhSignature = { verified: false, reason: out.reason };
+        if (cfg.mode === "enforce") {
+            stats.rejected++;
+            logDecision("warn", `rej:${out.reason}:${req.path}`, `[agent-sig] REJECTED ${method} ${req.path}: ${out.reason}`);
+            return res.status(401).json({ ok: false, error: "invalid command signature", reason: out.reason });
+        }
+        logDecision("warn", `warn:${out.reason}:${req.path}`, `[agent-sig] WARN (would reject in enforce) ${method} ${req.path}: ${out.reason}`);
+        return next();
+    };
+}
+
+/**
+ * Verifies a WS tunnel envelope. Returns { ok, params, reason, verified }:
+ * `params` is what the command must run with (the signed paramsRaw when the
+ * envelope verified; the legacy object otherwise, in warn/off).
+ */
+export function verifyWsEnvelope(envelope, cfg) {
+    const legacy = envelope.params || {};
+    if (cfg.mode === "off") return { ok: true, verified: false, params: legacy };
+    const raw = typeof envelope.paramsRaw === "string" ? envelope.paramsRaw : null;
+    const out = raw == null
+        ? { ok: false, reason: "unsigned request" }
+        : verifySignature({ method: "WS", pathAndQuery: String(envelope.command || ""), body: Buffer.from(raw, "utf-8"), sig: envelope.sig }, cfg);
+    if (out.ok) {
+        let params;
+        try { params = JSON.parse(raw); } catch { return { ok: false, verified: false, reason: "paramsRaw is not JSON", params: {} }; }
+        stats.verified++;
+        return { ok: true, verified: true, params: params || {}, tenantId: out.tenantId, workspaceId: out.workspaceId };
+    }
+    if (!envelope.sig) stats.unsigned++; else stats.failed++;
+    if (cfg.mode === "enforce") {
+        stats.rejected++;
+        logDecision("warn", `wsrej:${out.reason}:${envelope.command}`, `[agent-sig] REJECTED WS ${envelope.command}: ${out.reason}`);
+        return { ok: false, verified: false, reason: out.reason, params: {} };
+    }
+    logDecision("warn", `wswarn:${out.reason}:${envelope.command}`, `[agent-sig] WARN (would reject in enforce) WS ${envelope.command}: ${out.reason}`);
+    return { ok: true, verified: false, reason: out.reason, params: legacy };
+}
+
+export function describeSigningConfig(cfg) {
+    const ids = [...cfg.keys.keys()].join(",") || "none";
+    const who = cfg.identity.tenantId ? `tenant=${cfg.identity.tenantId}` : "any tenant (shared agent)";
+    return `mode=${cfg.mode}, trusted keys=[${ids}], identity=${who}`
+        + (cfg.keyErrors.length ? `, key errors: ${cfg.keyErrors.join("; ")}` : "");
+}
+
+/** body-parser `verify` hook: keeps the exact bytes the signature covers. */
+export function captureRawBody(req, _res, buf) {
+    req.rawBody = Buffer.from(buf);
+}
+
+/** Process-wide signing config (one nonce cache for the 5055 API, the MCP bridge and the WS tunnel). */
+let shared = null;
+export function getSigningConfig() {
+    if (!shared) {
+        let fileCfg = {};
+        try {
+            const home = process.env.HOME || process.env.USERPROFILE;
+            if (home) fileCfg = JSON.parse(fs.readFileSync(path.join(home, ".deepdebug", "config.json"), "utf-8"));
+        } catch { /* no local config */ }
+        shared = resolveSigningConfig(process.env, { fileCfg });
+    }
+    return shared;
+}

package/src/utils/root-recovery.js

@@ -0,0 +1,244 @@
+import path from "path";
+import fs from "fs";
+import { WORKSPACE_SIDECAR, readWorkspaceSidecar } from "./open-gate.js";
+
+/** Hard cap on the sidecar bytes read during recovery (it is ~200 bytes). */
+export const SIDECAR_MAX_BYTES = 16 * 1024;
+
+/**
+ * ROOT-RECOVERY - transversal live-root resolution for stateless agents.
+ *
+ * Problem (proven in QA, 2026-07-19): orchestrating loops (gateway v1,
+ * orchestrator/agent2 v2, indexer, IDE) send X-Workspace-Root from a
+ * PERSISTED workspace row - typically an NFS-era path like
+ * "/mnt/workspaces/<tenant>/<repo>". On a stateless agent (no NFS mount)
+ * the actual clone made by /workspace/clone lands under
+ * WORKSPACE_MOUNT (e.g. "/tmp/workspaces/<owner>_<repo>"), so every
+ * read/search against the dead header path returns 404/empty forever and
+ * the AI burns its whole iteration budget re-preparing workspaces.
+ *
+ * This module recovers the LIVE root for a dead header root, the way
+ * Claude Code / Copilot's agent anchor tools to the session's real
+ * checkout: the filesystem the agent itself populated is the authority.
+ *
+ * Safety rules:
+ *  - NEVER overrides a header root that exists on disk (byte-identical
+ *    behavior for every caller that already works).
+ *  - Matching is conservative: the recovered directory's basename must be
+ *    exactly the dead root's basename, or end with "_<basename>" (the
+ *    cloud-clone "<owner>_<repo>" layout). No fuzzy matching.
+ *  - TENANT GATE (2026-07-19, multi-tenant shared agent): a dead root of
+ *    tenant A must NEVER recover to a clone hydrated for tenant B just
+ *    because the repo basenames collide. Rules (fail-closed):
+ *      - workspace-id match (step 1) stays authoritative, EXCEPT when both
+ *        sides have a KNOWN tenant and they differ -> no recovery.
+ *      - basename match (step 2) and disk scan (step 3) require the dead
+ *        root's tenant to be KNOWN (first path segment after
+ *        "/mnt/workspaces/") AND the candidate clone to have the SAME
+ *        tenant registered. Unknown tenant on either side -> no recovery
+ *        -> caller falls into the structured workspace_root_not_hydrated
+ *        fail-fast with its actionable hint.
+ *  - SIDECAR TENANT (2026-10-09): the registry is in-memory, so a clone whose
+ *    registration was lost (cold start / second revision / "default" key
+ *    overwritten) has an unknown tenant and was denied forever. For the disk
+ *    scan ONLY, when the registry has no tenant for a candidate dir, the
+ *    candidate's tenant is read from the sidecar the agent itself wrote there
+ *    (`.vh-workspace.json`, see WorkspaceManager.writeSidecar). It is used
+ *    only if ALL hold: the candidate dir really lives inside the clone mount
+ *    (realpath); the sidecar is a regular file (not a symlink) of <= 16 KB
+ *    whose realpath stays inside the candidate dir; it parses as strict JSON
+ *    with a non-empty `id`, a `root` equal to that dir and a non-empty string
+ *    `tenantId`; and that tenantId EQUALS the dead root's tenant (the same
+ *    tenantGateAllows comparison as everywhere). Any other field (repoUrl,
+ *    ...) is ignored. A registry tenant, when present, always wins and the
+ *    sidecar is not consulted (byte-identical to the previous behaviour).
+ *    Nothing else is relaxed: no adoption by git remote, no fuzzy matching.
+ *  - Never throws; returns null when nothing can be recovered.
+ *
+ * Kept pure/dependency-injected so guard tests can pin the decision
+ * without a running server (same style as utils/sandbox.js tests).
+ */
+
+/**
+ * Extract the tenant id from an NFS-era workspace root.
+ * "/mnt/workspaces/<tenant>/<repo>[/...]" -> "<tenant>"; anything else -> null.
+ * Pure + total: never throws, unknown stays null (fail-closed downstream).
+ */
+export function tenantOfNfsRoot(root) {
+    const m = /^\/mnt\/workspaces\/([^/]+)\/.+/.exec(String(root || "").trim());
+    return m ? m[1] : null;
+}
+
+/**
+ * Tenant gate for basename/scan recovery: BOTH tenants must be known and
+ * equal. Unknown on either side denies (fail-closed).
+ */
+export function tenantGateAllows(deadTenant, candidateTenant) {
+    return Boolean(deadTenant) && Boolean(candidateTenant) && deadTenant === candidateTenant;
+}
+
+function isWithin(child, parent) {
+    return child === parent || child.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep);
+}
+
+/**
+ * Tenant a clone dir was hydrated for, from its own sidecar. Fail-closed:
+ * returns {tenantId:null, reason} unless every containment/shape check
+ * passes (see the SIDECAR TENANT note above). Never throws, never logs data.
+ */
+export function sidecarTenantOf(candDir, mountDir) {
+    const no = (reason) => ({ tenantId: null, reason });
+    try {
+        const realMount = fs.realpathSync(mountDir);
+        const realDir = fs.realpathSync(candDir);
+        if (realDir === realMount || !isWithin(realDir, realMount)) return no("candidate-outside-mount");
+        const file = path.join(candDir, WORKSPACE_SIDECAR);
+        let st;
+        try { st = fs.lstatSync(file); } catch { return no("missing"); }
+        if (st.isSymbolicLink() || !st.isFile()) return no("not-a-regular-file");
+        if (!isWithin(fs.realpathSync(file), realDir)) return no("escapes-candidate-dir");
+        if (st.size > SIDECAR_MAX_BYTES) return no("oversized");
+        const capped = (f) => {
+            const fd = fs.openSync(f, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+            try {
+                const buf = Buffer.alloc(SIDECAR_MAX_BYTES + 1);
+                const n = fs.readSync(fd, buf, 0, buf.length, 0);
+                if (n > SIDECAR_MAX_BYTES) throw new Error("oversized");
+                return buf.toString("utf8", 0, n);
+            } finally { fs.closeSync(fd); }
+        };
+        // Reuse the open-gate reader (id non-empty, root == this dir).
+        const entry = readWorkspaceSidecar(path.resolve(candDir), { readFileSync: capped });
+        if (!entry) return no("malformed-or-root-mismatch");
+        if (!entry.tenantId) return no("no-tenantId");
+        return { tenantId: entry.tenantId, reason: null };
+    } catch {
+        return no("unreadable");
+    }
+}
+
+/**
+ * Attempt to recover the live root for a dead (non-existent) header root.
+ *
+ * @param {string} deadRoot   the X-Workspace-Root value that does NOT exist on disk
+ * @param {object} opts
+ * @param {string|null} opts.wsIdHint      optional workspace id from header/body/query
+ * @param {string|null} opts.tenantHint    optional tenant id from the request (fallback
+ *                                         when the dead root is not an NFS-era path)
+ * @param {Array<{id:string,root:string,tenantId?:string|null}>} opts.registry
+ *                                         live workspaces (wsManager.list()); tenantId
+ *                                         is the tenant the clone was hydrated for
+ * @param {string} opts.mountDir           the agent's clone mount (WORKSPACE_MOUNT)
+ * @param {(p:string)=>boolean} [opts.existsSync]   injectable for tests
+ * @param {(p:string)=>string[]} [opts.readdirSync] injectable for tests
+ * @param {(msg:string)=>void} [opts.warn]          injectable warn logger
+ * @returns {string|null} the live root, or null
+ */
+export function recoverLiveRoot(deadRoot, opts = {}) {
+    try {
+        const existsSync = opts.existsSync || fs.existsSync;
+        const readdirSync = opts.readdirSync || fs.readdirSync;
+        const warn = typeof opts.warn === "function" ? opts.warn : (m) => console.warn(m);
+        const registry = Array.isArray(opts.registry) ? opts.registry : [];
+
+        const base = path.basename(String(deadRoot || "").trim());
+        if (!base || base === "/" || base === ".") return null;
+
+        // TENANT GATE: tenant the dead root belongs to. NFS-era path segment
+        // is authoritative; a caller-supplied hint is the fallback.
+        const deadTenant = tenantOfNfsRoot(deadRoot) || opts.tenantHint || null;
+
+        // 1. Registry by workspace id (strongest signal when the caller sent one).
+        //    Denied only when BOTH tenants are known and differ - that means the
+        //    id was reused across tenants, which must never cross-recover.
+        if (opts.wsIdHint) {
+            const byId = registry.find((w) => w && w.id === opts.wsIdHint);
+            if (byId && byId.root && existsSync(byId.root)) {
+                const candTenant = byId.tenantId || null;
+                if (deadTenant && candTenant && deadTenant !== candTenant) {
+                    warn(`[ROOT-RECOVERY] TENANT GATE: id match denied - dead tenant '${deadTenant}' != registered tenant '${candTenant}' (ws '${opts.wsIdHint}', base '${base}')`);
+                    return null;
+                }
+                return byId.root;
+            }
+        }
+
+        // Basename/scan recovery is only allowed when the dead root's tenant
+        // is KNOWN - otherwise fail closed into workspace_root_not_hydrated.
+        if (!deadTenant) return null;
+
+        // 2. Registry by conservative basename match - candidate must be
+        //    registered for the SAME tenant.
+        for (const w of registry) {
+            if (!w || !w.root) continue;
+            const b = path.basename(w.root);
+            if (b !== base && !b.endsWith("_" + base)) continue;
+            if (!tenantGateAllows(deadTenant, w.tenantId || null)) {
+                warn(`[ROOT-RECOVERY] TENANT GATE: basename match denied - dead tenant '${deadTenant}' vs registered tenant '${w.tenantId || "unknown"}' (base '${base}')`);
+                continue;
+            }
+            if (existsSync(w.root)) return w.root;
+        }
+
+        // 3. Disk scan under the clone mount. Tenant knowledge for a scanned
+        //    dir comes from the registry (root -> tenantId); a dir this
+        //    instance never registered has an unknown tenant and is DENIED
+        //    (fail-closed - the caller's structured fail-fast tells it to
+        //    re-prepare, which re-registers with the tenant).
+        const mountDir = opts.mountDir;
+        if (mountDir && existsSync(mountDir)) {
+            const tenantByRoot = new Map();
+            for (const w of registry) {
+                if (w && w.root && w.tenantId) tenantByRoot.set(path.resolve(w.root), w.tenantId);
+            }
+            const entries = readdirSync(mountDir);
+            // Every basename candidate is considered (two owners may share a
+            // repo name); the first one the tenant gate allows wins. When none
+            // is allowed the FIRST denial is logged (same line as before).
+            let firstDenial = null;
+            for (const hit of entries.filter((e) => e === base || e.endsWith("_" + base))) {
+                const p = path.join(mountDir, hit);
+                let candTenant = tenantByRoot.get(path.resolve(p)) || null;
+                let why = null;
+                if (!candTenant) {
+                    const sc = sidecarTenantOf(p, mountDir);
+                    candTenant = sc.tenantId;
+                    why = sc.reason;
+                }
+                if (!tenantGateAllows(deadTenant, candTenant)) {
+                    if (!firstDenial) {
+                        firstDenial = `[ROOT-RECOVERY] TENANT GATE: disk-scan match denied - dead tenant '${deadTenant}' vs candidate tenant '${candTenant || "unknown"}' (base '${base}')`
+                            + (why ? ` [sidecar: ${why}]` : "");
+                    }
+                    continue;
+                }
+                if (existsSync(p)) return p;
+            }
+            if (firstDenial) warn(firstDenial);
+        }
+    } catch (_) {
+        // Recovery is best-effort by design - never break the request path.
+    }
+    return null;
+}
+
+/**
+ * Resolve the EFFECTIVE root for a header-supplied root:
+ *  - header root exists on disk -> header root (current behavior, untouched)
+ *  - header root dead + recovery hit -> live root
+ *  - otherwise -> header root unchanged (caller fails exactly as before)
+ * Returns { root, recovered } so the caller can log the correction.
+ */
+export function resolveEffectiveHeaderRoot(headerRoot, opts = {}) {
+    const trimmed = String(headerRoot || "").trim();
+    if (!trimmed) return { root: null, recovered: false };
+    const existsSync = (opts && opts.existsSync) || fs.existsSync;
+    try {
+        if (existsSync(trimmed)) return { root: trimmed, recovered: false };
+    } catch (_) {
+        return { root: trimmed, recovered: false };
+    }
+    const live = recoverLiveRoot(trimmed, opts);
+    if (live) return { root: live, recovered: true };
+    return { root: trimmed, recovered: false };
+}

package/src/utils/safe-exec-args.js

@@ -0,0 +1,58 @@
+/**
+ * safe-exec-args.js - argv builders for the few agent routes that used to
+ * concatenate request text into shell strings (security review 2026-10-11, H4).
+ * Every function returns an argument ARRAY meant for execFile/spawn without a
+ * shell, so request input can never be interpreted as shell syntax.
+ */
+
+const EXCLUDED_DIRS = [
+    "node_modules", ".git", "target", "build", "dist", ".idea", "__pycache__", ".next",
+    "vendor", "bin", "obj", ".gradle", ".mvn", ".venv", "coverage",
+];
+
+/** grep argv for POST /workspace/search. `pattern` and `fileFilter` stay data. */
+export function buildGrepArgs({ pattern, fileFilter, root }) {
+    if (typeof pattern !== "string" || !pattern) throw new Error("pattern is required");
+    if (typeof root !== "string" || !root) throw new Error("root is required");
+    const args = ["-rn"];
+    if (typeof fileFilter === "string" && fileFilter.trim()) args.push(`--include=${fileFilter}`);
+    for (const d of EXCLUDED_DIRS) args.push(`--exclude-dir=${d}`);
+    args.push("-e", pattern, "--", root);
+    return args;
+}
+
+/** tar argv for POST /workspace/build-push. */
+export function buildTarArgs({ tarPath, wsPath }) {
+    return ["-czf", tarPath, "--exclude=.git", "--exclude=node_modules", "--exclude=target",
+        "--exclude=*.class", "--exclude=.gradle", "-C", wsPath, "."];
+}
+
+const AUTH_ARG = /^[A-Za-z0-9][A-Za-z0-9._:=\/@-]{0,127}$/;
+const AUTH_COMMANDS = [
+    ["gcloud", "auth", "login"],
+    ["gcloud", "auth", "application-default", "login"],
+    ["az", "login"],
+    ["gh", "auth", "login"],
+    ["glab", "auth", "login"],
+    ["aws", "sso", "login"],
+];
+
+/**
+ * POST /setup/run-auth-command: only interactive login commands are accepted,
+ * optionally followed by flag-like tokens made of safe characters. Returns
+ * { ok: true, argv } or { ok: false, reason }.
+ */
+export function parseAuthCommand(command) {
+    if (typeof command !== "string" || !command.trim() || command.length > 300) {
+        return { ok: false, reason: "command is required" };
+    }
+    const tokens = command.trim().split(/ +/);
+    const match = AUTH_COMMANDS.find((c) => c.every((t, i) => tokens[i] === t));
+    if (!match) return { ok: false, reason: "only interactive login commands are allowed (gcloud/az/gh/glab/aws)" };
+    const rest = tokens.slice(match.length);
+    for (const t of rest) {
+        const bare = t.startsWith("--") ? t.slice(2) : t;
+        if (!AUTH_ARG.test(bare)) return { ok: false, reason: `unsafe argument: ${t.slice(0, 40)}` };
+    }
+    return { ok: true, argv: tokens };
+}