@stigmer/runner 3.4.1 → 3.5.0

package/dist/tools/url-guard.js

@@ -0,0 +1,211 @@
+/**
+ * URL guard for the native `web_fetch` tool — the SSRF boundary.
+ *
+ * Why this is load-bearing: `web_fetch` is deliberately auto-approved (see
+ * shared/tool-kind.ts `toolApprovalCategory`), so in unattended runs it is
+ * the only ungated network path an agent has. On managed cloud runners the
+ * fetch executes inside the runner process, which sits on infrastructure
+ * with network reach to internal services and the cloud metadata endpoint —
+ * without this guard, "fetch a URL" becomes "read my pod's credentials".
+ *
+ * Posture is mode-aware because locality differs, not trust:
+ *
+ * - "strict" (managed cloud runners): loopback, RFC 1918 private,
+ *   link-local, and their IPv6 equivalents are all rejected.
+ * - "relaxed" (self-hosted / local runners): the machine belongs to the
+ *   user, and fetching their own dev server (http://localhost:3000) is a
+ *   legitimate ask — only the link-local range (which contains the cloud
+ *   metadata endpoint 169.254.169.254) stays blocked, as costless
+ *   defense-in-depth.
+ *
+ * The default posture derives from Config.mode ("cloud" → strict), NOT from
+ * cloudModeEnabled — that is the Cursor cloud-agent feature flag and says
+ * nothing about where this process runs. Config.mode tracks credential
+ * transport rather than physical locality (a desktop runner proxies traffic
+ * while executing on the user's machine), so STIGMER_WEB_FETCH_ALLOW_PRIVATE
+ * exists as an explicit override for embedders that know better. Managed
+ * cloud deployments never set it.
+ *
+ * Validation runs on the addresses DNS resolves to immediately before the
+ * request is dispatched, and the caller re-validates every redirect hop.
+ * Accepted limitation: a DNS-rebinding window remains between our lookup
+ * and the socket connect — Node's fetch (undici) offers no lookup pinning
+ * without replacing the dispatcher, and the strict posture's range blocks
+ * make the rebinding payoff (an internal address) unreachable anyway.
+ */
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+/** Thrown for every guard rejection; message is safe to surface to the model. */
+export class UrlGuardError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UrlGuardError";
+    }
+}
+/**
+ * Derive the guard posture from runner mode plus the explicit override.
+ *
+ * @param mode Config.mode — "cloud" means a managed runner on shared infrastructure.
+ * @param env  Environment to read STIGMER_WEB_FETCH_ALLOW_PRIVATE from.
+ */
+export function resolveGuardPosture(mode, env = process.env) {
+    const override = env.STIGMER_WEB_FETCH_ALLOW_PRIVATE;
+    if (override === "true")
+        return "relaxed";
+    if (override === "false")
+        return "strict";
+    return mode === "cloud" ? "strict" : "relaxed";
+}
+/**
+ * Validate a URL for fetching under the given posture.
+ *
+ * Checks the scheme, then resolves the hostname and checks EVERY address it
+ * resolves to (a hostname with one public and one private A record must be
+ * rejected, or the private record becomes the bypass).
+ *
+ * @returns the parsed URL on success.
+ * @throws UrlGuardError with a model-readable reason on rejection.
+ */
+export async function validateFetchUrl(rawUrl, posture) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new UrlGuardError(`Invalid URL: ${rawUrl}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new UrlGuardError(`Unsupported URL scheme "${url.protocol.replace(/:$/, "")}" — only http and https are allowed.`);
+    }
+    const addresses = await resolveAddresses(url.hostname);
+    for (const address of addresses) {
+        const reason = blockedReason(address, posture);
+        if (reason) {
+            throw new UrlGuardError(`Refusing to fetch ${url.hostname}: it resolves to ${address}, a ${reason} address that this runner does not fetch from.`);
+        }
+    }
+    return url;
+}
+/**
+ * Resolve a hostname to all of its addresses. Literal IPs pass through
+ * (bracketed IPv6 hosts arrive from URL.hostname still bracketed).
+ */
+async function resolveAddresses(hostname) {
+    const literal = hostname.replace(/^\[|\]$/g, "");
+    if (isIP(literal) !== 0) {
+        return [literal];
+    }
+    try {
+        const records = await lookup(hostname, { all: true, verbatim: true });
+        return records.map((r) => r.address);
+    }
+    catch {
+        throw new UrlGuardError(`Could not resolve hostname: ${hostname}`);
+    }
+}
+/**
+ * Classify an IP address against the posture's blocked ranges.
+ *
+ * @returns a human-readable range name when blocked, or null when allowed.
+ */
+export function blockedReason(address, posture) {
+    const family = isIP(address);
+    if (family === 4) {
+        return blockedReasonV4(address, posture);
+    }
+    if (family === 6) {
+        const groups = expandV6(address);
+        if (!groups)
+            return "unrecognized";
+        // IPv4-mapped IPv6 (::ffff:a.b.c.d, in dotted OR hex form) — classify
+        // the embedded IPv4 so the mapping cannot smuggle a blocked v4 address
+        // past the guard.
+        const embedded = extractMappedV4(groups);
+        if (embedded) {
+            return blockedReasonV4(embedded, posture);
+        }
+        return blockedReasonV6(groups, posture);
+    }
+    // Unparseable — fail closed; only real addresses get sockets.
+    return "unrecognized";
+}
+function blockedReasonV4(address, posture) {
+    const octets = address.split(".").map(Number);
+    if (octets.length !== 4 || octets.some((o) => Number.isNaN(o) || o < 0 || o > 255)) {
+        return "unrecognized";
+    }
+    const [a, b] = octets;
+    // Link-local (169.254.0.0/16) hosts the cloud metadata service at
+    // 169.254.169.254 — blocked under BOTH postures.
+    if (a === 169 && b === 254)
+        return "link-local (cloud metadata)";
+    if (posture === "relaxed")
+        return null;
+    if (a === 127)
+        return "loopback";
+    if (a === 0)
+        return "unspecified";
+    if (a === 10)
+        return "private (RFC 1918)";
+    if (a === 172 && b >= 16 && b <= 31)
+        return "private (RFC 1918)";
+    if (a === 192 && b === 168)
+        return "private (RFC 1918)";
+    return null;
+}
+function blockedReasonV6(groups, posture) {
+    // fe80::/10 — IPv6 link-local, the v6 sibling of the metadata range;
+    // blocked under BOTH postures for symmetry with v4.
+    if ((groups[0] & 0xffc0) === 0xfe80)
+        return "link-local (cloud metadata)";
+    if (posture === "relaxed")
+        return null;
+    const allZero = groups.every((g) => g === 0);
+    if (allZero)
+        return "unspecified";
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return "loopback";
+    // fc00::/7 — unique local (private) addresses.
+    if ((groups[0] & 0xfe00) === 0xfc00)
+        return "private (unique local)";
+    return null;
+}
+/**
+ * Expand an IPv6 address (already validated by isIP) into its 8 groups.
+ * Handles `::` compression, a trailing dotted-IPv4 tail, and zone suffixes.
+ */
+function expandV6(address) {
+    let text = address.toLowerCase().split("%")[0];
+    // Convert a dotted-IPv4 tail (e.g. ::ffff:127.0.0.1) into two hex groups.
+    const v4Tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+    if (v4Tail) {
+        const octets = v4Tail[1].split(".").map(Number);
+        if (octets.length !== 4 || octets.some((o) => o > 255))
+            return null;
+        const hex = `${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+        text = text.slice(0, -v4Tail[1].length) + hex;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const parseHalf = (half) => half === "" ? [] : half.split(":").map((g) => parseInt(g, 16));
+    const head = parseHalf(halves[0]);
+    const tail = halves.length === 2 ? parseHalf(halves[1]) : [];
+    const fill = 8 - head.length - tail.length;
+    if (halves.length === 2 ? fill < 0 : head.length !== 8)
+        return null;
+    const groups = [...head, ...(halves.length === 2 ? Array(fill).fill(0) : []), ...tail];
+    if (groups.length !== 8 || groups.some((g) => Number.isNaN(g) || g < 0 || g > 0xffff)) {
+        return null;
+    }
+    return groups;
+}
+/** Extract the IPv4 payload from IPv4-mapped groups (::ffff:0:0/96), if any. */
+function extractMappedV4(groups) {
+    const isMapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
+    if (!isMapped)
+        return null;
+    const [hi, lo] = [groups[6], groups[7]];
+    return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+}
+//# sourceMappingURL=url-guard.js.map

package/dist/tools/url-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-guard.js","sourceRoot":"","sources":["../../src/tools/url-guard.ts"],"names":[],"mappings":"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"}

package/dist/tools/web-fetch-tool.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Native `web_fetch` tool — built-in URL retrieval for the deep-agent harness.
+ *
+ * Closes the harness parity gap of stigmer/stigmer#214: the Cursor harness
+ * ships WebFetch as a CLI built-in, while native runs previously needed an
+ * MCP server (seedpack `fetch`) for the same capability. Both tool names
+ * classify to TOOL_KIND_FETCH, so rendering is identical across harnesses.
+ *
+ * Design constraints, in order:
+ *
+ * - Security: every URL — including every redirect hop — passes the URL
+ *   guard (url-guard.ts). web_fetch is auto-approved, so the guard is the
+ *   only boundary between "fetch a page" and the runner's network position.
+ * - Model ergonomics: HTML is reduced to Markdown (turndown, with obvious
+ *   chrome stripped), and `start_index`/`max_length` give the model
+ *   deterministic pagination over large pages — the same surface the
+ *   seedpack fetch MCP exposed, so existing agent instructions keep working.
+ * - Budget discipline: the default window (20 000 chars) sits deliberately
+ *   below the tool-truncation middleware's 30 000-char default, so the
+ *   truncation layer never chops fetch output and the model's pagination
+ *   arithmetic stays exact.
+ *
+ * Failures return a plain "Error: …" string instead of throwing: a fetch
+ * miss is information the model should route around (try the .md export,
+ * cite a different page), not an execution fault.
+ */
+import { z } from "zod";
+import { type GuardPosture } from "./url-guard.js";
+export interface WebFetchToolOptions {
+    /** URL guard posture — derive via resolveGuardPosture(config.mode). */
+    readonly posture: GuardPosture;
+}
+export declare function createWebFetchTool(options: WebFetchToolOptions): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    url: z.ZodString;
+    max_length: z.ZodOptional<z.ZodNumber>;
+    start_index: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    max_length?: number | undefined;
+    start_index?: number | undefined;
+}, {
+    url: string;
+    max_length?: number | undefined;
+    start_index?: number | undefined;
+}>, {
+    url: string;
+    max_length?: number | undefined;
+    start_index?: number | undefined;
+}, {
+    url: string;
+    max_length?: number | undefined;
+    start_index?: number | undefined;
+}, string, unknown, "web_fetch">;

