@zeroroot-ai/zerocool 0.3.1 → 0.5.0

package/dist/gitlab.js

@@ -0,0 +1,82 @@
+/**
+ * GitLab — the trigger the always-on agent watches (zerocool-plugins#88).
+ *
+ * The agent polls one project's pipelines on one branch. It never receives a
+ * webhook and GitLab holds no Gibson credential: the poll runs outbound from
+ * the sandbox on the tenant's own project access token, resolved through the
+ * harness `GetCredential` under the dispatch grant. That direction is the point
+ * — a CI job cannot originate a Gibson mission (ADR-0063 admits a component
+ * only from inside a mission it was dispatched to), so the agent watches
+ * GitLab rather than GitLab calling Gibson.
+ *
+ * FINISHED MEANS `success`. A pipeline that failed published no image and left
+ * `main` unchanged, so there is nothing new to scan; treating it as a trigger
+ * would run a Scan mission against the image the previous pipeline built and
+ * report its findings against the new commit. `canceled` and `skipped` are the
+ * same case. The status this polls for is therefore `success`, named once in
+ * {@link TRIGGER_STATUS} rather than spelled at each call site.
+ *
+ * Everything here is one `fetch` away from pure: {@link gitlabRest} takes the
+ * fetch it uses, so `watch.test.ts` drives a whole loop against a stub with no
+ * network and no token.
+ */
+/** The pipeline status that triggers a Scan mission. See the module note. */
+export const TRIGGER_STATUS = "success";
+/** GitLab's public host, when a tenant names no other instance. */
+export const GITLAB_DEFAULT_URL = "https://gitlab.com";
+/**
+ * Read one pipeline out of GitLab's JSON. A row without an id or a sha is
+ * dropped rather than guessed at: a Scan mission keyed on a missing commit
+ * would scan whatever the workspace happened to hold.
+ */
+export function parsePipeline(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const p = raw;
+    const id = typeof p.id === "number" ? p.id : Number.NaN;
+    const sha = typeof p.sha === "string" ? p.sha : "";
+    if (!Number.isInteger(id) || id <= 0 || !sha)
+        return undefined;
+    return {
+        id,
+        sha,
+        status: typeof p.status === "string" ? p.status : "",
+        ref: typeof p.ref === "string" ? p.ref : "",
+        webUrl: typeof p.web_url === "string" ? p.web_url : "",
+    };
+}
+/**
+ * A {@link GitLabClient} over GitLab's REST API.
+ *
+ * The token travels in `PRIVATE-TOKEN`, which is what a project access token
+ * authenticates with. It is never logged and never placed in a URL, so it
+ * cannot reach the console stream through an error message that quotes the
+ * request.
+ */
+export function gitlabRest(opts) {
+    const base = (opts.baseUrl || GITLAB_DEFAULT_URL).replace(/\/+$/, "");
+    const project = encodeURIComponent(opts.projectPath);
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    return {
+        async latestFinishedPipeline(ref) {
+            const url = `${base}/api/v4/projects/${project}/pipelines` +
+                `?ref=${encodeURIComponent(ref)}&status=${TRIGGER_STATUS}&order_by=id&sort=desc&per_page=1`;
+            const res = await doFetch(url, {
+                headers: { "PRIVATE-TOKEN": opts.token, Accept: "application/json" },
+            });
+            if (!res.ok) {
+                throw new Error(`GitLab pipelines for ${opts.projectPath}@${ref} returned ${res.status} ${res.statusText}`);
+            }
+            const body = await res.json();
+            if (!Array.isArray(body)) {
+                throw new Error(`GitLab pipelines for ${opts.projectPath}@${ref} returned ${typeof body}, expected an array`);
+            }
+            for (const row of body) {
+                const p = parsePipeline(row);
+                if (p)
+                    return p;
+            }
+            return undefined;
+        },
+    };
+}

package/dist/knowledge-source.js

