@stigmer/runner 3.14.0 → 3.15.0

package/src/shared/__tests__/worker-shutdown.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
+import { CancelledFailure } from "@temporalio/activity";
 import {
+  cancellationReasonOf,
   classifyTurnInterruption,
   getShutdownSignalForQueue,
   registerWorkerShutdownSignal,
@@ -44,58 +46,61 @@ describe("worker-shutdown signal registry", () => {
 });
 
 describe("classifyTurnInterruption", () => {
-  const none = {
-    heartbeatCancelled: false,
-    heartbeatWorkerShutdown: false,
-    cancellationSignalAborted: false,
-    shutdownSignalAborted: false,
-  };
-
   it("an uninterrupted turn is none", () => {
-    expect(classifyTurnInterruption(none)).toBe("none");
+    expect(classifyTurnInterruption({ cancellationReason: undefined, shutdownSignalAborted: false })).toBe("none");
   });
 
   it("GRACE-WINDOW GUARD (#776): an aborted shutdown signal alone stays none — a run that completed inside the drain grace window must not be failed", () => {
-    expect(
-      classifyTurnInterruption({ ...none, shutdownSignalAborted: true }),
-    ).toBe("none");
+    expect(classifyTurnInterruption({ cancellationReason: undefined, shutdownSignalAborted: true })).toBe("none");
+  });
+
+  it("a workflow-requested cancellation without a shutdown signal is the orchestrator's pause", () => {
+    expect(classifyTurnInterruption({ cancellationReason: "CANCELLED", shutdownSignalAborted: false })).toBe("pause");
+  });
+
+  it("a delivered cancellation WITH the shutdown signal aborted is a worker shutdown, not a pause (the #776 misclassification)", () => {
+    expect(classifyTurnInterruption({ cancellationReason: "CANCELLED", shutdownSignalAborted: true })).toBe("worker-shutdown");
   });
 
-  it("heartbeat cancellation without a shutdown signal is the orchestrator's pause", () => {
-    expect(
-      classifyTurnInterruption({ ...none, heartbeatCancelled: true }),
-    ).toBe("pause");
+  it("the SDK's own WORKER_SHUTDOWN reason classifies directly, signal or not", () => {
+    expect(classifyTurnInterruption({ cancellationReason: "WORKER_SHUTDOWN", shutdownSignalAborted: false })).toBe("worker-shutdown");
   });
 
-  it("heartbeat cancellation WITH the shutdown signal aborted is a worker shutdown, not a pause (the #776 misclassification)", () => {
-    expect(
-      classifyTurnInterruption({
-        ...none,
-        heartbeatCancelled: true,
-        shutdownSignalAborted: true,
-      }),
-    ).toBe("worker-shutdown");
+  it("a heartbeat timeout (TIMED_OUT) is an infrastructure cancel, neither shutdown nor pause", () => {
+    expect(classifyTurnInterruption({ cancellationReason: "TIMED_OUT", shutdownSignalAborted: false })).toBe("infrastructure");
   });
 
-  it("the heartbeat's own workerShutdown flag classifies directly", () => {
-    expect(
-      classifyTurnInterruption({ ...none, heartbeatWorkerShutdown: true }),
-    ).toBe("worker-shutdown");
+  it("any other reason (a closed run, a conversion failure) is an infrastructure cancel", () => {
+    expect(classifyTurnInterruption({ cancellationReason: "NOT_FOUND", shutdownSignalAborted: false })).toBe("infrastructure");
+    expect(classifyTurnInterruption({ cancellationReason: "HEARTBEAT_DETAILS_CONVERSION_FAILED", shutdownSignalAborted: false })).toBe("infrastructure");
+  });
+
+  it("the shutdown signal outranks an infrastructure reason: a drain is a drain whatever Temporal says", () => {
+    expect(classifyTurnInterruption({ cancellationReason: "TIMED_OUT", shutdownSignalAborted: true })).toBe("worker-shutdown");
+  });
+});
+
+describe("cancellationReasonOf", () => {
+  it("is undefined for a live signal", () => {
+    expect(cancellationReasonOf(new AbortController().signal)).toBeUndefined();
   });
 
-  it("a delivered cancellation with the shutdown signal aborted is a worker shutdown (signal races the heartbeat tick)", () => {
-    expect(
-      classifyTurnInterruption({
-        ...none,
-        cancellationSignalAborted: true,
-        shutdownSignalAborted: true,
-      }),
-    ).toBe("worker-shutdown");
+  it("reads the CancelledFailure message the Temporal SDK aborts with", () => {
+    const controller = new AbortController();
+    controller.abort(new CancelledFailure("TIMED_OUT"));
+    expect(cancellationReasonOf(controller.signal)).toBe("TIMED_OUT");
   });
 
-  it("a delivered cancellation alone (heartbeat timeout / infra cancel) is neither shutdown nor pause", () => {
-    expect(
-      classifyTurnInterruption({ ...none, cancellationSignalAborted: true }),
-    ).toBe("none");
+  it("reads a string reason as itself and a reasonless abort as CANCELLED", () => {
+    const withString = new AbortController();
+    withString.abort("WORKER_SHUTDOWN");
+    expect(cancellationReasonOf(withString.signal)).toBe("WORKER_SHUTDOWN");
+    const bare = new AbortController();
+    bare.abort();
+    // A bare abort() carries a DOMException (an Error), whose message is the
+    // platform's "This operation was aborted": not a Temporal reason, but a
+    // delivered cancellation all the same — the classifier files it as
+    // infrastructure, never as nothing.
+    expect(cancellationReasonOf(bare.signal)).toBeTypeOf("string");
   });
 });

package/src/shared/approval-policy.ts

@@ -438,7 +438,7 @@ export function mergeApprovalPolicies(
 export function lookupMcpToolPolicy(
   toolName: string,
   mcpServerSlug: string,
-  policies: Map<string, MergedToolPolicy>,
+  policies: ReadonlyMap<string, MergedToolPolicy>,
 ): MergedToolPolicy | undefined {
   return policies.get(`${mcpServerSlug}/${toolName}`);
 }

package/src/{activities/execute-cursor → shared}/attachment-resolver.ts

@@ -39,18 +39,18 @@
 import { mkdir, copyFile, readFile, stat, writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
-import type { ArtifactStorage } from "../../shared/artifact-storage.js";
-import { mintAttachmentDownloadUrl } from "../../shared/attachment-download-urls.js";
-import { allocateUniqueName } from "../../shared/attachment-naming.js";
+import type { ArtifactStorage } from "./artifact-storage.js";
+import { mintAttachmentDownloadUrl } from "./attachment-download-urls.js";
+import { allocateUniqueName } from "./attachment-naming.js";
 import {
   isVisionCandidate,
   type VisionBudget,
   type VisionDegradedReason,
   type VisionImage,
   type VisionOutcome,
-} from "../../shared/attachment-vision.js";
-import { getPlatformDir } from "../../shared/workspace/platform-dir.js";
-import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
+} from "./attachment-vision.js";
+import { getPlatformDir } from "./workspace/platform-dir.js";
+import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
 
 const INPUTS_SUBDIR = "inputs";
 

package/src/{activities/execute-cursor → shared}/blueprint-resolver.ts

@@ -11,31 +11,25 @@
  * containing runner-internal markers are rejected with a warning.
  */
 
-import { resolve } from "node:path";
-import type { StigmerClient } from "../../client/stigmer-client.js";
+import type { StigmerClient } from "../client/stigmer-client.js";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import type { AgentSpec, McpServerUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import type { CloudRepo } from "./session-lifecycle.js";
-import { mergeMcpServerUsages } from "../../shared/mcp-resolver.js";
+import { mergeMcpServerUsages } from "./mcp-resolver.js";
 
 // Both harnesses must merge agent + session usages identically (session wins
 // per slug — the usage whose enabled_tools the enforcement honors), so the
 // merge lives in shared/mcp-resolver.ts. Re-exported here for its historical
 // home alongside mergeSkillRefs.
-export { mergeMcpServerUsages } from "../../shared/mcp-resolver.js";
+export { mergeMcpServerUsages } from "./mcp-resolver.js";
 
-/**
- * Path segments that identify runner-internal directories. Any workspace dir
- * whose resolved absolute path contains one of these is rejected.
- */
-const RUNNER_INTERNAL_MARKERS = [
-  "/runtimes/cursor-runner/",
-  "/runtimes/agent-runner/",
-] as const;
+export interface CloudRepo {
+  url: string;
+  startingRef?: string;
+}
 
 export interface ResolvedBlueprint {
   agent: Agent;
@@ -46,7 +40,6 @@ export interface ResolvedBlueprint {
   subAgents: SubAgent[];
   mergedMcpServerUsages: McpServerUsage[];
   mergedSkillRefs: ApiResourceReference[];
-  workspaceDirs: string[];
   cloudRepos: CloudRepo[];
 }
 
@@ -59,7 +52,6 @@ export interface ResolvedBlueprint {
 export async function resolveBlueprint(
   client: StigmerClient,
   session: Session,
-  fallbackWorkspaceDir: string,
 ): Promise<ResolvedBlueprint> {
   const sessionSpec = session.spec!;
 
@@ -78,7 +70,6 @@ export async function resolveBlueprint(
     sessionSpec.skillRefs,
   );
 
-  const workspaceDirs = resolveWorkspaceDirs(sessionSpec, fallbackWorkspaceDir);
   const cloudRepos = resolveCloudRepos(sessionSpec.workspaceEntries);
 
   return {
@@ -90,7 +81,6 @@ export async function resolveBlueprint(
     subAgents: agentSpec.subAgents,
     mergedMcpServerUsages,
     mergedSkillRefs,
-    workspaceDirs,
     cloudRepos,
   };
 }
@@ -151,64 +141,3 @@ export function mergeSkillRefs(
 
   return [...bySlug.values()];
 }
-
-// ---------------------------------------------------------------------------
-// Local workspace resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve workspace directories from session workspace entries.
- *
- * For local path entries: use the local path directly.
- * Falls back to the config's workspaceRootDir when no entries exist.
- *
- * All resolved paths are validated to ensure they do not overlap with
- * the runner's own internal directories. Any path that fails validation
- * is replaced with the fallback directory.
- */
-function resolveWorkspaceDirs(
-  sessionSpec: SessionSpec,
-  fallbackDir: string,
-): string[] {
-  const safeFallback = validateWorkspaceDir(fallbackDir)
-    ? fallbackDir
-    : logAndSkipRunnerDir(fallbackDir, "fallback config");
-
-  if (!sessionSpec.workspaceEntries.length) {
-    return safeFallback ? [safeFallback] : [];
-  }
-
-  const dirs: string[] = [];
-  for (const entry of sessionSpec.workspaceEntries) {
-    if (entry.source?.source.case === "localPath") {
-      const path = entry.source.source.value.path;
-      if (validateWorkspaceDir(path)) {
-        dirs.push(path);
-      } else {
-        logAndSkipRunnerDir(path, "session workspace entry");
-      }
-    }
-  }
-
-  if (dirs.length > 0) {
-    return dirs;
-  }
-
-  return safeFallback ? [safeFallback] : [];
-}
-
-/**
- * Returns true if the directory is safe (not a runner-internal path).
- */
-function validateWorkspaceDir(dir: string): boolean {
-  const absolute = resolve(dir);
-  return !RUNNER_INTERNAL_MARKERS.some((marker) => absolute.includes(marker));
-}
-
-function logAndSkipRunnerDir(dir: string, source: string): undefined {
-  console.warn(
-    `Workspace dir from ${source} ("${dir}") is a runner-internal path — ` +
-    "rejecting to prevent implementation detail leakage.",
-  );
-  return undefined;
-}

package/src/shared/channel-attachment.ts

@@ -164,7 +164,7 @@ export function synthesizeChannelAttachment(
  * aid). Returns "" when nothing survives the filter — the tool alone
  * still serves text sends inside a 24-hour window.
  */
-export function formatChannelTemplatesSection(channels: ChannelMessagingInfo[]): string {
+export function formatChannelTemplatesSection(channels: readonly ChannelMessagingInfo[]): string {
   let withheld = 0;
   let budget = TEMPLATE_SECTION_CAP;
 

package/src/{activities/execute-cursor → shared}/cost-guard.ts

@@ -1,5 +1,9 @@
 /**
- * ExecutionConfig.max_cost_usd enforcement for the Cursor harness.
+ * ExecutionConfig.max_cost_usd enforcement as a hard stop on a harness turn.
+ *
+ * Harness-agnostic: the Cursor activity is today's only caller and the turn
+ * runtime takes it over in S2 M3. The rationale below is Cursor's, and it is
+ * why the module is shaped as a hard stop rather than a middleware.
  *
  * The native harness enforces the cap in middleware (cost-cap.ts): tools are
  * blocked at the threshold and the model gets one final tool-free round to

package/src/{activities/execute-cursor → shared}/env-resolver.ts

@@ -6,7 +6,7 @@
  * (e.g. API keys for HTTP headers, secrets for stdio subprocesses).
  */
 
-import type { StigmerClient } from "../../client/stigmer-client.js";
+import type { StigmerClient } from "../client/stigmer-client.js";
 
 export interface EnvResult {
   envVars: Record<string, string>;

package/src/{activities/execute-cursor → shared}/exact-apply.ts

@@ -57,11 +57,11 @@ import type {
   ToolCall,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
-import { ELISION_MARKER } from "../../shared/status-offload.js";
-import { extractFilePath, extractWriteContent } from "../../shared/file-tools.js";
-import { resolveWorkspacePath } from "../../shared/file-change.js";
-import type { WorkspaceBackend } from "../../shared/workspace/types.js";
-import { utcTimestamp } from "../../shared/status.js";
+import { ELISION_MARKER } from "./status-offload.js";
+import { extractFilePath, extractWriteContent } from "./file-tools.js";
+import { resolveWorkspacePath } from "./file-change.js";
+import type { WorkspaceBackend } from "./workspace/types.js";
+import { utcTimestamp } from "./status.js";
 
 /** Options for {@link applyApprovedWholeFileWrites}. */
 export interface ExactApplyOptions {
@@ -148,7 +148,7 @@ export async function applyApprovedWholeFileWrites(
       tc.error = "";
       applied.add(tc.id);
       console.log(
-        `ExecuteCursor exact-apply: wrote approved bytes to ${target} ` +
+        `[exact-apply] wrote approved bytes to ${target} ` +
           `(tool=${tc.id}); no resource grant issued, so a further change ` +
           `re-gates. execution=${opts.executionId}`,
       );
@@ -247,7 +247,7 @@ function isWithinWorkspace(
 
 function logSkip(executionId: string, tc: ToolCall, reason: string): void {
   console.log(
-    `ExecuteCursor exact-apply skipped (falling back to grant+reinvocation): ` +
+    `[exact-apply] skipped (falling back to grant+reinvocation): ` +
       `tool=${tc.id} reason="${reason}" execution=${executionId}`,
   );
 }

package/src/shared/execution-context.ts

@@ -0,0 +1,45 @@
+/**
+ * The execution-scoped context — "this async work belongs to execution X" —
+ * as an `AsyncLocalStorage` the turn runtime enters once around the WHOLE
+ * activity, and the transport layer reads per request.
+ *
+ * Why it is the runtime's and not a harness's: every proxy-bound request the
+ * runner makes carries `x-stigmer-execution-id` from this store (the Cursor
+ * fetch and HTTP/2 interceptors stamp it; `rejection-capture.ts` correlates
+ * unhandled rejections by it), and a large share of those requests are made
+ * OUTSIDE any engine stretch — attachment downloads and status offload
+ * through the artifact proxy, the memory selection, the structured-output
+ * extraction and the plan-artifact publish in the epilogue, and in a cloud
+ * sandbox the control-plane writes themselves. Under `maxConcurrentActivities
+ * > 1` the fallback (a module-level id, `fetch-interceptor.ts`
+ * `setInterceptorExecutionId`) is whichever turn set it last; this store is
+ * what makes concurrent turns not overwrite each other's headers.
+ *
+ * Moved from `activities/execute-cursor/fetch-interceptor.ts` (S2 M3,
+ * Q-M3-12) so `harness/run-turn.ts` can enter it without importing the
+ * adapter; the interceptors import it from here. No harness enters it: the
+ * contract lists it among the things deliberately NOT on `TurnSink`.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface ExecutionContextStore {
+  readonly executionId: string;
+}
+
+const executionContext = new AsyncLocalStorage<ExecutionContextStore>();
+
+/** The store, for readers that stamp or correlate by execution id. */
+export function getExecutionContext(): AsyncLocalStorage<ExecutionContextStore> {
+  return executionContext;
+}
+
+/**
+ * Run an async function with execution-scoped context. The executionId is
+ * propagated through the async call chain via AsyncLocalStorage, ensuring
+ * concurrent activities on the same runner process don't overwrite each
+ * other's proxy headers.
+ */
+export function runWithExecutionContext<T>(executionId: string, fn: () => Promise<T>): Promise<T> {
+  return executionContext.run({ executionId }, fn);
+}

package/src/{activities/execute-cursor → shared}/extract-structured-output.ts

@@ -1,5 +1,8 @@
 /**
- * Tier-2 structured-output extraction for the Cursor harness.
+ * Tier-2 structured-output extraction for a harness turn.
+ *
+ * Harness-agnostic: the Cursor activity is today's only caller and the turn
+ * runtime takes it over in S2 M3 (the native harness has no tier 2 today).
  *
  * When tier-1 text extraction (shared/extract-json.ts) cannot find JSON in
  * the agent's free-text response, this tier asks an economy-tier LLM to
@@ -13,12 +16,12 @@
  * bundle-slim's deferred evaluation preserves.
  */
 
-import type { Config } from "../../config.js";
-import { getEconomyModel } from "../../shared/model-registry.js";
-import { buildChatModel } from "../../shared/model-client.js";
-import { checkDirectCredentials } from "../../shared/llm-backend.js";
-import { tryInferProvider } from "../../shared/llm-proxy.js";
-import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
+import type { Config } from "../config.js";
+import { getEconomyModel } from "./model-registry.js";
+import { buildChatModel } from "./model-client.js";
+import { checkDirectCredentials } from "./llm-backend.js";
+import { tryInferProvider } from "./llm-proxy.js";
+import { jsonSchemaToZod } from "./json-schema-to-zod.js";
 
 /**
  * Extract structured data from an agent's free-text response using an

package/src/shared/filereview/capture.ts

@@ -95,7 +95,7 @@ import { isSecretLikePath } from "./secret-paths.js";
  * no capture substrate and falls back to the deny-gate: the agent still runs, but
  * file writes gate pre-execution instead of flowing. In the Cursor harness that
  * fallback is also the ONLY branch that arms the resume-time exact-apply guarantee
- * (see execute-cursor/exact-apply.ts); the deep-agent harness re-applies an
+ * (see shared/exact-apply.ts); the deep-agent harness re-applies an
  * approved write via LangGraph checkpoint replay and needs no exact-apply. Keeping
  * this the single, named, truth-table-tested decision pins exactly when the
  * no-storage deny-gate engages in either harness.

package/src/shared/heartbeat.ts

@@ -3,50 +3,36 @@
  *
  * Provides a periodic heartbeat loop that activities can start for
  * long-running operations. The loop sends heartbeat details at a
- * configurable interval and stops when cancelled or when the
- * returned abort function is called.
+ * configurable interval and stops when the returned handle is stopped.
  *
- * Heartbeats serve two purposes:
- * 1. Prevent Temporal from timing out the activity (heartbeatTimeout)
- * 2. Detect parent workflow cancellation (CancelledFailure from heartbeat)
+ * Heartbeats keep Temporal from timing the activity out
+ * (`heartbeatTimeout`) and are how an activity RECEIVES cancellation: the
+ * server piggybacks a cancel request on a heartbeat response, and the SDK
+ * then aborts `Context.current().cancellationSignal`. `Context.heartbeat()`
+ * itself never throws for cancellation (it enqueues to the worker's
+ * heartbeat subject — `@temporalio/activity/lib/index.js`
+ * `Context.heartbeat`, `@temporalio/worker/lib/worker.js` the heartbeat
+ * callback; the SDK's own doc: "Cancellation is not propagated from this
+ * function"). Until S2 M3 this handle carried two flags for a throw that
+ * cannot happen; a turn reads its interruption from the signal's reason
+ * instead (`worker-shutdown.ts` `classifyTurnInterruption`).
  */
 
 import { Context, CancelledFailure } from "@temporalio/activity";
 
 export interface HeartbeatHandle {
   stop(): void;
-  readonly cancelled: boolean;
-  readonly workerShutdown: boolean;
-}
-
-export interface HeartbeatOptions {
-  shutdownSignal?: AbortSignal;
 }
 
 export function startHeartbeat(
   intervalMs: number,
   getDetails?: () => Record<string, unknown>,
-  options?: HeartbeatOptions,
 ): HeartbeatHandle {
   let stopped = false;
-  let wasCancelled = false;
-  let wasWorkerShutdown = false;
 
   const timer = setInterval(() => {
     if (stopped) return;
-    try {
-      Context.current().heartbeat(getDetails?.());
-    } catch (err) {
-      if (err instanceof CancelledFailure) {
-        if (options?.shutdownSignal?.aborted) {
-          wasWorkerShutdown = true;
-        } else {
-          wasCancelled = true;
-        }
-        stopped = true;
-        clearInterval(timer);
-      }
-    }
+    Context.current().heartbeat(getDetails?.());
   }, intervalMs);
 
   return {
@@ -54,12 +40,6 @@ export function startHeartbeat(
       stopped = true;
       clearInterval(timer);
     },
-    get cancelled() {
-      return wasCancelled;
-    },
-    get workerShutdown() {
-      return wasWorkerShutdown;
-    },
   };
 }
 

package/src/{activities/execute-cursor → shared}/persist-decision.ts

@@ -1,5 +1,8 @@
 /**
- * Streaming persist decision for the Cursor harness.
+ * Streaming persist decision for a harness turn.
+ *
+ * Harness-agnostic: the Cursor stream loop is today's only caller, the turn
+ * runtime takes it over in S2 M3, and S3 retires the native twin below.
  *
  * Mirrors the native deep-agent harness (execute-deep-agent/streaming.ts):
  * `shouldPersist = forceFlush || scheduler.shouldSendUpdate(eventCount)`.
@@ -10,7 +13,7 @@
  * exercise the same implementation and cannot drift.
  */
 
-import type { StreamingUpdateScheduler } from "../../shared/streaming-scheduler.js";
+import type { StreamingUpdateScheduler } from "./streaming-scheduler.js";
 
 /**
  * Force-flush signals — discrete, user-visible state changes that must reach the

package/src/{activities/execute-cursor → shared}/skill-resolver.ts

@@ -5,9 +5,17 @@
  * - Mounts each skill via the shared skill-mount mechanics (SKILL.md +
  *   extracted artifact, hash-keyed cache — see shared/skill-mount.ts)
  * - Uses a platform-managed directory outside the workspace
- * - Ensures the workspace `.stigmer` symlink (see stigmer-link.ts)
+ * - Ensures the workspace `.stigmer` symlink (see workspace/stigmer-link.ts)
  * - Returns metadata for prompt injection
  *
+ * A turn-runtime phase (`harness/turn-context.ts` `mountSkills`): it reads
+ * the control plane, which only the runtime holds, and writes under the
+ * platform dir the runtime owns; the harness renders the returned metadata
+ * into its prompt in its own placement. Moved from
+ * `activities/execute-cursor/` at S2 M3b; the native harness's twin
+ * (`skill-writer.ts` `fetchSkillsByRefs` + `mountSkills`) is what S3
+ * reconciles it with.
+ *
  * The mount is cached by the skill's content-addressed version hash
  * (stigmer/stigmer#672): metadata is fetched on every execution (that keeps
  * latest-version freshness), but the artifact download and file rewrite are
@@ -19,17 +27,23 @@
 
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import type { StigmerClient } from "../../client/stigmer-client.js";
+import type { StigmerClient } from "../client/stigmer-client.js";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import type { SkillMetadata } from "./prompt-builder.js";
-import { getPlatformDir } from "../../shared/workspace/platform-dir.js";
+import { getPlatformDir } from "./workspace/platform-dir.js";
 import {
   SKILLS_SUBDIR,
   mountIsFresh,
   downloadArtifact,
   writeSkillMount,
-} from "../../shared/skill-mount.js";
-import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/workspace/stigmer-link.js";
+} from "./skill-mount.js";
+import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
+
+/** One mounted skill as a prompt renders it: its name, its description, and the workspace-relative path of its SKILL.md. */
+export interface SkillMetadata {
+  name: string;
+  description: string;
+  path: string;
+}
 
 export interface SkillResolverOptions {
   sessionId: string;

package/src/shared/subagent-rows.ts

@@ -0,0 +1,39 @@
+/**
+ * Terminal transitions on the sub-agent rows of an execution status,
+ * operating on the proto array itself.
+ *
+ * One function today: marking every non-terminal sub-agent CANCELLED when a
+ * turn ends without them (a pause, a shutdown, a stall, a cost cap, an
+ * infrastructure cancel), so the final snapshot has no permanent IN_PROGRESS
+ * "zombie" delegation. Harness-agnostic (a `SubAgentExecution` is the
+ * platform's row, not an engine's), read by the turn runtime's terminal
+ * table and the Cursor accumulator's own finalize alike.
+ *
+ * Moved from `activities/execute-cursor/message-translator.ts` at S2 M3 so
+ * the runtime's catch can reach it; the body is unchanged.
+ */
+
+import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { SubAgentStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { utcTimestamp } from "./status.js";
+
+/**
+ * Transition any non-terminal sub-agent (IN_PROGRESS or PENDING) in the given
+ * proto array to CANCELLED with a completion timestamp, in place. Returns
+ * true if any sub-agent changed.
+ */
+export function cancelInProgressSubAgentProtos(subAgents: SubAgentExecution[]): boolean {
+  let changed = false;
+  for (const sub of subAgents) {
+    if (
+      sub.status === SubAgentStatus.SUB_AGENT_IN_PROGRESS ||
+      sub.status === SubAgentStatus.SUB_AGENT_PENDING
+    ) {
+      sub.status = SubAgentStatus.SUB_AGENT_CANCELLED;
+      sub.completedAt = utcTimestamp();
+      changed = true;
+    }
+  }
+  return changed;
+}