@zeroroot-ai/zerocool 0.9.0 → 0.9.2

package/dist/dispatch.d.ts

@@ -33,18 +33,21 @@
  * 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):
+ * THE LAUNCHER CONTRACT IS READ ONCE, BY THE SDK. `readSandboxDispatch` from
+ * `@zeroroot-ai/sdk` is the one reader of the launch environment in this
+ * package, and `sandboxHarness` opens the callbacks on what it read. The
+ * 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.
  *
- * 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.
+ * 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
+ * writes any of them, so the SDK carries none of them:
  *
- *   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", "watch",
  *                              "fix"); the Task's own context `zerocool.task`
@@ -54,9 +57,9 @@
  *
  * 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.
+ * the grant the SDK read.
  */
-import { type AgentOutcome, type TaskHarness } from "@zeroroot-ai/sdk";
+import { type AgentOutcome, type SandboxDispatch, type TaskHarness } from "@zeroroot-ai/sdk";
 import { type FindingsBackend } from "./findings.js";
 import { type FindingSource, type FindingStatusWriter, type FixPlanner, type Workspace } from "./fix.js";
 import { type GitLabClient, type GitLabWriter } from "./gitlab.js";
@@ -65,8 +68,11 @@ 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.
+ * The per-dispatch grant as the OPENCODE CHILD receives it.
+ *
+ * These are `ExecuteRequest` field names, not launcher environment names. The
+ * shape is shared with `serve-agent.ts`, which fills it from a polled work
+ * item, so the child sees one environment however the run was launched.
  */
 export interface CallbackGrant {
     /** `ExecuteRequest.callback_endpoint` — a bare `host:port` or an http(s) URL. */
@@ -80,27 +86,6 @@ export interface CallbackGrant {
     agentRunId?: string;
     traceId?: string;
 }
-/** Everything one sandboxed dispatch needs, read from the environment. */
-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. */
-    model?: string;
-    /** Continue an earlier opencode session instead of starting a new one. */
-    sessionId?: string;
-    /** Hard deadline for the run, in ms. `0` when none was set. */
-    timeoutMs: number;
-}
 /**
  * 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
@@ -112,46 +97,45 @@ export interface DispatchContext extends CallbackGrant {
  */
 export declare function dispatchChildEnv(g: CallbackGrant): NodeJS.ProcessEnv;
 /**
- * Decode the base64 protojson `gibson.types.v1.Task` the sandbox launch injects
- * as `GIBSON_AGENT_TASK_B64` (gibson agent.go `envAgentTaskB64`) and return its
- * goal. gibson sends the full typed Task, not a plain goal string, so decode it
- * here rather than run opencode against an empty or malformed prompt.
+ * Everything one sandboxed dispatch needs.
+ *
+ * The launcher contract, exactly as `readSandboxDispatch` read it, plus the
+ * local options of this host. Extending {@link SandboxDispatch} rather than
+ * copying its fields keeps one name for each thing: the grant is `grant`, the
+ * dial target is `callbackEndpoint`, and there is no second spelling to drift.
  */
-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>;
+export interface DispatchContext extends SandboxDispatch {
+    /**
+     * `task.context` read as strings. The mission node sets it. It 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>;
+    /** Dial the callback listener without TLS. A local option, not the contract. */
+    insecure: boolean;
+    /** opencode edits files here; it is the run's workspace. */
+    workspace: string;
+    /** Continue an earlier opencode session instead of starting a new one. */
+    sessionId?: string;
+    /** Hard deadline for the run, in ms. `0` when none was set. */
+    timeoutMs: number;
 }
 /**
- * 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.
+ * Read one `Task.context` entry as a string.
  *
- * 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.
+ * `Task.context` is `map<string, gibson.common.v1.TypedValue>`. The SDK parses
+ * the launcher's protojson with the generated schema, so every value arrives
+ * as the protobuf-es oneof shape and never as a bare string. Reading these
+ * maps as plain strings dropped every entry, which is why a mission node's
+ * `zerocool.task`, `repository.commit` and `target.id` never reached a run.
  *
- * `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"`.
+ * A null yields no entry: a null is the absence of a value, and rendering it
+ * would hand a task a target id of `"null"`. Bytes, arrays and maps yield no
+ * entry either — a task reads these keys as single strings.
  */
