@stigmer/runner 3.12.0 → 3.12.2

package/src/activities/execute-cursor/__tests__/skill-resolver.test.ts

@@ -1,8 +1,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { mkdtempSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { resolveSkills } from "../skill-resolver.js";
+import { buildZip } from "../../../__test-utils__/zip-fixtures.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
@@ -10,52 +11,13 @@ function makeTempDir(prefix: string): string {
   return mkdtempSync(join(tmpdir(), prefix));
 }
 
-/**
- * Build a minimal stored (method 0) ZIP archive for testing.
- */
-function buildStoredZip(files: { name: string; content: string }[]): Uint8Array {
-  const parts: Uint8Array[] = [];
-
-  for (const file of files) {
-    const nameBytes = new TextEncoder().encode(file.name);
-    const contentBytes = new TextEncoder().encode(file.content);
-    const isDir = file.name.endsWith("/");
-
-    const header = new ArrayBuffer(30);
-    const view = new DataView(header);
-    view.setUint32(0, 0x04034b50, true);
-    view.setUint16(4, 20, true);
-    view.setUint16(6, 0, true);
-    view.setUint16(8, 0, true);
-    view.setUint16(10, 0, true);
-    view.setUint16(12, 0, true);
-    view.setUint32(14, 0, true);
-    view.setUint32(18, isDir ? 0 : contentBytes.length, true);
-    view.setUint32(22, isDir ? 0 : contentBytes.length, true);
-    view.setUint16(26, nameBytes.length, true);
-    view.setUint16(28, 0, true);
-
-    parts.push(new Uint8Array(header));
-    parts.push(nameBytes);
-    if (!isDir) parts.push(contentBytes);
-  }
-
-  const totalLength = parts.reduce((sum, p) => sum + p.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const part of parts) {
-    result.set(part, offset);
-    offset += part.length;
-  }
-  return result;
-}
-
 function makeSkillProto(overrides: {
   name?: string;
   slug?: string;
   description?: string;
   skillMd?: string;
   artifactStorageKey?: string;
+  versionHash?: string;
 } = {}) {
   return {
     metadata: {
@@ -70,7 +32,7 @@ function makeSkillProto(overrides: {
     },
     status: {
       artifactStorageKey: overrides.artifactStorageKey ?? "",
-      versionHash: "abc",
+      versionHash: overrides.versionHash ?? "abc",
     },
   } as any;
 }
@@ -114,12 +76,14 @@ describe("resolveSkills — artifact extraction", () => {
       ...clientOverrides,
     } as any;
 
+    // Re-run resolution for the same session — the mount-cache tests model
+    // one session's successive executions, which share the platform dir.
+    const resolveAgain = () =>
+      resolveSkills(client, refs, { sessionId, primaryWorkspaceDir: workspaceDir });
+
     try {
-      const result = await resolveSkills(client, refs, {
-        sessionId,
-        primaryWorkspaceDir: workspaceDir,
-      });
-      return { result, platformDir, client };
+      const result = await resolveAgain();
+      return { result, platformDir, client, resolveAgain };
     } catch (err) {
       // Clean up on failure
       rmSync(platformDir, { recursive: true, force: true });
@@ -141,7 +105,7 @@ describe("resolveSkills — artifact extraction", () => {
     const skillMd = "# Garden Design Makeover\n\nSee [references/database-schema.md](references/database-schema.md)";
     const schemaContent = "# Database Schema\n\nTable definitions here.";
 
-    const artifact = buildStoredZip([
+    const artifact = buildZip([
       { name: "SKILL.md", content: skillMd },
       { name: "references/", content: "" },
       { name: "references/database-schema.md", content: schemaContent },
@@ -228,11 +192,164 @@ describe("resolveSkills — artifact extraction", () => {
     }
   });
 
+  it("re-resolving an unchanged version skips the artifact download (mount cache hit)", async () => {
+    const artifact = buildZip([
+      { name: "SKILL.md", content: "# Cached" },
+      { name: "references/guide.md", content: "guide" },
+    ]);
+    const getSkillByReference = vi.fn().mockResolvedValue(
+      makeSkillProto({
+        name: "cached-skill",
+        slug: "cached-skill",
+        skillMd: "# Cached",
+        artifactStorageKey: "artifacts/cached.zip",
+        versionHash: "hash-v1",
+      }),
+    );
+    const getSkillArtifact = vi.fn().mockResolvedValue({ artifact });
+
+    const { result, platformDir, client, resolveAgain } = await resolveWithMockClient(
+      [makeRef("cached-skill")],
+      { getSkillByReference, getSkillArtifact },
+    );
+
+    try {
+      expect(result).toHaveLength(1);
+      expect(client.getSkillArtifact).toHaveBeenCalledTimes(1);
+
+      const second = await resolveAgain();
+      expect(second).toHaveLength(1);
+      expect(second[0].name).toBe("cached-skill");
+      // Metadata was re-fetched (latest-version freshness)...
+      expect(client.getSkillByReference).toHaveBeenCalledTimes(2);
+      // ...but the artifact transfer and rewrite were skipped.
+      expect(client.getSkillArtifact).toHaveBeenCalledTimes(1);
+
+      const skillDir = join(platformDir, "skills", "cached-skill");
+      expect(readFileSync(join(skillDir, "references", "guide.md"), "utf-8")).toBe("guide");
+    } finally {
+      cleanupPlatformDir(platformDir);
+    }
+  });
+
+  it("re-downloads on version change and clears stale files from the old mount", async () => {
+    const v1 = makeSkillProto({
+      name: "evolving-skill",
+      slug: "evolving-skill",
+      skillMd: "# V1",
+      artifactStorageKey: "artifacts/v1.zip",
+      versionHash: "hash-v1",
+    });
+    const v2 = makeSkillProto({
+      name: "evolving-skill",
+      slug: "evolving-skill",
+      skillMd: "# V2",
+      artifactStorageKey: "artifacts/v2.zip",
+      versionHash: "hash-v2",
+    });
+    const artifactV1 = buildZip([{ name: "references/removed-in-v2.md", content: "old" }]);
+    const artifactV2 = buildZip([{ name: "references/new-in-v2.md", content: "new" }]);
+
+    const getSkillByReference = vi.fn().mockResolvedValueOnce(v1).mockResolvedValueOnce(v2);
+    const getSkillArtifact = vi
+      .fn()
+      .mockResolvedValueOnce({ artifact: artifactV1 })
+      .mockResolvedValueOnce({ artifact: artifactV2 });
+
+    const { platformDir, client, resolveAgain } = await resolveWithMockClient(
+      [makeRef("evolving-skill")],
+      { getSkillByReference, getSkillArtifact },
+    );
+
+    try {
+      const skillDir = join(platformDir, "skills", "evolving-skill");
+      expect(readFileSync(join(skillDir, "references", "removed-in-v2.md"), "utf-8")).toBe("old");
+
+      await resolveAgain();
+      expect(client.getSkillArtifact).toHaveBeenCalledTimes(2);
+      expect(readFileSync(join(skillDir, "SKILL.md"), "utf-8")).toBe("# V2");
+      expect(readFileSync(join(skillDir, "references", "new-in-v2.md"), "utf-8")).toBe("new");
+      // The v1-only file must not linger in the v2 mount (the stale-file leak).
+      expect(existsSync(join(skillDir, "references", "removed-in-v2.md"))).toBe(false);
+    } finally {
+      cleanupPlatformDir(platformDir);
+    }
+  });
+
+  it("does not cache a SKILL.md-only fallback — the next execution retries the download", async () => {
+    const proto = makeSkillProto({
+      name: "retry-skill",
+      slug: "retry-skill",
+      skillMd: "# Retry",
+      artifactStorageKey: "artifacts/retry.zip",
+      versionHash: "hash-v1",
+    });
+    const artifact = buildZip([{ name: "references/late.md", content: "finally" }]);
+    const getSkillByReference = vi.fn().mockResolvedValue(proto);
+    const getSkillArtifact = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("Network timeout"))
+      .mockResolvedValueOnce({ artifact });
+
+    const { result, platformDir, client, resolveAgain } = await resolveWithMockClient(
+      [makeRef("retry-skill")],
+      { getSkillByReference, getSkillArtifact },
+    );
+
+    try {
+      // First pass degraded to SKILL.md only.
+      expect(result).toHaveLength(1);
+      const skillDir = join(platformDir, "skills", "retry-skill");
+      expect(existsSync(join(skillDir, "references"))).toBe(false);
+
+      // Second pass retries and completes the mount.
+      await resolveAgain();
+      expect(client.getSkillArtifact).toHaveBeenCalledTimes(2);
+      expect(readFileSync(join(skillDir, "references", "late.md"), "utf-8")).toBe("finally");
+
+      // Third pass is a cache hit.
+      await resolveAgain();
+      expect(client.getSkillArtifact).toHaveBeenCalledTimes(2);
+    } finally {
+      cleanupPlatformDir(platformDir);
+    }
+  });
+
+  it("treats a corrupted mount marker as stale and remounts", async () => {
+    const artifact = buildZip([{ name: "references/guide.md", content: "guide" }]);
+    const getSkillByReference = vi.fn().mockResolvedValue(
+      makeSkillProto({
+        name: "tampered-skill",
+        slug: "tampered-skill",
+        skillMd: "# Tampered",
+        artifactStorageKey: "artifacts/tampered.zip",
+        versionHash: "hash-v1",
+      }),
+    );
+    const getSkillArtifact = vi.fn().mockResolvedValue({ artifact });
+
+    const { platformDir, client, resolveAgain } = await resolveWithMockClient(
+      [makeRef("tampered-skill")],
+      { getSkillByReference, getSkillArtifact },
+    );
+
+    try {
+      const skillDir = join(platformDir, "skills", "tampered-skill");
+      writeFileSync(join(skillDir, ".stigmer-mount.json"), "not json {");
+
+      await resolveAgain();
+      expect(client.getSkillArtifact).toHaveBeenCalledTimes(2);
+      expect(readFileSync(join(skillDir, "references", "guide.md"), "utf-8")).toBe("guide");
+    } finally {
+      cleanupPlatformDir(platformDir);
+    }
+  });
+
   it("SKILL.md from spec takes precedence over ZIP copy", async () => {
     const specContent = "# Authoritative SKILL.md from spec";
     const zipContent = "# Stale SKILL.md from ZIP";
 
-    const artifact = buildStoredZip([
+    const artifact = buildZip([
       { name: "SKILL.md", content: zipContent },
       { name: "references/data.md", content: "data" },
     ]);

package/src/activities/execute-cursor/capture-flow.ts

@@ -112,10 +112,11 @@ export function captureBaselineToLedger(opts: {
  * bytes withheld from durable storage.
  *
  * `deniedTokens` are the identities the hook gated this turn (shell/MCP, or a
- * gitignored delete). A streamed file-edit row whose identity is in that set is
- * left for the deny-gate reconcile path — it did NOT flow. A flowed gitignored
- * write is NOT in that set (the hook allowed it), so it is stamped like any
- * other flowed edit and its captured delta surfaces as a CAS entry in the set.
+ * secret-like delete — non-secret CAS deletes flow since issue #303). A streamed
+ * file-edit row whose identity is in that set is left for the deny-gate
+ * reconcile path — it did NOT flow. A flowed gitignored write or delete is NOT
+ * in that set (the hook allowed it), so it is stamped like any other flowed
+ * edit and its captured delta surfaces as a CAS entry in the set.
  *
  * `hitlDir`/`storage` are omitted only by callers with no artifact storage
  * (captureIgnored off); the CAS half is then skipped and this is a git-only

package/src/activities/execute-cursor/cas-observations.ts

@@ -1,5 +1,6 @@
 /**
- * The Cursor harness's disk-backed observer for gitignored file writes — the
+ * The Cursor harness's disk-backed observer for CAS-owned file mutations —
+ * gitignored / non-git writes, and (issue #303) pre-delete byte capture — the
  * out-of-process analog of the deep-agent `CasCaptureFilesystemBackend`
  * ({@link ../execute-deep-agent/cas-capture-backend.js}).
  *
@@ -185,14 +186,19 @@ export function buildSecretClassifyScript(): string {
 
 /**
  * Build the standalone Node.js script the hook runs to observe a single
- * gitignored write — the disk-backed mirror of `CasCaptureFilesystemBackend`'s
- * `recordBefore` plus the DD-E secret gate.
+ * CAS-owned mutation — the disk-backed mirror of `CasCaptureFilesystemBackend`'s
+ * `recordBefore` plus the DD-E secret gate. Staging is mutation-agnostic: it
+ * records the PRE-mutation bytes, so the hook runs it for a write/edit and —
+ * issue #303 — for a delete (whose before-bytes exist only until the tool runs;
+ * the boundary later reads after=null and authors the DELETE). The hook's
+ * delete arm pre-classifies secrets and never invokes this for a secret-like
+ * delete (a gated delete must not leave a "secret" marker in the sidecar).
  *
  * Invoked as `printf %s "$SALIENT" | node -e '<this>' <workspaceRoot> <obsDir>`
  * — the (arbitrary) salient path arrives on stdin so no argv escaping is needed;
  * the two absolute paths ride argv. Prints one token on stdout for the hook:
  *  - `captured` — non-secret: staged the pre-turn bytes (first-touch-wins), the
- *    hook then ALLOWS the write to flow;
+ *    hook then ALLOWS the mutation to flow;
  *  - `secret`   — secret-like: recorded a content-less marker, the hook then
  *    DENIES with the security message (nothing is written);
  *  - `error`    — the path escaped the workspace or a filesystem error occurred,

package/src/activities/execute-cursor/hook-script.ts

@@ -574,9 +574,8 @@ if echo "$STATE" | grep -q '"captureIgnored":true'; then
 fi
 # gitWorkspace selects the capture substrate (Slice 2c). Default true when the
 # key is absent (older state files). When false the workspace is NOT a git tree:
-# there is no git snapshot, so EVERY file write is CAS-staged below (not only
-# gitignored ones), the git-tracked flow arm is skipped, and a delete stays gated
-# (no CAS delete-capture path, parity with the deep-agent).
+# there is no git snapshot, so EVERY file write/delete is CAS-staged below (not
+# only gitignored ones) and the git-tracked flow arm is skipped.
 GIT_WORKSPACE=true
 if echo "$STATE" | grep -q '"gitWorkspace":false'; then
   GIT_WORKSPACE=false
@@ -597,9 +596,10 @@ fi
 # secret-like one must be hard-blocked in every mode. WHICH writes are CAS-owned
 # depends on the substrate: in a git tree it is only the GITIGNORED writes (git
 # captures the tracked ones); in a NON-GIT workspace it is EVERY write (there is
-# no git snapshot). Only a built-in write/edit (category "write") takes this arm;
-# deletes and shell/MCP stay on the deny-gate below (parity with the deep-agent
-# approval gate). The staging runs on the runner's own Node binary (the
+# no git snapshot). Only a built-in write/edit (category "write") takes THIS arm;
+# deletes take their own staging arm just below (issue #303), shell/MCP stay on
+# the deny-gate (parity with the deep-agent approval gate). The staging runs on
+# the runner's own Node binary (the
 # disk-backed mirror of CasCaptureFilesystemBackend.recordBefore): the salient
 # path rides stdin (no argv escaping), the workspace root and the per-turn
 # cas-observations dir ride argv. "captured" -> allow (apply-then-review);
@@ -629,6 +629,32 @@ if [ "$CAPTURE_IGNORED" = "true" ] && [ "$CATEGORY" = "write" ] && [ -n "$SALIEN
   fi
 fi
 
+# --- Capture mode: observe CAS-owned deletes for review (issue #303) --------
+# The delete twin of the write arm above — a non-secret CAS-owned delete stages
+# its before-bytes (the one moment they still exist on disk) and flows; the
+# turn boundary then reads after=null and authors a reviewable, restorable
+# DELETE entry. One deliberate difference from the write arm: the path is
+# classified for secret-likeness BEFORE any staging touches the sidecar. A
+# secret-like delete must stay on the deny-gate below where a human may still
+# approve it (its args expose no secret content, unlike a write) — staging it
+# would both persist the secret before-bytes and mark the sidecar "secret",
+# making the boundary author a blocking DIFF_UNREVIEWABLE for a merely-gated
+# delete. Every failure mode (secret, classify error, staging error) falls
+# through to the deny-gate rather than denying here, so grants and leases keep
+# applying to a gated delete exactly as before this arm existed; the eventual
+# resolution records its own ledger kind.
+if [ "$CAPTURE_IGNORED" = "true" ] && [ "$CATEGORY" = "delete" ] && [ -n "$SALIENT" ] && { [ "$GIT_WORKSPACE" = "false" ] || __stigmer_is_gitignored "$SALIENT"; }; then
+  DELETE_SECRET_RESULT=$(printf '%s' "$SALIENT" | ELECTRON_RUN_AS_NODE=1 "$NODE_BIN" -e '${secretClassifyScript}' 2>/dev/null || echo error)
+  if [ "$DELETE_SECRET_RESULT" = "ok" ]; then
+    OBS_DIR="$(dirname "$STATE_FILE")/${CAS_OBSERVATIONS_DIRNAME}"
+    OBS_RESULT=$(printf '%s' "$SALIENT" | ELECTRON_RUN_AS_NODE=1 "$NODE_BIN" -e '${observationStagingScript}' "$GIT_ROOT" "$OBS_DIR" 2>/dev/null || echo error)
+    if [ "$OBS_RESULT" = "captured" ]; then
+      echo '{"permission":"allow"}'
+      exit 0
+    fi
+  fi
+fi
+
 # --- 1a. MCP capability manifest: enabled_tools (issue #350) ---
 # Runs BEFORE the auto-approve-all shortcut and every grant check because
 # enabled_tools is a capability manifest, not an approval gate: no bypass may
@@ -700,13 +726,13 @@ if [ -n "$CATEGORY" ]; then
   # Capture mode (GIT tree only): a git-tracked file mutation (write/edit/delete)
   # flows freely — the runner captures the whole change set with git at the turn
   # boundary and gates it per-file for review. A gitignored path is invisible to
-  # that git snapshot: a non-secret gitignored WRITE was already handled above
-  # (staged + allowed, or hard-blocked) when captureIgnored is on; here it only
-  # reaches the deny-gate when captureIgnored is off (no artifact storage) or it is
-  # a gitignored DELETE (no CAS capture path, parity with deep-agent). shell
-  # (category "shell") never takes this branch and stays gated as always. In a
-  # NON-GIT workspace this arm is skipped entirely (there is no git diff): writes
-  # were CAS-staged above and a delete falls through to the deny-gate.
+  # that git snapshot: a non-secret gitignored WRITE or DELETE was already
+  # handled above (staged + allowed, hard-blocked, or left to fall through) when
+  # captureIgnored is on; here it only reaches the deny-gate when captureIgnored
+  # is off (no artifact storage), or it is a secret-like DELETE (approvable, but
+  # never staged — issue #303). shell (category "shell") never takes this branch
+  # and stays gated as always. In a NON-GIT workspace this arm is skipped
+  # entirely (there is no git diff): writes and deletes were CAS-staged above.
   if [ "$CAPTURE_MODE" = "true" ] && [ "$GIT_WORKSPACE" = "true" ] && { [ "$CATEGORY" = "write" ] || [ "$CATEGORY" = "delete" ]; }; then
     if ! __stigmer_is_gitignored "$SALIENT"; then
       echo '{"permission":"allow"}'

package/src/activities/execute-cursor/skill-resolver.ts

@@ -7,9 +7,17 @@
  * - Uses a platform-managed directory outside the workspace
  * - Ensures the workspace `.stigmer` symlink (see stigmer-link.ts)
  * - Returns metadata for prompt injection
+ *
+ * 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
+ * skipped when the mounted content's hash already matches. The session's
+ * platform dir survives across executions, so on an active session every
+ * message after the first pays a metadata read instead of a full artifact
+ * transfer.
  */
 
-import { mkdir, writeFile, rm } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
@@ -21,6 +29,25 @@ import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/work
 
 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.
+ */
+const MOUNT_MARKER_FILE = ".stigmer-mount.json";
+
+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;
+}
+
 export interface SkillResolverOptions {
   sessionId: string;
   primaryWorkspaceDir: string;
@@ -61,11 +88,34 @@ export async function resolveSkills(
   for (const ref of skillRefs) {
     try {
       const skill = await client.getSkillByReference(ref);
+      const spec = skill.spec;
+      if (!spec?.skillMd) {
+        console.warn(`[resolveSkills] skill ${ref.org}/${ref.slug} fetched but had no skillMd content`);
+        continue;
+      }
+
+      const name = spec.name || skill.metadata?.slug || "unknown";
+      const skillDir = join(skillsDir, name);
+      const versionHash = skill.status?.versionHash ?? "";
+      const wantsArtifact = Boolean(skill.status?.artifactStorageKey);
+      const meta: SkillMetadata = {
+        name,
+        description: spec.description || `Skill: ${name}`,
+        path: join(STIGMER_LOCAL_STATE_DIR, SKILLS_SUBDIR, name, "SKILL.md"),
+      };
+
+      if (versionHash !== "" && (await mountIsFresh(skillDir, versionHash, wantsArtifact))) {
+        results.push(meta);
+        console.log(
+          `[resolveSkills] mount cache hit: ${name} (version ${versionHash.slice(0, 12)}) — skipping artifact transfer`,
+        );
+        continue;
+      }
 
       let artifactBytes: Uint8Array | undefined;
-      if (skill.status?.artifactStorageKey) {
+      if (wantsArtifact) {
         try {
-          const resp = await client.getSkillArtifact(skill.status.artifactStorageKey);
+          const resp = await client.getSkillArtifact(skill.status!.artifactStorageKey);
           if (resp.artifact && resp.artifact.length > 0) {
             artifactBytes = resp.artifact;
           }
@@ -77,13 +127,9 @@ export async function resolveSkills(
         }
       }
 
-      const meta = await writeSkill(skill, skillsDir, options.primaryWorkspaceDir, artifactBytes);
-      if (meta) {
-        results.push(meta);
-        console.log(`[resolveSkills] wrote skill: ${meta.name} -> ${meta.path}`);
-      } else {
-        console.warn(`[resolveSkills] skill ${ref.org}/${ref.slug} fetched but had no skillMd content`);
-      }
+      await writeSkillMount(skill, skillDir, artifactBytes);
+      results.push(meta);
+      console.log(`[resolveSkills] wrote skill: ${name} -> ${meta.path}`);
     } catch (err) {
       console.warn(
         `[resolveSkills] failed to resolve skill ${ref.org}/${ref.slug}: ${err instanceof Error ? err.message : err}`,
@@ -98,24 +144,47 @@ export async function resolveSkills(
   return results;
 }
 
-async function writeSkill(
+/**
+ * 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.
+ */
+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;
+  }
+}
+
+/**
+ * (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 — 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.
+ */
+async function writeSkillMount(
   skill: Skill,
-  skillsDir: string,
-  workspaceDir: string,
-  artifactBytes?: Uint8Array,
-): Promise<SkillMetadata | null> {
-  const spec = skill.spec;
-  if (!spec?.skillMd) return null;
-
-  const name = spec.name || skill.metadata?.slug || "unknown";
-  const skillDir = join(skillsDir, name);
+  skillDir: string,
+  artifactBytes: Uint8Array | undefined,
+): Promise<void> {
+  await rm(skillDir, { recursive: true, force: true });
   await mkdir(skillDir, { recursive: true });
 
-  const skillMdPath = join(skillDir, "SKILL.md");
-  await writeFile(skillMdPath, spec.skillMd, "utf-8");
+  await writeFile(join(skillDir, "SKILL.md"), skill.spec!.skillMd, "utf-8");
 
-  if (artifactBytes && artifactBytes.length > 0) {
-    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md"] });
+  const artifactMounted = artifactBytes !== undefined && artifactBytes.length > 0;
+  if (artifactMounted) {
+    const entries = await extractZipFileEntries(artifactBytes, { exclude: ["SKILL.md", MOUNT_MARKER_FILE] });
     for (const entry of entries) {
       const filePath = join(skillDir, entry.path);
       await mkdir(dirname(filePath), { recursive: true });
@@ -123,13 +192,11 @@ async function writeSkill(
     }
   }
 
-  const relativePath = join(STIGMER_LOCAL_STATE_DIR, SKILLS_SUBDIR, name, "SKILL.md");
-
-  return {
-    name,
-    description: spec.description || `Skill: ${name}`,
-    path: relativePath,
-  };
+  const versionHash = skill.status?.versionHash ?? "";
+  if (versionHash !== "") {
+    const marker: MountMarker = { versionHash, artifactMounted };
+    await writeFile(join(skillDir, MOUNT_MARKER_FILE), JSON.stringify(marker), "utf-8");
+  }
 }
 
 /**