@zeroroot-ai/zerocool 0.3.1 → 0.5.0

package/dist/dispatch.d.ts

@@ -46,6 +46,8 @@
  *   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
  *   GIBSON_OPENCODE_SESSION_ID continue an earlier opencode session
  *   GIBSON_TIMEOUT_MS          hard deadline for the run, in ms
  *
@@ -53,8 +55,13 @@
  * {@link dispatchChildEnv} — that is the opencode plugin's own contract, fed from
  * the GIBSON_CG_JWT this process reads.
  */
-import type { AgentOutcome } from "@zeroroot-ai/sdk";
+import { type AgentOutcome, type TaskHarness } from "@zeroroot-ai/sdk";
+import { type FindingsBackend } from "./findings.js";
+import { type GitLabClient } from "./gitlab.js";
 import { runOpencode } from "./opencode-run.js";
+import type { SemgrepRunner } from "./semgrep.js";
+import { type ScanLauncher, type WatchCheckpoints } from "./watch.js";
+import { type TriageModel } from "./source-analysis.js";
 /**
  * The per-dispatch grant, as the sandbox injects it. The child authenticates its
  * harness callbacks with this; {@link dispatchChildEnv} renders it back to env.
@@ -75,6 +82,14 @@ export interface CallbackGrant {
 export interface DispatchContext extends CallbackGrant {
     /** `task.goal` — the natural-language objective the sandbox handed over. */
     goal: string;
+    /**
+     * `task.context` — the string map the mission node set. Selects the task kind
+     * (`zerocool.task`) and carries what a task needs beyond a goal: the
+     * repository url and commit, a sub-path, the target id.
+     */
+    taskContext: Record<string, string>;
+    /** `GIBSON_MISSION_ID`, so a Finding names the mission it belongs to. */
+    missionId?: string;
     /** opencode edits files here; it is the run's workspace. */
     workspace: string;
     /** `provider/model`, e.g. `gibson/default`. Omitted lets opencode choose. */
@@ -101,6 +116,48 @@ export declare function dispatchChildEnv(g: CallbackGrant): NodeJS.ProcessEnv;
  * here rather than run opencode against an empty or malformed prompt.
  */
 export declare function decodeTaskGoal(taskB64: string | undefined): string;
+/** The parts of a `gibson.types.v1.Task` a dispatch reads. */
+export interface DecodedTask {
+    goal: string;
+    context: Record<string, string>;
+    metadata: Record<string, string>;
+}
+/**
+ * Decode the whole Task: the goal, and the `context` and `metadata` string
+ * maps a mission node sets. protojson renders both as plain objects, so a
+ * value that is not a string is dropped rather than guessed at.
+ */
+export declare function decodeTask(taskB64: string | undefined): DecodedTask;
+/**
+ * Read one `Task.context` / `Task.metadata` entry as a string.
+ *
+ * Both maps are `map<string, gibson.common.v1.TypedValue>`, so canonical
+ * protojson renders every value as a one-key object naming the oneof arm —
+ * `{"stringValue":"source-analysis"}`, `{"intValue":"42"}` — never as a bare
+ * string. gibson marshals the Task with `protojson.Marshal` over
+ * `agent.TaskToProto`, which wraps each entry with `mapToTypedValueMap`, so
+ * this is the only shape a dispatched agent ever receives. Reading these maps
+ * as plain strings silently dropped every entry, which is why a mission node's
+ * `zerocool.task`, `repository.commit` and `target.id` never reached the run.
+ *
+ * A bare string is still accepted, because a hand-built Task written as plain
+ * JSON is the normal way to drive a dispatch by hand. Both snake_case and
+ * lowerCamel arm names are read: protojson emits lowerCamel by default but can
+ * be told to keep the proto field names, and a decoder that accepts only one of
+ * them fails on a Task that is otherwise valid.
+ *
+ * `nullValue` yields no entry: a null is the absence of a value, and rendering
+ * it as the string "null" would hand a task a target id of `"null"`.
+ */
+export declare function typedValueString(val: unknown): string | undefined;
+/** The task kinds a sandboxed dispatch can serve. */
+export type DispatchTaskKind = "opencode" | "source-analysis" | "watch";
+/**
+ * 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.
+ * Anything unrecognized is the default: drive opencode on the goal.
+ */
+export declare function dispatchTaskKind(ctx: Pick<DispatchContext, "taskContext">, env?: NodeJS.ProcessEnv): DispatchTaskKind;
 /**
  * Read one sandboxed dispatch's context from the environment.
  *
@@ -123,6 +180,28 @@ export interface DispatchDeps {
     run?: typeof runOpencode;
     /** Live tap for each NDJSON event opencode prints. */
     onEvent?: (line: string) => void;
