@zeroroot-ai/zerocool 0.6.0 → 0.8.0

package/dist/dispatch.d.ts

@@ -46,8 +46,9 @@
  *   GIBSON_CALLBACK_INSECURE   "1" to dial the callback listener without TLS (kind)
  *   GIBSON_MISSION_ID / GIBSON_MISSION_RUN_ID / GIBSON_AGENT_RUN_ID   provenance
  *   ZEROCOOL_WORKSPACE         working directory (defaults to the cwd)
- *   ZEROCOOL_TASK              force a task kind ("source-analysis"); the Task's
- *                              own context `zerocool.task` is the normal way
+ *   ZEROCOOL_TASK              force a task kind ("source-analysis", "watch",
+ *                              "fix"); the Task's own context `zerocool.task`
+ *                              is the normal way
  *   GIBSON_OPENCODE_SESSION_ID continue an earlier opencode session
  *   GIBSON_TIMEOUT_MS          hard deadline for the run, in ms
  *
@@ -57,7 +58,8 @@
  */
 import { type AgentOutcome, type TaskHarness } from "@zeroroot-ai/sdk";
 import { type FindingsBackend } from "./findings.js";
-import { type GitLabClient } from "./gitlab.js";
+import { type FindingSource, type FindingStatusWriter, type FixPlanner, type Workspace } from "./fix.js";
+import { type GitLabClient, type GitLabWriter } from "./gitlab.js";
 import { runOpencode } from "./opencode-run.js";
 import type { SemgrepRunner } from "./semgrep.js";
 import { type ScanLauncher, type WatchCheckpoints } from "./watch.js";
@@ -151,7 +153,7 @@ export declare function decodeTask(taskB64: string | undefined): DecodedTask;
  */
 export declare function typedValueString(val: unknown): string | undefined;
 /** The task kinds a sandboxed dispatch can serve. */
-export type DispatchTaskKind = "opencode" | "source-analysis" | "watch";
+export type DispatchTaskKind = "opencode" | "source-analysis" | "watch" | "fix";
 /**
  * Which task this dispatch runs. The mission node says so in the Task's
  * context (`zerocool.task`); ZEROCOOL_TASK forces it for a hand-run sandbox.
@@ -190,6 +192,29 @@ export interface DispatchDeps {
     taskKind?: DispatchTaskKind;
     /** Watch seams: no GitLab, no World and no child missions in a test. */
     watch?: WatchDeps;
