@stigmer/runner 3.40.1 → 3.41.0

package/src/shared/tool-rounds.ts

@@ -1,18 +1,28 @@
 /**
- * ExecutionConfig.max_tool_rounds → LangGraph recursion_limit resolution.
+ * ExecutionConfig.max_tool_rounds: the round budget, its backstop, and the
+ * signal that the budget ended a turn.
  *
  * Implements the proto contract (agentexecution/v1/spec.proto):
- *   - 0 / unset = unlimited — no recursionLimit is placed on the invoke
- *     config, preserving the run-until-done + loop-detection posture.
+ *   - 0 / unset = unlimited: no round limit and no recursionLimit, preserving
+ *     the run-until-done + loop-detection posture.
  *   - When set, valid range is 10–1000 rounds; out-of-range values are
  *     clamped to the nearest bound with a warning log.
- *   - recursion_limit = rounds × 6: each model-tool round consumes multiple
- *     graph super-steps because every active middleware hook is its own
- *     node; ×6 is the contract's floor estimate.
+ *   - A round is one model response that proposes one or more tool calls,
+ *     followed by their execution; parallel calls are one round.
  *
- * The SAME resolved limit must feed both LangGraph's hard stop (the invoke
- * config) and the ExecutionBudgetMiddleware's wrap-up advisory, so the
- * "~80% of budget" warning and the enforcement point can never disagree.
+ * The budget is COUNTED, not estimated. `middleware/execution-budget.ts`
+ * counts rounds where the model is called and throws
+ * {@link ToolRoundLimitError} before round N+1's model call, so N rounds
+ * run on every middleware stack. The count and the "~80% of budget"
+ * advisory live in that one middleware, so they can never disagree. Until
+ * #1113 the budget was LangGraph's recursion limit at rounds × 6 super-steps,
+ * and because every middleware hook is its own graph node, how many rounds
+ * fitted moved whenever the stack did.
+ *
+ * LangGraph's recursion limit stays only as a backstop
+ * ({@link backstopRecursionLimit}): generous enough never to bind before the
+ * round count on any stack, it halts a graph that loops without calling the
+ * model. Either stop is the same outcome ({@link isToolCallBudgetStop}).
  *
  * The knob and its terminal copy live together (the `cost-guard.ts` shape):
  * when the budget is exhausted the adapter ends its turn `tool_call_limit`
@@ -21,26 +31,39 @@
  * and the conversation continues on the next message.
  */
 
-export const SUPER_STEPS_PER_ROUND = 6;
+import { unwrapModelError } from "./model-error.js";
+
 export const MIN_TOOL_ROUNDS = 10;
 export const MAX_TOOL_ROUNDS = 1000;
 
 /**
- * The advisory-only budget used when max_tool_rounds is unset: high enough
- * to never fire on a healthy run. Deliberately NOT enforced as a hard
- * recursionLimit — unset means unlimited per the proto contract.
+ * Super-steps per round the backstop allows: well above the graph nodes one
+ * round costs on any stack the runner builds (about five today), so the
+ * round count, never the backstop, is what a bounded run meets.
+ */
+export const SUPER_STEPS_BACKSTOP_PER_ROUND = 20;
+
+/**
+ * The advisory-only round budget used when max_tool_rounds is unset: high
+ * enough to never fire on a healthy run. Deliberately NOT enforced — unset
+ * means unlimited per the proto contract.
  */
-export const UNBOUNDED_ADVISORY_RECURSION_LIMIT = 6000;
+export const UNBOUNDED_ADVISORY_TOOL_ROUNDS = MAX_TOOL_ROUNDS;
 
 /**
- * The recursionLimit for the invoke config, or null when the execution is
- * unbounded (max_tool_rounds 0/unset — the pre-existing default posture).
+ * The round budget for a turn, clamped to the valid range, or null when the
+ * execution is unbounded (max_tool_rounds 0/unset — the default posture).
  */