+    /** Source-analysis seams: no semgrep binary, no model, no daemon in a test. */
+    semgrep?: SemgrepRunner;
+    model?: TriageModel;
+    findings?: FindingsBackend;
+    /** Opens the task harness. Defaults to `openTaskHarness` on the dispatch grant. */
+    harness?: (ctx: DispatchContext) => TaskHarness;
+    /** Force the task kind, over the Task's own context. */
+    taskKind?: DispatchTaskKind;
+    /** Watch seams: no GitLab, no World and no child missions in a test. */
+    watch?: WatchDeps;
+}
+/** The watch task's injectable seams. Everything the loop reaches out through. */
+export interface WatchDeps {
+    gitlab?: GitLabClient;
+    checkpoints?: WatchCheckpoints;
+    scans?: ScanLauncher;
+    /** Resolve the GitLab token. Defaults to the harness `GetCredential`. */
+    credential?: (name: string) => Promise<string>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Bound the loop. Unset runs until the sandbox is torn down. */
+    maxPolls?: number;
+    signal?: AbortSignal;
 }
 /**
  * Run one dispatched Task headless and map it to a terminal outcome.
@@ -133,6 +212,42 @@ export interface DispatchDeps {
  * into a failed terminal result and a non-zero exit.
  */
 export declare function runDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