package/dist/tools/web-fetch-tool.js

@@ -0,0 +1,216 @@
+/**
+ * Native `web_fetch` tool — built-in URL retrieval for the deep-agent harness.
+ *
+ * Closes the harness parity gap of stigmer/stigmer#214: the Cursor harness
+ * ships WebFetch as a CLI built-in, while native runs previously needed an
+ * MCP server (seedpack `fetch`) for the same capability. Both tool names
+ * classify to TOOL_KIND_FETCH, so rendering is identical across harnesses.
+ *
+ * Design constraints, in order:
+ *
+ * - Security: every URL — including every redirect hop — passes the URL
+ *   guard (url-guard.ts). web_fetch is auto-approved, so the guard is the
+ *   only boundary between "fetch a page" and the runner's network position.
+ * - Model ergonomics: HTML is reduced to Markdown (turndown, with obvious
+ *   chrome stripped), and `start_index`/`max_length` give the model
+ *   deterministic pagination over large pages — the same surface the
+ *   seedpack fetch MCP exposed, so existing agent instructions keep working.
+ * - Budget discipline: the default window (20 000 chars) sits deliberately
+ *   below the tool-truncation middleware's 30 000-char default, so the
+ *   truncation layer never chops fetch output and the model's pagination
+ *   arithmetic stays exact.
+ *
+ * Failures return a plain "Error: …" string instead of throwing: a fetch
+ * miss is information the model should route around (try the .md export,
+ * cite a different page), not an execution fault.
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import TurndownService from "turndown";
+import { validateFetchUrl, UrlGuardError } from "./url-guard.js";
+/** Ceiling on response bytes read from the wire, before any conversion. */
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+/** Per-request timeout; applied to each redirect hop independently. */
+const REQUEST_TIMEOUT_MS = 15_000;
+/** Redirect chain limit — matches the common browser/curl default region. */
+const MAX_REDIRECTS = 5;
+/** Default pagination window; see file header for why it is below 30 000. */
+const DEFAULT_MAX_LENGTH = 20_000;
+/** Hard ceiling for a caller-supplied max_length. */
+const MAX_MAX_LENGTH = 100_000;
+const USER_AGENT = "Stigmer/1.0 (web_fetch; +https://stigmer.ai)";
+export function createWebFetchTool(options) {
+    return tool(async (input) => {
+        try {
+            return await runFetch(input, options.posture);
+        }
+        catch (err) {
+            if (err instanceof UrlGuardError) {
+                return `Error: ${err.message}`;
+            }
+            if (err instanceof Error && err.name === "TimeoutError") {
+                return `Error: Fetching ${input.url} timed out after ${REQUEST_TIMEOUT_MS / 1000}s.`;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            return `Error: Failed to fetch ${input.url}: ${message}`;
+        }
+    }, {
+        name: "web_fetch",
+        description: "Fetch the contents of a URL over http(s). HTML pages are converted " +
+            "to Markdown; plain text, Markdown, JSON, and other text formats are " +
+            "returned as-is. Binary content is not supported.\n\n" +
+            "Large pages are windowed: at most max_length characters are " +
+            "returned per call (default 20000). If the result ends with a " +
+            "truncation notice, call web_fetch again with the same url and the " +
+            "start_index the notice gives you to continue reading.",
+        schema: z.object({
+            url: z.string().describe("The http(s) URL to fetch."),
+            max_length: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_MAX_LENGTH)
+                .optional()
+                .describe(`Maximum characters to return (default ${DEFAULT_MAX_LENGTH}).`),
+            start_index: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Character offset to start from, for paginating large pages (default 0)."),
+        }),
+    });
+}
+async function runFetch(input, posture) {
+    const maxLength = input.max_length ?? DEFAULT_MAX_LENGTH;
+    const startIndex = input.start_index ?? 0;
+    const { response, finalUrl } = await fetchFollowingRedirects(input.url, posture);
+    if (!response.ok) {
+        // Drain defensively; some agents (undici) keep the connection reserved otherwise.
+        await response.body?.cancel().catch(() => undefined);
+        return `Error: ${finalUrl} responded with HTTP ${response.status} ${response.statusText}.`;
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!isTextual(contentType)) {
+        await response.body?.cancel().catch(() => undefined);
+        return (`Error: ${finalUrl} returned non-text content (${contentType || "unknown type"}). ` +
+            "web_fetch only supports text formats.");
+    }
+    const { text, bytesTruncated } = await readBodyCapped(response, MAX_RESPONSE_BYTES);
+    const content = isHtml(contentType) ? htmlToMarkdown(text) : text;
+    return paginate(content, {
+        url: finalUrl,
+        startIndex,
+        maxLength,
+        bytesTruncated,
+    });
+}
+/**
+ * Fetch with `redirect: "manual"`, re-validating each hop against the URL
+ * guard — automatic following would let a public host 302 the runner into
+ * a private address, bypassing the pre-flight check entirely.
+ */
+async function fetchFollowingRedirects(rawUrl, posture) {
+    let url = await validateFetchUrl(rawUrl, posture);
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        const response = await fetch(url, {
+            redirect: "manual",
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                "user-agent": USER_AGENT,
+                accept: "text/html, text/markdown;q=0.9, text/plain;q=0.8, application/json;q=0.7, */*;q=0.5",
+            },
+        });
+        if (response.status < 300 || response.status >= 400) {
+            return { response, finalUrl: url.toString() };
+        }
+        const location = response.headers.get("location");
+        await response.body?.cancel().catch(() => undefined);
+        if (!location) {
+            throw new Error(`redirect (HTTP ${response.status}) without a Location header`);
+        }
+        // Resolve relative redirects against the current hop, then re-guard.
+        url = await validateFetchUrl(new URL(location, url).toString(), posture);
+    }
+    throw new Error(`too many redirects (more than ${MAX_REDIRECTS})`);
+}
+/** Stream the body, stopping at the byte cap instead of buffering unbounded. */
+async function readBodyCapped(response, maxBytes) {
+    if (!response.body) {
+        return { text: "", bytesTruncated: false };
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    let bytesTruncated = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            total += value.byteLength;
+            if (total > maxBytes) {
+                chunks.push(value.subarray(0, value.byteLength - (total - maxBytes)));
+                bytesTruncated = true;
+                await reader.cancel().catch(() => undefined);
+                break;
+            }
+            chunks.push(value);
+        }
+    }
+    const merged = new Uint8Array(chunks.reduce((n, c) => n + c.byteLength, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { text: new TextDecoder("utf-8").decode(merged), bytesTruncated };
+}
+function isHtml(contentType) {
+    return /text\/html|application\/xhtml\+xml/i.test(contentType);
+}
+function isTextual(contentType) {
+    if (contentType === "")
+        return true; // no header — assume text, the cap bounds the damage
+    return /^(text\/|application\/(json|xml|xhtml\+xml|rss\+xml|atom\+xml|javascript|x-yaml|yaml|toml))/i.test(contentType);
+}
+/**
+ * Reduce HTML to Markdown. Page chrome that never carries answerable
+ * content (scripts, styles, navigation, embedded media shells) is removed
+ * before conversion so the pagination window is spent on substance.
+ */
+function htmlToMarkdown(html) {
+    const turndown = new TurndownService({
+        headingStyle: "atx",
+        codeBlockStyle: "fenced",
+        bulletListMarker: "-",
+    });
+    turndown.remove([
+        "script", "style", "noscript", "iframe", "object", "embed",
+        "nav", "aside", "footer", "form", "button", "select", "canvas",
+    ]);
+    const markdown = turndown.turndown(html);
+    // Collapse the blank-line runs left behind by removed blocks.
+    return markdown.replace(/\n{3,}/g, "\n\n").trim();
+}
+/** Apply the start_index/max_length window and explain any truncation. */
+function paginate(content, opts) {
+    if (opts.startIndex >= content.length && content.length > 0) {
+        return `Error: start_index ${opts.startIndex} is beyond the end of the content (${content.length} characters).`;
+    }
+    if (content.length === 0) {
+        return `[${opts.url} returned an empty body]`;
+    }
+    const window = content.slice(opts.startIndex, opts.startIndex + opts.maxLength);
+    const end = opts.startIndex + window.length;
+    const notices = [];
+    if (end < content.length) {
+        notices.push(`[Content truncated at ${end} of ${content.length} characters. ` +
+            `Call web_fetch again with start_index=${end} to continue.]`);
+    }
+    if (opts.bytesTruncated) {
+        notices.push(`[The response exceeded the ${MAX_RESPONSE_BYTES / (1024 * 1024)} MB fetch limit and was cut off.]`);
+    }
+    return notices.length > 0 ? `${window}\n\n${notices.join("\n")}` : window;
+}
+//# sourceMappingURL=web-fetch-tool.js.map

package/dist/tools/web-fetch-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch-tool.js","sourceRoot":"","sources":["../../src/tools/web-fetch-tool.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.4.1",
+    "@stigmer/protos": "3.5.0",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",
@@ -98,6 +98,7 @@
     "js-yaml": "^4.1.1",
     "proper-lockfile": "^4.1.2",
     "semver": "^7.8.0",
+    "turndown": "^7.2.4",
     "zod": "^3.25.0",
     "zod-to-json-schema": "^3.24.0"
   },
