@zeroroot-ai/zerocool 0.5.0 → 0.6.0

package/dist/fix.d.ts

@@ -0,0 +1,207 @@
+import type { FileChange, GitLabWriter, MergeRequest } from "./gitlab.js";
+/**
+ * The Fix — what the always-on agent does with a Finding (zerocool-plugins#89).
+ *
+ * After a Scan mission lands, the agent works the Application's open Findings
+ * in priority order. For each one it can act on it rewrites the repository,
+ * runs the repository's own tests, and only then opens a merge request set to
+ * merge itself when the pipeline succeeds. It records the scan verdict on the
+ * commit as `gibson/scan` and posts one note saying what it fixed, what it did
+ * not, and why.
+ *
+ * THE ORDER IS TESTS, THEN PUSH. A fix that breaks the build is worse than the
+ * Finding: it stops every other fix behind it. So the change is applied to a
+ * workspace, the tests run there, and a failure resets the workspace and leaves
+ * the Finding `open` with its reason recorded. Nothing unproven reaches GitLab.
+ *
+ * THE FIX NEVER MARKS A FINDING `verified`. A merge is not evidence that a
+ * rescan did not see the weakness again — only the rescan is, and absence is
+ * not an observation, so it is reconciled once at a scan's completion
+ * (gibson#1686). The Fix moves a Finding `open` → `fixing` when its merge
+ * request opens and `fixing` → `fixed` when GitLab reports that request merged.
+ *
+ * THE TOKEN NEVER APPEARS IN ANYTHING THIS WRITES. It reaches GitLab only as a
+ * `PRIVATE-TOKEN` header inside {@link gitlabRestWriter}. No branch name, merge
+ * request title, description, note or status description is built from it, and
+ * `fix.test.ts` proves that with a sentinel that would show up in every
+ * recorded output if it ever did.
+ *
+ * TWO SEAMS ARE DELIBERATELY UNIMPLEMENTED HERE. Reading an Application's
+ * Findings and writing a Finding's status both exist on the Go SDK as of
+ * v0.174.0, and on neither the TypeScript SDK nor this package: `@zeroroot-ai/sdk`
+ * carries no `applicationFindings` and its `observe` admits only host, domain,
+ * subdomain, credential, account and memory. That is sdk-ts#51. Until it lands,
+ * {@link FindingSource} and {@link FindingStatusWriter} have no platform
+ * implementation, and the Fix is driven by whatever supplies them. This is a
+ * seam, not a second code path: when the wire arrives there is one
+ * implementation to add and nothing here changes.
+ */
+/** Severities, worst first. Used for the note's counts and for a stable order. */
+export declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+/** A Finding as the Fix needs it — the read half of sdk-ts#51. */
+export interface FixableFinding {
+    /** The graph's `brain_id`, so a write lands on the node that was read. */
+    id: string;
+    /** `open`, `fixing`, `fixed` or `verified`. */
+    status: string;
+    severity: string;
+    /** The CVE, GHSA or platform id this Finding is an instance of. */
+    vulnerabilityId: string;
+    /** Where it is: a `Package`, a `Repository` file, or a `Service`. */
+    placeLabel: string;
+    placeKey: string;
+    /** `P1`..`P4` once the read carries what a triage pass decided (gibson#1684). */
+    priority?: string;
+    /** The merge request already opened for this Finding, when it is `fixing`. */
+    mergeRequestIid?: number;
+}
+/** Reads an Application's Findings. Platform implementation pending sdk-ts#51. */
+export interface FindingSource {
+    /**
+     * The Application's Findings in the given statuses, **in the order they
+     * should be worked**. Rejects when the graph is unreachable; it must never
+     * resolve empty to signal failure, because an empty list reads as a healthy
+     * Application and the Fix would report success over a live backlog.
+     */
+    findings(application: string, statuses: string[]): Promise<FixableFinding[]>;
+}
+/** Moves a Finding through its statuses. Platform implementation pending sdk-ts#51. */
+export interface FindingStatusWriter {
+    /** Record that a merge request now proposes this Finding's fix. */
+    markFixing(findingId: string, mr: MergeRequest): Promise<void>;
+    /** Record that the merge request merged. Never `verified` — the rescan does that. */
+    markFixed(findingId: string): Promise<void>;
+}
+/** A checkout the Fix can change and test before anything is pushed. */
+export interface Workspace {
+    /** File contents, or `undefined` when the path does not exist. */
+    read(path: string): Promise<string | undefined>;
+    /** Stage a rewrite in the workspace. Not a push. */
+    write(path: string, content: string): Promise<void>;
+    /** Run the repository's own tests. `output` is quoted in the note on failure. */
+    test(): Promise<{
+        ok: boolean;
+        output: string;
+    }>;
+    /** Discard staged rewrites, so a failed fix does not leak into the next one. */
+    reset(): Promise<void>;
+    /** What was staged, in commit order. */
+    staged(): FileChange[];
+}
+/** What the agent proposes to do about one Finding. */
+export interface FixPlan {
+    /** Which of the three the owner's scope named. Reported in the note. */
+    kind: "dependency" | "source" | "config";
+    /** One line, for the merge request title. */
+    summary: string;
+    /** The commit message body. */
+    detail: string;
+}
+/**
+ * Decides what to change for a Finding, and stages it in the workspace.
+ *
+ * Returning `undefined` means "no strategy for this Finding" — reported in the
+ * note as unfixed with that reason, never silently skipped. A planner that
+ * throws is treated the same way, with its message as the reason: one Finding
+ * with no strategy must not stop the ones behind it.
+ */
+export interface FixPlanner {
+    plan(finding: FixableFinding, ws: Workspace): Promise<FixPlan | undefined>;
+}
+/** What happened to one Finding in a Fix pass. */
+export interface FixOutcome {
+    finding: FixableFinding;
+    /** `fixing` when a merge request opened, `merged` when one already had, else `unfixed`. */
+    result: "fixing" | "merged" | "unfixed";
+    /** Why it is unfixed. Empty otherwise. Quoted verbatim in the note. */
+    reason: string;
+    mergeRequest?: MergeRequest;
+    plan?: FixPlan;
+}
+/** One line of the console stream, so the ops wall shows the Fix working. */
+export type FixEvent = {
+    type: "fix.start";
+    application: string;
+    commit: string;
+    open: number;
+    fixing: number;
+} | {
+    type: "fix.plan";
+    findingId: string;
+    kind: FixPlan["kind"];
+    summary: string;
+} | {
+    type: "fix.tests";
+    findingId: string;
+    ok: boolean;
+} | {
+    type: "fix.mr";
+    findingId: string;
+    iid: number;
+    webUrl: string;
+} | {
+    type: "fix.merged";
+    findingId: string;
+    iid: number;
+} | {
+    type: "fix.skip";
+    findingId: string;
+    reason: string;
+} | {
+    type: "fix.error";
+    stage: "read" | "status" | "note" | "plan";
+    message: string;
+};
+export interface FixSummary {
+    application: string;
+    commit: string;
+    outcomes: FixOutcome[];
+    /** True when every Finding that had a strategy ended `fixing` or `merged`. */
+    clean: boolean;
+}
+export interface RunFixOptions {
+    application: string;
+    /** The commit the Scan mission ran against — what the status is set on. */
+    commit: string;
+    /** The branch merge requests target. */
+    targetRef: string;
+    findings: FindingSource;
+    status: FindingStatusWriter;
+    planner: FixPlanner;
+    workspace: Workspace;
+    gitlab: GitLabWriter;
+    /** The pipeline page, linked from the commit status. */
+    pipelineUrl?: string;
+    /** Cap on merge requests opened in one pass, so a backlog cannot flood review. */
+    maxMergeRequests?: number;
+    onEvent?: (e: FixEvent) => void;
+}
+/** Default ceiling on merge requests opened by one pass. */
+export declare const DEFAULT_MAX_MERGE_REQUESTS = 10;
+/**
+ * Run one Fix pass over an Application.
+ *
+ * Reconcile first, then fix. A Finding already `fixing` whose merge request has
+ * merged becomes `fixed` before anything new is opened, so a pass never opens a
+ * second merge request for a Finding the previous pass already resolved.
+ */
+export declare function runFix(opts: RunFixOptions): Promise<FixSummary>;
+/**
+ * The branch one Finding's fix lands on. Stable, so a retry reuses it rather
+ * than opening a second merge request for the same Finding.
+ *
+ * The slug keeps only `[a-z0-9-]`. Dots are dropped rather than preserved:
+ * git refuses a ref containing `..`, and a vulnerability id is attacker-
+ * adjacent text that ends up interpolated into a URL path, so a dot run is
+ * exactly the shape not to carry through. The Finding id is appended so two
+ * occurrences of one CVE get two branches.
+ */
+export declare function fixBranch(finding: FixableFinding): string;
+/** Counts by severity, worst first, for the note and the status line. */
+export declare function countsBySeverity(findings: FixableFinding[]): Record<string, number>;
+/** The one-line verdict GitLab shows beside the commit. */
+export declare function statusDescription(summary: FixSummary): string;
+/** The merge request description. Names the Finding it closes and how. */
+export declare function mergeRequestBody(finding: FixableFinding, plan: FixPlan): string;
+/** The note posted on each merge request: what this pass did, in full. */
+export declare function noteBody(summary: FixSummary): string;