+/**
+ * The source-analysis task, sandboxed (zerocool-plugins#87). opencode is not
+ * involved: semgrep produces candidates, the model triages them through the
+ * harness `LLMComplete` on the task grant, and real ones are submitted through
+ * the harness `SubmitFinding` on the same grant. The task reads the checkout
+ * (the workspace, or `source.path` under it) and changes nothing.
+ *
+ * Task context keys it reads: `zerocool.task` (selector), `source.path`,
+ * `repository.url`, `repository.commit`, `target.id`.
+ */
+export declare function runSourceAnalysisDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
+/**
+ * The watch task, sandboxed (zerocool-plugins#88). The always-on shape: this
+ * dispatch does not finish until the mission is cancelled or the sandbox is
+ * torn down. It polls the application's GitLab project and originates a Scan
+ * mission per finished pipeline on the branch, from inside this very mission
+ * (ADR-0063). See `watch.ts` for why the agent polls rather than CI calling in.
+ *
+ * Task context keys it reads:
+ *   `zerocool.task`        selector, "watch"
+ *   `application`          the Application this watch follows (required)
+ *   `gitlab.project`       `group/project` on the instance (required)
+ *   `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
+ *   `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>;
+/**
+ * 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
+ * console stream this dispatch writes is shown in the browser.
+ */
+export declare function harnessCredential(harness: TaskHarness): (name: string) => Promise<string>;
 /**
  * Render a terminal outcome as the last NDJSON line on stdout.
  *

package/dist/dispatch.js

@@ -1,5 +1,67 @@
 #!/usr/bin/env node
+/**
+ * zerocool-dispatch — one sandboxed dispatched run, then exit.
+ *
+ * The third dispatched shape, and the one gibson launches (zerocool-plugins#57,
+ * gibson#1596, ADR-0016). `zerocool-agent` and `zerocool-serve` are long-lived
+ * hosts that enroll once, keep a host key, and POLL the daemon for work. This is
+ * the opposite: gibson runs an untrusted agent by launching an ephemeral setec
+ * sandbox per mission run and injecting the run's credentials as environment. So
+ * there is no enrollment, no host key, and no poll loop — the task and the grant
+ * are already in the environment when the process starts, and the process serves
+ * exactly one dispatch and exits so the sandbox is torn down.
+ *
+ * WHAT REPLACES THE BOOTSTRAP TOKEN. The poll-loop shapes authenticate as a
+ * long-lived COMPONENT: a human mints a one-time `GIBSON_BOOTSTRAP_TOKEN`, the
+ * first run trades it for a persistent host key, and every later run re-registers
+ * with that key (ADR-0045). A sandboxed run has neither. It authenticates with
+ * the PER-DISPATCH capability grant gibson mints for this run and injects as
+ * `GIBSON_CALLBACK_ENDPOINT` + `GIBSON_CG_JWT`. That grant carries exactly the
+ * authority of this dispatch, so this process never reads a bootstrap token and
+ * never touches a host key.
+ *
+ * THE CALLBACKS ARE GRANT-AUTHENTICATED. This process drives `opencode run`
+ * headless and passes the per-dispatch grant to the child (see
+ * {@link dispatchChildEnv}). The child's mission callbacks — findings, tool
+ * calls, knowledge reads — then reach the daemon's harness callback listener as
+ * the TASK, on the injected grant, not as some enrolled component (see
+ * `knowledge-source.ts`).
+ *
+ * THE OUTPUT IS A LIVE NDJSON STREAM. Every event opencode prints is forwarded
+ * to this process's stdout as it arrives, so the daemon can stream the run to the
+ * read-only console (a later slice consumes it). The last line is the terminal
+ * result. stdout is therefore a clean event stream — the driver's own logs go to
+ * stderr — and a clean exit lets the sandbox tear down.
+ *
+ * Environment (injected by the sandbox launch):
+ *
+ * These names are gibson's canonical dispatch contract — the constants in gibson
+ * `internal/engine/harness/sandboxed/agent.go` (envAgent*). This process conforms
+ * to them; it does not define its own.
+ *
+ *   GIBSON_CALLBACK_ENDPOINT   per-dispatch harness callback dial target (required)
+ *   GIBSON_CG_JWT              per-dispatch capability grant (CG-JWT)    (required)
+ *   GIBSON_AGENT_TASK_B64      base64 protojson gibson.types.v1.Task     (required)
+ *   GIBSON_MODEL               provider/model resolved for the tenant at dispatch
+ *   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
+ *   GIBSON_OPENCODE_SESSION_ID continue an earlier opencode session
+ *   GIBSON_TIMEOUT_MS          hard deadline for the run, in ms
+ *
+ * The child `opencode run` still receives the grant as GIBSON_CALLBACK_TOKEN via
+ * {@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 { join } from "node:path";
+import { taskFindingsBackend } from "./findings.js";
+import { gitlabRest } 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";
 /**
  * Render the per-dispatch grant back to environment for the opencode child, so
  * the child's harness callbacks travel on the task grant rather than on any
@@ -26,6 +88,14 @@ export function dispatchChildEnv(g) {
  * here rather than run opencode against an empty or malformed prompt.
  */
 export function decodeTaskGoal(taskB64) {
+    return decodeTask(taskB64).goal;
+}
+/**
+ * Decode the whole Task: the goal, and the `context` and `metadata` string
+ * maps a mission node sets. protojson renders both as plain objects, so a
+ * value that is not a string is dropped rather than guessed at.
+ */
+export function decodeTask(taskB64) {
     if (!taskB64) {
         throw new Error("GIBSON_AGENT_TASK_B64 is not set. The sandbox launch injects the task to pursue as the " +
             "base64 protojson of a gibson.types.v1.Task; without it there is nothing to run.");
@@ -43,7 +113,77 @@ export function decodeTaskGoal(taskB64) {
         throw new Error("GIBSON_AGENT_TASK_B64 decoded to a Task with no goal. Running opencode against an empty " +
             "prompt would report whatever it says back as a mission result.");
     }
-    return goal;
+    return { goal, context: stringMap(task.context), metadata: stringMap(task.metadata) };
+}
+function stringMap(v) {
+    if (!v || typeof v !== "object")
+        return {};
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        const s = typedValueString(val);
+        if (s !== undefined)
+            out[k] = s;
+    }
+    return out;
+}
+/**
+ * Read one `Task.context` / `Task.metadata` entry as a string.
+ *
+ * Both maps are `map<string, gibson.common.v1.TypedValue>`, so canonical
+ * protojson renders every value as a one-key object naming the oneof arm —
+ * `{"stringValue":"source-analysis"}`, `{"intValue":"42"}` — never as a bare
+ * string. gibson marshals the Task with `protojson.Marshal` over
+ * `agent.TaskToProto`, which wraps each entry with `mapToTypedValueMap`, so
+ * this is the only shape a dispatched agent ever receives. Reading these maps
+ * as plain strings silently dropped every entry, which is why a mission node's
+ * `zerocool.task`, `repository.commit` and `target.id` never reached the run.
+ *
+ * A bare string is still accepted, because a hand-built Task written as plain
+ * JSON is the normal way to drive a dispatch by hand. Both snake_case and
+ * lowerCamel arm names are read: protojson emits lowerCamel by default but can
+ * be told to keep the proto field names, and a decoder that accepts only one of
+ * them fails on a Task that is otherwise valid.
+ *
+ * `nullValue` yields no entry: a null is the absence of a value, and rendering
+ * it as the string "null" would hand a task a target id of `"null"`.
+ */
+export function typedValueString(val) {
+    if (typeof val === "string")
+        return val;
+    if (!val || typeof val !== "object")
+        return undefined;
+    const v = val;
+    const arm = (camel, snake) => (v[camel] !== undefined ? v[camel] : v[snake]);
+    const s = arm("stringValue", "string_value");
+    if (typeof s === "string")
+        return s;
+    // protojson renders int64 and uint64 as strings, and double as a number.
+    const i = arm("intValue", "int_value");
+    if (typeof i === "string" || typeof i === "number")
+        return String(i);
+    const u = arm("uintValue", "uint_value");
+    if (typeof u === "string" || typeof u === "number")
+        return String(u);
+    const d = arm("doubleValue", "double_value");
+    if (typeof d === "number")
+        return String(d);
+    const b = arm("boolValue", "bool_value");
+    if (typeof b === "boolean")
+        return String(b);
+    return undefined;
+}
+/**
+ * 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.
+ * Anything unrecognized is the default: drive opencode on the goal.
+ */
+export function dispatchTaskKind(ctx, env = {}) {
+    const kind = env.ZEROCOOL_TASK ?? ctx.taskContext["zerocool.task"] ?? "";
+    if (kind === "source-analysis")
+        return "source-analysis";
+    if (kind === "watch")
+        return "watch";
+    return "opencode";
 }
 /**
  * Read one sandboxed dispatch's context from the environment.
@@ -71,7 +211,7 @@ export function readDispatchContext(env, opts = {}) {
             "grant to authenticate with; a sandboxed run must not fall back to any other identity, " +
             "so this fails instead.");
     }
-    const goal = decodeTaskGoal(env.GIBSON_AGENT_TASK_B64);
+    const task = decodeTask(env.GIBSON_AGENT_TASK_B64);
     const timeoutRaw = env.GIBSON_TIMEOUT_MS ? Number(env.GIBSON_TIMEOUT_MS) : 0;
     return {
         callbackEndpoint: endpoint,
@@ -80,7 +220,9 @@ export function readDispatchContext(env, opts = {}) {
         missionRunId: env.GIBSON_MISSION_RUN_ID ?? "",
         agentRunId: env.GIBSON_AGENT_RUN_ID ?? "",
         traceId: env.GIBSON_TRACE_ID ?? "",
-        goal,
+        goal: task.goal,
+        taskContext: task.context,
+        ...(env.GIBSON_MISSION_ID ? { missionId: env.GIBSON_MISSION_ID } : {}),
         workspace: env.ZEROCOOL_WORKSPACE ?? opts.cwd ?? process.cwd(),
         ...(env.GIBSON_MODEL ? { model: env.GIBSON_MODEL } : {}),
         ...(env.GIBSON_OPENCODE_SESSION_ID ? { sessionId: env.GIBSON_OPENCODE_SESSION_ID } : {}),
@@ -96,6 +238,13 @@ export function readDispatchContext(env, opts = {}) {
  * into a failed terminal result and a non-zero exit.
  */
 export async function runDispatch(ctx, deps = {}) {
+    const kind = deps.taskKind ?? dispatchTaskKind(ctx, process.env);
+    if (kind === "source-analysis") {
+        return runSourceAnalysisDispatch(ctx, deps);
+    }
+    if (kind === "watch") {
+        return runWatchDispatch(ctx, deps);
+    }
     const run = deps.run ?? runOpencode;
     const result = await run({
         goal: ctx.goal,
@@ -118,6 +267,173 @@ export async function runDispatch(ctx, deps = {}) {
         },
     };
 }
+/**
+ * The source-analysis task, sandboxed (zerocool-plugins#87). opencode is not
+ * involved: semgrep produces candidates, the model triages them through the
+ * harness `LLMComplete` on the task grant, and real ones are submitted through
+ * the harness `SubmitFinding` on the same grant. The task reads the checkout
+ * (the workspace, or `source.path` under it) and changes nothing.
+ *
+ * Task context keys it reads: `zerocool.task` (selector), `source.path`,
+ * `repository.url`, `repository.commit`, `target.id`.
+ */
+export async function runSourceAnalysisDispatch(ctx, deps = {}) {
+    const opened = !deps.harness && !(deps.model && deps.findings);
+    const harness = deps.model && deps.findings
+        ? undefined
+        : (deps.harness ?? ((c) => openTaskHarness({ endpoint: c.callbackEndpoint, token: c.callbackToken, insecure: c.insecure ?? false })))(ctx);
+    const model = deps.model ?? harnessTriageModel(harness);
+    const findings = deps.findings ?? taskFindingsBackend(harness);
+    const sub = ctx.taskContext["source.path"];
+    const dir = sub ? join(ctx.workspace, sub) : ctx.workspace;
+    try {
+        const summary = await runSourceAnalysis({
+            dir,
+            model,
+            findings,
+            ...(deps.semgrep ? { semgrep: deps.semgrep } : {}),
+            ...(ctx.timeoutMs > 0 ? { semgrepTimeoutMs: ctx.timeoutMs } : {}),
+            provenance: {
+                ...(ctx.missionId ? { missionId: ctx.missionId } : {}),
+                ...(ctx.taskContext["repository.url"] ? { repository: ctx.taskContext["repository.url"] } : {}),
+                ...(ctx.taskContext["repository.commit"] ? { commit: ctx.taskContext["repository.commit"] } : {}),
+                ...(ctx.taskContext["target.id"] ? { targetId: ctx.taskContext["target.id"] } : {}),
+            },
+            ...(deps.onEvent ? { onEvent: (event) => deps.onEvent?.(JSON.stringify(event)) } : {}),
+        });
+        return {
+            output: formatSourceAnalysis(summary),
+            success: true,
+            findingIds: summary.findingIds,
+            metadata: {
+                task: "source-analysis",
+                matches: String(summary.matches),
+                candidates: String(summary.candidates),
+                real: String(summary.real),
+                noise: String(summary.noise),
+                submitted: String(summary.findingIds.length),
+                failed: String(summary.failed.length),
+            },
+        };
+    }
+    finally {
+        if (opened)
+            harness?.stop();
+    }
+}
+/**
+ * The watch task, sandboxed (zerocool-plugins#88). The always-on shape: this
+ * dispatch does not finish until the mission is cancelled or the sandbox is
+ * torn down. It polls the application's GitLab project and originates a Scan
+ * mission per finished pipeline on the branch, from inside this very mission
+ * (ADR-0063). See `watch.ts` for why the agent polls rather than CI calling in.
+ *
+ * Task context keys it reads:
+ *   `zerocool.task`        selector, "watch"
+ *   `application`          the Application this watch follows (required)
+ *   `gitlab.project`       `group/project` on the instance (required)
+ *   `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
+ *   `target.id`            the registered target each Scan mission binds to
+ *   `watch.interval_ms`    poll cadence; defaults to 30s
+ */
+export async function runWatchDispatch(ctx, deps = {}) {
+    const w = deps.watch ?? {};
+    const application = ctx.taskContext.application || "";
+    const projectPath = ctx.taskContext["gitlab.project"] || "";
+    const ref = ctx.taskContext["gitlab.ref"] || DEFAULT_REF;
+    const targetId = ctx.taskContext["target.id"] || "";
+    const credentialName = ctx.taskContext["gitlab.credential"] || "gitlab-token";
+    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 " +
+            "state from another watch's.");
+    }
+    if (!w.gitlab && !projectPath) {
+        throw new Error("watch: the mission node set no `gitlab.project` in the task context, so there is no " +
+            "project to poll.");
+    }
+    // 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;
+    const harness = needsHarness
+        ? (deps.harness ??
+            ((c) => openTaskHarness({ endpoint: c.callbackEndpoint, token: c.callbackToken, insecure: c.insecure ?? false })))(ctx)
+        : undefined;
+    try {
+        const gitlab = w.gitlab ??
+            gitlabRest({
+                projectPath,
+                token: await (w.credential ?? harnessCredential(harness))(credentialName),
+                ...(ctx.taskContext["gitlab.url"] ? { baseUrl: ctx.taskContext["gitlab.url"] } : {}),
+            });
+        const checkpoints = w.checkpoints ?? worldCheckpoints(harness, application);
+        const scans = w.scans ??
+            harnessScanLauncher(harness, {
+                targetId,
+                inputs: {
+                    application,
+                    repositoryUrl: ctx.taskContext["repository.url"] || "",
+                    ...(ctx.taskContext["image.ref"] ? { imageRef: ctx.taskContext["image.ref"] } : {}),
+                },
+            });
+        const intervalMs = Number(ctx.taskContext["watch.interval_ms"] || Number.NaN);
+        const summary = await runWatchLoop({
+            application,
+            ref,
+            gitlab,
+            checkpoints,
+            scans,
+            ...(Number.isFinite(intervalMs) && intervalMs > 0 ? { intervalMs } : {}),
+            ...(w.maxPolls !== undefined ? { maxPolls: w.maxPolls } : {}),
+            ...(w.signal ? { signal: w.signal } : {}),
+            ...(w.sleep ? { sleep: w.sleep } : {}),
+            ...(deps.onEvent ? { onEvent: (e) => deps.onEvent?.(JSON.stringify(e)) } : {}),
+        });
+        return {
+            output: `watch ${application}@${ref}: ${summary.polls} polls, ${summary.scans} scan missions, ` +
+                `${summary.errors} errors; last pipeline ${summary.lastPipelineId || "none"}`,
+            success: true,
+            metadata: {
+                task: "watch",
+                application,
+                ref,
+                polls: String(summary.polls),
+                scans: String(summary.scans),
+                errors: String(summary.errors),
+                last_pipeline_id: String(summary.lastPipelineId),
+            },
+        };
+    }
+    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
+ * console stream this dispatch writes is shown in the browser.
+ */
+export function harnessCredential(harness) {
+    return async (name) => {
+        const res = await harness.client.getCredential({ context: harness.context, name });
+        if (res.error) {
+            throw new Error(`GetCredential(${name}) refused: ${res.error.message}`);
+        }
+        const secret = res.credential?.secretData;
+        const value = secret?.case === "apiKey" || secret?.case === "bearerToken" || secret?.case === "customSecret"
+            ? secret.value
+            : undefined;
+        if (!value) {
+            throw new Error(`GetCredential(${name}) returned no usable secret. A GitLab project access token is ` +
+                "stored as an api key, a bearer token, or a single-valued custom secret.");
+        }
+        return value;
+    };
+}
 /**
  * Render a terminal outcome as the last NDJSON line on stdout.
  *

package/dist/findings.d.ts

@@ -1,5 +1,5 @@
 import type { ToolDefinition } from "@opencode-ai/plugin";
-import { type Finding, type GibsonSession } from "@zeroroot-ai/sdk";
+import { type Finding, type GibsonSession, type TaskHarness } from "@zeroroot-ai/sdk";
 export interface FindingsBackend {
     /** Submit a finding; returns the identifier it was recorded under. */
     submit(f: Finding): Promise<string>;
