deepdebug-local-agent 1.9.0 → 1.10.0

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

@@ -0,0 +1,276 @@
+/**
+ * manager.js - `job.assign` / `job.cancel` receiver and job supervisor of the Local Agent (F3-10). Registered by install.js only with
+ * LOCAL_AGENT_JOBS=true, v2 on, DLP enforce and a runner.
+ *
+ * `job.assign` (the frame is already schema-validated and its Ed25519 signature checked by the session). The answer is the ack:
+ *   accepted                     the job runs (or waits, state `queued`) and its progress/outcome come back as job.event / job.result.
+ *                                A job id already known (running, queued or recently finished) is acked `accepted` and NOT started again.
+ *   rejected protocol_unsupported  no runner, DLP not enforce (read per request), or the runner does not do that `kind`
+ *   rejected unauthorized          the envelope's workspace is not one this agent serves (for this tenant)
+ *   rejected schema_violation      `options` malformed (the session's schema check comes first; this is the second line)
+ *   rejected protocol_unsupported  also: `options` present and the runner did not declare `supportsOptions` (options.js: never ignore dryRun silently)
+ *   rejected rate_limited          concurrency + queue full, memory reservation or RSS above the limit (retryable: the CP may try later or elsewhere)
+ * The requested budget is CLAMPED to the local ceilings (LOCAL_AGENT_JOBS_MAX_TOKENS / _SECONDS); whatever the job needs beyond ends it with
+ * `budget_exceeded` / `timeout`. Failures that happen after the ack (no LLM key, a runner error) are job.event `failed` + job.result `failed`.
+ *
+ * `job.cancel`: aborts the job's signal, calls runner.cancel(jobId), and after `cancelGraceMs` abandons a runner that did not stop; the job ends
+ * `cancelled` (job.event + job.result). A queued job is cancelled at once. An unknown or finished id is a no-op acked `accepted` (no oracle, idempotent:
+ * a repeated cancel, a cancel of a finished job and a cancel of an orphan the CP gave up are all the same). An id never seen is remembered (bounded), so a
+ * job.assign that arrives afterwards for it is acked `accepted` and NOT run. A job id that is not a UUID is acked `rejected schema_violation`: no lookup, no effect.
+ *
+ * What goes on the wire: only the whitelisted metadata of events.js. What is logged or audited: short hashes of ids, kinds, counters, codes. Never an
+ * input, a prompt, an answer, a path or an error text. The runner's `answer` stays local (`onResult`).
+ */
+import { dlpConfigFromEnv } from "../../dlp/index.js";
+import { createAudit, short } from "../content-handlers/audit.js";
+import { createJobEvents, resultPayload, JOB_ERROR_CODES } from "./events.js";
+import { LlmClientError } from "../llm/client.js";
+import { normalizeJobOptions } from "./options.js";
+
+const LLM_TO_JOB = Object.freeze({ budget_exceeded: "budget_exceeded", timeout: "timeout", cancelled: "cancelled", dlp_blocked: "policy_denied", dlp_denied: "policy_denied", dlp_not_enforced: "policy_denied", model_not_allowed: "policy_denied" });
+const utf8 = new TextEncoder();
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const EARLY_CANCELS = 256;   // job ids cancelled before they were known (bounded)
+
+/** A job error code from whatever a runner threw (codes only; the message is never read). */
+export function jobErrorCodeOf(err) {
+    if (err && JOB_ERROR_CODES.includes(err.jobErrorCode) && err.jobErrorCode !== "none") return err.jobErrorCode;
+    if (err && err.name === "LlmClientError") return LLM_TO_JOB[err.code] || "llm_error";
+    return "unknown";
+}
+
+/**
+ * Runner interface (F3-08c plugs the packaged agent loop in here):
+ *   { name: string, kinds?: string[] (default: all of fix|implement|quality), needsLlm?: boolean (default true),
+ *     start(job, ctx): Promise<{ outcome: "pr_opened"|"no_change"|"failed"|"cancelled", errorCode?, prUrl?, branch?, commitSha?, filesChangedCount?,
+ *                                diffSha256?, tests?, answer? }>,
+ *     cancel(jobId): void|Promise<void> }
+ * `job.options` (contract 2.1, capability `job.options`): always an object (options.js), frozen, every field present: createBranch, createPullRequest, dryRun,
+ * maxIterations (clamped to LOCAL_AGENT_JOBS_MAX_ITERATIONS), `effects` {createBranch, push, openPullRequest} (what the runner may do outside; dryRun
+ * -> none) and, when named, ticketKey / branchName. A runner declares `supportsOptions: true` to be given options: a job that carries any is
+ * refused `protocol_unsupported` by a runner that does not (dryRun and createPullRequest:false are NEVER ignored silently).
+ * `ctx.readFile` after the job was cancelled, timed out or finished answers `{ok:false, status:"cancelled"}` without touching the disk.
+ * `answer` is client content: it never leaves through this module (it goes to `onResult` only).
+ */
+export function validateRunner(r) {
+    return !!r && typeof r === "object" && typeof r.name === "string" && /^[a-z0-9][a-z0-9._-]{0,31}$/.test(r.name) && typeof r.start === "function" && typeof r.cancel === "function"
+        && (r.kinds === undefined || (Array.isArray(r.kinds) && r.kinds.every((k) => ["fix", "implement", "quality"].includes(k))))
+        && (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,
+    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);
+    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)
+    const recent = new Set();    // jobIds that finished (bounded)
+    const queue = [];
+    const cancelledEarly = new Set();   // job.cancel for an id not known (yet): a job.assign that arrives later for it is not run (orphan of a lost/late assign)
+    let running = 0;
+    let reserved = 0;
+    let closed = false;
+    let theRunner = runner && validateRunner(runner) ? runner : null;
+    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,
+        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)); };
+
+    function release(rec) {
+        reserved = Math.max(0, reserved - rec.reservedBytes);
+        rec.reservedBytes = 0;
+        for (const t of [rec.deadlineTimer, rec.graceTimer]) if (t) clearTimeout(t);
+        rec.deadlineTimer = rec.graceTimer = null;
+        active.delete(rec.jobId);
+        recent.add(rec.jobId);
+        while (recent.size > config.recentJobs) recent.delete(recent.values().next().value);
+        rec.job = null;   // the inline inputs (transit content) are not kept a moment longer than the job
+    }
+
+    function startNext() {
+        while (!closed && running < config.maxConcurrent && queue.length) { const rec = queue.shift(); rec.holdsSlot = true; running++; start(rec); }
+    }
+
+    function abort(rec, reason) {
+        if (rec.abortReason) return;
+        rec.abortReason = reason;
+        try { rec.ac.abort(); } catch { /* already aborted */ }
+        try { Promise.resolve(theRunner.cancel(rec.jobId)).catch(() => {}); } catch { /* a runner's cancel never breaks the supervisor */ }
+        if (!rec.graceTimer && rec.state === "running") {
+            rec.graceTimer = setTimeout(() => { if (!rec.finished) { stats.abandoned++; note("job_runner_abandoned", { jobShort: rec.short, reason }); finish(rec, null, null); } }, config.cancelGraceMs);
+            if (rec.graceTimer.unref) rec.graceTimer.unref();
+        }
+    }
+
+    /** The one place a job ends. `outcome`: what the runner returned (null if it threw or was abandoned); `err`: what it threw. */
+    async function finish(rec, outcome, err) {
+        if (rec.finished) return;
+        rec.finished = true;
+        try { rec.ac.abort(); } catch { /* already aborted */ }   // anything the runner left in flight (a read, an LLM call) is released with the job
+        const holdsSlot = rec.holdsSlot;
+        let state;
+        let errorCode;
+        let result;
+        if (rec.abortReason === "cancelled") { state = "cancelled"; errorCode = "cancelled"; result = "cancelled"; }
+        else if (rec.abortReason === "timeout") { state = "failed"; errorCode = "timeout"; result = "failed"; }
+        else if (rec.abortReason === "budget_exceeded") { state = "failed"; errorCode = "budget_exceeded"; result = "failed"; }
+        else if (err) { state = "failed"; errorCode = jobErrorCodeOf(err); result = "failed"; }
+        else if (outcome && outcome.outcome === "failed") { state = "failed"; errorCode = JOB_ERROR_CODES.includes(outcome.errorCode) && outcome.errorCode !== "none" ? outcome.errorCode : "unknown"; result = "failed"; }
+        else if (outcome && outcome.outcome === "cancelled") { state = "cancelled"; errorCode = "cancelled"; result = "cancelled"; }
+        else if (outcome && (outcome.outcome === "pr_opened" || outcome.outcome === "no_change")) { state = "succeeded"; errorCode = "none"; result = outcome.outcome; }
+        else { state = "failed"; errorCode = "unknown"; result = "failed"; }
+        rec.state = state;
+        if (state === "succeeded") rec.phase = "done";
+        if (holdsSlot) running--;
+        const snap = snapshot(rec, { state, errorCode });
+        stats.finished[state]++;
+        note("job_finished", { jobShort: rec.short, kind: rec.kind, state, errorCode, tokensIn: rec.tokensIn, tokensOut: rec.tokensOut, ms: snap.durationMs, answerBytes: outcome && typeof outcome.answer === "string" ? utf8.encode(outcome.answer).length : 0 });
+        if (onResult && outcome) { try { onResult({ jobId: rec.jobId, kind: rec.kind, state, outcome: result, errorCode, answer: typeof outcome.answer === "string" ? outcome.answer : undefined }); } catch { /* a consumer's bug never breaks the supervisor */ } }
+        const resultFrame = resultPayload(rec.jobId, result, state === "succeeded" || result === "pr_opened" ? outcome || {} : {});
+        const workspaceId = rec.workspaceId;
+        release(rec);
+        startNext();   // the slot is free as soon as the job is over, not when its last frame is acked
+        await ev.terminal({ ev: rec.ev, workspaceId, short: rec.short }, snap, resultFrame);
+    }
+
+    /** The slot (`running`, `holdsSlot`) is taken by the caller at admission time, so a burst of job.assign can never exceed maxConcurrent. */
+    function start(rec) {
+        rec.state = "running";
+        rec.startedAt = now();
+        rec.phase = "init";
+        note("job_started", { jobShort: rec.short, kind: rec.kind });
+        publish(rec);
+        const secondsMs = rec.budget.seconds * 1000;
+        rec.deadlineTimer = setTimeout(() => abort(rec, "timeout"), secondsMs);
+        if (rec.deadlineTimer.unref) rec.deadlineTimer.unref();
+        // F3-09/F3-10: a runner that thinks needs the key the job names; a mismatch is a failure of the job, not of the channel
+        if (theRunner.needsLlm !== false) {
+            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; }
+        }
+        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;
+                },
+            }),
+            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
+                // in flight returns is dropped, not counted and not handed to the runner
+                if (rec.abortReason || rec.finished) return { ok: false, status: "cancelled" };
+                if (!readFile) return { ok: false, status: "forbidden" };
+                const r = await readFile({ workspaceId: rec.workspaceId, ref, maxBytes: opts.maxBytes, signal: rec.ac.signal });
+                if (rec.abortReason || rec.finished) return { ok: false, status: "cancelled" };
+                if (r && r.ok) { rec.filesRead++; publish(rec); }
+                return r;
+            },
+            progress(p = {}) {
+                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];
+                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(
+            (outcome) => finish(rec, outcome && typeof outcome === "object" ? outcome : null, null),
+            (err) => finish(rec, null, err || new Error("runner")),
+        ).catch(() => {});
+    }
+
+    return {
+        stats, audit: auditor, events: ev,
+        get runner() { return theRunner; },
+        get activeCount() { return active.size; },
+        get running() { return running; },
+        get reservedBytes() { return reserved; },
+        /** F3-08c: the packaged agent loop replaces the runner (jobs already running keep the one they started with only as far as their own cancel). */
+        setRunner(r) { if (!validateRunner(r)) throw new Error("not a runner"); theRunner = r; },
+
+        handleAssign(ctx) {
+            stats.received++;
+            const p = ctx.params;
+            const base = { jobShort: short(p?.jobId), kind: p?.kind };
+            if (closed || !theRunner) return reject(base, "protocol_unsupported");
+            // F3-07b rule, per request: a job reads client files and feeds them to the LLM; never without the DLP in enforce
+            if (dlpConfigFromEnv(env).mode !== "enforce") return reject(base, "protocol_unsupported");
+            if (theRunner.kinds && !theRunner.kinds.includes(p.kind)) return reject(base, "protocol_unsupported");
+            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");
+            // 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"); }
+            if (p.options !== undefined && theRunner.supportsOptions !== true) { stats.optionsUnsupported++; return reject({ ...base, options: opts.present }, "protocol_unsupported"); }
+            let inlineBytes = 0;
+            for (const i of p.inputs || []) if (typeof i.inline === "string") inlineBytes += utf8.encode(i.inline).length;
+            const need = inlineBytes + config.memPerJobBytes;
+            if (reserved + need > config.maxMemoryBytes) return reject(base, "rate_limited");
+            if (config.maxRssBytes > 0 && memoryUsage() > config.maxRssBytes) return reject(base, "rate_limited");
+            const slotFree = running < config.maxConcurrent;
+            if (!slotFree && queue.length >= config.maxQueued) return reject(base, "rate_limited");
+
+            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,
+                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 }),
+            };
+            reserved += need;
+            active.set(rec.jobId, rec);
+            stats.accepted++;
+            note("job_accepted", { ...base, workspaceShort: short(ctx.workspaceId), budgetClamped: budget.tokens !== p.budget.tokens || budget.seconds !== p.budget.seconds, queued: !slotFree, inlineBytes,
+                options: opts.present, dryRun: opts.options.dryRun });
+            if (slotFree) { rec.holdsSlot = true; running++; setImmediate(() => { if (!closed && !rec.finished && rec.state === "queued") start(rec); }); }   // starts after the ack; the slot is ours from now on
+            else { stats.queued++; queue.push(rec); publish(rec); }
+            return { accept: true };
+        },
+
+        handleCancel(ctx) {
+            const p = ctx.params;
+            // a job id that is not a UUID is not a job of this contract: a clear refusal, no lookup, no state touched, nothing echoed (not even in the audit)
+            if (!p || typeof p.jobId !== "string" || !UUID.test(p.jobId)) { stats.cancelInvalid++; note("job_cancel_invalid", {}); return reject({}, "schema_violation"); }
+            const rec = active.get(p.jobId);
+            stats.cancels++;
+            note("job_cancel", { jobShort: short(p.jobId), known: !!rec, reason: p.reason });
+            if (!rec) {
+                // unknown or already finished: idempotent, never tells which. An id never seen is remembered (bounded) so an assign that arrives late is not run.
+                if (!recent.has(p.jobId) && !closed) { cancelledEarly.add(p.jobId); while (cancelledEarly.size > EARLY_CANCELS) cancelledEarly.delete(cancelledEarly.values().next().value); }
+                return { accept: true };
+            }
+            if (rec.state === "queued") {
+                const i = queue.indexOf(rec);
+                if (i >= 0) queue.splice(i, 1);
+                rec.abortReason = "cancelled";
+                finish(rec, null, null);
+            } else abort(rec, "cancelled");
+            return { accept: true };
+        },
+
+        /** Link close / process shutdown: every job is aborted, nothing more is sent. */
+        cancelAll() {
+            closed = true;
+            queue.length = 0;
+            for (const rec of [...active.values()]) { rec.finished = true; rec.abortReason ||= "cancelled"; try { rec.ac.abort(); } catch { /* done */ } try { Promise.resolve(theRunner?.cancel(rec.jobId)).catch(() => {}); } catch { /* done */ } release(rec); }
+            running = 0;
+            ev.close();
+        },
+    };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * options.js - `job.assign.payload.options` (contract 2.1, capability `job.options`, F3-10): how to run a job.
+ *
+ * The session has already validated the frame against the closed schema; this module validates AGAIN (the manager is also called without a session in
+ * tests and by future code) and turns the optional object into the one shape every runner reads as `job.options`: frozen, every field present.
+ *
+ *   absent / not given   the agent's own defaults: createBranch true, createPullRequest true, dryRun false, maxIterations = the local ceiling
+ *   maxIterations        CLAMPED to LOCAL_AGENT_JOBS_MAX_ITERATIONS: an option never widens what the agent allows itself
+ *   effects              what a runner may DO to the outside world, derived conservatively (a missing effect is never a surprise, an extra one is):
+ *                        dryRun -> no branch, no push, no pull request; createBranch false -> work on repoRef.branch, never push to it, no pull request;
+ *                        createPullRequest false -> no pull request
+ *
+ * A runner that does not declare `supportsOptions: true` is never given options (the manager refuses the job, see manager.js): dryRun and
+ * createPullRequest:false must never be ignored silently. Nothing here is content (an id, a ref name, flags, a counter); still nothing of it is
+ * written to a log: the audit records only which keys were present.
+ */
+export const OPTION_KEYS = Object.freeze(["ticketKey", "branchName", "createBranch", "createPullRequest", "dryRun", "maxIterations"]);
+export const JOB_OPTIONS_CAPABILITY = "job.options";
+
+const SHORT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+// the same expression as the contract (job.assign.schema.json options.branchName): no "..", no "//", no component starting with ".", no trailing "." or "/", no ".lock" suffix
+const BRANCH = /^(?!.*\.\.)(?!.*\/\/)(?!.*\/\.)(?!.*[./]$)(?!.*\.lock(\/|$))[A-Za-z0-9_][A-Za-z0-9_./-]{0,254}$/;
+
+/**
+ * @param {unknown} raw  the payload's `options` (undefined when absent)
+ * @param {{maxIterations:number}} config  the local ceilings
+ * @returns {{ok:true, options:object, present:string[]} | {ok:false}}  `ok:false` = malformed (the caller answers `schema_violation`, nothing runs)
+ */
+export function normalizeJobOptions(raw, config) {
+    const ceiling = Number.isSafeInteger(config?.maxIterations) && config.maxIterations >= 1 ? config.maxIterations : 25;
+    if (raw !== undefined && (raw === null || typeof raw !== "object" || Array.isArray(raw))) return { ok: false };
+    const o = raw || {};
+    const keys = Object.keys(o);
+    if (keys.length === 0 && raw !== undefined) return { ok: false };                           // minProperties 1
+    if (keys.some((k) => !OPTION_KEYS.includes(k))) return { ok: false };                        // closed
+    for (const k of ["createBranch", "createPullRequest", "dryRun"]) if (o[k] !== undefined && typeof o[k] !== "boolean") return { ok: false };
+    if (o.ticketKey !== undefined && !(typeof o.ticketKey === "string" && SHORT_ID.test(o.ticketKey))) return { ok: false };
+    if (o.branchName !== undefined && !(typeof o.branchName === "string" && BRANCH.test(o.branchName))) return { ok: false };
+    if (o.maxIterations !== undefined && !(Number.isSafeInteger(o.maxIterations) && o.maxIterations >= 1 && o.maxIterations <= 100)) return { ok: false };
+
+    const createBranch = o.createBranch !== false;
+    const createPullRequest = o.createPullRequest !== false;
+    const dryRun = o.dryRun === true;
+    const maxIterations = Math.min(o.maxIterations ?? ceiling, ceiling);
+    const effects = Object.freeze({
+        createBranch: !dryRun && createBranch,
+        push: !dryRun && createBranch,
+        openPullRequest: !dryRun && createBranch && createPullRequest,
+    });
+    const options = Object.freeze({
+        ...(o.ticketKey !== undefined ? { ticketKey: o.ticketKey } : {}),
+        ...(o.branchName !== undefined ? { branchName: o.branchName } : {}),
+        createBranch, createPullRequest, dryRun, maxIterations, effects,
+    });
+    return { ok: true, options, present: keys.sort() };
+}

