@stigmer/runner 3.0.1

package/src/activities/execute-cursor/__tests__/model-pricing.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, vi, beforeAll } from "vitest";
+
+/**
+ * Verifies the cursor-runner display estimate resolves Cursor speed variants
+ * (e.g. composer-2.5-fast) to the base model's fast-tier rates, mirroring the
+ * authoritative cloud billing path.
+ */
+describe("getCursorModelPricing — speed variant resolution", () => {
+  let getCursorModelPricing: typeof import("../model-pricing.js").getCursorModelPricing;
+  let computeTurnCost: typeof import("../model-pricing.js").computeTurnCost;
+
+  beforeAll(async () => {
+    const registry = {
+      models: [
+        {
+          id: "composer-2.5",
+          displayName: "Composer 2.5",
+          provider: "cursor",
+          harness: "cursor",
+          costTier: "economy",
+          pricing: {
+            inputPricePerMillion: 0.5,
+            outputPricePerMillion: 2.5,
+            cacheWritePricePerMillion: 0,
+            cacheReadPricePerMillion: 0.2,
+          },
+          pricingVariants: {
+            fast: {
+              inputPricePerMillion: 3.0,
+              outputPricePerMillion: 15.0,
+              cacheWritePricePerMillion: 0,
+              cacheReadPricePerMillion: 0.2,
+            },
+          },
+        },
+        {
+          id: "claude-opus-4-6",
+          displayName: "Claude 4.6 Opus",
+          provider: "anthropic",
+          harness: "cursor",
+          costTier: "premium",
+          pricing: {
+            inputPricePerMillion: 5.0,
+            outputPricePerMillion: 25.0,
+            cacheWritePricePerMillion: 6.25,
+            cacheReadPricePerMillion: 0.5,
+          },
+        },
+      ],
+    };
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: true, status: 200, json: async () => registry })),
+    );
+    process.env.STIGMER_TOKEN = "test-token";
+
+    const mod = await import("../model-pricing.js");
+    await mod.ensureLoaded();
+    getCursorModelPricing = mod.getCursorModelPricing;
+    computeTurnCost = mod.computeTurnCost;
+  });
+
+  it("resolves composer-2.5-fast to the fast tier ($3/$15)", () => {
+    const p = getCursorModelPricing("composer-2.5-fast");
+    expect(p.model).toBe("composer-2.5-fast");
+    expect(p.inputPricePerMillion).toBe(3.0);
+    expect(p.outputPricePerMillion).toBe(15.0);
+    expect(p.cacheReadPricePerMillion).toBe(0.2);
+  });
+
+  it("resolves the base composer-2.5 to the standard tier ($0.5/$2.5)", () => {
+    const p = getCursorModelPricing("composer-2.5");
+    expect(p.inputPricePerMillion).toBe(0.5);
+    expect(p.outputPricePerMillion).toBe(2.5);
+  });
+
+  it("uses base rates when a -fast model has no fast variant", () => {
+    // claude-opus-4-6 has no fast variant in this stub → fall back to base.
+    const p = getCursorModelPricing("claude-opus-4-6-fast");
+    // No variant and no exact/normalized match → DEFAULT_PRICING (Auto pool).
+    expect(p.inputPricePerMillion).toBe(1.25);
+  });
+
+  it("computeTurnCost on the fast tier reproduces the higher charge", () => {
+    const p = getCursorModelPricing("composer-2.5-fast");
+    // Cursor reports inputTokens inclusive of cache; regular input = 44,513.
+    // (266,945 - 222,432 cache read). 44,513*$3 + 7,069*$15 + 222,432*$0.2 ≈ $0.284
+    const cost = computeTurnCost(p, 266_945, 7_069, 0, 222_432);
+    expect(cost).toBeCloseTo(0.28406, 5);
+  });
+});