-export function resolveRecursionLimit(maxToolRounds: number | undefined): number | null {
+export function resolveToolRoundLimit(maxToolRounds: number | undefined): number | null {
   if (!maxToolRounds || maxToolRounds <= 0) {
     return null;
   }
-  return clampToolRounds(maxToolRounds) * SUPER_STEPS_PER_ROUND;
+  return clampToolRounds(maxToolRounds);
+}
+
+/** The recursionLimit backstop for a bounded turn's invoke config; see {@link SUPER_STEPS_BACKSTOP_PER_ROUND}. */
+export function backstopRecursionLimit(toolRoundLimit: number): number {
+  return toolRoundLimit * SUPER_STEPS_BACKSTOP_PER_ROUND;
 }
 
 function clampToolRounds(requested: number): number {
@@ -88,13 +111,36 @@ export const TOOL_CALL_LIMIT_USER_COPY =
   "Send another message to continue where the agent left off.";
 
 /**
- * Whether an error thrown out of a LangGraph run is the graph exhausting the
- * recursion limit `resolveRecursionLimit` placed on it — the budget's own
- * signal, not a failure: the adapter ends the turn `tool_call_limit`.
- * Matched by class name and message because the error class is not
- * exported on a stable path across `@langchain/langgraph` versions.
+ * The execution budget's stop: thrown by `middleware/execution-budget.ts` in
+ * place of round N+1's model call, so the graph ends on round N's tool
+ * results with no proposed call left unexecuted.
+ */
+export class ToolRoundLimitError extends Error {
+  constructor(readonly toolRoundLimit: number) {
+    super(`Tool-round limit reached: ${toolRoundLimit} rounds`);
+    this.name = "ToolRoundLimitError";
+  }
+}
+
+/**
+ * Whether an error thrown out of a LangGraph run is the tool-call budget
+ * ending the turn — the budget's own signal, not a failure: the adapter ends
+ * the turn `tool_call_limit`. Two producers, one outcome: the round count's
+ * {@link ToolRoundLimitError}, which reaches the turn wrapped in LangChain's
+ * `MiddlewareError` once per `wrapModelCall` layer (so the cause chain is
+ * walked, as `unwrapModelError` does for a model error), and the backstop's
+ * `GraphRecursionError`.
+ */
+export function isToolCallBudgetStop(err: unknown): boolean {
+  return unwrapModelError(err) instanceof ToolRoundLimitError || isRecursionLimitError(err);
+}
+
+/**
+ * LangGraph exhausting the backstop recursion limit. Matched by class name and
+ * message because the error class is not exported on a stable path across
+ * `@langchain/langgraph` versions.
  */
-export function isGraphRecursionError(err: unknown): boolean {
+function isRecursionLimitError(err: unknown): boolean {
   if (err instanceof Error) {
     return err.constructor.name === "GraphRecursionError" ||
       err.message.includes("GraphRecursionError") ||

package/src/shared/workspace/__tests__/stigmer-link.test.ts

@@ -1,8 +1,15 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtemp, mkdir, rm, writeFile, readFile, lstat, readlink } from "node:fs/promises";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile, readFile, readdir, rename, lstat, readlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+// `rename` passes through to the real one; the cross-filesystem case rejects
+// it once with EXDEV, as a move from a cloud workspace volume to `$HOME` does.
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  return { ...actual, rename: vi.fn(actual.rename) };
+});
+
 import {
   ensureStigmerSymlink,
   removeStigmerSymlink,
@@ -16,7 +23,9 @@ import { LocalWorkspaceBackend } from "../local-backend.js";
  * (approved plan, skills, attachment inputs) readable at `.stigmer/…` by
  * whatever reads from the workspace: the Cursor SDK and shell commands on
  * both harnesses. The lifecycle tests pin the ownership contract (ensure
- * replaces, remove is symlink-only); the convergence tests pin the physics:
+ * moves a real entry out of the workspace and never deletes one, refuses a
+ * `.stigmer` that holds the platform dir, and remove is symlink-only); the
+ * convergence tests pin the physics:
  * content written through the platform-routing LocalWorkspaceBackend is
  * readable at the same `.stigmer/…` path from inside the workspace once the
  * link exists, and not before (the "plan file doesn't exist" bug).
@@ -69,20 +78,108 @@ describe("stigmer-link", () => {
       }
     });
 
-    it("replaces a real .stigmer directory (platform owns the name)", async () => {
-      // The ownership sharp edge, pinned deliberately: a non-symlink
-      // `.stigmer` (left behind by an older runner) must never shadow the
-      // platform mount. See the module header for why this is safe.
-      await mkdir(join(linkPath(), "old"), { recursive: true });
-      await writeFile(join(linkPath(), "old", "stale.txt"), "stale");
+    it("removes an empty real .stigmer directory, then links", async () => {
+      await mkdir(linkPath());
 
       await ensureStigmerSymlink(workspaceDir, platformDir);
 
-      expect((await lstat(linkPath())).isSymbolicLink()).toBe(true);
       expect(await readlink(linkPath())).toBe(platformDir);
     });
   });
 
+  // ── A real `.stigmer` in the link's place (#1123, #1424) ─────────
+
+  describe("ensureStigmerSymlink over a real .stigmer", () => {
+    // The platform dir sits in a session tree here, as `getPlatformDir` lays
+    // it out, so the displaced dir lands beside it and not in the shared tmp.
+    let sessionDir: string;
+    let sessionPlatformDir: string;
+
+    beforeEach(async () => {
+      sessionDir = await mkdtemp(join(tmpdir(), "stigmer-link-session-"));
+      sessionPlatformDir = join(sessionDir, "platform");
+      await mkdir(sessionPlatformDir);
+    });
+
+    afterEach(async () => {
+      await rm(sessionDir, { recursive: true, force: true });
+    });
+
+    /** The one entry under the session's `displaced/` dir. */
+    async function displacedEntry(): Promise<string> {
+      const entries = await readdir(join(sessionDir, "displaced"));
+      expect(entries).toHaveLength(1);
+      expect(entries[0]).toMatch(/^\d{8}T\d{9}Z$/);
+      return join(sessionDir, "displaced", entries[0]);
+    }
+
+    it("moves a non-empty directory to the session's displaced dir, then links", async () => {
+      // An agent write on a turn with no link, or an older runner's leftover:
+      // kept, never deleted.
+      await mkdir(join(linkPath(), "notes"), { recursive: true });
+      await writeFile(join(linkPath(), "notes", "draft.md"), "the agent's draft");
+
+      await ensureStigmerSymlink(workspaceDir, sessionPlatformDir);
+
+      expect(await readlink(linkPath())).toBe(sessionPlatformDir);
+      expect(await readFile(join(await displacedEntry(), "notes", "draft.md"), "utf-8")).toBe("the agent's draft");
+      expect(await readdir(workspaceDir), "nothing else is left in the workspace").toEqual([STIGMER_LOCAL_STATE_DIR]);
+    });
+
+    it("moves a real .stigmer file the same way", async () => {
+      await writeFile(linkPath(), "not a directory");
+
+      await ensureStigmerSymlink(workspaceDir, sessionPlatformDir);
+
+      expect(await readlink(linkPath())).toBe(sessionPlatformDir);
+      expect(await readFile(await displacedEntry(), "utf-8")).toBe("not a directory");
+    });
+
+    it("copies then removes when the session dir is on another filesystem (EXDEV)", async () => {
+      await mkdir(join(linkPath(), "notes"), { recursive: true });
+      await writeFile(join(linkPath(), "notes", "draft.md"), "across mounts");
+      vi.mocked(rename).mockRejectedValueOnce(
+        Object.assign(new Error("EXDEV: cross-device link not permitted"), { code: "EXDEV" }),
+      );
+
+      await ensureStigmerSymlink(workspaceDir, sessionPlatformDir);
+
+      expect(vi.mocked(rename)).toHaveBeenCalled();
+      expect(await readlink(linkPath())).toBe(sessionPlatformDir);
+      expect(await readFile(join(await displacedEntry(), "notes", "draft.md"), "utf-8")).toBe("across mounts");
+    });
+
+    it("refuses a .stigmer that holds the platform dir, touching nothing (a workspace at the home directory)", async () => {
+      // The workspace IS the home: its `.stigmer` is the Stigmer home, where
+      // the CLI's config and every session live, this one's platform dir too.
+      const home = await mkdtemp(join(tmpdir(), "stigmer-link-home-"));
+      try {
+        const stigmerHome = join(home, STIGMER_LOCAL_STATE_DIR);
+        const homePlatformDir = join(stigmerHome, "sessions", "s1", "platform");
+        await mkdir(homePlatformDir, { recursive: true });
+        await writeFile(join(stigmerHome, "config.yaml"), "context: local\n");
+
+        await expect(ensureStigmerSymlink(home, homePlatformDir)).rejects.toThrow(/is the Stigmer home/);
+
+        expect((await lstat(stigmerHome)).isDirectory(), "still the real directory").toBe(true);
+        expect(await readFile(join(stigmerHome, "config.yaml"), "utf-8")).toBe("context: local\n");
+        expect((await lstat(homePlatformDir)).isDirectory()).toBe(true);
+        await expect(lstat(join(stigmerHome, "sessions", "s1", "displaced"))).rejects.toMatchObject({ code: "ENOENT" });
+      } finally {
+        await rm(home, { recursive: true, force: true });
+      }
+    });
+
+    it("refuses when the platform dir is the .stigmer itself", async () => {
+      await mkdir(linkPath());
+      await writeFile(join(linkPath(), "keep.txt"), "keep");
+
+      await expect(ensureStigmerSymlink(workspaceDir, linkPath())).rejects.toThrow(/is the Stigmer home/);
+
+      expect(await readFile(join(linkPath(), "keep.txt"), "utf-8")).toBe("keep");
+    });
+  });
+
   describe("removeStigmerSymlink", () => {
     it("removes the symlink and leaves the platform dir intact", async () => {
       await writeFile(join(platformDir, "keep.txt"), "keep");

package/src/shared/workspace/platform-dir.ts

@@ -10,12 +10,14 @@
  *   a real repo never leaves Stigmer files behind in it (see issue #173); only
  *   a minimal, transient `.cursor/hooks.json` referencing the absolute script
  *   path is written into the workspace itself.
+ * - `displaced/` — a real `.stigmer` entry found in the workspace when the
+ *   platform link takes the name, kept rather than deleted (stigmer-link.ts).
  *
  * This module replaces the duplicated `getPlatformDir` helpers in
  * execute-cursor/skill-resolver.ts and shared/attachment-resolver.ts.
  */
 
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
@@ -110,6 +112,22 @@ export async function ensurePlatformDir(sessionId: string): Promise<string> {
   return dir;
 }
 
+/**
+ * Compute where a real `.stigmer` entry found in a workspace is moved when the
+ * platform link takes the name — `displaced/<stamp>` beside the session's
+ * `platform/` and `hitl/` trees (see stigmer-link.ts). Outside the workspace,
+ * so a real repo is never left holding it (issue #173) and a write-back never
+ * commits it; outside `platform/`, so the agent never reads it back as
+ * platform content.
+ *
+ * Takes the platform dir rather than a session id, unlike its siblings: the
+ * link step knows only the dir it links to, and the session dir is its parent.
+ * Pure function — performs no I/O.
+ */
+export function getDisplacedDir(platformDir: string, stamp: string): string {
+  return join(dirname(platformDir), "displaced", stamp);
+}
+
 /**
  * Compute the HITL directory path for a session — the runner-owned home for the
  * approval gate's hook script, approval-state file, and denial ledger.

package/src/shared/workspace/stigmer-link.ts

@@ -11,10 +11,10 @@
  * `.stigmer/…` paths those agents are prompted with (skill locations,
  * `.stigmer/inputs/…` attachments) actually resolve. The native harness's
  * FILE tools are the exception: their virtual-rooted backend refuses a path
- * whose real location leaves the workspace, so they read the platform dir
- * through a read-only `.stigmer/` route instead
- * (`activities/execute-deep-agent/platform-route.ts`), mounted on exactly
- * the turns this link exists ({@link stigmerSymlinkPointsAt}).
+ * whose real location leaves the workspace, so they reach `.stigmer/` through
+ * a route instead (`activities/execute-deep-agent/platform-route.ts`),
+ * mounted on every turn and exposing the platform dir on exactly the turns
+ * this link exists ({@link stigmerSymlinkPointsAt}).
  *
  * Lifecycle contract (same for both harnesses):
  * - Created per turn, under the workspace turn lock — the link is a
@@ -29,26 +29,35 @@
  * - {@link ensureStigmerSymlink} is idempotent, so multiple populaters may
  *   run in any order within a turn.
  *
- * OWNERSHIP SHARP EDGE: the platform owns the `.stigmer` name inside a
- * workspace. {@link ensureStigmerSymlink} REPLACES a real (non-symlink)
- * `.stigmer` directory it finds there — deliberate, so a directory left
- * behind by an older runner can never shadow the platform mount. (A user's
- * own `.stigmer` content is unreachable anyway: the runner's
- * `LocalWorkspaceBackend` routes every `.stigmer/…` path to the platform
- * dir.) Turn-end removal is the conservative half: it only ever removes a
- * SYMLINK.
+ * OWNERSHIP: the platform owns the `.stigmer` name inside a workspace, but
+ * never deletes what it did not make. A real (non-symlink) `.stigmer` entry
+ * found where the link goes — left by an older runner, or written by a shell
+ * command or a Cursor edit on a turn with no link, where nothing sits between
+ * those tools and the disk (#1123) — is MOVED out of the workspace to the
+ * session's `displaced/` dir (platform-dir.ts `getDisplacedDir`) and named in
+ * a warning; an empty directory is simply removed. Out of the workspace
+ * because a write-back commits everything the tree holds (`git add -A`) and
+ * git excludes only the exact `.stigmer` name. One case is refused outright:
+ * a `.stigmer` that is, or holds, the platform dir itself — a workspace
+ * rooted at the home directory, whose `.stigmer` is the Stigmer home (#1424).
+ * Turn-end removal is the conservative half: it only ever removes a SYMLINK.
  */
 
-import { symlink, readlink, unlink, rm, lstat } from "node:fs/promises";
-import { join } from "node:path";
+import { cp, lstat, mkdir, readdir, readlink, realpath, rename, rm, rmdir, symlink, unlink } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { getDisplacedDir } from "./platform-dir.js";
 
 /** The workspace-visible name of the platform namespace. */
 export const STIGMER_LOCAL_STATE_DIR = ".stigmer";
 
 /**
  * Ensure the workspace `.stigmer` symlink points to the platform dir.
- * Idempotent: an existing correct link is kept; a stale link (or a non-link
- * left behind by an older runner) is replaced.
+ * Idempotent: an existing correct link is kept and a stale link is
+ * re-pointed. A real entry in the link's place is moved to the session's
+ * `displaced/` dir first (an empty directory is removed); a real `.stigmer`
+ * that holds the platform dir is refused with an error naming it, before
+ * anything is touched. See the module header, OWNERSHIP.
  */
 export async function ensureStigmerSymlink(
   workspaceDir: string,
@@ -56,24 +65,85 @@ export async function ensureStigmerSymlink(
 ): Promise<void> {
   const linkPath = join(workspaceDir, STIGMER_LOCAL_STATE_DIR);
 
+  let entry: Stats | undefined;
   try {
-    const existing = await readlink(linkPath);
-    if (existing === platformDir) return;
+    entry = await lstat(linkPath);
+  } catch (err) {
+    if (errnoCode(err) !== "ENOENT") throw err;
+  }
+
+  if (entry?.isSymbolicLink()) {
+    if ((await readlink(linkPath)) === platformDir) return;
     await unlink(linkPath);
-  } catch (err: any) {
-    if (err.code === "ENOENT") {
-      // No existing symlink
-    } else if (err.code === "EINVAL") {
-      // Exists but is not a symlink — remove the directory
-      await rm(linkPath, { recursive: true, force: true });
-    } else {
-      throw err;
-    }
+  } else if (entry !== undefined) {
+    await displaceRealEntry(linkPath, platformDir, entry);
   }
 
   await symlink(platformDir, linkPath, "dir");
 }
 
+/**
+ * Clear a real `.stigmer` entry out of the link's place without losing it:
+ * refuse the Stigmer home, remove an empty directory, move anything else.
+ */
+async function displaceRealEntry(linkPath: string, platformDir: string, entry: Stats): Promise<void> {
+  if (entry.isDirectory()) {
+    await refuseDirHoldingPlatform(linkPath, platformDir);
+    if ((await readdir(linkPath)).length === 0) {
+      await rmdir(linkPath);
+      return;
+    }
+  }
+  const destination = getDisplacedDir(platformDir, displacementStamp(new Date()));
+  await mkdir(dirname(destination), { recursive: true });
+  await moveEntry(linkPath, destination);
+  console.warn(
+    `ensureStigmerSymlink: moved the real ${linkPath} out of the workspace to ${destination}; ` +
+    "the platform owns the .stigmer name, so the link to the session's platform dir takes its place",
+  );
+}
+
+/**
+ * Throw when the real `.stigmer` directory is, or contains, the platform dir:
+ * a workspace rooted at the home directory resolves `.stigmer` to the Stigmer
+ * home, where the platform dir, the CLI's config and every session live.
+ * Compared by real path, so a symlinked or `HOME`-overridden spelling of
+ * either side cannot slip past.
+ */
+async function refuseDirHoldingPlatform(linkPath: string, platformDir: string): Promise<void> {
+  const [realLink, realPlatform] = await Promise.all([realpath(linkPath), realpath(platformDir)]);
+  const fromLink = relative(realLink, realPlatform);
+  const outside = fromLink === ".." || fromLink.startsWith(`..${sep}`) || isAbsolute(fromLink);
+  if (!outside) {
+    throw new Error(
+      `The workspace's ${linkPath} is the Stigmer home (it holds this session's platform dir, ${platformDir}); ` +
+      "use a project directory as the workspace, not the home directory",
+    );
+  }
+}
+
+/** Rename, or copy then remove when the destination is on another filesystem (a cloud workspace volume and `$HOME` are). */
+async function moveEntry(source: string, destination: string): Promise<void> {
+  try {
+    await rename(source, destination);
+  } catch (err) {
+    if (errnoCode(err) !== "EXDEV") throw err;
+    await cp(source, destination, { recursive: true, errorOnExist: true, force: false, verbatimSymlinks: true });
+    await rm(source, { recursive: true, force: true });
+  }
+}
+
+/** A compact UTC stamp with milliseconds (`20260929T101500123Z`): sortable, and free of the colons a path should not carry. */
+function displacementStamp(now: Date): string {
+  return now.toISOString().replace(/[-:.]/g, "");
+}
+
+/** The errno code of a Node filesystem error, or `undefined` for anything else. */
+function errnoCode(err: unknown): string | undefined {
+  if (typeof err !== "object" || err === null || !("code" in err)) return undefined;
+  return typeof err.code === "string" ? err.code : undefined;
+}
+
 /**
  * Whether the workspace's `.stigmer` is, right now, the link
  * {@link ensureStigmerSymlink} makes to `platformDir`. A turn that mounts no
@@ -105,8 +175,8 @@ export async function removeStigmerSymlink(workspaceDir: string): Promise<void>
     if (stat.isSymbolicLink()) {
       await unlink(linkPath);
     }
-  } catch (err: any) {
-    if (err?.code !== "ENOENT") {
+  } catch (err) {
+    if (errnoCode(err) !== "ENOENT") {
       console.warn(
         `removeStigmerSymlink: failed to remove ${linkPath} (non-fatal): ` +
         `${err instanceof Error ? err.message : err}`,

package/src/tools/__tests__/url-guard.test.ts

@@ -131,7 +131,25 @@ describe("validateFetchUrl", () => {
 
   it("rejects unresolvable hostnames", async () => {
     await expect(
-      validateFetchUrl("http://definitely-not-a-real-host.stigmer.invalid/", "strict"),
+      validateFetchUrl("http://definitely-not-a-real-host.stigmer.invalid/", "relaxed"),
     ).rejects.toThrow(/Could not resolve/);
   });
+
+  it("on a strict runner, a name that does not resolve and one that resolves to a refused address read alike and name no address", async () => {
+    const refusals = await Promise.all(
+      ["http://localhost:9999/", "http://definitely-not-a-real-host.stigmer.invalid/"].map((url) =>
+        validateFetchUrl(url, "strict").then(
+          () => {
+            throw new Error(`expected ${url} to be refused`);
+          },
+          (error: unknown) => (error instanceof UrlGuardError ? error.message : String(error)),
+        ),
+      ),
+    );
+    expect(refusals).toEqual([
+      "Refusing to fetch localhost: it does not resolve to a public address.",
+      "Refusing to fetch definitely-not-a-real-host.stigmer.invalid: it does not resolve to a public address.",
+    ]);
+    expect(refusals.join(" ")).not.toMatch(/127\.0\.0\.1|::1|loopback/);
+  });
 });

package/src/tools/url-guard.ts

@@ -12,7 +12,11 @@
  * IPv4-mapped IPv6 is unwrapped, how every resolved address is judged) has
  * one home, `@stigmer/outbound/egress`, shared with the control plane, which
  * dials user-supplied URLs too. This module keeps what is the runner's:
- * deriving the posture from its mode, and the sentence a model reads.
+ * deriving the posture from its mode, and the sentence a model reads. What
+ * that sentence may say is the shared rule too (`refusalWithholdsResolution`):
+ * on a strict runner a name that does not resolve and one that resolves to
+ * a refused address read alike and name no address, because the runner
+ * resolves through a network its caller does not own.
  *
  * Posture is mode-aware because locality differs, not trust:
  *
@@ -41,6 +45,7 @@ import {
   checkEgress,
   egressPolicyForPosture,
   nodeLookup,
+  refusalWithholdsResolution,
   blockedReason as sharedBlockedReason,
   type EgressPosture,
 } from "@stigmer/outbound/egress";
@@ -91,6 +96,9 @@ export async function validateFetchUrl(
   if (check.ok) return check.url;
 
   const refusal = check.refusal;
+  if (refusalWithholdsResolution(refusal) && (refusal.kind === "unresolvable" || refusal.kind === "blocked")) {
+    throw new UrlGuardError(`Refusing to fetch ${refusal.hostname}: it does not resolve to a public address.`);
+  }
   switch (refusal.kind) {
     case "invalid-url":
       throw new UrlGuardError(`Invalid URL: ${refusal.url}`);

package/src/worker.ts

@@ -34,7 +34,17 @@ export interface StartWorkerOptions {
   payloadCodecs?: PayloadCodec[];
 }
 
-export async function startWorker(opts: StartWorkerOptions): Promise<Worker> {
+/**
+ * The worker and the connection it polls on. The caller owns both: it runs
+ * and shuts down the worker, then closes the connection once `run()` has
+ * resolved (the SDK refuses to close a connection a worker still holds).
+ */
+export interface StartedWorker {
+  readonly worker: Worker;
+  readonly connection: NativeConnection;
+}
+
+export async function startWorker(opts: StartWorkerOptions): Promise<StartedWorker> {
   const { config, activities, payloadCodecs } = opts;
 
   const connection = await NativeConnection.connect({
@@ -109,5 +119,5 @@ export async function startWorker(opts: StartWorkerOptions): Promise<Worker> {
     },
   });
 
-  return worker;
+  return { worker, connection };
 }

package/src/workflow-engine/__tests__/golden-execution.test.ts

@@ -164,7 +164,8 @@ describe("Golden Execution — Tier 1c: External Calls", () => {
   it("#03 foreach-loop — for loop with HTTP call per item", async () => {
     const model = loadWorkflowFromYaml(loadGolden("03-foreach-loop.yaml"));
     const state = createState();
-    state.data = { items: ["item1", "item2", "item3"] };
+    // The workflow's input, where the engine puts it (engine-core.ts: state.input = workflow_input).
+    state.input = { items: ["item1", "item2", "item3"] };
 
     const mockCallHttp = vi.fn(async () => fakeHttpResponse());
     const ctx = makeCtx({ callHttp: mockCallHttp });

package/src/workflow-engine/__tests__/loader.test.ts

@@ -391,7 +391,7 @@ do:
       expect(forEntry).toBeDefined();
       if (forEntry?.task.kind === "for") {
         expect(forEntry.task.for.each).toBe("item");
-        expect(forEntry.task.for.in).toBe("${ $data.items }");
+        expect(forEntry.task.for.in).toBe("${ $input.items }");
         expect(forEntry.task.do.length).toBeGreaterThan(0);
       }
     });