@stigmer/runner 3.40.0 → 3.41.0

package/src/activities/execute-deep-agent/__tests__/turn-stream.test.ts

@@ -45,7 +45,7 @@ import type { WorkspaceBackend } from "../../../shared/workspace/types.js";
 import type { ModelPricing } from "../../../shared/model-pricing.js";
 import { CasCaptureObserver } from "../cas-capture-observer.js";
 import type { DeepAgentEngine, DeepAgentGateState, DeepAgentGraphInput, DeepAgentWorkspace } from "../turn-setup.js";
-import { consumeDeepAgentStream, createDeepAgentTranscript, type StreamableRun } from "../turn-stream.js";
+import { consumeDeepAgentStream, createDeepAgentTranscript, type DeepAgentTranscript, type StreamableRun } from "../turn-stream.js";
 import type { V3ProtocolEvent } from "../v3-event-recorder.js";
 import {
   makeMessageFinish,
@@ -129,6 +129,8 @@ interface Harness {
   readonly engine: DeepAgentEngine;
   readonly streamEvents: ReturnType<typeof vi.fn>;
   readonly blobs: Map<string, Buffer>;
+  /** The transcript the last `run` streamed into; its side effects hold the turn's publishes. */
+  readonly transcript: () => DeepAgentTranscript;
   run(run: StreamableRun): ReturnType<typeof consumeDeepAgentStream>;
 }
 
@@ -150,14 +152,19 @@ function harness(options: { gate?: DeepAgentGateState; files?: Record<string, st
   };
   const workspace = workspaceOver(options.files ?? {});
   const graphInput: DeepAgentGraphInput = { kind: "message", input: { messages: [{ role: "user", content: "Say hello." }] } };
+  let transcript: DeepAgentTranscript | undefined;
   return {
     sink,
     engine,
     streamEvents,
     blobs,
+    transcript: () => {
+      if (transcript === undefined) throw new Error("harness: no run yet");
+      return transcript;
+    },
     run(run) {
       streamEvents.mockResolvedValue(run);
-      const transcript = createDeepAgentTranscript(input, sink, engine, workspace);
+      transcript = createDeepAgentTranscript(input, sink, engine, workspace);
       return consumeDeepAgentStream({ input, sink, engine, graphInput, transcript });
     },
   };
@@ -245,7 +252,7 @@ describe("consumeDeepAgentStream — what each event becomes", () => {
 
   it("publishes a file-modifying tool's target as an artifact on the status when the call finishes", async () => {
     const h = harness({ files: { "src/main.ts": "console.log('hi');" } });
-    const result = await h.run(
+    await h.run(
       scriptedRun([
         ...textTurn("run-1", "Writing."),
         makeToolStarted("toolu_w", "write_file", { file_path: "src/main.ts", content: "console.log('hi');" }),
@@ -253,8 +260,9 @@ describe("consumeDeepAgentStream — what each event becomes", () => {
       ]),
     );
 
-    expect(result.pendingPublishPromises, "one publish fired mid-turn, for the settle to drain").toHaveLength(1);
-    await Promise.all(result.pendingPublishPromises);
+    const { sideEffects } = h.transcript();
+    expect(sideEffects.pendingPublishPromises, "one publish fired mid-turn, held by the transcript for the drain").toHaveLength(1);
+    await sideEffects.drainPublishes();
     expect(h.sink.status.artifacts.map((a) => a.sandboxPath)).toEqual(["src/main.ts"]);
     expect([...h.blobs.keys()], "the bytes were uploaded under the execution's artifact key").toEqual(["artifacts/aex_fixture_0001/main.ts"]);
   });

package/src/activities/execute-deep-agent/inline-publisher.ts

@@ -8,6 +8,15 @@
  * Designed as a fire-and-forget callback: exceptions are logged and
  * swallowed so the streaming loop is never interrupted.
  *
+ * A file is uploaded only when its bytes differ from the row the execution's
+ * status already lists for its path. The status is the one home of that fact:
+ * the builder writes every row into it, and a reinvocation's seed carries the
+ * earlier turns' rows onto it before this publisher exists. So a completed
+ * turn after a gate, whose safety net walks the seeded history again, re-reads
+ * each earlier file but uploads none that did not change (stigmer/stigmer#1448).
+ * The re-read is kept on purpose: a shell command may have rewritten an earlier
+ * turn's file, and only its bytes can say so.
+ *
  * DD-7: No skill-aware directory publishing. Individual files only.
  */
 
@@ -35,6 +44,16 @@ export interface ArtifactSink {
   addArtifact(artifact: ExecutionArtifact): void;
 }
 
+/**
+ * The execution status's artifact rows, read at every publish: the status the
+ * {@link ArtifactSink} builds into (`TurnSink.status` in production), so a row
+ * registered here or seeded by a reinvocation is visible on the next check.
+ * Read, never copied, because the builder keeps writing it.
+ */
+export interface ArtifactRecord {
+  readonly artifacts: readonly ExecutionArtifact[];
+}
+
 export class InlinePublisher {
   private readonly workspaceBackend: WorkspaceBackend;
   /**
@@ -45,33 +64,46 @@ export class InlinePublisher {
    */
   private readonly artifactStorage: ArtifactStorage | undefined;
   private readonly artifacts: ArtifactSink;
+  private readonly record: ArtifactRecord;
   private readonly executionId: string;
 
-  /** Tracks (sandboxPath -> contentHash) for deduplication. */
-  private readonly published = new Map<string, string>();
+  /**
+   * Paths this publisher brought up to date in this turn, uploaded or found
+   * unchanged, so the post-stream safety net does not read them again. Per
+   * turn by design: an earlier turn's path is absent until this turn checks
+   * it, so a file rewritten outside a write tool is still caught.
+   */
+  private readonly published = new Set<string>();
 
   constructor(opts: {
     workspaceBackend: WorkspaceBackend;
     artifactStorage: ArtifactStorage | undefined;
     artifacts: ArtifactSink;
+    record: ArtifactRecord;
     executionId: string;
   }) {
     this.workspaceBackend = opts.workspaceBackend;
     this.artifactStorage = opts.artifactStorage;
     this.artifacts = opts.artifacts;
+    this.record = opts.record;
     this.executionId = opts.executionId;
   }
 
-  /** Set of sandbox paths that have been published (for auto-publish dedup). */
+  /** Set of sandbox paths brought up to date this turn (for auto-publish dedup). */
   get publishedPaths(): ReadonlySet<string> {
-    return new Set(this.published.keys());
+    return new Set(this.published);
   }
 
   /**
    * Upload the file at `path` to artifact storage and register it on the
    * status builder. Fire-and-forget: errors are logged and swallowed.
+   *
+   * The artifact's `createdAt` is read here, before the first await: the
+   * stream asks for the publish in the step that folds the write's finish, so
+   * the stamp is the write's, never the moment a slow upload returned.
    */
   async publish(path: string): Promise<void> {
+    const createdAt = utcTimestamp();
     // No artifact store (proxy misconfig): nothing to upload to. Skip silently —
     // this is a best-effort UI publisher and the operator was warned at setup.
     if (!this.artifactStorage) return;
@@ -97,7 +129,8 @@ export class InlinePublisher {
       const contentBuffer = Buffer.from(content, "utf-8");
       const contentHash = sha256(contentBuffer);
 
-      if (this.published.get(sandboxPath) === contentHash) {
+      if (this.isRecorded(sandboxPath, contentHash)) {
+        this.published.add(sandboxPath);
         return;
       }
 
@@ -112,12 +145,12 @@ export class InlinePublisher {
         kind: ExecutionArtifactKind.FILE,
         sizeBytes: BigInt(contentBuffer.length),
         storageKey,
-        createdAt: utcTimestamp(),
+        createdAt,
         contentHash,
       });
 
       this.artifacts.addArtifact(artifact);
-      this.published.set(sandboxPath, contentHash);
+      this.published.add(sandboxPath);
 
       console.log(
         `[InlinePublisher] execution=${this.executionId} — published '${sandboxPath}' ` +
@@ -130,6 +163,13 @@ export class InlinePublisher {
       );
     }
   }
+
+  /** Whether the status already lists these exact bytes at this path. */
+  private isRecorded(sandboxPath: string, contentHash: string): boolean {
+    return this.record.artifacts.some(
+      (a) => a.sandboxPath === sandboxPath && a.contentHash === contentHash,
+    );
+  }
 }
 
 function normalizePath(path: string): string {

package/src/activities/execute-deep-agent/platform-route.ts

@@ -30,9 +30,18 @@
  *
  * WHEN IT IS MOUNTED
  * ------------------
- * On the turns where the workspace link points at the platform dir — the
- * turns whose skill or attachment phase made it — so what the agent can
- * reach is exactly what the link exposes to the shell on the same turn.
+ * On every turn: `.stigmer/` is the platform's name whether or not the turn
+ * mounted anything, so a write there never reaches the workspace. Before
+ * #1123 the route existed only on linked turns, and a write under `.stigmer/`
+ * on any other turn made a real directory in the user's tree that the next
+ * link displaced. What the route exposes follows the link, so the file tools
+ * reach exactly what the shell reaches on the same turn:
+ * - on a turn whose skill or attachment phase made the link, the platform dir
+ *   ({@link PlatformContentBackend});
+ * - on any other turn, nothing ({@link NoPlatformContentBackend}): the dir
+ *   still holds earlier turns' skills and inputs, which this turn's shell
+ *   cannot reach, so the file tools must not either. The root listing then
+ *   leaves `.stigmer/` out, as the tree does.
  * The link itself stays: shell commands (a skill's own scripts among them)
  * run in the workspace and resolve `.stigmer/…` through it.
  */
@@ -40,10 +49,16 @@
 import { CompositeBackend, FilesystemBackend } from "deepagents";
 import type {
   AnyBackendProtocol,
+  BackendProtocolV2,
   DeleteResult,
   EditResult,
+  FileDownloadResponse,
   FileUploadResponse,
+  GlobResult,
+  GrepResult,
   LsResult,
+  ReadRawResult,
+  ReadResult,
   WriteResult,
 } from "deepagents";
 import { STIGMER_LOCAL_STATE_DIR, stigmerSymlinkPointsAt } from "../../shared/workspace/stigmer-link.js";
@@ -51,14 +66,25 @@ import { STIGMER_LOCAL_STATE_DIR, stigmerSymlinkPointsAt } from "../../shared/wo
 /** The route prefix, with the trailing slash `CompositeBackend` needs to match `/.stigmer/x` but never `/.stigmerx`. */
 export const PLATFORM_ROUTE_PREFIX = `/${STIGMER_LOCAL_STATE_DIR}/`;
 
+/** The path as the agent named it: the route hands its backend the path with the prefix stripped. */
+function agentPath(routedPath: string): string {
+  return `${PLATFORM_ROUTE_PREFIX.slice(0, -1)}${routedPath}`;
+}
+
 function readOnly(routedPath: string): string {
-  const agentPath = `${PLATFORM_ROUTE_PREFIX.slice(0, -1)}${routedPath}`;
   return (
-    `Error: '${agentPath}' is platform content (skills, attached inputs, the approved plan) ` +
+    `Error: '${agentPath(routedPath)}' is platform content (skills, attached inputs, the approved plan) ` +
     "and is read-only; write your own files in the workspace"
   );
 }
 
+function noPlatformContent(routedPath: string): string {
+  return (
+    `Error: '${agentPath(routedPath)}' does not exist: this turn has no platform content ` +
+    "(no skills or attached inputs)"
+  );
+}
+
 /** The platform dir, virtual-rooted like every native backend, refusing every mutation. */
 export class PlatformContentBackend extends FilesystemBackend {
   constructor(platformDir: string) {
@@ -83,17 +109,80 @@ export class PlatformContentBackend extends FilesystemBackend {
 }
 
 /**
- * The workspace backend with the platform mounted at {@link PLATFORM_ROUTE_PREFIX}.
+ * The `.stigmer/` route on a turn that exposes no platform content: nothing
+ * to read, list or find, and every mutation refused with the same message
+ * the platform dir's route gives. It stands on no filesystem, so it cannot
+ * create or reveal anything, and `ls` answers "does not exist" rather than
+ * an empty listing because the root listing leaves `.stigmer/` out.
+ */
+export class NoPlatformContentBackend implements BackendProtocolV2 {
+  ls(path: string): LsResult {
+    return { error: noPlatformContent(path) };
+  }
+
+  read(filePath: string): ReadResult {
+    return { error: noPlatformContent(filePath) };
+  }
+
+  readRaw(filePath: string): ReadRawResult {
+    return { error: noPlatformContent(filePath) };
+  }
+
+  grep(): GrepResult {
+    return { matches: [] };
+  }
+
+  glob(): GlobResult {
+    return { files: [] };
+  }
+
+  write(filePath: string): WriteResult {
+    return { error: readOnly(filePath) };
+  }
+
+  edit(filePath: string): EditResult {
+    return { error: readOnly(filePath) };
+  }
+
+  delete(filePath: string): DeleteResult {
+    return { error: readOnly(filePath) };
+  }
+
+  uploadFiles(files: Array<[string, Uint8Array]>): FileUploadResponse[] {
+    return files.map(([path]) => ({ path, error: "permission_denied" }));
+  }
+
+  downloadFiles(paths: string[]): FileDownloadResponse[] {
+    return paths.map((path) => ({ path, content: null, error: "file_not_found" }));
+  }
+}
+
+/**
+ * The workspace backend with `.stigmer/` routed to {@link PLATFORM_ROUTE_PREFIX}'s
+ * backend for this turn.
  *
  * One behaviour differs from the stock router: listing `/`. The composite
- * adds each route to the root listing, and the workspace backend already
- * lists `.stigmer/` by following the link, so the stock listing names the
- * same directory twice; the root listing is de-duplicated by path.
+ * adds each route to the root listing whatever the route holds. With the
+ * platform exposed, the workspace backend also lists `.stigmer/` by following
+ * the link, so the stock listing names the same directory twice and is
+ * de-duplicated by path. With nothing exposed, `.stigmer/` is left out of the
+ * root listing altogether: the route has nothing to show, and a real
+ * `.stigmer` the workspace may hold is unreachable behind it.
  */
 export class PlatformRoutedBackend extends CompositeBackend {
+  private readonly exposesPlatform: boolean;
+
+  constructor(backend: AnyBackendProtocol, platform: PlatformContentBackend | NoPlatformContentBackend) {
+    super(backend, { [PLATFORM_ROUTE_PREFIX]: platform });
+    this.exposesPlatform = platform instanceof PlatformContentBackend;
+  }
+
   override async ls(path: string): Promise<LsResult> {
     const result = await super.ls(path);
     if (path !== "/" || !result.files) return result;
+    if (!this.exposesPlatform) {
+      return { ...result, files: result.files.filter((entry) => entry.path !== PLATFORM_ROUTE_PREFIX) };
+    }
     const seen = new Set<string>();
     return {
       ...result,
@@ -114,21 +203,21 @@ export interface PlatformRouteOptions {
 }
 
 /**
- * Mount the platform route over `backend` when this turn exposes platform
- * content; otherwise hand `backend` back unchanged. `execute` and the
- * sandbox identity stay the workspace backend's (`CompositeBackend` delegates
- * both to its default), so a shell-capable graph keeps its `execute` tool and
- * a plan-mode graph stays without one.
+ * Mount the `.stigmer/` route over `backend` for this turn: the platform dir
+ * when the workspace link points at it, the empty route otherwise. Only a
+ * session without a platform dir gets `backend` back unchanged. `execute`
+ * and the sandbox identity stay the workspace backend's (`CompositeBackend`
+ * delegates both to its default), so a shell-capable graph keeps its
+ * `execute` tool and a plan-mode graph stays without one.
  */
 export async function mountPlatformRoute(
   backend: AnyBackendProtocol,
   options: PlatformRouteOptions,
 ): Promise<AnyBackendProtocol> {
   const { workspaceDir, platformDir } = options;
-  if (platformDir === undefined || !(await stigmerSymlinkPointsAt(workspaceDir, platformDir))) {
-    return backend;
-  }
-  return new PlatformRoutedBackend(backend, {
-    [PLATFORM_ROUTE_PREFIX]: new PlatformContentBackend(platformDir),
-  });
+  if (platformDir === undefined) return backend;
+  const platform = (await stigmerSymlinkPointsAt(workspaceDir, platformDir))
+    ? new PlatformContentBackend(platformDir)
+    : new NoPlatformContentBackend();
+  return new PlatformRoutedBackend(backend, platform);
 }

package/src/activities/execute-deep-agent/prompt-builder.ts

@@ -1,19 +1,32 @@
 /**
- * The native harness's system prompt: what `createDeepAgent` receives as
- * `systemPrompt`, rebuilt on EVERY invocation (never checkpointed with the
- * message history), so every standing fact is injected on every turn by
- * design — a first-turn-only injection would vanish from turn 2 onward.
+ * The native harness's prompt: the system prompt `createDeepAgent` receives
+ * as `systemPrompt`, and the turn's user message.
+ *
+ * The system prompt is rebuilt on EVERY invocation (never checkpointed with
+ * the message history), so every standing fact is injected on every turn by
+ * design — a first-turn-only injection would vanish from turn 2 onward. It is
+ * a function of the session and of the execution's settings (its mode), never
+ * of the turn. The provider caches tools, system and messages as one prefix,
+ * so a system byte that follows the message re-writes the cached prompt and
+ * the whole conversation after it, on every turn, at the cache-write price.
+ * What belongs to one turn — its input files, the workspace paths it
+ * references, the conversation catchup — rides that turn's user message
+ * (`composeUserMessage`), which enters the checkpointer with the turn and
+ * stays in history. That is the Cursor harness's resumed-turn placement
+ * (`execute-cursor/prompt-builder.ts` `buildPrompt`) and the runner's rule
+ * that user content goes in user messages, never the system prompt.
  *
  * Pure functions: no side effects, no I/O. `turn-setup.ts` gathers the
  * inputs from the runtime's resolved record and this module renders them.
  *
  * What is this harness's and what is shared (since #1096):
  *  - Shared through `shared/prompt-sections.ts`: WHICH standing sections
- *    render and in WHAT order (`standingContextSections`), the input-files
- *    bullet and disclosure lines (`inputFileLines`), which skills a prompt
- *    highlights (`selectSkillsForPrompt`, called from `turn-setup.ts`) and
- *    the also-available sentence. Their WORDS come from each fact's own
- *    module; this builder only frames them.
+ *    render and in WHAT order (`standingContextSections`) and the
+ *    input-files bullet and disclosure lines (`inputFileLines`). Their WORDS
+ *    come from each fact's own module; this builder only frames them. Every
+ *    mounted skill is described on every turn, as the Cursor harness does:
+ *    choosing skills by the message made the system prompt follow the
+ *    message.
  *  - This harness's: the framing — `## Heading` markdown sections, the house
  *    style for a system prompt — and every text that quotes this engine's
  *    tools: the `## Skills` activation protocol, the response rules, the
@@ -24,7 +37,8 @@
  *
  * The rendered bytes are load-bearing for the hermetic tests: `ScriptedModel`
  * tells its scripted roles apart by the system prompt's text, so this
- * module's whole output is pinned by `__tests__/prompt-goldens.test.ts`.
+ * module's whole output — the system prompt and the turn's message — is
+ * pinned by `__tests__/prompt-goldens.test.ts`.
  */
 
 import { relative } from "node:path";
@@ -43,10 +57,7 @@ import {
 } from "../../shared/prompt-sections.js";
 import { effectiveInstructions } from "../../shared/builtin-assistant-prompt.js";
 import { PLAN_MODE_DIRECTIVE } from "../../shared/plan-mode-prompt.js";
-import {
-  buildImplementPlanDirective,
-  findApprovedPlanPath,
-} from "../../shared/implement-plan-prompt.js";
+import { buildImplementPlanDirective } from "../../shared/implement-plan-prompt.js";
 import type { ResolvedAttachment } from "../../shared/attachment-resolver.js";
 import type { SkillMetadata } from "../../shared/skill-resolver.js";
 import { STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
@@ -131,22 +142,6 @@ export interface PromptBuilderInput {
    * when the agent serves no proactive channel or nothing is sendable.
    */
   channelTemplatesPromptSection?: string;
-  workspaceFileRefs: string[];
-  workspaceRoot: string;
-  /** The turn's resolved input files, as the runtime's attachment phase returns them. */
-  inputFiles: readonly ResolvedAttachment[];
-  /**
-   * Vision facts about this turn's attachments (T04): which images the model
-   * sees inline in the user message and which degraded to path-only.
-   * Rendered inside the Input Files section.
-   */
-  vision?: VisionPromptInfo;
-  /**
-   * What kind of URL the turn's storage backend mints (issue #532) — keys
-   * the Input Files section's hand-off wording (attachment-download-urls.ts).
-   * One turn-level fact: all attachments ride the one configured storage.
-   */
-  downloadUrlKind?: DownloadUrlKind;
   /**
    * The execution's interaction mode. PLAN appends the shared plan-mode
    * directive so the model knows the turn's deliverable is a plan document.
@@ -163,6 +158,14 @@ export interface PromptBuilderInput {
    * message itself is just a short label ("Build from plan").
    */
   buildFromPlan?: boolean;
+  /**
+   * The approved plan's path among the turn's input files
+   * (`implement-plan-prompt.ts` `findApprovedPlanPath`), read only under
+   * `buildFromPlan`. Absent when the plan did not materialize, which selects
+   * the directive's conversation-plan variant. The Input Files section
+   * itself rides the turn's message (`composeUserMessage`).
+   */
+  approvedPlanPath?: string;
   /**
    * Rollover context bridge (cloud DD-013): a digest of the previous
    * session's conversation, read from `SessionSpec.metadata`. Injected on
@@ -252,22 +255,6 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
     prompt += "\n\n" + input.channelTemplatesPromptSection;
   }
 
-  if (input.workspaceFileRefs.length > 0) {
-    const refSection = buildReferencedFilesSection(
-      input.workspaceFileRefs,
-      input.workspaceRoot,
-    );
-    if (refSection) {
-      prompt += refSection;
-    }
-  }
-
-  if (input.inputFiles.length > 0) {
-    prompt += buildInputFilesSection(
-      input.inputFiles, input.vision, input.downloadUrlKind,
-    );
-  }
-
   // The standing context, in the shared order (the doctrine is stated once,
   // on `standingContextSections`); this harness only frames each section.
   for (const section of standingContextSections(input)) {
@@ -296,34 +283,67 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
   }
 
   if (input.buildFromPlan) {
-    const planPath = findApprovedPlanPath(
-      input.inputFiles.map((f) => f.relativePath),
-    );
     prompt +=
       "\n\n## Implement the approved plan\n\n" +
-      buildImplementPlanDirective(planPath);
+      buildImplementPlanDirective(input.approvedPlanPath);
   }
 
   return prompt;
 }
 
+/** The turn's own content, composed around what the user typed. */
+export interface TurnMessageInput {
+  /** What the user typed (`spec.message`); never mutated. */
+  readonly message: string;
+  /** The conversation catchup digest (cloud DD-006), when the turn carries one. */
+  readonly conversationCatchup?: string;
+  /** This turn's resolved input files, as the runtime's attachment phase returns them. */
+  readonly inputFiles: readonly ResolvedAttachment[];
+  /**
+   * Vision facts about this turn's attachments (T04): which images the model
+   * sees inline in this same message and which degraded to path-only.
+   * Rendered inside the Input Files section.
+   */
+  readonly vision?: VisionPromptInfo;
+  /**
+   * What kind of URL the turn's storage backend mints (issue #532) — keys
+   * the Input Files section's hand-off wording (attachment-download-urls.ts).
+   * One turn-level fact: all attachments ride the one configured storage.
+   */
+  readonly downloadUrlKind?: DownloadUrlKind;
+  /** The workspace paths the user highlighted for this message (`spec.workspace_file_refs`). */
+  readonly workspaceFileRefs: readonly string[];
+}
+
 /**
- * Compose the turn's USER MESSAGE for the graph invocation: the framed
- * conversation catchup (cloud DD-006), when present, prepended to the
- * customer's message. In the user message and never the system prompt (A27):
- * the system prompt is rebuilt per invocation and would forget the digest one
- * turn later, while a message enters the checkpointer with the turn and
- * persists in history — the same durability the cursor harness gets from its
- * prompt prefix. The caller's `spec.message` is never mutated; the prepend
- * exists only in the graph input.
+ * Compose the turn's USER MESSAGE for the graph invocation: this turn's
+ * payload (its input files, then the workspace paths it references), then the
+ * framed conversation catchup (cloud DD-006), then what the user typed, each
+ * set off by a horizontal rule. Payload first and context closest to the task
+ * is the Cursor harness's resumed-turn order.
+ *
+ * In the user message and never the system prompt (A27, and the module
+ * header): the system prompt is rebuilt per invocation, so a turn's content
+ * there would vanish one turn later and, while it lasted, change the cached
+ * prefix; a message enters the checkpointer with the turn and persists in
+ * history, so a later turn still knows which files an earlier one carried.
+ * An approval resume sends no new message and needs none: the payload is
+ * already in the checkpointed one. The caller's `spec.message` is never
+ * mutated; the composition exists only in the graph input.
  */
-export function composeUserMessage(
-  message: string,
-  conversationCatchup: string | undefined,
-): string {
-  return conversationCatchup
-    ? `${formatConversationCatchupText(conversationCatchup)}\n\n---\n\n${message}`
-    : message;
+export function composeUserMessage(input: TurnMessageInput): string {
+  const parts: string[] = [];
+  if (input.inputFiles.length > 0) {
+    parts.push(buildInputFilesSection(input.inputFiles, input.vision, input.downloadUrlKind));
+  }
+  if (input.workspaceFileRefs.length > 0) {
+    parts.push(buildReferencedFilesSection(input.workspaceFileRefs));
+  }
+  if (input.conversationCatchup) {
+    parts.push(formatConversationCatchupText(input.conversationCatchup));
+  }
+  parts.push(input.message);
+  return parts.join("\n\n---\n\n");
 }
 
 /**
@@ -454,14 +474,14 @@ function formatEntryDescription(result: ProvisionResult): string {
     );
   }
 
+  // No commit: the clone's HEAD moves with every write-back commit, and a
+  // system prompt that names it would change on every such turn
+  // (`shared/workspace/sources/git.ts` says the same for one entry).
   if (result.sourceType === "git_repo" && result.gitMetadata) {
     const meta: GitMetadata = result.gitMetadata;
-    const shortSha = meta.baseCommit.length >= 7
-      ? meta.baseCommit.slice(0, 7)
-      : meta.baseCommit;
+    const branch = meta.branch ? ` (branch: ${meta.branch})` : "";
     return (
-      `Workspace entry **${name}** was initialized from ` +
-      `${meta.repoUrl} (branch: ${meta.branch}, commit: ${shortSha}).\n` +
+      `Workspace entry **${name}** was initialized from ${meta.repoUrl}${branch}.\n` +
       "Changes you make will be captured as artifacts when execution completes."
     );
   }
@@ -476,36 +496,29 @@ function formatEntryDescription(result: ProvisionResult): string {
   return result.workspaceDescription;
 }
 
-function buildReferencedFilesSection(
-  workspaceFileRefs: string[],
-  _workspaceRoot: string,
-): string {
-  if (workspaceFileRefs.length === 0) return "";
-
-  let section =
-    "\n\n## Referenced Files\n\n" +
+/** The `## Referenced Files` part of the turn's message: the paths the user highlighted, one bullet each. */
+function buildReferencedFilesSection(workspaceFileRefs: readonly string[]): string {
+  return (
+    "## Referenced Files\n\n" +
     "The user has highlighted the following workspace paths for your " +
-    `attention. Use \`${ENGINE_TOOL.readFile}\` to access file contents.\n\n`;
-
-  for (const refPath of workspaceFileRefs) {
-    section += `- \`${refPath}\`\n`;
-  }
-
-  return section;
+    `attention. Use \`${ENGINE_TOOL.readFile}\` to access file contents.\n\n` +
+    workspaceFileRefs.map((refPath) => `- \`${refPath}\``).join("\n")
+  );
 }
 
 /**
- * The `## Input Files` section: this harness's intro (it names this engine's
- * file-reading tool) around the shared lines (`prompt-sections.ts` `inputFileLines`
- * says what each bullet and disclosure carries and why). Each disclosure
- * group is set off by a blank line, the markdown idiom.
+ * The `## Input Files` part of the turn's message: this harness's intro (it
+ * names this engine's file-reading tool) around the shared lines
+ * (`prompt-sections.ts` `inputFileLines` says what each bullet and disclosure
+ * carries and why). Each disclosure group is set off by a blank line, the
+ * markdown idiom.
  */
 function buildInputFilesSection(
   files: readonly ResolvedAttachment[],
   vision?: VisionPromptInfo,
   downloadUrlKind?: DownloadUrlKind,
 ): string {
-  let section = "\n\n## Input Files\n\n";
+  let section = "## Input Files\n\n";
   section +=
     "The following files have been provided as read-only reference " +
     "material for your task. They live under `.stigmer/inputs/` and " +
@@ -526,7 +539,6 @@ function buildInputFilesSection(
     section += "\n" + lines.vision.join("\n") + "\n";
   }
 
-  // Every section opens with its own blank line ("\n\n## ..."), so this one
-  // ends on its last line rather than adding a second blank (#1127).
+  // The part ends on its last line; the message's rule sets it off (#1127).
   return section.replace(/\n+$/, "");
 }