@@ -1,4 +1,4 @@
-import { componentKnowledge, connectTaskHarness, taskKnowledge, } from "@zeroroot-ai/sdk";
+import { componentKnowledge, openTaskHarness, taskKnowledge, } from "@zeroroot-ai/sdk";
 /**
  * Pick the grant this process should read the knowledge graph with.
  *
@@ -27,7 +27,7 @@ export function selectKnowledgeSource(session) {
             "widen this run's authority.");
     }
     return {
-        knowledge: taskKnowledge(connectTaskHarness({
+        knowledge: taskKnowledge(openTaskHarness({
             endpoint,
             token,
             // A local or kind daemon may serve the callback listener without TLS.

package/dist/semgrep.d.ts

@@ -0,0 +1,76 @@
+/**
+ * semgrep — the candidate producer for the source-analysis task
+ * (zerocool-plugins#87).
+ *
+ * semgrep runs the vendored ruleset (`semgrep/rules.yaml`, pinned with the
+ * package, never fetched) over a checkout and prints one JSON document. The
+ * parser below is pure and is tested against bytes recorded from semgrep
+ * 1.175.0 over the fixture repository, so a change in semgrep's output fails a
+ * unit test rather than a Scan mission.
+ *
+ * A match is a CANDIDATE, not a Finding. The model triages each one in
+ * `source-analysis.ts`; nothing here decides.
+ */
+/** One semgrep match, reduced to what triage and a Finding need. */
+export interface SemgrepCandidate {
+    /** The rule id, e.g. `rules.js-eval-of-request-input`. */
+    checkId: string;
+    /** Repository-relative path, as semgrep printed it. */
+    path: string;
+    line: number;
+    endLine: number;
+    message: string;
+    /** semgrep's own level: ERROR, WARNING or INFO. */
+    severity: string;
+    /** CWE strings from the rule's metadata, verbatim (`CWE-79: ...`). */
+    cwe: string[];
+    /** The rule's `metadata.category`, when it set one. */
+    category?: string;
+    /** The matched source lines. */
+    snippet: string;
+}
+/**
+ * Parse the JSON `semgrep scan --json` writes. Throws when the document is not
+ * JSON or carries an error semgrep itself marked as an error, because a partial
+ * candidate list would look like a clean checkout.
+ */
+export declare function parseSemgrepOutput(stdout: string): SemgrepCandidate[];
+/**
+ * semgrep prefixes a local rule's id with the config file's path, dot-joined
+ * (`app.semgrep.js-eval-any` in the image, `rules.js-eval-any` from a relative
+ * config). The rule is the last segment; the prefix is where the file sat. A
+ * Finding must name the rule, not the install path, so the prefix is dropped.
+ */
+export declare function bareRuleId(checkId: string): string;
+/** The vendored ruleset, resolved from the package it ships with. */
+export declare function defaultRulesPath(): string;
+export interface SemgrepRunOptions {
+    /** The checkout to scan. semgrep runs with this as its cwd and `.` as the target. */
+    dir: string;
+    /** Ruleset path. Defaults to the vendored one. */
+    rules?: string;
+    /** Binary to run. Overridable for a pinned install and for tests. */
+    bin?: string;
+    /** Hard deadline. The child is killed when it elapses. */
+    timeoutMs?: number;
+}
+/**
+ * Build the argv. Exported so a test can assert it.
+ *
+ * The target is `.` and the cwd is the checkout, on purpose: semgrep reports
+ * paths relative to the target, so a Finding's `file` is repository-relative
+ * rather than a sandbox path, and semgrep's default ignore list (which skips
+ * `test/` directories anywhere in the path) is judged against the checkout,
+ * not against wherever the sandbox mounted it.
+ */
+export declare function semgrepArgs(opts: SemgrepRunOptions): string[];
+/** A function that yields candidates for a checkout. The seam tests stub. */
+export type SemgrepRunner = (opts: SemgrepRunOptions) => Promise<SemgrepCandidate[]>;
+/**
+ * Run semgrep once over a checkout and return the candidates.
+ *
+ * semgrep exits 0 when the scan ran, with or without matches; anything else is
+ * a failed scan and throws with semgrep's stderr tail, so a task never reports
+ * "no findings" for a scan that did not happen.
+ */
+export declare const runSemgrep: SemgrepRunner;

package/dist/semgrep.js