package/src/la-protocol-v2/jobs/smoke-runner.js

@@ -0,0 +1,39 @@
+/**
+ * smoke-runner.js - the REFERENCE runner of F3-10: proves the whole path (job.assign -> runner -> LLM client -> job.event/job.result) with the smallest
+ * possible job. It reads ONE allowed file of the job's workspace (the first `inputs[].ref`, an opaque id this agent minted, resolved by the content
+ * handlers' registry and path guard: deny list, symlinks, root), asks the AI gateway one FIXED question about it and returns the answer to the LOCAL
+ * `onResult` hook. It changes nothing (outcome `no_change`), opens no PR, touches no Git. It is not an agent loop: that is F3-08c.
+ * Selected with LOCAL_AGENT_JOBS_RUNNER=smoke; meant for QA and for tests, not for production traffic.
+ */
+export const SMOKE_QUESTION = "In at most three sentences, say what the file below is for.";
+export const SMOKE_SYSTEM = "You are a careful code reader. Answer briefly and only about the file you are given.";
+
+/**
+ * Options (contract 2.1, `job.options`): this runner is the REFERENCE of how a runner reads them. It supports them trivially and visibly: it never
+ * creates a branch, pushes or opens a pull request, so `dryRun`, `createBranch` and `createPullRequest` cannot make it do more; `maxIterations` caps its
+ * (single) iteration, and `effects` (options.js) is what a real runner must check before every outside effect. dryRun still asks the LLM: a dry run
+ * runs the whole loop and only withholds the effects.
+ */
+export function createSmokeRunner({ maxFileBytes = 64 * 1024, maxOutputTokens = 256 } = {}) {
+    return {
+        name: "smoke",
+        kinds: ["fix", "implement", "quality"],
+        needsLlm: true,
+        supportsOptions: true,
+        async start(job, ctx) {
+            const iteration = Math.min(1, job.options?.maxIterations ?? 1);   // one question = one iteration, never above the job's cap (>= 1 by contract)
+            ctx.progress({ phase: "context" });
+            const ref = (job.inputs || []).find((i) => typeof i.ref === "string");
+            if (!ref) return { outcome: "failed", errorCode: "unknown" };
+            const file = await ctx.readFile(ref.ref, { maxBytes: maxFileBytes });
+            if (!file || !file.ok) return { outcome: "failed", errorCode: file && file.status === "forbidden" ? "policy_denied" : "unknown" };
+            ctx.progress({ phase: "plan", iteration });
+            const r = await ctx.llm.chat({
+                messages: [{ role: "system", content: SMOKE_SYSTEM }, { role: "user", content: `${SMOKE_QUESTION}\n\n<file>\n${file.text}\n</file>` }],
+                maxTokens: maxOutputTokens, temperature: 0,
+            });
+            return { outcome: "no_change", answer: r.text };
+        },
+        cancel() { /* the job's signal aborts the LLM call; nothing else is held */ },
+    };
+}