deepdebug-local-agent 1.9.0 → 1.11.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/config.js

@@ -0,0 +1,60 @@
+/**
+ * config.js - LOCAL_AGENT_JOBS flag and limits of the job.assign receiver (F3-10).
+ *
+ *   false (default)  `job.assign` and `job.cancel` keep being acked `rejected protocol_unsupported`, the capability `job.assign` is NOT announced:
+ *                    nothing of this folder is loaded.
+ *   true             the agent receives `job.assign`, validates it, acks it and hands it to a RUNNER (runners.js); `job.cancel` stops it; progress,
+ *                    cost and the result go back as `job.event` / `job.result` (metadata only). Needs LOCAL_AGENT_PROTOCOL_V2=true and
+ *                    LOCAL_AGENT_DLP_MODE=enforce (a job reads client files), and a runner: LOCAL_AGENT_JOBS_RUNNER=smoke (the reference runner,
+ *                    which also needs the LLM client) or one passed to buildV2Link by the packaging of the agent loop (F3-08c). Without a runner the
+ *                    receiver is NOT installed and the capability is NOT announced.
+ *
+ * Unset/empty/unrecognised = false. Every number is clamped: a bad value falls back to the default, never to "unlimited".
+ */
+export const JOBS_FLAG = "LOCAL_AGENT_JOBS";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+const KIB = 1024;
+const MIB = 1024 * KIB;
+
+function int(raw, def, min, max) {
+    const n = Number.parseInt(String(raw ?? ""), 10);
+    return Number.isFinite(n) && n >= min && n <= max ? n : def;
+}
+
+export const KNOWN_RUNNERS = Object.freeze(["smoke"]);
+
+export function resolveJobsConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[JOBS_FLAG] ?? "").trim().toLowerCase();
+    if (!TRUE.has(raw)) {
+        if (!FALSE.has(raw)) warn(`[la-jobs] unrecognised ${JOBS_FLAG} value; job.assign stays off`);
+        return { enabled: false };
+    }
+    let runner = String(env.LOCAL_AGENT_JOBS_RUNNER ?? "").trim().toLowerCase() || null;
+    if (runner && !KNOWN_RUNNERS.includes(runner)) { warn("[la-jobs] unknown LOCAL_AGENT_JOBS_RUNNER; no runner selected"); runner = null; }
+    const maxRss = Number.parseInt(String(env.LOCAL_AGENT_JOBS_MAX_RSS_BYTES ?? ""), 10);
+    return {
+        enabled: true,
+        runner,
+        maxConcurrent: int(env.LOCAL_AGENT_JOBS_MAX_CONCURRENT, 1, 1, 8),                       // jobs running at once
+        maxQueued: int(env.LOCAL_AGENT_JOBS_MAX_QUEUED, 4, 0, 64),                              // accepted and waiting for a slot (state `queued`); beyond it: rate_limited
+        // a job asks for a budget; the agent never grants more than this (clamped, not refused: the job then ends budget_exceeded / timeout)
+        maxTokens: int(env.LOCAL_AGENT_JOBS_MAX_TOKENS, 2_000_000, 1, 10_000_000),
+        maxSeconds: int(env.LOCAL_AGENT_JOBS_MAX_SECONDS, 3_600, 1, 86_400),
+        // job.assign `options.maxIterations` caps the agent loop BELOW this ceiling, never above it (options.js); also the value when the job names none
+        maxIterations: int(env.LOCAL_AGENT_JOBS_MAX_ITERATIONS, 25, 1, 100),
+        // memory: each admitted job reserves its inline bytes + memPerJobBytes against maxMemoryBytes; with maxRssBytes > 0 a new job is also
+        // refused while the process RSS is above it (a runner is code in this process: the reservation is accounting, the RSS check is the brake)
+        memPerJobBytes: int(env.LOCAL_AGENT_JOBS_MEM_PER_JOB_BYTES, 32 * MIB, MIB, 4 * 1024 * MIB),
+        maxMemoryBytes: int(env.LOCAL_AGENT_JOBS_MAX_MEMORY_BYTES, 256 * MIB, 16 * MIB, 64 * 1024 * MIB),
+        maxRssBytes: Number.isFinite(maxRss) && maxRss >= 128 * MIB ? maxRss : 0,
+        eventMinIntervalMs: int(env.LOCAL_AGENT_JOBS_EVENT_MIN_MS, 1_000, 50, 60_000),          // progress job.event coalescing (the last one wins); terminal ones are never dropped
+        terminalRetries: int(env.LOCAL_AGENT_JOBS_TERMINAL_RETRIES, 20, 0, 200),
+        terminalRetryMs: int(env.LOCAL_AGENT_JOBS_TERMINAL_RETRY_MS, 500, 10, 10_000),
+        cancelGraceMs: int(env.LOCAL_AGENT_JOBS_CANCEL_GRACE_MS, 10_000, 100, 120_000),         // after job.cancel a runner that has not stopped is abandoned
+        recentJobs: 256,                                                                         // finished job ids remembered, so a repeated job.assign is idempotent
+        smokeMaxFileBytes: int(env.LOCAL_AGENT_JOBS_SMOKE_MAX_FILE_BYTES, 64 * KIB, KIB, MIB),
+        auditFile: String(env.LOCAL_AGENT_JOBS_AUDIT_FILE ?? "").trim() || null,
+    };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * events.js - LA -> CP `job.event` and `job.result` of one job (F3-10). METADATA ONLY: the payloads are built from a fixed whitelist of
+ * counters, enums and ids (the contract has no free-text field; the session re-validates every frame against the closed schemas before a byte
+ * is written). Nothing of the work itself (prompts, answers, paths, diffs) can be put here.
+ *
+ *   progress  coalesced: at most one frame per `eventMinIntervalMs` per job, the LAST state wins (a fast runner cannot flood the channel; a
+ *             full send queue (`rate_limited`) or a detached session drops that frame and counts it: progress is advisory).
+ *   terminal  `job.event` (succeeded|failed|cancelled) then `job.result`: never dropped on backpressure; retried every `terminalRetryMs`
+ *             up to `terminalRetries` times while the queue is full or the session is between connections, then given up (audited).
+ */
+import { ProtocolError } from "../errors.js";
+
+const STATES = new Set(["queued", "running", "waiting_approval", "succeeded", "failed", "cancelled"]);
+const PHASES = new Set(["init", "context", "plan", "edit", "validate", "pr", "done"]);
+export const JOB_ERROR_CODES = Object.freeze(["none", "llm_error", "policy_denied", "build_failed", "tests_failed", "timeout", "cancelled", "budget_exceeded", "infra", "unknown"]);
+const OUTCOMES = new Set(["pr_opened", "no_change", "failed", "cancelled"]);
+const isCount = (v) => Number.isSafeInteger(v) && v >= 0;
+
+/** The `job.event` payload of a job snapshot (unknown or invalid fields are left out, never repaired). */
+export function eventPayload(snap) {
+    const p = { jobId: snap.jobId, state: STATES.has(snap.state) ? snap.state : "running" };
+    if (PHASES.has(snap.phase)) p.phase = snap.phase;
+    if (Number.isInteger(snap.iteration) && snap.iteration >= 0 && snap.iteration <= 1000) p.iteration = snap.iteration;
+    for (const k of ["filesRead", "filesChanged", "tokensIn", "tokensOut", "durationMs"]) if (isCount(snap[k])) p[k] = snap[k];
+    if (typeof snap.costUsd === "number" && Number.isFinite(snap.costUsd) && snap.costUsd >= 0 && snap.costUsd <= 100000) p.costUsd = Math.round(snap.costUsd * 1e6) / 1e6;
+    if (JOB_ERROR_CODES.includes(snap.errorCode)) p.errorCode = snap.errorCode;
+    return p;
+}
+
+/** The `job.result` payload: the outcome and the fields a runner may report (the schema validates their shapes; an invalid one drops the whole extra set). */
+export function resultPayload(jobId, outcome, extra = {}) {
+    const p = { jobId, outcome: OUTCOMES.has(outcome) ? outcome : "failed" };
+    for (const k of ["prUrl", "branch", "commitSha", "diffSha256"]) if (typeof extra[k] === "string") p[k] = extra[k];
+    if (isCount(extra.filesChangedCount)) p.filesChangedCount = extra.filesChangedCount;
+    const t = extra.tests;
+    if (t && isCount(t.pass) && isCount(t.fail) && isCount(t.skip)) p.tests = { pass: t.pass, fail: t.fail, skip: t.skip };
+    return p;
+}
+
+const RETRYABLE = new Set(["rate_limited", "not_ready"]);
+
+export function createJobEvents({ session, config, audit = null, now = Date.now, sleep = (ms) => new Promise((r) => { const t = setTimeout(r, ms); if (t.unref) t.unref(); }) }) {
+    const stats = { progressSent: 0, progressDropped: 0, terminalSent: 0, terminalGivenUp: 0 };
+    const timers = new Set();
+    let closed = false;
+    const note = (event, extra) => { try { audit?.record({ event, ...extra }); } catch { /* never breaks the data path */ } };
+
+    async function enqueueOnce(type, payload, workspaceId) {
+        const h = await session.enqueue(type, payload, { workspaceId });
+        h.acked.catch(() => {});   // the session retransmits; a lost ack is not this module's business
+    }
+
+    async function sendReliable(type, payload, workspaceId, jobShort) {
+        for (let i = 0; ; i++) {
+            if (closed) return { ok: false, code: "agent_offline" };
+            try { await enqueueOnce(type, payload, workspaceId); return { ok: true }; } catch (e) {
+                const code = e instanceof ProtocolError ? e.code : "internal";
+                if (code === "schema_violation") return { ok: false, code };   // the caller may fall back to a smaller payload
+                if (!RETRYABLE.has(code) || i >= config.terminalRetries) { stats.terminalGivenUp++; note("job_event_given_up", { jobShort, type, code, tries: i + 1 }); return { ok: false, code }; }
+                await sleep(config.terminalRetryMs);
+            }
+        }
+    }
+
+    return {
+        stats,
+        /** Advisory: coalesced, may be dropped. `job.ev` is this module's private per-job state. */
+        progress(job, snap) {
+            if (closed) return;
+            const ev = job.ev || (job.ev = { last: 0, timer: null, pending: null });
+            ev.pending = eventPayload(snap);
+            if (ev.timer) return;
+            const flush = () => {
+                ev.timer = null;
+                const payload = ev.pending;
+                ev.pending = null;
+                if (!payload || closed) return;
+                ev.last = now();
+                enqueueOnce("job.event", payload, job.workspaceId).then(() => { stats.progressSent++; }, () => { stats.progressDropped++; });
+            };
+            const wait = Math.max(0, ev.last + config.eventMinIntervalMs - now());
+            if (wait === 0) { flush(); return; }
+            ev.timer = setTimeout(flush, wait);
+            if (ev.timer.unref) ev.timer.unref();
+            timers.add(ev.timer);
+        },
+        /**
+         * The end: the pending progress frame is discarded (the terminal event carries the totals). The RESULT goes out BEFORE the terminal
+         * event: the control plane closes the job on the first terminal frame it sees and drops anything that comes after it, so a result
+         * sent after the terminal event (prUrl, branch, files changed) would be lost. Both are always sent; true only if both were accepted.
+         */
+        async terminal(job, snap, result) {
+            const ev = job.ev;
+            if (ev) { if (ev.timer) { clearTimeout(ev.timer); timers.delete(ev.timer); ev.timer = null; } ev.pending = null; }
+            const jobShort = job.short;
+            let r = await sendReliable("job.result", result, job.workspaceId, jobShort);
+            // a runner-supplied field the schema refuses (a malformed PR url) must not lose the result: send the outcome alone
+            if (!r.ok && r.code === "schema_violation") r = await sendReliable("job.result", { jobId: result.jobId, outcome: result.outcome }, job.workspaceId, jobShort);
+            const okResult = r.ok;
+            const okEvent = (await sendReliable("job.event", eventPayload(snap), job.workspaceId, jobShort)).ok;
+            if (okEvent && okResult) stats.terminalSent++;
+            return okEvent && okResult;
+        },
+        close() { closed = true; for (const t of timers) clearTimeout(t); timers.clear(); },
+    };
+}

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