+    /** Fix seams: no GitLab, no graph and no checkout in a test. */
+    fix?: FixDeps;
+}
+/**
+ * The fix task's injectable seams.
+ *
+ * `planner` and `workspace` have no default. The Fix decides what to change
+ * and runs the repository's own tests before anything is pushed, and neither
+ * is something this process can synthesise: a default planner would be one
+ * that changes nothing, and a default workspace would be one whose tests
+ * always pass. Both would turn a missing dependency into a Fix that reports
+ * success having done nothing, so a dispatch without them fails instead.
+ */
+export interface FixDeps {
+    gitlab?: GitLabWriter;
+    findings?: FindingSource;
+    status?: FindingStatusWriter;
+    planner?: FixPlanner;
+    workspace?: Workspace;
+    /** Resolve the GitLab token. Defaults to the harness `GetCredential`. */
+    credential?: (name: string) => Promise<string>;
+    /** Cap on merge requests opened by one pass. */
+    maxMergeRequests?: number;
 }
 /** The watch task's injectable seams. Everything the loop reaches out through. */
 export interface WatchDeps {
@@ -237,11 +262,44 @@ export declare function runSourceAnalysisDispatch(ctx: DispatchContext, deps?: D
  *   `gitlab.url`           instance base url; defaults to gitlab.com
  *   `gitlab.ref`           branch to watch; defaults to `main`
  *   `gitlab.credential`    tenant secret holding the project access token
- *   `repository.url`       clone url handed to each Scan mission
+ *   `repository.url`       clone url the Scan mission checks out (required)
+ *   `image.ref`            the image the pipeline published, by digest (required)
  *   `target.id`            the registered target each Scan mission binds to
  *   `watch.interval_ms`    poll cadence; defaults to 30s
  */
 export declare function runWatchDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
+/**
+ * The fix task, sandboxed (zerocool-plugins#89, finished in #96).
+ *
+ * What the always-on agent does after a Scan mission lands: read the
+ * Application's Findings over the task grant, work them in priority order,
+ * and for each one it can act on rewrite the repository, run the repository's
+ * own tests, and only then open a merge request that merges itself on a green
+ * pipeline. See `fix.ts` for why the order is tests-then-push and why this
+ * never marks a Finding `verified`.
+ *
+ * THE READ AND THE STATUS WRITE TRAVEL ON THE DISPATCH GRANT, not on a
+ * component identity — this process has none. `applicationFindings` and
+ * `observe` both reach the daemon as the task, so the run holds exactly the
+ * authority its dispatch granted.
+ *
+ * A REJECTED READ FAILS THE RUN. `harnessFindingSource` does not catch it, and
+ * neither does this: an unreachable graph reported as an empty backlog is a
+ * Fix that says the Application is clean while the backlog is live, and it
+ * reads identically to health.
+ *
+ * Task context keys it reads:
+ *   `zerocool.task`        selector, "fix"
+ *   `application`          the Application whose Findings are worked (required)
+ *   `gitlab.project`       `group/project` on the instance (required)
+ *   `gitlab.url`           instance base url; defaults to gitlab.com
+ *   `gitlab.ref`           branch merge requests target; defaults to `main`
+ *   `gitlab.credential`    tenant secret holding the project access token
+ *   `repository.commit`    the commit the Scan ran against — what the status lands on
+ *   `pipeline.url`         the pipeline page, linked from the commit status
+ *   `fix.max_merge_requests`  cap on merge requests opened in one pass
+ */
+export declare function runFixDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
 /**
  * Resolve a tenant secret through the harness on the dispatch grant. The value
  * is returned to the caller and never logged: it is the GitLab token, and the

package/dist/dispatch.js

@@ -46,8 +46,9 @@
  *   GIBSON_CALLBACK_INSECURE   "1" to dial the callback listener without TLS (kind)
  *   GIBSON_MISSION_ID / GIBSON_MISSION_RUN_ID / GIBSON_AGENT_RUN_ID   provenance
  *   ZEROCOOL_WORKSPACE         working directory (defaults to the cwd)
- *   ZEROCOOL_TASK              force a task kind ("source-analysis"); the Task's
- *                              own context `zerocool.task` is the normal way
+ *   ZEROCOOL_TASK              force a task kind ("source-analysis", "watch",
+ *                              "fix"); the Task's own context `zerocool.task`
+ *                              is the normal way
  *   GIBSON_OPENCODE_SESSION_ID continue an earlier opencode session
  *   GIBSON_TIMEOUT_MS          hard deadline for the run, in ms
  *
@@ -55,10 +56,11 @@
  * {@link dispatchChildEnv} — that is the opencode plugin's own contract, fed from
  * the GIBSON_CG_JWT this process reads.
  */
-import { openTaskHarness } from "@zeroroot-ai/sdk";
+import { observe, openTaskHarness, taskKnowledge } from "@zeroroot-ai/sdk";
 import { join } from "node:path";
 import { taskFindingsBackend } from "./findings.js";
-import { gitlabRest } from "./gitlab.js";
+import { harnessFindingSource, harnessFindingStatus, runFix, } from "./fix.js";
+import { gitlabRest, gitlabRestWriter } from "./gitlab.js";
 import { runOpencode } from "./opencode-run.js";
 import { DEFAULT_REF, harnessScanLauncher, runWatchLoop, worldCheckpoints, } from "./watch.js";
 import { formatSourceAnalysis, harnessTriageModel, runSourceAnalysis, } from "./source-analysis.js";
@@ -183,6 +185,8 @@ export function dispatchTaskKind(ctx, env = {}) {
         return "source-analysis";
     if (kind === "watch")
         return "watch";
+    if (kind === "fix")
+        return "fix";
     return "opencode";
 }
 /**
@@ -245,6 +249,9 @@ export async function runDispatch(ctx, deps = {}) {
     if (kind === "watch") {
         return runWatchDispatch(ctx, deps);
     }
+    if (kind === "fix") {
+        return runFixDispatch(ctx, deps);
+    }
     const run = deps.run ?? runOpencode;
     const result = await run({
         goal: ctx.goal,
@@ -335,7 +342,8 @@ export async function runSourceAnalysisDispatch(ctx, deps = {}) {
  *   `gitlab.url`           instance base url; defaults to gitlab.com
  *   `gitlab.ref`           branch to watch; defaults to `main`
  *   `gitlab.credential`    tenant secret holding the project access token
- *   `repository.url`       clone url handed to each Scan mission
+ *   `repository.url`       clone url the Scan mission checks out (required)
+ *   `image.ref`            the image the pipeline published, by digest (required)
  *   `target.id`            the registered target each Scan mission binds to
  *   `watch.interval_ms`    poll cadence; defaults to 30s
  */
@@ -346,6 +354,8 @@ export async function runWatchDispatch(ctx, deps = {}) {
     const ref = ctx.taskContext["gitlab.ref"] || DEFAULT_REF;
     const targetId = ctx.taskContext["target.id"] || "";
     const credentialName = ctx.taskContext["gitlab.credential"] || "gitlab-token";
+    const repositoryUrl = ctx.taskContext["repository.url"] || "";
+    const imageRef = ctx.taskContext["image.ref"] || "";
     if (!application) {
         throw new Error("watch: the mission node set no `application` in the task context. The watch keys its " +
             "checkpoints and its Scan missions by Application; without one it cannot tell its own " +
@@ -355,6 +365,23 @@ export async function runWatchDispatch(ctx, deps = {}) {
         throw new Error("watch: the mission node set no `gitlab.project` in the task context, so there is no " +
             "project to poll.");
     }
+    // Checked here, not at the first trigger. The checked-in Scan mission requires
+    // all seven of its parameters — CUE refuses an incomplete render rather than
+    // substituting an empty string — so a watch missing one is already broken. It
+    // would otherwise poll cleanly for hours and fail on the first pipeline, at
+    // which point the failure looks like the pipeline's fault rather than the
+    // watch's configuration.
+    if (!w.scans) {
+        const missing = [
+            ...(repositoryUrl ? [] : ["repository.url"]),
+            ...(imageRef ? [] : ["image.ref"]),
+        ];
+        if (missing.length > 0) {
+            throw new Error(`watch: the mission node set no ${missing.join(" and no ")} in the task context. The ` +
+                "checked-in Scan mission requires every one of its seven parameters, so a Scan " +
+                "originated without these would be refused rather than run.");
+        }
+    }
     // A harness is opened unless every seam that would use one was injected.
     const needsHarness = !w.gitlab || !w.checkpoints || !w.scans || !w.credential;
     const opened = needsHarness && !deps.harness;
@@ -373,11 +400,7 @@ export async function runWatchDispatch(ctx, deps = {}) {
         const scans = w.scans ??
             harnessScanLauncher(harness, {
                 targetId,
-                inputs: {
-                    application,
-                    repositoryUrl: ctx.taskContext["repository.url"] || "",
-                    ...(ctx.taskContext["image.ref"] ? { imageRef: ctx.taskContext["image.ref"] } : {}),
-                },
+                inputs: { application, repositoryUrl, imageRef },
             });
         const intervalMs = Number(ctx.taskContext["watch.interval_ms"] || Number.NaN);
         const summary = await runWatchLoop({
@@ -412,6 +435,118 @@ export async function runWatchDispatch(ctx, deps = {}) {
             harness?.stop();
     }
 }
+/**
+ * The fix task, sandboxed (zerocool-plugins#89, finished in #96).
+ *
+ * What the always-on agent does after a Scan mission lands: read the
+ * Application's Findings over the task grant, work them in priority order,
+ * and for each one it can act on rewrite the repository, run the repository's
+ * own tests, and only then open a merge request that merges itself on a green
+ * pipeline. See `fix.ts` for why the order is tests-then-push and why this
+ * never marks a Finding `verified`.
+ *
+ * THE READ AND THE STATUS WRITE TRAVEL ON THE DISPATCH GRANT, not on a
+ * component identity — this process has none. `applicationFindings` and
+ * `observe` both reach the daemon as the task, so the run holds exactly the
+ * authority its dispatch granted.
+ *
+ * A REJECTED READ FAILS THE RUN. `harnessFindingSource` does not catch it, and
+ * neither does this: an unreachable graph reported as an empty backlog is a
+ * Fix that says the Application is clean while the backlog is live, and it
+ * reads identically to health.
+ *
+ * Task context keys it reads:
+ *   `zerocool.task`        selector, "fix"
+ *   `application`          the Application whose Findings are worked (required)
+ *   `gitlab.project`       `group/project` on the instance (required)
+ *   `gitlab.url`           instance base url; defaults to gitlab.com
+ *   `gitlab.ref`           branch merge requests target; defaults to `main`
+ *   `gitlab.credential`    tenant secret holding the project access token
+ *   `repository.commit`    the commit the Scan ran against — what the status lands on
+ *   `pipeline.url`         the pipeline page, linked from the commit status
+ *   `fix.max_merge_requests`  cap on merge requests opened in one pass
+ */
+export async function runFixDispatch(ctx, deps = {}) {
+    const f = deps.fix ?? {};
+    const application = ctx.taskContext.application || "";
+    const projectPath = ctx.taskContext["gitlab.project"] || "";
+    const targetRef = ctx.taskContext["gitlab.ref"] || DEFAULT_REF;
+    const commit = ctx.taskContext["repository.commit"] || "";
+    const credentialName = ctx.taskContext["gitlab.credential"] || "gitlab-token";
+    if (!application) {
+        throw new Error("fix: the mission node set no `application` in the task context. The Fix reads one " +
+            "Application's Findings and writes back to them; without one it cannot tell which " +
+            "backlog it is working.");
+    }
+    if (!f.gitlab && !projectPath) {
+        throw new Error("fix: the mission node set no `gitlab.project` in the task context, so there is no " +
+            "project to open a merge request against.");
+    }
+    // No default planner and no default workspace: see FixDeps. A Fix that
+    // cannot change anything or cannot test what it changed must not report a
+    // clean pass over a backlog it never touched.
+    if (!f.planner) {
+        throw new Error("fix: no planner was supplied, so this dispatch could only report every finding unfixed");
+    }
+    if (!f.workspace) {
+        throw new Error("fix: no workspace was supplied, so no change could be made or tested");
+    }
+    const needsHarness = !f.gitlab || !f.findings || !f.status || !f.credential;
+    const opened = needsHarness && !deps.harness;
+    const harness = needsHarness
+        ? (deps.harness ??
+            ((c) => openTaskHarness({ endpoint: c.callbackEndpoint, token: c.callbackToken, insecure: c.insecure ?? false })))(ctx)
+        : undefined;
+    try {
+        const gitlab = f.gitlab ??
+            gitlabRestWriter({
+                projectPath,
+                token: await (f.credential ?? harnessCredential(harness))(credentialName),
+                ...(ctx.taskContext["gitlab.url"] ? { baseUrl: ctx.taskContext["gitlab.url"] } : {}),
+            });
+        const findings = f.findings ?? harnessFindingSource(taskKnowledge(harness));
+        const status = f.status ??
+            harnessFindingStatus((entity) => observe(harness, { lifecycleEntity: entity }));
+        const cap = Number(ctx.taskContext["fix.max_merge_requests"] || Number.NaN);
+        const summary = await runFix({
+            application,
+            commit,
+            targetRef,
+            findings,
+            status,
+            planner: f.planner,
+            workspace: f.workspace,
+            gitlab,
+            ...(ctx.taskContext["pipeline.url"] ? { pipelineUrl: ctx.taskContext["pipeline.url"] } : {}),
+            ...(f.maxMergeRequests !== undefined
+                ? { maxMergeRequests: f.maxMergeRequests }
+                : Number.isFinite(cap) && cap > 0
+                    ? { maxMergeRequests: cap }
+                    : {}),
+            ...(deps.onEvent ? { onEvent: (e) => deps.onEvent?.(JSON.stringify(e)) } : {}),
+        });
+        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;
+        return {
+            output: `fix ${application}@${commit.slice(0, 12) || "unknown"}: ${fixing} merge request(s) opened, ` +
+                `${merged} merged, ${unfixed} left for a human`,
+            success: true,
+            metadata: {
+                task: "fix",
+                application,
+                commit,
+                fixing: String(fixing),
+                merged: String(merged),
+                unfixed: String(unfixed),
+            },
+        };
+    }
+    finally {
+        if (opened)
+            harness?.stop();
+    }
+}
 /**
  * Resolve a tenant secret through the harness on the dispatch grant. The value
  * is returned to the caller and never logged: it is the GitLab token, and the

package/dist/fix.d.ts

@@ -26,15 +26,14 @@ import type { FileChange, GitLabWriter, MergeRequest } from "./gitlab.js";
  * `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.
+ * THE TWO PLATFORM SEAMS ARE LIVE. Reading an Application's Findings and
+ * writing a Finding's status arrived on the TypeScript wire in
+ * `@zeroroot-ai/sdk@0.10.0` (sdk-ts#51), so {@link harnessFindingSource} and
+ * {@link harnessFindingStatus} below back {@link FindingSource} and
+ * {@link FindingStatusWriter} on the per-dispatch task grant. They stayed
+ * seams rather than becoming direct calls, which is what let this file be
+ * driven by stubs before the wire existed and still be driven by them in
+ * tests now that it does.
  */
 /** Severities, worst first. Used for the note's counts and for a stable order. */
 export declare const SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
@@ -50,12 +49,15 @@ export interface FixableFinding {
     /** 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). */
+    /**
+     * `P1`..`P4`, what a triage pass decided (gibson#1684). **Absent means no
+     * pass has decided yet, never "unimportant"** — see {@link byWorkOrder}.
+     */
     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. */
+/** Reads an Application's Findings. Backed by {@link harnessFindingSource}. */
 export interface FindingSource {
     /**
      * The Application's Findings in the given statuses, **in the order they
@@ -65,7 +67,7 @@ export interface FindingSource {
      */
     findings(application: string, statuses: string[]): Promise<FixableFinding[]>;
 }
-/** Moves a Finding through its statuses. Platform implementation pending sdk-ts#51. */
+/** Moves a Finding through its statuses. Backed by {@link harnessFindingStatus}. */
 export interface FindingStatusWriter {
     /** Record that a merge request now proposes this Finding's fix. */
     markFixing(findingId: string, mr: MergeRequest): Promise<void>;
@@ -205,3 +207,62 @@ export declare function statusDescription(summary: FixSummary): string;
 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;
+/**
+ * The order the Fix works Findings in: priority first, severity beneath it,
+ * then the Finding id so a pass over unchanged input is deterministic.
+ *
+ * Deterministic order matters beyond tidiness: the merge-request cap means the
+ * tail of this list is what gets deferred to the next pass, so an unstable
+ * sort would defer a different Finding each run and none would ever be worked.
+ */
+export declare function byWorkOrder(a: FixableFinding, b: FixableFinding): number;
+/**
+ * Read an Application's Findings over the task grant (sdk-ts#51).
+ *
+ * The rejection is deliberately NOT caught. `applicationFindings` throws when
+ * the graph is unreachable, and swallowing that into an empty list is the one
+ * failure this whole seam exists to prevent: the Fix would report a clean
+ * Application over a live backlog, and it would look exactly like health.
+ */
+export declare function harnessFindingSource(knowledge: KnowledgeReadsFindings): FindingSource;
+/** The single read the Fix needs from a knowledge source. */
+export interface KnowledgeReadsFindings {
+    applicationFindings(opts: {
+        application: string;
+        statuses?: string[];
+        limit?: number;
+    }): Promise<ReadFinding[]>;
+}
+/** The fields of an `ApplicationFinding` the Fix reads. */
+export interface ReadFinding {
+    findingId: string;
+    status: string;
+    severity: string;
+    vulnerabilityId: string;
+    placeLabel: string;
+    placeKey: string;
+    priority: string;
+}
+/** Writes one lifecycle sighting. Satisfied by the SDK's `observe`. */
+export type ObserveLifecycle = (entity: {
+    label: string;
+    idProperties: Record<string, string>;
+    properties?: Record<string, string>;
+}) => Promise<void>;
+/**
+ * Move a Finding through its statuses over the task grant (sdk-ts#51).
+ *
+ * The Finding is named by its `brain_id` in `idProperties`, so the write lands
+ * on the node the scan raised rather than creating a second one beside it.
+ *
+ * Only the properties this transition decides are sent. A sighting that omits
+ * a property leaves whatever an earlier one established; one that sets it to
+ * `""` erases it. The Fix decides a status and, when it has one, the merge
+ * request — it decides nothing about severity, priority or reason, so it sends
+ * none of them and cannot blank what the scan or a triage pass recorded.
+ *
+ * There is no `markVerified`, and there is no branch here that could reach it.
+ * `verified` follows a rescan not seeing the weakness again, and absence is not
+ * an observation this process can make (gibson#1686).
+ */
+export declare function harnessFindingStatus(observe: ObserveLifecycle): FindingStatusWriter;

package/dist/fix.js

@@ -25,15 +25,14 @@
  * `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.
+ * THE TWO PLATFORM SEAMS ARE LIVE. Reading an Application's Findings and
+ * writing a Finding's status arrived on the TypeScript wire in
+ * `@zeroroot-ai/sdk@0.10.0` (sdk-ts#51), so {@link harnessFindingSource} and
+ * {@link harnessFindingStatus} below back {@link FindingSource} and
+ * {@link FindingStatusWriter} on the per-dispatch task grant. They stayed
+ * seams rather than becoming direct calls, which is what let this file be
+ * driven by stubs before the wire existed and still be driven by them in
+ * tests now that it does.
  */
 /** Severities, worst first. Used for the note's counts and for a stable order. */
 export const SEVERITIES = ["critical", "high", "medium", "low", "info"];
@@ -253,3 +252,101 @@ function firstLines(output, n = 3) {
 function message(e) {
     return e instanceof Error ? e.message : String(e);
 }
+// --------------------------------------------------------------------------
+// the platform seams, backed by the task grant (zerocool-plugins#96)
+// --------------------------------------------------------------------------
+/**
+ * Priority order, worst first. `P1` is the most urgent thing a triage pass
+ * found; anything it has not ranked sorts AFTER everything it has.
+ *
+ * An unranked Finding is not a low-priority one — it is one no pass has
+ * decided about yet (gibson#1684). Ranking it as `P4` would be inventing a
+ * decision nobody took, and the triage agent's keep-previous rule would then
+ * preserve that invention on the next pass. So unranked sorts last among
+ * peers rather than being scored, and severity breaks the tie beneath it, so
+ * a critical unranked Finding still outranks a low unranked one.
+ */
+const PRIORITY_ORDER = ["p1", "p2", "p3", "p4"];
+function priorityRank(priority) {
+    const i = PRIORITY_ORDER.indexOf((priority ?? "").toLowerCase());
+    return i === -1 ? PRIORITY_ORDER.length : i;
+}
+function severityRank(severity) {
+    const i = SEVERITIES.indexOf(severity.toLowerCase());
+    return i === -1 ? SEVERITIES.length : i;
+}
+/**
+ * The order the Fix works Findings in: priority first, severity beneath it,
+ * then the Finding id so a pass over unchanged input is deterministic.
+ *
+ * Deterministic order matters beyond tidiness: the merge-request cap means the
+ * tail of this list is what gets deferred to the next pass, so an unstable
+ * sort would defer a different Finding each run and none would ever be worked.
+ */
+export function byWorkOrder(a, b) {
+    const p = priorityRank(a.priority) - priorityRank(b.priority);
+    if (p !== 0)
+        return p;
+    const s = severityRank(a.severity) - severityRank(b.severity);
+    if (s !== 0)
+        return s;
+    return a.id.localeCompare(b.id);
+}
+/**
+ * Read an Application's Findings over the task grant (sdk-ts#51).
+ *
+ * The rejection is deliberately NOT caught. `applicationFindings` throws when
+ * the graph is unreachable, and swallowing that into an empty list is the one
+ * failure this whole seam exists to prevent: the Fix would report a clean
+ * Application over a live backlog, and it would look exactly like health.
+ */
+export function harnessFindingSource(knowledge) {
+    return {
+        async findings(application, statuses) {
+            const found = await knowledge.applicationFindings({ application, statuses });
+            return found
+                .map((f) => ({
+                id: f.findingId,
+                status: f.status,
+                severity: f.severity,
+                vulnerabilityId: f.vulnerabilityId,
+                placeLabel: f.placeLabel,
+                placeKey: f.placeKey,
+                // Omitted rather than defaulted: empty means no pass has decided.
+                ...(f.priority ? { priority: f.priority } : {}),
+            }))
+                .sort(byWorkOrder);
+        },
+    };
+}
+/**
+ * Move a Finding through its statuses over the task grant (sdk-ts#51).
+ *
+ * The Finding is named by its `brain_id` in `idProperties`, so the write lands
+ * on the node the scan raised rather than creating a second one beside it.
+ *
+ * Only the properties this transition decides are sent. A sighting that omits
+ * a property leaves whatever an earlier one established; one that sets it to
+ * `""` erases it. The Fix decides a status and, when it has one, the merge
+ * request — it decides nothing about severity, priority or reason, so it sends
+ * none of them and cannot blank what the scan or a triage pass recorded.
+ *
+ * There is no `markVerified`, and there is no branch here that could reach it.
+ * `verified` follows a rescan not seeing the weakness again, and absence is not
+ * an observation this process can make (gibson#1686).
+ */
+export function harnessFindingStatus(observe) {
+    const write = (findingId, properties) => observe({ label: "Finding", idProperties: { brain_id: findingId }, properties });
+    return {
+        async markFixing(findingId, mr) {
+            await write(findingId, {
+                status: "fixing",
+                merge_request_iid: String(mr.iid),
+                merge_request_url: mr.webUrl,
+            });
+        },
+        async markFixed(findingId) {
+            await write(findingId, { status: "fixed" });
+        },
+    };
+}

package/dist/watch.d.ts

@@ -156,48 +156,40 @@ export declare function parseCheckpoint(text: string): {
 export declare function worldCheckpoints(harness: TaskHarness, application: string): WatchCheckpoints;
 /** The recall text for an application's checkpoints. Exported so a test names it once. */
 export declare function checkpointQueryText(application: string): string;
+/**
+ * The name of the checked-in Scan mission in gibson's mission catalog.
+ *
+ * One file in `internal/platform/missioncatalog/missions/` is one mission,
+ * named for its file: `scan.cue` is `"scan"`.
+ */
+export declare const SCAN_CATALOG_MISSION = "scan";
 /** What a Scan mission needs to know about the pipeline that triggered it. */
 export interface ScanMissionInputs {
     application: string;
     pipeline: Pipeline;
     /** The project's clone url, so the Scan mission knows what to check out. */
     repositoryUrl: string;
-    /** The image the pipeline built, when the watch was told how to name it. */
-    imageRef?: string;
-    /** The registered target the runtime scans are allowed to reach. */
-    targetId?: string;
+    /** The image the pipeline published, by digest. */
+    imageRef: string;
 }
 /**
- * The Scan mission definition, as canonical proto JSON.
- *
- * 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
- * mission schema is not re-exported from it.
+ * The seven parameters the checked-in Scan mission is rendered with.
+ *
+ * These names are the catalog's, not ours: `missioncatalog.Params.fields()` is
+ * the one declaration of them, and the daemon REFUSES an unrecognised key
+ * rather than ignoring it. That refusal is the smuggling defence — `Params` has
+ * no target or host field, so the runtime target binds from the mission's
+ * `target_id` alone and a caller cannot point a scan at a host the tenant never
+ * registered. A key renamed here without renaming it there fails loudly at the
+ * next launch, which is the intended outcome.
+ *
+ * Every one is required. CUE refuses an incomplete render rather than
+ * substituting an empty string, so a missing commit fails instead of scanning
+ * HEAD and a missing image fails instead of scanning nothing.
  */
-export declare function scanMissionDefinition(inputs: ScanMissionInputs): unknown;
+export declare function scanCatalogParams(inputs: ScanMissionInputs): Record<string, string>;
 /** The child mission's name, which is also how a person finds it in the dashboard. */
 export declare function scanMissionName(inputs: ScanMissionInputs): string;
-/**
- * Render a string map as `map<string, gibson.common.v1.TypedValue>` in
- * protojson. Every value the loop passes is a string, so every entry is a
- * `stringValue`.
- */
-export declare function typedContext(ctx: Record<string, string>): Record<string, {
-    stringValue: string;
-}>;
 export interface HarnessScanLauncherOptions {
     /** Everything but the pipeline, which the launcher fills in per trigger. */
     inputs: Omit<ScanMissionInputs, "pipeline">;
@@ -205,8 +197,6 @@ export interface HarnessScanLauncherOptions {
     targetId: string;
     /** Ceiling on one Scan. Defaults to {@link DEFAULT_SCAN_TIMEOUT_MS}. */
     scanTimeoutMs?: number;
-    /** Override the definition, so gibson#1660 can supply the real one. */
-    definition?: (inputs: ScanMissionInputs) => unknown;
 }
 /**
  * A {@link ScanLauncher} over the harness callbacks, on the dispatch grant.
@@ -215,5 +205,29 @@ export interface HarnessScanLauncherOptions {
  * daemon resolves the parent from this harness, so the Scan mission is a child
  * of the watch mission and inherits its tenant. Nothing in the request names a
  * parent, a tenant or an originator, so nothing here can widen them.
+ *
+ * THE MISSION IS NAMED, NOT BUILT (ADR-0018, gibson#1688). The Scan mission is
+ * checked into gibson's `missioncatalog` and that copy is authoritative; this
+ * launcher sends its name and seven parameters. It used to build its own graph,
+ * because `CreateMission` had no way to ask for the catalog's copy — two
+ * descriptions of one mission, which is the parallel definition ADR-0027
+ * forbids. There is no fallback to the old path: a definition that only one of
+ * the two knew about is the drift the single copy exists to prevent.
+ *
+ * The request goes through the SDK's `buildCreateMissionRequest` rather than
+ * being assembled here, because that builder normalises the one trap in this
+ * call. `JSON.stringify(undefined)` encodes to zero bytes but
+ * `JSON.stringify(null)` encodes to the four-byte string `"null"`, so a graph
+ * field filled in unconditionally puts a non-empty body on the wire beside the
+ * catalog name; the daemon refuses the pair, and the failure reads as "the
+ * catalog path does not work" rather than "you passed a null definition".
+ *
+ * The response is then sent by hand rather than through `createTaskMission`,
+ * for one reason: `CreateMissionResponse` carries an in-band `error`, and the
+ * daemon puts its most useful refusals there — an unknown parameter key naming
+ * the key and listing the known set, or every missing parameter reported at
+ * once. `createTaskMission` reads only `mission`, so those would surface as
+ * "returned no mission" and the operator would lose the sentence that says what
+ * to fix.
  */
 export declare function harnessScanLauncher(harness: TaskHarness, opts: HarnessScanLauncherOptions): ScanLauncher;

package/dist/watch.js

@@ -1,4 +1,4 @@
-import { remember, taskKnowledge } from "@zeroroot-ai/sdk";
+import { buildCreateMissionRequest, remember, taskKnowledge } from "@zeroroot-ai/sdk";
 import { TRIGGER_STATUS } from "./gitlab.js";
 /**
  * The always-on watch loop (zerocool-plugins#88).
@@ -222,81 +222,47 @@ export function worldCheckpoints(harness, application) {
 export function checkpointQueryText(application) {
     return `${CHECKPOINT_KIND} application=${application}`;
 }
+// ---------------------------------------------------------------------------
+// The Scan mission
+// ---------------------------------------------------------------------------
 /**
- * The Scan mission definition, as canonical proto JSON.
+ * The name of the checked-in Scan mission in gibson's mission catalog.
  *
- * 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.
+ * One file in `internal/platform/missioncatalog/missions/` is one mission,
+ * named for its file: `scan.cue` is `"scan"`.
+ */
+export const SCAN_CATALOG_MISSION = "scan";
+/**
+ * The seven parameters the checked-in Scan mission is rendered with.
  *
- * 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.
+ * These names are the catalog's, not ours: `missioncatalog.Params.fields()` is
+ * the one declaration of them, and the daemon REFUSES an unrecognised key
+ * rather than ignoring it. That refusal is the smuggling defence — `Params` has
+ * no target or host field, so the runtime target binds from the mission's
+ * `target_id` alone and a caller cannot point a scan at a host the tenant never
+ * registered. A key renamed here without renaming it there fails loudly at the
+ * next launch, which is the intended outcome.
  *
- * 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
- * mission schema is not re-exported from it.
+ * Every one is required. CUE refuses an incomplete render rather than
+ * substituting an empty string, so a missing commit fails instead of scanning
+ * HEAD and a missing image fails instead of scanning nothing.
  */
-export function scanMissionDefinition(inputs) {
-    const { application, pipeline } = inputs;
-    const context = {
-        "zerocool.task": "source-analysis",
-        application,
-        "pipeline.id": String(pipeline.id),
-        "pipeline.url": pipeline.webUrl,
-        "repository.url": inputs.repositoryUrl,
-        "repository.ref": pipeline.ref,
-        "repository.commit": pipeline.sha,
-        ...(inputs.imageRef ? { "image.ref": inputs.imageRef } : {}),
-        ...(inputs.targetId ? { "target.id": inputs.targetId } : {}),
-    };
+export function scanCatalogParams(inputs) {
+    const { pipeline } = inputs;
     return {
-        name: scanMissionName(inputs),
-        description: `Scan ${application} at ${pipeline.sha.slice(0, 12)}, originated by the always-on agent ` +
-            `for pipeline ${pipeline.id}.`,
-        version: "1.0.0",
-        nodes: {
-            scan: {
-                id: "scan",
-                type: "NODE_TYPE_AGENT",
-                name: "scan",
-                description: "Source analysis of the commit the pipeline built.",
-                agentConfig: {
-                    agentName: "zerocool",
-                    task: {
-                        id: "scan",
-                        goal: `Scan the ${application} repository at commit ${pipeline.sha} and submit a Finding for ` +
-                            "every real weakness you can support with evidence.",
-                        context: typedContext(context),
-                    },
-                },
-            },
-        },
-        entryPoints: ["scan"],
+        application: inputs.application,
+        repositoryUrl: inputs.repositoryUrl,
+        ref: pipeline.ref,
+        commit: pipeline.sha,
+        pipelineId: String(pipeline.id),
+        pipelineUrl: pipeline.webUrl,
+        imageRef: inputs.imageRef,
     };
 }
 /** The child mission's name, which is also how a person finds it in the dashboard. */
 export function scanMissionName(inputs) {
     return `scan ${inputs.application} pipeline ${inputs.pipeline.id}`;
 }
-/**
- * Render a string map as `map<string, gibson.common.v1.TypedValue>` in
- * protojson. Every value the loop passes is a string, so every entry is a
- * `stringValue`.
- */
-export function typedContext(ctx) {
-    const out = {};
-    for (const [k, v] of Object.entries(ctx)) {
-        if (v !== "")
-            out[k] = { stringValue: v };
-    }
-    return out;
-}
 /**
  * A {@link ScanLauncher} over the harness callbacks, on the dispatch grant.
  *
@@ -304,19 +270,43 @@ export function typedContext(ctx) {
  * daemon resolves the parent from this harness, so the Scan mission is a child
  * of the watch mission and inherits its tenant. Nothing in the request names a
  * parent, a tenant or an originator, so nothing here can widen them.
+ *
+ * THE MISSION IS NAMED, NOT BUILT (ADR-0018, gibson#1688). The Scan mission is
+ * checked into gibson's `missioncatalog` and that copy is authoritative; this
+ * launcher sends its name and seven parameters. It used to build its own graph,
+ * because `CreateMission` had no way to ask for the catalog's copy — two
+ * descriptions of one mission, which is the parallel definition ADR-0027
+ * forbids. There is no fallback to the old path: a definition that only one of
+ * the two knew about is the drift the single copy exists to prevent.
+ *
+ * The request goes through the SDK's `buildCreateMissionRequest` rather than
+ * being assembled here, because that builder normalises the one trap in this
+ * call. `JSON.stringify(undefined)` encodes to zero bytes but
+ * `JSON.stringify(null)` encodes to the four-byte string `"null"`, so a graph
+ * field filled in unconditionally puts a non-empty body on the wire beside the
+ * catalog name; the daemon refuses the pair, and the failure reads as "the
+ * catalog path does not work" rather than "you passed a null definition".
+ *
+ * The response is then sent by hand rather than through `createTaskMission`,
+ * for one reason: `CreateMissionResponse` carries an in-band `error`, and the
+ * daemon puts its most useful refusals there — an unknown parameter key naming
+ * the key and listing the known set, or every missing parameter reported at
+ * once. `createTaskMission` reads only `mission`, so those would surface as
+ * "returned no mission" and the operator would lose the sentence that says what
+ * to fix.
  */
 export function harnessScanLauncher(harness, opts) {
-    const build = opts.definition ?? scanMissionDefinition;
     const timeoutMs = BigInt(opts.scanTimeoutMs ?? DEFAULT_SCAN_TIMEOUT_MS);
     return {
         async launch(pipeline) {
-            const inputs = { ...opts.inputs, pipeline, targetId: opts.targetId };
-            const created = await harness.client.createMission({
-                context: harness.context,
-                missionDefinitionJson: new TextEncoder().encode(JSON.stringify(build(inputs))),
+            const inputs = { ...opts.inputs, pipeline };
+            const wire = buildCreateMissionRequest({
+                catalogMission: SCAN_CATALOG_MISSION,
+                catalogParams: scanCatalogParams(inputs),
                 targetId: opts.targetId,
                 name: scanMissionName(inputs),
             });
+            const created = await harness.client.createMission({ context: harness.context, ...wire });
             if (created.error) {
                 throw new Error(`CreateMission refused: ${created.error.message}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/zerocool",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "opencode plugin: Gibson platform integration (zerocool). Zero-config LLM, tools, findings, knowledge, delegate/missions.",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
     "test": "tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\""
   },
   "dependencies": {
-    "@zeroroot-ai/sdk": "^0.9.0"
+    "@zeroroot-ai/sdk": "^0.11.0"
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "*"