@stigmer/runner 3.40.0 → 3.41.0

package/src/shared/platform-server-address.ts

@@ -0,0 +1,123 @@
+/**
+ * The Stigmer server's address for user-defined MCP servers — the reserved
+ * STIGMER_SERVER_ADDRESS key, and the one dial-target rule every writer of
+ * that key shares (stigmer/stigmer#1433, #1446).
+ *
+ * The runner is the one component that supplies it, because the runner is
+ * the one that knows where the consumer runs:
+ *
+ *   - A remote HTTP server receives the key only through a templated header,
+ *     so it needs the server's PUBLIC address: STIGMER_MCP_PUBLIC_ENDPOINT,
+ *     which the server hands every sandbox it provisions from its own
+ *     configuration (stigmer/stigmer#1447), or an operator names to a
+ *     runner it starts by hand.
+ *   - A stdio server is a child of this runner (only a local runner spawns
+ *     one; mcp-transport-guard.ts), so the address the runner itself dials,
+ *     STIGMER_BACKEND_ENDPOINT, is right for it by construction.
+ *
+ * No page supplies it: a value written into a run's runtime_env sits in the
+ * top merge layer, above every value the user saved (stigmer/stigmer#1446).
+ *
+ * The runner FILLS, it never overrides: a non-empty value already in the
+ * environment (one the user saved or typed to aim a server elsewhere)
+ * stands. A key nobody can supply stays missing, and a
+ * header that templates it fails with the resolver's named
+ * PlaceholderResolutionError instead of dialing a guess.
+ *
+ * Injection is opt-in exactly as for the caller-identity keys
+ * (caller-identity.ts): only a server whose spec.env declares the key
+ * receives it. Applied before filterEnvToDeclaredKeys at execution
+ * (mcp-resolver.ts) and before placeholder resolution at discovery
+ * (activities/discover-mcp-server.ts), so both phases share one rule.
+ */
+
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { Config } from "../config.js";
+
+/**
+ * Reserved env key: the Stigmer server's gRPC dial target, host:port. The
+ * name the mcp-server reads its target from (mcp-server/src/config.ts) and
+ * `@stigmer/react` keeps out of its setup prompts
+ * (sdk/react/src/environment/systemEnvVars.ts); a cross-package string,
+ * pinned on every side.
+ */
+export const SERVER_ADDRESS_ENV_KEY = "STIGMER_SERVER_ADDRESS";
+
+/** The two runner-known endpoints an address can be filled from. */
+export type PlatformEndpoints = Pick<Config, "mcpPublicEndpoint" | "stigmerBackendEndpoint">;
+
+/**
+ * The gRPC dial target (host:port) for an endpoint, the shape
+ * STIGMER_SERVER_ADDRESS wants.
+ *
+ * An http(s) URL becomes its host with an explicit port: the URL's own, else
+ * 80 for http and 443 for https. The port is never left implicit, because
+ * the mcp-server derives TLS from it and assumes :443 with TLS for a
+ * non-loopback host that has none (mcp-server/src/config.ts). Any other
+ * input (a scheme-less host:port, a bare host) is already a dial target and
+ * passes through unchanged.
+ */
+export function grpcTarget(endpoint: string): string {
+  let url: URL;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return endpoint;
+  }
+  // `new URL("host:7234")` parses with `host:` as its scheme, so only a
+  // real http(s) URL is taken apart.
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return endpoint;
+  }
+  const port = url.port || (url.protocol === "https:" ? "443" : "80");
+  return `${url.hostname}:${port}`;
+}
+
+/**
+ * The address the platform supplies for a server of this transport, or
+ * `null` when the runner knows none: the operator's public endpoint for any
+ * transport, else the runner's own backend endpoint for a stdio child.
+ */
+export function platformServerAddress(
+  transport: McpServerTransport | undefined,
+  endpoints: PlatformEndpoints,
+): string | null {
+  if (endpoints.mcpPublicEndpoint) {
+    return grpcTarget(endpoints.mcpPublicEndpoint);
+  }
+  if (transport === "stdio") {
+    return grpcTarget(endpoints.stigmerBackendEndpoint);
+  }
+  return null;
+}
+
+/**
+ * Return the env map with STIGMER_SERVER_ADDRESS filled for `server` when it
+ * declares the key and the map holds no non-empty value for it; otherwise the
+ * map itself, unchanged. Never mutates its input.
+ */
+export function fillPlatformServerAddress(
+  server: McpServer,
+  envVars: Record<string, string>,
+  endpoints: PlatformEndpoints,
+): Record<string, string> {
+  const declared = server.spec?.env ?? {};
+  if (!(SERVER_ADDRESS_ENV_KEY in declared) || envVars[SERVER_ADDRESS_ENV_KEY]) {
+    return envVars;
+  }
+  const value = platformServerAddress(server.spec?.serverType.case, endpoints);
+  if (value === null) {
+    return envVars;
+  }
+  const source = endpoints.mcpPublicEndpoint
+    ? "STIGMER_MCP_PUBLIC_ENDPOINT"
+    : "STIGMER_BACKEND_ENDPOINT";
+  console.info(
+    `MCP server '${server.metadata?.slug ?? ""}': ${SERVER_ADDRESS_ENV_KEY} ` +
+    `filled from ${source} (no value in the execution environment)`,
+  );
+  return { ...envVars, [SERVER_ADDRESS_ENV_KEY]: value };
+}
+
+/** The transports a McpServer spec declares (its `serverType` oneof). */
+type McpServerTransport = NonNullable<NonNullable<McpServer["spec"]>["serverType"]["case"]>;

