@zeroroot-ai/zerocool 0.9.1 → 0.9.3

package/dist/dispatch.d.ts

@@ -39,9 +39,9 @@
  * launcher names — GIBSON_CG_JWT, GIBSON_CALLBACK_ENDPOINT,
  * GIBSON_AGENT_TASK_B64, GIBSON_MISSION_ID, GIBSON_MISSION_RUN_ID,
  * GIBSON_AGENT_RUN_ID, GIBSON_MODEL, GIBSON_TRACE_ID, GIBSON_SPAN_ID — are
- * spelled in the SDK, against gibson `internal/engine/harness/sandboxed/agent.go`
- * (the `envAgent*` constants). This file spells none of them. A second spelling
- * here is how the two drift, which is the defect zerocool-plugins#7 records.
+ * spelled in the SDK, against the launcher's own constants. This file spells
+ * none of them. A second spelling here is how the two drift, which is the
+ * defect zerocool-plugins#7 records.
  *
  * FOUR VARIABLES ARE STILL READ HERE, and every one of them is a local option
  * of this host rather than part of the launcher contract. The launcher never
@@ -189,6 +189,8 @@ export interface DispatchDeps {
     watch?: WatchDeps;
     /** Fix seams: no GitLab, no graph and no checkout in a test. */
     fix?: FixDeps;
+    /** The component's environment, where the connector configuration lives. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * The fix task's injectable seams.
@@ -254,7 +256,8 @@ export declare function runSourceAnalysisDispatch(ctx: DispatchContext, deps?: D
  *   `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.url`           instance base url, https, host in ZEROCOOL_GITLAB_HOSTS;
+ *                          defaults to the one allowed host
  *   `gitlab.ref`           branch to watch; defaults to `main`
  *   `gitlab.credential`    tenant secret holding the project access token
  *   `repository.url`       clone url the Scan mission checks out (required)
@@ -287,12 +290,15 @@ export declare function runWatchDispatch(ctx: DispatchContext, deps?: DispatchDe
  *   `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.url`           instance base url, https, host in ZEROCOOL_GITLAB_HOSTS;
+ *                          defaults to the one allowed host
  *   `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
+ *   `fix.auto_merge`       `true` arms merge-when-pipeline-succeeds on the merge
+ *                          requests this pass opens. Default off: a person merges.
  */
 export declare function runFixDispatch(ctx: DispatchContext, deps?: DispatchDeps): Promise<AgentOutcome>;
 /**

package/dist/dispatch.js

@@ -41,9 +41,9 @@
  * launcher names — GIBSON_CG_JWT, GIBSON_CALLBACK_ENDPOINT,
  * GIBSON_AGENT_TASK_B64, GIBSON_MISSION_ID, GIBSON_MISSION_RUN_ID,
  * GIBSON_AGENT_RUN_ID, GIBSON_MODEL, GIBSON_TRACE_ID, GIBSON_SPAN_ID — are
- * spelled in the SDK, against gibson `internal/engine/harness/sandboxed/agent.go`
- * (the `envAgent*` constants). This file spells none of them. A second spelling
- * here is how the two drift, which is the defect zerocool-plugins#7 records.
+ * spelled in the SDK, against the launcher's own constants. This file spells
+ * none of them. A second spelling here is how the two drift, which is the
+ * defect zerocool-plugins#7 records.
  *
  * FOUR VARIABLES ARE STILL READ HERE, and every one of them is a local option
  * of this host rather than part of the launcher contract. The launcher never
@@ -65,7 +65,7 @@ import { observe, readSandboxDispatch, sandboxHarness, taskKnowledge, } from "@z
 import { join } from "node:path";
 import { taskFindingsBackend } from "./findings.js";
 import { harnessFindingSource, harnessFindingStatus, runFix, } from "./fix.js";
-import { gitlabRest, gitlabRestWriter } from "./gitlab.js";
+import { allowedGitLabHosts, gitlabRest, gitlabRestWriter, resolveGitLabBaseUrl } 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";
@@ -293,7 +293,8 @@ export async function runSourceAnalysisDispatch(ctx, deps = {}) {
  *   `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.url`           instance base url, https, host in ZEROCOOL_GITLAB_HOSTS;
+ *                          defaults to the one allowed host
  *   `gitlab.ref`           branch to watch; defaults to `main`
  *   `gitlab.credential`    tenant secret holding the project access token
  *   `repository.url`       clone url the Scan mission checks out (required)
@@ -319,6 +320,9 @@ 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.");
     }
+    // The host the tenant's token is sent to is checked before the token is
+    // fetched, against the connector configuration and never the mission node.
+    const gitlabBaseUrl = w.gitlab ? undefined : resolveGitLabBaseUrl(ctx.taskContext["gitlab.url"], allowedGitLabHosts(deps.env ?? process.env));
     // 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
@@ -345,7 +349,7 @@ export async function runWatchDispatch(ctx, deps = {}) {
             gitlabRest({
                 projectPath,
                 token: await (w.credential ?? harnessCredential(harness))(credentialName),
-                ...(ctx.taskContext["gitlab.url"] ? { baseUrl: ctx.taskContext["gitlab.url"] } : {}),
+                baseUrl: gitlabBaseUrl,
             });
         const checkpoints = w.checkpoints ?? worldCheckpoints(harness, application);
         const scans = w.scans ??
@@ -410,12 +414,15 @@ export async function runWatchDispatch(ctx, deps = {}) {
  *   `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.url`           instance base url, https, host in ZEROCOOL_GITLAB_HOSTS;
+ *                          defaults to the one allowed host
  *   `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
+ *   `fix.auto_merge`       `true` arms merge-when-pipeline-succeeds on the merge
+ *                          requests this pass opens. Default off: a person merges.
  */
 export async function runFixDispatch(ctx, deps = {}) {
     const f = deps.fix ?? {};
@@ -433,6 +440,8 @@ export async function runFixDispatch(ctx, deps = {}) {
         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.");
     }
+    // Same check as the watch: the host is the connector's choice, not the node's.
+    const gitlabBaseUrl = f.gitlab ? undefined : resolveGitLabBaseUrl(ctx.taskContext["gitlab.url"], allowedGitLabHosts(deps.env ?? process.env));
     // 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.
@@ -450,7 +459,7 @@ export async function runFixDispatch(ctx, deps = {}) {
             gitlabRestWriter({
                 projectPath,
                 token: await (f.credential ?? harnessCredential(harness))(credentialName),
-                ...(ctx.taskContext["gitlab.url"] ? { baseUrl: ctx.taskContext["gitlab.url"] } : {}),
+                baseUrl: gitlabBaseUrl,
             });
         const findings = f.findings ?? harnessFindingSource(taskKnowledge(harness));
         const status = f.status ??
@@ -460,6 +469,7 @@ export async function runFixDispatch(ctx, deps = {}) {
             application,
             commit,
             targetRef,
+            autoMerge: ctx.taskContext["fix.auto_merge"] === "true",
             findings,
             status,
             planner: f.planner,

package/dist/fix.d.ts

@@ -4,10 +4,17 @@ import type { FileChange, GitLabWriter, MergeRequest } from "./gitlab.js";
  *
  * 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.
+ * runs the repository's own tests, and only then opens a merge request for a
+ * person to review. 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.
+ *
+ * A PERSON MERGES, UNLESS THE APPLICATION OPTED IN. The planner is steered by
+ * the Finding and by the repository content it triaged, which is the
+ * untrusted input of this whole task. So a merge request is never armed to
+ * merge itself by default. `autoMerge` arms `merge_when_pipeline_succeeds`
+ * on the requests one pass opens, and it is set only from the Application's
+ * explicit `fix.auto_merge` opt-in in the task context.
  *
  * 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
@@ -176,6 +183,8 @@ export interface RunFixOptions {
     pipelineUrl?: string;
     /** Cap on merge requests opened in one pass, so a backlog cannot flood review. */
     maxMergeRequests?: number;
+    /** Arm auto-merge on the merge requests this pass opens. Default false. See the module note. */
+    autoMerge?: boolean;
     onEvent?: (e: FixEvent) => void;
 }
 /** Default ceiling on merge requests opened by one pass. */
@@ -203,8 +212,8 @@ export declare function fixBranch(finding: FixableFinding): string;
 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 merge request description. Names the Finding it closes, how, and who merges. */
+export declare function mergeRequestBody(finding: FixableFinding, plan: FixPlan, autoMerge?: boolean): 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

@@ -5,10 +5,17 @@
  *
  * 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.
+ * runs the repository's own tests, and only then opens a merge request for a
+ * person to review. 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.
+ *
+ * A PERSON MERGES, UNLESS THE APPLICATION OPTED IN. The planner is steered by
+ * the Finding and by the repository content it triaged, which is the
+ * untrusted input of this whole task. So a merge request is never armed to
+ * merge itself by default. `autoMerge` arms `merge_when_pipeline_succeeds`
+ * on the requests one pass opens, and it is set only from the Application's
+ * explicit `fix.auto_merge` opt-in in the task context.
  *
  * 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
@@ -112,7 +119,8 @@ export async function runFix(opts) {
         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));
+            const autoMerge = opts.autoMerge === true;
+            const mr = await opts.gitlab.openMergeRequest(branch, opts.targetRef, plan.summary, mergeRequestBody(finding, plan, autoMerge), { autoMerge });
             emit({ type: "fix.mr", findingId: finding.id, iid: mr.iid, webUrl: mr.webUrl });
             opened++;
             await opts.status.markFixing(finding.id, mr);
@@ -193,8 +201,8 @@ export function statusDescription(summary) {
         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) {
+/** The merge request description. Names the Finding it closes, how, and who merges. */
+export function mergeRequestBody(finding, plan, autoMerge = false) {
     return [
         plan.detail,
         "",
@@ -203,9 +211,10 @@ export function mergeRequestBody(finding, plan) {
         `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.",
+        autoMerge
+            ? "Opened by the Gibson always-on agent. This Application opted in to auto-merge, so it merges itself when the pipeline succeeds."
+            : "Opened by the Gibson always-on agent for review. A person merges it.",
+        "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. */

package/dist/gitlab.d.ts

@@ -24,6 +24,27 @@
 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";
+/**
+ * The connector configuration that says which GitLab hosts a tenant's token
+ * may be sent to: a comma-separated list of host names in the component's
+ * environment, set by the operator, never by a mission node. Default:
+ * `gitlab.com`.
+ */
+export declare const GITLAB_HOSTS_ENV = "ZEROCOOL_GITLAB_HOSTS";
+/** Read the allow list from the environment. */
+export declare function allowedGitLabHosts(env: NodeJS.ProcessEnv): string[];
+/**
+ * The instance base URL a dispatch may use, checked against the allow list.
+ *
+ * `gitlab.url` comes from the mission node's task context, and the token it
+ * would be sent with is the tenant's project access token. So the value is
+ * not trusted on its own: the scheme must be https, the host must be one the
+ * connector configuration names, and the URL carries no credential, query or
+ * fragment. An empty `gitlab.url` means the one allowed host, and is refused
+ * when the allow list names several, because guessing would pick a host the
+ * mission author did not.
+ */
+export declare function resolveGitLabBaseUrl(requested: string | undefined, allowedHosts: string[]): string;
 /** 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. */
@@ -52,7 +73,7 @@ export interface GitLabRestOptions {
     projectPath: string;
     /** The project access token, resolved from the tenant secret store. */
     token: string;
-    /** The instance. Defaults to {@link GITLAB_DEFAULT_URL}. */
+    /** The instance, https only. Defaults to {@link GITLAB_DEFAULT_URL}. Resolve it with {@link resolveGitLabBaseUrl}. */
     baseUrl?: string;
     /** Injectable transport. Defaults to the global `fetch`. */
     fetch?: typeof globalThis.fetch;
@@ -85,6 +106,11 @@ export interface MergeRequest {
     /** GitLab's own state: `opened`, `merged`, `closed`, `locked`. */
     state: string;
 }
+/** What {@link GitLabWriter.openMergeRequest} may be told beyond the request itself. */
+export interface OpenMergeRequestOptions {
+    /** Arm `merge_when_pipeline_succeeds`. Default false: a person merges. */
+    autoMerge?: boolean;
+}
 /** One file the Fix rewrote, as the commit API wants it. */
 export interface FileChange {
     path: string;
@@ -98,8 +124,12 @@ export interface GitLabWriter {
      * 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>;
+    /**
+     * Open a merge request for a person to review. Auto-merge on a green
+     * pipeline is armed only when `opts.autoMerge` is true, which the Fix sets
+     * from the Application's explicit opt-in and nothing else.
+     */
+    openMergeRequest(branch: string, targetRef: string, title: string, description: string, opts?: OpenMergeRequestOptions): 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. */

package/dist/gitlab.js

@@ -26,6 +26,69 @@
 export const TRIGGER_STATUS = "success";
 /** GitLab's public host, when a tenant names no other instance. */
 export const GITLAB_DEFAULT_URL = "https://gitlab.com";
+/**
+ * The connector configuration that says which GitLab hosts a tenant's token
+ * may be sent to: a comma-separated list of host names in the component's
+ * environment, set by the operator, never by a mission node. Default:
+ * `gitlab.com`.
+ */
+export const GITLAB_HOSTS_ENV = "ZEROCOOL_GITLAB_HOSTS";
+/** Read the allow list from the environment. */
+export function allowedGitLabHosts(env) {
+    const raw = env[GITLAB_HOSTS_ENV] ?? "";
+    const hosts = raw
+        .split(",")
+        .map((h) => h.trim().toLowerCase())
+        .filter((h) => h.length > 0);
+    return hosts.length > 0 ? hosts : ["gitlab.com"];
+}
+/**
+ * The instance base URL a dispatch may use, checked against the allow list.
+ *
+ * `gitlab.url` comes from the mission node's task context, and the token it
+ * would be sent with is the tenant's project access token. So the value is
+ * not trusted on its own: the scheme must be https, the host must be one the
+ * connector configuration names, and the URL carries no credential, query or
+ * fragment. An empty `gitlab.url` means the one allowed host, and is refused
+ * when the allow list names several, because guessing would pick a host the
+ * mission author did not.
+ */
+export function resolveGitLabBaseUrl(requested, allowedHosts) {
+    const allowed = allowedHosts.map((h) => h.toLowerCase());
+    if (allowed.length === 0)
+        throw new Error(`${GITLAB_HOSTS_ENV} names no GitLab host, so no token can be sent anywhere`);
+    const wanted = (requested ?? "").trim();
+    if (!wanted) {
+        if (allowed.length === 1)
+            return `https://${allowed[0]}`;
+        throw new Error(`gitlab.url is not set and ${GITLAB_HOSTS_ENV} allows several hosts (${allowed.join(", ")}); the task context must name one`);
+    }
+    let url;
+    try {
+        url = new URL(wanted);
+    }
+    catch {
+        throw new Error(`gitlab.url ${JSON.stringify(wanted)} is not a URL`);
+    }
+    if (url.protocol !== "https:") {
+        throw new Error(`gitlab.url ${JSON.stringify(wanted)} is not https; the tenant's token travels only over https`);
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error(`gitlab.url ${JSON.stringify(wanted)} carries a credential, a query or a fragment; only scheme, host and path are read`);
+    }
+    const host = url.hostname.toLowerCase();
+    if (!allowed.includes(host)) {
+        throw new Error(`gitlab.url host ${JSON.stringify(host)} is not in ${GITLAB_HOSTS_ENV} (${allowed.join(", ")}); the connector configuration names the hosts a token may be sent to`);
+    }
+    return `${url.origin}${url.pathname}`.replace(/\/+$/, "");
+}
+/** Both clients take the base through here, so a caller cannot hand them a plaintext host. */
+function httpsBase(baseUrl) {
+    const base = (baseUrl || GITLAB_DEFAULT_URL).replace(/\/+$/, "");
+    if (!base.startsWith("https://"))
+        throw new Error(`GitLab base url ${JSON.stringify(base)} is not https`);
+    return base;
+}
 /**
  * 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
@@ -56,7 +119,7 @@ export function parsePipeline(raw) {
  * request.
  */
 export function gitlabRest(opts) {
-    const base = (opts.baseUrl || GITLAB_DEFAULT_URL).replace(/\/+$/, "");
+    const base = httpsBase(opts.baseUrl);
     const project = encodeURIComponent(opts.projectPath);
     const doFetch = opts.fetch ?? globalThis.fetch;
     return {
@@ -93,7 +156,7 @@ export const SCAN_STATUS_CONTEXT = "gibson/scan";
  * code — never a header.
  */
 export function gitlabRestWriter(opts) {
-    const base = (opts.baseUrl || GITLAB_DEFAULT_URL).replace(/\/+$/, "");
+    const base = httpsBase(opts.baseUrl);
     const project = encodeURIComponent(opts.projectPath);
     const doFetch = opts.fetch ?? globalThis.fetch;
     const api = `${base}/api/v4/projects/${project}`;
@@ -141,7 +204,7 @@ export function gitlabRestWriter(opts) {
             }
             return sha;
         },
-        async openMergeRequest(branch, targetRef, title, description) {
+        async openMergeRequest(branch, targetRef, title, description, opts) {
             const created = asMergeRequest(await call("POST", "/merge_requests", {
                 source_branch: branch,
                 target_branch: targetRef,
@@ -149,15 +212,21 @@ export function gitlabRestWriter(opts) {
                 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.
+            // The merge request is open for a person. Machine-written code lands on
+            // the customer's branch by itself only where the Application opted in:
+            // anything that steers the planner, including the repository content it
+            // triaged, would otherwise land as soon as CI went green.
+            if (opts?.autoMerge === true) {
+                // 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;
         },

package/dist/http-probe.d.ts

@@ -7,11 +7,19 @@ import { decodeToolInput, type GibsonClients, type ToolInvocation } from "@zeror
  * dispatch path — mission node → work queue → this process → result → mission
  * completion — without the result depending on anything about the target.
  *
- * SAFETY. This is a fetch, not a scanner: one request, no redirect chasing
- * beyond what fetch does by default, no body execution, and a hard timeout. The
- * body is measured, never returned — a probe that echoes arbitrary remote
- * content back into a mission's knowledge graph is an injection surface, and
- * the size is what the caller actually asked for.
+ * SAFETY. This is a fetch, not a scanner: one request, no redirect followed,
+ * no body execution, and a hard timeout. The body is measured, never returned:
+ * a probe that echoes arbitrary remote content back into a mission's knowledge
+ * graph is an injection surface, and the size is what the caller asked for.
+ *
+ * NO INTERNAL TARGET. The probe runs inside the agent container, next to the
+ * instance metadata service, the Kubernetes API and every internal service.
+ * A dispatch names the URL, so the host is resolved first and every address
+ * it resolves to must be a public unicast address. Loopback, link-local,
+ * RFC 1918, carrier-grade NAT, IPv6 unique-local and link-local, the
+ * unspecified address and multicast are refused before any connection. A
+ * redirect is reported as its status and never followed, so a public host
+ * cannot bounce the probe inward.
  */
 export interface ProbeResult {
     url: string;
@@ -23,8 +31,29 @@ export interface ProbeResult {
     elapsedMs: number;
 }
 export declare const HTTP_PROBE_TIMEOUT_MS = 15000;
+/** One resolved address, as `dns.lookup` with `all: true` returns it. */
+export interface ResolvedAddress {
+    address: string;
+    family: number;
+}
+/** The seams a test replaces: name resolution and the transport. */
+export interface ProbeDeps {
+    lookup?: (host: string) => Promise<ResolvedAddress[]>;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * True when the address is not a public unicast address. Written as the
+ * ranges the probe refuses, so each one is named and testable.
+ */
+export declare function isInternalAddress(address: string): boolean;
+/**
+ * Resolve the host and refuse it when any address it maps to is internal. A
+ * host that resolves to nothing is refused too: the probe has nothing to
+ * check, so it does not connect.
+ */
+export declare function assertPublicHost(hostname: string, lookup: (host: string) => Promise<ResolvedAddress[]>): Promise<void>;
 /** Perform the probe. Exported separately from the handler so it is testable without a work item. */
-export declare function probe(url: string, timeoutMs?: number): Promise<ProbeResult>;
+export declare function probe(url: string, timeoutMs?: number, deps?: ProbeDeps): Promise<ProbeResult>;
 /**
  * Work handler: takes a claimed tool invocation and returns the probe result.
  *

package/dist/http-probe.js

@@ -1,18 +1,122 @@
 // SPDX-License-Identifier: Elastic-2.0
 // Copyright 2026 Zero Root AI
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
 import { decodeToolInput } from "@zeroroot-ai/sdk";
 export const HTTP_PROBE_TIMEOUT_MS = 15_000;
+const defaultLookup = async (host) => dnsLookup(host, { all: true });
+/** Parse dotted IPv4 into its four octets, or undefined. */
+function ipv4Octets(address) {
+    if (isIP(address) !== 4)
+        return undefined;
+    return address.split(".").map((o) => Number(o));
+}
+/**
+ * True when the address is not a public unicast address. Written as the
+ * ranges the probe refuses, so each one is named and testable.
+ */
+export function isInternalAddress(address) {
+    const v4 = ipv4Octets(address);
+    if (v4) {
+        const [a, b] = v4;
+        if (a === 0)
+            return true; // 0.0.0.0/8, "this network"
+        if (a === 10)
+            return true; // RFC 1918
+        if (a === 127)
+            return true; // loopback
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // 100.64.0.0/10, carrier-grade NAT
+        if (a === 169 && b === 254)
+            return true; // link-local, and the cloud metadata service
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // RFC 1918
+        if (a === 192 && b === 168)
+            return true; // RFC 1918
+        if (a >= 224)
+            return true; // multicast and reserved
+        return false;
+    }
+    if (isIP(address) !== 6)
+        return true; // not an address at all: refuse
+    const groups = ipv6Groups(address);
+    if (!groups)
+        return true;
+    const [first] = groups;
+    const leadingZero = groups.slice(0, 5).every((g) => g === 0);
+    // ::ffff:a.b.c.d (IPv4-mapped) and ::a.b.c.d (IPv4-compatible, deprecated)
+    // are judged as their IPv4 part. The URL parser writes the mapped form in
+    // hex, so the last two groups are read back as four octets.
+    if (leadingZero && (groups[5] === 0xffff || (groups[5] === 0 && (groups[6] !== 0 || groups[7] > 1)))) {
+        const hi = groups[6];
+        const lo = groups[7];
+        return isInternalAddress(`${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`);
+    }
+    if (groups.every((g) => g === 0))
+        return true; // ::, unspecified
+    if (leadingZero && groups[5] === 0 && groups[6] === 0 && groups[7] === 1)
+        return true; // ::1, loopback
+    if ((first & 0xfe00) === 0xfc00)
+        return true; // fc00::/7, unique local
+    if ((first & 0xffc0) === 0xfe80)
+        return true; // fe80::/10, link-local
+    if ((first & 0xff00) === 0xff00)
+        return true; // ff00::/8, multicast
+    return false;
+}
+/** Expand an IPv6 address into its eight 16-bit groups, or undefined. */
+function ipv6Groups(address) {
+    let text = address.toLowerCase();
+    const zone = text.indexOf("%");
+    if (zone >= 0)
+        text = text.slice(0, zone);
+    // A trailing dotted quad becomes two hex groups.
+    const dotted = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+    if (dotted) {
+        const [a, b, c, d] = dotted[1].split(".").map(Number);
+        text = `${text.slice(0, -dotted[1].length)}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return undefined;
+    const head = halves[0] ? halves[0].split(":") : [];
+    const tail = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+    const fill = 8 - head.length - tail.length;
+    if (fill < 0 || (halves.length === 1 && fill !== 0))
+        return undefined;
+    const parts = [...head, ...Array(fill).fill("0"), ...tail];
+    const groups = parts.map((p) => Number.parseInt(p || "0", 16));
+    return groups.some((g) => Number.isNaN(g) || g < 0 || g > 0xffff) ? undefined : groups;
+}
+/**
+ * Resolve the host and refuse it when any address it maps to is internal. A
+ * host that resolves to nothing is refused too: the probe has nothing to
+ * check, so it does not connect.
+ */
+export async function assertPublicHost(hostname, lookup) {
+    const bare = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+    const addresses = isIP(bare) ? [{ address: bare, family: isIP(bare) }] : await lookup(bare);
+    if (addresses.length === 0)
+        throw new Error(`http_probe refuses ${hostname}: it resolves to no address`);
+    for (const { address } of addresses) {
+        if (isInternalAddress(address)) {
+            throw new Error(`http_probe refuses ${hostname}: it resolves to ${address}, which is not a public address`);
+        }
+    }
+}
 /** Perform the probe. Exported separately from the handler so it is testable without a work item. */
-export async function probe(url, timeoutMs = HTTP_PROBE_TIMEOUT_MS) {
+export async function probe(url, timeoutMs = HTTP_PROBE_TIMEOUT_MS, deps = {}) {
     const parsed = new URL(url);
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
         throw new Error(`unsupported scheme ${parsed.protocol} (http and https only)`);
     }
+    await assertPublicHost(parsed.hostname, deps.lookup ?? defaultLookup);
+    const doFetch = deps.fetch ?? globalThis.fetch;
     const started = Date.now();
     const ctl = new AbortController();
     const timer = setTimeout(() => ctl.abort(), timeoutMs);
     try {
-        const res = await fetch(parsed.toString(), { method: "GET", signal: ctl.signal });
+        const res = await doFetch(parsed.toString(), { method: "GET", redirect: "manual", signal: ctl.signal });
         const body = await res.arrayBuffer();
         return {
             url: parsed.toString(),

package/dist/index.js

@@ -54,8 +54,7 @@ export const GibsonPlugin = async () => {
     // first Capability Grant handshake and the host key it registers is persisted
     // at `hostKeyPath`. Every later start re-registers by proving possession of
     // that host key — the daemon routes on credential type: `host+jwt` is
-    // re-registration, anything else is first registration
-    // (gibson `internal/server/daemon/capabilitygrant_register.go:134-155`).
+    // re-registration, anything else is first registration.
     //
     // So the bootstrap token is passed ONLY when no host key exists yet. Replaying
     // a one-time token on every start would be rejected, and it would mean asking

package/dist/mcp-config.d.ts

@@ -6,10 +6,15 @@
  * the `config` hook, so a user configures nothing.
  *
  * The command is the published package, not a path inside this plugin: the
- * server is shared by every host and released on the SDK train, so pinning it
- * to whatever this plugin happens to bundle would freeze the tool set.
+ * server is shared by every host and released on the SDK train.
+ *
+ * The version is exact. `npx --yes` runs whatever the registry serves with no
+ * prompt, so a floating tag would run one compromised publish on every
+ * machine at session start. The pin is the one in tools/hosts/package.json,
+ * which Dependabot bumps. `pins.test.ts` in claude-gibson fails when the two
+ * differ or when any install path floats again.
  */
-export declare const GIBSON_MCP_PACKAGE = "@zeroroot-ai/gibson-mcp@latest";
+export declare const GIBSON_MCP_PACKAGE = "@zeroroot-ai/gibson-mcp@0.2.1";
 export interface OpencodeMcpLocal {
     type: "local";
     command: string[];

package/dist/mcp-config.js

@@ -8,10 +8,15 @@
  * the `config` hook, so a user configures nothing.
  *
  * The command is the published package, not a path inside this plugin: the
- * server is shared by every host and released on the SDK train, so pinning it
- * to whatever this plugin happens to bundle would freeze the tool set.
+ * server is shared by every host and released on the SDK train.
+ *
+ * The version is exact. `npx --yes` runs whatever the registry serves with no
+ * prompt, so a floating tag would run one compromised publish on every
+ * machine at session start. The pin is the one in tools/hosts/package.json,
+ * which Dependabot bumps. `pins.test.ts` in claude-gibson fails when the two
+ * differ or when any install path floats again.
  */
-export const GIBSON_MCP_PACKAGE = "@zeroroot-ai/gibson-mcp@latest";
+export const GIBSON_MCP_PACKAGE = "@zeroroot-ai/gibson-mcp@0.2.1";
 /** The `mcp.gibson` entry. `environment` carries nothing secret. */
 export function gibsonMcpServer(env = process.env) {
     const environment = {};

package/dist/opencode-run.d.ts

@@ -52,7 +52,7 @@ export interface OpencodeRunOptions {
     sessionId?: string;
     /** Hard deadline. The child is killed when it elapses. */
     timeoutMs?: number;
-    /** Extra environment for the child, merged over the parent's. */
+    /** Extra environment for the child, merged over the allow-listed parent environment. */
     env?: NodeJS.ProcessEnv;
     /** Binary to run. Overridable for tests and for a pinned install. */
     bin?: string;
@@ -78,6 +78,13 @@ export declare function createLineStreamer(onLine: (line: string) => void): {
     push: (chunk: string) => void;
     flush: () => void;
 };
+/**
+ * The environment the opencode child gets: the allow list above from `parent`,
+ * then `extra` on top. `extra` is the per-dispatch grant from
+ * `dispatchChildEnv`, which is the only way a `GIBSON_CALLBACK_*` name reaches
+ * the child.
+ */
+export declare function opencodeChildEnv(parent: NodeJS.ProcessEnv, extra?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Build the argv for a headless run. Exported so a test can assert it. */
 export declare function opencodeArgs(opts: OpencodeRunOptions): string[];
 /**

package/dist/opencode-run.js

@@ -80,6 +80,81 @@ export function createLineStreamer(onLine) {
         },
     };
 }
+/**
+ * Environment names and prefixes the opencode child may see. Everything else
+ * is dropped, so the launcher's component grant (`GIBSON_CG_JWT`), the
+ * one-time enrollment token (`GIBSON_BOOTSTRAP_TOKEN`) and the launch task
+ * (`GIBSON_AGENT_TASK_B64`) never reach a process that runs with `--auto`
+ * and has a shell. `knowledge-source.ts` states the child contract: it reads
+ * `GIBSON_CALLBACK_ENDPOINT` and `GIBSON_CALLBACK_TOKEN`, which the caller
+ * passes in `opts.env`, and nothing of the launch environment.
+ *
+ * `GIBSON_` names are listed one by one and never by prefix: the grant and
+ * the token share that prefix with the addressing the child plugin reads.
+ * The provider credential passes through because opencode itself reads it
+ * for a model that is not served through the Gibson shim, the same posture
+ * `claude-member/src/env.ts` takes for Claude Code.
+ */
+const CHILD_ENV_ALLOW_EXACT = [
+    "PATH",
+    "HOME",
+    "USER",
+    "SHELL",
+    "TZ",
+    "TERM",
+    "TMPDIR",
+    "NO_PROXY",
+    "no_proxy",
+    "HTTP_PROXY",
+    "http_proxy",
+    "HTTPS_PROXY",
+    "https_proxy",
+    "CLOUD_ML_REGION",
+    // Addressing the child plugin reads (index.ts, mcp-config.ts). No secret.
+    "GIBSON_PLATFORM_URL",
+    "GIBSON_DAEMON_URL",
+    "GIBSON_HOST_KEY_PATH",
+    "GIBSON_AGENT_MODE",
+    "GIBSON_SHIM_PORT",
+    "GIBSON_TARGET_ID",
+    "GIBSON_CA_CERT",
+    "GIBSON_OPENCODE_SESSION_ID",
+];
+const CHILD_ENV_ALLOW_PREFIX = [
+    "LANG",
+    "LC_",
+    "XDG_",
+    "NODE_",
+    "SSL_CERT_",
+    "OPENCODE_",
+    "ZEROCOOL_",
+    "ANTHROPIC_",
+    "OPENAI_",
+    "AWS_",
+    "GOOGLE_",
+    "AZURE_",
+];
+/**
+ * The environment the opencode child gets: the allow list above from `parent`,
+ * then `extra` on top. `extra` is the per-dispatch grant from
+ * `dispatchChildEnv`, which is the only way a `GIBSON_CALLBACK_*` name reaches
+ * the child.
+ */
+export function opencodeChildEnv(parent, extra = {}) {
+    const out = {};
+    for (const [k, v] of Object.entries(parent)) {
+        if (v === undefined)
+            continue;
+        if (!CHILD_ENV_ALLOW_EXACT.includes(k) && !CHILD_ENV_ALLOW_PREFIX.some((p) => k.startsWith(p)))
+            continue;
+        out[k] = v;
+    }
+    for (const [k, v] of Object.entries(extra)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
 /** Build the argv for a headless run. Exported so a test can assert it. */
 export function opencodeArgs(opts) {
     const args = ["run", "--format", "json", "--dir", opts.dir];
@@ -109,7 +184,7 @@ export async function runOpencode(opts) {
     return await new Promise((resolve, reject) => {
         const child = spawn(bin, args, {
             cwd: opts.dir,
-            env: { ...process.env, ...opts.env },
+            env: opencodeChildEnv(process.env, opts.env),
             stdio: ["ignore", "pipe", "pipe"],
             ...(opts.timeoutMs && opts.timeoutMs > 0 ? { timeout: opts.timeoutMs, killSignal: "SIGTERM" } : {}),
         });

package/dist/serve-agent.js

@@ -57,11 +57,10 @@ export async function agentHandler(item, opts) {
         // pass it back — see the ADR on why this is not yet automatic.
         sessionId: item.context.opencode_session_id,
         timeoutMs: item.timeoutMs,
-        // The task-scoped callback seam. gibson mints the grant per dispatch
-        // (`internal/engine/harness/implementation.go:1205-1210`) so a dispatched run
-        // reaches the harness as the TASK rather than as this component. The same
-        // passthrough the sandboxed shape uses (`dispatch.ts`), so the child sees one
-        // environment however it was launched.
+        // The task-scoped callback seam. The platform mints the grant per dispatch,
+        // so a dispatched run reaches the harness as the TASK rather than as this
+        // component. The same passthrough the sandboxed shape uses (`dispatch.ts`),
+        // so the child sees one environment however it was launched.
         env: dispatchChildEnv({
             callbackEndpoint: item.callbackEndpoint,
             callbackToken: item.callbackToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroroot-ai/zerocool",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "opencode host adapter for Gibson (zerocool): zero-config LLM through the harness, ambient knowledge, and the Gibson MCP server registered for you. The tools come from @zeroroot-ai/gibson-mcp.",
   "license": "Elastic-2.0",
   "repository": {
@@ -29,7 +29,7 @@
     "@opencode-ai/plugin": "*"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "^1.18.27"
+    "@opencode-ai/plugin": "^1.18.29"
   },
   "bin": {
     "zerocool-serve": "dist/serve.js",