@runfusion/fusion 0.49.0 → 0.50.0

package/dist/pi-claude-cli/index.ts

@@ -25,10 +25,10 @@ import {
 } from "./src/mcp-config.js";
 
 /**
- * Route A kill-switch (U11). When `FUSION_CLAUDE_ACP=1` AND a bridge binary path
- * is available (`FUSION_CLAUDE_ACP_BRIDGE`, injected by the engine seam per
- * KTD10), the provider drives Claude through the ACP bridge instead of
- * `claude -p`. OFF by default: the live `-p` path is untouched until soak.
+ * FNXC:pi-claude-cli 2026-06-27-06:39:
+ * Route A drives Claude through the ACP bridge only when `FUSION_CLAUDE_ACP=1`
+ * AND a bridge binary path is injected via `FUSION_CLAUDE_ACP_BRIDGE`.
+ * OFF by default: the live `claude -p` path stays untouched until soak.
  */
 function resolveAcpBridgePath(): string | undefined {
   if (process.env.FUSION_CLAUDE_ACP !== "1") return undefined;
@@ -52,14 +52,12 @@ process.on("exit", killAllProcesses);
 const PROVIDER_ID = "pi-claude-cli";
 
 /**
- * Run CLI presence + auth probes at most once per process, asynchronously.
- *
- * The factory below is invoked on every `createFnAgent` call (the dashboard
- * does this per chat message). Doing the probes synchronously with execSync
- * froze the entire Node event loop for a few seconds while `claude` cold-
- * started. Memoizing as a Promise + spawning the probes async means the
- * factory returns immediately and other requests keep flowing; the result
- * is logged once on first run and reused thereafter.
+ * FNXC:pi-claude-cli 2026-06-27-06:39:
+ * The factory runs per `createFnAgent` call, which the dashboard does for each
+ * chat message. Synchronous `execSync` presence + auth probes froze the Node
+ * event loop while `claude` cold-started, so memoize the probes as an async
+ * Promise: the factory returns immediately, the result logs once, and later
+ * calls reuse it.
  */
 let cliValidationPromise: Promise<void> | undefined;
 
@@ -257,8 +255,7 @@ export default function (pi: ExtensionAPI) {
           parameters: Record<string, unknown>;
         }> }).tools;
 
-        // Route A (U11): drive Claude through the ACP bridge when the kill-switch
-        // is on AND a bridge path is injected. OFF by default → `-p` path below.
+        // FNXC:pi-claude-cli 2026-06-27-06:39: Route A drives Claude through the ACP bridge only when the kill-switch is on AND a bridge path is injected. OFF by default → `-p` path below.
         const bridgePath = resolveAcpBridgePath();
         if (bridgePath) {
           const toolDefs = resolveToolDefs(pi, contextTools);
@@ -268,8 +265,7 @@ export default function (pi: ExtensionAPI) {
             ...options,
             bridgePath,
             mcpServers: buildAcpMcpServers(toolDefs, hash, userMcpServers),
-            // Forward only HOME/PATH so the bridged `claude` authenticates from the
-            // login/keychain session (R17); never inherited process.env or API keys.
+            // FNXC:pi-claude-cli 2026-06-27-06:39: Forward only HOME/PATH so the bridged `claude` authenticates from the login/keychain session (R17); never inherited process.env or API keys.
             bridgeEnv: { HOME: process.env.HOME, PATH: process.env.PATH },
           });
         }

package/dist/pi-claude-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion/pi-claude-cli",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "type": "module",
   "private": true,
   "main": "index.ts",

package/dist/plugin-sdk/index.d.ts

@@ -2172,6 +2172,12 @@ interface EnsureGitRepositoryOptions {
 }
 declare function ensureGitRepositoryForProjectPath(projectPath: string, options?: EnsureGitRepositoryOptions): Promise<GitRepositoryEnsureOutcome>;
 
