deepdebug-local-agent 1.10.0 → 1.12.0

package/src/la-protocol-v2/jobs/agent2/supervisor.js

@@ -0,0 +1,269 @@
+/**
+ * supervisor.js - keeps agent2 (the packaged agent loop, profile local-agent) available for the runner (F3-08c, Local Agent half).
+ *
+ *   spawn   (LOCAL_AGENT_AGENT2_CMD)  this agent starts the process, with a minimal environment and a NEW random API token at every start; waits for
+ *                                     `/local/v1/health`; probes it while it runs; restarts it (at the next job) after a crash, at most `maxRestarts`
+ *                                     times inside `restartWindowMs`, then reports `unavailable` instead of looping; kills it above `maxRssBytes`;
+ *                                     stops it with the agent (SIGTERM, then SIGKILL after `stopGraceMs`).
+ *   attach  (LOCAL_AGENT_AGENT2_URL)  agent2 already runs (sidecar); only health is checked. The token is the one it was started with.
+ *
+ * The environment of the child is an ALLOWLIST (PATH, HOME, JAVA_HOME, locale, proxies, the git/ssh variables the machine's own credentials need) plus
+ * what this module sets and what the operator named in LOCAL_AGENT_AGENT2_ENV_PASSTHROUGH (never a name that looks like a secret). Nothing else of this
+ * agent's environment reaches agent2: not the LLM key (it lives in the holder, in memory), not LOCAL_AGENT_TOKEN's siblings, not the signing keys.
+ * stdout/stderr of the child are drained and DROPPED: they may hold customer content; agent2's own logging is configured in agent2.
+ */
+import { spawn as nodeSpawn, execFile } from "node:child_process";
+import crypto from "node:crypto";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createAgent2Api } from "./api-client.js";
+import { isSecretEnvName } from "../../../utils/child-env.js";
+
+const ALLOW = Object.freeze(["PATH", "HOME", "USER", "LOGNAME", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "TMPDIR", "TMP", "TEMP", "JAVA_HOME",
+    "SSH_AUTH_SOCK", "GIT_ASKPASS", "GIT_SSH", "GIT_SSH_COMMAND", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_CONFIG_NOSYSTEM", "GIT_TERMINAL_PROMPT",
+    "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy", "SSL_CERT_FILE", "SSL_CERT_DIR", "SYSTEMROOT", "PATHEXT", "COMSPEC"]);
+
+export class Agent2UnavailableError extends Error {
+    constructor(code) { super(code); this.name = "Agent2UnavailableError"; this.code = code; }
+}
+
+const defaultSleep = (ms) => new Promise((r) => { const t = setTimeout(r, ms); if (t.unref) t.unref(); });
+const defaultRss = (pid) => new Promise((resolve) => {
+    execFile("ps", ["-o", "rss=", "-p", String(pid)], { timeout: 3_000 }, (err, out) => {
+        const kb = err ? 0 : Number.parseInt(String(out).trim(), 10);
+        resolve(Number.isFinite(kb) && kb > 0 ? kb * 1024 : 0);
+    });
+});
+
+/** The full command line of a process, or null when it cannot be told (no `ps`, no such process). */
+const defaultCmdline = (pid) => new Promise((resolve) => {
+    execFile("ps", ["-ww", "-o", "command=", "-p", String(pid)], { timeout: 3_000 }, (err, out) => {
+        const t = err ? "" : String(out).trim();
+        resolve(t || null);
+    });
+});
+
+const isAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return !!e && e.code === "EPERM"; } };
+
+// Children still running when THIS process exits normally (SIGTERM/SIGINT handlers, process.exit): ended synchronously, best effort. A SIGKILL of this agent skips
+// 'exit' handlers: that case is the pidfile's (the next start ends the orphan).
+const liveChildren = new Set();
+let exitHooked = false;
+function hookExit() {
+    if (exitHooked) return;
+    exitHooked = true;
+    process.once("exit", () => { for (const c of liveChildren) { try { c.kill("SIGKILL"); } catch { /* gone */ } } });
+}
+
+/** The environment agent2 starts with (pure, so a test can pin it). */
+export function agent2ChildEnv({ config, env, tenantId, token, bridgeBase, callbackToken }) {
+    const out = {};
+    for (const k of ALLOW) if (env[k] !== undefined) out[k] = env[k];
+    for (const k of config.passthrough || []) if (env[k] !== undefined && !isSecretEnvName(k)) out[k] = env[k];
+    Object.assign(out, {
+        AGENT2_LOCAL_MODE: "true",
+        AGENT2_LOCAL_BIND: "127.0.0.1",
+        AGENT2_LOCAL_PORT: String(config.apiPort),
+        AGENT2_LOCAL_API_TOKEN: token,
+        AGENT2_LOCAL_TENANT_ID: tenantId,
+        AGENT2_LLM_BASE_URL: `${bridgeBase}/v1`,                    // the loopback bridge: DLP + the LLM client of this agent, never the AI gateway directly
+        // agent2 reaches this agent's /workspace API THROUGH the bridge, which signs for it (internal marker) and adds the API's X-Agent-Token itself: the token agent2 holds
+        // here is the bridge's callback token, NOT LOCAL_AGENT_TOKEN, and it opens nothing but the bridge
+        AGENT2_LA_WORKSPACE_URL: bridgeBase,
+        AGENT2_LA_WORKSPACE_TOKEN: callbackToken,
+        AGENT2_LA_CALLBACK_URL: bridgeBase,                         // POST {url}/agent2/cp-request: the PolicyGate door (-> policy.check over the v2 channel)
+        AGENT2_LA_CALLBACK_TOKEN: callbackToken,
+        DEEPDEBUG_POLICYGATE_TIMEOUT_MS: String(config.policyCheckTimeoutMs + 3_000),   // agent2 must wait longer than the channel does (default 3 s would cut a decision off)
+    });
+    if (config.maxHeapMb > 0) out.JAVA_TOOL_OPTIONS = `-Xmx${config.maxHeapMb}m`;
+    if (config.approvalWaitSeconds > 0) out.AGENT2_LOCAL_APPROVAL_WAIT_SECONDS = String(config.approvalWaitSeconds);
+    return out;
+}
+
+export function createAgent2Supervisor({ config, tenantId, bridge, env = process.env, log = console, spawnImpl = nodeSpawn, fetchImpl, now = Date.now, sleep = defaultSleep, rssOf = defaultRss, cmdlineOf = defaultCmdline }) {
+    const emitter = new EventEmitter();
+    const warn = (m) => (log.warn || log.log).call(log, m);
+    const info = (m) => (log.info || log.log).call(log, m);
+    const stats = { starts: 0, exits: 0, healthFailed: 0, killedForRss: 0, startFailures: 0, refusedRestartLimit: 0, orphansEnded: 0, orphanChecksSkipped: 0 };
+    const cmdSha = config.mode === "spawn" ? crypto.createHash("sha256").update(JSON.stringify(config.cmd)).digest("hex") : "";
+    const pidFile = config.mode === "spawn" ? (config.pidFile || path.join(env.HOME || env.USERPROFILE || os.homedir(), ".deepdebug", "agent2-runner.pid")) : null;
+    const startTimes = [];
+    let state = "idle";            // idle | starting | ready | down | stopped
+    let child = null;
+    let target = config.mode === "attach" ? { baseUrl: config.url, token: config.token } : null;
+    let starting = null;
+    let healthTimer = null;
+    let healthFails = 0;
+    let lastExitAt = 0;
+    let stopping = false;
+
+    // ---- the pidfile: a child that outlived this agent (SIGKILL, crash) would keep the API port and an old token; the next start ends it
+    function writePidFile(pid) {
+        if (!pidFile || !pid) return;
+        try {
+            fs.mkdirSync(path.dirname(pidFile), { recursive: true, mode: 0o700 });
+            fs.writeFileSync(pidFile, JSON.stringify({ pid, cmdSha, startedAt: now() }), { mode: 0o600 });
+        } catch { warn("[la-agent2] could not write the pidfile of agent2; a restart of this agent will not be able to end an orphan"); }
+    }
+    function removePidFile(onlyPid) {
+        if (!pidFile) return;
+        try {
+            if (onlyPid) { const cur = JSON.parse(fs.readFileSync(pidFile, "utf8")); if (cur && cur.pid !== onlyPid) return; }
+            fs.rmSync(pidFile, { force: true });
+        } catch { /* nothing to remove */ }
+    }
+    /**
+     * An agent2 left by a previous run of this agent: ended (SIGTERM, then SIGKILL after the grace) only when the pid is alive AND its command line is the command
+     * this agent starts (a reused pid of another program is never touched). Where the command line cannot be read (no `ps`) nothing is killed.
+     */
+    async function reapOrphan() {
+        if (!pidFile) return;
+        let rec;
+        try { rec = JSON.parse(fs.readFileSync(pidFile, "utf8")); } catch { return; }
+        const pid = rec && Number.isSafeInteger(rec.pid) && rec.pid > 1 ? rec.pid : 0;
+        if (!pid || pid === process.pid || !isAlive(pid)) { removePidFile(); return; }
+        const line = await cmdlineOf(pid);
+        if (line === null) { stats.orphanChecksSkipped++; warn("[la-agent2] the pidfile names a live process but its command line cannot be read; it is left alone"); return; }
+        if (rec.cmdSha !== cmdSha || !config.cmd.slice(0, 8).every((a) => line.includes(a))) { removePidFile(); return; }   // not ours (any more): the pid was reused
+        warn("[la-agent2] an agent2 from a previous run is still alive; ending it");
+        try { process.kill(pid, "SIGTERM"); } catch { /* gone */ }
+        const deadline = now() + config.stopGraceMs;
+        while (isAlive(pid) && now() < deadline) await sleep(50);
+        if (isAlive(pid)) { try { process.kill(pid, "SIGKILL"); } catch { /* gone */ } await sleep(100); }
+        if (isAlive(pid)) throw new Agent2UnavailableError("orphan_alive");
+        stats.orphansEnded++;
+        removePidFile();
+    }
+
+    const api = createAgent2Api({ getTarget: () => { if (!target) throw new Agent2UnavailableError("agent2_down"); return target; }, requestTimeoutMs: config.requestTimeoutMs, ...(fetchImpl ? { fetchImpl } : {}) });
+
+    function markDown(why) {
+        if (state === "down" || state === "stopped") return;
+        state = "down";
+        if (config.mode === "spawn") target = null;
+        emitter.emit("down", { why });
+    }
+
+    function startHealthTimer() {
+        clearInterval(healthTimer);
+        healthFails = 0;
+        healthTimer = setInterval(async () => {
+            if (state !== "ready") return;
+            if (await api.health()) healthFails = 0;
+            else if (++healthFails >= config.healthFailures) {
+                stats.healthFailed++;
+                warn("[la-agent2] agent2 stopped answering its health probe");
+                if (child) { try { child.kill("SIGKILL"); } catch { /* gone */ } }
+                markDown("health");
+                return;
+            }
+            if (config.mode === "spawn" && config.maxRssBytes > 0 && child && child.pid) {
+                const rss = await rssOf(child.pid);
+                if (rss > config.maxRssBytes) { stats.killedForRss++; warn("[la-agent2] agent2 is above LOCAL_AGENT_AGENT2_MAX_RSS_BYTES; stopping it (a new one starts at the next job)"); try { child.kill("SIGKILL"); } catch { /* gone */ } markDown("rss"); }
+            }
+        }, config.healthIntervalMs);
+        if (healthTimer.unref) healthTimer.unref();
+    }
+
+    async function waitHealthy(proc) {
+        const deadline = now() + config.startTimeoutMs;
+        for (;;) {
+            if (stopping) throw new Agent2UnavailableError("stopped");
+            if (proc && proc.exited) throw new Agent2UnavailableError("exited_during_start");
+            if (await api.health()) return;
+            if (now() >= deadline) throw new Agent2UnavailableError("start_timeout");
+            await sleep(Math.min(250, Math.max(10, config.startTimeoutMs / 20)));
+        }
+    }
+
+    async function startAttach() {
+        state = "starting";
+        try { await waitHealthy(null); } catch (e) { state = "down"; stats.startFailures++; throw e; }
+        state = "ready";
+        startHealthTimer();
+    }
+
+    async function startSpawn() {
+        const t = now();
+        while (startTimes.length && t - startTimes[0] > config.restartWindowMs) startTimes.shift();
+        if (startTimes.length >= config.maxRestarts + 1) { stats.refusedRestartLimit++; throw new Agent2UnavailableError("restart_limit"); }
+        if (startTimes.length > 0) { const wait = Math.max(0, lastExitAt + config.restartBackoffMs * startTimes.length - t); if (wait > 0) await sleep(wait); }
+        startTimes.push(now());
+        state = "starting";
+        stats.starts++;
+        try { await reapOrphan(); } catch (e) { state = "down"; stats.startFailures++; throw e; }
+        const token = crypto.randomBytes(32).toString("base64url");             // a NEW secret per start: nothing from a previous process works
+        const callbackToken = crypto.randomBytes(32).toString("base64url");
+        const { baseUrl: bridgeBase } = await bridge.listen();
+        bridge.setCallbackToken(callbackToken);
+        const childEnv = agent2ChildEnv({ config, env, tenantId, token, bridgeBase, callbackToken });
+        const proc = { exited: false };
+        let c;
+        try {
+            c = spawnImpl(config.cmd[0], config.cmd.slice(1), { env: childEnv, stdio: ["ignore", "pipe", "pipe"], shell: false, windowsHide: true });
+        } catch { state = "down"; stats.startFailures++; throw new Agent2UnavailableError("spawn_failed"); }
+        child = c;
+        liveChildren.add(c); hookExit();
+        writePidFile(c.pid);
+        for (const s of [c.stdout, c.stderr]) { if (s && typeof s.on === "function") { s.on("data", () => {}); s.on("error", () => {}); } }   // drained and dropped
+        c.on("error", () => { proc.exited = true; liveChildren.delete(c); });
+        c.on("exit", (code, signal) => {
+            proc.exited = true;
+            stats.exits++;
+            lastExitAt = now();
+            liveChildren.delete(c);
+            removePidFile(c.pid);
+            if (child === c) child = null;
+            if (!stopping) warn(`[la-agent2] agent2 exited (code ${code ?? "none"}, signal ${signal ?? "none"})`);
+            markDown("exit");
+        });
+        info(`[la-agent2] started agent2 (pid ${c.pid ?? "?"})`);
+        target = { baseUrl: `http://127.0.0.1:${config.apiPort}`, token };
+        try { await waitHealthy(proc); } catch (e) {
+            stats.startFailures++;
+            try { c.kill("SIGKILL"); } catch { /* gone */ }
+            state = "down"; target = null;
+            throw e;
+        }
+        if (proc.exited) { state = "down"; target = null; throw new Agent2UnavailableError("exited_during_start"); }
+        state = "ready";
+        startHealthTimer();
+    }
+
+    return {
+        api, stats,
+        on: (ev, fn) => emitter.on(ev, fn),
+        off: (ev, fn) => emitter.off(ev, fn),
+        get state() { return state; },
+        get pid() { return child ? child.pid : null; },
+        /** Resolves when agent2 answers its health probe (starting it first in spawn mode). Throws Agent2UnavailableError(code). */
+        async ensureReady() {
+            if (stopping) throw new Agent2UnavailableError("stopped");
+            if (state === "ready") {
+                if (await api.health()) return;
+                if (child) { try { child.kill("SIGKILL"); } catch { /* gone */ } }
+                markDown("health");
+            }
+            if (!starting) starting = (config.mode === "attach" ? startAttach() : startSpawn()).finally(() => { starting = null; });
+            await starting;
+        },
+        /** Stops the child (SIGTERM, then SIGKILL after the grace) and every timer. */
+        async stop() {
+            stopping = true;
+            state = "stopped";
+            clearInterval(healthTimer);
+            const c = child;
+            child = null;
+            if (!c) return;
+            await new Promise((resolve) => {
+                let done = false;
+                const fin = () => { if (!done) { done = true; clearTimeout(t); resolve(); } };
+                const t = setTimeout(() => { try { c.kill("SIGKILL"); } catch { /* gone */ } fin(); }, config.stopGraceMs);   // not unref'd: whoever awaits stop() waits at most stopGraceMs
+                c.once("exit", fin);
+                try { if (!c.kill("SIGTERM")) fin(); } catch { fin(); }
+            });
+        },
+    };
+}

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,13 +8,14 @@
 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"]);
 