@@ -106,6 +107,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/proper-lockfile": "^4.1.4",
     "@types/semver": "^7.7.1",
+    "@types/turndown": "^5.0.6",
     "esbuild": "^0.28.0",
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",

package/src/__tests__/otel-metrics.test.ts

@@ -13,6 +13,9 @@ describe("OTel Metrics Registry", () => {
     expect(instruments.activityDuration).toBeDefined();
     expect(instruments.workflowTaskDuration).toBeDefined();
     expect(instruments.workflowTaskCount).toBeDefined();
+    expect(instruments.runnerBootDuration).toBeDefined();
+    expect(instruments.executionSetupDuration).toBeDefined();
+    expect(instruments.poolAttachDuration).toBeDefined();
   });
 
   it("returns the same singleton on repeated calls", async () => {
@@ -29,6 +32,9 @@ describe("OTel Metrics Registry", () => {
     expect(() => instruments.activityDuration.record(150)).not.toThrow();
     expect(() => instruments.workflowTaskDuration.record(42)).not.toThrow();
     expect(() => instruments.workflowTaskCount.add(1, { "task.kind": "set" })).not.toThrow();
+    expect(() => instruments.runnerBootDuration.record(6200, { mode: "cloud" })).not.toThrow();
+    expect(() => instruments.executionSetupDuration.record(3000, { harness: "cursor" })).not.toThrow();
+    expect(() => instruments.poolAttachDuration.record(400)).not.toThrow();
   });
 
   it("reset allows re-creation", async () => {

package/src/__tests__/pool-member.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, afterEach } from "vitest";
+import {
+  decidePoolBoot,
+  registerPoolMemberContext,
+  getPoolMemberContext,
+  clearPoolMemberContext,
+  type PoolAttachTarget,
+} from "../pool-member.js";
+
+/** Build an unsigned JWT-shaped token with the given payload. */
+function fakeJwt(payload: Record<string, unknown>): string {
+  const b64 = (obj: Record<string, unknown>) =>
+    Buffer.from(JSON.stringify(obj)).toString("base64url");
+  return `${b64({ alg: "RS256", typ: "JWT" })}.${b64(payload)}.signature`;
+}
+
+const noopManager: PoolAttachTarget = {
+  addSession: async () => {},
+  updateToken: () => {},
+};
+
+describe("decidePoolBoot", () => {
+  it("polls the control queue with a fresh pool_sandbox credential", () => {
+    const intent = decidePoolBoot(fakeJwt({ token_type: "pool_sandbox", pool_member_id: "pm_1" }));
+    expect(intent).toEqual({ kind: "pool-control" });
+  });
+
+  it("resumes the claimed session when the Secret already holds a session token (post-claim restart)", () => {
+    const intent = decidePoolBoot(fakeJwt({ token_type: "sandbox", session_id: "ses_9" }));
+    expect(intent).toEqual({ kind: "claimed-session", sessionId: "ses_9" });
+  });
+
+  it("rejects a session token without a session_id claim", () => {
+    const intent = decidePoolBoot(fakeJwt({ token_type: "sandbox" }));
+    expect(intent.kind).toBe("invalid");
+  });
+
+  it("rejects every other credential class rather than guessing", () => {
+    // Booting a pool member with the wrong token class is a provisioning bug;
+    // serving anything on a guess would hand the pod a scope it must not have.
+    expect(decidePoolBoot(fakeJwt({ token_type: "embedded_runner" })).kind).toBe("invalid");
+    expect(decidePoolBoot(fakeJwt({ token_type: "workflow_sandbox" })).kind).toBe("invalid");
+    expect(decidePoolBoot(fakeJwt({ sub: "user-1" })).kind).toBe("invalid");
+    expect(decidePoolBoot(null).kind).toBe("invalid");
+    expect(decidePoolBoot("not-a-jwt").kind).toBe("invalid");
+  });
+
+  it("names the offending token_type in the rejection reason", () => {
+    const intent = decidePoolBoot(fakeJwt({ token_type: "embedded_runner" }));
+    expect(intent.kind === "invalid" && intent.reason).toContain("embedded_runner");
+  });
+});
+
+describe("pool member context registry", () => {
+  afterEach(() => {
+    clearPoolMemberContext();
+  });
+
+  it("is undefined outside a pool member (the inert default)", () => {
+    expect(getPoolMemberContext()).toBeUndefined();
+  });
+
+  it("returns the registered context after pool boot", () => {
+    registerPoolMemberContext({ memberId: "pm_1", poolToken: "tok", manager: noopManager });
+
+    const ctx = getPoolMemberContext();
+    expect(ctx?.memberId).toBe("pm_1");
+    expect(ctx?.poolToken).toBe("tok");
+  });
+
+  it("clears for test isolation", () => {
+    registerPoolMemberContext({ memberId: "pm_1", poolToken: "tok", manager: noopManager });
+    clearPoolMemberContext();
+    expect(getPoolMemberContext()).toBeUndefined();
+  });
+});