@@ -0,0 +1,111 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+/**
+ * Parse the JSON `semgrep scan --json` writes. Throws when the document is not
+ * JSON or carries an error semgrep itself marked as an error, because a partial
+ * candidate list would look like a clean checkout.
+ */
+export function parseSemgrepOutput(stdout) {
+    let doc;
+    try {
+        doc = JSON.parse(stdout);
+    }
+    catch (e) {
+        throw new Error(`semgrep output is not JSON: ${e.message}`);
+    }
+    const fatal = (doc.errors ?? []).filter((err) => (err.level ?? "error") === "error");
+    if (fatal.length > 0) {
+        throw new Error(`semgrep reported ${fatal.length} error(s): ${fatal.map((err) => err.message ?? "?").join("; ")}`);
+    }
+    return (doc.results ?? []).map((r) => {
+        const cweRaw = r.extra?.metadata?.cwe;
+        const cwe = Array.isArray(cweRaw) ? cweRaw : cweRaw ? [cweRaw] : [];
+        return {
+            checkId: bareRuleId(r.check_id ?? ""),
+            path: r.path ?? "",
+            line: r.start?.line ?? 0,
+            endLine: r.end?.line ?? r.start?.line ?? 0,
+            message: (r.extra?.message ?? "").trim(),
+            severity: r.extra?.severity ?? "",
+            cwe,
+            ...(r.extra?.metadata?.category ? { category: r.extra.metadata.category } : {}),
+            snippet: r.extra?.lines ?? "",
+        };
+    });
+}
+/**
+ * semgrep prefixes a local rule's id with the config file's path, dot-joined
+ * (`app.semgrep.js-eval-any` in the image, `rules.js-eval-any` from a relative
+ * config). The rule is the last segment; the prefix is where the file sat. A
+ * Finding must name the rule, not the install path, so the prefix is dropped.
+ */
+export function bareRuleId(checkId) {
+    const i = checkId.lastIndexOf(".");
+    return i >= 0 ? checkId.slice(i + 1) : checkId;
+}
+/** The vendored ruleset, resolved from the package it ships with. */
+export function defaultRulesPath() {
+    return fileURLToPath(new URL("../semgrep/rules.yaml", import.meta.url));
+}
+/**
+ * Build the argv. Exported so a test can assert it.
+ *
+ * The target is `.` and the cwd is the checkout, on purpose: semgrep reports
+ * paths relative to the target, so a Finding's `file` is repository-relative
+ * rather than a sandbox path, and semgrep's default ignore list (which skips
+ * `test/` directories anywhere in the path) is judged against the checkout,
+ * not against wherever the sandbox mounted it.
+ */
+export function semgrepArgs(opts) {
+    return [
+        "scan",
+        "--json",
+        "--quiet",
+        "--metrics=off",
+        "--disable-version-check",
+        "--config",
+        opts.rules ?? defaultRulesPath(),
+        ".",
+    ];
+}
+/**
+ * Run semgrep once over a checkout and return the candidates.
+ *
+ * semgrep exits 0 when the scan ran, with or without matches; anything else is
+ * a failed scan and throws with semgrep's stderr tail, so a task never reports
+ * "no findings" for a scan that did not happen.
+ */
+export const runSemgrep = async (opts) => {
+    const bin = opts.bin ?? process.env.ZEROCOOL_SEMGREP_BIN ?? "semgrep";
+    const args = semgrepArgs(opts);
+    return await new Promise((resolve, reject) => {
+        const child = spawn(bin, args, {
+            cwd: opts.dir,
+            env: { ...process.env, SEMGREP_SEND_METRICS: "off", SEMGREP_ENABLE_VERSION_CHECK: "0" },
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(opts.timeoutMs && opts.timeoutMs > 0 ? { timeout: opts.timeoutMs, killSignal: "SIGTERM" } : {}),
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (e) => reject(new Error(`could not run ${bin}: ${e.message}`)));
+        child.on("close", (code, signal) => {
+            if (signal) {
+                reject(new Error(`semgrep timed out after ${opts.timeoutMs}ms (killed with ${signal})`));
+                return;
+            }
+            if (code !== 0) {
+                const tail = stderr.trim().split("\n").slice(-5).join("; ");
+                reject(new Error(`semgrep exited ${code}${tail ? `: ${tail}` : ""}`));
+                return;
+            }
+            try {
+                resolve(parseSemgrepOutput(stdout));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    });
+};

package/dist/source-analysis.d.ts

@@ -0,0 +1,134 @@
+import { type Finding, type Severity, type TaskHarness } from "@zeroroot-ai/sdk";
+import type { FindingsBackend } from "./findings.js";
+import { type SemgrepCandidate, type SemgrepRunner } from "./semgrep.js";
+/**
+ * The source-analysis task (zerocool-plugins#87).
+ *
+ * semgrep produces candidates from a checkout; the model triages each one as
+ * real or noise; every real one is submitted as a Finding that names its
+ * Vulnerability (a CWE, or a platform id when the rule carries none), the file
+ * and line, and the model's reason. The task reads the checkout and writes
+ * Findings. It changes no file and pushes nothing — that is the Fix's job
+ * (zerocool-plugins#89), a different task with a different grant posture.
+ *
+ * Deterministic first, model second. semgrep decides what is a candidate; the
+ * model only decides whether a candidate is real, given the rule's message and
+ * the code around the match. A rule that never yields a real finding is
+ * removed from the ruleset rather than argued with in a prompt.
+ *
+ * Every seam is injectable — the semgrep runner, the model, the findings
+ * backend, the file reader — so the test in `source-analysis.test.ts` drives a
+ * whole pass over the fixture repository with no semgrep binary, no network,
+ * and no daemon.
+ */
+/** What the model said about one candidate. */
+export interface Triage {
+    verdict: "real" | "noise";
+    reason: string;
+}
+/** The model seam: one candidate in, one verdict out. */
+export type TriageModel = (c: AnalysisCandidate, snippet: string) => Promise<Triage>;
+/** A deduplicated candidate: one place, one Vulnerability, the rules that hit it. */
+export interface AnalysisCandidate extends SemgrepCandidate {
+    /** `CWE-95`, or `zerocool:semgrep:<rule>` when the rule names no CWE. */
+    vulnerabilityId: string;
+    /** Every rule that matched this place for this Vulnerability. */
+    ruleIds: string[];
+}
+/**
+ * The Vulnerability id for a candidate. A CWE from the rule's metadata wins,
+ * normalized to `CWE-<n>` so the same weakness from two rules is one node in
+ * the graph. A rule with no CWE gets a platform id keyed by the rule, which is
+ * still stable across runs and repositories.
+ */
+export declare function vulnerabilityId(c: SemgrepCandidate): string;
+/**
+ * Collapse matches to one candidate per (path, line, Vulnerability). Two rules
+ * that flag the same eval on the same line are one weakness, and two Findings
+ * for it would be one duplicate for a person to close. The strongest rule's
+ * level and message are kept; every rule id is recorded.
+ */
+export declare function dedupeCandidates(matches: SemgrepCandidate[]): AnalysisCandidate[];
+/** Lines around a match, numbered, for the model and for the Finding's evidence. */
+export declare function readSnippet(dir: string, c: SemgrepCandidate, read?: (path: string) => Promise<string>, context?: number): Promise<string>;
+/**
+ * The triage prompt. The model gets the rule's message, the weakness, and the
+ * code; it answers with one JSON object. Exported so the wording is testable
+ * and so a reader can see exactly what the model is asked.
+ */
+export declare function triageMessages(c: AnalysisCandidate, snippet: string): {
+    role: string;
+    content: string;
+}[];
+/**
+ * Parse the model's answer. Tolerant of prose around the object, strict about
+ * the verdict: anything but a clear "real" is noise, because a Finding the
+ * model did not clearly confirm is exactly the noise this task exists to drop.
+ */
+export declare function parseTriage(text: string): Triage;
+/**
+ * The model behind the task grant: one `LLMComplete` on the harness per
+ * candidate, on the tenant's own provider, through the harness so the call is
+ * traced and budgeted like every other model call the run makes.
+ */
+export declare function harnessTriageModel(harness: TaskHarness, slot?: string): TriageModel;
+/** semgrep's level mapped onto the Finding severity scale. */
+export declare function findingSeverity(level: string): Severity;
+/** What the Finding needs to say where it came from. */
+export interface AnalysisProvenance {
+    missionId?: string;
+    /** `https://gitlab.com/examplebank/customer-portal`, when the task knows it. */
+    repository?: string;
+    commit?: string;
+    targetId?: string;
+}
+/**
+ * Build the Finding for a real candidate. The Vulnerability id, the file and
+ * the line travel in the title, the tags and the evidence, so they survive the
+ * typed `SubmitFinding` mapping, which carries no free-form metadata.
+ */
+export declare function candidateFinding(c: AnalysisCandidate, triage: Triage, snippet: string, prov: AnalysisProvenance): Finding;
+export interface SourceAnalysisOptions {
+    /** The checkout to analyze. */
+    dir: string;
+    model: TriageModel;
+    findings: FindingsBackend;
+    provenance?: AnalysisProvenance;
+    /** Seams. */
+    semgrep?: SemgrepRunner;
+    readFile?: (path: string) => Promise<string>;
+    rules?: string;
+    semgrepTimeoutMs?: number;
+    /** Progress events, one object per step, for the console stream. */
+    onEvent?: (event: Record<string, unknown>) => void;
+}
+/** What one pass produced. */
+export interface SourceAnalysisSummary {
+    matches: number;
+    candidates: number;
+    real: number;
+    noise: number;
+    /** Ids of the Findings submitted, in order. */
+    findingIds: string[];
+    /** Candidates the model or the backend failed on, with the error. Never silent. */
+    failed: {
+        candidate: string;
+        error: string;
+    }[];
+    /** Every verdict, for the terminal result and the MR note. */
+    verdicts: {
+        candidate: string;
+        vulnerabilityId: string;
+        verdict: Triage["verdict"];
+        reason: string;
+    }[];
+}
+/**
+ * One pass: scan, dedupe, triage, submit. A candidate the model or the backend
+ * fails on is recorded in `failed` and the pass continues, so one bad answer
+ * costs one candidate rather than the whole scan. The pass never throws for a
+ * clean checkout; it throws only when semgrep itself could not run.
+ */
+export declare function runSourceAnalysis(opts: SourceAnalysisOptions): Promise<SourceAnalysisSummary>;
+/** The human-readable result the mission node records. */
+export declare function formatSourceAnalysis(s: SourceAnalysisSummary): string;

package/dist/source-analysis.js

@@ -0,0 +1,251 @@
+import { newFinding } from "@zeroroot-ai/sdk";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runSemgrep } from "./semgrep.js";
+/** semgrep's level, ranked so the strongest rule wins a deduplicated place. */
+const LEVEL_RANK = { ERROR: 3, WARNING: 2, INFO: 1 };
+/**
+ * The Vulnerability id for a candidate. A CWE from the rule's metadata wins,
+ * normalized to `CWE-<n>` so the same weakness from two rules is one node in
+ * the graph. A rule with no CWE gets a platform id keyed by the rule, which is
+ * still stable across runs and repositories.
+ */
+export function vulnerabilityId(c) {
+    for (const raw of c.cwe) {
+        const m = /CWE-(\d+)/i.exec(raw);
+        if (m)
+            return `CWE-${m[1]}`;
+    }
+    return `zerocool:semgrep:${c.checkId}`;
+}
+/**
+ * Collapse matches to one candidate per (path, line, Vulnerability). Two rules
+ * that flag the same eval on the same line are one weakness, and two Findings
+ * for it would be one duplicate for a person to close. The strongest rule's
+ * level and message are kept; every rule id is recorded.
+ */
+export function dedupeCandidates(matches) {
+    const byKey = new Map();
+    for (const m of matches) {
+        const id = vulnerabilityId(m);
+        const key = `${m.path}:${m.line}:${id}`;
+        const seen = byKey.get(key);
+        if (!seen) {
+            byKey.set(key, { ...m, vulnerabilityId: id, ruleIds: [m.checkId] });
+            continue;
+        }
+        if (!seen.ruleIds.includes(m.checkId))
+            seen.ruleIds.push(m.checkId);
+        if ((LEVEL_RANK[m.severity] ?? 0) > (LEVEL_RANK[seen.severity] ?? 0)) {
+            seen.severity = m.severity;
+            seen.message = m.message;
+            seen.checkId = m.checkId;
+            seen.endLine = Math.max(seen.endLine, m.endLine);
+        }
+    }
+    return [...byKey.values()].sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line);
+}
+/** Lines around a match, numbered, for the model and for the Finding's evidence. */
+export async function readSnippet(dir, c, read = (p) => readFile(p, "utf8"), context = 4) {
+    let text;
+    try {
+        text = await read(join(dir, c.path));
+    }
+    catch {
+        return "";
+    }
+    const lines = text.split("\n");
+    const from = Math.max(1, c.line - context);
+    const to = Math.min(lines.length, c.endLine + context);
+    const out = [];
+    for (let n = from; n <= to; n++) {
+        const mark = n >= c.line && n <= c.endLine ? ">" : " ";
+        out.push(`${mark} ${String(n).padStart(4)} | ${lines[n - 1] ?? ""}`);
+    }
+    return out.join("\n");
+}
+/**
+ * The triage prompt. The model gets the rule's message, the weakness, and the
+ * code; it answers with one JSON object. Exported so the wording is testable
+ * and so a reader can see exactly what the model is asked.
+ */
+export function triageMessages(c, snippet) {
+    return [
+        {
+            role: "system",
+            content: "You triage static-analysis matches in application source code. For the match below, " +
+                "decide whether it is a real weakness an attacker or a caller could exploit, or noise " +
+                "(a constant, dead code, a test, a value no caller can influence). Answer with exactly " +
+                'one JSON object and nothing else: {"verdict":"real"|"noise","reason":"<one sentence>"}.',
+        },
+        {
+            role: "user",
+            content: `Rule: ${c.ruleIds.join(", ")}\n` +
+                `Weakness: ${c.vulnerabilityId}\n` +
+                `Rule message: ${c.message}\n` +
+                `File: ${c.path} lines ${c.line}-${c.endLine}\n\n` +
+                `${snippet || "(source not available)"}`,
+        },
+    ];
+}
+/**
+ * Parse the model's answer. Tolerant of prose around the object, strict about
+ * the verdict: anything but a clear "real" is noise, because a Finding the
+ * model did not clearly confirm is exactly the noise this task exists to drop.
+ */
+export function parseTriage(text) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (m) {
+        try {
+            const obj = JSON.parse(m[0]);
+            const verdict = String(obj.verdict ?? "").toLowerCase() === "real" ? "real" : "noise";
+            const reason = typeof obj.reason === "string" && obj.reason.trim() ? obj.reason.trim() : "no reason given";
+            return { verdict, reason };
+        }
+        catch {
+            // fall through
+        }
+    }
+    return { verdict: "noise", reason: `model answer was not the expected JSON: ${text.slice(0, 120)}` };
+}
+/**
+ * The model behind the task grant: one `LLMComplete` on the harness per
+ * candidate, on the tenant's own provider, through the harness so the call is
+ * traced and budgeted like every other model call the run makes.
+ */
+export function harnessTriageModel(harness, slot = "primary") {
+    return async (c, snippet) => {
+        const res = await harness.client.lLMComplete({
+            context: harness.context,
+            slot,
+            messages: triageMessages(c, snippet).map((m) => ({ role: m.role, content: m.content })),
+            temperature: 0,
+            stop: [],
+        });
+        if (res.error)
+            throw new Error(`LLMComplete refused: ${res.error.message}`);
+        return parseTriage(res.content);
+    };
+}
+/** semgrep's level mapped onto the Finding severity scale. */
+export function findingSeverity(level) {
+    if (level === "ERROR")
+        return "high";
+    if (level === "WARNING")
+        return "medium";
+    return "low";
+}
+/**
+ * Build the Finding for a real candidate. The Vulnerability id, the file and
+ * the line travel in the title, the tags and the evidence, so they survive the
+ * typed `SubmitFinding` mapping, which carries no free-form metadata.
+ */
+export function candidateFinding(c, triage, snippet, prov) {
+    const where = `${c.path}:${c.line}`;
+    return newFinding({
+        title: `${c.vulnerabilityId} at ${where}: ${c.message.split(".")[0] ?? c.message}`.slice(0, 200),
+        description: `${c.message}\n\n` +
+            `Vulnerability: ${c.vulnerabilityId}\n` +
+            `File: ${c.path}\nLines: ${c.line}-${c.endLine}\n` +
+            `Rules: ${c.ruleIds.join(", ")}\n` +
+            (prov.repository ? `Repository: ${prov.repository}${prov.commit ? ` @ ${prov.commit}` : ""}\n` : "") +
+            `\nTriage: ${triage.reason}`,
+        category: c.category ?? "source",
+        severity: findingSeverity(c.severity),
+        confidence: 0.8,
+        missionID: prov.missionId ?? "",
+        agentName: "zerocool",
+        ...(prov.targetId ? { targetID: prov.targetId } : {}),
+        tags: [
+            "source-analysis",
+            `vulnerability:${c.vulnerabilityId}`,
+            `file:${c.path}`,
+            `line:${c.line}`,
+            ...c.ruleIds.map((r) => `semgrep:${r}`),
+            ...(prov.commit ? [`commit:${prov.commit}`] : []),
+        ],
+        evidence: [
+            {
+                type: "code",
+                title: where,
+                content: snippet || "(source not available)",
+                timestamp: new Date().toISOString(),
+                metadata: { path: c.path, line: c.line, end_line: c.endLine, rules: c.ruleIds },
+            },
+        ],
+    });
+}
+/**
+ * One pass: scan, dedupe, triage, submit. A candidate the model or the backend
+ * fails on is recorded in `failed` and the pass continues, so one bad answer
+ * costs one candidate rather than the whole scan. The pass never throws for a
+ * clean checkout; it throws only when semgrep itself could not run.
+ */
+export async function runSourceAnalysis(opts) {
+    const emit = opts.onEvent ?? (() => { });
+    const semgrep = opts.semgrep ?? runSemgrep;
+    emit({ type: "source_analysis", phase: "semgrep", dir: opts.dir });
+    const matches = await semgrep({
+        dir: opts.dir,
+        ...(opts.rules ? { rules: opts.rules } : {}),
+        ...(opts.semgrepTimeoutMs ? { timeoutMs: opts.semgrepTimeoutMs } : {}),
+    });
+    const candidates = dedupeCandidates(matches);
+    emit({ type: "source_analysis", phase: "candidates", matches: matches.length, candidates: candidates.length });
+    const summary = {
+        matches: matches.length,
+        candidates: candidates.length,
+        real: 0,
+        noise: 0,
+        findingIds: [],
+        failed: [],
+        verdicts: [],
+    };
+    for (const c of candidates) {
+        const label = `${c.path}:${c.line} ${c.vulnerabilityId}`;
+        const snippet = await readSnippet(opts.dir, c, opts.readFile);
+        let triage;
+        try {
+            triage = await opts.model(c, snippet);
+        }
+        catch (e) {
+            summary.failed.push({ candidate: label, error: `triage: ${e.message}` });
+            emit({ type: "source_analysis", phase: "triage", candidate: label, error: e.message });
+            continue;
+        }
+        summary.verdicts.push({ candidate: label, vulnerabilityId: c.vulnerabilityId, verdict: triage.verdict, reason: triage.reason });
+        emit({ type: "source_analysis", phase: "triage", candidate: label, verdict: triage.verdict, reason: triage.reason });
+        if (triage.verdict !== "real") {
+            summary.noise += 1;
+            continue;
+        }
+        summary.real += 1;
+        const finding = candidateFinding(c, triage, snippet, opts.provenance ?? {});
+        try {
+            const id = await opts.findings.submit(finding);
+            summary.findingIds.push(id);
+            emit({ type: "source_analysis", phase: "submit", candidate: label, finding_id: id });
+        }
+        catch (e) {
+            summary.failed.push({ candidate: label, error: `submit: ${e.message}` });
+            emit({ type: "source_analysis", phase: "submit", candidate: label, error: e.message });
+        }
+    }
+    emit({ type: "source_analysis", phase: "done", ...summaryCounts(summary) });
+    return summary;
+}
+function summaryCounts(s) {
+    return { matches: s.matches, candidates: s.candidates, real: s.real, noise: s.noise, submitted: s.findingIds.length, failed: s.failed.length };
+}
+/** The human-readable result the mission node records. */
+export function formatSourceAnalysis(s) {
+    const lines = [
+        `source analysis: ${s.matches} semgrep matches, ${s.candidates} candidates, ` +
+            `${s.real} real, ${s.noise} noise, ${s.findingIds.length} findings submitted, ${s.failed.length} failed`,
+    ];
+    for (const v of s.verdicts)
+        lines.push(`- ${v.verdict.padEnd(5)} ${v.candidate}: ${v.reason}`);
+    for (const f of s.failed)
+        lines.push(`- FAILED ${f.candidate}: ${f.error}`);
+    return lines.join("\n");
+}