package/dist/fix.js

@@ -0,0 +1,255 @@
+/**
+ * The Fix — what the always-on agent does with a Finding (zerocool-plugins#89).
+ *
+ * After a Scan mission lands, the agent works the Application's open Findings
+ * in priority order. For each one it can act on it rewrites the repository,
+ * runs the repository's own tests, and only then opens a merge request set to
+ * merge itself when the pipeline succeeds. It records the scan verdict on the
+ * commit as `gibson/scan` and posts one note saying what it fixed, what it did
+ * not, and why.
+ *
+ * THE ORDER IS TESTS, THEN PUSH. A fix that breaks the build is worse than the
+ * Finding: it stops every other fix behind it. So the change is applied to a
+ * workspace, the tests run there, and a failure resets the workspace and leaves
+ * the Finding `open` with its reason recorded. Nothing unproven reaches GitLab.
+ *
+ * THE FIX NEVER MARKS A FINDING `verified`. A merge is not evidence that a
+ * rescan did not see the weakness again — only the rescan is, and absence is
+ * not an observation, so it is reconciled once at a scan's completion
+ * (gibson#1686). The Fix moves a Finding `open` → `fixing` when its merge
+ * request opens and `fixing` → `fixed` when GitLab reports that request merged.
+ *
+ * THE TOKEN NEVER APPEARS IN ANYTHING THIS WRITES. It reaches GitLab only as a
+ * `PRIVATE-TOKEN` header inside {@link gitlabRestWriter}. No branch name, merge
+ * request title, description, note or status description is built from it, and
+ * `fix.test.ts` proves that with a sentinel that would show up in every
+ * recorded output if it ever did.
+ *
+ * TWO SEAMS ARE DELIBERATELY UNIMPLEMENTED HERE. Reading an Application's
+ * Findings and writing a Finding's status both exist on the Go SDK as of
+ * v0.174.0, and on neither the TypeScript SDK nor this package: `@zeroroot-ai/sdk`
+ * carries no `applicationFindings` and its `observe` admits only host, domain,
+ * subdomain, credential, account and memory. That is sdk-ts#51. Until it lands,
+ * {@link FindingSource} and {@link FindingStatusWriter} have no platform
+ * implementation, and the Fix is driven by whatever supplies them. This is a
+ * seam, not a second code path: when the wire arrives there is one
+ * implementation to add and nothing here changes.
+ */
+/** Severities, worst first. Used for the note's counts and for a stable order. */
+export const SEVERITIES = ["critical", "high", "medium", "low", "info"];
+/** Default ceiling on merge requests opened by one pass. */
+export const DEFAULT_MAX_MERGE_REQUESTS = 10;
+/**
+ * Run one Fix pass over an Application.
+ *
+ * Reconcile first, then fix. A Finding already `fixing` whose merge request has
+ * merged becomes `fixed` before anything new is opened, so a pass never opens a
+ * second merge request for a Finding the previous pass already resolved.
+ */
+export async function runFix(opts) {
+    const emit = (e) => opts.onEvent?.(e);
+    const cap = opts.maxMergeRequests ?? DEFAULT_MAX_MERGE_REQUESTS;
+    const outcomes = [];
+    const all = await opts.findings.findings(opts.application, ["open", "fixing"]);
+    const fixing = all.filter((f) => f.status === "fixing");
+    const open = all.filter((f) => f.status === "open");
+    emit({ type: "fix.start", application: opts.application, commit: opts.commit, open: open.length, fixing: fixing.length });
+    // Reconcile: a merge request that merged moves its Finding to `fixed`.
+    for (const finding of fixing) {
+        if (finding.mergeRequestIid === undefined)
+            continue;
+        try {
+            const mr = await opts.gitlab.mergeRequestState(finding.mergeRequestIid);
+            if (mr.state !== "merged")
+                continue;
+            await opts.status.markFixed(finding.id);
+            emit({ type: "fix.merged", findingId: finding.id, iid: mr.iid });
+            outcomes.push({ finding, result: "merged", reason: "", mergeRequest: mr });
+        }
+        catch (e) {
+            emit({ type: "fix.error", stage: "status", message: message(e) });
+        }
+    }
+    let opened = 0;
+    for (const finding of open) {
+        if (opened >= cap) {
+            outcomes.push({ finding, result: "unfixed", reason: `merge request cap of ${cap} reached in this pass` });
+            emit({ type: "fix.skip", findingId: finding.id, reason: "cap reached" });
+            continue;
+        }
+        let plan;
+        try {
+            plan = await opts.planner.plan(finding, opts.workspace);
+        }
+        catch (e) {
+            await safeReset(opts.workspace);
+            outcomes.push({ finding, result: "unfixed", reason: `planning failed: ${message(e)}` });
+            emit({ type: "fix.error", stage: "plan", message: message(e) });
+            continue;
+        }
+        if (!plan) {
+            await safeReset(opts.workspace);
+            outcomes.push({ finding, result: "unfixed", reason: "no fix strategy for this finding" });
+            emit({ type: "fix.skip", findingId: finding.id, reason: "no fix strategy" });
+            continue;
+        }
+        const changes = opts.workspace.staged();
+        if (changes.length === 0) {
+            await safeReset(opts.workspace);
+            outcomes.push({ finding, result: "unfixed", reason: "the planner changed nothing" });
+            emit({ type: "fix.skip", findingId: finding.id, reason: "no change staged" });
+            continue;
+        }
+        emit({ type: "fix.plan", findingId: finding.id, kind: plan.kind, summary: plan.summary });
+        const tests = await opts.workspace.test();
+        emit({ type: "fix.tests", findingId: finding.id, ok: tests.ok });
+        if (!tests.ok) {
+            await safeReset(opts.workspace);
+            outcomes.push({ finding, result: "unfixed", plan, reason: `the repository's tests failed: ${firstLines(tests.output)}` });
+            continue;
+        }
+        try {
+            const branch = fixBranch(finding);
+            await opts.gitlab.commitToBranch(branch, opts.targetRef, `${plan.summary}\n\n${plan.detail}`, changes);
+            const mr = await opts.gitlab.openMergeRequest(branch, opts.targetRef, plan.summary, mergeRequestBody(finding, plan));
+            emit({ type: "fix.mr", findingId: finding.id, iid: mr.iid, webUrl: mr.webUrl });
+            opened++;
+            await opts.status.markFixing(finding.id, mr);
+            outcomes.push({ finding, result: "fixing", reason: "", mergeRequest: mr, plan });
+        }
+        catch (e) {
+            outcomes.push({ finding, result: "unfixed", plan, reason: `GitLab refused the change: ${message(e)}` });
+            emit({ type: "fix.error", stage: "status", message: message(e) });
+        }
+        finally {
+            await safeReset(opts.workspace);
+        }
+    }
+    const summary = {
+        application: opts.application,
+        commit: opts.commit,
+        outcomes,
+        clean: outcomes.every((o) => o.result !== "unfixed"),
+    };
+    // The verdict lands on the commit that was scanned, whatever happened above.
+    // A pass that could not reach GitLab for the status still reports its work
+    // through the return value, so the caller is never told the pass did nothing.
+    try {
+        await opts.gitlab.setCommitStatus(opts.commit, summary.clean ? "success" : "failed", statusDescription(summary), opts.pipelineUrl);
+    }
+    catch (e) {
+        emit({ type: "fix.error", stage: "note", message: message(e) });
+    }
+    for (const outcome of outcomes) {
+        if (outcome.result !== "fixing" || !outcome.mergeRequest)
+            continue;
+        try {
+            await opts.gitlab.comment(outcome.mergeRequest.iid, noteBody(summary));
+        }
+        catch (e) {
+            emit({ type: "fix.error", stage: "note", message: message(e) });
+        }
+    }
+    return summary;
+}
+/**
+ * The branch one Finding's fix lands on. Stable, so a retry reuses it rather
+ * than opening a second merge request for the same Finding.
+ *
+ * The slug keeps only `[a-z0-9-]`. Dots are dropped rather than preserved:
+ * git refuses a ref containing `..`, and a vulnerability id is attacker-
+ * adjacent text that ends up interpolated into a URL path, so a dot run is
+ * exactly the shape not to carry through. The Finding id is appended so two
+ * occurrences of one CVE get two branches.
+ */
+export function fixBranch(finding) {
+    const slug = `${finding.vulnerabilityId || finding.id}`
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `gibson/fix-${slug || "unclassified"}-${finding.id.slice(0, 8)}`;
+}
+/** Counts by severity, worst first, for the note and the status line. */
+export function countsBySeverity(findings) {
+    const out = {};
+    for (const s of SEVERITIES) {
+        const n = findings.filter((f) => f.severity.toLowerCase() === s).length;
+        if (n > 0)
+            out[s] = n;
+    }
+    const known = new Set(SEVERITIES);
+    const other = findings.filter((f) => !known.has(f.severity.toLowerCase())).length;
+    if (other > 0)
+        out.other = other;
+    return out;
+}
+/** The one-line verdict GitLab shows beside the commit. */
+export function statusDescription(summary) {
+    const fixing = summary.outcomes.filter((o) => o.result === "fixing").length;
+    const merged = summary.outcomes.filter((o) => o.result === "merged").length;
+    const unfixed = summary.outcomes.filter((o) => o.result === "unfixed").length;
+    if (summary.outcomes.length === 0)
+        return "no open findings";
+    return `${fixing} merge request(s) opened, ${merged} merged, ${unfixed} left for a human`;
+}
+/** The merge request description. Names the Finding it closes and how. */
+export function mergeRequestBody(finding, plan) {
+    return [
+        plan.detail,
+        "",
+        `Finding: \`${finding.id}\``,
+        `Vulnerability: \`${finding.vulnerabilityId || "unclassified"}\``,
+        `Where: ${finding.placeLabel} \`${finding.placeKey}\``,
+        `Severity: ${finding.severity}${finding.priority ? ` · priority ${finding.priority}` : ""}`,
+        "",
+        "Opened by the Gibson always-on agent. It merges itself when the pipeline",
+        "succeeds. The finding is marked fixed on merge and verified only by a",
+        "later rescan.",
+    ].join("\n");
+}
+/** The note posted on each merge request: what this pass did, in full. */
+export function noteBody(summary) {
+    const lines = [
+        `### Gibson scan of \`${summary.commit.slice(0, 12)}\` on ${summary.application}`,
+        "",
+    ];
+    const counts = countsBySeverity(summary.outcomes.map((o) => o.finding));
+    const rendered = Object.entries(counts)
+        .map(([k, v]) => `${v} ${k}`)
+        .join(", ");
+    lines.push(rendered ? `Findings this pass: ${rendered}.` : "No open findings this pass.");
+    lines.push("");
+    const fixed = summary.outcomes.filter((o) => o.result === "fixing" || o.result === "merged");
+    if (fixed.length > 0) {
+        lines.push("**Fixed**");
+        for (const o of fixed) {
+            const where = `${o.finding.placeLabel} \`${o.finding.placeKey}\``;
+            const link = o.mergeRequest?.webUrl ? ` — ${o.mergeRequest.webUrl}` : "";
+            lines.push(`- ${o.finding.vulnerabilityId || o.finding.id} in ${where}${link}`);
+        }
+        lines.push("");
+    }
+    const unfixed = summary.outcomes.filter((o) => o.result === "unfixed");
+    if (unfixed.length > 0) {
+        lines.push("**Left for a human**");
+        for (const o of unfixed) {
+            const where = `${o.finding.placeLabel} \`${o.finding.placeKey}\``;
+            lines.push(`- ${o.finding.vulnerabilityId || o.finding.id} in ${where} — ${o.reason}`);
+        }
+    }
+    return lines.join("\n");
+}
+async function safeReset(ws) {
+    try {
+        await ws.reset();
+    }
+    catch {
+        // A reset that fails is reported by the next planner call changing nothing.
+    }
+}
+function firstLines(output, n = 3) {
+    return output.split("\n").slice(0, n).join(" ").trim();
+}
+function message(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/gitlab.d.ts

@@ -72,3 +72,47 @@ export declare function parsePipeline(raw: unknown): Pipeline | undefined;
  * request.
  */
 export declare function gitlabRest(opts: GitLabRestOptions): GitLabClient;
+/** The `gibson/scan` commit status states GitLab accepts, narrowed to what we set. */
+export type CommitStatusState = "success" | "failed" | "running";
+/** The context name the scan status is reported under, named once. */
+export declare const SCAN_STATUS_CONTEXT = "gibson/scan";
+/** A merge request the Fix opened, reduced to what the Fix and a human need. */
+export interface MergeRequest {
+    /** The project-scoped iid, which is what every later GitLab call takes. */
+    iid: number;
+    /** The page a human opens. Also what the Finding records. */
+    webUrl: string;
+    /** GitLab's own state: `opened`, `merged`, `closed`, `locked`. */
+    state: string;
+}
+/** One file the Fix rewrote, as the commit API wants it. */
+export interface FileChange {
+    path: string;
+    content: string;
+}
+/** The GitLab writes the Fix makes. Kept behind an interface so a test needs no network. */
+export interface GitLabWriter {
+    /**
+     * Commit `changes` onto a new branch off `startRef`. Returns the commit sha.
+     * The branch is created by the same call, so a half-made branch with no
+     * commit is not a state this can leave behind.
+     */
+    commitToBranch(branch: string, startRef: string, message: string, changes: FileChange[]): Promise<string>;
+    /** Open a merge request set to merge itself when its pipeline succeeds. */
+    openMergeRequest(branch: string, targetRef: string, title: string, description: string): Promise<MergeRequest>;
+    /** The current state of a merge request, so a later pass can see it merged. */
+    mergeRequestState(iid: number): Promise<MergeRequest>;
+    /** Post a note on a merge request. */
+    comment(iid: number, body: string): Promise<void>;
+    /** Set the `gibson/scan` status on a commit. */
+    setCommitStatus(sha: string, state: CommitStatusState, description: string, targetUrl?: string): Promise<void>;
+}
+/**
+ * A {@link GitLabWriter} over GitLab's REST API.
+ *
+ * Every request carries the token in `PRIVATE-TOKEN` and never in a URL or a
+ * body, so a failure message that quotes the request cannot carry it into the
+ * console stream. The error text names the project, the branch and the status
+ * code — never a header.
+ */
+export declare function gitlabRestWriter(opts: GitLabRestOptions): GitLabWriter;

package/dist/gitlab.js

@@ -80,3 +80,97 @@ export function gitlabRest(opts) {
         },
     };
 }
