@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/src/sandbox-token-renewal.ts

@@ -0,0 +1,211 @@
+/**
+ * Self-renewal of a cloud sandbox's control-plane credential (STIGMER_TOKEN).
+ *
+ * A sandbox token is minted with a fixed TTL, but the sandbox it serves has no
+ * fixed lifetime: an active conversation extends a session sandbox
+ * indefinitely, past any TTL chosen at provisioning. Before this module, the
+ * only refresh path was the control plane's Secret-rewrite + pod restart —
+ * which the 2026-08-05 incident showed both sacrifices the turn that trips it
+ * (the old pod picks up the work holding the dead env token) and wipes an
+ * ephemeral sandbox's workspace. Renewal decouples credential lifetime from
+ * sandbox lifetime: the runner re-mints in-process before expiry via the
+ * getRunnerScopedToken `renewal` arm, and the server bounds renewability by
+ * the live sandbox record (a reaped sandbox's credential dies with it).
+ *
+ * Relationship to {@link createRunnerTokenCoordinator}
+ * (runner-token-coordinator.ts): the coordinator owns the PROXY credential
+ * (x-stigmer-auth) and re-mints it using the control-plane token; this
+ * module keeps that control-plane token itself fresh, so the two form one
+ * chain with no expiring root. They stay separate modules because their
+ * hosts differ — every proxy-mode runner has a coordinator, but only
+ * in-cluster sandbox runners (static cloud sandboxes and pool members) hold
+ * a renewable credential; the desktop's control-plane token is the user's
+ * own Auth0 token, refreshed by the host app.
+ *
+ * The loop re-reads the CURRENT token every cycle rather than binding to
+ * the boot credential, because the credential's class can change under it:
+ * a pool member boots with a non-renewable pool_sandbox token and swaps to
+ * a renewable session token at claim time (attach-session.ts). A
+ * non-renewable token parks the loop on a slow recheck instead of stopping
+ * it, so the swap is picked up without any coupling to the claim path.
+ */
+
+/**
+ * Renew once the token has lived this fraction of its issued lifetime
+ * (anchored on iat/exp, the coordinator's 0.8 convention). Anchoring on the
+ * ISSUED lifetime matters: a fraction of the *remaining* lifetime re-arms at
+ * 80% of an ever-shrinking remainder and never reaches the renewal point.
+ */
+const RENEW_AT_LIFETIME_FRACTION = 0.8;
+
+/**
+ * Fallback safety margin before expiry for a token without an iat claim:
+ * renew this early, leaving room for two retry cycles.
+ */
+const FALLBACK_RENEW_MARGIN_MS = 10 * 60_000;
+
+/** Retry delay after a failed renewal — short enough to recover well before expiry. */
+const RETRY_DELAY_MS = 60_000;
+
+/** Recheck cadence while the current token is not a renewable class (pre-claim pool member). */
+const RECHECK_DELAY_MS = 60_000;
+
+/** Floor for any scheduled delay so a malformed expiry cannot spin a hot loop. */
+const MIN_DELAY_MS = 5_000;
+
+/** The token_type claims the renewal arm accepts (mirrors the server's gate). */
+const RENEWABLE_TOKEN_TYPES = new Set(["sandbox"]);
+
+export interface SandboxTokenRenewalOptions {
+  /** Reads the credential currently in effect (re-read every cycle; see module doc). */
+  readonly getToken: () => string | null | undefined;
+  /**
+   * Calls the getRunnerScopedToken `renewal` arm authenticated with
+   * {@code currentToken}. Returns undefined when the server minted nothing;
+   * the loop retries rather than crashing the runner.
+   */
+  readonly renew: (currentToken: string) => Promise<
+    { token: string; expiresInSeconds?: number } | undefined
+  >;
+  /** Applies a freshly minted credential to every sink the host wires (ref, env, interceptors). */
+  readonly applyToken: (token: string) => void;
+  /** Optional structured logger; defaults to console. */
+  readonly log?: Pick<typeof console, "log" | "warn">;
+}
+
+export interface SandboxTokenRenewal {
+  /** Stop the renewal timer. Idempotent. */
+  stop(): void;
+}
+
+/**
+ * Whether a token's decoded claims mark it as renewable through the
+ * `renewal` arm. Exported so a static-mode host can decide not to start
+ * the loop at all for a credential whose class can never change.
+ */
+export function isRenewableSandboxToken(token: string | null | undefined): boolean {
+  const claims = decodeClaims(token);
+  return claims !== null
+    && RENEWABLE_TOKEN_TYPES.has(claims.tokenType ?? "")
+    && claims.expMs !== null;
+}
+
+/**
+ * Start the renewal loop. The first cycle runs immediately (it only reads
+ * the token and schedules; no network call unless the credential is already
+ * past its renewal point).
+ */
+export function startSandboxTokenRenewal(
+  options: SandboxTokenRenewalOptions,
+): SandboxTokenRenewal {
+  const log = options.log ?? console;
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const schedule = (delayMs: number): void => {
+    if (stopped) {
+      return;
+    }
+    timer = setTimeout(() => {
+      void cycle();
+    }, Math.max(MIN_DELAY_MS, delayMs));
+    // Never keep the process alive solely for a token renewal.
+    timer.unref?.();
+  };
+
+  const cycle = async (): Promise<void> => {
+    if (stopped) {
+      return;
+    }
+    const token = options.getToken() ?? null;
+    const claims = decodeClaims(token);
+
+    if (token === null || claims === null
+        || !RENEWABLE_TOKEN_TYPES.has(claims.tokenType ?? "")) {
+      // Not (yet) a renewable credential — a pre-claim pool member, or a
+      // credential class this loop does not own. Park and look again.
+      schedule(RECHECK_DELAY_MS);
+      return;
+    }
+
+    if (claims.expMs === null) {
+      // A renewable-class token without an expiry is a mint-side anomaly;
+      // renewing "before expiry" is undefined, so park rather than spin.
+      log.warn("[sandbox-token-renewal] Credential carries no exp claim; parking");
+      schedule(RECHECK_DELAY_MS);
+      return;
+    }
+
+    const renewAtMs = claims.iatMs !== null
+      ? claims.iatMs + (claims.expMs - claims.iatMs) * RENEW_AT_LIFETIME_FRACTION
+      : claims.expMs - FALLBACK_RENEW_MARGIN_MS;
+    const delayMs = renewAtMs - Date.now();
+    if (delayMs > MIN_DELAY_MS) {
+      schedule(delayMs);
+      return;
+    }
+
+    // At or past the renewal point (possibly past expiry after a long pod
+    // pause — the attempt is still correct: the server decides).
+    try {
+      const renewed = await options.renew(token);
+      if (renewed) {
+        options.applyToken(renewed.token);
+        log.log("[sandbox-token-renewal] Sandbox credential renewed");
+        // Recompute from the fresh token (its own exp is authoritative).
+        schedule(MIN_DELAY_MS);
+      } else {
+        log.warn("[sandbox-token-renewal] Server minted no renewal; will retry");
+        schedule(RETRY_DELAY_MS);
+      }
+    } catch (err) {
+      log.warn(
+        "[sandbox-token-renewal] Renewal failed; will retry: " +
+        `${err instanceof Error ? err.message : err}`,
+      );
+      schedule(RETRY_DELAY_MS);
+    }
+  };
+
+  void cycle();
+
+  return {
+    stop(): void {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+/**
+ * Decode the claims this module reads (token_type, iat, exp) from an
+ * unverified JWT. Decode-only on purpose: this is the runner's OWN
+ * credential, minted by the server it will present it back to —
+ * verification happens there.
+ */
+function decodeClaims(
+  token: string | null | undefined,
+): { tokenType: string | undefined; iatMs: number | null; expMs: number | null } | null {
+  if (!token) {
+    return null;
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return null;
+  }
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1], "base64url").toString("utf-8"),
+    ) as { token_type?: string; iat?: number; exp?: number };
+    return {
+      tokenType: payload.token_type,
+      iatMs: typeof payload.iat === "number" ? payload.iat * 1000 : null,
+      expMs: typeof payload.exp === "number" ? payload.exp * 1000 : null,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/shared/__tests__/activity-input.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import {
+  normalizeActivityInput,
+  type ExecuteActivityInput,
+} from "../activity-input.js";
+
+describe("normalizeActivityInput — dual-shape activity boundary", () => {
+  it("reads the new typed object (snake_case wire keys from Go/Java)", () => {
+    const wire: ExecuteActivityInput = {
+      execution_id: "exec-1",
+      thread_id: "thread-1",
+      invoker_identity_account_id: "acct-1",
+      turn_seq: 2,
+    };
+    expect(normalizeActivityInput(wire)).toEqual({
+      executionId: "exec-1",
+      threadId: "thread-1",
+      turnSeq: 2,
+    });
+  });
+
+  it("reads the legacy positional args (old Go control plane: 2 args)", () => {
+    expect(normalizeActivityInput("exec-2", "thread-2")).toEqual({
+      executionId: "exec-2",
+      threadId: "thread-2",
+      turnSeq: 0,
+    });
+  });
+
+  it("ignores a legacy 3rd positional arg (old Java sent invokerId as arg2)", () => {
+    // The runner only declares (arg0, arg1); a 3rd positional arg is dropped by
+    // JS, so the old Java (executionId, threadId, invokerId) call still works.
+    expect(normalizeActivityInput("exec-3", "thread-3")).toEqual({
+      executionId: "exec-3",
+      threadId: "thread-3",
+      turnSeq: 0,
+    });
+  });
+
+  it("treats an empty thread_id (first run / new harness state) as empty", () => {
+    expect(
+      normalizeActivityInput({
+        execution_id: "exec-4",
+        thread_id: "",
+        invoker_identity_account_id: "acct-4",
+      }),
+    ).toEqual({ executionId: "exec-4", threadId: "", turnSeq: 0 });
+
+    expect(normalizeActivityInput("exec-5")).toEqual({
+      executionId: "exec-5",
+      threadId: "",
+      turnSeq: 0,
+    });
+  });
+
+  it("defaults turn_seq to 0 when the object omits it (first turn / older control plane)", () => {
+    expect(
+      normalizeActivityInput({
+        execution_id: "exec-7",
+        thread_id: "thread-7",
+        invoker_identity_account_id: "acct-7",
+      }),
+    ).toEqual({ executionId: "exec-7", threadId: "thread-7", turnSeq: 0 });
+  });
+
+  it("deserializes the exact JSON shape the control planes emit", () => {
+    // Mirrors the bytes the Go struct / Java record serialize to (snake_case),
+    // including the additive turn_seq the cutover threads through.
+    const fromWire = JSON.parse(
+      '{"execution_id":"exec-6","thread_id":"thread-6","invoker_identity_account_id":"acct-6","turn_seq":3}',
+    ) as ExecuteActivityInput;
+    expect(normalizeActivityInput(fromWire)).toEqual({
+      executionId: "exec-6",
+      threadId: "thread-6",
+      turnSeq: 3,
+    });
+  });
+});

package/src/shared/__tests__/advisory-anthropic-payload.test.ts

@@ -0,0 +1,194 @@
+/**
+ * The request each advising middleware produces, sent through the REAL
+ * @langchain/anthropic conversion (stigmer/stigmer#1354).
+ *
+ * The middleware suites check the message a middleware adds; only the
+ * provider's own conversion can say whether a request carrying it is one
+ * Anthropic accepts. That conversion is what failed every native run that
+ * reached an advisory: a mid-conversation system message, which
+ * `_convertMessagesToAnthropicPayload` refuses. The converter is not on the
+ * package's public exports, so these tests reach it the way production does:
+ * a `ChatAnthropic` whose client is a fake that records the payload
+ * `messages.create` is handed. No request leaves the process.
+ *
+ * Each arm drives one middleware until it fires, takes the request it hands
+ * its handler on the next call, prepends the system prompt as the agent node
+ * does (`[systemMessage, ...request.messages]`), and asserts the payload:
+ * no system role among the messages, every `tool_use` answered by the user
+ * turn right after it, and the advisory as a user turn after that, which the
+ * API combines with the tool results into one turn. A last case pins that the
+ * old shape is exactly what the client refuses.
+ *
+ * One request has no tool result before its advisory: a sub-agent invoked
+ * after the run crossed the cost line is advised on its first call, right
+ * after the task message (stigmer/stigmer#1679). Its arm asserts the two user
+ * turns the API combines, the task's and the advisory's.
+ */
+
+import { describe, expect, it } from "vitest";
+import { ChatAnthropic } from "@langchain/anthropic";
+import { AIMessage, HumanMessage, SystemMessage, ToolMessage, type BaseMessage } from "@langchain/core/messages";
+
+import { createExecutionBudgetMiddleware } from "../../middleware/execution-budget.js";
+import { createCostAdvisoryMiddleware } from "../../middleware/cost-advisory.js";
+import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
+import { ADVISORY_LEAD_IN } from "../../middleware/advisory-message.js";
+import type { ModelCallRequest, StigmerMiddleware } from "../../middleware/types.js";
+
+interface AnthropicPayload {
+  readonly system?: unknown;
+  readonly messages: ReadonlyArray<{ role: string; content: unknown }>;
+}
+
+/** A ChatAnthropic whose client records every payload and answers with a one-line message. */
+function capturingModel(): { model: ChatAnthropic; payloads: AnthropicPayload[] } {
+  const payloads: AnthropicPayload[] = [];
+  const model = new ChatAnthropic({
+    model: "claude-haiku-4-5-20251001",
+    apiKey: "offline",
+    maxRetries: 0,
+    createClient: () =>
+      ({
+        messages: {
+          create: async (payload: AnthropicPayload) => {
+            payloads.push(payload);
+            return {
+              id: "msg_offline",
+              type: "message",
+              role: "assistant",
+              model: "claude-haiku-4-5-20251001",
+              content: [{ type: "text", text: "ok" }],
+              stop_reason: "end_turn",
+              stop_sequence: null,
+              usage: { input_tokens: 1, output_tokens: 1 },
+            };
+          },
+        },
+      }) as never,
+  });
+  return { model, payloads };
+}
+
+/** The history every model call in these arms sees: a user turn, one tool call and its result. */
+const HISTORY: BaseMessage[] = [
+  new HumanMessage("Read the file."),
+  new AIMessage({ content: "", tool_calls: [{ id: "toolu_1", name: "read_file", args: { file_path: "/a.md" }, type: "tool_call" }] }),
+  new ToolMessage({ content: "contents", tool_call_id: "toolu_1" }),
+];
+
+const REQUEST: ModelCallRequest = { model: {}, messages: HISTORY, state: { messages: HISTORY }, runtime: {} };
+
+function toolResponse(args: Record<string, unknown>, usage = { input_tokens: 10, output_tokens: 5, total_tokens: 15 }): AIMessage {
+  return new AIMessage({
+    content: "",
+    tool_calls: [{ id: "toolu_next", name: "read_file", args, type: "tool_call" }],
+    usage_metadata: usage,
+  });
+}
+
+/**
+ * Calls `mw` with `respond` until a call's request carries more than the
+ * history, and returns that request: the one the middleware advised.
+ */
+async function firstAdvisedRequest(mw: StigmerMiddleware, respond: (call: number) => AIMessage, maxCalls = 40): Promise<ModelCallRequest> {
+  for (let call = 0; call < maxCalls; call++) {
+    let seen: ModelCallRequest | undefined;
+    await mw.wrapModelCall!(REQUEST, async (request) => {
+      seen = request;
+      return respond(call);
+    });
+    if (seen && seen.messages.length > HISTORY.length) return seen;
+  }
+  throw new Error(`${mw.name} advised no request within ${maxCalls} calls`);
+}
+
+async function payloadFor(request: ModelCallRequest): Promise<AnthropicPayload> {
+  const { model, payloads } = capturingModel();
+  await model.invoke([new SystemMessage("You are a test agent."), ...(request.messages as BaseMessage[])]);
+  expect(payloads).toHaveLength(1);
+  return payloads[0];
+}
+
+function assertAdvisedPayload(payload: AnthropicPayload): void {
+  expect(payload.system, "the system prompt rides the request's own field").toBeDefined();
+  expect(payload.messages.map((m) => m.role), "no system role among the messages").toEqual(["user", "assistant", "user", "user"]);
+
+  const toolUse = payload.messages[1].content as Array<{ type: string; id?: string }>;
+  expect(toolUse.map((b) => b.type)).toEqual(["tool_use"]);
+  const results = payload.messages[2].content as Array<{ type: string; tool_use_id?: string }>;
+  expect(results.map((b) => b.type), "the tool_use is answered by the turn right after it").toEqual(["tool_result"]);
+  expect(results[0].tool_use_id).toBe(toolUse[0].id);
+
+  const advisory = payload.messages[3].content;
+  const text = typeof advisory === "string" ? advisory : (advisory as Array<{ text?: string }>).map((b) => b.text ?? "").join("");
+  expect(text.startsWith(ADVISORY_LEAD_IN), "the advisory follows the results as a user turn").toBe(true);
+}
+
+describe("an advised request through the real @langchain/anthropic conversion", () => {
+  it("the tool-round budget's advisory at 80% of max_tool_rounds", async () => {
+    const mw = createExecutionBudgetMiddleware({ maxToolRounds: 10, warningPct: 80 });
+    const request = await firstAdvisedRequest(mw, (call) => toolResponse({ file_path: `/f${call}.md` }));
+    assertAdvisedPayload(await payloadFor(request));
+  });
+
+  it("the sub-agent stack's periodic advisory", async () => {
+    const mw = createExecutionBudgetMiddleware({ warningInterval: 30, maxWarnings: 4 });
+    const request = await firstAdvisedRequest(mw, (call) => toolResponse({ file_path: `/f${call}.md` }));
+    assertAdvisedPayload(await payloadFor(request));
+  });
+
+  it("the cost advisory once the estimate crosses 80% of max_cost_usd", async () => {
+    const mw = createCostAdvisoryMiddleware({
+      maxCostUsd: 1,
+      inputPricePerMillion: 100_000,
+      outputPricePerMillion: 100_000,
+      cacheReadPricePerMillion: 0,
+      warningPct: 80,
+    });
+    const request = await firstAdvisedRequest(mw, (call) => toolResponse({ file_path: `/f${call}.md` }));
+    assertAdvisedPayload(await payloadFor(request));
+  });
+
+  it("the cost advisory on a sub-agent's first call after the run crossed: right after the task message", async () => {
+    const mw = createCostAdvisoryMiddleware({
+      maxCostUsd: 1,
+      inputPricePerMillion: 100_000,
+      outputPricePerMillion: 100_000,
+      cacheReadPricePerMillion: 0,
+      warningPct: 80,
+    });
+    // The parent's call crosses the line; the sub-agent is invoked after it.
+    await mw.wrapModelCall!(REQUEST, async () => toolResponse({ file_path: "/a.md" }));
+    const view = mw.forSubAgent();
+    view.beforeAgent!({}, {});
+    const task: BaseMessage[] = [new HumanMessage("Summarize the file.")];
+    let first: ModelCallRequest | undefined;
+    await view.wrapModelCall!({ model: {}, messages: task, state: { messages: task }, runtime: {} }, async (request) => {
+      first = request;
+      return new AIMessage({ content: "ok" });
+    });
+    expect(first!.messages, "the first call carries the task and the advisory").toHaveLength(task.length + 1);
+
+    const payload = await payloadFor(first!);
+    expect(payload.system, "the system prompt rides the request's own field").toBeDefined();
+    expect(payload.messages.map((m) => m.role), "two user turns, which the API combines into one").toEqual(["user", "user"]);
+    const texts = payload.messages.map((m) =>
+      typeof m.content === "string" ? m.content : (m.content as Array<{ text?: string }>).map((b) => b.text ?? "").join(""),
+    );
+    expect(texts[0]).toBe("Summarize the file.");
+    expect(texts[1].startsWith(ADVISORY_LEAD_IN), "the advisory follows the task message").toBe(true);
+  });
+
+  it("loop detection's warning after seven identical calls", async () => {
+    const mw = createLoopDetectionMiddleware();
+    const request = await firstAdvisedRequest(mw, () => toolResponse({ file_path: "/same.md" }));
+    assertAdvisedPayload(await payloadFor(request));
+  });
+
+  it("refuses the shape these advisories had: a system message after the first", async () => {
+    const { model } = capturingModel();
+    await expect(model.invoke([new SystemMessage("sys"), ...HISTORY, new SystemMessage("warning")])).rejects.toThrow(
+      /System messages are only permitted as the first passed message/,
+    );
+  });
+});

package/src/shared/__tests__/agent-handover.test.ts

@@ -0,0 +1,186 @@
+/**
+ * The one-time handover of the agent's files (`shared/agent-handover.ts`),
+ * on a real tree, with the ownership change recorded (a test cannot give
+ * files to another user).
+ *
+ * Pinned:
+ *  - a session's state moves from the runner's `~/.stigmer` into the
+ *    agent's, contents intact, and a name the agent's home already holds is
+ *    left where it is;
+ *  - every entry of the agent's state and of the workspace root is handed
+ *    over, a link changed itself and its target never reached;
+ *  - a workspace root inside the runner's state has the directories above
+ *    it made traversable but not listable;
+ *  - nothing in the agent's home is the agent's while the walk works in it:
+ *    the home is taken back before anything is written in it, and every
+ *    directory is handed over after its contents;
+ *  - an agent home that would hold the runner's own files (its home's
+ *    ancestor, or a place inside its state) is refused before anything moves;
+ *  - the marker makes it run once: a later boot only hands over the agent's
+ *    home and the workspace root themselves;
+ *  - a move across filesystems copies, then removes; a workspace root
+ *    outside the runner's state has no directories closed above it, and
+ *    an agent's home without state yet is left as it is.
+ */
+
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+
+// renameSync passes through, but a test can make it cross filesystems once.
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return { ...actual, renameSync: vi.fn(actual.renameSync) };
+});
+
+import { HANDOVER_MARKER, handOverToAgent } from "../agent-handover.js";
+
+const identity = { name: "stigmer-agent", uid: 10001, gid: 10001, home: "" };
+
+function tree() {
+  const base = mkdtempSync(join(tmpdir(), "agent-handover-"));
+  const runnerHome = join(base, "data");
+  const agentHome = join(runnerHome, "agent");
+  const workspaceRoot = join(runnerHome, ".stigmer", "data", "workspace");
+  mkdirSync(join(runnerHome, ".stigmer", "sessions", "ses-1", "platform"), { recursive: true });
+  writeFileSync(join(runnerHome, ".stigmer", "sessions", "ses-1", "checkpoints.db"), "checkpoints");
+  mkdirSync(join(runnerHome, ".stigmer", "workspace-locks"), { recursive: true });
+  mkdirSync(join(workspaceRoot, "sessions", "ses-1"), { recursive: true });
+  writeFileSync(join(workspaceRoot, "sessions", "ses-1", "README.md"), "work");
+  const outside = join(base, "outside.txt");
+  writeFileSync(outside, "not the agent's");
+  symlinkSync(outside, join(workspaceRoot, "sessions", "ses-1", "link"));
+  return { runnerHome, agentHome, workspaceRoot, outside, who: { ...identity, home: agentHome } };
+}
+
+describe("handing the agent's files to the agent user", () => {
+  it("moves the session state, hands every entry over without following links, and closes the runner's directories above the workspace", () => {
+    const t = tree();
+    const chowned: string[] = [];
+    const result = handOverToAgent(t.who, { runnerHome: t.runnerHome, workspaceRoot: t.workspaceRoot }, { chown: (path) => void chowned.push(path) });
+
+    expect(result).toEqual({ moved: ["sessions"], firstTime: true });
+    expect(readFileSync(join(t.agentHome, ".stigmer", "sessions", "ses-1", "checkpoints.db"), "utf8")).toBe("checkpoints");
+    expect(existsSync(join(t.runnerHome, ".stigmer", "sessions"))).toBe(false);
+    expect(existsSync(join(t.runnerHome, ".stigmer", "workspace-locks")), "the runner's own state stays").toBe(true);
+
+    expect(chowned).toContain(join(t.agentHome, ".stigmer", "sessions", "ses-1", "checkpoints.db"));
+    expect(chowned).toContain(join(t.workspaceRoot, "sessions", "ses-1", "README.md"));
+    expect(chowned).toContain(join(t.workspaceRoot, "sessions", "ses-1", "link"));
+    expect(chowned, "a link's target is never reached").not.toContain(t.outside);
+    expect(chowned.filter((path) => path.includes("workspace-locks"))).toEqual([]);
+
+    expect(statSync(join(t.runnerHome, ".stigmer")).mode & 0o777).toBe(0o711);
+    expect(statSync(join(t.runnerHome, ".stigmer", "data")).mode & 0o777).toBe(0o711);
+    expect(existsSync(join(t.runnerHome, ".stigmer", HANDOVER_MARKER))).toBe(true);
+  });
+
+  it("runs once: a later boot hands over only the agent's home and the workspace root themselves", () => {
+    const t = tree();
+    handOverToAgent(t.who, { runnerHome: t.runnerHome, workspaceRoot: t.workspaceRoot }, { chown: () => {} });
+    const chowned: string[] = [];
+    expect(handOverToAgent(t.who, { runnerHome: t.runnerHome, workspaceRoot: t.workspaceRoot }, { chown: (path) => void chowned.push(path) })).toEqual({ moved: [], firstTime: false });
+    expect(chowned).toEqual([t.agentHome, t.workspaceRoot]);
+  });
+
+  it("takes the agent's home back before writing in it, and hands each directory over after its contents", () => {
+    const t = tree();
+    mkdirSync(t.agentHome, { recursive: true });
+    const calls: string[] = [];
+    handOverToAgent(t.who, { runnerHome: t.runnerHome, workspaceRoot: t.workspaceRoot }, { chown: (path, uid) => void calls.push(`${uid} ${path}`) });
+    const state = join(t.agentHome, ".stigmer");
+    expect(calls[0], "the home is root's before the state moves in").toBe(`0 ${t.agentHome}`);
+    expect(calls.indexOf(`10001 ${join(state, "sessions", "ses-1", "checkpoints.db")}`)).toBeLessThan(calls.indexOf(`10001 ${state}`));
+    expect(calls.indexOf(`10001 ${state}`)).toBeLessThan(calls.indexOf(`10001 ${t.agentHome}`));
+    for (const dir of [t.agentHome, state, t.workspaceRoot]) {
+      expect(calls.indexOf(`0 ${dir}`), `${dir} is listed as root's`).toBeLessThan(calls.indexOf(`10001 ${dir}`));
+    }
+  });
+
+  it("leaves a name the agent's home already holds where it is", () => {
+    const t = tree();
+    mkdirSync(join(t.agentHome, ".stigmer", "sessions"), { recursive: true });
+    const result = handOverToAgent(t.who, { runnerHome: t.runnerHome, workspaceRoot: t.workspaceRoot }, { chown: () => {} });
+    expect(result.moved).toEqual([]);
+    expect(existsSync(join(t.runnerHome, ".stigmer", "sessions", "ses-1", "checkpoints.db"))).toBe(true);
+  });
+});
+
+describe("handing over across filesystems and outside the runner's state", () => {
+  it("copies the session state, then removes it, when the agent's home is on another filesystem", () => {
+    const t = tree();
+    vi.mocked(renameSync).mockImplementationOnce(() => {
+      throw Object.assign(new Error("EXDEV: cross-device link not permitted"), { code: "EXDEV" });
+    });
+    expect(handOverToAgent(t.who, { runnerHome: t.runnerHome, workspaceRoot: t.workspaceRoot }, { chown: () => {} }).moved).toEqual(["sessions"]);
+    expect(readFileSync(join(t.agentHome, ".stigmer", "sessions", "ses-1", "checkpoints.db"), "utf8")).toBe("checkpoints");
+    expect(existsSync(join(t.runnerHome, ".stigmer", "sessions"))).toBe(false);
+  });
+
+  it("refuses a move that fails for another reason", () => {
+    const t = tree();
+    vi.mocked(renameSync).mockImplementationOnce(() => {
+      throw Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" });
+    });
+    expect(() => handOverToAgent(t.who, { runnerHome: t.runnerHome, workspaceRoot: t.workspaceRoot }, { chown: () => {} })).toThrow("EACCES");
+  });
+
+  it("closes no directory above a workspace root outside the runner's state", () => {
+    const base = mkdtempSync(join(tmpdir(), "agent-handover-driver-"));
+    const runnerHome = join(base, "root");
+    const workspaceRoot = join(base, "workspace");
+    mkdirSync(join(runnerHome, ".stigmer"), { recursive: true });
+    const chowned: string[] = [];
+    const who = { ...identity, home: join(base, "home", "stigmer-agent") };
+    expect(handOverToAgent(who, { runnerHome, workspaceRoot }, { chown: (path) => void chowned.push(path) })).toEqual({ moved: [], firstTime: true });
+    expect(chowned).toContain(workspaceRoot);
+    expect(statSync(join(runnerHome, ".stigmer")).mode & 0o777, "nothing above the workspace is the runner's").not.toBe(0o711);
+  });
+
+  it("refuses the default workspace under a runner home the agent cannot pass, naming WORKSPACE_ROOT_DIR", () => {
+    // A driver's HOME is /root, 0700: the default ~/.stigmer/workspaces/runner
+    // under it would be a workspace the agent cannot open.
+    const base = mkdtempSync(join(tmpdir(), "agent-handover-closed-"));
+    const runnerHome = join(base, "root");
+    const workspaceRoot = join(runnerHome, ".stigmer", "workspaces", "runner");
+    mkdirSync(runnerHome, { mode: 0o700 });
+    chmodSync(runnerHome, 0o700);
+    const who = { ...identity, home: join(base, "home", "stigmer-agent") };
+    expect(() => handOverToAgent(who, { runnerHome, workspaceRoot }, { chown: () => {} })).toThrow(
+      `the workspace root ${workspaceRoot} is out of the agent's reach: ${runnerHome} (mode 0700) is closed to it; set WORKSPACE_ROOT_DIR to a directory outside the runner's home`,
+    );
+    chmodSync(runnerHome, 0o755);
+    expect(handOverToAgent(who, { runnerHome, workspaceRoot }, { chown: () => {} }).firstTime).toBe(true);
+  });
+
+  it("refuses an agent home that would hold the runner's own files, above its home or inside its state", () => {
+    const base = mkdtempSync(join(tmpdir(), "agent-handover-enclosing-"));
+    const runnerHome = join(base, "data");
+    const refusal = `would hold the runner's own files (${join(runnerHome, ".stigmer")}); set STIGMER_AGENT_HOME to a directory of the agent's own, outside the runner's state`;
+    for (const home of ["/", base, join(runnerHome, ".stigmer", "agent"), join(runnerHome, ".stigmer", "..agent")]) {
+      expect(() => handOverToAgent({ ...identity, home }, { runnerHome, workspaceRoot: join(base, "workspace") }, { chown: () => {} }), home).toThrow(refusal);
+    }
+    expect(existsSync(join(base, "workspace")), "refused before anything is made").toBe(false);
+  });
+
+  it("refuses an agent home that is the runner's own", () => {
+    const base = mkdtempSync(join(tmpdir(), "agent-handover-shared-"));
+    expect(() => handOverToAgent({ ...identity, home: base }, { runnerHome: base, workspaceRoot: join(base, "workspace") }, { chown: () => {} })).toThrow(
+      "the agent's home (" + base + ") is the runner's own; set STIGMER_AGENT_HOME to a directory of the agent's own",
+    );
+  });
+
+  it("walks nothing on a sandbox's wake: no state to move, and a workspace that is the agent's already", () => {
+    // The runner's home does not persist in a sandbox, so its marker is gone
+    // at every wake; the workspace claim, the agent's since the first boot,
+    // is what says the handover ran.
+    const base = mkdtempSync(join(tmpdir(), "agent-handover-wake-"));
+    const workspaceRoot = join(base, "workspace");
+    mkdirSync(join(workspaceRoot, "node_modules", "deep"), { recursive: true });
+    const owner = { ...identity, uid: process.getuid!(), gid: process.getgid!(), home: join(base, "agent") };
+    const chowned: string[] = [];
+    expect(handOverToAgent(owner, { runnerHome: join(base, "root"), workspaceRoot }, { chown: (path) => void chowned.push(path) })).toEqual({ moved: [], firstTime: false });
+    expect(chowned).toEqual([owner.home, workspaceRoot]);
+  });
+});