package/src/activities/execute-cursor/__tests__/prompt-builder-delegation.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  SubAgentSchema,
+  McpAccessSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import {
+  formatSubAgentsSection,
+  formatExplorationGuidance,
+  buildEnhancedPrompt,
+} from "../prompt-builder.js";
+
+function makeSubAgent(name: string, description: string, mcpServers?: string[]) {
+  const sa = create(SubAgentSchema);
+  sa.name = name;
+  sa.description = description;
+  sa.instructions = "do the thing thoroughly";
+  if (mcpServers) {
+    sa.mcpAccess = mcpServers.map((s) => {
+      const a = create(McpAccessSchema);
+      a.mcpServer = s;
+      return a;
+    });
+  }
+  return sa;
+}
+
+describe("formatSubAgentsSection", () => {
+  it("lists sub-agents by name and explains Task-tool delegation", () => {
+    const section = formatSubAgentsSection([
+      makeSubAgent("researcher", "Researches topics"),
+    ]);
+    expect(section).toContain("<sub_agent_delegation>");
+    expect(section).toContain("Task tool");
+    expect(section).toContain("**researcher**: Researches topics");
+    expect(section).toContain("</sub_agent_delegation>");
+  });
+
+  it("marks MCP access as advisory and explains the inheritance caveat", () => {
+    const section = formatSubAgentsSection([
+      makeSubAgent("tooluser", "uses tools", ["server-a"]),
+    ]);
+    expect(section).toContain("MCP access (advisory): server-a");
+    expect(section).toContain("advisory");
+    expect(section.toLowerCase()).toContain("inherit");
+  });
+
+  it("omits the MCP caveat line when no sub-agent declares mcp access", () => {
+    const section = formatSubAgentsSection([
+      makeSubAgent("plain", "no tools"),
+    ]);
+    expect(section).not.toContain("advisory");
+  });
+});
+
+describe("formatExplorationGuidance", () => {
+  it("encourages the built-in explore sub-agent and discourages trivial delegation", () => {
+    const g = formatExplorationGuidance();
+    expect(g).toContain("<codebase_exploration>");
+    expect(g).toContain("explore");
+    expect(g).toContain("Task tool");
+    expect(g).toContain("Do NOT delegate trivial");
+  });
+});
+
+describe("buildEnhancedPrompt delegation integration", () => {
+  const base = {
+    instructions: "You are a test agent.",
+    userMessage: "find the bug",
+    skills: [],
+    subAgents: [],
+    workspaceFileRefs: [],
+    attachmentPaths: [],
+  };
+
+  it("includes exploration guidance when a workspace dir is present", () => {
+    const prompt = buildEnhancedPrompt({
+      ...base,
+      workspaceDirs: ["/tmp/project"],
+    });
+    expect(prompt).toContain("<codebase_exploration>");
+  });
+
+  it("omits exploration guidance when there is no workspace dir", () => {
+    const prompt = buildEnhancedPrompt({
+      ...base,
+      workspaceDirs: [],
+    });
+    expect(prompt).not.toContain("<codebase_exploration>");
+  });
+
+  it("includes the sub-agent delegation section when blueprint sub-agents exist", () => {
+    const prompt = buildEnhancedPrompt({
+      ...base,
+      workspaceDirs: ["/tmp/project"],
+      subAgents: [makeSubAgent("researcher", "Researches topics")],
+    });
+    expect(prompt).toContain("<sub_agent_delegation>");
+    expect(prompt).toContain("**researcher**");
+  });
+});

