@desplega.ai/agent-swarm 2.5.2 → 2.5.4

package/src/tests/opencode-adapter.test.ts

@@ -10,6 +10,7 @@
 import { afterAll, afterEach, beforeAll, describe, expect, spyOn, test } from "bun:test";
 import type { OpenCodeEvent } from "@opencode/sdk";
 import { normalizeSessionLogs, type SessionLogRecord } from "../../apps/ui/src/logs-parser";
+import { renderContextBoundNote } from "../prompts/context-bound-note";
 import {
   _setOpencodeSdkLoaderForTests,
   _setOpencodeSessionHooksForTests,
@@ -22,6 +23,7 @@ import {
 import { createSkillInvokeTracker, type SkillInvoke } from "../providers/skill-invoke";
 import type { ProviderEvent, ProviderSessionConfig } from "../providers/types";
 import { clearVolatileSecretsForTesting } from "../utils/secret-scrubber";
+import { HELD_NOTE_TEXT, holdTemplateRender } from "./fixtures/held-template-render";
 
 const SESSION_ID = "ses_test";
 
@@ -68,6 +70,7 @@ type FakeHostOptions = {
   tools?: string[];
   /** Model responses handed to the plugin's `http.response` hook at startup. */
   responses?: Response[];
+  syntheticError?: Error;
 };
 
 /**
@@ -85,6 +88,7 @@ function makeFakeHost(events: OpenCodeEvent[], opts: FakeHostOptions = {}) {
     createOptions: undefined as unknown as Record<string, unknown>,
     created: [] as unknown[],
     prompts: [] as Array<Record<string, unknown>>,
+    synthetics: [] as Array<Record<string, unknown>>,
     interrupts: [] as unknown[],
     closeCalls: 0,
     mcpListCalls: 0,
@@ -116,6 +120,11 @@ function makeFakeHost(events: OpenCodeEvent[], opts: FakeHostOptions = {}) {
         host.interrupts.push(input);
         return {};
       },
+      synthetic: async (input: Record<string, unknown>) => {
+        host.synthetics.push(input);
+        if (opts.syntheticError) throw opts.syntheticError;
+        return {};
+      },
     },
     events: {
       async *subscribe() {
@@ -815,6 +824,131 @@ describe("OpencodeSession — abort and steering", () => {
   });
 });
 
+describe("OpencodeSession — context-bound note", () => {
+  const boundConfig = (threshold: string) =>
+    testConfig({ env: { CONTEXT_BOUND_NOTE_TOKENS: threshold } });
+  const step = (sessionID: string, input: number, read = 0, write = 0) =>
+    ev("session.step.ended", { sessionID, tokens: tokens(input, 10, read, write) });
+
+  test("steers the note once at the threshold, not again on a larger step", async () => {
+    const { session, host } = await startSession([], boundConfig("1000"));
+    // 600 input + 300 cache read + 100 cache write = 1,000 (output does not count).
+    session.handleOpencodeEvent(step(SESSION_ID, 500, 300, 100));
+    session.handleOpencodeEvent(step(SESSION_ID, 600, 300, 100));
+    session.handleOpencodeEvent(step(SESSION_ID, 5_000));
+    await waitFor(() => host.synthetics.length > 0);
+    await Bun.sleep(20);
+    expect(host.synthetics).toEqual([
+      {
+        sessionID: SESSION_ID,
+        text: await renderContextBoundNote(1_000, "openrouter/google/gemini-3-flash-preview"),
+        delivery: "steer",
+        resume: false,
+      },
+    ]);
+    expect(host.synthetics[0]?.text).toContain("1,000");
+    session.handleOpencodeEvent(succeeded);
+    expect((await session.waitForCompletion()).isError).toBe(false);
+  });
+
+  test("the note shows the window share for a known model and omits it for an unknown one", async () => {
+    const noteFor = async (model: string) => {
+      const { session, host } = await startSession(
+        [],
+        testConfig({ model, env: { CONTEXT_BOUND_NOTE_TOKENS: "1000" } }),
+      );
+      session.handleOpencodeEvent(step(SESSION_ID, 524_288));
+      await waitFor(() => host.synthetics.length > 0);
+      session.handleOpencodeEvent(succeeded);
+      await session.waitForCompletion();
+      return host.synthetics[0]?.text;
+    };
+    const rest =
+      "Keep this task bounded: finish the current step, store-progress, and complete or defer instead of starting new exploration.";
+    expect(await noteFor("openrouter/google/gemini-3-flash-preview")).toBe(
+      `Context is 524,288 tokens (50% of the 1,048,576-token window). ${rest}`,
+    );
+    expect(await noteFor("openrouter/made-up/model")).toBe(`Context is 524,288 tokens. ${rest}`);
+  });
+
+  test("off when CONTEXT_BOUND_NOTE_TOKENS is unset", async () => {
+    const { session, host } = await startSession([]);
+    session.handleOpencodeEvent(step(SESSION_ID, 900_000));
+    await Bun.sleep(20);
+    expect(host.synthetics).toEqual([]);
+    session.handleOpencodeEvent(succeeded);
+    await session.waitForCompletion();
+  });
+
+  test("no-op below the threshold and for a child session's steps", async () => {
+    const { session, host } = await startSession([], boundConfig("1000"));
+    session.handleOpencodeEvent(step(SESSION_ID, 999));
+    session.handleOpencodeEvent(step("ses_child", 50_000));
+    await Bun.sleep(20);
+    expect(host.synthetics).toEqual([]);
+    session.handleOpencodeEvent(succeeded);
+    await session.waitForCompletion();
+  });
+
+  test("off at 0", async () => {
+    const { session, host } = await startSession([], boundConfig("0"));
+    session.handleOpencodeEvent(step(SESSION_ID, 250_000));
+    await Bun.sleep(20);
+    expect(host.synthetics).toEqual([]);
+    session.handleOpencodeEvent(succeeded);
+    await session.waitForCompletion();
+  });
+
+  test("fails open on corrupt step tokens", async () => {
+    const { session, host } = await startSession([], boundConfig("1000"));
+    session.handleOpencodeEvent(
+      ev("session.step.ended", {
+        sessionID: SESSION_ID,
+        tokens: { input: "lots", output: 1, reasoning: 0, cache: { read: null, write: {} } },
+      }),
+    );
+    await Bun.sleep(20);
+    expect(host.synthetics).toEqual([]);
+    session.handleOpencodeEvent(succeeded);
+    expect((await session.waitForCompletion()).isError).toBe(false);
+  });
+
+  test("a rejected steer still lets the session complete", async () => {
+    const { session, host } = await startSession([], boundConfig("1000"), {
+      syntheticError: new Error("synthetic refused"),
+    });
+    session.handleOpencodeEvent(step(SESSION_ID, 5_000));
+    await waitFor(() => host.synthetics.length > 0);
+    session.handleOpencodeEvent(succeeded);
+    expect((await session.waitForCompletion()).isError).toBe(false);
+  });
+
+  test("a note rendered after the session completed is dropped", async () => {
+    const lateSynthetics = async (releaseInSession: boolean) => {
+      const held = holdTemplateRender();
+      try {
+        const { session, host } = await startSession([], boundConfig("1000"));
+        session.handleOpencodeEvent(step(SESSION_ID, 5_000));
+        await held.requested;
+        if (releaseInSession) {
+          held.release();
+          await waitFor(() => host.synthetics.length > 0);
+        }
+        session.handleOpencodeEvent(succeeded);
+        expect((await session.waitForCompletion()).isError).toBe(false);
+        held.release();
+        await Bun.sleep(50);
+        return host.synthetics.map((s) => s.text);
+      } finally {
+        held.stop();
+      }
+    };
+    expect(await lateSynthetics(false)).toEqual([]);
+    // Control: ready while the session runs.
+    expect(await lateSynthetics(true)).toEqual([HELD_NOTE_TEXT]);
+  });
+});
+
 describe("OpenRouter attribution config", () => {
   test("overrides harness attribution while preserving custom headers and options", () => {
     const config = {

package/src/tests/pi-mono-adapter.test.ts

@@ -12,6 +12,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { OPENAI_COMPATIBLE_PROVIDERS } from "@desplega/model-catalog";
 import * as piCodingAgent from "@earendil-works/pi-coding-agent";
+import { renderContextBoundNote } from "../prompts/context-bound-note";
 import { configureHttpResolver, resetHttpResolver } from "../prompts/resolver";
 import {
   checkPiMonoCredentials,
@@ -24,6 +25,7 @@ import {
   writeSessionModelsJson,
 } from "../providers/pi-mono-adapter";
 import type { ProviderSessionConfig } from "../providers/types";
+import { HELD_NOTE_TEXT, holdTemplateRender } from "./fixtures/held-template-render";
 
 describe("PiMonoAdapter", () => {
   test("name is 'pi'", () => {
@@ -1187,6 +1189,8 @@ function makeMockAgentSession(opts: {
   steerCalls?: string[];
   followUpCalls?: string[];
   steeringError?: string;
+  /** Awaited after each call's events, as a real turn keeps running its tools. */
+  afterEvents?: () => Promise<unknown>;
 }): AgentSession {
   const listeners: Array<(event: AgentSessionEvent) => void> = [];
   const scripts = opts.turns ?? [opts.events ?? []];
@@ -1210,6 +1214,7 @@ function makeMockAgentSession(opts: {
       for (const event of scripts[call] ?? []) {
         for (const l of listeners) l(event);
       }
+      await opts.afterEvents?.();
       if (opts.throwError) throw new Error(opts.throwError);
     },
     getContextUsage: () => null,
@@ -1754,3 +1759,103 @@ describe("classifyAwsSdkError — all 4 categories (quick summary)", () => {
     }
   });
 });