@@ -8,6 +8,14 @@ export interface FindingsBackend {
 }
 /** Platform backend — findings land in the tenant knowledge graph. */
 export declare function gibsonFindingsBackend(session: GibsonSession): FindingsBackend;
+/**
+ * Task backend — the callback service's typed `SubmitFinding` under the
+ * per-dispatch grant, so a sandboxed run's findings are attributed to the TASK
+ * (mission and run), never to a component identity the sandbox does not hold.
+ * Fields map from the SDK's JSON finding onto `gibson.types.v1.Finding`; the
+ * daemon keeps the id `newFinding` minted. Same mapping as claude-gibson's.
+ */
+export declare function taskFindingsBackend(harness: TaskHarness): FindingsBackend;
 /**
  * Standalone backend — findings are appended as JSONL. The same Finding shape is
  * written, so a local log can be replayed into Gibson later.

package/dist/findings.js

@@ -26,6 +26,42 @@ export function gibsonFindingsBackend(session) {
         describe: () => "the tenant Gibson graph",
     };
 }
+/**
+ * Task backend — the callback service's typed `SubmitFinding` under the
+ * per-dispatch grant, so a sandboxed run's findings are attributed to the TASK
+ * (mission and run), never to a component identity the sandbox does not hold.
+ * Fields map from the SDK's JSON finding onto `gibson.types.v1.Finding`; the
+ * daemon keeps the id `newFinding` minted. Same mapping as claude-gibson's.
+ */
+export function taskFindingsBackend(harness) {
+    const severity = (s) => ({ critical: 1, high: 2, medium: 3, low: 4, info: 5 })[s] ?? 0;
+    return {
+        submit: async (f) => {
+            const res = await harness.client.submitFinding({
+                context: harness.context,
+                finding: {
+                    id: f.id,
+                    missionId: f.mission_id,
+                    agentName: f.agent_name,
+                    title: f.title,
+                    description: f.description,
+                    category: f.category,
+                    severity: severity(f.severity),
+                    confidence: f.confidence,
+                    remediation: f.remediation ?? "",
+                    targetId: f.target_id ?? "",
+                    tags: f.tags ?? [],
+                    references: f.references ?? [],
+                    evidence: (f.evidence ?? []).map((e) => ({ type: e.type, title: e.title, content: e.content })),
+                },
+            });
+            if (res.error)
+                throw new Error(`SubmitFinding refused: ${res.error.message}`);
+            return f.id;
+        },
+        describe: () => "the tenant Gibson graph (dispatch grant)",
+    };
+}
 /**
  * Standalone backend — findings are appended as JSONL. The same Finding shape is
  * written, so a local log can be replayed into Gibson later.

package/dist/gitlab.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 declare const TRIGGER_STATUS = "success";
+/** GitLab's public host, when a tenant names no other instance. */
+export declare const GITLAB_DEFAULT_URL = "https://gitlab.com";
+/** One pipeline, reduced to what a trigger decision and a Scan mission need. */
+export interface Pipeline {
+    /** GitLab's own pipeline id. Monotonic per project, and the checkpoint key. */
+    id: number;
+    /** The commit the pipeline ran on — the Scan mission's `repository.commit`. */
+    sha: string;
+    /** `success` for anything this module returns; carried for the console line. */
+    status: string;
+    /** The branch, echoed back so a caller can log what it matched. */
+    ref: string;
+    /** GitLab's page for the pipeline, for the console line and the MR note. */
+    webUrl: string;
+}
+/** The GitLab reads the watch loop makes. One method, so a stub is three lines. */
+export interface GitLabClient {
+    /**
+     * The most recent successful pipeline on `ref`, or `undefined` when the
+     * project has none. Rejects when GitLab refuses or is unreachable — the loop
+     * reports that and keeps polling.
+     */
+    latestFinishedPipeline(ref: string): Promise<Pipeline | undefined>;
+}
+/** What {@link gitlabRest} needs to reach one project. */
+export interface GitLabRestOptions {
+    /** `group/project`, unencoded. Encoded once here, at the call. */
+    projectPath: string;
+    /** The project access token, resolved from the tenant secret store. */
+    token: string;
+    /** The instance. Defaults to {@link GITLAB_DEFAULT_URL}. */
+    baseUrl?: string;
+    /** Injectable transport. Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * 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 declare function parsePipeline(raw: unknown): Pipeline | undefined;
+/**
+ * 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 declare function gitlabRest(opts: GitLabRestOptions): GitLabClient;