+type RunningAgentCountSource = (projectIds: readonly string[]) => Promise<Record<string, number>> | Record<string, number>;
+interface RunningAgentCounts {
+    currentlyActive: number;
+    projectsActive: Record<string, number>;
+}
+
 interface CentralCoreEvents {
     "project:registered": [project: RegisteredProject];
     "project:reattached": [project: RegisteredProject, reason: string];
@@ -2391,6 +2397,9 @@ declare class CentralCore extends EventEmitter<CentralCoreEvents> {
     getDefaultProjectId(): Promise<string | undefined>;
     setDefaultProjectId(projectId: string | null): Promise<void>;
     getGlobalConcurrencyState(): Promise<GlobalConcurrencyState>;
+    getLiveRunningAgentCounts(options?: {
+        source?: RunningAgentCountSource;
+    }): Promise<RunningAgentCounts>;
     updateGlobalConcurrency(updates: Partial<Pick<GlobalConcurrencyState, "globalMaxConcurrent" | "currentlyActive" | "queuedCount">>): Promise<GlobalConcurrencyState>;
     acquireGlobalSlot(projectId: string): Promise<boolean>;
     releaseGlobalSlot(projectId: string): Promise<void>;
@@ -2696,6 +2705,13 @@ declare class TaskStore extends EventEmitter<TaskStoreEvents> {
             reason: string;
         }>;
     }>;
+    reconcilePhantomCommittedReservations(): Promise<{
+        reconciled: string[];
+        skipped: Array<{
+            id: string;
+            reason: string;
+        }>;
+    }>;
     private readTaskJson;
     private writeTaskJsonFile;
     private atomicCreateTaskJson;
@@ -2720,6 +2736,7 @@ declare class TaskStore extends EventEmitter<TaskStoreEvents> {
     private writeConfig;
     resolveLocalNodeIdForTaskAllocation(): Promise<string>;
     private createTaskWithDistributedReservation;
+    private rollbackFailedDistributedReservationCreate;
     private taskDir;
     private artifactRegistryDir;
     private static artifactStoredName;
@@ -2741,6 +2758,10 @@ declare class TaskStore extends EventEmitter<TaskStoreEvents> {
         prompt?: string;
         applyDefaultWorkflowSteps?: boolean;
         invokeTaskCreatedHook?: boolean;
+        reservationCommit?: {
+            reservationId: string;
+            nodeId: string;
+        };
     }): Promise<Task>;
     applyReplicatedTaskCreate(payload: MeshReplicatedTaskCreatePayload): Promise<MeshReplicatedTaskApplyResult>;
     private _createTaskInternal;
@@ -3989,6 +4010,7 @@ declare class Database {
     private applyMigration;
     private hasTable;
     isFts5CorruptionError(error: unknown): boolean;
+    reindexMessages(): void;
     private getTableColumns;
     private hasColumn;
     private tableExists;
@@ -4363,6 +4385,7 @@ interface WorkflowStep {
     prompt: string;
     toolMode?: WorkflowStepToolMode;
     skillName?: string;
+    requiresBrowser?: boolean;
     scriptName?: string;
     enabled: boolean;
     defaultOn?: boolean;
@@ -4372,7 +4395,7 @@ interface WorkflowStep {
     createdAt: string;
     updatedAt: string;
 }
-type NtfyNotificationEvent = "in-review" | "merged" | "failed" | "awaiting-approval" | "awaiting-user-review" | "planning-awaiting-input" | "gridlock" | "board-stall-unrecovered" | "db-corruption-detected" | "fallback-used" | "memory-dreams-processed" | "token-budget" | "message:agent-to-user" | "message:agent-to-agent" | "message:room" | "oauth-token-expired" | "task-created" | "workflow-notify";
+type NtfyNotificationEvent = "in-review" | "merged" | "failed" | "awaiting-approval" | "awaiting-user-review" | "planning-awaiting-input" | "cli-agent-awaiting-input" | "gridlock" | "board-stall-unrecovered" | "db-corruption-detected" | "fallback-used" | "memory-dreams-processed" | "token-budget" | "message:agent-to-user" | "message:agent-to-agent" | "message:room" | "oauth-token-expired" | "task-created" | "workflow-notify";
 interface NotificationProviderConfig {
     id: string;
     name: string;
@@ -5652,6 +5675,7 @@ interface ProjectSettings {
     verificationCommandTimeoutMs?: number;
     scopeVerificationToChangedFiles?: boolean;
     requirePlanApproval?: boolean;
+    planApprovalMode?: "workflow" | "auto-approve-all" | "require-all";
     ephemeralAgentsEnabled?: boolean;
     agentProvisioning?: {
         approvalMode?: AgentProvisioningApprovalMode;
@@ -6428,6 +6452,7 @@ interface Agent {
     totalOutputTokens?: number;
     lastError?: string;
     pendingApprovalCount?: number;
+    taskColumn?: string;
     instructionsPath?: string;
     instructionsText?: string;
     soul?: string;

package/dist/plugins/fusion-plugin-acp-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/acp-runtime",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "type": "module",
   "exports": {
     ".": {

package/dist/plugins/fusion-plugin-cli-printing-press/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fusion-plugin-examples/cli-printing-press",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "type": "module",
   "private": true,
   "exports": {

package/dist/plugins/fusion-plugin-compound-engineering/bundled.js

@@ -50,6 +50,18 @@ var COMPOUND_ENGINEERING_SKILLS = [
     enabled: true,
     triggerPatterns: ["do the work", "implement", "execute the plan", "finish this feature"]
   },
+  {
+    /*
+     * FNXC:CompoundEngineering 2026-06-27-00:00:
+     * FN-7144 bundles ce-doc-review because ce-plan and ce-brainstorm invoke it as a named markdown document-review skill, and the built-in CE workflow now exposes it as an optional advisory stage after planning.
+     */
+    skillId: "ce-doc-review",
+    name: "ce-doc-review",
+    description: "Review CE markdown plan documents for coherence, feasibility, scope alignment, and safe markdown-only fixes.",
+    skillFiles: ["skills/ce-doc-review/SKILL.md"],
+    enabled: true,
+    triggerPatterns: ["doc review", "document review", "review the plan", "pressure-test the requirements"]
+  },
   {
     skillId: "ce-code-review",
     name: "ce-code-review",
@@ -105,9 +117,23 @@ var COMPOUND_ENGINEERING_SKILLS = [
 ];
 
 // ../../plugins/fusion-plugin-compound-engineering/src/skill-installation.ts
-import { cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+
+// ../../plugins/fusion-plugin-compound-engineering/src/upstream-provenance.ts
+var CE_UPSTREAM_PROVENANCE = {
+  repo: "EveryInc/compound-engineering-plugin",
+  repoUrl: "https://github.com/EveryInc/compound-engineering-plugin",
+  releaseTag: "compound-engineering-v3.15.0",
+  releaseUrl: "https://github.com/EveryInc/compound-engineering-plugin/releases/tag/compound-engineering-v3.15.0",
+  sourceTarballUrl: "https://github.com/EveryInc/compound-engineering-plugin/archive/refs/tags/compound-engineering-v3.15.0.tar.gz",
+  commit: "2bbdbfb1d4287db95af407808b53266988ada974",
+  tarballSha256: "fce13e71bd709f8f572bf167c6af3753fc3fde0309c8f878498c78cb391c0b14",
+  vendoredAt: "2026-06-26"
+};
+
+// ../../plugins/fusion-plugin-compound-engineering/src/skill-installation.ts
 function resolveBundledSkillsRoot() {
   const here = fileURLToPath(import.meta.url);
   const dir = dirname(here);
@@ -143,17 +169,54 @@ function assertValidSkillSource(skillId, sourceDir) {
     );
   }
 }
+var SKILL_INSTALL_PROVENANCE_FILE = ".fusion-ce-upstream-provenance.json";
+function installProvenancePath(targetRoot) {
+  return join(targetRoot, SKILL_INSTALL_PROVENANCE_FILE);
+}
+function isCurrentInstalledProvenance(targetRoot) {
+  try {
+    const marker = JSON.parse(readFileSync(installProvenancePath(targetRoot), "utf-8"));
+    return marker.releaseTag === CE_UPSTREAM_PROVENANCE.releaseTag && marker.tarballSha256 === CE_UPSTREAM_PROVENANCE.tarballSha256;
+  } catch {
+    return false;
+  }
+}
+function writeInstalledProvenance(targetRoot) {
+  mkdirSync(targetRoot, { recursive: true });
+  writeFileSync(
+    installProvenancePath(targetRoot),
+    `${JSON.stringify(
+      {
+        repo: CE_UPSTREAM_PROVENANCE.repo,
+        releaseTag: CE_UPSTREAM_PROVENANCE.releaseTag,
+        commit: CE_UPSTREAM_PROVENANCE.commit,
+        tarballSha256: CE_UPSTREAM_PROVENANCE.tarballSha256,
+        installedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      null,
+      2
+    )}
+`
+  );
+}
 function installBundledCeSkills(options = {}) {
   const targetRoot = options.targetRoot ? resolve(options.targetRoot) : resolveDefaultInstallTargetRoot();
   assertPluginLocalTarget(targetRoot);
   const sourceRoot = options.sourceRoot ? resolve(options.sourceRoot) : resolveBundledSkillsRoot();
+  const installIsCurrent = isCurrentInstalledProvenance(targetRoot);
   const results = COMPOUND_ENGINEERING_SKILLS.map((skill) => {
     const sourceDir = join(sourceRoot, skill.skillId);
     const targetDir = join(targetRoot, skill.skillId);
     try {
       assertValidSkillSource(skill.skillId, sourceDir);
       if (existsSync(targetDir)) {
-        return { skillId: skill.skillId, sourceDir, targetDir, outcome: "skipped", reason: "existing install preserved" };
+        if (installIsCurrent) {
+          return { skillId: skill.skillId, sourceDir, targetDir, outcome: "skipped", reason: "current install preserved" };
+        }
+        rmSync(targetDir, { recursive: true, force: true });
+        mkdirSync(targetRoot, { recursive: true });
+        cpSync(sourceDir, targetDir, { recursive: true });
+        return { skillId: skill.skillId, sourceDir, targetDir, outcome: "refreshed", reason: "stale install refreshed" };
       }
       mkdirSync(targetRoot, { recursive: true });
       cpSync(sourceDir, targetDir, { recursive: true });
@@ -168,6 +231,9 @@ function installBundledCeSkills(options = {}) {
       };
     }
   });
+  if (results.every((result) => result.outcome !== "error")) {
+    writeInstalledProvenance(targetRoot);
+  }
   return { targetRoot, results };
 }
 function isPluginLocalPath(p) {
@@ -175,7 +241,7 @@ function isPluginLocalPath(p) {
 }
 
 // ../../plugins/fusion-plugin-compound-engineering/src/agent-installation.ts
-import { cpSync as cpSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { cpSync as cpSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname2, isAbsolute as isAbsolute2, join as join2, resolve as resolve2, sep as sep2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function resolveBundledAgentsRoot() {
@@ -207,10 +273,41 @@ function assertValidAgentSource(agentId, sourceFile) {
     throw new Error(`Bundled agent def '${agentId}' at ${sourceFile} is missing a frontmatter 'name:' field`);
   }
 }
+var AGENT_INSTALL_PROVENANCE_FILE = ".fusion-ce-upstream-provenance.json";
+function installProvenancePath2(targetRoot) {
+  return join2(targetRoot, AGENT_INSTALL_PROVENANCE_FILE);
+}
+function isCurrentInstalledProvenance2(targetRoot) {
+  try {
+    const marker = JSON.parse(readFileSync2(installProvenancePath2(targetRoot), "utf-8"));
+    return marker.releaseTag === CE_UPSTREAM_PROVENANCE.releaseTag && marker.tarballSha256 === CE_UPSTREAM_PROVENANCE.tarballSha256;
+  } catch {
+    return false;
+  }
+}
+function writeInstalledProvenance2(targetRoot) {
+  mkdirSync2(targetRoot, { recursive: true });
+  writeFileSync2(
+    installProvenancePath2(targetRoot),
+    `${JSON.stringify(
+      {
+        repo: CE_UPSTREAM_PROVENANCE.repo,
+        releaseTag: CE_UPSTREAM_PROVENANCE.releaseTag,
+        commit: CE_UPSTREAM_PROVENANCE.commit,
+        tarballSha256: CE_UPSTREAM_PROVENANCE.tarballSha256,
+        installedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      null,
+      2
+    )}
+`
+  );
+}
 function installBundledCeAgents(options = {}) {
   const targetRoot = options.targetRoot ? resolve2(options.targetRoot) : resolveDefaultAgentsInstallTargetRoot();
   assertPluginLocalAgentsTarget(targetRoot);
   const sourceRoot = options.sourceRoot ? resolve2(options.sourceRoot) : resolveBundledAgentsRoot();
+  const installIsCurrent = isCurrentInstalledProvenance2(targetRoot);
   const sourceFiles = existsSync2(sourceRoot) ? readdirSync(sourceRoot).filter((f) => f.endsWith(".md")) : [];
   const results = sourceFiles.map((file) => {
     const agentId = file.replace(/\.md$/, "");
@@ -219,7 +316,13 @@ function installBundledCeAgents(options = {}) {
     try {
       assertValidAgentSource(agentId, sourceFile);
       if (existsSync2(targetFile)) {
-        return { agentId, sourceFile, targetFile, outcome: "skipped", reason: "existing install preserved" };
+        if (installIsCurrent) {
+          return { agentId, sourceFile, targetFile, outcome: "skipped", reason: "current install preserved" };
+        }
+        rmSync2(targetFile, { force: true });
+        mkdirSync2(targetRoot, { recursive: true });
+        cpSync2(sourceFile, targetFile);
+        return { agentId, sourceFile, targetFile, outcome: "refreshed", reason: "stale install refreshed" };
       }
       mkdirSync2(targetRoot, { recursive: true });
       cpSync2(sourceFile, targetFile);
@@ -234,6 +337,9 @@ function installBundledCeAgents(options = {}) {
       };
     }
   });
+  if (results.length > 0 && results.every((result) => result.outcome !== "error")) {
+    writeInstalledProvenance2(targetRoot);
+  }
   return { targetRoot, results };
 }
 function isPluginLocalAgentsPath(p) {
@@ -318,7 +424,7 @@ function ensureCeSchema(db) {
 }
 
 // ../../plugins/fusion-plugin-compound-engineering/src/session/orchestrator.ts
-import { mkdirSync as mkdirSync3, writeFileSync } from "node:fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname3, isAbsolute as isAbsolute3, join as join3 } from "node:path";
 
 // ../../plugins/fusion-plugin-compound-engineering/src/sync/pipeline-store.ts
@@ -529,13 +635,17 @@ var STAGE_DEFINITIONS = [
     artifactGlob: "docs/ideation/**/*.md"
   },
   {
+    /*
+     * FNXC:CompoundEngineering 2026-06-27-00:21:
+     * Brainstorm and plan keep separate Fusion stage IDs and bundled skill IDs for session, pipeline, and board back-compat, but CE v3.15.0 aliases their durable artifact to one unified docs/plans plan. ce-brainstorm writes the requirements-only unified plan that ce-plan later enriches in place to implementation-ready.
+     */
     stageId: "brainstorm",
     order: 300,
     skillId: "ce-brainstorm",
-    artifactLocation: "docs/brainstorms/",
+    artifactLocation: "docs/plans/",
     icon: "Sparkles",
     label: "Brainstorm",
-    artifactGlob: "docs/brainstorms/**/*.md"
+    artifactGlob: "docs/plans/**/*.md"
   },
   {
     stageId: "plan",
@@ -891,6 +1001,29 @@ var CeTurnTimeoutError = class extends Error {
 function resolveStageSkillPaths() {
   return [resolveDefaultInstallTargetRoot()];
 }
+function checkStageSkillResolution(stage, skillPaths = resolveStageSkillPaths()) {
+  const expectedSkillMdPaths = skillPaths.map((root) => join3(root, stage.skillId, "SKILL.md"));
+  return {
+    skillId: stage.skillId,
+    expectedSkillMdPaths,
+    found: expectedSkillMdPaths.some((skillMd) => existsSync3(skillMd))
+  };
+}
+function warnIfStageSkillMissing(logger, stage, additionalSkillPaths = resolveStageSkillPaths()) {
+  const guard = checkStageSkillResolution(stage, additionalSkillPaths);
+  if (!guard.found) {
+    logger.warn(
+      `Compound Engineering stage '${stage.stageId}' requested skill '${stage.skillId}', but no SKILL.md was found on the plugin-local discovery paths. The session will still request the skill so the engine can resolve it if installation completes, but the current install appears missing.`,
+      {
+        stageId: stage.stageId,
+        skillId: stage.skillId,
+        expectedSkillMdPaths: guard.expectedSkillMdPaths,
+        additionalSkillPaths
+      }
+    );
+  }
+  return guard;
+}
 function buildStageSystemPrompt(stage) {
   return [
     `You are running the Compound Engineering "${stage.stageId}" stage.`,
@@ -955,12 +1088,14 @@ var CeOrchestrator = class {
   buildSessionOptions(stage, sessionId) {
     const defaultProvider = getDefaultProvider(this.ctx.settings);
     const defaultModelId = getDefaultModelId(this.ctx.settings);
+    const additionalSkillPaths = resolveStageSkillPaths();
+    warnIfStageSkillMissing(this.ctx.logger, stage, additionalSkillPaths);
     return {
       cwd: this.projectRoot,
       systemPrompt: buildStageSystemPrompt(stage),
       tools: "coding",
       requestedSkillNames: [stage.skillId],
-      additionalSkillPaths: resolveStageSkillPaths(),
+      additionalSkillPaths,
       onProgress: (event) => this.handleProgress(sessionId, event),
       ...defaultProvider ? { defaultProvider } : {},
       ...defaultModelId ? { defaultModelId } : {}
@@ -1450,7 +1585,7 @@ var CeOrchestrator = class {
     const target = location.endsWith("/") ? join3(location, `${session.stage}-${session.id}.md`) : location;
     const abs = isAbsolute3(target) ? target : join3(this.projectRoot, target);
     mkdirSync3(dirname3(abs), { recursive: true });
-    writeFileSync(abs, content, "utf-8");
+    writeFileSync3(abs, content, "utf-8");
     return abs;
   }
   extractArtifactContent(data) {
@@ -1657,7 +1792,17 @@ function createSessionRoutes() {
 }
 
 // ../../plugins/fusion-plugin-compound-engineering/src/artifacts/discovery.ts
-import { accessSync, constants, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync } from "node:fs";
+import {
+  accessSync,
+  closeSync,
+  constants,
+  lstatSync,
+  openSync,
+  readFileSync as readFileSync3,
+  readSync,
+  readdirSync as readdirSync2,
+  realpathSync
+} from "node:fs";
 import { isAbsolute as isAbsolute4, join as join4, relative, sep as sep3 } from "node:path";
 var CONVENTIONAL_LOCATIONS = [
   { stage: "strategy", label: "Strategy", path: "STRATEGY.md", kind: "file" },
@@ -1668,6 +1813,7 @@ var CONVENTIONAL_LOCATIONS = [
   { stage: "concepts", label: "Concepts", path: "CONCEPTS.md", kind: "file" }
 ];
 var MAX_ARTIFACT_BYTES = 2e6;
+var FRONTMATTER_PREFIX_BYTES = 8 * 1024;
 function toPosix(p) {
   return p.split(sep3).join("/");
 }
@@ -1681,6 +1827,19 @@ function isWithin(root, locationAbs, candidate) {
 function makeId(stage, relPath) {
   return `${stage}:${relPath}`;
 }
+function isRealPathWithin(root, locationAbs, candidate) {
+  try {
+    const realRoot = realpathSync(root);
+    const realLocation = realpathSync(locationAbs);
+    const realCandidate = realpathSync(candidate);
+    return isWithin(realRoot, realLocation, realCandidate);
+  } catch {
+    return false;
+  }
+}
+function symlinkError(stage, relPath) {
+  return makeError(stage, relPath, "Symlink artifacts are not allowed in CE discovery");
+}
 function makeError(stage, relPath, message) {
   return {
     id: makeId(stage, relPath),
@@ -1691,17 +1850,66 @@ function makeError(stage, relPath, message) {
     error: message
   };
 }
+function emptyMetadata() {
+  return { artifactContract: null, artifactReadiness: null, productContractSource: null };
+}
+function cleanYamlScalar(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  const commentStart = trimmed.indexOf(" #");
+  const withoutComment = commentStart >= 0 ? trimmed.slice(0, commentStart).trim() : trimmed;
+  return withoutComment.replace(/^['\"]|['\"]$/g, "") || null;
+}
+function parseArtifactMetadata(prefix) {
+  const metadata = emptyMetadata();
+  if (!prefix.startsWith("---")) return metadata;
+  const end = prefix.indexOf("\n---", 3);
+  if (end < 0) return metadata;
+  const frontmatter = prefix.slice(3, end).split(/\r?\n/);
+  for (const line of frontmatter) {
+    const match = /^\s*([A-Za-z0-9_-]+)\s*:\s*(.*?)\s*$/.exec(line);
+    if (!match) continue;
+    const value = cleanYamlScalar(match[2]);
+    if (match[1] === "artifact_contract") metadata.artifactContract = value;
+    if (match[1] === "artifact_readiness") metadata.artifactReadiness = value;
+    if (match[1] === "product_contract_source") metadata.productContractSource = value;
+  }
+  return metadata;
+}
+function readMetadataPrefix(abs, size) {
+  let fd;
+  try {
+    fd = openSync(abs, "r");
+    const buffer = Buffer.alloc(Math.min(size, FRONTMATTER_PREFIX_BYTES));
+    const bytesRead = readSync(fd, buffer, 0, buffer.length, 0);
+    return parseArtifactMetadata(buffer.toString("utf8", 0, bytesRead));
+  } catch {
+    return emptyMetadata();
+  } finally {
+    if (fd !== void 0) {
+      try {
+        closeSync(fd);
+      } catch {
+      }
+    }
+  }
+}
 function readArtifactEntry(stage, root, locationAbs, abs, relPath) {
   const name = relPath.split("/").pop() ?? relPath;
   if (!isWithin(root, locationAbs, abs)) {
     return makeError(stage, relPath, "Path is outside its conventional location");
   }
   try {
-    const st = statSync(abs);
+    const st = lstatSync(abs);
+    if (st.isSymbolicLink()) return symlinkError(stage, relPath);
+    if (!isRealPathWithin(root, locationAbs, abs)) {
+      return makeError(stage, relPath, "Path is outside its conventional location");
+    }
     if (st.size > MAX_ARTIFACT_BYTES) {
       return makeError(stage, relPath, `Artifact too large to read (${st.size} bytes)`);
     }
     accessSync(abs, constants.R_OK);
+    const metadata = readMetadataPrefix(abs, st.size);
     return {
       id: makeId(stage, relPath),
       stage,
@@ -1709,6 +1917,7 @@ function readArtifactEntry(stage, root, locationAbs, abs, relPath) {
       name,
       size: st.size,
       updatedAt: st.mtimeMs,
+      ...metadata,
       kind: "artifact"
     };
   } catch (err) {
@@ -1728,13 +1937,17 @@ function discoverLocation(root, loc) {
   let present = false;
   let st;
   try {
-    st = statSync(locationAbs);
+    st = lstatSync(locationAbs);
     present = true;
   } catch {
     return { stage: loc.stage, label: loc.label, present: false, entries: [] };
   }
   if (loc.kind === "file") {
-    if (st.isFile()) {
+    if (st.isSymbolicLink()) {
+      entries.push(symlinkError(loc.stage, toPosix(loc.path)));
+    } else if (!isRealPathWithin(root, locationAbs, locationAbs)) {
+      entries.push(makeError(loc.stage, toPosix(loc.path), "Path is outside its conventional location"));
+    } else if (st.isFile()) {
       entries.push(readArtifactEntry(loc.stage, root, locationAbs, locationAbs, toPosix(loc.path)));
     } else {
       entries.push(
@@ -1749,6 +1962,14 @@ function discoverLocation(root, loc) {
   }
   let names = [];
   try {
+    if (st.isSymbolicLink()) {
+      entries.push(symlinkError(loc.stage, toPosix(loc.path)));
+      return { stage: loc.stage, label: loc.label, present, entries: sortEntries(entries) };
+    }
+    if (!isRealPathWithin(root, locationAbs, locationAbs)) {
+      entries.push(makeError(loc.stage, toPosix(loc.path), "Path is outside its conventional location"));
+      return { stage: loc.stage, label: loc.label, present, entries: sortEntries(entries) };
+    }
     if (!st.isDirectory()) {
       entries.push(
         makeError(
@@ -1771,11 +1992,15 @@ function discoverLocation(root, loc) {
     const relPath = toPosix(join4(loc.path, childName));
     let childStat;
     try {
-      childStat = statSync(abs);
+      childStat = lstatSync(abs);
     } catch (err) {
       entries.push(makeError(loc.stage, relPath, err instanceof Error ? err.message : String(err)));
       continue;
     }
+    if (childStat.isSymbolicLink()) {
+      entries.push(symlinkError(loc.stage, relPath));
+      continue;
+    }
     if (!childStat.isFile()) continue;
     entries.push(readArtifactEntry(loc.stage, root, locationAbs, abs, relPath));
   }
@@ -1818,7 +2043,9 @@ function readArtifactById(projectRoot, id) {
   let mtimeMs;
   let size;
   try {
-    const st = statSync(abs);
+    const st = lstatSync(abs);
+    if (st.isSymbolicLink()) return { error: "Symlink artifacts are not allowed in CE discovery" };
+    if (!isRealPathWithin(projectRoot, locationAbs, abs)) return void 0;
     if (!st.isFile()) return { error: "Artifact is not a readable file" };
     if (st.size > MAX_ARTIFACT_BYTES) return { error: `Artifact too large to read (${st.size} bytes)` };
     mtimeMs = st.mtimeMs;
@@ -1841,6 +2068,7 @@ function readArtifactById(projectRoot, id) {
       name,
       size,
       updatedAt: mtimeMs,
+      ...parseArtifactMetadata(content.slice(0, FRONTMATTER_PREFIX_BYTES)),
       kind: "artifact"
     },
     content
@@ -2120,12 +2348,14 @@ var plugin = definePlugin({
     // Install the bundled, pinned ce-* SKILL.md files into a plugin-local,
     // discoverable directory on load. The engine ingests
     // PluginSkillContribution only as a name; physical discovery requires the
-    // files to exist on a path it scans (U2 finding). Install is idempotent
-    // (skip-if-exists) and guarded to never touch a global ~/.claude/skills.
+    // files to exist on a path it scans (U2 finding). Install is provenance-aware:
+    // current plugin-local copies are skipped, stale/unmarked copies are refreshed,
+    // and global ~/.claude/skills is never touched.
     onLoad: async (ctx) => {
       try {
         const { targetRoot, results } = installBundledCeSkills();
         const installed = results.filter((r) => r.outcome === "installed").length;
+        const refreshed = results.filter((r) => r.outcome === "refreshed").length;
         const errored = results.filter((r) => r.outcome === "error");
         if (errored.length > 0) {
           ctx.logger.warn(
@@ -2133,7 +2363,7 @@ var plugin = definePlugin({
           );
         }
         ctx.logger.info(
-          `Compound Engineering skills ready \u2014 installed=${installed} target=${targetRoot}`
+          `Compound Engineering skills ready \u2014 installed=${installed} refreshed=${refreshed} target=${targetRoot}`
         );
         ctx.emitEvent("compound-engineering:skills-installed", { targetRoot, results });
       } catch (error) {
@@ -2143,6 +2373,7 @@ var plugin = definePlugin({
       try {
         const { targetRoot, results } = installBundledCeAgents();
         const installed = results.filter((r) => r.outcome === "installed").length;
+        const refreshed = results.filter((r) => r.outcome === "refreshed").length;
         const errored = results.filter((r) => r.outcome === "error");
         if (errored.length > 0) {
           ctx.logger.warn(
@@ -2150,7 +2381,7 @@ var plugin = definePlugin({
           );
         }
         ctx.logger.info(
-          `Compound Engineering agent personas ready \u2014 installed=${installed} target=${targetRoot}`
+          `Compound Engineering agent personas ready \u2014 installed=${installed} refreshed=${refreshed} target=${targetRoot}`
         );
         ctx.emitEvent("compound-engineering:agents-installed", { targetRoot, results });
       } catch (error) {