+
+describe("PiMonoSession context-bound note", () => {
+  /** An assistant `message_end` with this request usage; a tool call unless `final`. */
+  function assistantTurn(usage: unknown, final = false): AgentSessionEvent {
+    return {
+      type: "message_end",
+      message: {
+        role: "assistant",
+        content: final
+          ? [{ type: "text", text: "Done" }]
+          : [{ type: "toolCall", id: "call-1", name: "bash", arguments: {} }],
+        stopReason: final ? "stop" : "toolUse",
+        usage,
+      },
+    } as unknown as AgentSessionEvent;
+  }
+
+  const usage = (input: number) => ({ input, cacheRead: 300, cacheWrite: 200, output: 50 });
+
+  async function steersFor(
+    threshold: string,
+    events: AgentSessionEvent[],
+    afterEvents: () => Promise<unknown> = () => Bun.sleep(50),
+    model?: string,
+  ): Promise<string[]> {
+    const steerCalls: string[] = [];
+    const session = new PiMonoSession(
+      makeMockAgentSession({ events, steerCalls, afterEvents }),
+      {
+        ...makeSessionConfig(join(tmpLogDir, `bound-note-${crypto.randomUUID()}.log`)),
+        env: { CONTEXT_BOUND_NOTE_TOKENS: threshold },
+        ...(model ? { model } : {}),
+      },
+      false,
+    );
+    await session.waitForCompletion();
+    return steerCalls;
+  }
+
+  test("steers the note once when a tool-call request reaches the threshold", async () => {
+    const steers = await steersFor("1000", [
+      assistantTurn(usage(400)),
+      assistantTurn(usage(500)),
+      assistantTurn(usage(900)),
+      assistantTurn(usage(1500), true),
+    ]);
+    // 500 + 300 + 200 reaches 1000; the larger later request does not steer again.
+    expect(steers).toEqual([await renderContextBoundNote(1000)]);
+  });
+
+  test("the note shows the window share for a known model and omits it for an unknown one", async () => {
+    const events = () => [assistantTurn(usage(209_500)), assistantTurn(usage(400), true)];
+    const rest =
+      "Keep this task bounded: finish the current step, store-progress, and complete or defer instead of starting new exploration.";
+    expect(await steersFor("200000", events(), undefined, "anthropic/claude-sonnet-4-6")).toEqual([
+      `Context is 210,000 tokens (21% of the 1,000,000-token window). ${rest}`,
+    ]);
+    expect(await steersFor("200000", events(), undefined, "made-up/model")).toEqual([
+      `Context is 210,000 tokens. ${rest}`,
+    ]);
+  });
+
+  test("no-op below the threshold and when disabled at 0", async () => {
+    const events = [assistantTurn(usage(400)), assistantTurn(usage(400), true)];
+    expect(await steersFor("1000", events)).toEqual([]);
+    expect(await steersFor("0", events)).toEqual([]);
+  });
+
+  test("fails open on missing or corrupt usage", async () => {
+    const events = [
+      assistantTurn(undefined),
+      assistantTurn({ input: "lots", cacheRead: {}, cacheWrite: null }),
+      assistantTurn(undefined, true),
+    ];
+    expect(await steersFor("1", events)).toEqual([]);
+  });
+
+  test("never steers after the final reply, which would start another turn", async () => {
+    expect(await steersFor("1", [assistantTurn(usage(5000), true)])).toEqual([]);
+  });
+
+  test("a note rendered after its tool turn ended is dropped", async () => {
+    const turnEnd = { type: "turn_end" } as unknown as AgentSessionEvent;
+    const lateSteers = async (events: AgentSessionEvent[]) => {
+      const held = holdTemplateRender();
+      try {
+        return await steersFor("1", events, async () => {
+          held.release();
+          await Bun.sleep(50);
+        });
+      } finally {
+        held.stop();
+      }
+    };
+    // Pi already read steering for that turn; the next reply could be the final one.
+    expect(await lateSteers([assistantTurn(usage(5000)), turnEnd])).toEqual([]);
+    // Control: ready while the tool turn is still running.
+    expect(await lateSteers([assistantTurn(usage(5000))])).toEqual([HELD_NOTE_TEXT]);
+  });
+});