package/src/activities/execute-cursor/__tests__/runner-error-regressions.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Regression tests for runner execution pipeline fixes.
+ *
+ * Covers three bugs discovered during daily-notification-plan workflow
+ * execution:
+ *
+ * 1. Model pricing loaded too late (resolveModelId before ensurePricingLoaded)
+ * 2. MCP connect-backfill proto serialization (plain object instead of
+ *    create(ExecutionValueSchema, ...))
+ * 3. Session slug re-validation on full update
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { ConnectInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 1. Model pricing: resolveModelId must succeed after ensureLoaded
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("model pricing ordering regression", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("resolveModelId returns 'default' before ensureLoaded (documents the bug)", async () => {
+    // Reset module state to simulate a fresh import
+    vi.resetModules();
+    const { resolveModelId } = await import("../model-pricing.js");
+    expect(resolveModelId("claude-sonnet-4")).toBe("default");
+  });
+
+  it("resolveModelId returns the model name after ensureLoaded with populated registry", async () => {
+    vi.resetModules();
+
+    // Mock the pricing data fetch to return a known model
+    vi.doMock("../model-pricing-data.js", () => ({
+      getPricingTable: vi.fn().mockResolvedValue([
+        {
+          model: "claude-sonnet-4",
+          displayName: "Claude Sonnet 4",
+          costTier: "standard",
+          inputPricePerMillion: 3.0,
+          outputPricePerMillion: 15.0,
+          cacheWritePricePerMillion: 3.75,
+          cacheReadPricePerMillion: 0.30,
+        },
+      ]),
+      DEFAULT_PRICING: {
+        model: "unknown",
+        displayName: "Unknown",
+        costTier: "standard",
+        inputPricePerMillion: 1.25,
+        outputPricePerMillion: 6.0,
+        cacheWritePricePerMillion: 1.25,
+        cacheReadPricePerMillion: 0.25,
+      },
+    }));
+
+    const { resolveModelId, ensureLoaded } = await import("../model-pricing.js");
+
+    await ensureLoaded();
+    expect(resolveModelId("claude-sonnet-4")).toBe("claude-sonnet-4");
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 2. Connect-backfill: ExecutionValue must be a proto message, not a plain object
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("connect-backfill proto serialization regression", () => {
+  it("ConnectInput.runtimeEnv serializes correctly with create(ExecutionValueSchema)", () => {
+    const input = create(ConnectInputSchema, {
+      mcpServerId: "test-id",
+      org: "test-org",
+    });
+
+    // This is the FIXED pattern — uses create(ExecutionValueSchema, ...)
+    input.runtimeEnv["POSTGRES_URL"] = create(ExecutionValueSchema, {
+      value: "postgresql://localhost/test",
+      isSecret: true,
+    });
+
+    // Verify the message is a proper proto message, not a plain object
+    expect(input.runtimeEnv["POSTGRES_URL"].value).toBe("postgresql://localhost/test");
+    expect(input.runtimeEnv["POSTGRES_URL"].isSecret).toBe(true);
+    expect(input.runtimeEnv["POSTGRES_URL"].$typeName).toBe(
+      "ai.stigmer.agentic.executioncontext.v1.ExecutionValue",
+    );
+  });
+
+  it("plain object assignment would fail serialization (documents the bug)", () => {
+    const input = create(ConnectInputSchema, {
+      mcpServerId: "test-id",
+      org: "test-org",
+    });
+
+    // This was the BUGGY pattern — plain object cast with `as any`
+    input.runtimeEnv["KEY"] = { value: "val" } as any;
+
+    // The plain object lacks $typeName, proving it's not a proper proto message
+    expect((input.runtimeEnv["KEY"] as any).$typeName).toBeUndefined();
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. Session slug: clearing slug before update avoids re-validation failure
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("session slug clearing regression", () => {
+  it("clearing metadata.slug to empty string avoids re-validation of invalid slugs", () => {
+    // Simulate a session object returned from getSession with an invalid slug
+    const session = {
+      metadata: {
+        id: "ses_01kscspgzpswfpgjdxw3wfgvvy",
+        name: "ses-wf-wex01kscsp7qj7p7q7ffg6rcajk5d-analyze-player-data",
+        slug: "ses-wf-wex_01kscsp7qj7p7q7ffg6rcajk5d-analyze_player_data",
+        org: "tt-demo",
+      },
+      spec: {
+        harnessStateId: "",
+        cursorMode: 0,
+      },
+    };
+
+    // The slug contains underscores, which violates ^[a-z][a-z0-9-]*[a-z0-9]$
+    const slugPattern = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+    expect(slugPattern.test(session.metadata.slug)).toBe(false);
+
+    // After clearing (the fix), the empty slug passes IGNORE_IF_ZERO_VALUE
+    session.metadata.slug = "";
+    expect(session.metadata.slug).toBe("");
+
+    // Metadata still has the fields needed for the update pipeline
+    expect(session.metadata.id).toBeTruthy();
+    expect(session.metadata.name).toBeTruthy();
+    expect(session.metadata.org).toBeTruthy();
+  });
+});

package/src/activities/execute-cursor/__tests__/session-lifecycle.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Unit tests for resolvePlatformOptions — the Cursor SDK stateRoot derivation.
+ *
+ * stateRoot is keyed by sessionId and rooted at the durable workspace volume so
+ * native Agent.resume() survives restart/snapshot-restore and so sessions that
+ * share one volume (e.g. a workflow sandbox's child agent executions) never
+ * collide. These invariants are correctness-critical, hence the explicit tests.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolvePlatformOptions } from "../session-lifecycle.js";
+
+const tempRoots: string[] = [];
+
+function freshWorkspaceRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "stigmer-stateroot-test-"));
+  tempRoots.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempRoots.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("resolvePlatformOptions", () => {
+  it("derives stateRoot under the workspace volume (not $HOME)", () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const opts = resolvePlatformOptions("ses-123", workspaceRootDir);
+
+    expect(opts.stateRoot).toBe(
+      join(workspaceRootDir, ".stigmer", "cursor-sdk-state", "ses-123"),
+    );
+    expect(opts.stateRoot.startsWith(workspaceRootDir)).toBe(true);
+    // Created eagerly to prevent ENOENT on first SDK write.
+    expect(existsSync(opts.stateRoot!)).toBe(true);
+    expect(opts.workspaceRef).toBe("stigmer-session:ses-123");
+  });
+
+  it("isolates two sessions sharing one workspace volume into distinct stores", () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const a = resolvePlatformOptions("ses-aaa", workspaceRootDir);
+    const b = resolvePlatformOptions("ses-bbb", workspaceRootDir);
+
+    expect(a.stateRoot).not.toBe(b.stateRoot);
+    expect(a.workspaceRef).not.toBe(b.workspaceRef);
+    // Both live under the same shared volume but in session-keyed subdirs.
+    expect(a.stateRoot!.startsWith(join(workspaceRootDir, ".stigmer"))).toBe(true);
+    expect(b.stateRoot!.startsWith(join(workspaceRootDir, ".stigmer"))).toBe(true);
+  });
+
+  it("throws on an empty sessionId (would collide across sessions on a shared volume)", () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    expect(() => resolvePlatformOptions("", workspaceRootDir)).toThrow(/sessionId is required/);
+  });
+
+  it("throws on an empty workspaceRootDir (state must live on the durable volume)", () => {
+    expect(() => resolvePlatformOptions("ses-123", "")).toThrow(/workspaceRootDir is required/);
+  });
+});

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

@@ -0,0 +1,265 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { resolveSkills } from "../skill-resolver.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+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;
+} = {}) {
+  return {
+    metadata: {
+      id: `skill-${overrides.slug ?? "test"}`,
+      slug: overrides.slug ?? "test-skill",
+      org: "test-org",
+    },
+    spec: {
+      name: overrides.name ?? overrides.slug ?? "test-skill",
+      description: overrides.description ?? "A test skill",
+      skillMd: overrides.skillMd ?? "# Test Skill",
+    },
+    status: {
+      artifactStorageKey: overrides.artifactStorageKey ?? "",
+      versionHash: "abc",
+    },
+  } as any;
+}
+
+function makeRef(slug: string, org = "test-org") {
+  return { slug, org, kind: 43 } as any;
+}
+
+// ─── resolveSkills with artifacts ────────────────────────────────────────
+
+describe("resolveSkills — artifact extraction", () => {
+  let workspaceDir: string;
+
+  beforeEach(() => {
+    workspaceDir = makeTempDir("resolver-ws-");
+  });
+
+  afterEach(() => {
+    rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Resolve skills using a mock client. The getPlatformDir call uses the
+   * real HOME-based path, but we override by mocking the module to point
+   * at our temp directory instead.
+   */
+  async function resolveWithMockClient(
+    refs: any[],
+    clientOverrides: Record<string, any>,
+  ) {
+    const sessionId = `test-session-${Date.now()}`;
+
+    // We need to clean up the platform dir after the test; capture it
+    // via the getPlatformDir import so we know the actual path.
+    const { getPlatformDir } = await import("../../../shared/workspace/platform-dir.js");
+    const platformDir = getPlatformDir(sessionId);
+
+    const client = {
+      getSkillByReference: vi.fn(),
+      getSkillArtifact: vi.fn().mockResolvedValue({ artifact: new Uint8Array(0) }),
+      ...clientOverrides,
+    } as any;
+
+    try {
+      const result = await resolveSkills(client, refs, {
+        sessionId,
+        primaryWorkspaceDir: workspaceDir,
+      });
+      return { result, platformDir, client };
+    } catch (err) {
+      // Clean up on failure
+      rmSync(platformDir, { recursive: true, force: true });
+      throw err;
+    }
+  }
+
+  function cleanupPlatformDir(platformDir: string) {
+    try {
+      rmSync(platformDir, { recursive: true, force: true });
+    } catch { /* best effort */ }
+    // Also remove the symlink in workspace
+    try {
+      rmSync(join(workspaceDir, ".stigmer"), { force: true });
+    } catch { /* best effort */ }
+  }
+
+  it("writes SKILL.md and extracts reference files from artifact", async () => {
+    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([
+      { name: "SKILL.md", content: skillMd },
+      { name: "references/", content: "" },
+      { name: "references/database-schema.md", content: schemaContent },
+    ]);
+
+    const { result, platformDir } = await resolveWithMockClient(
+      [makeRef("garden-design-makeover")],
+      {
+        getSkillByReference: vi.fn().mockResolvedValue(
+          makeSkillProto({
+            name: "garden-design-makeover",
+            slug: "garden-design-makeover",
+            skillMd,
+            artifactStorageKey: "artifacts/garden.zip",
+          }),
+        ),
+        getSkillArtifact: vi.fn().mockResolvedValue({ artifact }),
+      },
+    );
+
+    try {
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe("garden-design-makeover");
+
+      const skillDir = join(platformDir, "skills", "garden-design-makeover");
+      expect(readFileSync(join(skillDir, "SKILL.md"), "utf-8")).toBe(skillMd);
+      expect(readFileSync(join(skillDir, "references", "database-schema.md"), "utf-8")).toBe(schemaContent);
+    } finally {
+      cleanupPlatformDir(platformDir);
+    }
+  });
+
+  it("writes only SKILL.md when skill has no artifactStorageKey", async () => {
+    const { result, platformDir, client } = await resolveWithMockClient(
+      [makeRef("simple-skill")],
+      {
+        getSkillByReference: vi.fn().mockResolvedValue(
+          makeSkillProto({
+            name: "simple-skill",
+            slug: "simple-skill",
+            skillMd: "# Simple",
+            artifactStorageKey: "",
+          }),
+        ),
+      },
+    );
+
+    try {
+      expect(result).toHaveLength(1);
+      expect(client.getSkillArtifact).not.toHaveBeenCalled();
+
+      const skillDir = join(platformDir, "skills", "simple-skill");
+      expect(readFileSync(join(skillDir, "SKILL.md"), "utf-8")).toBe("# Simple");
+      expect(existsSync(join(skillDir, "references"))).toBe(false);
+    } finally {
+      cleanupPlatformDir(platformDir);
+    }
+  });
+
+  it("falls back to SKILL.md only when artifact download fails", async () => {
+    const { result, platformDir } = await resolveWithMockClient(
+      [makeRef("flaky-skill")],
+      {
+        getSkillByReference: vi.fn().mockResolvedValue(
+          makeSkillProto({
+            name: "flaky-skill",
+            slug: "flaky-skill",
+            skillMd: "# Flaky",
+            artifactStorageKey: "artifacts/flaky.zip",
+          }),
+        ),
+        getSkillArtifact: vi.fn().mockRejectedValue(new Error("Network timeout")),
+      },
+    );
+
+    try {
+      expect(result).toHaveLength(1);
+      expect(result[0].name).toBe("flaky-skill");
+
+      const skillDir = join(platformDir, "skills", "flaky-skill");
+      expect(readFileSync(join(skillDir, "SKILL.md"), "utf-8")).toBe("# Flaky");
+    } 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([
+      { name: "SKILL.md", content: zipContent },
+      { name: "references/data.md", content: "data" },
+    ]);
+
+    const { result, platformDir } = await resolveWithMockClient(
+      [makeRef("precedence-test")],
+      {
+        getSkillByReference: vi.fn().mockResolvedValue(
+          makeSkillProto({
+            name: "precedence-test",
+            slug: "precedence-test",
+            skillMd: specContent,
+            artifactStorageKey: "artifacts/test.zip",
+          }),
+        ),
+        getSkillArtifact: vi.fn().mockResolvedValue({ artifact }),
+      },
+    );
+
+    try {
+      expect(result).toHaveLength(1);
+
+      const skillDir = join(platformDir, "skills", "precedence-test");
+      expect(readFileSync(join(skillDir, "SKILL.md"), "utf-8")).toBe(specContent);
+      expect(readFileSync(join(skillDir, "references", "data.md"), "utf-8")).toBe("data");
+    } finally {
+      cleanupPlatformDir(platformDir);
+    }
+  });
+});