-export function installJobs({ link, tenantId, wsManager, getWorkspaceRoot, config, env = process.env, log = console, runner = null, onResult = null, now = Date.now, memoryUsage, sleep }) {
-    if (dlpConfigFromEnv(env).mode !== "enforce") throw new Error("job.assign needs LOCAL_AGENT_DLP_MODE=enforce");
+/** A workspace "served here": open in the manager (of this tenant, or of none yet) or the default root. -> { root } | null */
+export function makeWorkspaceResolver({ wsManager, getWorkspaceRoot, tenantId }) {
     const tenant = String(tenantId).toLowerCase();
-    const resolveWorkspace = (workspaceId) => {
+    return (workspaceId) => {
         if (typeof workspaceId !== "string" || !workspaceId) return null;
         const listed = (wsManager?.list?.() || []).find((w) => w && w.id === workspaceId);
         if (listed) {
@@ -24,9 +25,18 @@ export function installJobs({ link, tenantId, wsManager, getWorkspaceRoot, confi
         if (workspaceId === "default") { const root = getWorkspaceRoot(); return root ? { root } : null; }
         return null;
     };
+}
+
+export function installJobs({ link, tenantId, wsManager, getWorkspaceRoot, config, env = process.env, log = console, runner = null, onResult = null, now = Date.now, memoryUsage, sleep }) {
+    if (dlpConfigFromEnv(env).mode !== "enforce") throw new Error("job.assign needs LOCAL_AGENT_DLP_MODE=enforce");
+    const tenant = String(tenantId).toLowerCase();
+    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)
@@ -77,7 +78,8 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
     const note = (event, extra) => { try { auditor.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
     const reject = (rec, code) => { stats.rejected[code] = (stats.rejected[code] || 0) + 1; note("job_rejected", { code, ...rec }); return { reject: code }; };
 
-    const snapshot = (rec, over = {}) => ({ jobId: rec.jobId, state: rec.state, phase: rec.phase, iteration: rec.iteration, filesRead: rec.filesRead, filesChanged: rec.filesChanged,
+    // `waiting` (a runner that waits for a person: ADR-0010) shows as `waiting_approval` while the job runs; every other state is the job's own
+    const snapshot = (rec, over = {}) => ({ jobId: rec.jobId, state: rec.state === "running" && rec.waiting ? "waiting_approval" : rec.state, phase: rec.phase, iteration: rec.iteration, filesRead: rec.filesRead, filesChanged: rec.filesChanged,
         tokensIn: rec.tokensIn, tokensOut: rec.tokensOut, costUsd: rec.costUsd, durationMs: Math.max(0, now() - rec.acceptedAt), ...over });
     const tokensUsed = (rec) => rec.tokensIn + rec.tokensOut;
     const publish = (rec) => { if (rec.state === "running" || rec.state === "queued") ev.progress(rec, snapshot(rec)); };
@@ -154,20 +156,23 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
             if (!llm || !llm.client) { finish(rec, null, Object.assign(new Error("no llm"), { jobErrorCode: "llm_error" })); return; }
             if (!llm.holder.held || !llm.holder.matches(rec.job.llm.keyRef)) { finish(rec, null, Object.assign(new Error("no key"), { jobErrorCode: "llm_error" })); return; }
         }
+        async function llmCall(kind, opts) {
+            if (rec.abortReason || rec.finished) throw new LlmClientError("cancelled");
+            const r = await llm.client[kind]({ ...opts, model: opts.model ?? rec.job.llm.alias, signal: rec.ac.signal, job: { jobId: rec.jobId, agent: theRunner.name }, tokensLeft: Math.max(0, rec.budget.tokens - tokensUsed(rec)) });
+            rec.tokensIn += r.usage.promptTokens;
+            rec.tokensOut += r.usage.completionTokens;
+            if (r.costUsd !== null && r.costUsd !== undefined) rec.costUsd = (rec.costUsd || 0) + r.costUsd;
+            publish(rec);
+            if (tokensUsed(rec) > rec.budget.tokens) abort(rec, "budget_exceeded");   // the next call is refused at equality (client: budget_exceeded); only an overshoot of the provider aborts
+            return r;
+        }
         const ctx = Object.freeze({
             signal: rec.ac.signal,
             workspace: Object.freeze({ id: rec.workspaceId }),
             llm: Object.freeze({
-                async chat(opts = {}) {
-                    if (rec.abortReason || rec.finished) throw new LlmClientError("cancelled");
-                    const r = await llm.client.chat({ ...opts, model: opts.model ?? rec.job.llm.alias, signal: rec.ac.signal, job: { jobId: rec.jobId, agent: theRunner.name }, tokensLeft: Math.max(0, rec.budget.tokens - tokensUsed(rec)) });
-                    rec.tokensIn += r.usage.promptTokens;
-                    rec.tokensOut += r.usage.completionTokens;
-                    if (r.costUsd !== null && r.costUsd !== undefined) rec.costUsd = (rec.costUsd || 0) + r.costUsd;
-                    publish(rec);
-                    if (tokensUsed(rec) > rec.budget.tokens) abort(rec, "budget_exceeded");   // the next call is refused at equality (client: budget_exceeded); only an overshoot of the provider aborts
-                    return r;
-                },
+                chat: (opts = {}) => llmCall("chat", opts),
+                /** F3-08c: one turn of the Anthropic Messages API (tools, content blocks) - what the packaged agent loop speaks. Same gates, same budget. */
+                messages: (opts = {}) => llmCall("messages", opts),
             }),
             async readFile(ref, opts = {}) {
                 // an abandoned, cancelled or timed-out job reads nothing more (no descriptor opened, no buffer built), and what a read that was already
@@ -183,11 +188,15 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
                 if (rec.finished) return;
                 if (p.phase) rec.phase = p.phase;
                 for (const k of ["iteration", "filesRead", "filesChanged"]) if (Number.isSafeInteger(p[k]) && p[k] >= 0) rec[k] = p[k];
+                if (typeof p.waitingApproval === "boolean") rec.waiting = p.waitingApproval;
                 publish(rec);
             },
             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(() => {});
@@ -213,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"); }
@@ -228,8 +242,8 @@ 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,
-                tokensIn: 0, tokensOut: 0, costUsd: null, acceptedAt: now(), startedAt: 0, ac: new AbortController(), abortReason: null, finished: false, ev: null, holdsSlot: false,
+                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 }),
             };