@stigmer/runner 3.12.4 → 3.12.6

package/src/shared/skill-mount.ts

@@ -0,0 +1,179 @@
+/**
+ * Skill mount mechanics — the ONE cache shape shared by both harnesses.
+ *
+ * A skill "mount" is the on-disk materialization of a skill inside the
+ * session's platform directory: `{platformDir}/skills/{name}/` holding
+ * SKILL.md plus the artifact's supporting files. Both harnesses write to
+ * that same physical location — the Cursor harness directly, the native
+ * (deep-agent) harness through the `.stigmer/` virtual namespace that
+ * LocalWorkspaceBackend routes there — so they MUST share one cache shape
+ * (issues #337/#672). This module owns that shape:
+ *
+ * - The mount is cached by the skill's content-addressed
+ *   `status.version_hash`: metadata is still fetched every execution
+ *   (that keeps latest-version freshness — push a skill update and the
+ *   very next message picks it up), but the artifact download and file
+ *   rewrite are skipped when the mounted content's hash already matches.
+ * - Remounts rebuild the directory from scratch, so files deleted between
+ *   skill versions never linger in the mount.
+ * - Crash-safe by ordering: the marker is stamped LAST, after every file
+ *   of the mount landed — a crash mid-write leaves no marker, so the next
+ *   execution remounts instead of trusting a partial tree.
+ *
+ * Extracted from execute-cursor/skill-resolver.ts (PR #682) when the
+ * deep-agent path adopted the same cache (issue #337). Orchestration —
+ * which skills to mount, prompt metadata, degradation logging — stays
+ * with each harness; only the per-skill-directory mechanics live here.
+ */
+
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { join, dirname, extname, resolve } from "node:path";
+import { ConnectError, Code } from "@connectrpc/connect";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { extractZipFileEntries } from "./zip-extract.js";
+
+/** Subdirectory of the platform dir where skill mounts live. */
+export const SKILLS_SUBDIR = "skills";
+
+/**
+ * Marker recording what a skill's mount directory currently holds. Written
+ * LAST, after every file of the mount landed — a crash mid-write leaves no
+ * marker, so the next execution remounts instead of trusting a partial tree.
+ */
+export const MOUNT_MARKER_FILE = ".stigmer-mount.json";
+
+export interface MountMarker {
+  /** Content-addressed version hash (`Skill.status.version_hash`) of the mounted content. */
+  versionHash: string;
+  /**
+   * Whether the artifact's files are part of the mount. `false` when the
+   * skill has no artifact OR when the download failed and the mount fell
+   * back to SKILL.md only — the latter makes the next execution retry the
+   * download rather than cache the degraded mount.
+   */
+  artifactMounted: boolean;
+}
+
+/**
+ * File extensions written with the executable bit set. The ZIP layer is
+ * deliberately mode-blind (path + bytes only, see zip-extract.ts), so
+ * extension is the only signal available for `./script.sh`-style
+ * invocation to work out of the mount.
+ */
+const SCRIPT_EXTENSIONS = new Set([".sh", ".py", ".js", ".ts", ".rb", ".pl"]);
+
+/**
+ * Whether the mount at `skillDir` already holds this version's content.
+ *
+ * Fresh means: the marker's hash matches AND the mount isn't a degraded
+ * SKILL.md-only fallback when the skill does carry an artifact. Any read or
+ * parse failure counts as stale — the remount is the safe default.
+ */
+export async function mountIsFresh(
+  skillDir: string,
+  versionHash: string,
+  wantsArtifact: boolean,
+): Promise<boolean> {
+  try {
+    const raw = await readFile(join(skillDir, MOUNT_MARKER_FILE), "utf-8");
+    const marker = JSON.parse(raw) as Partial<MountMarker>;
+    return marker.versionHash === versionHash && (marker.artifactMounted === true || !wantsArtifact);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Download a skill artifact's ZIP bytes, transfer lane first (#675).
+ *
+ * The URL lane (getArtifactDownloadUrl → HTTP GET) carries any valid skill
+ * size; the unary getArtifact response is capped by the server's 10MB gRPC
+ * message limit. Servers that predate the lane (and cloud until its sibling
+ * lands) answer the mint with UNIMPLEMENTED — those fall back to the unary
+ * path, which behaves exactly as before for ≤10MB artifacts.
+ *
+ * Runs only on a mount-cache miss (the hash-keyed marker above) — a hit
+ * skips the transfer entirely, whichever lane would have carried it.
+ */
+export async function downloadArtifact(
+  client: StigmerClient,
+  artifactStorageKey: string,
+): Promise<Uint8Array | undefined> {
+  let minted;
+  try {
+    minted = await client.getSkillArtifactDownloadUrl(artifactStorageKey);
+  } catch (err) {
+    if (err instanceof ConnectError && err.code === Code.Unimplemented) {
+      const resp = await client.getSkillArtifact(artifactStorageKey);
+      return resp.artifact && resp.artifact.length > 0 ? resp.artifact : undefined;
+    }
+    throw err;
+  }
+
+  const resp = await fetch(minted.url);
+  if (!resp.ok) {
+    throw new Error(`artifact fetch failed: HTTP ${resp.status} from ${minted.url}`);
+  }
+  const bytes = new Uint8Array(await resp.arrayBuffer());
+  if (minted.sizeBytes > 0n && BigInt(bytes.length) !== minted.sizeBytes) {
+    throw new Error(
+      `artifact fetch truncated: got ${bytes.length} bytes, expected ${minted.sizeBytes}`,
+    );
+  }
+  return bytes.length > 0 ? bytes : undefined;
+}
+
+/**
+ * (Re)write a skill's mount directory from scratch.
+ *
+ * The directory is removed first so files deleted between versions don't
+ * linger in the mount, then SKILL.md and the artifact files are written, and
+ * the marker is stamped LAST (see MOUNT_MARKER_FILE for the crash-safety
+ * contract). SKILL.md always comes from `spec.skillMd` — the server's
+ * authoritative copy, which the push pipeline guarantees is non-empty
+ * (push.go hard-fails a ZIP without an extractable SKILL.md) — never from
+ * the zip; both the zip's SKILL.md and any stray marker-named entry are
+ * excluded from extraction so the mount's ownership of those two files is
+ * unconditional.
+ *
+ * Every extracted entry must resolve inside `skillDir`. The server already
+ * rejects traversal at push (google/safearchive), but this runner-side
+ * check is kept as defense-in-depth: it is the guard the deep-agent path
+ * used to get from LocalWorkspaceBackend's platform-path routing, preserved
+ * here when skill writes moved to direct fs.
+ */
+export async function writeSkillMount(
+  skill: Skill,
+  skillDir: string,
+  artifactBytes: Uint8Array | undefined,
+): Promise<void> {
+  await rm(skillDir, { recursive: true, force: true });
+  await mkdir(skillDir, { recursive: true });
+
+  await writeFile(join(skillDir, "SKILL.md"), skill.spec!.skillMd, "utf-8");
+
+  const artifactMounted = artifactBytes !== undefined && artifactBytes.length > 0;
+  if (artifactMounted) {
+    const normalizedSkillDir = resolve(skillDir);
+    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md", MOUNT_MARKER_FILE] });
+    for (const entry of entries) {
+      const filePath = resolve(normalizedSkillDir, entry.path);
+      if (filePath !== normalizedSkillDir && !filePath.startsWith(normalizedSkillDir + "/")) {
+        throw new Error(
+          `skill artifact entry escapes its mount directory: '${entry.path}'`,
+        );
+      }
+      await mkdir(dirname(filePath), { recursive: true });
+      await writeFile(filePath, entry.content, {
+        mode: SCRIPT_EXTENSIONS.has(extname(entry.path)) ? 0o755 : 0o644,
+      });
+    }
+  }
+
+  const versionHash = skill.status?.versionHash ?? "";
+  if (versionHash !== "") {
+    const marker: MountMarker = { versionHash, artifactMounted };
+    await writeFile(join(skillDir, MOUNT_MARKER_FILE), JSON.stringify(marker), "utf-8");
+  }
+}

package/src/shared/skill-writer.ts

@@ -1,5 +1,5 @@
 /**
- * Skill writing and prompt generation for the deep-agent execution path.
+ * Skill mounting and prompt generation for the deep-agent execution path.
  *
  * Follows the Agent Skills specification progressive disclosure model:
  *
@@ -10,19 +10,33 @@
  * 3. Resources (on demand) — scripts, references, and assets are
  *    loaded by the agent only when required.
  *
- * Skills live under `.stigmer/skills/{name}/` relative to the workspace root.
- * Returned paths are workspace-relative so that the agent's sandbox backend
- * resolves them correctly regardless of mount strategy.
+ * Skills physically live in the session's platform directory
+ * (`{platformDir}/skills/{name}/` — the SAME location the Cursor harness
+ * mounts into), and the agent sees them as `.stigmer/skills/{name}/`
+ * through the per-turn workspace symlink (see workspace/stigmer-link.ts).
+ * Returned paths are the agent-visible `.stigmer/…` form.
+ *
+ * Mounts are cached by the skill's content-addressed version hash via the
+ * shared skill-mount mechanics (issue #337, mirroring the Cursor harness's
+ * #672 fix): metadata is fetched every execution — a pushed skill update
+ * still lands on the very next message — but an unchanged skill skips the
+ * artifact download and rewrite entirely.
  */
 
-import type { WorkspaceBackend } from "./workspace/types.js";
+import { join } from "node:path";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
-import { extractZipFileEntries } from "./zip-extract.js";
+import {
+  SKILLS_SUBDIR,
+  mountIsFresh,
+  downloadArtifact,
+  writeSkillMount,
+} from "./skill-mount.js";
+import { STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
 
-const SKILLS_RELATIVE_BASE = ".stigmer/skills";
-const SCRIPT_EXTENSIONS = new Set([".sh", ".py", ".js", ".ts", ".rb", ".pl"]);
+/** Agent-visible base of the skills tree (via the workspace `.stigmer` symlink). */
+const SKILLS_RELATIVE_BASE = `${STIGMER_LOCAL_STATE_DIR}/${SKILLS_SUBDIR}`;
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -81,114 +95,100 @@ export async function fetchSkillsByRefs(
   return results;
 }
 
-// ─── Write ───────────────────────────────────────────────────────────────
+// ─── Mount ───────────────────────────────────────────────────────────────
 
 /**
- * Write skill artifacts to the workspace. Returns a map of
- * skill-id -> workspace-relative directory path.
+ * Mount skills into the session's platform directory, downloading each
+ * skill's artifact only on a version-hash cache miss (see skill-mount.ts
+ * for the marker mechanics). Returns a map of skill-id -> agent-visible
+ * directory path.
+ *
+ * The returned map is a NAMING function, not a success record: every skill
+ * gets its path entry so prompt generation stays total, while mount
+ * failures degrade that one skill (loud log, no throw) — one broken skill
+ * must never kill the run.
  *
- * For each skill:
- * - If a ZIP artifact is available, extract it to .stigmer/skills/{name}/
- * - Otherwise, write just the SKILL.md from the spec
- * - Make scripts executable
+ * Skills mount in parallel (each owns an independent directory), EXCEPT
+ * when two skills resolve to the same directory name (same `spec.name`
+ * from different orgs): concurrent remove-and-rewrite passes on one
+ * directory would corrupt the mount, so only the first claimant mounts and
+ * the collision is logged loudly. (The sequential code this replaced
+ * silently let the last writer win — no better, just quieter.)
  */
-export async function writeSkills(
+export async function mountSkills(
+  client: StigmerClient,
   skills: readonly Skill[],
-  workspaceBackend: WorkspaceBackend,
-  artifacts: ReadonlyMap<string, Uint8Array>,
+  platformDir: string,
 ): Promise<SkillPathMap> {
   const paths = new Map<string, string>();
+  const claims = new Map<string, Skill>();
 
   for (const skill of skills) {
     const name = skill.spec?.name || skill.metadata?.slug || "unknown";
     const skillId = skill.metadata?.id ?? name;
-    const relativeDir = `${SKILLS_RELATIVE_BASE}/${name}`;
-    paths.set(skillId, relativeDir);
+    paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
 
-    const artifactBytes = artifacts.get(skillId);
-    if (skill.spec?.skillMd) {
-      const skillMdPath = `${relativeDir}/SKILL.md`;
-      await workspaceBackend.writeFile(skillMdPath, skill.spec.skillMd);
-      if (artifactBytes && artifactBytes.length > 0) {
-        await extractZipToWorkspaceExcluding(artifactBytes, "SKILL.md", relativeDir, workspaceBackend);
-      }
-    } else if (artifactBytes && artifactBytes.length > 0) {
-      await extractZipToWorkspace(artifactBytes, relativeDir, workspaceBackend);
+    // Impossible through the push pipeline (push.go hard-fails a ZIP
+    // without an extractable SKILL.md and always populates spec.skill_md),
+    // so an empty skillMd means a broken resource — skip, same as Cursor.
+    if (!skill.spec?.skillMd) {
+      console.warn(
+        `[skill-writer] skill ${name} (${skillId}) has no skillMd content — skipping mount`,
+      );
+      continue;
     }
 
-    await makeScriptsExecutable(relativeDir, workspaceBackend);
-  }
-
-  return { paths };
-}
-
-/**
- * Compute skill paths without writing anything (for resume integrity checks).
- */
-export function computeSkillPaths(skills: readonly Skill[]): Map<string, string> {
-  const paths = new Map<string, string>();
-  for (const skill of skills) {
-    const name = skill.spec?.name || skill.metadata?.slug || "unknown";
-    const skillId = skill.metadata?.id ?? name;
-    paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
+    const prev = claims.get(name);
+    if (prev) {
+      console.warn(
+        `[skill-writer] mount directory collision on '${name}': ` +
+        `${prev.metadata?.org}/${prev.metadata?.slug} already claims it, ` +
+        `skipping ${skill.metadata?.org}/${skill.metadata?.slug}`,
+      );
+      continue;
+    }
+    claims.set(name, skill);
   }
-  return paths;
-}
-
-/**
- * Check workspace integrity for resume fast-path.
- * Returns true if the sentinel SKILL.md file exists for the first skill.
- */
-export async function checkSkillIntegrity(
-  skills: readonly Skill[],
-  workspaceBackend: WorkspaceBackend,
-): Promise<boolean> {
-  if (skills.length === 0) return true;
-
-  const paths = computeSkillPaths(skills);
-  const firstPath = paths.values().next().value;
-  if (!firstPath) return true;
 
-  const sentinel = `${firstPath}/SKILL.md`;
-  return workspaceBackend.exists(sentinel);
-}
+  await Promise.all([...claims.entries()].map(async ([name, skill]) => {
+    const skillDir = join(platformDir, SKILLS_SUBDIR, name);
+    try {
+      const versionHash = skill.status?.versionHash ?? "";
+      const wantsArtifact = Boolean(skill.status?.artifactStorageKey);
 
-// ─── ZIP extraction ──────────────────────────────────────────────────────
+      if (versionHash !== "" && (await mountIsFresh(skillDir, versionHash, wantsArtifact))) {
+        console.log(
+          `[skill-writer] mount cache hit: ${name} (version ${versionHash.slice(0, 12)}) — skipping artifact transfer`,
+        );
+        return;
+      }
 
-async function extractZipToWorkspace(
-  zipBytes: Uint8Array,
-  targetDir: string,
-  backend: WorkspaceBackend,
-): Promise<void> {
-  const entries = await extractZipFileEntries(zipBytes);
-  for (const entry of entries) {
-    await backend.writeFileBuffer(`${targetDir}/${entry.path}`, Buffer.from(entry.content));
-  }
-}
+      let artifactBytes: Uint8Array | undefined;
+      if (wantsArtifact) {
+        try {
+          artifactBytes = await downloadArtifact(client, skill.status!.artifactStorageKey);
+        } catch (err) {
+          // Deliberate degradation, but LOUD (#675): the run still gets
+          // SKILL.md, and the marker records artifactMounted=false so the
+          // next execution retries the download.
+          console.error(
+            `[skill-writer] artifact download FAILED for ${name} ` +
+            `(key=${skill.status!.artifactStorageKey}) — mounting SKILL.md WITHOUT the skill's ` +
+            `supporting files (scripts/references will be missing): ${err instanceof Error ? err.message : err}`,
+          );
+        }
+      }
 
-async function extractZipToWorkspaceExcluding(
-  zipBytes: Uint8Array,
-  excludeName: string,
-  targetDir: string,
-  backend: WorkspaceBackend,
-): Promise<void> {
-  const entries = await extractZipFileEntries(zipBytes, { exclude: [excludeName] });
-  for (const entry of entries) {
-    await backend.writeFileBuffer(`${targetDir}/${entry.path}`, Buffer.from(entry.content));
-  }
-}
+      await writeSkillMount(skill, skillDir, artifactBytes);
+      console.log(`[skill-writer] wrote skill mount: ${name}`);
+    } catch (err) {
+      console.warn(
+        `[skill-writer] failed to mount skill ${name}: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }));
 
-async function makeScriptsExecutable(
-  relativeDir: string,
-  backend: WorkspaceBackend,
-): Promise<void> {
-  const extensions = [...SCRIPT_EXTENSIONS].map(ext => `-name '*${ext}'`).join(" -o ");
-  const cmd = `find ${relativeDir} -type f \\( ${extensions} \\) -exec chmod +x {} \\; 2>/dev/null || true`;
-  try {
-    await backend.execute(cmd);
-  } catch {
-    // Non-fatal: scripts may not be executable in all environments
-  }
+  return { paths };
 }
 
 // ─── Prompt generation ───────────────────────────────────────────────────
@@ -264,37 +264,3 @@ export function generateAlsoAvailableSection(
     "read its SKILL.md at `.stigmer/skills/<name>/SKILL.md` to activate it.\n"
   );
 }
-
-// ─── Artifact fetching ───────────────────────────────────────────────────
-
-/**
- * Download skill artifacts for all skills that have a storage key.
- * Returns a map from skill ID to artifact bytes.
- */
-export async function fetchSkillArtifacts(
-  client: StigmerClient,
-  skills: readonly Skill[],
-): Promise<Map<string, Uint8Array>> {
-  const artifacts = new Map<string, Uint8Array>();
-
-  const fetches = skills
-    .filter(s => s.status?.artifactStorageKey)
-    .map(async (skill) => {
-      const key = skill.status!.artifactStorageKey;
-      const skillId = skill.metadata?.id ?? skill.spec?.name ?? "unknown";
-      try {
-        const response = await client.getSkillArtifact(key);
-        if (response.artifact && response.artifact.length > 0) {
-          artifacts.set(skillId, response.artifact);
-        }
-      } catch (err) {
-        console.warn(
-          `[skill-writer] Failed to download artifact for ${skill.spec?.name}: ` +
-          `${err instanceof Error ? err.message : String(err)}. Falling back to SKILL.md only.`,
-        );
-      }
-    });
-
-  await Promise.all(fetches);
-  return artifacts;
-}

package/src/shared/thinking-mode.ts

@@ -0,0 +1,52 @@
+/**
+ * Harness-neutral thinking-mode semantics (stigmer/stigmer#772) — the
+ * second variant dimension alongside `shared/service-tier.ts`.
+ *
+ * The platform contract mirrors the service tier's: the thinking pin is
+ * ALWAYS explicit by the time a provider request leaves the runner.
+ * UNSPECIFIED resolves to DISABLED here and ONLY here — every upstream
+ * layer preserves the caller's raw enum so "user chose disabled" stays
+ * distinguishable from "platform default" all the way to the ledger.
+ *
+ * Unlike the fast tier, thinking is NOT separately priced: Cursor bills
+ * thinking variants at base per-token rates (ledger-verified 2026-08-15 —
+ * 277 events at exactly base; thinking+fast at exactly the fast rate).
+ * The cost of ENABLED is the extra reasoning tokens, billed as output.
+ * Selection is therefore capability-gated (registry capabilities.thinking)
+ * rather than pricing-gated, and the estimate/billing paths need no
+ * thinking-specific rates.
+ *
+ * v1 translates thinking on the Cursor harness only (the explicit
+ * `thinking` variant parameter, `execute-cursor/service-tier.ts`). No
+ * native wire mapping exists yet — create-time validation refuses ENABLED
+ * for native-harness models, mirroring the tier's #361 posture.
+ */
+
+import { ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/**
+ * The effective mode after platform-default resolution: never UNSPECIFIED.
+ */
+export type EffectiveThinkingMode = ThinkingMode.DISABLED | ThinkingMode.ENABLED;
+
+/**
+ * Resolve the configured mode to its effective value. The single place in
+ * the platform where UNSPECIFIED becomes DISABLED.
+ */
+export function resolveEffectiveThinkingMode(
+  configured: ThinkingMode | undefined,
+): EffectiveThinkingMode {
+  return configured === ThinkingMode.ENABLED ? ThinkingMode.ENABLED : ThinkingMode.DISABLED;
+}
+
+/** Human-readable mode label for logs and error messages. */
+export function thinkingModeLabel(mode: ThinkingMode): string {
+  switch (mode) {
+    case ThinkingMode.ENABLED:
+      return "enabled";
+    case ThinkingMode.DISABLED:
+      return "disabled";
+    default:
+      return "unspecified";
+  }
+}

package/src/shared/worker-shutdown.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-task-queue worker-shutdown signals — the classification channel that
+ * lets an in-flight activity distinguish "my worker is shutting down" from
+ * "the orchestrator cancelled me" (a user pause).
+ *
+ * The signal carries NO lifecycle authority: aborting it never stops a
+ * worker or an activity (Temporal's own drain does that). It exists purely
+ * so the activity's cancellation handling can classify the interruption
+ * honestly — a shutdown is not a pause, and must surface as the
+ * worker-shutdown failure shape the control planes recognize (issue #776).
+ *
+ * Ownership contract:
+ *   - whoever creates a Worker registers a signal for its queue BEFORE the
+ *     worker starts polling;
+ *   - whoever initiates a full shutdown (SIGTERM handler, desktop quit)
+ *     aborts the signal BEFORE calling worker.shutdown(), so activities
+ *     cancelled by the drain observe it already aborted;
+ *   - a graceful single-worker teardown (view close, deferred teardown in
+ *     the runner-manager) must NOT abort — those paths only run once no
+ *     activity is in flight, and aborting earlier is exactly the regression
+ *     that killed running activities on a view close.
+ *
+ * Module-level (not per-manager) because activities resolve their signal by
+ * task-queue name via {@link getShutdownSignalForQueue} without a handle to
+ * the runner/manager instance that created their worker.
+ */
+
+const registry = new Map<string, AbortController>();
+
+/**
+ * Register a fresh shutdown signal for a task queue, replacing any previous
+ * registration (a re-created worker on a reused queue must not observe the
+ * old worker's aborted signal). Returns the controller so the worker's owner
+ * can abort it at shutdown.
+ */
+export function registerWorkerShutdownSignal(taskQueue: string): AbortController {
+  const controller = new AbortController();
+  registry.set(taskQueue, controller);
+  return controller;
+}
+
+/** The signal an activity on `taskQueue` should observe, if one is registered. */
+export function getShutdownSignalForQueue(taskQueue: string): AbortSignal | undefined {
+  return registry.get(taskQueue)?.signal;
+}
+
+/**
+ * Abort the queue's signal, marking any in-flight activity's imminent
+ * cancellation as a worker shutdown. Idempotent; no-op for an unknown queue.
+ */
+export function signalWorkerShutdown(taskQueue: string): void {
+  registry.get(taskQueue)?.abort();
+}
+
+/** Drop the registration once the queue's worker is fully torn down. */
+export function unregisterWorkerShutdownSignal(taskQueue: string): void {
+  registry.delete(taskQueue);
+}
+
+/** The evidence a turn's post-stream classification weighs (see below). */
+export interface TurnInterruptionEvidence {
+  /** The periodic heartbeat threw CancelledFailure with no shutdown signal. */
+  heartbeatCancelled: boolean;
+  /** The periodic heartbeat threw CancelledFailure with the signal aborted. */
+  heartbeatWorkerShutdown: boolean;
+  /** Temporal delivered cancellation to the activity. */
+  cancellationSignalAborted: boolean;
+  /** This queue's worker-shutdown signal is aborted. */
+  shutdownSignalAborted: boolean;
+}
+
+/**
+ * Classify how (whether) a turn's stream was interrupted, from the evidence
+ * available after the stream ends. Pure so the decision table is directly
+ * testable — the activities feed it their heartbeat flags and signals.
+ *
+ * The load-bearing rule is the grace-window guard (#776): an aborted
+ * shutdown signal ALONE is "none", because a run that completes normally
+ * inside the drain grace window reaches the classification with the signal
+ * already aborted and nothing actually interrupted. Shutdown requires
+ * interruption evidence (a heartbeat CancelledFailure or a delivered
+ * cancellation) alongside the signal; a heartbeat cancellation with no
+ * shutdown signal is the orchestrator's pause.
+ */
+export function classifyTurnInterruption(
+  evidence: TurnInterruptionEvidence,
+): "worker-shutdown" | "pause" | "none" {
+  const interrupted =
+    evidence.heartbeatCancelled ||
+    evidence.heartbeatWorkerShutdown ||
+    evidence.cancellationSignalAborted;
+  if (!interrupted) {
+    return "none";
+  }
+  if (evidence.heartbeatWorkerShutdown || evidence.shutdownSignalAborted) {
+    return "worker-shutdown";
+  }
+  return evidence.heartbeatCancelled ? "pause" : "none";
+}

package/src/shared/workspace/types.ts

@@ -49,8 +49,9 @@ export class WorkspaceProvisionError extends Error {
 /**
  * Abstraction for executing commands inside a workspace.
  *
- * In local mode, commands run via child_process. In cloud mode (Phase 3),
- * commands route through the Daytona sandbox proxy.
+ * Commands run via child_process in both modes: in cloud mode the runner
+ * itself lives inside the sandbox, so "local" execution is already
+ * sandbox-scoped there.
  *
  * When `platformDir` is set, paths under `.stigmer/` are transparently
  * routed to the platform directory instead of the workspace root, keeping