package/src/tests/prompt-template-session.test.ts

@@ -22,6 +22,7 @@ const SYSTEM_TEMPLATES = [
   "system.agent.communication",
   "system.agent.communication.remote",
   "system.agent.compaction.goal_reminder",
+  "system.agent.context.bound_note",
   "system.agent.cursor.first_message",
   "system.agent.lead",
   "system.agent.memory",
@@ -117,11 +118,11 @@ describe("Session templates: registration", () => {
     expect(sessionSystemEventTypes("session")).toEqual([...SESSION_TEMPLATES].sort());
   });
 
-  test("registers 31 system and session templates in total", () => {
+  test("registers 32 system and session templates in total", () => {
     const all = getAllTemplateDefinitions();
     const sessionSystem = all.filter((d) => d.category === "system" || d.category === "session");
-    // 26 system blocks + 5 session composites.
-    expect(sessionSystem.length).toBe(31);
+    // 27 system blocks + 5 session composites.
+    expect(sessionSystem.length).toBe(32);
   });
 
   test("drops the v1 blocks that prompt v2 deleted", () => {

package/src/tests/runner-push-delivery.test.ts

@@ -139,6 +139,31 @@ async function nudge(kind: WorkerNudge["kind"], taskId?: string) {
   expect((await waiting)?.kind).toBe(kind);
 }
 
+test("shutdown stops an open poll window before it can claim a resume", async () => {
+  let shuttingDown = false;
+  // The second poll would claim the resume created during shutdown.
+  pollTriggerAfter = 2;
+  const sleep = spyOn(Bun, "sleep").mockImplementation(async () => {
+    expect(requests.filter((r) => r === "GET /api/poll")).toHaveLength(1);
+    shuttingDown = true;
+  });
+  try {
+    const trigger = await pollForTrigger({
+      apiUrl,
+      apiKey,
+      agentId,
+      pollInterval: 2,
+      pollTimeout: 5000,
+      shouldStop: () => shuttingDown,
+    });
+    expect(shuttingDown).toBe(true);
+    expect(trigger).toBeNull();
+    expect(requests.filter((r) => r === "GET /api/poll")).toHaveLength(1);
+  } finally {
+    sleep.mockRestore();
+  }
+});
+
 async function poll(now: number, mode: DeliveryMode = "push") {
   const checks = delivery.checks(mode, now);
   const schedule = delivery.schedule({

package/src/tests/runtime-controller-liveness.test.ts

@@ -0,0 +1,133 @@
+import { afterEach, expect, spyOn, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createNetServer, type Socket } from "node:net";
+import { WebSocketServer } from "ws";
+import { startControllerClient } from "../commands/controller";
+import { CONTROLLER_PROTOCOL_VERSION } from "../runtime-providers/controller-protocol";
+import type { RuntimeProvider } from "../runtime-providers/types";
+import { listenOnFreePort } from "./test-net";
+
+const LIVENESS_MS = 300;
+const WELCOME = JSON.stringify({
+  type: "welcome",
+  controllerId: "controller-1",
+  version: CONTROLLER_PROTOCOL_VERSION,
+});
+
+const provider = {
+  kind: "docker",
+  traits: { canProvision: true, ephemeralDisk: true, supportsPause: false },
+  checkConfig: () => ({ ready: true, missing: [] }),
+} as unknown as RuntimeProvider;
+
+const cleanups: Array<() => void> = [];
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0).reverse()) cleanup();
+});
+
+// A raw TCP WebSocket peer. Under Bun, `ws` maps to a native shim that always answers
+// pings, so it cannot model a dead link. This peer completes the handshake, sends
+// welcome, and then never answers a frame: what a cut network looks like to the client.
+async function startRawServer(options: { pingEveryMs?: number } = {}) {
+  let connections = 0;
+  const sockets: Socket[] = [];
+  const server = createNetServer((socket) => {
+    sockets.push(socket);
+    socket.once("data", (data) => {
+      const key = /sec-websocket-key: *(\S+)/i.exec(data.toString())?.[1];
+      const accept = createHash("sha1")
+        .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+        .digest("base64");
+      socket.write(
+        `HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`,
+      );
+      const payload = Buffer.from(WELCOME);
+      socket.write(Buffer.concat([Buffer.from([0x81, payload.length]), payload]));
+      connections++;
+      if (options.pingEveryMs) {
+        const timer = setInterval(
+          () => socket.write(Buffer.from([0x89, 0x00])),
+          options.pingEveryMs,
+        );
+        socket.once("close", () => clearInterval(timer));
+      }
+    });
+    socket.on("error", () => {});
+  });
+  const port = await listenOnFreePort(server);
+  cleanups.push(() => {
+    for (const socket of sockets) socket.destroy();
+    server.close();
+  });
+  return { apiUrl: `http://127.0.0.1:${port}`, connections: () => connections };
+}
+
+function startClient(apiUrl: string) {
+  const logSpy = spyOn(console, "log").mockImplementation(() => {});
+  const client = startControllerClient({
+    apiUrl,
+    token: "aseph_test-token",
+    provider,
+    target: {},
+    livenessTimeoutMs: LIVENESS_MS,
+  });
+  cleanups.push(() => {
+    client.stop();
+    logSpy.mockRestore();
+  });
+  return { logs: () => logSpy.mock.calls.flat().join("\n") };
+}
+
+async function until(check: () => boolean, timeoutMs: number) {
+  const deadline = Date.now() + timeoutMs;
+  while (!check()) {
+    if (Date.now() > deadline) throw new Error("Timed out waiting for condition");
+    await Bun.sleep(20);
+  }
+}
+
+test("a server that goes silent without closing makes the client reconnect", async () => {
+  const server = await startRawServer();
+  const { logs } = startClient(server.apiUrl);
+  await until(() => logs().includes("Connected as controller-1"), 2000);
+  const silentAt = Date.now();
+  // Detection within the timeout plus one check interval, then the first backoff (at most 1000ms).
+  await until(() => server.connections() === 2, LIVENESS_MS * 2 + 1500);
+  expect(logs()).toContain(`No traffic for ${LIVENESS_MS}ms`);
+  expect(logs()).toContain("Disconnected. Reconnect in");
+  expect(Date.now() - silentAt).toBeGreaterThanOrEqual(LIVENESS_MS);
+});
+
+test("server ping frames keep an idle controller connected", async () => {
+  // Matches the API: it pings on an interval and sends no app message to an idle controller.
+  // This peer never answers the client's pings, so only the server pings count.
+  const server = await startRawServer({ pingEveryMs: LIVENESS_MS / 3 });
+  const { logs } = startClient(server.apiUrl);
+  await until(() => logs().includes("Connected as controller-1"), 2000);
+  await Bun.sleep(LIVENESS_MS * 4);
+  expect(server.connections()).toBe(1);
+  expect(logs()).not.toContain("Disconnected");
+});
+
+test("pongs to client pings keep an idle controller connected", async () => {
+  // A healthy peer that sends nothing on its own still answers pings.
+  const http = createHttpServer();
+  const wss = new WebSocketServer({ server: http });
+  let connections = 0;
+  wss.on("connection", (ws) => {
+    connections++;
+    ws.send(WELCOME);
+  });
+  const port = await listenOnFreePort(http);
+  cleanups.push(() => {
+    for (const ws of wss.clients) ws.terminate();
+    wss.close();
+    http.close();
+  });
+  const { logs } = startClient(`http://127.0.0.1:${port}`);
+  await until(() => logs().includes("Connected as controller-1"), 2000);
+  await Bun.sleep(LIVENESS_MS * 4);
+  expect(connections).toBe(1);
+  expect(logs()).not.toContain("Disconnected");
+});

package/src/tests/runtime-providers-docker.test.ts

@@ -310,6 +310,7 @@ describe("Docker runtime provider", () => {
     await provider.terminate(target, handle);
     expect(calls[0]?.init.method).toBe("DELETE");
     expect(calls[0]?.url.searchParams.get("force")).toBe("true");
+    expect(calls[0]?.url.searchParams.get("v")).toBe("true");
   });
 
   test("termination succeeds when the container is already absent", async () => {
@@ -376,6 +377,7 @@ describe("Docker runtime provider", () => {
         "DELETE /v1.47/containers/container-1",
       ]);
       expect(calls[2]?.url.searchParams.get("force")).toBe("true");
+      expect(calls[2]?.url.searchParams.get("v")).toBe("true");
     }
   });
 

package/src/tests/script-connections.test.ts

@@ -570,6 +570,9 @@ describe("script connections", () => {
       markMigrationApplied(database, "151_repair_scheduled_task_required_params.sql");
       // 152 indexes task routing context absent from this migration-112-only fixture.
       markMigrationApplied(database, "152_routing_decisions.sql");
+      // 153 drops a column, so SQLite revalidates 144's agent_tasks triggers
+      // against this fixture's id-only agent_tasks (Bun < 1.4.4 hid the error).
+      markMigrationApplied(database, "153_deferred_task_wait_members.sql");
       // 156 alters inbox_item_state, which this migration-112-only fixture does not create.
       markMigrationApplied(database, "156_inbox_item_state_read_at.sql");
       // 157 alters scheduled_tasks and slack_messages, neither of which this
@@ -642,6 +645,12 @@ describe("script connections", () => {
       markMigrationApplied(database, "235_chat_relay_defer.sql");
       // 237 reads approval_requests and inbox_item_state, which this migration-112-only fixture does not create.
       markMigrationApplied(database, "237_session_inbox_cleanup.sql");
+      // 239 indexes skills, which this migration-112-only fixture does not create.
+      markMigrationApplied(database, "239_skills_fts.sql");
+      // 240 alters workflow_runs, which this migration-112-only fixture does not create.
+      markMigrationApplied(database, "240_workflow_run_parent_step_attempt.sql");
+      // 241 indexes skills, which this migration-112-only fixture does not create.
+      markMigrationApplied(database, "241_skills_meta_fts.sql");
 
       const id = crypto.randomUUID();
       const now = new Date().toISOString();

package/src/tests/script-run-config-scope.test.ts

@@ -2,7 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { createServer, type Server } from "node:http";
 import { closeDb, createAgent, initDb, upsertSwarmConfig } from "../be/db";
-import { mintScriptRunToken, revokeSessionToken } from "../be/users";
+import { mintAgentToken, mintScriptRunToken, revokeSessionToken } from "../be/users";
 import { handleConfig } from "../http/config";
 import { handleCore } from "../http/core";
 import { handleSessions } from "../http/sessions";
@@ -17,12 +17,16 @@ import { listenOnFreePort } from "./test-net";
 const API_KEY = `script-run-config-operator-${randomBytes(8).toString("hex")}`;
 const WORKER_SECRET = `worker-secret-${randomBytes(8).toString("hex")}`;
 const OTHER_SECRET = `other-secret-${randomBytes(8).toString("hex")}`;
+const GLOBAL_SECRET = `global-secret-${randomBytes(8).toString("hex")}`;
+const SHADOWED_GLOBAL = `shadowed-global-${randomBytes(8).toString("hex")}`;
+const SHADOWING_AGENT = `shadowing-agent-${randomBytes(8).toString("hex")}`;
 
 let server: Server;
 let baseUrl: string;
 let workerId: string;
 let otherId: string;
 let otherConfigId: string;
+let ownConfigId: string;
 
 function headers(bearer: string, agentId?: string): Record<string, string> {
   return {
@@ -36,11 +40,32 @@ beforeAll(async () => {
   initDb(":memory:");
   workerId = (await createAgent({ name: "script-run-worker", isLead: false, status: "idle" })).id;
   otherId = (await createAgent({ name: "script-run-other", isLead: false, status: "idle" })).id;
+  ownConfigId = (
+    await upsertSwarmConfig({
+      scope: "agent",
+      scopeId: workerId,
+      key: "OWN_SECRET",
+      value: WORKER_SECRET,
+      isSecret: true,
+    })
+  ).id;
+  await upsertSwarmConfig({
+    scope: "global",
+    key: "GLOBAL_SECRET",
+    value: GLOBAL_SECRET,
+    isSecret: true,
+  });
+  await upsertSwarmConfig({
+    scope: "global",
+    key: "SHADOWED",
+    value: SHADOWED_GLOBAL,
+    isSecret: true,
+  });
   await upsertSwarmConfig({
     scope: "agent",
     scopeId: workerId,
-    key: "OWN_SECRET",
-    value: WORKER_SECRET,
+    key: "SHADOWED",
+    value: SHADOWING_AGENT,
     isSecret: true,
   });
   otherConfigId = (
@@ -118,3 +143,66 @@ describe("script run token is scoped to its executing agent", () => {
     }
   });
 });
+
+// `ctx.swarm.config` holds the run's resolved config (own agent over global).
+// The raw list and by-id reads must hand the run's token those same values,
+// and only those, or a script that reads a key through `config_list` gets a
+// masked placeholder and fails while the run already holds the real value.
+describe("script run token reads its held secrets on the raw config routes", () => {
+  test("list reveals the rows the run holds and masks the rest", async () => {
+    const run = await mintScriptRunToken(workerId, 60_000);
+    try {
+      const res = await fetch(`${baseUrl}/api/config?includeSecrets=true`, {
+        headers: headers(run.plaintext),
+      });
+      expect(res.status).toBe(200);
+      const body = await res.text();
+      expect(body).toContain(WORKER_SECRET);
+      expect(body).toContain(GLOBAL_SECRET);
+      expect(body).toContain(SHADOWING_AGENT);
+      // The run holds the agent row for SHADOWED, not the global one.
+      expect(body).not.toContain(SHADOWED_GLOBAL);
+      expect(body).not.toContain(OTHER_SECRET);
+    } finally {
+      await revokeSessionToken(run.tokenId);
+    }
+  });
+
+  test("by-id reveals an own row and masks another agent's row", async () => {
+    const run = await mintScriptRunToken(workerId, 60_000);
+    try {
+      const own = await fetch(`${baseUrl}/api/config/${ownConfigId}?includeSecrets=true`, {
+        headers: headers(run.plaintext),
+      });
+      expect(await own.text()).toContain(WORKER_SECRET);
+      const other = await fetch(`${baseUrl}/api/config/${otherConfigId}?includeSecrets=true`, {
+        headers: headers(run.plaintext),
+      });
+      expect(other.status).toBe(200);
+      expect(await other.text()).not.toContain(OTHER_SECRET);
+    } finally {
+      await revokeSessionToken(run.tokenId);
+    }
+  });
+
+  test("without includeSecrets the run token still gets masked values", async () => {
+    const run = await mintScriptRunToken(workerId, 60_000);
+    try {
+      const res = await fetch(`${baseUrl}/api/config`, { headers: headers(run.plaintext) });
+      expect(await res.text()).not.toContain(WORKER_SECRET);
+    } finally {
+      await revokeSessionToken(run.tokenId);
+    }
+  });
+
+  test("the worker's own agent token keeps the masked list", async () => {
+    const worker = await mintAgentToken(workerId);
+    const res = await fetch(`${baseUrl}/api/config?includeSecrets=true`, {
+      headers: headers(worker.plaintext),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.text();
+    expect(body).not.toContain(WORKER_SECRET);
+    expect(body).not.toContain(GLOBAL_SECRET);
+  });
+});