package/src/shared/prompt-sections.ts

@@ -9,8 +9,12 @@
  * `attachment-download-urls.ts`). What the two prompt builders duplicated
  * until #1096 was the glue around those bodies: the order
  * the five standing sections read in, with the same doctrine comments written
- * twice; the input-files bullet and disclosure lines; which skills a prompt
- * highlights when there are many. This module is that glue, written once.
+ * twice; the input-files bullet and disclosure lines. This module is that
+ * glue, written once. It also chose which skills a prompt highlighted when
+ * there were many, until the native harness stopped choosing skills by the
+ * turn's message: a system prompt that follows the message misses the
+ * provider's prompt cache on every turn, so every harness now describes every
+ * mounted skill.
  *
  * What stays with each harness, on purpose:
  *  - Framing and placement. The native harness renders `## Heading` sections
@@ -43,9 +47,6 @@ import { formatDeclaredPreferencesText, type DeclaredPreferencesContent } from "
 import { formatRecalledMemoriesText, type RecalledMemoriesContent } from "./recalled-memories.js";
 import { formatSenderIdentityText, type SenderIdentity } from "./sender-identity.js";
 import { formatSessionContextText } from "./session-context.js";
-import { filterSkills } from "./skill-relevance.js";
-import type { SkillMetadata } from "./skill-resolver.js";
-import { STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
 
 // ---------------------------------------------------------------------------
 // The standing context: five sections, one order
@@ -204,53 +205,3 @@ export function inputFileLines(
     vision: vision ? visionDisclosureLines(vision.inlineFilenames, vision.notViewable) : [],
   };
 }
-
-// ---------------------------------------------------------------------------
-// The skills: which to highlight
-// ---------------------------------------------------------------------------
-
-/** Which mounted skills a prompt highlights, and which it only names. */
-export interface SkillSelection {
-  /** The skills the prompt describes in full, in the filter's order. */
-  readonly highlighted: readonly SkillMetadata[];
-  /** The names of the skills left out of the highlighted set; empty below the threshold. */
-  readonly alsoAvailable: readonly string[];
-}
-
-/**
- * The relevance selection over the turn's message (`skill-relevance.ts`):
- * below `SKILL_COUNT_THRESHOLD` every skill is highlighted; at and above it,
- * the skills the message's terms reach are highlighted and the rest are
- * named, so the agent can still activate one on its own judgement (the Agent
- * Skills spec's progressive disclosure: metadata up front, instructions on
- * demand). The native harness calls this on every turn; the Cursor harness
- * lists every skill today; adopting the selection there is an open item.
- */
-export function selectSkillsForPrompt(userMessage: string, skills: readonly SkillMetadata[]): SkillSelection {
-  const filter = filterSkills(
-    userMessage,
-    skills.map((s) => s.name),
-    skills.map((s) => s.description),
-  );
-  return {
-    highlighted: filter.includedIndices.map((i) => skills[i]),
-    alsoAvailable: filter.excludedNames,
-  };
-}
-
-/**
- * The tool-neutral sentence that names the skills a prompt did not highlight
- * (`SkillSelection.alsoAvailable`), so the agent can activate one by reading
- * its SKILL.md at the mounted path. The sentence names no tool, so it serves
- * any harness; the heading above it is the builder's framing. Empty for no
- * names.
- */
-export function alsoAvailableSkillsNote(excludedNames: readonly string[]): string {
-  if (excludedNames.length === 0) return "";
-  const names = excludedNames.map((n) => `\`${n}\``).join(", ");
-  return (
-    `These skills are installed but were not highlighted above: ${names}. ` +
-    "If you determine one of them is relevant to your task, " +
-    `read its SKILL.md at \`${STIGMER_LOCAL_STATE_DIR}/skills/<name>/SKILL.md\` to activate it.`
-  );
-}

package/src/shared/skill-resolver.ts

@@ -14,9 +14,8 @@
  * into its prompt in its own placement. Moved from
  * `activities/execute-cursor/` in #1070; the native harness's twin
  * (`skill-writer.ts` `fetchSkillsByRefs` + `mountSkills`) retired in #1096,
