deepdebug-local-agent 1.11.0 → 1.12.0

package/.github/workflows/build-byoc-image.yml

@@ -10,11 +10,12 @@
 # (ideally `:<semver>@sha256:<digest>`); this workflow never moves a floating
 # tag (no :latest, no :v3) and refuses to overwrite an existing :<semver>.
 #
-# Triggers:
-#   - push of a v* tag / published GitHub release (tag must be on main).
-#     NOTE: tags pushed by npm-publish.yml's auto-bump use GITHUB_TOKEN and so do
-#     NOT trigger other workflows; run this manually (workflow_dispatch) for those.
-#   - workflow_dispatch from main (version defaults to package.json).
+# Trigger: workflow_dispatch from main only (version defaults to package.json).
+#   The CI identity (deploy-byoc-image@visionhammer, vh-infra live/nonprod/_project) trusts
+#   this repository at refs/heads/main only. v* tag pushes and release events carry a
+#   refs/tags/* ref and would be refused by Workload Identity Federation, so they are no
+#   longer triggers (tags pushed by npm-publish.yml's auto-bump never triggered this
+#   workflow anyway: they use GITHUB_TOKEN).
 #
 # Supply chain (ADR-0017 D12), OFF by default: the `supply-chain` job signs the
 # pushed image with cosign (keyless, GitHub OIDC), attaches an SPDX SBOM (syft)
@@ -25,10 +26,6 @@
 name: Build BYOC Agent Image
 
 on:
-  push:
-    tags: ['v*']
-  release:
-    types: [published]
   workflow_dispatch:
     inputs:
       version:
@@ -52,7 +49,8 @@ permissions:
 env:
   GCP_PROJECT: visionhammer
   WIF_PROVIDER: projects/1009366917257/locations/global/workloadIdentityPools/github-pool/providers/github-provider
-  DEPLOYER_SA: github-deployer@visionhammer.iam.gserviceaccount.com
+  # Per-service identity (module cicd-identity): writer on visionhammer-docker-public-eu only.
+  DEPLOYER_SA: deploy-byoc-image@visionhammer.iam.gserviceaccount.com
   AR_HOST: europe-west1-docker.pkg.dev
   AR_IMAGE: europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full
 
@@ -200,7 +198,7 @@ jobs:
 
   # Cosign keyless signature + SBOM + provenance for the image pushed above.
   # Flag: input `supply_chain` (dispatch) or repo variable BYOC_SUPPLY_CHAIN=='true'.
-  # Needs github-deployer to write signatures next to the image (same repository,
+  # Needs deploy-byoc-image to write signatures next to the image (same repository,
   # roles/artifactregistry.writer, already required to push).
   supply-chain:
     needs: build

package/cloudbuild-full.yaml

@@ -5,12 +5,13 @@
 #
 # Usage (from a clean checkout of main; both substitutions are required):
 #   gcloud builds submit --project visionhammer --config cloudbuild-full.yaml \
+#     --region=europe-west1 --gcs-source-staging-dir=gs://visionhammer-codescan-src-eu/cloudbuild-staging \
 #     --substitutions=_VERSION=1.0.31,_GIT_SHA=$(git rev-parse HEAD) .
 #
 # Pushes :<_VERSION> and :<_GIT_SHA> — never a floating tag. Pin the gateway to
 # the resulting digest (deepdebug.byoc.agent-image in vh-api-gateway).
 substitutions:
-  _IMAGE: 'us-central1-docker.pkg.dev/visionhammer/visionhammer-docker-public/local-agent-full'
+  _IMAGE: 'europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full'
   _VERSION: ''
   _GIT_SHA: ''
 

package/docs/byoc-agent-image.md

@@ -14,8 +14,8 @@ built separately per tenant and does not use this image.
 ## Publishing a version
 
 1. Actions → **Build BYOC Agent Image** → *Run workflow* on `main` (version
-   defaults to `package.json`; or push a `v*` tag / publish a release on a
-   commit that is on `main`).
+   defaults to `package.json`). Tag pushes and releases no longer trigger it
+   (the CI identity only trusts `refs/heads/main`).
 2. The workflow builds `Dockerfile.full`, smoke-tests it (`/health` public,
    API returns 401 without `X-Agent-Token` when `LOCAL_AGENT_TOKEN` is set),
    then pushes `:<semver>` and `:<git-sha>`. It refuses to overwrite an
@@ -26,8 +26,8 @@ built separately per tenant and does not use this image.
    (`...local-agent-full:<semver>@sha256:<digest>`).
 
 4. Optional supply chain (flag, off by default): tick `supply_chain` on the
-   dispatch (or set the repository variable `BYOC_SUPPLY_CHAIN=true` for tag and
-   release runs). The `supply-chain` job signs `:<semver>@sha256:<digest>` with
+   dispatch (or set the repository variable `BYOC_SUPPLY_CHAIN=true` to sign
+   every run). The `supply-chain` job signs `:<semver>@sha256:<digest>` with
    cosign keyless (GitHub OIDC), attaches an SPDX SBOM (syft) and a SLSA v1
    provenance attestation, and verifies all three. Consumers verify with:
 
@@ -63,8 +63,9 @@ container groups created before the TLS/token spec are recreated on re-provision
 
 ## One-time operator setup
 
-- `github-deployer@visionhammer.iam.gserviceaccount.com` needs
-  `roles/artifactregistry.writer` on the `visionhammer-docker-public-eu` repository (europe-west1; today granted at project level)
-  (and `artifactregistry.reader` for the overwrite guard).
+- `deploy-byoc-image@visionhammer.iam.gserviceaccount.com` (vh-infra `live/nonprod/_project`, module `cicd-identity`) has
+  `roles/artifactregistry.writer` on the `visionhammer-docker-public-eu` repository (europe-west1) and nothing else; writer
+  includes the read needed by the overwrite guard. It trusts this repository at `refs/heads/main` only, so the build is a
+  `workflow_dispatch` from main (tag and release triggers were removed for that reason).
 - The repository must stay public-read (`allUsers` → `artifactregistry.reader`) so
   customer projects / ACI pull without credentials.

package/docs/la-jobs-and-llm.md

@@ -60,3 +60,10 @@ Reference runner `LOCAL_AGENT_JOBS_RUNNER=smoke`: reads the first `inputs[].ref`
 ## Git credentials
 The control plane never sends a Git token: `job.assign` is a closed schema with no field for one (a test sends one and gets `schema_violation`). A runner that opens a PR uses what the machine already has: the
 user's git credential helper, ssh-agent, or variables of the agent's own process environment. The `repoRef` only names provider/org/repo/branch.
+
+## Workspace materialization (LA-2, flag `LOCAL_AGENT_JOBS_AUTO_WORKSPACE`, default OFF)
+A `job.assign` names a workspace by id plus `repoRef`. When this agent does not serve that id, it can clone it itself into `LOCAL_AGENT_WORKSPACE_CACHE` (default `~/.deepdebug/workspaces`),
+with the customer's own credentials (helper / ssh-agent / `GH_TOKEN` of the process, or `LOCAL_AGENT_GIT_TOKEN_FILE` read by a GIT_ASKPASS script). Only for repos in the local allowlist
+`LOCAL_AGENT_ALLOWED_REPOS` (+ optional `LOCAL_AGENT_ALLOWED_REPOS_FILE`; `host/org/repo` or `host/org/*`); empty = nothing is materialized. The allowlist is never taken from the control plane.
+The clone runs inside the job (not in the 5 s ack); failure = job `failed`/`infra`, no git text. One clone at a time, one per workspace id, tenant = the session's. No new HTTP surface.
+Limits: `LOCAL_AGENT_WORKSPACE_CLONE_TIMEOUT_MS`, `LOCAL_AGENT_WORKSPACE_GIT_TIMEOUT_MS`, `LOCAL_AGENT_WORKSPACE_MAX_BYTES`, `LOCAL_AGENT_WORKSPACE_CLONE_DEPTH`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