-export declare function typedValueString(val: unknown): string | undefined;
+export declare function typedValueString(v: SandboxDispatch["task"]["context"][string]): string | undefined;
+/** The whole context map as strings. Entries with no readable value are dropped. */
+export declare function taskContextStrings(context: SandboxDispatch["task"]["context"]): Record<string, string>;
 /** The task kinds a sandboxed dispatch can serve. */
 export type DispatchTaskKind = "opencode" | "source-analysis" | "watch" | "fix";
 /**
@@ -161,21 +145,32 @@ export type DispatchTaskKind = "opencode" | "source-analysis" | "watch" | "fix";
  */
 export declare function dispatchTaskKind(ctx: Pick<DispatchContext, "taskContext">, env?: NodeJS.ProcessEnv): DispatchTaskKind;
 /**
- * Read one sandboxed dispatch's context from the environment.
+ * Read one sandboxed dispatch from the environment.
+ *
+ * The launcher contract comes from `readSandboxDispatch`, which is the one
+ * reader of those names on the TypeScript side. It fails, never falls back: a
+ * launch without a grant, an endpoint or a task is a defect in the launch, not
+ * something to guess around by running opencode with no task or by making
+ * unauthenticated calls.
  *
  * Deliberately never reads `GIBSON_BOOTSTRAP_TOKEN` or a host key: a sandboxed
  * run is authenticated by its per-dispatch grant alone, and reaching for a
  * bootstrap token here would reintroduce the enrollment handshake this shape
  * exists to avoid.
  *
- * The grant and the goal are required. A missing piece throws with the reason,
- * because a sandbox that launched this process without them is a defect in the
- * launch, not something to guess around by running opencode with no task or by
- * making unauthenticated calls.
+ * What this adds on top are this host's own options — the workspace, the
+ * deadline, the opencode session to continue, and whether to dial the callback
+ * listener without TLS. The launcher writes none of them, so the SDK carries
+ * none of them, and reading them here is not a second spelling of the contract.
  */
 export declare function readDispatchContext(env: NodeJS.ProcessEnv, opts?: {
     cwd?: string;
 }): DispatchContext;