- * and the module itself with it — the one renderer it kept is
- * `shared/prompt-sections.ts` `alsoAvailableSkillsNote`. This is the one
- * skills path for every harness.
+ * and the module itself with it. This is the one skills path for every
+ * harness.
  *
  * The mount is cached by the skill's content-addressed version hash
  * (stigmer/stigmer#672): metadata is fetched on every execution (that keeps

package/src/shared/synthesized-attachment.ts

@@ -98,15 +98,3 @@ export function injectSynthesizedAttachment(
     attachment,
   ];
 }
-
-/**
- * The gRPC dial target (host:port) for a backend endpoint URL — the
- * shape STIGMER_SERVER_ADDRESS wants (the bridge warns on schemes).
- */
-export function grpcTarget(endpoint: string): string {
-  try {
-    return new URL(endpoint).host;
-  } catch {
-    return endpoint;
-  }
-}

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__/git-source.test.ts

@@ -73,14 +73,17 @@ describe("provisionGit", () => {
     expect(cmds.some((c) => c.includes("git checkout 'develop'"))).toBe(true);
   });
 
-  it("sets workspace description with repo URL and branch", async () => {
+  it("describes the clone by repo URL and branch, never by its commit", async () => {
     const backend = mockWorkspaceBackend({
       execute: routingExecute({ branch: "main\n", sha: "sha789\n" }),
     });
     const result = await provisionGit(makeOptions({ backend }));
     expect(result.workspaceDescription).toContain("github.com/org/repo.git");
-    expect(result.workspaceDescription).toContain("main");
-    expect(result.workspaceDescription).toContain("sha789");
+    expect(result.workspaceDescription).toContain("(branch: main)");
+    // The native system prompt carries this text on every turn; write-back
+    // commits move HEAD every approved turn, so a commit here would change it.
+    expect(result.workspaceDescription).not.toContain("sha789");
+    expect(result.gitMetadata?.baseCommit, "the commit stays in the metadata write-back reads").toBe("sha789");
   });
 
   // ── Default-branch resolution ─────────────────────────────────────
@@ -120,7 +123,10 @@ describe("provisionGit", () => {
 
     const result = await provisionGit(makeOptions({ backend }));
     expect(result.sourceType).toBe("git_repo");
-    expect(result.workspaceDescription).toContain("existing repo detected");
+    const fresh = await provisionGit(
+      makeOptions({ backend: mockWorkspaceBackend({ execute: routingExecute() }) }),
+    );
+    expect(result.workspaceDescription, "a reused clone is described exactly as a fresh one").toBe(fresh.workspaceDescription);
 
     expect(calls(backend).some((c) => c.includes("git init"))).toBe(false);
     expect(calls(backend).some((c) => c.includes("git fetch"))).toBe(false);
@@ -395,7 +401,7 @@ describe("provisionGit", () => {
     }));
 
     expect(result.gitMetadata!.gitCredentialsConfigured).toBe(true);
-    expect(result.workspaceDescription).toContain("existing repo detected");
+    expect(calls(backend).some((c) => c.includes("git init")), "the reuse path, not a fresh clone").toBe(false);
   });
 
   it("handles credential setup failure gracefully", async () => {

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/sources/git.ts

@@ -83,15 +83,24 @@ export async function provisionGit(options: GitProvisionOptions): Promise<Provis
     rootDir: cloneDir,
     sourceType: "git_repo",
     consumedKeys,
-    workspaceDescription:
-      `Your workspace is a git clone of ${url}` +
-      (metadata.branch ? ` (branch: ${metadata.branch})` : "") +
-      `.\nBase commit: ${metadata.baseCommit}`,
+    workspaceDescription: describeClone(url, metadata.branch),
     gitMetadata: metadata,
     entryName: "",
   };
 }
 
+/**
+ * The model's description of a cloned workspace, the same on the turn that
+ * clones and on every turn that reuses the clone: the native system prompt
+ * carries it and must not change from one message to the next. So it names
+ * the repository and the branch, never the commit (write-back commits move
+ * `HEAD` on every approved turn) and never whether the clone was reused. The
+ * branch changes only when a branch really changes, and the text says so.
+ */
+function describeClone(url: string, branch: string): string {
+  return `Your workspace is a git clone of ${url}` + (branch ? ` (branch: ${branch})` : "") + ".";
+}
+
 async function reuseExistingRepo(
   cloneDir: string,
   url: string,
@@ -114,10 +123,7 @@ async function reuseExistingRepo(
     rootDir: cloneDir,
     sourceType: "git_repo",
     consumedKeys: [],
-    workspaceDescription:
-      `Your workspace is a git clone of ${url}` +
-      (metadata.branch ? ` (branch: ${metadata.branch})` : "") +
-      ` (existing repo detected).\nBase commit: ${metadata.baseCommit}`,
+    workspaceDescription: describeClone(url, metadata.branch),
     gitMetadata: metadata,
     entryName: "",
   };