package/src/la-protocol-v2/jobs/git-exec.js

@@ -0,0 +1,71 @@
+/**
+ * git-exec.js - the ONE way the workspace materializer runs git (LA-2). `execFile` with an argument array (no shell), an explicit cwd, a timeout, an abort
+ * signal, a bounded output buffer and a minimal environment. A credential never travels in an argument, in the URL or in `.git/config`: it comes from what
+ * this machine already has (the user's credential helper, ssh-agent, GH_TOKEN of this process) or, optionally, from a local token FILE read by a GIT_ASKPASS
+ * script git itself runs (the agent never holds the token in a variable).
+ *
+ * Nothing of git's output leaves this module except `classifyGitFailure()`: a CODE (auth, not_found, branch_missing, timeout, aborted, failed). The raw stderr
+ * can name a URL or a user and is never logged, audited or thrown.
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const KEEP_ENV = Object.freeze(["PATH", "HOME", "USERPROFILE", "LANG", "TMPDIR", "TEMP", "TMP", "SYSTEMROOT", "SSH_AUTH_SOCK", "GIT_SSH_COMMAND", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM",
+    "XDG_CONFIG_HOME", "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "https_proxy", "http_proxy", "no_proxy", "GH_TOKEN", "GITHUB_TOKEN", "GITLAB_TOKEN", "GH_CONFIG_DIR", "GH_HOST"]);
+
+/** Minimal env for git: the names above from this process (what a credential helper needs), never prompts, never the agent's own secrets. */
+export function gitEnv(env = process.env, { askpass = null, tokenFile = null } = {}) {
+    const out = {};
+    for (const k of KEEP_ENV) if (env[k] !== undefined) out[k] = env[k];
+    out.GIT_TERMINAL_PROMPT = "0";
+    out.GCM_INTERACTIVE = "never";
+    out.LC_ALL = "C";
+    if (askpass && tokenFile) { out.GIT_ASKPASS = askpass; out.LA_GIT_TOKEN_FILE = tokenFile; out.SSH_ASKPASS = askpass; }
+    return out;
+}
+
+/** A 0700 shell script that answers git's askpass questions from a token file: the username is a constant, the password is the file's content. POSIX only. */
+export function ensureAskpassScript(dir) {
+    const file = path.join(dir, ".vh-git-askpass.sh");
+    const body = "#!/bin/sh\ncase \"$1\" in\n  Username*|username*) printf '%s\\n' 'x-access-token' ;;\n  *) cat -- \"$LA_GIT_TOKEN_FILE\" ;;\nesac\n";
+    let current = null;
+    try { current = fs.readFileSync(file, "utf8"); } catch { current = null; }
+    if (current !== body) { const tmp = `${file}.${process.pid}.tmp`; fs.writeFileSync(tmp, body, { mode: 0o700 }); fs.renameSync(tmp, file); }
+    fs.chmodSync(file, 0o700);
+    return file;
+}
+
+/** The config every git call gets: no exotic transports (a URL is built by us, https only). */
+export const SAFE_GIT_CONFIG = Object.freeze(["-c", "protocol.ext.allow=never", "-c", "protocol.file.allow=never", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null"]);
+
+/**
+ * @param {string[]} args  after the safe config
+ * @param {{cwd?:string, env:object, timeoutMs:number, signal?:AbortSignal, extraConfig?:string[]}} o
+ * @returns {Promise<{ok:true, stdout:string} | {ok:false, code:string}>}  never throws, never returns stderr
+ */
+export function runGit(args, { cwd, env, timeoutMs, signal, extraConfig = [] }) {
+    return new Promise((resolve) => {
+        if (signal && signal.aborted) { resolve({ ok: false, code: "aborted" }); return; }
+        let child;
+        try {
+            child = execFile("git", [...SAFE_GIT_CONFIG, ...extraConfig, ...args], { cwd, env, timeout: timeoutMs, signal, maxBuffer: 1024 * 1024, windowsHide: true, encoding: "utf8" }, (err, stdout, stderr) => {
+                if (!err) { resolve({ ok: true, stdout: String(stdout || "") }); return; }
+                resolve({ ok: false, code: classifyGitFailure(err, String(stderr || ""), signal) });
+            });
+        } catch { resolve({ ok: false, code: "failed" }); return; }
+        void child;
+    });
+}
+
+/** A failure CODE from the exit state and stderr. stderr is read here and nowhere else. */
+export function classifyGitFailure(err, stderr, signal) {
+    if (signal && signal.aborted) return "aborted";
+    if (err && (err.killed || err.code === "ETIMEDOUT" || err.signal === "SIGTERM")) return "timeout";
+    if (err && err.code === "ENOENT") return "git_missing";
+    const s = stderr.toLowerCase();
+    if (/authentication failed|could not read username|could not read password|terminal prompts disabled|permission denied \(publickey|invalid username or password|http 40[13]|returned error: 40[13]|access denied|bad credentials/.test(s)) return "auth";
+    if (/remote branch .* not found|couldn't find remote ref|could not find remote branch/.test(s)) return "branch_missing";
+    if (/repository not found|not found|does not exist|http 404|returned error: 404/.test(s)) return "not_found";
+    return "failed";
+}

package/src/la-protocol-v2/jobs/install.js

@@ -8,6 +8,7 @@
 import { dlpConfigFromEnv } from "../../dlp/index.js";
 import { createJobManager } from "./manager.js";
 import { createSmokeRunner } from "./smoke-runner.js";
+import { resolveMaterializeConfig, createWorkspaceMaterializer } from "./workspace-materializer.js";
 
 export const JOBS_CAPABILITIES = Object.freeze(["job.assign"]);
 
@@ -32,7 +33,10 @@ export function installJobs({ link, tenantId, wsManager, getWorkspaceRoot, confi
     const resolveWorkspace = makeWorkspaceResolver({ wsManager, getWorkspaceRoot, tenantId: tenant });
     const theRunner = runner || (config.runner === "smoke" ? createSmokeRunner({ maxFileBytes: config.smokeMaxFileBytes }) : null);
     if (!theRunner) throw new Error("job.assign needs a runner");
-    const manager = createJobManager({ session: link.session, tenantId: tenant, resolveWorkspace, config, env, llm: link.llm || null,
+    // LA-2: LOCAL_AGENT_JOBS_AUTO_WORKSPACE (default off) lets this agent clone an allowlisted workspace itself, with the customer's own credentials
+    const mat = resolveMaterializeConfig(env, (m) => (log.warn || log.log).call(log, m));
+    const materializer = mat.enabled && wsManager ? createWorkspaceMaterializer({ config: mat, tenantId: tenant, wsManager, audit: null, env, log }) : null;
+    const manager = createJobManager({ session: link.session, tenantId: tenant, resolveWorkspace, materializer, config, env, llm: link.llm || null,
         readFile: link.content ? link.content.readAllowedFile : null, runner: theRunner, onResult, log, now, ...(memoryUsage ? { memoryUsage } : {}), ...(sleep ? { sleep } : {}) });
     link.session.setHandler("job.assign", (ctx) => manager.handleAssign(ctx));
     link.session.setHandler("job.cancel", (ctx) => manager.handleCancel(ctx));

package/src/la-protocol-v2/jobs/manager.js

@@ -58,12 +58,13 @@ export function validateRunner(r) {
         && (r.supportsOptions === undefined || typeof r.supportsOptions === "boolean");
 }
 
-export function createJobManager({ session, tenantId, resolveWorkspace, config, env = process.env, llm = null, readFile = null, runner = null, onResult = null, audit = null,
+export function createJobManager({ session, tenantId, resolveWorkspace, materializer = null, config, env = process.env, llm = null, readFile = null, runner = null, onResult = null, audit = null,
     log = console, now = Date.now, memoryUsage = () => process.memoryUsage().rss, events = null, sleep }) {
     const tenant = String(tenantId).toLowerCase();
     const auditor = audit || createAudit({ file: config.auditFile, now });
     const ev = events || createJobEvents({ session, config, audit: auditor, now, ...(sleep ? { sleep } : {}) });
     const warn = (m) => (log.warn || log.log).call(log, m);
+    if (materializer && typeof materializer.bindAudit === "function") materializer.bindAudit(auditor);
     const stats = { received: 0, accepted: 0, duplicate: 0, queued: 0, rejected: {}, finished: { succeeded: 0, failed: 0, cancelled: 0 }, cancels: 0, cancelInvalid: 0, cancelledBeforeAssign: 0,
         optionsInvalid: 0, optionsUnsupported: 0, abandoned: 0 };
     const active = new Map();    // jobId -> record (queued + running)
@@ -192,7 +193,10 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
             },
             budget: () => ({ tokensLeft: Math.max(0, rec.budget.tokens - tokensUsed(rec)), msLeft: Math.max(0, rec.startedAt + secondsMs - now()) }),
         });
-        Promise.resolve().then(() => theRunner.start(rec.job, ctx)).then(
+        // LA-2: a workspace this agent does not serve yet is cloned HERE (inside the job, never inside the 5 s ack), with the customer's own credentials, only for an
+        // allowlisted repo; a failure is job `failed`/`infra` (a code, never git's text). The runner then finds the workspace in the manager like any other.
+        const prepared = rec.materialize ? Promise.resolve().then(() => materializer.ensure(rec.workspaceId, rec.job.repoRef, rec.ac.signal)) : Promise.resolve();
+        prepared.then(() => { if (rec.abortReason || rec.finished) return { outcome: "cancelled" }; return theRunner.start(rec.job, ctx); }).then(
             (outcome) => finish(rec, outcome && typeof outcome === "object" ? outcome : null, null),
             (err) => finish(rec, null, err || new Error("runner")),
         ).catch(() => {});
@@ -218,7 +222,12 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
             if (active.has(p.jobId) || recent.has(p.jobId)) { stats.duplicate++; note("job_duplicate", base); return { accept: true }; }
             if (cancelledEarly.has(p.jobId)) { stats.cancelledBeforeAssign++; note("job_assign_after_cancel", base); return { accept: true }; }   // the CP already gave this job up: never started
             const ws = typeof ctx.workspaceId === "string" && ctx.workspaceId ? resolveWorkspace(ctx.workspaceId) : null;
-            if (!ws || !ws.root) return reject(base, "unauthorized");
+            let materialize = false;
+            if (!ws || !ws.root) {
+                // LA-2 (flag LOCAL_AGENT_JOBS_AUTO_WORKSPACE, default off): not served here, but it may be materialized: allowlisted repo, usable credential, same tenant
+                if (!materializer || !materializer.admit(ctx.workspaceId, p.repoRef)) return reject(base, "unauthorized");
+                materialize = true;
+            }
             // contract 2.1 `options`: only a runner that declared it handles them; a malformed object (the session's schema check should have caught it) runs nothing
             const opts = normalizeJobOptions(p.options, config);
             if (!opts.ok) { stats.optionsInvalid++; return reject(base, "schema_violation"); }
@@ -233,7 +242,7 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
 
             const budget = { tokens: Math.min(p.budget.tokens, config.maxTokens), seconds: Math.min(p.budget.seconds, config.maxSeconds) };
             const rec = {
-                jobId: p.jobId, short: short(p.jobId), kind: p.kind, workspaceId: ctx.workspaceId, state: "queued", phase: "init", iteration: 0, filesRead: 0, filesChanged: 0,
+                jobId: p.jobId, short: short(p.jobId), kind: p.kind, workspaceId: ctx.workspaceId, state: "queued", materialize, phase: "init", iteration: 0, filesRead: 0, filesChanged: 0,
                 tokensIn: 0, tokensOut: 0, costUsd: null, waiting: false, acceptedAt: now(), startedAt: 0, ac: new AbortController(), abortReason: null, finished: false, ev: null, holdsSlot: false,
                 reservedBytes: need, deadlineTimer: null, graceTimer: null, budget,
                 job: Object.freeze({ jobId: p.jobId, kind: p.kind, workspaceId: ctx.workspaceId, incidentRef: p.incidentRef, repoRef: p.repoRef, policy: p.policy, budget: Object.freeze({ ...budget }), llm: p.llm, inputs: p.inputs || [], options: opts.options }),

package/src/la-protocol-v2/jobs/workspace-materializer.js

@@ -0,0 +1,244 @@
+/**
+ * workspace-materializer.js - LA-2 (ADR-0014 Design A, chat on the Local Agent). A `job.assign` names a workspace by id and a `repoRef`
+ * {provider, org, repo, branch}. When this agent does not serve that workspace yet, it can CLONE IT ITSELF, into its own cache, with the customer's OWN
+ * credentials (credential helper / ssh-agent / GH_TOKEN of this process, or a local token file read by GIT_ASKPASS). The platform never sends a token and
+ * never sees one; it only names the repository.
+ *
+ *   LOCAL_AGENT_JOBS_AUTO_WORKSPACE=true   (default OFF) turns it on. Needs LOCAL_AGENT_JOBS (the manager that calls it).
+ *   LOCAL_AGENT_ALLOWED_REPOS              `host/org/repo` or `host/org/*`, separated by comma/space/newline; LOCAL_AGENT_ALLOWED_REPOS_FILE adds a file
+ *                                          (one entry per line, `#` comments). ONLY the customer decides this list: it is never taken from the control plane.
+ *                                          Empty = nothing is materialized (fail closed).
+ *   LOCAL_AGENT_WORKSPACE_CACHE            where clones live (default ~/.deepdebug/workspaces)
+ *   LOCAL_AGENT_GIT_TOKEN_FILE             optional: a file with a token that a GIT_ASKPASS script cats (POSIX). Absent = the machine's own helper/ssh.
+ *   LOCAL_AGENT_WORKSPACE_CLONE_TIMEOUT_MS (default 300000), LOCAL_AGENT_WORKSPACE_MAX_BYTES (default 2 GiB, a clone above it is removed)
+ *
+ * Rules: one clone at a time on this agent and one clone per workspace id (a second job for the same id awaits the first); URL built here from the closed
+ * provider list and the validated org/repo (never from outside text, never with credentials); `execFile` with an array; the tenant is the SESSION's
+ * (wsManager.open(.., {tenantId})); a directory of another tenant, a symlink in the cache or a foreign directory is refused; nothing of git's stderr, of a path
+ * or of the allowlist is thrown, logged or audited (codes and short hashes only). An existing clone is fetched and fast-forwarded only when clean: local work
+ * of a previous job is never reset.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { readWorkspaceSidecar, isSafeToRemove } from "../../utils/open-gate.js";
+import { short } from "../content-handlers/audit.js";
+import { gitEnv, ensureAskpassScript, runGit } from "./git-exec.js";
+
+export const MATERIALIZE_FLAG = "LOCAL_AGENT_JOBS_AUTO_WORKSPACE";
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const MIB = 1024 * 1024;
+const WS_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const SEG = /^[A-Za-z0-9_.-]{1,100}$/;
+const BRANCH = /^[A-Za-z0-9_./-]{1,255}$/;
+const HOSTS = Object.freeze({ github: "github.com", gitlab: "gitlab.com", bitbucket: "bitbucket.org" });   // azure/other: no known host, not materializable
+const ENTRY = /^([a-z0-9.-]+)\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+|\*)$/;
+
+function int(raw, def, min, max) { const n = Number.parseInt(String(raw ?? ""), 10); return Number.isFinite(n) && n >= min && n <= max ? n : def; }
+
+/** An error with a code and the job error code `infra`; the message is generic (the manager never reads it anyway). */
+export class MaterializeError extends Error {
+    constructor(code) { super(`workspace not available (${code})`); this.name = "MaterializeError"; this.code = code; this.jobErrorCode = "infra"; }
+}
+
+/** Parses the allowlist text. Returns { exact:Set<"host/org/repo">, orgs:Set<"host/org">, invalid:number } (lower case). */
+export function parseAllowlist(text) {
+    const exact = new Set();
+    const orgs = new Set();
+    let invalid = 0;
+    for (const raw of String(text || "").split(/[\s,]+/)) {
+        const e = raw.trim().toLowerCase();
+        if (!e || e.startsWith("#")) continue;
+        const m = ENTRY.exec(e);
+        if (!m || m[2] === "." || m[2] === ".." || m[3] === "." || m[3] === "..") { invalid++; continue; }
+        if (m[3] === "*") orgs.add(`${m[1]}/${m[2]}`); else exact.add(`${m[1]}/${m[2]}/${m[3]}`);
+    }
+    return { exact, orgs, invalid };
+}
+
+function readAllowlistText(env) {
+    let text = String(env.LOCAL_AGENT_ALLOWED_REPOS ?? "");
+    const file = String(env.LOCAL_AGENT_ALLOWED_REPOS_FILE ?? "").trim();
+    if (file) {
+        try { text += "\n" + fs.readFileSync(file, "utf8").split(/\r?\n/).filter((l) => !l.trim().startsWith("#")).join("\n"); } catch { /* unreadable file = no entries from it (fail closed) */ }
+    }
+    return text;
+}
+
+/** { enabled:false } unless LOCAL_AGENT_JOBS_AUTO_WORKSPACE is true. */
+export function resolveMaterializeConfig(env = process.env, warn = console.warn) {
+    if (!TRUE.has(String(env[MATERIALIZE_FLAG] ?? "").trim().toLowerCase())) return { enabled: false };
+    const allow = parseAllowlist(readAllowlistText(env));
+    if (allow.invalid) warn(`[la-workspace] ${allow.invalid} invalid LOCAL_AGENT_ALLOWED_REPOS entr${allow.invalid === 1 ? "y" : "ies"} ignored`);
+    if (!allow.exact.size && !allow.orgs.size) warn("[la-workspace] LOCAL_AGENT_ALLOWED_REPOS is empty: no workspace will be materialized");
+    const tokenFile = String(env.LOCAL_AGENT_GIT_TOKEN_FILE ?? "").trim() || null;
+    return {
+        enabled: true,
+        allow,
+        cacheDir: path.resolve(String(env.LOCAL_AGENT_WORKSPACE_CACHE ?? "").trim() || path.join(os.homedir(), ".deepdebug", "workspaces")),
+        tokenFile: tokenFile ? path.resolve(tokenFile) : null,
+        cloneTimeoutMs: int(env.LOCAL_AGENT_WORKSPACE_CLONE_TIMEOUT_MS, 300_000, 1_000, 3_600_000),
+        gitTimeoutMs: int(env.LOCAL_AGENT_WORKSPACE_GIT_TIMEOUT_MS, 60_000, 1_000, 600_000),
+        maxBytes: int(env.LOCAL_AGENT_WORKSPACE_MAX_BYTES, 2048 * MIB, MIB, 64 * 1024 * MIB),
+        depth: int(env.LOCAL_AGENT_WORKSPACE_CLONE_DEPTH, 50, 1, 10_000),
+    };
+}
+
+/** Validates a repoRef and builds { host, org, repo, branch, key, url } or null. The url has NO credentials and is only https. */
+export function repoTarget(repoRef) {
+    if (!repoRef || typeof repoRef !== "object") return null;
+    const host = HOSTS[repoRef.provider];
+    const { org, repo, branch } = repoRef;
+    if (!host || typeof org !== "string" || typeof repo !== "string" || typeof branch !== "string") return null;
+    if (!SEG.test(org) || !SEG.test(repo) || org === "." || org === ".." || repo === "." || repo === "..") return null;
+    if (!BRANCH.test(branch) || branch.startsWith("-") || branch.startsWith("/") || branch.endsWith("/") || branch.endsWith(".lock") || branch.includes("..") || branch.includes("//") || branch.includes("/.")) return null;
+    return { host, org, repo, branch, key: `${host}/${org.toLowerCase()}/${repo.toLowerCase()}`, orgKey: `${host}/${org.toLowerCase()}`, url: `https://${host}/${org}/${repo}.git` };
+}
+
+/** Bounded, symlink-safe size of a directory (lstat, no following). Returns bytes counted up to `limit`+1. */
+function dirBytes(dir, limit) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length) {
+        const d = stack.pop();
+        let ents;
+        try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+        for (const e of ents) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) stack.push(p);
+            else { try { total += fs.lstatSync(p).size; } catch { /* vanished */ } }
+            if (total > limit) return total;
+        }
+    }
+    return total;
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.config         resolveMaterializeConfig() (enabled)
+ * @param {string} o.tenantId       the SESSION's tenant
+ * @param {object} o.wsManager      open(id, dir, {tenantId}), list()
+ * @param {object} [o.audit]        { record(entry) } - codes and short hashes only
+ * @param {object} [o.env]
+ * @param {object} [o.seams]        TESTS ONLY: { remoteUrl(target) => string, gitConfig: string[] (e.g. protocol.file.allow=always), runGit }
+ */
+export function createWorkspaceMaterializer({ config, tenantId, wsManager, audit: auditIn = null, env = process.env, log = console, seams = {} }) {
+    let audit = auditIn;
+    const tenant = String(tenantId).toLowerCase();
+    const git = seams.runGit || runGit;
+    const stats = { admitted: 0, refused: {}, cloned: 0, reused: 0, failed: {} };
+    const inflight = new Map();   // workspaceId -> Promise<{root}>
+    let chain = Promise.resolve();   // one clone/fetch at a time on this agent
+    const note = (event, extra) => { try { audit?.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
+    const refuse = (why, extra) => { stats.refused[why] = (stats.refused[why] || 0) + 1; note("workspace_refused", { why, ...extra }); return null; };
+
+    const cacheReal = () => { try { fs.mkdirSync(config.cacheDir, { recursive: true, mode: 0o700 }); return fs.realpathSync(config.cacheDir); } catch { return null; } };
+    const allowed = (t) => config.allow.exact.has(t.key) || config.allow.orgs.has(t.orgKey);
+    const tokenUsable = () => { if (!config.tokenFile) return true; try { fs.accessSync(config.tokenFile, fs.constants.R_OK); return fs.statSync(config.tokenFile).isFile(); } catch { return false; } };
+    const listed = (id) => (wsManager?.list?.() || []).find((w) => w && w.id === id);
+
+    /**
+     * Synchronous admission (inside the 5 s ack): may this workspace be materialized for this job? true = the manager accepts the job and calls ensure()
+     * from inside it. false = the job is refused `unauthorized` with an audit CODE. Never touches the network.
+     */
+    function admit(workspaceId, repoRef) {
+        const base = { workspaceShort: short(workspaceId) };
+        if (typeof workspaceId !== "string" || !WS_ID.test(workspaceId) || workspaceId === "default") return !!refuse("bad_workspace_id", base);
+        if (listed(workspaceId)) return !!refuse("already_open_elsewhere", base);   // served (the resolver decided) or another tenant's: never replaced
+        const t = repoTarget(repoRef);
+        if (!t) return !!refuse("bad_repo_ref", base);
+        if (!allowed(t)) return !!refuse("repo_not_allowed", { ...base, repoShort: short(t.key) });
+        if (!tokenUsable()) return !!refuse("credential_unavailable", base);   // a configured token file that cannot be read: a clear refusal now, not a failed clone later
+        const root = cacheReal();
+        if (!root) return !!refuse("cache_unavailable", base);
+        const dir = path.join(root, workspaceId);
+        let st = null;
+        try { st = fs.lstatSync(dir); } catch { st = null; }
+        if (st) {
+            if (st.isSymbolicLink() || !st.isDirectory()) return !!refuse("cache_entry_unsafe", base);
+            const sc = readWorkspaceSidecar(dir);
+            if (!sc || sc.id !== workspaceId) return !!refuse("foreign_directory", base);
+            if (!sc.tenantId || sc.tenantId.toLowerCase() !== tenant) return !!refuse("tenant_mismatch", base);
+        }
+        stats.admitted++;
+        return true;
+    }
+
+    async function doEnsure(workspaceId, repoRef, signal) {
+        const t = repoTarget(repoRef);
+        const ws = short(workspaceId);
+        const fail = (code) => { stats.failed[code] = (stats.failed[code] || 0) + 1; note("workspace_failed", { code, workspaceShort: ws }); throw new MaterializeError(code); };
+        if (!t || !allowed(t) || !WS_ID.test(workspaceId)) fail("repo_not_allowed");   // defence in depth: ensure() re-checks what admit() checked
+        const root = cacheReal();
+        if (!root) fail("cache_unavailable");
+        const dir = path.join(root, workspaceId);
+        if (!isSafeToRemove(root, dir)) fail("cache_entry_unsafe");
+        let askpass = null;
+        if (config.tokenFile) {
+            if (!tokenUsable()) fail("credential_unavailable");
+            try { askpass = ensureAskpassScript(root); } catch { fail("cache_unavailable"); }
+        }
+        const env2 = gitEnv(env, { askpass, tokenFile: config.tokenFile });
+        const extraConfig = seams.gitConfig || [];
+        const remote = seams.remoteUrl ? seams.remoteUrl(t) : t.url;
+        let st = null;
+        try { st = fs.lstatSync(dir); } catch { st = null; }
+        if (st) {
+            if (st.isSymbolicLink() || !st.isDirectory()) fail("cache_entry_unsafe");
+            const sc = readWorkspaceSidecar(dir);
+            if (!sc || sc.id !== workspaceId) fail("foreign_directory");
+            if (!sc.tenantId || sc.tenantId.toLowerCase() !== tenant) fail("tenant_mismatch");
+            // existing clone: fetch the branch; move only a CLEAN tree (the previous job's local work is never reset)
+            const f = await git(["fetch", "--depth", String(config.depth), "--no-tags", "--", "origin", t.branch], { cwd: dir, env: env2, timeoutMs: config.gitTimeoutMs, signal, extraConfig });
+            if (!f.ok) fail(f.code === "failed" ? "fetch_failed" : f.code);
+            const dirty = await git(["status", "--porcelain"], { cwd: dir, env: env2, timeoutMs: config.gitTimeoutMs, signal, extraConfig });
+            if (dirty.ok && dirty.stdout.trim() === "") {
+                const co = await git(["checkout", "--quiet", t.branch, "--"], { cwd: dir, env: env2, timeoutMs: config.gitTimeoutMs, signal, extraConfig });
+                if (co.ok) await git(["merge", "--ff-only", "--quiet", "FETCH_HEAD"], { cwd: dir, env: env2, timeoutMs: config.gitTimeoutMs, signal, extraConfig });
+            } else note("workspace_kept_dirty", { workspaceShort: ws });
+            stats.reused++;
+        } else {
+            const tmp = path.join(root, `.tmp-${workspaceId}-${crypto.randomBytes(4).toString("hex")}`);
+            let ok = false;
+            try {
+                const c = await git(["clone", "--branch", t.branch, "--single-branch", "--depth", String(config.depth), "--no-tags", "--", remote, tmp], { env: env2, cwd: root, timeoutMs: config.cloneTimeoutMs, signal, extraConfig });
+                if (!c.ok) fail(c.code === "failed" ? "clone_failed" : c.code);
+                if (dirBytes(tmp, config.maxBytes) > config.maxBytes) fail("too_large");
+                // the remote of the clone is the credential-free URL we built; nothing else was ever written to its config
+                fs.renameSync(tmp, dir);
+                ok = true;
+            } finally {
+                if (!ok) { try { if (isSafeToRemove(root, tmp)) fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best effort */ } }
+            }
+            stats.cloned++;
+        }
+        try { await wsManager.open(workspaceId, dir, { tenantId: tenant }); } catch {
+            if (!st) { try { if (isSafeToRemove(root, dir)) fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } }   // a fresh clone that could not be registered must not stay as a "foreign" directory
+            fail("open_failed");
+        }
+        note("workspace_ready", { workspaceShort: ws, repoShort: short(t.key), reused: !!st });
+        return { root: dir };
+    }
+
+    return {
+        stats, config,
+        /** The job manager hands its audit in (one trail for jobs and workspaces). */
+        bindAudit(a) { if (!audit) audit = a; },
+        admit,
+        /**
+         * Clone (or refresh) and register the workspace. Called by the job manager from inside the job; resolves { root } or throws MaterializeError (job `failed`, `infra`).
+         * One clone at a time; a second call for the same id shares the first one's promise.
+         */
+        ensure(workspaceId, repoRef, signal) {
+            const running = inflight.get(workspaceId);
+            if (running) return running;
+            const p = chain.then(() => { if (signal && signal.aborted) throw new MaterializeError("aborted"); return doEnsure(workspaceId, repoRef, signal); });
+            chain = p.catch(() => {});
+            inflight.set(workspaceId, p);
+            const clear = () => { if (inflight.get(workspaceId) === p) inflight.delete(workspaceId); };
+            p.then(clear, clear);
+            return p;
+        },
+    };
+}

package/test/la-protocol-v2/workspace-materializer.test.js

@@ -0,0 +1,341 @@
+// LA-2: the Local Agent materializes a workspace itself for a job.assign (flag LOCAL_AGENT_JOBS_AUTO_WORKSPACE, default off). Allowlist (fail closed),
+// customer-side credentials only, tenant gate, cache safety (symlink, foreign dir), no secret anywhere, one clone at a time, job manager integration.
+// Real git is used against a local bare repository (the test seam allows the file transport; production never does).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { createWorkspaceMaterializer, resolveMaterializeConfig, parseAllowlist, repoTarget, MaterializeError } from "../../src/la-protocol-v2/jobs/workspace-materializer.js";
+import { classifyGitFailure, gitEnv, ensureAskpassScript, SAFE_GIT_CONFIG } from "../../src/la-protocol-v2/jobs/git-exec.js";
+import { createJobManager } from "../../src/la-protocol-v2/jobs/manager.js";
+import { resolveJobsConfig } from "../../src/la-protocol-v2/jobs/config.js";
+import { createAudit } from "../../src/la-protocol-v2/content-handlers/audit.js";
+import { WorkspaceManager } from "../../src/workspace-manager.js";
+import { WORKSPACE_SIDECAR } from "../../src/utils/open-gate.js";
+
+const TENANT = "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f";
+const OTHER = "9a9a9a9a-5a4d-4e7b-9c21-0a1b2c3d4e5f";
+const WS = "11111111-2222-4333-8444-555555555555";
+const SECRET = "ghp_PLANTEDsecretTOKEN0123456789abcdef";
+const REF = { provider: "github", org: "acme", repo: "app", branch: "main" };
+const noop = () => {};
+const tmp = (p) => fs.mkdtempSync(path.join(os.tmpdir(), `la-mat-${p}-`));
+const git = (cwd, ...a) => execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", ...a], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+
+/** A bare "remote" with one commit on main (and one on `dev`); returns its path. */
+function makeRemote() {
+    const bare = tmp("remote");
+    const work = tmp("seed");
+    git(bare, "init", "--bare", "-b", "main", ".");
+    git(work, "init", "-b", "main", ".");
+    fs.writeFileSync(path.join(work, "a.txt"), "one\n");
+    git(work, "add", "."); git(work, "commit", "-m", "one");
+    git(work, "remote", "add", "origin", bare);
+    git(work, "push", "origin", "main");
+    return { bare, work, push(text) { fs.writeFileSync(path.join(work, "a.txt"), text); git(work, "commit", "-am", "more"); git(work, "push", "origin", "main"); } };
+}
+
+function setup({ allow = "github.com/acme/app", remote = null, env = {}, runGit = undefined, tenant = TENANT } = {}) {
+    const cache = tmp("cache");
+    const warn = [];
+    const cfg = resolveMaterializeConfig({ LOCAL_AGENT_JOBS_AUTO_WORKSPACE: "true", LOCAL_AGENT_ALLOWED_REPOS: allow, LOCAL_AGENT_WORKSPACE_CACHE: cache, ...env }, (m) => warn.push(m));
+    const wsManager = new WorkspaceManager();
+    const audit = createAudit({});
+    const seams = remote ? { remoteUrl: () => remote.bare, gitConfig: ["-c", "protocol.file.allow=always"] } : {};
+    if (runGit) seams.runGit = runGit;
+    const mat = createWorkspaceMaterializer({ config: cfg, tenantId: tenant, wsManager, audit, env: { PATH: process.env.PATH, HOME: process.env.HOME, ...(env.PROC || {}) }, seams });
+    return { mat, cfg, cache, wsManager, audit, warn };
+}
+
+// ---------------------------------------------------------------- config / parsing
+
+test("config: off by default; on needs the flag; an empty allowlist warns and admits nothing", () => {
+    for (const v of [undefined, "", "false", "0", "nope"]) assert.deepEqual(resolveMaterializeConfig({ LOCAL_AGENT_JOBS_AUTO_WORKSPACE: v, LOCAL_AGENT_ALLOWED_REPOS: "github.com/acme/app" }), { enabled: false });
+    const w = [];
+    const c = resolveMaterializeConfig({ LOCAL_AGENT_JOBS_AUTO_WORKSPACE: "true" }, (m) => w.push(m));
+    assert.equal(c.enabled, true);
+    assert.match(w.join("\n"), /empty/);
+    const { mat } = setup({ allow: "" });
+    assert.equal(mat.admit(WS, REF), false);
+    assert.equal(mat.stats.refused.repo_not_allowed, 1);
+});
+
+test("allowlist parsing: exact and org/*; garbage (scheme, @, .., bare *, host/*) is dropped", () => {
+    const a = parseAllowlist("github.com/Acme/App, github.com/corp/*\nhttps://github.com/x/y git@github.com:x/y.git github.com/../x github.com/o/.. * github.com/* # c");
+    assert.deepEqual([...a.exact], ["github.com/acme/app"]);
+    assert.deepEqual([...a.orgs], ["github.com/corp"]);
+    assert.ok(a.invalid >= 6);
+});
+
+test("repoTarget: closed provider list, strict segments, branch rules, no credentials in the URL", () => {
+    const ok = repoTarget(REF);
+    assert.equal(ok.url, "https://github.com/acme/app.git");
+    assert.ok(!/@/.test(ok.url));
+    for (const bad of [{ ...REF, org: ".." }, { ...REF, repo: "." }, { ...REF, org: "a/b" }, { ...REF, org: "a@b" }, { ...REF, repo: "x y" }, { ...REF, provider: "azure" }, { ...REF, provider: "other" },
+        { ...REF, provider: "evil.com" }, { ...REF, branch: "-x" }, { ...REF, branch: "a..b" }, { ...REF, branch: "a//b" }, { ...REF, branch: "x.lock" }, { ...REF, branch: "/x" }, { ...REF, branch: "a b" }, null, {}]) assert.equal(repoTarget(bad), null, JSON.stringify(bad));
+    assert.equal(repoTarget({ ...REF, provider: "gitlab" }).url, "https://gitlab.com/acme/app.git");
+});
+
+test("git-exec: failure classification by code only; env is minimal and never carries the agent's own secrets", () => {
+    assert.equal(classifyGitFailure({}, "fatal: Authentication failed for 'https://x/'"), "auth");
+    assert.equal(classifyGitFailure({}, "fatal: could not read Username for 'https://github.com': terminal prompts disabled"), "auth");
+    assert.equal(classifyGitFailure({}, "fatal: Remote branch zz not found in upstream origin"), "branch_missing");
+    assert.equal(classifyGitFailure({}, "remote: Repository not found."), "not_found");
+    assert.equal(classifyGitFailure({ killed: true }, ""), "timeout");
+    assert.equal(classifyGitFailure({}, "boom"), "failed");
+    const ac = new AbortController(); ac.abort();
+    assert.equal(classifyGitFailure({}, "", ac.signal), "aborted");
+    const e = gitEnv({ PATH: "/bin", HOME: "/h", LOCAL_AGENT_TOKEN: "x", DEEPDEBUG_API_KEY: "y", LOCAL_AGENT_LLM_KEY: "z", SSH_AUTH_SOCK: "/s" });
+    assert.deepEqual(Object.keys(e).sort(), ["GCM_INTERACTIVE", "GIT_TERMINAL_PROMPT", "HOME", "LC_ALL", "PATH", "SSH_AUTH_SOCK"]);
+    assert.ok(SAFE_GIT_CONFIG.includes("protocol.ext.allow=never") && SAFE_GIT_CONFIG.includes("protocol.file.allow=never"));
+});
+
+// ---------------------------------------------------------------- admission
+
+test("admit: allowlisted repo ok; org/* ok; repo outside the allowlist, bad ids and 'default' are refused with a code", () => {
+    const { mat, audit } = setup({ allow: "github.com/acme/app,github.com/corp/*" });
+    assert.equal(mat.admit(WS, REF), true);
+    assert.equal(mat.admit(WS, { ...REF, org: "corp", repo: "anything" }), true);
+    assert.equal(mat.admit(WS, { ...REF, org: "evil" }), false);
+    assert.equal(mat.admit(WS, { ...REF, repo: "other" }), false);
+    assert.equal(mat.admit(WS, { ...REF, org: "..", repo: ".." }), false);
+    for (const id of ["default", "../x", "a/b", "", ".hidden", "x".repeat(101), null, 5]) assert.equal(mat.admit(id, REF), false, String(id));
+    assert.equal(mat.admit(WS, null), false);
+    assert.ok(mat.stats.refused.repo_not_allowed >= 2);
+    assert.ok(mat.stats.refused.bad_workspace_id >= 7);
+    const trail = JSON.stringify(audit.tail(100));
+    assert.ok(!trail.includes("evil") && !trail.includes(WS), "audit holds short hashes and codes, not names");
+});
+
+test("admit: an id already open (here or for another tenant) is never replaced", async () => {
+    const { mat, wsManager, cache } = setup();
+    const d = path.join(cache, "other"); fs.mkdirSync(d);
+    await wsManager.open(WS, d, { tenantId: OTHER });
+    assert.equal(mat.admit(WS, REF), false);
+    assert.equal(mat.stats.refused.already_open_elsewhere, 1);
+});
+
+test("admit: a cache entry that is a symlink, a directory without registration, or one of ANOTHER tenant is refused", () => {
+    const { mat, cache } = setup();
+    const outside = tmp("outside");
+    fs.symlinkSync(outside, path.join(cache, WS));
+    assert.equal(mat.admit(WS, REF), false);
+    assert.equal(mat.stats.refused.cache_entry_unsafe, 1);
+    const ws2 = "22222222-2222-4333-8444-555555555555";
+    fs.mkdirSync(path.join(cache, ws2));
+    assert.equal(mat.admit(ws2, REF), false);
+    assert.equal(mat.stats.refused.foreign_directory, 1);
+    const ws3 = "33333333-2222-4333-8444-555555555555";
+    const d3 = path.join(fs.realpathSync(cache), ws3); fs.mkdirSync(d3);
+    fs.writeFileSync(path.join(d3, WORKSPACE_SIDECAR), JSON.stringify({ id: ws3, tenantId: OTHER, root: d3, openedAt: "x" }));
+    assert.equal(mat.admit(ws3, REF), false);
+    assert.equal(mat.stats.refused.tenant_mismatch, 1);
+    assert.deepEqual(fs.readdirSync(outside), [], "nothing was written through the symlink");
+});
+
+test("admit: a configured token file that cannot be read is a clear refusal (credential_unavailable); without a token file the machine's own credentials are used", () => {
+    const { mat } = setup({ env: { LOCAL_AGENT_GIT_TOKEN_FILE: "/nonexistent/token" } });
+    assert.equal(mat.admit(WS, REF), false);
+    assert.equal(mat.stats.refused.credential_unavailable, 1);
+    assert.equal(setup().mat.admit(WS, REF), true);
+});
+
+// ---------------------------------------------------------------- real clone against a local bare repository
+
+test("ensure: clones into the cache, registers the workspace under the SESSION tenant, leaves no token and no credential in .git/config", async () => {
+    const remote = makeRemote();
+    const { mat, wsManager, cache, audit } = setup({ remote });
+    assert.equal(mat.admit(WS, REF), true);
+    const r = await mat.ensure(WS, REF);
+    assert.equal(r.root, path.join(fs.realpathSync(cache), WS));
+    assert.equal(fs.readFileSync(path.join(r.root, "a.txt"), "utf8"), "one\n");
+    const w = wsManager.list().find((x) => x.id === WS);
+    assert.equal(w.tenantId, TENANT);
+    const cfg = fs.readFileSync(path.join(r.root, ".git", "config"), "utf8");
+    assert.ok(!/@|token|password|x-access-token/i.test(cfg.replace(/user\.email/g, "")), "config has no credential");
+    assert.deepEqual(fs.readdirSync(cache).filter((n) => n.startsWith(".tmp-")), [], "no temp clone left");
+    assert.equal(mat.stats.cloned, 1);
+    assert.ok(audit.tail().some((e) => e.event === "workspace_ready"));
+});
+
+test("ensure: second call fetches and fast-forwards a CLEAN clone; a DIRTY one is kept untouched", async () => {
+    const remote = makeRemote();
+    const { mat } = setup({ remote });
+    const r = await mat.ensure(WS, REF);
+    remote.push("two\n");
+    await mat.ensure(WS, REF);
+    assert.equal(fs.readFileSync(path.join(r.root, "a.txt"), "utf8"), "two\n");
+    fs.writeFileSync(path.join(r.root, "a.txt"), "local work\n");
+    remote.push("three\n");
+    await mat.ensure(WS, REF);
+    assert.equal(fs.readFileSync(path.join(r.root, "a.txt"), "utf8"), "local work\n", "previous job's work is never reset");
+    assert.equal(mat.stats.reused, 2);
+});
+
+test("ensure: a missing branch fails with a code, leaves no directory behind and nothing registered", async () => {
+    const remote = makeRemote();
+    const { mat, wsManager, cache } = setup({ remote });
+    await assert.rejects(() => mat.ensure(WS, { ...REF, branch: "nope" }), (e) => e instanceof MaterializeError && e.code === "branch_missing" && e.jobErrorCode === "infra" && !/nope|acme|bare|remote/.test(e.message));
+    assert.deepEqual(fs.readdirSync(cache), []);
+    assert.equal(wsManager.list().length, 0);
+});
+
+test("ensure: concurrent jobs for the same workspace share ONE clone; two workspaces are serialized (one clone at a time)", async () => {
+    const remote = makeRemote();
+    let active = 0, peak = 0, clones = 0;
+    const real = (await import("../../src/la-protocol-v2/jobs/git-exec.js")).runGit;
+    const spy = async (args, o) => { const isClone = args[0] === "clone"; if (isClone) { clones++; active++; peak = Math.max(peak, active); await new Promise((r) => setTimeout(r, 40)); } try { return await real(args, o); } finally { if (isClone) active--; } };
+    const { mat } = setup({ remote, allow: "github.com/acme/*", runGit: spy });
+    const WS2 = "44444444-2222-4333-8444-555555555555";
+    await Promise.all([mat.ensure(WS, REF), mat.ensure(WS, REF), mat.ensure(WS2, REF)]);
+    assert.equal(clones, 2);
+    assert.equal(peak, 1);
+});
+
+test("ensure: a workspace of another tenant on disk, a symlinked cache entry and a repo outside the allowlist are refused even if admit() was skipped", async () => {
+    const remote = makeRemote();
+    const { mat, cache } = setup({ remote });
+    const outside = tmp("outside");
+    fs.symlinkSync(outside, path.join(cache, WS));
+    await assert.rejects(() => mat.ensure(WS, REF), (e) => e.code === "cache_entry_unsafe");
+    assert.deepEqual(fs.readdirSync(outside), []);
+    await assert.rejects(() => mat.ensure("55555555-2222-4333-8444-555555555555", { ...REF, org: "evil" }), (e) => e.code === "repo_not_allowed");
+    const other = setup({ remote, tenant: OTHER });
+    const first = await mat.ensure("66666666-2222-4333-8444-555555555555", REF);
+    fs.cpSync(first.root, path.join(other.cache, "66666666-2222-4333-8444-555555555555"), { recursive: true });   // same sidecar, tenant TENANT, found by OTHER's agent
+    await assert.rejects(() => other.mat.ensure("66666666-2222-4333-8444-555555555555", REF), (e) => e.code === "tenant_mismatch" || e.code === "foreign_directory");
+});
+
+test("ensure: a clone above the size limit is removed (too_large); an abort before start does not run git", async () => {
+    const remote = makeRemote();
+    const { mat, cache } = setup({ remote, env: { LOCAL_AGENT_WORKSPACE_MAX_BYTES: String(1024 * 1024) } });
+    fs.writeFileSync(path.join(remote.work, "big.bin"), crypto.randomBytes(1200 * 1024));
+    git(remote.work, "add", "."); git(remote.work, "commit", "-m", "big"); git(remote.work, "push", "origin", "main");
+    await assert.rejects(() => mat.ensure(WS, REF), (e) => e.code === "too_large");
+    assert.deepEqual(fs.readdirSync(cache), []);
+    const ac = new AbortController(); ac.abort();
+    await assert.rejects(() => mat.ensure("77777777-2222-4333-8444-555555555555", REF, ac.signal), (e) => e.code === "aborted");
+});
+
+// ---------------------------------------------------------------- secrets
+
+test("secrets: the token file is only passed by PATH (askpass), never in args, env values, logs, audit or errors; the askpass script holds no token", async () => {
+    const dir = tmp("tok");
+    const tokenFile = path.join(dir, "token");
+    fs.writeFileSync(tokenFile, SECRET, { mode: 0o600 });
+    const calls = [];
+    const fake = async (args, o) => { calls.push({ args, env: o.env }); return { ok: false, code: "auth" }; };
+    const logs = [];
+    const { mat, audit, cache } = setup({ env: { LOCAL_AGENT_GIT_TOKEN_FILE: tokenFile }, runGit: fake });
+    await assert.rejects(() => mat.ensure(WS, REF), (e) => e.code === "auth" && !e.message.includes(SECRET));
+    const everything = JSON.stringify({ calls, audit: audit.tail(100), logs, stats: mat.stats });
+    assert.ok(!everything.includes(SECRET));
+    assert.equal(calls[0].env.LA_GIT_TOKEN_FILE, tokenFile);
+    assert.ok(calls[0].env.GIT_ASKPASS && calls[0].env.GIT_TERMINAL_PROMPT === "0");
+    assert.ok(!calls[0].args.some((a) => /@|ghp_|x-access-token/.test(a)), "no credential in any git argument");
+    const script = fs.readFileSync(ensureAskpassScript(fs.realpathSync(cache)), "utf8");
+    assert.ok(!script.includes(SECRET));
+    assert.equal(fs.statSync(path.join(fs.realpathSync(cache), ".vh-git-askpass.sh")).mode & 0o777, 0o700);
+});
+
+test("secrets: with a real git the askpass script answers from the file (user constant, password = file content) without the agent holding it", () => {
+    const dir = tmp("ask");
+    const tokenFile = path.join(dir, "token");
+    fs.writeFileSync(tokenFile, SECRET + "\n", { mode: 0o600 });
+    const s = ensureAskpassScript(dir);
+    const env = { PATH: process.env.PATH, LA_GIT_TOKEN_FILE: tokenFile };
+    assert.equal(execFileSync(s, ["Username for 'https://github.com': "], { env, encoding: "utf8" }).trim(), "x-access-token");
+    assert.equal(execFileSync(s, ["Password for 'https://x-access-token@github.com': "], { env, encoding: "utf8" }).trim(), SECRET);
+});
+
+// ---------------------------------------------------------------- job manager
+
+const uuid = () => crypto.randomUUID();
+const tick = (ms = 5) => new Promise((r) => setTimeout(r, ms));
+const until = async (cond, ms = 3000) => { const t0 = Date.now(); while (!cond()) { if (Date.now() - t0 > ms) throw new Error("until: timed out"); await tick(5); } };
+const params = (over = {}) => ({ jobId: uuid(), kind: "fix", repoRef: REF, policy: { operationMode: "assist", automationLevel: 2, ceiling: "assist" }, budget: { tokens: 50_000, seconds: 60 },
+    llm: { alias: "a", keyRef: "ab".repeat(32) }, inputs: [], ...over });
+function mgr({ materializer, resolveWorkspace = () => null }) {
+    const frames = [];
+    const session = { enqueue: async (type, payload) => { frames.push({ type, payload }); return { acked: Promise.resolve() }; } };
+    const started = [];
+    const runner = { name: "r", needsLlm: false, start(job) { started.push(job.jobId); return Promise.resolve({ outcome: "no_change" }); }, cancel() {} };
+    const config = resolveJobsConfig({ LOCAL_AGENT_JOBS: "true", LOCAL_AGENT_JOBS_EVENT_MIN_MS: "50", LOCAL_AGENT_JOBS_TERMINAL_RETRY_MS: "10" }, noop);
+    const m = createJobManager({ session, tenantId: TENANT, resolveWorkspace, materializer, config, env: { LOCAL_AGENT_DLP_MODE: "enforce" }, runner, log: { warn: noop } });
+    return { m, frames, started };
+}
+
+test("manager: without a materializer (flag off) a workspace not served here is rejected unauthorized, as before", () => {
+    const { m, started } = mgr({ materializer: null });
+    const r = m.handleAssign({ params: params(), workspaceId: WS });
+    assert.deepEqual(r, { reject: "unauthorized" });
+    assert.equal(started.length, 0);
+});
+
+test("manager: a repo outside the allowlist is rejected unauthorized and nothing is cloned", () => {
+    const { mat } = setup({ allow: "github.com/other/thing" });
+    let ensured = 0;
+    const spy = { admit: (...a) => mat.admit(...a), ensure: () => { ensured++; }, bindAudit() {} };
+    const { m, started } = mgr({ materializer: spy });
+    assert.deepEqual(m.handleAssign({ params: params(), workspaceId: WS }), { reject: "unauthorized" });
+    assert.equal(ensured, 0);
+    assert.equal(started.length, 0);
+});
+
+test("manager: an allowlisted workspace is accepted, materialized INSIDE the job (after the ack), then the runner starts", async () => {
+    const order = [];
+    let release;
+    const gate = new Promise((r) => { release = r; });
+    const materializer = { admit: () => true, bindAudit() {}, ensure: async (id, ref) => { order.push(["ensure", id, ref.repo]); await gate; order.push(["ensured"]); return { root: "/x" }; } };
+    const { m, started, frames } = mgr({ materializer });
+    const p = params();
+    assert.deepEqual(m.handleAssign({ params: p, workspaceId: WS }), { accept: true });
+    await until(() => order.length === 1);
+    assert.equal(started.length, 0, "the runner waits for the clone");
+    release();
+    await until(() => started.length === 1);
+    assert.deepEqual(order.map((o) => o[0]), ["ensure", "ensured"]);
+    await until(() => frames.some((f) => f.type === "job.result"));
+});
+
+test("manager: a failed materialization (no credential, auth) ends the job failed/infra with a code only; the runner never starts", async () => {
+    const materializer = { admit: () => true, bindAudit() {}, ensure: async () => { throw new MaterializeError("auth"); } };
+    const { m, started, frames } = mgr({ materializer });
+    const p = params();
+    assert.deepEqual(m.handleAssign({ params: p, workspaceId: WS }), { accept: true });
+    await until(() => frames.some((f) => f.type === "job.result"));
+    const res = frames.find((f) => f.type === "job.result").payload;
+    assert.equal(res.outcome, "failed");
+    const fin = frames.filter((f) => f.type === "job.event").pop().payload;
+    assert.equal(fin.state, "failed");
+    assert.equal(fin.errorCode, "infra");
+    assert.equal(started.length, 0);
+    assert.ok(!JSON.stringify(frames).includes("auth"), "the wire carries infra, not the cause");
+});
+
+test("manager: job.cancel while the workspace is being cloned aborts the clone and the runner never starts", async () => {
+    let sig = null;
+    const materializer = { admit: () => true, bindAudit() {}, ensure: (id, ref, signal) => new Promise((_, rej) => { sig = signal; signal.addEventListener("abort", () => rej(new MaterializeError("aborted"))); }) };
+    const { m, started, frames } = mgr({ materializer });
+    const p = params();
+    m.handleAssign({ params: p, workspaceId: WS });
+    await until(() => sig);
+    m.handleCancel({ params: { jobId: p.jobId, reason: "user" } });
+    await until(() => frames.some((f) => f.type === "job.result"));
+    assert.equal(frames.find((f) => f.type === "job.result").payload.outcome, "cancelled");
+    assert.equal(started.length, 0);
+});
+
+test("manager + real materializer: a workspace of another tenant already open here is not touched (resolver refuses, materializer refuses)", async () => {
+    const { mat, wsManager, cache } = setup();
+    const d = path.join(cache, "x"); fs.mkdirSync(d);
+    await wsManager.open(WS, d, { tenantId: OTHER });
+    const resolve = (id) => { const w = wsManager.list().find((x) => x.id === id); return w && String(w.tenantId).toLowerCase() === TENANT ? { root: w.root } : null; };
+    const { m, started } = mgr({ materializer: mat, resolveWorkspace: resolve });
+    assert.deepEqual(m.handleAssign({ params: params(), workspaceId: WS }), { reject: "unauthorized" });
+    assert.equal(started.length, 0);
+    assert.equal(wsManager.list().find((x) => x.id === WS).tenantId, OTHER);
+});