+/**
+ * The task harness for this dispatch: the grant the launch injected, nothing
+ * else. `sandboxHarness` is the SDK's opener for exactly this shape.
+ */
+export declare function dispatchHarness(ctx: DispatchContext): TaskHarness;
 /** Injectable seams, so a test drives a dispatch without spawning opencode. */
 export interface DispatchDeps {
     /** Overridable opencode driver. */
@@ -186,7 +181,7 @@ export interface DispatchDeps {
     semgrep?: SemgrepRunner;
     model?: TriageModel;
     findings?: FindingsBackend;
-    /** Opens the task harness. Defaults to `openTaskHarness` on the dispatch grant. */
+    /** Opens the task harness. Defaults to {@link dispatchHarness} on the dispatch grant. */
     harness?: (ctx: DispatchContext) => TaskHarness;
     /** Force the task kind, over the Task's own context. */
     taskKind?: DispatchTaskKind;

package/dist/dispatch.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 /**
  * zerocool-dispatch — one sandboxed dispatched run, then exit.
  *
@@ -33,18 +35,21 @@
  * 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):
+ * THE LAUNCHER CONTRACT IS READ ONCE, BY THE SDK. `readSandboxDispatch` from
+ * `@zeroroot-ai/sdk` is the one reader of the launch environment in this
+ * package, and `sandboxHarness` opens the callbacks on what it read. The
+ * 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.
  *
- * 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.
+ * 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
+ * writes any of them, so the SDK carries none of them:
  *
- *   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", "watch",
  *                              "fix"); the Task's own context `zerocool.task`
@@ -54,9 +59,9 @@
  *
  * 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.
+ * the grant the SDK read.
  */
-import { observe, openTaskHarness, taskKnowledge } from "@zeroroot-ai/sdk";
+import { observe, readSandboxDispatch, sandboxHarness, taskKnowledge, } from "@zeroroot-ai/sdk";
 import { join } from "node:path";
 import { taskFindingsBackend } from "./findings.js";
 import { harnessFindingSource, harnessFindingStatus, runFix, } from "./fix.js";
@@ -84,96 +89,42 @@ export function dispatchChildEnv(g) {
     };
 }
 /**
- * Decode the base64 protojson `gibson.types.v1.Task` the sandbox launch injects
- * as `GIBSON_AGENT_TASK_B64` (gibson agent.go `envAgentTaskB64`) and return its
- * goal. gibson sends the full typed Task, not a plain goal string, so decode it
- * 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.
+ * Read one `Task.context` entry as a string.
+ *
+ * `Task.context` is `map<string, gibson.common.v1.TypedValue>`. The SDK parses
+ * the launcher's protojson with the generated schema, so every value arrives
+ * as the protobuf-es oneof shape and never as a bare string. Reading these
+ * maps as plain strings dropped every entry, which is why a mission node's
+ * `zerocool.task`, `repository.commit` and `target.id` never reached a run.
+ *
+ * A null yields no entry: a null is the absence of a value, and rendering it
+ * would hand a task a target id of `"null"`. Bytes, arrays and maps yield no
+ * entry either — a task reads these keys as single strings.
  */
-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.");
+export function typedValueString(v) {
+    switch (v.kind.case) {
+        case "stringValue":
+            return v.kind.value;
+        case "intValue":
+            return String(v.kind.value);
+        case "doubleValue":
+            return String(v.kind.value);
+        case "boolValue":
+            return String(v.kind.value);
+        default:
+            return undefined;
     }
-    let task;
-    try {
-        task = JSON.parse(Buffer.from(taskB64, "base64").toString("utf8"));
-    }
-    catch (e) {
-        throw new Error("GIBSON_AGENT_TASK_B64 is not valid base64 protojson of a gibson.types.v1.Task: " +
-            (e instanceof Error ? e.message : String(e)));
-    }
-    const goal = typeof task.goal === "string" ? task.goal.trim() : "";
-    if (!goal) {
-        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, context: stringMap(task.context), metadata: stringMap(task.metadata) };
 }
-function stringMap(v) {
-    if (!v || typeof v !== "object")
-        return {};
+/** The whole context map as strings. Entries with no readable value are dropped. */
+export function taskContextStrings(context) {
     const out = {};
-    for (const [k, val] of Object.entries(v)) {
-        const s = typedValueString(val);
+    for (const [k, v] of Object.entries(context ?? {})) {
+        const s = typedValueString(v);
         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.
@@ -190,49 +141,43 @@ export function dispatchTaskKind(ctx, env = {}) {
     return "opencode";
 }
 /**
- * Read one sandboxed dispatch's context from the environment.
+ * Read one sandboxed dispatch from the environment.
+ *
+ * The launcher contract comes from `readSandboxDispatch`, which is the one
+ * reader of those names on the TypeScript side. It fails, never falls back: a
+ * launch without a grant, an endpoint or a task is a defect in the launch, not
+ * something to guess around by running opencode with no task or by making
+ * unauthenticated calls.
  *
  * Deliberately never reads `GIBSON_BOOTSTRAP_TOKEN` or a host key: a sandboxed
  * run is authenticated by its per-dispatch grant alone, and reaching for a
  * bootstrap token here would reintroduce the enrollment handshake this shape
  * exists to avoid.
  *
- * The grant and the goal are required. A missing piece throws with the reason,
- * because a sandbox that launched this process without them is a defect in the
- * launch, not something to guess around by running opencode with no task or by
- * making unauthenticated calls.
+ * What this adds on top are this host's own options — the workspace, the
+ * deadline, the opencode session to continue, and whether to dial the callback
+ * listener without TLS. The launcher writes none of them, so the SDK carries
+ * none of them, and reading them here is not a second spelling of the contract.
  */
 export function readDispatchContext(env, opts = {}) {
-    const endpoint = env.GIBSON_CALLBACK_ENDPOINT;
-    const token = env.GIBSON_CG_JWT;
-    if (!endpoint) {
-        throw new Error("GIBSON_CALLBACK_ENDPOINT is not set. A sandboxed dispatched run is authenticated by " +
-            "the per-dispatch grant the sandbox launch injects, not by a bootstrap token — the " +
-            "launch must supply the callback endpoint and the grant.");
-    }
-    if (!token) {
-        throw new Error("GIBSON_CALLBACK_ENDPOINT is set but GIBSON_CG_JWT is not. The callbacks would have no " +
-            "grant to authenticate with; a sandboxed run must not fall back to any other identity, " +
-            "so this fails instead.");
-    }
-    const task = decodeTask(env.GIBSON_AGENT_TASK_B64);
+    const dispatch = readSandboxDispatch(env);
     const timeoutRaw = env.GIBSON_TIMEOUT_MS ? Number(env.GIBSON_TIMEOUT_MS) : 0;
     return {
-        callbackEndpoint: endpoint,
-        callbackToken: token,
+        ...dispatch,
+        taskContext: taskContextStrings(dispatch.task.context),
         insecure: env.GIBSON_CALLBACK_INSECURE === "1",
-        missionRunId: env.GIBSON_MISSION_RUN_ID ?? "",
-        agentRunId: env.GIBSON_AGENT_RUN_ID ?? "",
-        traceId: env.GIBSON_TRACE_ID ?? "",
-        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 } : {}),
         timeoutMs: Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 0,
     };
 }
+/**
+ * The task harness for this dispatch: the grant the launch injected, nothing
+ * else. `sandboxHarness` is the SDK's opener for exactly this shape.
+ */
+export function dispatchHarness(ctx) {
+    return sandboxHarness(ctx, { insecure: ctx.insecure });
+}
 /**
  * Run one dispatched Task headless and map it to a terminal outcome.
  *
@@ -259,7 +204,16 @@ export async function runDispatch(ctx, deps = {}) {
         ...(ctx.model ? { model: ctx.model } : {}),
         ...(ctx.sessionId ? { sessionId: ctx.sessionId } : {}),
         ...(ctx.timeoutMs > 0 ? { timeoutMs: ctx.timeoutMs } : {}),
-        env: dispatchChildEnv(ctx),
+        // The child speaks the opencode plugin's own contract, whose token name is
+        // GIBSON_CALLBACK_TOKEN. It is fed from the grant the SDK read.
+        env: dispatchChildEnv({
+            callbackEndpoint: ctx.callbackEndpoint,
+            callbackToken: ctx.grant,
+            insecure: ctx.insecure,
+            missionRunId: ctx.missionRunId,
+            agentRunId: ctx.agentRunId,
+            traceId: ctx.traceId,
+        }),
         ...(deps.onEvent ? { onEvent: deps.onEvent } : {}),
     });
     return {
@@ -288,7 +242,7 @@ 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);
+        : (deps.harness ?? dispatchHarness)(ctx);
     const model = deps.model ?? harnessTriageModel(harness);
     const findings = deps.findings ?? taskFindingsBackend(harness);
     const sub = ctx.taskContext["source.path"];
@@ -385,10 +339,7 @@ export async function runWatchDispatch(ctx, deps = {}) {
     // 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;
+    const harness = needsHarness ? (deps.harness ?? dispatchHarness)(ctx) : undefined;
     try {
         const gitlab = w.gitlab ??
             gitlabRest({
@@ -493,10 +444,7 @@ export async function runFixDispatch(ctx, deps = {}) {
     }
     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;
+    const harness = needsHarness ? (deps.harness ?? dispatchHarness)(ctx) : undefined;
     try {
         const gitlab = f.gitlab ??
             gitlabRestWriter({

package/dist/findings.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { submitFinding, } from "@zeroroot-ai/sdk";
 import { appendFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";

package/dist/fix.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 /**
  * The Fix — what the always-on agent does with a Finding (zerocool-plugins#89).
  *

package/dist/gitlab.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 /**
  * GitLab — the trigger the always-on agent watches (zerocool-plugins#88).
  *

package/dist/http-probe.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { decodeToolInput } from "@zeroroot-ai/sdk";
 export const HTTP_PROBE_TIMEOUT_MS = 15_000;
 /** Perform the probe. Exported separately from the handler so it is testable without a work item. */

package/dist/index.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { connectGibson, startCompletionsShim } from "@zeroroot-ai/sdk";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
@@ -111,7 +113,7 @@ export const GibsonPlugin = async () => {
     // Which grant this process reads the knowledge graph with. A dispatched run
     // reads as the TASK; an interactive one keeps the component grant. Chosen once
     // here so nothing downstream has to ask.
-    const { knowledge, scope: knowledgeScope } = selectKnowledgeSource(live);
+    const { knowledge, scope: knowledgeScope, stop: stopKnowledge } = selectKnowledgeSource(live);
     console.error(`[zerocool] knowledge reads use the ${knowledgeScope} grant`);
     const injectKnowledge = ambientKnowledge(knowledge, process.env.ZEROCOOL_AMBIENT_QUERY ?? "prior findings and security facts for this codebase");
     return {
@@ -147,6 +149,9 @@ export const GibsonPlugin = async () => {
                 context.sessionID = sessionID;
         },
         dispose: async () => {
+            // A task-scoped source holds a grant-renewal timer. Leaving it running
+            // would keep renewing a grant for a session that has ended.
+            stopKnowledge();
             session?.stop();
             await shim?.close();
         },

package/dist/knowledge-source.d.ts

@@ -1,12 +1,35 @@
-import { type GibsonSession, type KnowledgeSource } from "@zeroroot-ai/sdk";
+import { type GibsonSession, type KnowledgeSource, type OpenTaskHarnessOptions, type TaskHarness } from "@zeroroot-ai/sdk";
+/** The chosen knowledge source, and the way to release what it opened. */
+export interface SelectedKnowledge {
+    knowledge: KnowledgeSource;
+    scope: "task" | "component";
+    /**
+     * Release the task harness. Safe to call on either scope, and safe to call
+     * twice. A component-scoped run opens nothing, so this does nothing.
+     */
+    stop: () => void;
+}
+/** Seams, so a test can read what a dispatched run actually sends. */
+export interface KnowledgeSourceDeps {
+    /** Opens the task harness. Defaults to `openTaskHarness` on the dispatch grant. */
+    openHarness?: (opts: OpenTaskHarnessOptions) => TaskHarness;
+}
 /**
  * Pick the grant this process should read the knowledge graph with.
  *
  * A DISPATCHED run must read as the TASK, not as the component. gibson mints a
- * per-dispatch capability grant and `zerocool-agent` passes it to the child as
- * GIBSON_CALLBACK_ENDPOINT / GIBSON_CALLBACK_TOKEN. Reading with the component's
- * own grant instead is broader authority than the dispatch intended and leaves
- * no per-task attribution on anything the run reads — the gap ADR-0006 recorded.
+ * per-dispatch capability grant, and the driver passes it to this opencode
+ * child as GIBSON_CALLBACK_ENDPOINT / GIBSON_CALLBACK_TOKEN. Reading with the
+ * component's own grant instead is broader authority than the dispatch
+ * intended and leaves no per-task attribution on anything the run reads — the
+ * gap ADR-0006 recorded.
+ *
+ * THESE TWO NAMES ARE THE CHILD CONTRACT, NOT THE LAUNCHER CONTRACT. The
+ * launcher writes GIBSON_CG_JWT and GIBSON_AGENT_TASK_B64 into the sandbox,
+ * and `readSandboxDispatch` in `@zeroroot-ai/sdk` is the one reader of those
+ * (see `dispatch.ts`). This module runs one process further down, inside
+ * opencode, whose environment `dispatchChildEnv` writes. It never sees the
+ * launch environment, so it reads the child names and nothing else.
  *
  * An INTERACTIVE run has no callback seam and keeps the component grant, which
  * is correct: a human started it, and there is no task to scope to.
@@ -14,8 +37,10 @@ import { type GibsonSession, type KnowledgeSource } from "@zeroroot-ai/sdk";
  * A dispatch that carries an endpoint but no token FAILS rather than falling
  * back. Falling back is how the gap reappears silently, and a caller who wanted
  * task-scoped reads would get component-scoped ones without being told.
+ *
+ * `openTaskHarness` derives the `ContextInfo` every callback RPC carries from
+ * the grant's own claims, so a task-scoped read reaches the daemon naming the
+ * mission it belongs to. It also renews the grant on a timer, which is why the
+ * caller must {@link SelectedKnowledge.stop} the source when the session ends.
  */
-export declare function selectKnowledgeSource(session: GibsonSession): {
-    knowledge: KnowledgeSource;
-    scope: "task" | "component";
-};
+export declare function selectKnowledgeSource(session: GibsonSession, deps?: KnowledgeSourceDeps): SelectedKnowledge;

package/dist/knowledge-source.js

@@ -1,12 +1,22 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { componentKnowledge, openTaskHarness, taskKnowledge, } from "@zeroroot-ai/sdk";
 /**
  * Pick the grant this process should read the knowledge graph with.
  *
  * A DISPATCHED run must read as the TASK, not as the component. gibson mints a
- * per-dispatch capability grant and `zerocool-agent` passes it to the child as
- * GIBSON_CALLBACK_ENDPOINT / GIBSON_CALLBACK_TOKEN. Reading with the component's
- * own grant instead is broader authority than the dispatch intended and leaves
- * no per-task attribution on anything the run reads — the gap ADR-0006 recorded.
+ * per-dispatch capability grant, and the driver passes it to this opencode
+ * child as GIBSON_CALLBACK_ENDPOINT / GIBSON_CALLBACK_TOKEN. Reading with the
+ * component's own grant instead is broader authority than the dispatch
+ * intended and leaves no per-task attribution on anything the run reads — the
+ * gap ADR-0006 recorded.
+ *
+ * THESE TWO NAMES ARE THE CHILD CONTRACT, NOT THE LAUNCHER CONTRACT. The
+ * launcher writes GIBSON_CG_JWT and GIBSON_AGENT_TASK_B64 into the sandbox,
+ * and `readSandboxDispatch` in `@zeroroot-ai/sdk` is the one reader of those
+ * (see `dispatch.ts`). This module runs one process further down, inside
+ * opencode, whose environment `dispatchChildEnv` writes. It never sees the
+ * launch environment, so it reads the child names and nothing else.
  *
  * An INTERACTIVE run has no callback seam and keeps the component grant, which
  * is correct: a human started it, and there is no task to scope to.
@@ -14,25 +24,36 @@ import { componentKnowledge, openTaskHarness, taskKnowledge, } from "@zeroroot-a
  * A dispatch that carries an endpoint but no token FAILS rather than falling
  * back. Falling back is how the gap reappears silently, and a caller who wanted
  * task-scoped reads would get component-scoped ones without being told.
+ *
+ * `openTaskHarness` derives the `ContextInfo` every callback RPC carries from
+ * the grant's own claims, so a task-scoped read reaches the daemon naming the
+ * mission it belongs to. It also renews the grant on a timer, which is why the
+ * caller must {@link SelectedKnowledge.stop} the source when the session ends.
  */
-export function selectKnowledgeSource(session) {
+export function selectKnowledgeSource(session, deps = {}) {
     const endpoint = process.env.GIBSON_CALLBACK_ENDPOINT;
     const token = process.env.GIBSON_CALLBACK_TOKEN;
     if (!endpoint) {
-        return { knowledge: componentKnowledge(session.clients.component), scope: "component" };
+        return {
+            knowledge: componentKnowledge(session.clients.component),
+            scope: "component",
+            stop: () => { },
+        };
     }
     if (!token) {
         throw new Error("GIBSON_CALLBACK_ENDPOINT is set but GIBSON_CALLBACK_TOKEN is not. A dispatched run " +
             "must read with its task grant; falling back to the component grant would silently " +
             "widen this run's authority.");
     }
+    const harness = (deps.openHarness ?? openTaskHarness)({
+        endpoint,
+        token,
+        // A local or kind daemon may serve the callback listener without TLS.
+        insecure: process.env.GIBSON_CALLBACK_INSECURE === "1",
+    });
     return {
-        knowledge: taskKnowledge(openTaskHarness({
-            endpoint,
-            token,
-            // A local or kind daemon may serve the callback listener without TLS.
-            insecure: process.env.GIBSON_CALLBACK_INSECURE === "1",
-        })),
+        knowledge: taskKnowledge(harness),
         scope: "task",
+        stop: () => harness.stop(),
     };
 }

package/dist/knowledge.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { formatKnowledgeForPrompt, } from "@zeroroot-ai/sdk";
 /**
  * Knowledge — read the tenant graph so the agent sharpens across runs

package/dist/mcp-config.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 /**
  * How opencode reaches the Gibson MCP server (ADR-0008, slice A7).
  *

package/dist/opencode-run.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { spawn } from "node:child_process";
 /** Parse the NDJSON `opencode run --format json` writes to stdout. */
 export function parseOpencodeEvents(stdout) {

package/dist/semgrep.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 /**

package/dist/serve-agent.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 /**
  * zerocool-agent — run zerocool headless as a daemon-driven `kind=agent`.
  *

package/dist/serve.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 /**
  * zerocool-serve — run zerocool headless as a dispatched fleet component.
  *

package/dist/source-analysis.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { newFinding } from "@zeroroot-ai/sdk";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";

package/dist/watch.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Elastic-2.0
+// Copyright 2026 Zero Root AI
 import { buildCreateMissionRequest, remember, taskKnowledge } from "@zeroroot-ai/sdk";
 import { TRIGGER_STATUS } from "./gitlab.js";
 /**

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zeroroot-ai/zerocool",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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": "MIT",
+  "license": "Elastic-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zeroroot-ai/zerocool-plugins.git",
@@ -23,13 +23,13 @@
     "test": "tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\""
   },
   "dependencies": {
-    "@zeroroot-ai/sdk": "^0.11.0"
+    "@zeroroot-ai/sdk": "^0.12.0"
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "*"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "^1.18.11"
+    "@opencode-ai/plugin": "^1.18.27"
   },
   "bin": {
     "zerocool-serve": "dist/serve.js",