@@ -0,0 +1,43 @@
+/**
+ * install.js - puts the job.assign receiver on a v2 link (F3-10). Called by runtime.js only when LOCAL_AGENT_JOBS=true, v2 is on, DLP is enforce and a
+ * runner exists. Registers `job.assign` and `job.cancel`; `link.jobs` is the manager (setRunner() is how F3-08c plugs the packaged agent loop in).
+ *
+ * Git credentials: the control plane NEVER sends a token (the job.assign schema has no field for one, and it is closed). A runner that opens a PR uses
+ * what this machine already has: the user's git credential helper, ssh-agent or the environment of the agent's own process. See docs/la-jobs-and-llm.md.
+ */
+import { dlpConfigFromEnv } from "../../dlp/index.js";
+import { createJobManager } from "./manager.js";
+import { createSmokeRunner } from "./smoke-runner.js";
+
+export const JOBS_CAPABILITIES = Object.freeze(["job.assign"]);
+
+/** 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();
+    return (workspaceId) => {
+        if (typeof workspaceId !== "string" || !workspaceId) return null;
+        const listed = (wsManager?.list?.() || []).find((w) => w && w.id === workspaceId);
+        if (listed) {
+            if (listed.tenantId && String(listed.tenantId).toLowerCase() !== tenant) return null;
+            return listed.root ? { root: listed.root } : null;
+        }
+        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,
+        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));
+    const closeLink = link.close.bind(link);
+    link.close = () => { manager.cancelAll(); closeLink(); };
+    link.jobs = manager;
+    return manager;
+}