+/** The context name the scan status is reported under, named once. */
+export const SCAN_STATUS_CONTEXT = "gibson/scan";
+/**
+ * A {@link GitLabWriter} over GitLab's REST API.
+ *
+ * Every request carries the token in `PRIVATE-TOKEN` and never in a URL or a
+ * body, so a failure message that quotes the request cannot carry it into the
+ * console stream. The error text names the project, the branch and the status
+ * code — never a header.
+ */
+export function gitlabRestWriter(opts) {
+    const base = (opts.baseUrl || GITLAB_DEFAULT_URL).replace(/\/+$/, "");
+    const project = encodeURIComponent(opts.projectPath);
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const api = `${base}/api/v4/projects/${project}`;
+    async function call(method, path, body) {
+        const res = await doFetch(`${api}${path}`, {
+            method,
+            headers: {
+                "PRIVATE-TOKEN": opts.token,
+                Accept: "application/json",
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (!res.ok) {
+            throw new Error(`GitLab ${method} ${path} on ${opts.projectPath} returned ${res.status} ${res.statusText}`);
+        }
+        return res.json();
+    }
+    const asMergeRequest = (raw, branch) => {
+        const mr = (raw ?? {});
+        const iid = typeof mr.iid === "number" ? mr.iid : Number.NaN;
+        if (!Number.isInteger(iid) || iid <= 0) {
+            throw new Error(`GitLab returned a merge request for ${branch} with no iid`);
+        }
+        return {
+            iid,
+            webUrl: typeof mr.web_url === "string" ? mr.web_url : "",
+            state: typeof mr.state === "string" ? mr.state : "",
+        };
+    };
+    return {
+        async commitToBranch(branch, startRef, message, changes) {
+            if (changes.length === 0) {
+                throw new Error(`refusing to commit an empty change set to ${branch}`);
+            }
+            const raw = await call("POST", "/repository/commits", {
+                branch,
+                start_branch: startRef,
+                commit_message: message,
+                actions: changes.map((c) => ({ action: "update", file_path: c.path, content: c.content })),
+            });
+            const sha = raw.id;
+            if (typeof sha !== "string" || !sha) {
+                throw new Error(`GitLab accepted the commit on ${branch} but returned no sha`);
+            }
+            return sha;
+        },
+        async openMergeRequest(branch, targetRef, title, description) {
+            const created = asMergeRequest(await call("POST", "/merge_requests", {
+                source_branch: branch,
+                target_branch: targetRef,
+                title,
+                description,
+                remove_source_branch: true,
+            }), branch);
+            // Auto-merge is a separate call, and a refusal is not fatal: the merge
+            // request is open and correct either way, and a human can merge it. A
+            // thrown error here would lose a good merge request over a race with the
+            // pipeline that has not started yet.
+            try {
+                await call("PUT", `/merge_requests/${created.iid}/merge`, { merge_when_pipeline_succeeds: true });
+            }
+            catch {
+                // Reported by the caller through the note, not swallowed silently.
+            }
+            return created;
+        },
+        mergeRequestState: async (iid) => asMergeRequest(await call("GET", `/merge_requests/${iid}`), `!${iid}`),
+        comment: async (iid, body) => {
+            await call("POST", `/merge_requests/${iid}/notes`, { body });
+        },
+        setCommitStatus: async (sha, state, description, targetUrl) => {
+            await call("POST", `/statuses/${encodeURIComponent(sha)}`, {
+                state,
+                name: SCAN_STATUS_CONTEXT,
+                context: SCAN_STATUS_CONTEXT,
+                description,
+                ...(targetUrl ? { target_url: targetUrl } : {}),
+            });
+        },
+    };
+}

package/dist/watch.d.ts

@@ -170,13 +170,18 @@ export interface ScanMissionInputs {
 /**
  * The Scan mission definition, as canonical proto JSON.
  *
- * A PLACEHOLDER WITH A REAL SHAPE. gibson#1660 owns the Scan mission proper —
- * Trivy on the image, source analysis on the commit, and the runtime tools
- * against the target, fanned out and joined. Until it lands, this originates
- * the one node that exists today: zerocool's source-analysis task
- * (zerocool-plugins#87) on the pipeline's commit. Everything the full fan-out
- * needs is already carried in the node's task context, so gibson#1660 replaces
- * the body of this one function and nothing else in the loop changes.
+ * STILL BUILT HERE, AND IT SHOULD NOT BE. gibson#1685 landed the Scan mission
+ * as a checked-in definition in gibson's `missioncatalog`, and ADR-0018 makes
+ * that copy authoritative: this function is meant to become a mission name plus
+ * seven parameters, not a second description of the same graph.
+ *
+ * It cannot yet. `missioncatalog.Render` has no production caller, and
+ * `CreateMission` carries only `mission_definition_json` — there is no field
+ * naming a checked-in mission and none carrying its parameters, so an agent has
+ * no way to ask for the catalog's copy. That is gibson#1688. Until it lands the
+ * only way to originate a Scan is to send a graph, so this one stays, with the
+ * shape the catalog definition expects: everything the fan-out needs is carried
+ * in the node's task context, and the swap is this function's body alone.
  *
  * The definition is built as protojson by hand rather than through the
  * generated schema because the SDK's package exports only its index, and the

package/dist/watch.js

@@ -225,13 +225,18 @@ export function checkpointQueryText(application) {
 /**
  * The Scan mission definition, as canonical proto JSON.
  *
- * A PLACEHOLDER WITH A REAL SHAPE. gibson#1660 owns the Scan mission proper —
- * Trivy on the image, source analysis on the commit, and the runtime tools
- * against the target, fanned out and joined. Until it lands, this originates
- * the one node that exists today: zerocool's source-analysis task
- * (zerocool-plugins#87) on the pipeline's commit. Everything the full fan-out
- * needs is already carried in the node's task context, so gibson#1660 replaces
- * the body of this one function and nothing else in the loop changes.
+ * STILL BUILT HERE, AND IT SHOULD NOT BE. gibson#1685 landed the Scan mission
+ * as a checked-in definition in gibson's `missioncatalog`, and ADR-0018 makes
+ * that copy authoritative: this function is meant to become a mission name plus
+ * seven parameters, not a second description of the same graph.
+ *
+ * It cannot yet. `missioncatalog.Render` has no production caller, and
+ * `CreateMission` carries only `mission_definition_json` — there is no field
+ * naming a checked-in mission and none carrying its parameters, so an agent has
+ * no way to ask for the catalog's copy. That is gibson#1688. Until it lands the
+ * only way to originate a Scan is to send a graph, so this one stays, with the
+ * shape the catalog definition expects: everything the fan-out needs is carried
+ * in the node's task context, and the swap is this function's body alone.
  *
  * The definition is built as protojson by hand rather than through the
  * generated schema because the SDK's package exports only its index, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/zerocool",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "opencode plugin: Gibson platform integration (zerocool). Zero-config LLM, tools, findings, knowledge, delegate/missions.",
   "license": "MIT",
   "repository": {